echelongraph-mcp 3.0.2 → 3.1.0

package/dist/http.js

@@ -36,8 +36,9 @@ import http from "node:http";
 import http2 from "node:http2";
 import v8 from "node:v8";
 import { createMcpHandler } from "@modelcontextprotocol/server";
-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, handlerErrorClass, protocolErrorCode, originVerdict, resolveClient, revisionLabel, rpcError, isLargeBodyTarget, isListenStream, largeBodyAdmissible, uaFamily, } from "./httpPolicy.js";
+import { forwardToken, markHttpEntrypoint, onUpstreamFailure, requestLabels, requestSettled, SYNTHETIC_UA_FAMILY, withClient } from "./runtime.js";
+import { Admission, apiRoute, BODY_TOO_LARGE_CODE, BUSY_CODE, DEFAULT_ADMISSION_WAIT_MS, DEFAULT_LARGE_BODY_SLOTS, DEFAULT_LARGE_BODY_WAIT_MS, DEFAULT_LARGE_BODY_WAITERS, 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, handlerErrorClass, httpMethodLabel, protocolErrorCode, originVerdict, resolveClient, revisionLabel, rpcError, rstCodeLabel, isLargeBodyTarget, isListenStream, uaFamily, upstreamSeverity, } from "./httpPolicy.js";
+import { bodyReader, header } from "./readBody.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");
@@ -54,22 +55,45 @@ 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);
+// #2775: how long a large body that finds every slot busy waits for one (at most DEFAULT_LARGE_BODY_WAITERS wait).
+const LARGE_BODY_WAIT_MS = positiveInt(process.env.MCP_LARGE_BODY_WAIT_MS, DEFAULT_LARGE_BODY_WAIT_MS);
 // 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.
+// A large body that waited LARGE_BODY_WAIT_MS for a slot (or found two waiting already), and a
+// request that waited ADMISSION_WAIT_MS for admission, are told to come back.
 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`.
-function log(severity, message, fields = {}) {
+// One JSON object per line on stdout: Cloud Logging reads `severity` and `message`. #2863: the message is one of
+// logLines.ts LOG_LINES and the fields are exactly that line's keys, or this does not compile: a new line or a new
+// key is added there, where what each line carries is reviewed against /privacy Section 11 and the README.
+function log(severity, message, fields) {
     process.stdout.write(`${JSON.stringify({ severity, message, ...fields })}\n`);
 }
+// #2948: one line per API call that failed (runtime.ts upstreamFailed, from index.ts api()), so an
+// answer that says "could not be reached" is on our record too, with its cause. The route is a
+// template (httpPolicy.ts apiRoute): never the path, which can hold what was looked up, nor the
+// query string. tool and rpc_method are the request's bodyFacts (a shape-checked tool, a method from
+// httpPolicy.ts MCP_METHODS or "(other)"); synthetic says the request was the production synthetic's (its User-Agent family). WARNING, except the API's own
+// answer about the input (httpPolicy.ts upstreamSeverity). Written before the request's own
+// mcp_request line, which still says status 200: the JSON-RPC call itself succeeded.
+onUpstreamFailure((f) => {
+    const route = apiRoute(f.path);
+    log(upstreamSeverity(f.failureClass, f.status, route), "mcp_upstream_failed", {
+        tool: f.tool,
+        rpc_method: f.rpcMethod,
+        route,
+        failure_class: f.failureClass,
+        status: f.status,
+        after_ms: f.afterMs,
+        synthetic: f.synthetic,
+    });
+});
 if (process.env.MCP_REQUIRE_FORWARD_TOKEN === "1" && !forwardToken()) {
     log("ERROR", "mcp_remote_refusing_to_start", {
         reason: "MCP_REQUIRE_FORWARD_TOKEN=1 but ECHELONGRAPH_FORWARD_TOKEN is empty: the API would count every remote user as this one service (#2212)",
@@ -85,10 +109,22 @@ const handler = createMcpHandler(createServer, {
     maxRequestBodySize: MAX_SBOM_BODY_BYTES,
     // Never the message: an SDK error message can quote what the client sent. A fixed label and
     // the JSON-RPC code instead, so each one can be told apart (#2923).
-    onerror: (e) => log("WARNING", "mcp_handler_error", { error_name: e.name, error_class: handlerErrorClass(e), error_code: protocolErrorCode(e) }),
+    // #2923: the error by a fixed class and its code, never its message; and the request it arose in by its fixed labels,
+    // read from the request's scope (runtime.ts requestLabels): its JSON-RPC method (MCP_METHODS or "(other)"), its
+    // protocol version.
+    onerror: (e) => {
+        const labels = requestLabels();
+        log("WARNING", "mcp_handler_error", {
+            error_name: e.name,
+            error_class: handlerErrorClass(e),
+            error_code: protocolErrorCode(e),
+            rpc_method: labels.rpcMethod,
+            protocol_version: labels.protocolVersion,
+        });
+    },
 });
 const limiter = new FixedWindowLimiter(RATE_LIMIT_PER_MIN);
-const largeBodies = new Slots(LARGE_BODY_SLOTS);
+const largeBodies = new Slots(LARGE_BODY_SLOTS, DEFAULT_LARGE_BODY_WAITERS);
 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.
@@ -116,76 +152,19 @@ function send(res, status, body, headers = {}) {
     res.writeHead(status, forProtocol(res, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers }));
     res.end(body);
 }
-function readBody(req) {
-    const mayBeLarge = largeBodyAdmissible(header(req, "mcp-method"), header(req, "mcp-name"));
-    const cap = mayBeLarge ? MAX_SBOM_BODY_BYTES : MAX_BODY_BYTES;
-    const declared = Number(req.headers["content-length"]);
-    if (Number.isFinite(declared) && declared > cap) {
-        req.resume();
-        return Promise.resolve("too_large");
-    }
-    let slot = false;
-    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
-        if (!largeBodies.tryAcquire()) {
-            req.resume();
-            return Promise.resolve("busy");
-        }
-        slot = true;
-    }
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let size = 0;
-        let done = false;
-        const stop = (r) => {
-            done = true;
-            chunks.length = 0;
-            if (slot)
-                largeBodies.release();
-            slot = false;
-            resolve(r);
-        };
-        req.on("data", (chunk) => {
-            if (done)
-                return;
-            size += chunk.length;
-            if (size > cap)
-                return stop("too_large");
-            if (size > MAX_BODY_BYTES && !slot) {
-                if (!largeBodies.tryAcquire())
-                    return stop("busy");
-                slot = true;
-            }
-            chunks.push(chunk);
-        });
-        req.on("end", () => {
-            if (done)
-                return;
-            done = true;
-            resolve({ body: Buffer.concat(chunks), slot });
-        });
-        req.on("close", () => {
-            if (!done)
-                stop("gone");
-        });
-        req.on("error", (e) => {
-            if (done)
-                return;
-            done = true;
-            if (slot)
-                largeBodies.release();
-            reject(e);
-        });
-    });
-}
-function header(req, name) {
-    const v = req.headers[name];
-    return Array.isArray(v) ? v.join(", ") : v;
-}
+// The body is read by readBody.ts, over this instance's large-body slots and caps.
+const readBody = bodyReader(largeBodies, { maxBodyBytes: MAX_BODY_BYTES, maxSbomBodyBytes: MAX_SBOM_BODY_BYTES, largeBodyWaitMs: LARGE_BODY_WAIT_MS });
 function tooLarge(res, cors) {
     send(res, 413, rpcError(BODY_TOO_LARGE_CODE, `Request body too large: at most ${MAX_BODY_BYTES} bytes, or ${MAX_SBOM_BODY_BYTES} bytes for ${LARGE_BODY_TARGETS_TEXT}. A larger SBOM or lockfile can be passed to check_sbom as its purls.`, { max_bytes: MAX_BODY_BYTES, max_bytes_sbom: MAX_SBOM_BODY_BYTES }), { ...cors, Connection: "close" });
     return { status: 413, refused: "body_size" };
 }
+// #2775: the access line's slot_wait_ms is how long the request's large body waited for a slot, whatever came of it.
 async function serveMcp(req, res, pathname) {
+    const timing = { slotWaitMs: 0 };
+    const o = await serveMcpTimed(req, res, pathname, timing);
+    return { ...o, slotWaitMs: timing.slotWaitMs };
+}
+async function serveMcpTimed(req, res, pathname, timing) {
     const method = req.method ?? "GET";
     const origin = req.headers.origin;
     const verdict = originVerdict(Array.isArray(origin) ? origin.join(", ") : origin);
@@ -218,7 +197,8 @@ async function serveMcp(req, res, pathname) {
     // 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).
+    // (the access line's duration_ms is when the call actually stopped). rst_code is the stream's reset code when it is
+    // one HTTP/2 defines (0 to 13), else "(other)" (httpPolicy.ts rstCodeLabel): under h2c the client chooses it.
     const gone = new AbortController();
     const t0 = Date.now();
     const h2stream = res.stream;
@@ -226,7 +206,7 @@ async function serveMcp(req, res, pathname) {
         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 });
+        log("INFO", "mcp_client_gone", { after_ms: Date.now() - t0, answer_started: res.headersSent, rst_code: rstCodeLabel(h2stream?.rstCode) });
     };
     res.on("close", () => {
         if (!res.writableFinished || h2stream?.aborted)
@@ -250,7 +230,7 @@ async function serveMcp(req, res, pathname) {
         if (method === "POST") {
             let read;
             try {
-                read = await readBody(req);
+                read = await readBody(req, gone.signal, timing);
             }
             catch (e) {
                 // The request stream fails only when its connection does: the client went mid-upload.
@@ -280,7 +260,7 @@ async function serveMcp(req, res, pathname) {
             // 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 };
+                return { ...(await relay(req, res, pathname, method, cors, client, body, facts, gone.signal)), facts };
         }
         // #2773: at most MAX_IN_FLIGHT requests are served at once; the next waits here.
         const waitStart = Date.now();
@@ -298,7 +278,7 @@ async function serveMcp(req, res, pathname) {
         // 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 };
+            return { ...(await relay(req, res, pathname, method, cors, client, body, facts, gone.signal, work)), facts, ...admitted };
         }
         finally {
             // Every tool call stops on `gone` (#2775), so this wait is long only if one does not.
@@ -313,7 +293,7 @@ async function serveMcp(req, res, pathname) {
 }
 // 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) {
+async function relay(req, res, pathname, method, cors, client, body, facts, gone, work) {
     const headers = new Headers();
     for (const [k, v] of Object.entries(req.headers)) {
         // ":method", ":path", ":authority", ":scheme": an h2 request's pseudo-headers, which a Request cannot carry.
@@ -332,7 +312,17 @@ async function relay(req, res, pathname, method, cors, client, body, gone, work)
     // 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, signal: gone, work });
+    // #2948: the method and tool name a failed API call's line names (runtime.ts upstreamFailed).
+    // #2923: and the protocol-version label a handler error's line names (runtime.ts requestLabels).
+    const protocolVersion = revisionLabel(req.headers["mcp-protocol-version"]);
+    const response = await withClient(client.forwardAddress, () => handler.fetch(request), {
+        synthetic,
+        signal: gone,
+        work,
+        rpcMethod: facts?.rpc_method,
+        tool: facts?.tool,
+        protocolVersion,
+    });
     const out = { ...cors };
     response.headers.forEach((v, k) => {
         out[k] = v;
@@ -362,7 +352,7 @@ function onRequest(req, res) {
     const finish = (o) => {
         const facts = o.facts ?? (o.body ? bodyFacts(o.body) : { rpc_method: "(none)" });
         log("INFO", "mcp_request", {
-            method,
+            method: httpMethodLabel(method),
             path: pathname === MCP_PATH || pathname === HEALTH_PATH ? pathname : "(other)",
             status: o.status,
             duration_ms: Number((process.hrtime.bigint() - start) / 1000000n),
@@ -377,6 +367,7 @@ function onRequest(req, res) {
             client_closed: o.clientClosed === true,
             in_flight: o.inFlight ?? 0,
             queued_ms: o.queuedMs ?? 0,
+            slot_wait_ms: o.slotWaitMs ?? 0,
         });
     };
     if (pathname === HEALTH_PATH) {
@@ -438,6 +429,7 @@ server.listen(PORT, () => {
         max_body_bytes: MAX_BODY_BYTES,
         max_sbom_body_bytes: MAX_SBOM_BODY_BYTES,
         large_body_slots: LARGE_BODY_SLOTS,
+        large_body_wait_ms: LARGE_BODY_WAIT_MS,
         max_in_flight: MAX_IN_FLIGHT,
         admission_wait_ms: ADMISSION_WAIT_MS,
         heap_limit_mb: Math.round(heapLimit / MiB),

package/dist/httpPolicy.js

@@ -229,14 +229,21 @@ 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, 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
+// instance for as long as it is read, waits for a place (below) and is served. With none free it
+// waits up to DEFAULT_LARGE_BODY_WAIT_MS for one, at most DEFAULT_LARGE_BODY_WAITERS at once, and
+// is answered 503 with Retry-After when its wait runs out, or at once when that many already wait
+// (#2775, decided 2026-10-18: behind the Google Frontend a client's close reaches the container too
+// late to free the slot of the call it abandoned, so its retry must be able to wait out that call;
+// a waiter holds at most the 64 KiB read before it needed the slot, so two of them change nothing
+// of the memory bound). 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;
+export const DEFAULT_LARGE_BODY_WAIT_MS = 15_000;
+export const DEFAULT_LARGE_BODY_WAITERS = 2;
 /** The requests whose body may pass DEFAULT_MAX_BODY_BYTES: JSON-RPC method → the tools or prompts it may name.
  *  #2835: scan_manifest takes a project's lockfiles as text, up to the same 5,000,000 characters as
  *  check_sbom's document (scan_manifest.ts MAX_MANIFEST_CHARS), so it is admitted the same way. */
@@ -259,12 +266,17 @@ export function isLargeBodyTarget(facts) {
     const name = facts.rpc_method === "tools/call" ? facts.tool : facts.rpc_method === "prompts/get" ? facts.prompt : undefined;
     return name !== undefined && targetsOf(facts.rpc_method).includes(name);
 }
-/** A counting semaphore that never waits: tryAcquire answers at once. */
+/** A counting semaphore: tryAcquire answers at once; acquire (#2775) waits up to waitMs for a slot, first come first
+ *  served, with at most maxWaiting waiting (past that it answers false at once). release hands a freed slot straight
+ *  to the first waiter. */
 export class Slots {
     max;
+    maxWaiting;
     used = 0;
-    constructor(max) {
+    queue = [];
+    constructor(max, maxWaiting = 0) {
         this.max = max;
+        this.maxWaiting = maxWaiting;
     }
     tryAcquire() {
         if (this.used >= this.max)
@@ -272,13 +284,50 @@ export class Slots {
         this.used++;
         return true;
     }
+    /** Whether acquire(waitMs) would wait for a slot, rather than answer at once (one is free, or none may wait). */
+    wouldWait(waitMs) {
+        return this.used >= this.max && waitMs > 0 && this.queue.length < this.maxWaiting;
+    }
+    acquire(waitMs, signal) {
+        if (this.tryAcquire())
+            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 slot 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() {
-        if (this.used > 0)
+        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;
+    }
 }
 // ── Requests in flight per instance (#2773) ──
 //
@@ -437,11 +486,54 @@ export function isListenStream(facts, body, headers) {
 //
 // The access line carries no body, no query string, no argument and no client address: only
 // values from small closed sets or shapes, so nothing a client types reaches the log (#1983).
-const RPC_METHOD = /^[a-z][a-z/_]{0,39}$/i;
+// #2923's review (nit): rpc_method is a label from a closed set, never the client's own string. It is the method
+// when MCP defines it for a client to send, and "(other)" for any other string, however well shaped: the SDK's
+// ClientRequestSchema and ClientNotificationSchema (@modelcontextprotocol/core 2.1.0, which the server bundles), and
+// the 2025-11-25 task methods the SDK defines beside them. test/http-policy.test.mjs reads both unions from the
+// SDK, so an SDK upgrade that adds a client method fails there until it is listed here.
+export const MCP_METHODS = new Set([
+    // ClientRequestSchema
+    "ping",
+    "initialize",
+    "server/discover",
+    "completion/complete",
+    "logging/setLevel",
+    "prompts/get",
+    "prompts/list",
+    "resources/list",
+    "resources/templates/list",
+    "resources/read",
+    "resources/subscribe",
+    "resources/unsubscribe",
+    "subscriptions/listen",
+    "tools/call",
+    "tools/list",
+    // ClientNotificationSchema
+    "notifications/cancelled",
+    "notifications/progress",
+    "notifications/initialized",
+    "notifications/roots/list_changed",
+    // The task methods (GetTaskRequestSchema, GetTaskPayloadRequestSchema, ListTasksRequestSchema,
+    // CancelTaskRequestSchema, TaskStatusNotificationSchema)
+    "tasks/get",
+    "tasks/result",
+    "tasks/list",
+    "tasks/cancel",
+    "notifications/tasks/status",
+]);
+// 3.1.0's final review (low): the access line's `method` is a label from a closed set too. Over HTTP/1.1 Node's parser
+// admits only its own method list, but over h2c (production's protocol) the :method pseudo-header is whatever token the
+// client sent, and it reached the log verbatim ("JOHN.DOE-SSN-123-45-6789", an 8,000-character token). It is one of
+// these nine, as sent (case and all), else "(other)".
+export const HTTP_METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "CONNECT", "TRACE"]);
+/** The request's HTTP method when it is one of HTTP_METHODS, else "(other)"; never the client's own token. */
+export function httpMethodLabel(m) {
+    return m !== undefined && HTTP_METHODS.has(m) ? m : "(other)";
+}
 const TOOL_NAME = /^[a-z][a-z0-9_]{0,39}$/;
 const REVISION = /^\d{4}-\d{2}-\d{2}$/;
 const UA_FAMILY = /^[A-Za-z0-9._-]{1,40}$/;
-/** The JSON-RPC method and, for tools/call, the tool name (for prompts/get, the prompt name), shape-checked; never anything else from the body. */
+/** The JSON-RPC method, one of MCP_METHODS or "(other)", and, for tools/call, the tool name (for prompts/get, the prompt name), shape-checked; never anything else from the body. */
 export function bodyFacts(body) {
     if (!body || body.length === 0)
         return { rpc_method: "(none)" };
@@ -459,7 +551,7 @@ export function bodyFacts(body) {
     const m = parsed.method;
     if (typeof m !== "string")
         return { rpc_method: "(response)" };
-    if (!RPC_METHOD.test(m))
+    if (!MCP_METHODS.has(m))
         return { rpc_method: "(other)" };
     if (m !== "tools/call" && m !== "prompts/get")
         return { rpc_method: m };
@@ -467,6 +559,16 @@ export function bodyFacts(body) {
     const shaped = typeof name === "string" && TOOL_NAME.test(name) ? name : "(other)";
     return m === "tools/call" ? { rpc_method: m, tool: shaped } : { rpc_method: m, prompt: shaped };
 }
+/** HTTP/2's error codes (RFC 9113 §7): NO_ERROR (0x0) to HTTP_1_1_REQUIRED (0xd). */
+export const H2_MAX_ERROR_CODE = 0xd;
+/** An HTTP/2 stream's reset code as mcp_client_gone logs it: a code RFC 9113 defines, else "(other)"; null when the
+ *  request came over HTTP/1.1 or its stream was not reset. Under direct h2c the code is the client's own RST_STREAM,
+ *  any 32-bit number it chose (3.1.0's final panel: a reset with 0x7a71c0de logged rst_code 2054275294). */
+export function rstCodeLabel(code) {
+    if (code === undefined || code === null)
+        return null;
+    return Number.isInteger(code) && code >= 0 && code <= H2_MAX_ERROR_CODE ? code : "(other)";
+}
 export function revisionLabel(v) {
     if (v === undefined)
         return "(none)";
@@ -521,10 +623,36 @@ const HANDLER_ERROR_CLASSES = [
     ["Failed to encode result", "encode_result_failed"],
     ["Failed to send", "send_failed"],
 ];
+// #2923, 2026-10-18: a live read since 3.0.2 found one line with error_class "other" and error_code -32022. The
+// bundled SDK (@modelcontextprotocol/server 2.1.0) raises -32022 on these paths:
+//   - createMcpHandler serveModern: an UnsupportedProtocolVersionError, "Unsupported protocol version: <requested>"
+//     (index.mjs:1334), for a modern request naming an unsupported revision or none ("unknown");
+//   - modernOnlyStrictRejection: a ProtocolError, "Unsupported protocol version: the request did not name a protocol
+//     version" (src-D-y6h4N7.mjs:5313), reported as "Rejected 2025-era request on a modern-only endpoint" (a
+//     legacy: "reject" endpoint only; this one serves the 2025 era);
+//   - Protocol._onrequest's era mismatch, answered with -32022 (src-D-y6h4N7.mjs:6467) and reported as "Era mismatch";
+//   - ProtocolError.fromError (src-D-y6h4N7.mjs:3614): a peer's -32022 error response, rebuilt with the PEER's own
+//     message, which no prefix can know. That is how "other" with -32022 is reached.
+// So a message no prefix knows is classified by its JSON-RPC code where the code names a cause (HANDLER_ERROR_CODES):
+// -32022 is unsupported_protocol_version whatever its message, and "other" with -32022 cannot occur.
+const HANDLER_ERROR_CODES = new Map([
+    [-32022, "unsupported_protocol_version"],
+    [-32021, "missing_client_capability"],
+    [-32020, "header_mismatch"],
+    [-32700, "parse_error"],
+    [-32600, "invalid_request"],
+    [-32601, "method_not_found"],
+    [-32602, "invalid_params"],
+]);
 export function handlerErrorClass(e) {
-    const message = e instanceof Error ? e.message : "";
+    // A thrown non-Error (an object with a message) is read as an Error would be; its message is still never logged.
+    const m = e?.message;
+    const message = typeof m === "string" ? m : "";
     const hit = HANDLER_ERROR_CLASSES.find(([prefix]) => message.startsWith(prefix));
-    return hit ? hit[1] : "other";
+    if (hit)
+        return hit[1];
+    const code = protocolErrorCode(e);
+    return (code !== undefined && HANDLER_ERROR_CODES.get(code)) || "other";
 }
 export function protocolErrorCode(e) {
     const code = e?.code;
@@ -540,3 +668,62 @@ export function classifyHandlerError(e) {
         out.error_code = code;
     return out;
 }
+// ── The upstream-failure line (#2948) ──
+//
+// mcp_upstream_failed (http.ts) names the API call that failed by its ROUTE, never its path: a
+// lookup's path holds what was looked up (a CVE or CWE ID, a vendor and an advisory ID), and a
+// search's query string its filters (#1983). The route is one of the fixed templates below, each
+// core-backend's own name for it (the route field of its http_request line, router.go), so the two
+// lines can be read side by side: Fiber names a group's "/" with its trailing slash, so the two list
+// routes end in "/" although the server calls them without it (#2948's review; marketing-site
+// lib/privacyMcpEndpoint.test.ts holds every template to router.go). A path is matched whole, its query string dropped first, and only
+// the template that matched comes out: "(other)" when none does, "(none)" when no path is at hand
+// (an answer checked() refused against the tool's schema names none). The tool name (shape-checked)
+// and the JSON-RPC method (MCP_METHODS or "(other)") on the line are bodyFacts' own; the class,
+// status and duration are the server's. Nothing a client typed reaches it.
+const API_ROUTES = [
+    [/^\/api\/v1\/public\/cves\/?$/, "/api/v1/public/cves/"],
+    [/^\/api\/v1\/public\/cves\/summary$/, "/api/v1/public/cves/summary"],
+    [/^\/api\/v1\/public\/cves\/match$/, "/api/v1/public/cves/match"],
+    [/^\/api\/v1\/public\/cves\/match\/batch$/, "/api/v1/public/cves/match/batch"],
+    [/^\/api\/v1\/public\/cves\/[^/]+$/, "/api/v1/public/cves/:id"],
+    [/^\/api\/v1\/public\/cves\/[^/]+\/enrichment$/, "/api/v1/public/cves/:id/enrichment"],
+    [/^\/api\/v1\/public\/cves\/[^/]+\/epss-history$/, "/api/v1/public/cves/:id/epss-history"],
+    [/^\/api\/v1\/public\/cves\/[^/]+\/remediation$/, "/api/v1/public/cves/:id/remediation"],
+    [/^\/api\/v1\/public\/cwes\/[^/]+$/, "/api/v1/public/cwes/:cwe_id"],
+    [/^\/api\/v1\/public\/kev\/recent$/, "/api/v1/public/kev/recent"],
+    [/^\/api\/v1\/public\/kev-exposure\/stats$/, "/api/v1/public/kev-exposure/stats"],
+    [/^\/api\/v1\/public\/kev-exposure\/cve\/[^/]+$/, "/api/v1/public/kev-exposure/cve/:id"],
+    [/^\/api\/v1\/public\/exposed-databases\/stats$/, "/api/v1/public/exposed-databases/stats"],
+    [/^\/api\/v1\/public\/leaked-credentials\/stats$/, "/api/v1/public/leaked-credentials/stats"],
+    [/^\/api\/v1\/public\/shadow-ai-radar\/stats$/, "/api/v1/public/shadow-ai-radar/stats"],
+    [/^\/api\/v1\/public\/ai-exposure\/stats$/, "/api/v1/public/ai-exposure/stats"],
+    [/^\/api\/v1\/public\/vendor-advisories\/?$/, "/api/v1/public/vendor-advisories/"],
+    [/^\/api\/v1\/public\/vendor-advisories\/coverage$/, "/api/v1/public/vendor-advisories/coverage"],
+    [/^\/api\/v1\/public\/vendor-advisories\/by-cve\/[^/]+$/, "/api/v1/public/vendor-advisories/by-cve/:cve_id"],
+    [/^\/api\/v1\/public\/vendor-advisories\/[^/]+\/[^/]+$/, "/api/v1/public/vendor-advisories/:vendor/:advisory_id"],
+];
+/** Every route template the upstream-failure line can name, in match order. */
+export const API_ROUTE_TEMPLATES = API_ROUTES.map(([, route]) => route);
+/** The route template of an API path (its query string dropped): one of API_ROUTE_TEMPLATES, "(other)", or "(none)" for no path. */
+export function apiRoute(path) {
+    if (path === null)
+        return "(none)";
+    const p = path.split(/[?#]/, 1)[0];
+    const hit = API_ROUTES.find(([re]) => re.test(p));
+    return hit ? hit[1] : "(other)";
+}
+// The severity. The API's own answer about the input is no outage: a 400 (it refused the input,
+// which the tool reports as invalid_input) or a 404 on a route that names a record (no such CVE,
+// CWE or advisory: the tool reports no record). Those are INFO, so the log metric, which counts
+// WARNING, and its alert see only failures. A 404 on a route that names none (a list, the summary, a
+// radar's stats) means the route is gone, and is WARNING with every other failure.
+// #2948's review: output_schema (the tool's own outputSchema refused the answer) is this server's fault, not an
+// upstream failure: ERROR, which the upstream metric (WARNING lines) does not count.
+export function upstreamSeverity(failureClass, status, route) {
+    if (failureClass === "output_schema")
+        return "ERROR";
+    if (failureClass === "http" && (status === 400 || (status === 404 && route.includes("/:"))))
+        return "INFO";
+    return "WARNING";
+}