refactor(adapter-utils): clean up the HTTP/2 bridge request-body bounds (#12166)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agent adapters use the HTTP/2 bridge to carry requests and responses
> - The bridge has an idle bound and a total-lifetime ceiling for
request bodies
> - The old renewable lifetime bound re-armed with each DATA chunk and
could not act before the idle bound
> - The code also repeated the same bounds and rationale in several
places
> - This pull request removes the unreachable renewable bound, keeps the
one-shot ceiling, and simplifies the shared bounds object
> - The benefit is clearer protection logic with the same default
request-body behavior

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The HTTP/2 bridge request-body reader uses several repeated bound
parameters and comments. One renewable lifetime bound cannot act before
the idle bound under the shipped defaults.

**Subsystem affected**

`packages/adapter-utils/` — HTTP/2 bridge adapter utilities.

**Current behavior**

The idle bound and renewable lifetime bound both re-arm after each DATA
chunk. The renewable bound therefore does not act on its own. The
total-lifetime ceiling also shares timer setup with the renewable bound.

**Proposed behavior**

Remove the renewable lifetime bound. Keep the total-lifetime ceiling as
an independent one-shot timer. Pass one bounds object to the bridge call
sites and keep tests for the idle bound and total-lifetime ceiling.

**Reason and benefit**

The change removes unreachable logic and repeated rationale. It keeps
the independent total-lifetime protection and makes the bound behavior
easier to review.

**Breaking changes**

The change removes two public constant and option names that
repository-wide search found unused outside this implementation. The
shipped default behavior does not change.

## What Changed

- Remove the renewable request-body lifetime bound and its public names.
- Keep the total-lifetime ceiling as a one-shot timer that starts when
the body read starts.
- Replace repeated bound parameters with one `Http2BridgeBodyBounds`
object.
- De-duplicate bound rationale comments.
- Add shared test helpers and update tests for the idle bound and
total-lifetime ceiling.

## Verification

- Run `npx tsc --noEmit -p packages/adapter-utils`.
- Run `npx vitest run
packages/adapter-utils/src/http2-bridge-server.test.ts`.
- Wait for the pull request CI checks.
- Request the Greptile review and confirm a 5/5 verdict with no open
findings.

## Risks

The main risk is an incorrect timer lifetime after the renewable timer
removal. The one-shot ceiling remains independent, and the updated tests
cover its expiry and cleanup paths. The change does not alter the
shipped default bounds.

## Model Used

OpenAI Codex based on GPT-5. Exact runtime model version is GPT-5. The
work used tool calls and code execution for repository inspection and
GitHub operations.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Nicky LeachandPaperclip authored and GitHub committed 2026-08-25 08:09:52 -07:00
1 parent 445547c989
commit 02a984068c
2 files changed
+162 -241

No files matched your search

@@ -76,7 +76,6 @@ interface TestPairOptions {
pingIntervalMs?: number;
pingStallMs?: number;
requestBodyTimeoutMs?: number;
requestBodyMaxLifetimeMs?: number;
requestBodyLifetimeCeilingMs?: number;
closeGraceMs?: number;
onGoaway?: (record: Http2BridgeGoawayRecord) => void;
@@ -102,7 +101,6 @@ function bindTestServer(options: TestPairOptions = {}) {
pingIntervalMs: options.pingIntervalMs,
pingStallMs: options.pingStallMs,
requestBodyTimeoutMs: options.requestBodyTimeoutMs,
requestBodyMaxLifetimeMs: options.requestBodyMaxLifetimeMs,
requestBodyLifetimeCeilingMs: options.requestBodyLifetimeCeilingMs,
closeGraceMs: options.closeGraceMs,
onGoaway: options.onGoaway,
@@ -133,6 +131,45 @@ function connectRawClient(clientSide: Duplex): http2.ClientHttp2Session {
return http2.connect("http://bridge.internal", { createConnection: () => clientSide });
}
/** Track whether `forwardRequest` ran, so a test can prove a denied or
* destroyed stream never reached it. Call `markCalled()` from inside
* `forwardRequest`, then assert on `.called`. */
function createForwarderCallTracker(): { called: boolean; markCalled: () => void } {
const tracker = {
called: false,
markCalled(): void {
tracker.called = true;
},
};
return tracker;
}
/** Send one more request over `rawClient` and wait for it to complete, so a
* test can prove the session survived a prior faulted, stalled, or denied
* stream. */
async function expectSessionStillServesARequest(
rawClient: http2.ClientHttp2Session,
request: { method: string; path: string; token: string },
): Promise<{ status: number; body: string }> {
return new Promise((resolve, reject) => {
const req = rawClient.request({
":method": request.method,
":path": request.path,
authorization: `Bearer ${request.token}`,
});
let status = 0;
let body = "";
req.setEncoding("utf8");
req.on("response", (headers) => {
status = Number(headers[":status"]) || 0;
});
req.on("data", (chunk) => (body += chunk));
req.on("end", () => resolve({ status, body }));
req.on("error", reject);
req.end();
});
}
describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
it("test_one_session_over_a_fake_channel_forwards_a_request", async () => {
const { handle, gateway } = createTestPair();
@@ -296,22 +333,10 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
await abortedOutcome;
// The session survives: a second request completes normally.
const survivingResponse = await new Promise<{ status: number; body: string }>((resolve, reject) => {
const req = rawClient.request({
":method": "GET",
":path": "/api/companies/co1",
authorization: `Bearer ${bridgeToken}`,
});
let status = 0;
let body = "";
req.on("response", (headers) => {
status = Number(headers[":status"]) || 0;
});
req.setEncoding("utf8");
req.on("data", (chunk) => (body += chunk));
req.on("end", () => resolve({ status, body }));
req.on("error", reject);
req.end();
const survivingResponse = await expectSessionStillServesARequest(rawClient, {
method: "GET",
path: "/api/companies/co1",
token: bridgeToken,
});
expect(survivingResponse.status).toBe(200);
expect(JSON.parse(survivingResponse.body)).toEqual({ path: "/api/companies/co1" });
@@ -322,11 +347,11 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
});
it("test_a_stalled_request_body_settles_instead_of_hanging_forever", async () => {
let forwarderCalled = false;
const forwarderTracker = createForwarderCallTracker();
const { handle, bridgeToken, clientSide } = bindTestServer({
requestBodyTimeoutMs: 30,
forwardRequest: async () => {
forwarderCalled = true;
forwarderTracker.markCalled();
return { status: 200 };
},
});
@@ -347,24 +372,14 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
req.write("partial-body");
});
expect(Date.now() - startMs).toBeLessThan(5_000);
expect(forwarderCalled).toBe(false);
expect(forwarderTracker.called).toBe(false);
// The session survives the timed-out stream: a second, complete request
// still succeeds.
const survivingResponse = await new Promise<{ status: number }>((resolve, reject) => {
const req = rawClient.request({
":method": "POST",
":path": "/api/issues/abc/comments",
authorization: `Bearer ${bridgeToken}`,
});
let status = 0;
req.on("response", (headers) => {
status = Number(headers[":status"]) || 0;
});
req.on("data", () => undefined);
req.on("end", () => resolve({ status }));
req.on("error", reject);
req.end();
const survivingResponse = await expectSessionStillServesARequest(rawClient, {
method: "POST",
path: "/api/issues/abc/comments",
token: bridgeToken,
});
expect(survivingResponse.status).toBe(200);
} finally {
@@ -422,30 +437,28 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
}
});
it("test_progress_renews_the_lifetime_bound_but_the_hard_ceiling_still_stops_it", async () => {
it("test_a_slow_trickle_that_never_ends_stops_at_the_one_shot_ceiling", async () => {
// The idle bound is generous, so a chunk every 40ms never lets it
// expire. The lifetime bound (50ms) is short, but each chunk renews it,
// so the read survives past 50ms — proving a slow peer that keeps
// making real progress does not lose the stream early. The hard ceiling
// (150ms) never renews, so the read still ends once the read's total
// age passes it, no matter how the peer paces its chunks. This is the
// expire. The ceiling (150ms) arms once, when the read starts, and
// never renews on a chunk: this proves a peer that keeps every chunk
// gap under the idle bound, but never finishes the body, still loses
// the stream once the read's total age passes the ceiling. This is the
// failure mode an authenticated sandbox could otherwise use to hold one
// of the concurrent-stream slots open indefinitely: keep sending just
// enough to renew the lifetime bound, and never finish the body.
// enough to dodge the idle bound, and never finish the body.
//
// Every write below lands well before the current lifetime deadline,
// and the test makes no further call on the stream after the last one:
// nothing races the server's own reset of it once the ceiling passes,
// so this proves the bound from the server's own, deterministic effect
// (the forward handler never runs) instead of from a raw client-stream
// event whose timing Node does not guarantee here.
let forwarderCalled = false;
// Every write below lands well before the ceiling, and the test makes
// no further call on the stream after the last one: nothing races the
// server's own reset of it once the ceiling passes, so this proves the
// bound from the server's own, deterministic effect (the forward
// handler never runs) instead of from a raw client-stream event whose
// timing Node does not guarantee here.
const forwarderTracker = createForwarderCallTracker();
const { handle, bridgeToken, clientSide } = bindTestServer({
requestBodyTimeoutMs: 5_000,
requestBodyMaxLifetimeMs: 50,
requestBodyLifetimeCeilingMs: 150,
forwardRequest: async () => {
forwarderCalled = true;
forwarderTracker.markCalled();
return { status: 200 };
},
});
@@ -457,35 +470,24 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
authorization: `Bearer ${bridgeToken}`,
});
req.on("error", () => undefined);
// Four chunks, 40ms apart. The total send time, about 120ms, already
// passes the 50ms lifetime bound — proving renewal keeps the read
// alive past it — but stays under the 150ms hard ceiling. The body
// never ends: this request never calls `.end()`.
// Four chunks, 40ms apart, well inside the idle bound. The total send
// time, about 160ms, passes the 150ms ceiling. The body never ends:
// this request never calls `.end()`.
for (let chunkIndex = 0; chunkIndex < 4; chunkIndex += 1) {
req.write("chunk");
await new Promise((resolve) => setTimeout(resolve, 40));
}
// Wait past the hard ceiling with no further write, so the server has
// time to destroy the stalled stream on its own.
// Wait past the ceiling with no further write, so the server has time
// to destroy the stalled stream on its own.
await new Promise((resolve) => setTimeout(resolve, 150));
expect(forwarderCalled).toBe(false);
expect(forwarderTracker.called).toBe(false);
// The session survives the ended stream: a second, complete request
// The session survives the stopped stream: a second, complete request
// still succeeds.
const survivingResponse = await new Promise<{ status: number }>((resolve, reject) => {
const survivingReq = rawClient.request({
":method": "POST",
":path": "/api/issues/abc/comments",
authorization: `Bearer ${bridgeToken}`,
});
let status = 0;
survivingReq.on("response", (headers) => {
status = Number(headers[":status"]) || 0;
});
survivingReq.on("data", () => undefined);
survivingReq.on("end", () => resolve({ status }));
survivingReq.on("error", reject);
survivingReq.end();
const survivingResponse = await expectSessionStillServesARequest(rawClient, {
method: "POST",
path: "/api/issues/abc/comments",
token: bridgeToken,
});
expect(survivingResponse.status).toBe(200);
} finally {
@@ -495,11 +497,11 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
});
it("test_a_request_body_within_the_lifetime_bound_still_completes", async () => {
// A generous lifetime bound must not interfere with an ordinary request
// that finishes well inside it.
// A generous ceiling must not interfere with an ordinary request that
// finishes well inside it.
const { handle, bridgeToken, clientSide } = bindTestServer({
requestBodyTimeoutMs: 5_000,
requestBodyMaxLifetimeMs: 5_000,
requestBodyLifetimeCeilingMs: 5_000,
forwardRequest: async (request) => ({
status: 200,
body: JSON.stringify({ bodyLength: request.body.byteLength }),
@@ -533,19 +535,16 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
}
});
it("test_a_slow_but_progressing_upload_completes_past_the_base_lifetime_bound", async () => {
// The base lifetime bound (50ms) is short, but every chunk below carries
// real progress and renews it, and the hard ceiling (5s) is generous.
// The total send time, about 200ms, passes the 50ms base bound several
// times over, so this proves a slow but genuinely progressing upload now
// completes instead of losing its stream mid-upload.
let forwarderCalled = false;
it("test_a_slow_but_progressing_upload_completes_within_the_ceiling", async () => {
// The idle bound and the ceiling are both generous, so a slow but
// genuinely progressing upload completes normally, instead of losing
// its stream mid-upload.
const forwarderTracker = createForwarderCallTracker();
const { handle, bridgeToken, clientSide } = bindTestServer({
requestBodyTimeoutMs: 5_000,
requestBodyMaxLifetimeMs: 50,
requestBodyLifetimeCeilingMs: 5_000,
forwardRequest: async (request) => {
forwarderCalled = true;
forwarderTracker.markCalled();
return { status: 200, body: JSON.stringify({ bodyLength: request.body.byteLength }) };
},
});
@@ -576,7 +575,7 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
req.end();
})();
});
expect(forwarderCalled).toBe(true);
expect(forwarderTracker.called).toBe(true);
expect(response.status).toBe(200);
expect(JSON.parse(response.body)).toEqual({ bodyLength: "chunk".length * 6 });
} finally {
@@ -740,10 +739,10 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
});
it("test_a_stream_without_the_bridge_token_never_reaches_the_forwarder", async () => {
let forwarderCalled = false;
const forwarderTracker = createForwarderCallTracker();
const { handle, clientSide } = bindTestServer({
forwardRequest: async (request) => {
forwarderCalled = true;
forwarderTracker.markCalled();
return { status: 200, body: JSON.stringify({ path: request.pathname }) };
},
});
@@ -764,7 +763,7 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
req.end();
});
expect(response.status).toBe(401);
expect(forwarderCalled).toBe(false);
expect(forwarderTracker.called).toBe(false);
} finally {
rawClient.close();
await handle.close();
@@ -778,11 +777,11 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
// authenticated request gets — otherwise, up to
// `HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS` denied streams could each retain
// a slot forever and block every legitimate callback.
let forwarderCalled = false;
const forwarderTracker = createForwarderCallTracker();
const { handle, clientSide } = bindTestServer({
requestBodyTimeoutMs: 30,
forwardRequest: async () => {
forwarderCalled = true;
forwarderTracker.markCalled();
return { status: 200 };
},
});
@@ -808,24 +807,14 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
});
await closed;
expect(Date.now() - startMs).toBeLessThan(5_000);
expect(forwarderCalled).toBe(false);
expect(forwarderTracker.called).toBe(false);
// The session survives the freed stream: a second, complete request
// still succeeds, proving the session itself stayed open and healthy.
const survivingResponse = await new Promise<{ status: number }>((resolve, reject) => {
const survivingReq = rawClient.request({
":method": "GET",
":path": "/api/agents/me",
authorization: `Bearer ${BRIDGE_TOKEN}`,
});
let status = 0;
survivingReq.on("response", (headers) => {
status = Number(headers[":status"]) || 0;
});
survivingReq.on("data", () => undefined);
survivingReq.on("end", () => resolve({ status }));
survivingReq.on("error", reject);
survivingReq.end();
const survivingResponse = await expectSessionStillServesARequest(rawClient, {
method: "GET",
path: "/api/agents/me",
token: BRIDGE_TOKEN,
});
expect(survivingResponse.status).toBe(200);
} finally {
@@ -835,10 +824,10 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
});
it("rejects a route the allowlist does not carry, before the forwarder runs", async () => {
let forwarderCalled = false;
const forwarderTracker = createForwarderCallTracker();
const { gateway, handle } = createTestPair({
forwardRequest: async () => {
forwarderCalled = true;
forwarderTracker.markCalled();
return { status: 200 };
},
});
@@ -852,7 +841,7 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
receivedToken: BRIDGE_TOKEN,
});
expect(response.status).toBe(403);
expect(forwarderCalled).toBe(false);
expect(forwarderTracker.called).toBe(false);
} finally {
await gateway.close();
await handle.close();
@@ -860,10 +849,10 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
});
it("the sandbox gateway keeps its own token check before it opens a stream", async () => {
let forwarderCalled = false;
const forwarderTracker = createForwarderCallTracker();
const { gateway, handle } = createTestPair({
forwardRequest: async () => {
forwarderCalled = true;
forwarderTracker.markCalled();
return { status: 200 };
},
});
@@ -878,7 +867,7 @@ describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
receivedToken: "wrong-token",
}),
).rejects.toThrow(/invalid bridge token/i);
expect(forwarderCalled).toBe(false);
expect(forwarderTracker.called).toBe(false);
} finally {
await gateway.close();
await handle.close();
+61 -129
View File
@@ -421,31 +421,18 @@ export const DEFAULT_HTTP2_BRIDGE_PING_STALL_MS = 20_000;
* this bound, so a slow peer that keeps making real progress completes; only
* a peer that stops sending trips it. */
export const DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_TIMEOUT_MS = 30_000;
/** The default lifetime bound on a request body read, measured from the
* start of the read or from the most recent chunk that carried real
* progress, whichever is later. This bound is independent of
* {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_TIMEOUT_MS}: the idle bound
* resets on every chunk to catch a peer that stops sending; this bound
* renews on every chunk too, but only up to the hard ceiling below, so it
* catches a peer that never stops sending but also never finishes. See
* {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_LIFETIME_CEILING_MS} for the
* bound that keeps this renewal from running forever. */
export const DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_MAX_LIFETIME_MS = 120_000;
/** The default hard ceiling on a request body read's total lifetime: an
* absolute bound armed once, at the start of the read, and never pushed out
* past this point no matter how much progress a later chunk reports. A peer
* cannot use a steady trickle of small chunks to keep renewing
* {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_MAX_LIFETIME_MS} and hold a
* {@link HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS} stream slot open forever,
* because this ceiling still ends the read once the read's total age passes
* it. Set well above {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_MAX_LIFETIME_MS}
* so a legitimate upload that makes real but slow progress — a chunk every
* few seconds, well inside the renewable bound above — still has room to
* finish, while a peer that never finishes is still bounded to this ceiling
* instead of running forever. This is an intentional design limit, not a
* defect and not open for removal without a replacement bound. */
export const DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_LIFETIME_CEILING_MS =
DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_MAX_LIFETIME_MS * 4;
* absolute bound armed once, at the start of the read, and never renewed by
* later progress. This bound is independent of
* {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_TIMEOUT_MS}: the idle bound
* resets on every chunk to catch a peer that stops sending; this ceiling
* catches a peer that never stops sending but also never finishes, so a
* peer cannot use a steady trickle of small chunks to hold a
* {@link HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS} stream slot open forever. Set
* well above {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_TIMEOUT_MS} so a
* legitimate upload that makes real but slow progress — a chunk every few
* seconds, well inside the idle bound — still has room to finish. */
export const DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_LIFETIME_CEILING_MS = 480_000;
/** The default bound {@link Http2BridgeServerHandle.close} waits for an
* active session to close on its own before it force-destroys the session. A
* session that carries a stalled stream would otherwise hold `close()` open
@@ -558,16 +545,8 @@ export interface CreateHttp2BridgeServerOptions {
* received chunks. The default is
* {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_TIMEOUT_MS}. */
requestBodyTimeoutMs?: number;
/** The lifetime bound a request body read gets, renewed on every chunk
* that carries real progress, up to {@link requestBodyLifetimeCeilingMs}.
* See {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_MAX_LIFETIME_MS} for why the
* server enforces it. The default is
* {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_MAX_LIFETIME_MS}. */
requestBodyMaxLifetimeMs?: number;
/** The hard ceiling on a request body read's total lifetime, armed once
* and never pushed out by progress. This bound caps worst-case
* stream-slot occupancy even for a peer that keeps renewing
* {@link requestBodyMaxLifetimeMs} with a steady trickle of chunks. See
* and never renewed by progress. See
* {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_LIFETIME_CEILING_MS} for the
* default and the reasoning behind it. */
requestBodyLifetimeCeilingMs?: number;
@@ -634,29 +613,22 @@ function toOutboundHeaderRecord(headers: http2.IncomingHttpHeaders): Record<stri
return out;
}
/** The size and time bounds a request body read enforces. */
export interface Http2BridgeBodyBounds {
/** The maximum request body size, in bytes. */
maxBodyBytes: number;
/** The idle bound: see {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_TIMEOUT_MS}. */
idleTimeoutMs: number;
/** The lifetime ceiling: see {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_LIFETIME_CEILING_MS}. */
lifetimeCeilingMs: number;
}
/**
* Read one request body, bounded on size and on two independent time
* bounds.
*
* The idle bound resets on each received chunk, so a slow peer that keeps
* making real progress completes, while a peer that stops sending
* mid-stream — the same failure a stalled network path or a hung sandbox
* process produces — still trips it.
*
* The lifetime bound also renews on each received chunk, by the same
* amount, so a slow peer that keeps sending real progress gets more time
* instead of losing the stream mid-upload. That renewal never pushes the
* deadline past `startedAt + lifetimeCeilingMs`: the hard ceiling arms once,
* when the read starts, and holds no matter how much progress a later chunk
* reports. This is an intentional design limit, not a defect, and it is not
* open for removal or relaxation without a replacement bound. It exists to
* cap the worst-case time one read can occupy a
* {@link HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS} stream slot — a cap the idle
* bound cannot provide alone, because a peer that keeps every chunk gap
* under the idle bound never trips it, no matter how long the read runs. A
* peer cannot use a steady trickle of small chunks to hold the slot forever,
* because the ceiling still ends the read once the read's total age passes
* it, regardless of how the peer paces its chunks.
* bounds: an idle bound and a total-lifetime ceiling. See
* {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_TIMEOUT_MS} and
* {@link DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_LIFETIME_CEILING_MS} for why the
* server enforces each one.
*
* The `close` listener is the settle-of-last-resort: it fires whenever the
* stream ends for any reason at all — a normal end, an error, a timeout- or
@@ -665,23 +637,19 @@ function toOutboundHeaderRecord(headers: http2.IncomingHttpHeaders): Record<stri
*/
function readHttp2StreamBody(
stream: http2.ServerHttp2Stream,
maxBodyBytes: number,
idleTimeoutMs: number,
maxLifetimeMs: number,
lifetimeCeilingMs: number,
bounds: Http2BridgeBodyBounds,
): Promise<Buffer> {
return new Promise((resolve, reject) => {
const chunks: Buffer[] = [];
let totalBytes = 0;
let settled = false;
let idleTimer: ReturnType<typeof setTimeout>;
let lifetimeTimer: ReturnType<typeof setTimeout>;
const hardDeadline = Date.now() + lifetimeCeilingMs;
let lifetimeCeilingTimer: ReturnType<typeof setTimeout>;
const settle = (run: () => void) => {
if (settled) return;
settled = true;
clearTimeout(idleTimer);
clearTimeout(lifetimeTimer);
clearTimeout(lifetimeCeilingTimer);
run();
};
const armIdleTimer = () => {
@@ -689,38 +657,29 @@ function readHttp2StreamBody(
idleTimer = setTimeout(() => {
settle(() => reject(new Error("Bridge request body stalled before it completed.")));
stream.destroy();
}, idleTimeoutMs);
}, bounds.idleTimeoutMs);
idleTimer.unref?.();
};
// Renews on every chunk that carries real progress, but the delay never
// exceeds the time left before the hard ceiling armed below: see the
// function's own doc comment for why the ceiling must stay independent
// of progress.
const armLifetimeTimer = () => {
clearTimeout(lifetimeTimer);
const delayMs = Math.max(0, Math.min(maxLifetimeMs, hardDeadline - Date.now()));
lifetimeTimer = setTimeout(() => {
settle(() => reject(new Error("Bridge request body exceeded the maximum lifetime bound.")));
stream.destroy();
}, delayMs);
lifetimeTimer.unref?.();
};
armLifetimeTimer();
// Arms one time, when the read starts, and never rearms on a chunk: see
// DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_LIFETIME_CEILING_MS for why the
// ceiling must stay independent of progress.
lifetimeCeilingTimer = setTimeout(() => {
settle(() => reject(new Error("Bridge request body passed the total lifetime ceiling.")));
stream.destroy();
}, bounds.lifetimeCeilingMs);
lifetimeCeilingTimer.unref?.();
armIdleTimer();
stream.on("data", (chunk: Buffer) => {
totalBytes += chunk.byteLength;
if (totalBytes > maxBodyBytes) {
if (totalBytes > bounds.maxBodyBytes) {
settle(() => reject(new Error("Bridge request body exceeded the configured size limit.")));
stream.destroy();
return;
}
chunks.push(chunk);
// The chunk is real progress, so the peer is not stalled: reset the
// idle bound and renew the lifetime bound, instead of letting either
// expire under a slow but active upload. The lifetime renewal above is
// still capped by the hard ceiling.
// idle bound. The lifetime ceiling timer above does not reset here.
armIdleTimer();
armLifetimeTimer();
});
stream.once("end", () => settle(() => resolve(Buffer.concat(chunks))));
stream.once("error", (error) => settle(() => reject(error instanceof Error ? error : new Error(String(error)))));
@@ -743,26 +702,23 @@ function respondJson(stream: http2.ServerHttp2Stream, status: number, body: unkn
/**
* Answer a denied stream, then consume and discard its request body under
* the same idle and total lifetime bounds an authenticated request gets.
* A denied request's body content never reaches the forward handler, but
* the inbound half of the stream still needs a bound: without one, a peer
* that leaves the body unfinished keeps the stream open, holding one of the
* {@link HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS} slots for as long as it
* chooses. Nothing awaits the discard; the caller has already answered the
* request and moves on to the next stream.
* the same bounds ({@link Http2BridgeBodyBounds}) an authenticated request
* gets. A denied request's body content never reaches the forward handler,
* but the inbound half of the stream still needs a bound: without one, a
* peer that leaves the body unfinished keeps the stream open, holding one
* of the {@link HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS} slots for as long as
* it chooses. Nothing awaits the discard; the caller has already answered
* the request and moves on to the next stream.
*/
function denyRequest(
stream: http2.ServerHttp2Stream,
status: number,
body: unknown,
maxBodyBytes: number,
idleTimeoutMs: number,
maxLifetimeMs: number,
lifetimeCeilingMs: number,
bounds: Http2BridgeBodyBounds,
): void {
respondJson(stream, status, body);
if (stream.destroyed || stream.closed) return;
readHttp2StreamBody(stream, maxBodyBytes, idleTimeoutMs, maxLifetimeMs, lifetimeCeilingMs).catch(() => {
readHttp2StreamBody(stream, bounds).catch(() => {
// The idle or lifetime bound above already destroyed the stream, or the
// peer reset it first. Either way the slot is free; the discarded body
// content is irrelevant to a denial.
@@ -781,14 +737,20 @@ export function createHttp2BridgeServer(options: CreateHttp2BridgeServerOptions)
const pingIntervalMs = options.pingIntervalMs ?? DEFAULT_HTTP2_BRIDGE_PING_INTERVAL_MS;
const pingStallMs = options.pingStallMs ?? DEFAULT_HTTP2_BRIDGE_PING_STALL_MS;
const requestBodyTimeoutMs = options.requestBodyTimeoutMs ?? DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_TIMEOUT_MS;
const requestBodyMaxLifetimeMs =
options.requestBodyMaxLifetimeMs ?? DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_MAX_LIFETIME_MS;
const requestBodyLifetimeCeilingMs =
options.requestBodyLifetimeCeilingMs ?? DEFAULT_HTTP2_BRIDGE_REQUEST_BODY_LIFETIME_CEILING_MS;
const closeGraceMs = options.closeGraceMs ?? DEFAULT_HTTP2_BRIDGE_CLOSE_GRACE_MS;
const maxBufferedReadBytes = options.maxBufferedReadBytes ?? DEFAULT_HTTP2_BRIDGE_MAX_BUFFERED_READ_BYTES;
const readBackpressureStallMs =
options.readBackpressureStallMs ?? DEFAULT_HTTP2_BRIDGE_READ_BACKPRESSURE_STALL_MS;
// Built one time and passed to every readHttp2StreamBody() and
// denyRequest() call below, so every stream on this server enforces the
// same bounds.
const bodyBounds: Http2BridgeBodyBounds = {
maxBodyBytes,
idleTimeoutMs: requestBodyTimeoutMs,
lifetimeCeilingMs: requestBodyLifetimeCeilingMs,
};
const server = http2.createServer(HTTP2_BRIDGE_SERVER_OPTIONS);
const activeSessions = new Set<http2.ServerHttp2Session>();
@@ -801,15 +763,7 @@ export function createHttp2BridgeServer(options: CreateHttp2BridgeServerOptions)
// before route processing and before header processing. This host check
// is independent of the gateway's own token check on the sandbox side.
if (!compareBridgeTokensConstantTime(options.bridgeToken, readBridgeTokenHeader(headers))) {
denyRequest(
stream,
401,
{ error: "Invalid bridge token." },
maxBodyBytes,
requestBodyTimeoutMs,
requestBodyMaxLifetimeMs,
requestBodyLifetimeCeilingMs,
);
denyRequest(stream, 401, { error: "Invalid bridge token." }, bodyBounds);
return;
}
@@ -817,15 +771,7 @@ export function createHttp2BridgeServer(options: CreateHttp2BridgeServerOptions)
// allowlist and the forward request below read this one result.
const parsedPath = parseCanonicalBridgeRequestPath(headers);
if (!parsedPath.ok) {
denyRequest(
stream,
400,
{ error: `Invalid request path: ${parsedPath.reason}` },
maxBodyBytes,
requestBodyTimeoutMs,
requestBodyMaxLifetimeMs,
requestBodyLifetimeCeilingMs,
);
denyRequest(stream, 400, { error: `Invalid request path: ${parsedPath.reason}` }, bodyBounds);
return;
}
const method = normalizeStreamMethod(headers[":method"]);
@@ -835,15 +781,7 @@ export function createHttp2BridgeServer(options: CreateHttp2BridgeServerOptions)
routes,
);
if (denialReason) {
denyRequest(
stream,
403,
{ error: denialReason },
maxBodyBytes,
requestBodyTimeoutMs,
requestBodyMaxLifetimeMs,
requestBodyLifetimeCeilingMs,
);
denyRequest(stream, 403, { error: denialReason }, bodyBounds);
return;
}
@@ -854,13 +792,7 @@ export function createHttp2BridgeServer(options: CreateHttp2BridgeServerOptions)
let body: Buffer;
try {
body = await readHttp2StreamBody(
stream,
maxBodyBytes,
requestBodyTimeoutMs,
requestBodyMaxLifetimeMs,
requestBodyLifetimeCeilingMs,
);
body = await readHttp2StreamBody(stream, bodyBounds);
} catch (error) {
respondJson(stream, 413, { error: error instanceof Error ? error.message : String(error) });
return;