echelongraph-mcp 2.6.3 → 2.6.6

package/dist/http.js

@@ -13,6 +13,17 @@
 //   GET /health   liveness. Not /healthz: Cloud Run's front end reserves paths ending in "z"
 //                 and answers them itself, so a /healthz would never reach this process.
 //
+// HTTP/1.1 by default; HTTP/2 cleartext (h2c, prior knowledge) ONLY when MCP_H2C=1 (#2775). Cloud
+// Run tells a container that its client went away only over HTTP/2 or a WebSocket ("When you use
+// HTTP/1.1 on Cloud Run, client disconnect events are not propagated to the Cloud Run container",
+// https://docs.cloud.google.com/run/docs/troubleshooting): over HTTP/1.1 its front end reads the
+// whole answer itself, so an abandoned call ran to its end, holding its large-body slot. With
+// `--use-http2` Cloud Run sends the container h2c and nothing else, and a client that goes resets
+// its stream, which this server acts on at once (serveMcp). But on a canary of 2026-10-05 that reset
+// came only when the answer was written, 15 and 34 s in, not when the client went:
+// mcp_client_gone (after_ms, answer_started) is how production shows which. The flag and
+// MCP_H2C=1 go together (deploy-all.sh mcp-remote): either one alone answers no request at all.
+//
 // No auth: the endpoint serves only public data (MCP makes authorization optional), and the
 // server's instructions say what it is. The edge rules — Origin policy, per-client limit, body
 // cap, what is logged — are in httpPolicy.ts, each with its reasoning.
@@ -22,9 +33,11 @@
 // waf/mcpforward.go, #2212). MCP_REQUIRE_FORWARD_TOKEN=1 (set by deploy-all.sh) makes a missing
 // token fatal at start-up, because without it every remote user would share one API budget.
 import http from "node:http";
+import http2 from "node:http2";
+import v8 from "node:v8";
 import { createMcpHandler } from "@modelcontextprotocol/server";
-import { forwardToken, markHttpEntrypoint, SYNTHETIC_UA_FAMILY, withClient } from "./runtime.js";
-import { BODY_TOO_LARGE_CODE, BUSY_CODE, DEFAULT_LARGE_BODY_SLOTS, DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_SBOM_BODY_BYTES, DEFAULT_RATE_LIMIT_PER_MIN, LARGE_BODY_TARGETS_TEXT, Slots, FixedWindowLimiter, ORIGIN_REFUSED_CODE, RATE_LIMITED_CODE, bodyFacts, originVerdict, resolveClient, revisionLabel, rpcError, isLargeBodyTarget, largeBodyAdmissible, uaFamily, } from "./httpPolicy.js";
+import { forwardToken, markHttpEntrypoint, requestSettled, SYNTHETIC_UA_FAMILY, withClient } from "./runtime.js";
+import { Admission, BODY_TOO_LARGE_CODE, BUSY_CODE, DEFAULT_ADMISSION_WAIT_MS, DEFAULT_LARGE_BODY_SLOTS, DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_IN_FLIGHT, DEFAULT_MAX_SBOM_BODY_BYTES, DEFAULT_MAX_WAITING, DEFAULT_RATE_LIMIT_PER_MIN, LARGE_BODY_TARGETS_TEXT, Slots, FixedWindowLimiter, ORIGIN_REFUSED_CODE, RATE_LIMITED_CODE, bodyFacts, originVerdict, resolveClient, revisionLabel, rpcError, isLargeBodyTarget, isListenStream, largeBodyAdmissible, uaFamily, } from "./httpPolicy.js";
 // Must run before index.ts is evaluated: it is how index.ts knows not to start stdio.
 markHttpEntrypoint();
 const { createServer, NAME, VERSION, SHOWN_BASE, TIMEOUT_MS } = await import("./index.js");
@@ -41,8 +54,16 @@ const RATE_LIMIT_PER_MIN = positiveInt(process.env.MCP_RATE_LIMIT_PER_MIN, DEFAU
 const MAX_BODY_BYTES = positiveInt(process.env.MCP_MAX_BODY_BYTES, DEFAULT_MAX_BODY_BYTES);
 const MAX_SBOM_BODY_BYTES = Math.max(MAX_BODY_BYTES, positiveInt(process.env.MCP_MAX_SBOM_BODY_BYTES, DEFAULT_MAX_SBOM_BODY_BYTES));
 const LARGE_BODY_SLOTS = positiveInt(process.env.MCP_LARGE_BODY_SLOTS, DEFAULT_LARGE_BODY_SLOTS);
-// A large body's wait for a slot is not queued: the client is told to come back.
+// The requests served at once, and how long the next may wait (#2773): httpPolicy.ts "Requests
+// in flight per instance".
+const MAX_IN_FLIGHT = positiveInt(process.env.MCP_MAX_IN_FLIGHT, DEFAULT_MAX_IN_FLIGHT);
+const ADMISSION_WAIT_MS = positiveInt(process.env.MCP_ADMISSION_WAIT_MS, DEFAULT_ADMISSION_WAIT_MS);
+// A large body's wait for a slot is not queued: the client is told to come back. Nor is a
+// request that waited ADMISSION_WAIT_MS for admission.
 const BUSY_RETRY_AFTER_SEC = 5;
+// #2775: serve h2c instead of HTTP/1.1 (see the top of this file). Exactly "1": anything else is
+// HTTP/1.1, the default for a local run and for every test that does not ask.
+const H2C = process.env.MCP_H2C === "1";
 const MCP_PATH = "/mcp";
 const HEALTH_PATH = "/health";
 // One JSON object per line on stdout: Cloud Logging reads `severity` and `message`.
@@ -67,6 +88,7 @@ const handler = createMcpHandler(createServer, {
 });
 const limiter = new FixedWindowLimiter(RATE_LIMIT_PER_MIN);
 const largeBodies = new Slots(LARGE_BODY_SLOTS);
+const admission = new Admission(MAX_IN_FLIGHT, DEFAULT_MAX_WAITING);
 // CORS for a browser client on an https Origin (the Origin policy has already admitted it).
 // A wildcard is safe here because nothing is credentialed: no cookies, no auth.
 const CORS_HEADERS = {
@@ -80,8 +102,17 @@ const PREFLIGHT_HEADERS = {
     "Access-Control-Max-Age": "600",
 };
 const HOP_BY_HOP = new Set(["host", "connection", "content-length", "transfer-encoding", "keep-alive", "upgrade", "expect"]);
+// HTTP/2 has no connection-specific headers (RFC 9113 8.2.2): Node drops them from an h2 answer
+// with a warning, so they are never set on one. A refusal's "Connection: close" (the rest of the
+// body is discarded unread) is the stream's own end there.
+const CONNECTION_SPECIFIC = new Set(["connection", "keep-alive", "proxy-connection", "transfer-encoding", "upgrade"]);
+function forProtocol(res, headers) {
+    if (!(res instanceof http2.Http2ServerResponse))
+        return headers;
+    return Object.fromEntries(Object.entries(headers).filter(([k]) => !CONNECTION_SPECIFIC.has(k.toLowerCase())));
+}
 function send(res, status, body, headers = {}) {
-    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers });
+    res.writeHead(status, forProtocol(res, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers }));
     res.end(body);
 }
 function readBody(req) {
@@ -126,8 +157,14 @@ function readBody(req) {
             chunks.push(chunk);
         });
         req.on("end", () => {
+            if (done)
+                return;
+            done = true;
+            resolve({ body: Buffer.concat(chunks), slot });
+        });
+        req.on("close", () => {
             if (!done)
-                resolve({ body: Buffer.concat(chunks), slot });
+                stop("gone");
         });
         req.on("error", (e) => {
             if (done)
@@ -169,73 +206,148 @@ async function serveMcp(req, res, pathname) {
         log("WARNING", "mcp_rate_limited", { client: client.key, limit: RATE_LIMIT_PER_MIN });
         return { status: 429, throttled: true };
     }
-    let body;
-    let facts;
+    // #2775: the client has gone when the response closes before it has finished. That aborts the
+    // request: its wait for admission, the SDK's handling of it (which cancels the tool's call), and
+    // its API calls (runtime.ts requestSignal).
+    // Over h2c the response of a reset stream closes marked finished (node:http2's compatibility
+    // API ends it), so there the stream itself is watched, from the moment the reset arrives:
+    // 'aborted' (a reset before the answer was written, any error code) and a 'close' before this
+    // server ended its answer (a reset with NO_ERROR emits no 'aborted').
+    // mcp_client_gone says WHEN this server learned it: after_ms from the request's start, and
+    // whether its answer had started (answer_started). On 2026-10-05 a canary behind Cloud Run's
+    // --use-http2 logged its aborted calls 499 only when their answers were written, 15 and 34 s
+    // in: this line tells a reset that arrived then from one that arrived early and was not acted on
+    // (the access line's duration_ms is when the call actually stopped).
+    const gone = new AbortController();
+    const t0 = Date.now();
+    const h2stream = res.stream;
+    const clientWent = () => {
+        if (gone.signal.aborted)
+            return;
+        gone.abort();
+        log("INFO", "mcp_client_gone", { after_ms: Date.now() - t0, answer_started: res.headersSent, rst_code: h2stream?.rstCode ?? null });
+    };
+    res.on("close", () => {
+        if (!res.writableFinished || h2stream?.aborted)
+            clientWent();
+    });
+    if (h2stream) {
+        h2stream.once("aborted", clientWent);
+        h2stream.once("close", () => {
+            if (!res.writableEnded)
+                clientWent();
+        });
+    }
+    // The body is read BEFORE the request waits for admission (#2773), so a client that uploads
+    // slowly holds its socket, and a large body its large-body slot, as before admission existed,
+    // never one of the MAX_IN_FLIGHT places every other request needs. What a waiting request holds
+    // is its body: at most MAX_BODY_BYTES, or a large body that holds one of the slots.
     let slot = false;
-    if (method === "POST") {
-        const read = await readBody(req);
-        if (read === "too_large")
-            return tooLarge(res, cors);
-        if (read === "busy") {
-            send(res, 503, rpcError(BUSY_CODE, `Server busy: this instance is already reading its ${LARGE_BODY_SLOTS} large request bodies at once. Retry after ${BUSY_RETRY_AFTER_SEC} s, or pass check_sbom the SBOM's purls.`, { retry_after_seconds: BUSY_RETRY_AFTER_SEC }), { ...cors, "Retry-After": String(BUSY_RETRY_AFTER_SEC), Connection: "close" });
-            log("WARNING", "mcp_large_body_busy", { slots: LARGE_BODY_SLOTS });
-            return { status: 503, refused: "large_body_busy" };
+    try {
+        let body;
+        let facts;
+        if (method === "POST") {
+            let read;
+            try {
+                read = await readBody(req);
+            }
+            catch (e) {
+                // The request stream fails only when its connection does: the client went mid-upload.
+                if (req.destroyed)
+                    return { status: 499, refused: "client_closed", clientClosed: true };
+                throw e;
+            }
+            if (read === "gone")
+                return { status: 499, refused: "client_closed", clientClosed: true };
+            if (read === "too_large")
+                return tooLarge(res, cors);
+            if (read === "busy") {
+                send(res, 503, rpcError(BUSY_CODE, `Server busy: this instance is already reading its ${LARGE_BODY_SLOTS} large request bodies at once. Retry after ${BUSY_RETRY_AFTER_SEC} s, or pass check_sbom the SBOM's purls.`, { retry_after_seconds: BUSY_RETRY_AFTER_SEC }), { ...cors, "Retry-After": String(BUSY_RETRY_AFTER_SEC), Connection: "close" });
+                log("WARNING", "mcp_large_body_busy", { slots: LARGE_BODY_SLOTS });
+                return { status: 503, refused: "large_body_busy" };
+            }
+            body = read.body;
+            slot = read.slot;
+            facts = bodyFacts(body);
+            // Past the general cap, the body itself must be what the headers (if any) said: one of
+            // LARGE_BODY_TARGETS. A 2025-era client sends no Mcp-Method, so this is where its large body
+            // is held to that.
+            if (body.length > MAX_BODY_BYTES && !isLargeBodyTarget(facts))
+                return { ...tooLarge(res, cors), body, facts };
+            // A 2026-era subscriptions/listen is a stream open until its client leaves, carrying only
+            // keepalives here: it takes no place and holds no work, or 64 idle ones would leave every
+            // other request waiting for a 503 (#2773; httpPolicy.ts isListenStream says what bounds it).
+            const standard = { protocolVersion: header(req, "mcp-protocol-version"), mcpMethod: header(req, "mcp-method"), mcpName: header(req, "mcp-name") };
+            if (isListenStream(facts, body, standard))
+                return { ...(await relay(req, res, pathname, method, cors, client, body, gone.signal)), facts };
         }
-        body = read.body;
-        slot = read.slot;
-        facts = bodyFacts(body);
-        // Past the general cap, the body itself must be what the headers (if any) said: one of
-        // LARGE_BODY_TARGETS. A 2025-era client sends no Mcp-Method, so this is where its large body
-        // is held to that.
-        if (body.length > MAX_BODY_BYTES && !isLargeBodyTarget(facts)) {
-            if (slot)
-                largeBodies.release();
-            return { ...tooLarge(res, cors), body, facts };
+        // #2773: at most MAX_IN_FLIGHT requests are served at once; the next waits here.
+        const waitStart = Date.now();
+        if (!(await admission.acquire(ADMISSION_WAIT_MS, gone.signal))) {
+            const queuedMs = Date.now() - waitStart;
+            if (gone.signal.aborted)
+                return { status: 499, refused: "client_closed", clientClosed: true, body, facts, queuedMs };
+            req.resume();
+            send(res, 503, rpcError(BUSY_CODE, `Server busy: this instance is already serving its ${MAX_IN_FLIGHT} requests at once. Retry after ${BUSY_RETRY_AFTER_SEC} s.`, { retry_after_seconds: BUSY_RETRY_AFTER_SEC }), { ...cors, "Retry-After": String(BUSY_RETRY_AFTER_SEC), Connection: "close" });
+            log("WARNING", "mcp_busy", { max_in_flight: MAX_IN_FLIGHT, waiting: admission.waiting });
+            return { status: 503, refused: "busy", body, facts, queuedMs };
+        }
+        const admitted = { inFlight: admission.inUse, queuedMs: Date.now() - waitStart };
+        // What is still running for this request (runtime.ts holdRequest): its admission and its
+        // large-body slot are held until all of it has settled, not only until the answer is written.
+        const work = new Set();
+        try {
+            return { ...(await relay(req, res, pathname, method, cors, client, body, gone.signal, work)), facts, ...admitted };
+        }
+        finally {
+            // Every tool call stops on `gone` (#2775), so this wait is long only if one does not.
+            await requestSettled(work);
+            admission.release();
         }
-    }
-    try {
-        return { ...(await relay(req, res, pathname, method, cors, client, body)), facts };
     }
     finally {
         if (slot)
             largeBodies.release();
     }
 }
-// Hands one admitted request to the SDK's handler and streams its answer back.
-async function relay(req, res, pathname, method, cors, client, body) {
+// Hands one admitted request (or a listen stream, which is not admitted and passes no `work`) to
+// the SDK's handler and streams its answer back.
+async function relay(req, res, pathname, method, cors, client, body, gone, work) {
     const headers = new Headers();
     for (const [k, v] of Object.entries(req.headers)) {
-        if (v === undefined || HOP_BY_HOP.has(k))
+        // ":method", ":path", ":authority", ":scheme": an h2 request's pseudo-headers, which a Request cannot carry.
+        if (v === undefined || HOP_BY_HOP.has(k) || k.startsWith(":"))
             continue;
         for (const one of Array.isArray(v) ? v : [v])
             headers.append(k, one);
     }
-    const abort = new AbortController();
-    res.on("close", () => abort.abort());
     const request = new Request(`http://localhost${pathname}`, {
         method,
         headers,
         body: body && body.length > 0 ? new Uint8Array(body) : undefined,
-        signal: abort.signal,
+        signal: gone,
     });
     // #2737: the production synthetic names itself by its user-agent family; its API calls then
     // carry the synthetic's fixed token (runtime.ts upstreamUserAgent), so they are never counted
     // as hosted adoption.
     const synthetic = uaFamily(req.headers["user-agent"]) === SYNTHETIC_UA_FAMILY;
-    const response = await withClient(client.forwardAddress, () => handler.fetch(request), { synthetic });
+    const response = await withClient(client.forwardAddress, () => handler.fetch(request), { synthetic, signal: gone, work });
     const out = { ...cors };
     response.headers.forEach((v, k) => {
         out[k] = v;
     });
-    res.writeHead(response.status, out);
+    res.writeHead(response.status, forProtocol(res, out));
     if (response.body) {
         for await (const chunk of response.body)
             res.write(chunk);
     }
     res.end();
-    return { status: response.status, body, clientPublic: client.forwardAddress !== undefined };
+    const clientPublic = client.forwardAddress !== undefined;
+    if (gone.aborted)
+        return { status: 499, body, clientPublic, clientClosed: true };
+    return { status: response.status, body, clientPublic };
 }
-const server = http.createServer((req, res) => {
+function onRequest(req, res) {
     const start = process.hrtime.bigint();
     // The path only: a query string is never read, kept or logged.
     let pathname = "/";
@@ -261,6 +373,9 @@ const server = http.createServer((req, res) => {
             refused: o.refused ?? "",
             ua_family: uaFamily(req.headers["user-agent"]),
             client_public: o.clientPublic === true,
+            client_closed: o.clientClosed === true,
+            in_flight: o.inFlight ?? 0,
+            queued_ms: o.queuedMs ?? 0,
         });
     };
     if (pathname === HEALTH_PATH) {
@@ -283,11 +398,36 @@ const server = http.createServer((req, res) => {
             res.end();
         finish({ status: 500 });
     });
-});
+}
+// #2775: with MCP_H2C=1, node:http2's compatibility API, whose request and response carry the
+// IncomingMessage / ServerResponse members used above. Where they differ the code says so:
+// pseudo-headers (relay), connection-specific headers (forProtocol), a stream reset mid-upload
+// (readBody "gone"). A stream reset after that closes the response unfinished, which aborts
+// `gone` in serveMcp exactly as a closed HTTP/1.1 socket does.
+const server = H2C
+    ? http2.createServer((req, res) => onRequest(req, res))
+    : http.createServer(onRequest);
+// #2773: the heap V8 may grow to, and the memory the container allows (0 when none is known). A
+// heap allowed past the container's memory is collected only when the kernel kills the instance:
+// Dockerfile.http caps it, and this says when a process was started without that cap. It can say
+// so only where Node can read the container's limit (process.constrainedMemory(), from cgroups):
+// where it cannot, memory_limit_mb is null, this never fires, and heap_limit_mb is what to read.
+const MiB = 1024 * 1024;
+const heapLimit = v8.getHeapStatistics().heap_size_limit;
+const memoryLimit = process.constrainedMemory?.() ?? 0;
+const memoryKnown = memoryLimit > 0 && memoryLimit < 2 ** 50;
+if (memoryKnown && heapLimit > memoryLimit * 0.75) {
+    log("WARNING", "mcp_remote_heap_unbounded", {
+        heap_limit_mb: Math.round(heapLimit / MiB),
+        memory_limit_mb: Math.round(memoryLimit / MiB),
+        reason: "V8 may grow its heap past the container's memory, and the kernel then kills the instance with every request on it (#2773): start http.js as Dockerfile.http does",
+    });
+}
 server.listen(PORT, () => {
     const addr = server.address();
     log("INFO", "mcp_remote_listening", {
         port: typeof addr === "object" && addr ? addr.port : PORT,
+        protocol: H2C ? "h2c" : "http/1.1",
         name: NAME,
         version: VERSION,
         api_base: SHOWN_BASE,
@@ -297,6 +437,10 @@ server.listen(PORT, () => {
         max_body_bytes: MAX_BODY_BYTES,
         max_sbom_body_bytes: MAX_SBOM_BODY_BYTES,
         large_body_slots: LARGE_BODY_SLOTS,
+        max_in_flight: MAX_IN_FLIGHT,
+        admission_wait_ms: ADMISSION_WAIT_MS,
+        heap_limit_mb: Math.round(heapLimit / MiB),
+        memory_limit_mb: memoryKnown ? Math.round(memoryLimit / MiB) : null,
     });
 });
 const shutdown = () => {

package/dist/httpPolicy.js

@@ -2,6 +2,7 @@
 // tested on its own: who the client is, which Origins are served, the per-client limit, and the
 // JSON-RPC error bodies the edge answers with.
 import { isIP } from "node:net";
+import { classifyInboundRequest } from "@modelcontextprotocol/server";
 // ── JSON-RPC errors from the edge ──
 //
 // Every refusal at the edge is a JSON-RPC error object, never an HTML page and never a bare
@@ -10,7 +11,7 @@ import { isIP } from "node:net";
 export const ORIGIN_REFUSED_CODE = -32000; // the SDK's own code for an Origin refusal (originValidationResponse)
 export const RATE_LIMITED_CODE = -32029; // implementation-defined server error range (-32000..-32099); "429"
 export const BODY_TOO_LARGE_CODE = -32600; // Invalid Request
-export const BUSY_CODE = -32030; // implementation-defined server error range; "503", no large-body slot free (#2747)
+export const BUSY_CODE = -32030; // implementation-defined server error range; "503": no large-body slot free (#2747), or the instance full (#2773)
 export function rpcError(code, message, data) {
     return JSON.stringify({ jsonrpc: "2.0", id: null, error: { code, message, ...(data ? { data } : {}) } });
 }
@@ -227,9 +228,11 @@ export class FixedWindowLimiter {
 // 2,000-purl ~2 MB body +62 MB; one 5.47 MB body +76 MB; two 5.47 MB bodies at once 209 MB in
 // all, also with V8's old space held to 64 MB: ~59 MB of 256 MiB left for everything else, so
 // not a third. So a body past 64 KiB must hold one of DEFAULT_LARGE_BODY_SLOTS (2) slots per
-// instance for as long as it is read and served; with none free it is answered 503 with
-// Retry-After, never queued. The per-client limit still counts each large request as one
-// request, before its body is read.
+// instance for as long as it is read, waits for a place (below) and is served; with none free it
+// is answered 503 with Retry-After, never queued. The per-client limit still counts each large
+// request as one request, before its body is read. That budget measured the two bodies alone, not
+// the requests served beside them, which were enough to kill the instance (#2773): "Requests in
+// flight per instance" below bounds those and records what each costs.
 export const DEFAULT_MAX_BODY_BYTES = 64 * 1024;
 export const DEFAULT_MAX_SBOM_BODY_BYTES = 6 * 1024 * 1024;
 export const DEFAULT_LARGE_BODY_SLOTS = 2;
@@ -273,6 +276,159 @@ export class Slots {
         return this.used;
     }
 }
+// ── Requests in flight per instance (#2773) ──
+//
+// The slots bound the large bodies, not the requests served beside them. Cloud Run sends one
+// instance up to 250 requests at once (deploy-all.sh SVC_CONCURRENCY) into 256 MiB. Measured
+// 2026-10-04 on dist/http.js, Node 22.22, in a 256 MiB memory cgroup, against a stub API
+// answering in 1.5 s, two 4,999,913-character check_sbom documents in flight plus N tools/call
+// cve_summary at once, 2025-era (answered over SSE, the costlier era): N=100 peaked at 226 MB,
+// N=125 at 259 MB (96%), N=200 and N=250 were OOM-killed; with no document, N=200 peaked at
+// 240 MB and N=250 was OOM-killed.
+//
+// Two bounds hold that load (test/http-memory.test.mjs drives the real server with it; what each
+// case does without each bound is below):
+//   - V8's heap. In that sandbox (a cgroup v1 on a 16 GB host) Node 22 sized V8's heap from the
+//     host's memory, not the cgroup's (heap_size_limit 8,195 MiB in 256 MiB), so V8 left the
+//     garbage of the requests served (~1 MB each) uncollected until the kernel killed the
+//     instance. So the image caps V8's old space at 128 MiB (Dockerfile.http), and V8 collects
+//     first. On Cloud Run this is not verified: an instance that shows Node only its 256 MiB gets
+//     a default heap near the cap already, and then the cap changes little. Its start-up line says
+//     which (heap_limit_mb; memory_limit_mb, null where Node is told no limit).
+//   - The live set. Under the cap, what must fit is what is live at once, and 250 requests at once
+//     do not: with every answer held until all 250 were inside the instance, V8 aborted
+//     ("JavaScript heap out of memory"). So an instance serves at most DEFAULT_MAX_IN_FLIGHT /mcp
+//     requests at once, large ones included (they hold a slot as well), whatever its heap.
+// A request's body is read before it waits for a place, so a client that uploads slowly holds its
+// socket (and a large body its slot), never a place. It then waits, first come first served, up
+// to DEFAULT_ADMISSION_WAIT_MS for one to finish, and is then answered 503 with Retry-After: it
+// waits rather than being refused at once because Cloud Run still routes up to 250 to the
+// instance and counts a waiting request toward scaling out. A waiting request costs its socket and
+// its body: at most 64 KiB, or a large body that holds a slot. At most DEFAULT_MAX_WAITING wait;
+// past that, 503 at once. A request counts until its answer is written AND its work has stopped: a
+// check_sbom call whose client has gone keeps its place until it stops (#2775). /health is never
+// held, and nor is a subscriptions/listen stream (isListenStream below).
+//
+// With both, in that cgroup, the two documents at the API, then 248 cve_summary sent at once:
+//   - the API answering in 1.5 s: all 250 answered 200, 64 served at once and the last waiting
+//     ~9 s (one core here serves about 28 a second, so on a slower one the last of such a burst
+//     wait past DEFAULT_ADMISSION_WAIT_MS and are answered 503), cgroup peak 221-225 MB of 268 MB
+//     (82-84%). Without the heap cap: OOM-killed in three runs of four, the fourth at 248 MB.
+//     Without the admission: V8 aborted, four of four.
+//   - every answer held until all 250 were inside the instance at once: 64 served and answered
+//     200, the other 186 answered 503 after waiting 10 s, peak 201-208 MB (75-77%), and 204-206 MB
+//     without the heap cap. Without the admission: V8 aborted, two of two.
+// What this does not bound is a request whose ANSWER is large: a check_sbom call of 2,000 purls
+// fits a 64 KiB body, and with production-shaped rows (~2.2 KB each) one peaks at +77 MB; beside
+// the two documents, 8 at once peaked at 84%, and 16 at once exhausted the 128 MiB heap. Bounding
+// that needs a weight per call (its purls), not a count of requests.
+export const DEFAULT_MAX_IN_FLIGHT = 64;
+export const DEFAULT_ADMISSION_WAIT_MS = 10_000;
+export const DEFAULT_MAX_WAITING = 250;
+/**
+ * A counting semaphore whose callers may wait, in arrival order, for a bounded time. acquire
+ * resolves true once admitted (the caller then calls release() exactly once), or false when the
+ * wait timed out, `signal` aborted, or maxWaiting callers were already waiting.
+ */
+export class Admission {
+    max;
+    maxWaiting;
+    used = 0;
+    queue = [];
+    constructor(max, maxWaiting) {
+        this.max = max;
+        this.maxWaiting = maxWaiting;
+    }
+    acquire(waitMs, signal) {
+        if (this.used < this.max && this.queue.length === 0) {
+            this.used++;
+            return Promise.resolve(true);
+        }
+        if (signal?.aborted || waitMs <= 0 || this.queue.length >= this.maxWaiting)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            // admit is called by release(), which hands its unit straight over (used is unchanged).
+            const admit = () => {
+                done();
+                resolve(true);
+            };
+            const giveUp = () => {
+                const i = this.queue.indexOf(admit);
+                if (i >= 0)
+                    this.queue.splice(i, 1);
+                done();
+                resolve(false);
+            };
+            const timer = setTimeout(giveUp, waitMs);
+            const done = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", giveUp);
+            };
+            signal?.addEventListener("abort", giveUp, { once: true });
+            this.queue.push(admit);
+        });
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next)
+            next();
+        else if (this.used > 0)
+            this.used--;
+    }
+    get inUse() {
+        return this.used;
+    }
+    get waiting() {
+        return this.queue.length;
+    }
+}
+// ── The request that is a stream: subscriptions/listen ──
+//
+// A 2026-07-28 client opens subscriptions/listen to hear of list changes, and the SDK answers it
+// with an SSE stream that stays open until the client leaves (or the server closes). This server
+// declares no listChanged (index.ts), so the stream carries the acknowledgement and then only
+// the SDK's keepalives: no work, no API call. Admitted like any other request, it held its place
+// for as long as it was open, so 64 idle listeners (under the per-client limit) left every
+// tools/call, initialize and server/discover on the instance waiting 10 s for a 503 (#2773). So it
+// is relayed without admission and without a work hold. What bounds the streams instead: the
+// per-client limit, which counts each one when it opens; the SDK's own cap of
+// DEFAULT_MAX_SUBSCRIPTIONS (1024 in @modelcontextprotocol/server 2.1.0) open per process, past
+// which it answers JSON-RPC -32603 "Subscription limit reached" at once; and on Cloud Run the
+// instance's 250 requests at once and its 60 s request timeout, which ends every stream
+// (deploy-all.sh SVC_CONCURRENCY, --timeout). Measured 2026-10-04 on dist/http.js, Node 22.22,
+// started as Dockerfile.http starts it, in a 256 MiB memory cgroup, with every place taken (two
+// maximum check_sbom documents and 62 cve_summary held at the API): beside 186 open listen
+// streams (Cloud Run's 250 at once) the cgroup peaked at 209-218 MB of 268 MB, and beside 1,024
+// (the SDK's cap) at 224-225 MB, never OOM-killed. Within Cloud Run's 250, a listen stream
+// takes the instance's concurrency that a waiting request would, and Cloud Run scales out.
+//
+// It is the only such request. GET and DELETE /mcp (the 2025 session stream and its end) are
+// answered 405 at once by the SDK's stateless legacy fallback, a 2025-era POST's SSE answer ends
+// with its result, and the server registers no task or resource subscription. Which request is a
+// listen stream is decided by the SDK's own routing step (classifyInboundRequest, what
+// createMcpHandler runs), so the two cannot disagree: a 2025-era body naming the method goes to
+// the legacy fallback, which answers it at once, and it waits for a place like any request.
+export const LISTEN_METHOD = "subscriptions/listen";
+/** Whether a read POST body is one the SDK serves as a subscriptions/listen stream: see the section comment. */
+export function isListenStream(facts, body, headers) {
+    if (facts.rpc_method !== LISTEN_METHOD)
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        return false;
+    }
+    const route = classifyInboundRequest({
+        httpMethod: "POST",
+        protocolVersionHeader: headers.protocolVersion,
+        mcpMethodHeader: headers.mcpMethod,
+        mcpNameHeader: headers.mcpName,
+        body: parsed,
+    });
+    return route.kind === "modern" && route.messageKind === "request" && route.message.method === LISTEN_METHOD;
+}
 // ── Bounded access-log fields ──
 //
 // The access line carries no body, no query string, no argument and no client address: only