mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 10:52:06 +01:00
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:
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();
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in new issue
Block a user