@cyanheads/mcp-ts-core 0.13.3 → 0.13.5

package/dist/utils/network/httpError.d.ts

@@ -10,11 +10,18 @@ import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
  * 4xx/5xx range, with specific mappings for the codes most upstream APIs use to
  * signal authoritative outcomes (auth failures, conflicts, validation, rate limits).
  *
- * Returns `undefined` when the status is in the 1xx/2xx/3xx range — those are not
+ * Returns `undefined` when the status is in the 1xx/2xx range — those are not
  * errors and the caller should not be invoking error mapping on them.
  *
+ * A 3xx does reach error mapping: under `redirect: 'manual'` the caller gets the
+ * redirect back rather than the followed response, and `!response.ok` throws. It
+ * maps like an unlisted 4xx — the request as sent cannot be served at this URL —
+ * which also keeps it out of `withRetry`'s transient set, since re-issuing it
+ * returns the same redirect.
+ *
  * | Status | Code |
  * |:-------|:-----|
+ * | 3xx | `InvalidRequest` |
  * | 400 | `InvalidParams` |
  * | 401 | `Unauthorized` |
  * | 402 | `Forbidden` (payment-required, treated as access denial) |
@@ -57,6 +64,26 @@ export declare function httpStatusToErrorCode(status: number): JsonRpcErrorCode
 export declare function httpStatusRetryability(status: number): {
     retryable: false;
 } | undefined;
+/**
+ * The selected response headers as a fragment to spread into an `McpError`'s
+ * `data`, mirroring {@link httpStatusRetryability}'s shape: `undefined` when
+ * nothing was captured, so the spread adds no `headers` key at all.
+ *
+ * Selection is case-insensitive and keys are lowercased, so `['X-Request-Id']`
+ * and `['x-request-id']` collapse to one `headers['x-request-id']` entry.
+ * Presence follows `Headers.has()` — a header carried with an empty value is
+ * captured as `''`, one the response does not carry adds no key — and a
+ * multi-valued field is captured comma-joined, as `Headers.get()` returns it.
+ *
+ * Every captured value reaches the MCP client as `structuredContent.error.data`,
+ * which is why capture is an explicit allowlist rather than a redacted copy of
+ * every header: an arbitrary upstream header name can carry a secret, so no
+ * field-name redactor can make the default safe. Both HTTP helpers route through
+ * here so the two cannot drift apart.
+ */
+export declare function selectErrorHeaders(headers: Headers, selector: readonly string[] | undefined): {
+    headers: Record<string, string>;
+} | undefined;
 /** Configuration for {@link httpErrorFromResponse}. */
 export interface HttpErrorFromResponseOptions {
     /**
@@ -82,14 +109,36 @@ export interface HttpErrorFromResponseOptions {
     codeOverride?: (status: number) => JsonRpcErrorCode | undefined;
     /**
      * Additional fields merged into `error.data`. Always includes
-     * `{ url, status, statusText, body? }` from the response itself, plus the
-     * legacy aliases `statusCode` (= `status`) and `responseBody` (= `body`) for
+     * `{ status, statusText, body? }` from the response itself, plus the legacy
+     * aliases `statusCode` (= `status`) and `responseBody` (= `body`) for
      * consumers reading `fetchWithTimeout`'s shape — slated for consolidation in a
      * future major. A status whose failure is permanent also carries
      * `retryable: false` (see {@link httpStatusRetryability}). Fields passed here
      * override the defaults on key collision.
+     *
+     * `error.data` is forwarded to the client as `structuredContent.error.data`,
+     * so treat everything put here as client-visible.
      */
     data?: Record<string, unknown>;
+    /**
+     * Response headers to copy onto `error.data.headers` under lowercase keys —
+     * provider budget headers (`x-ratelimit-remaining-usd`), a quota reset, a
+     * request ID. Omitted or empty, no `headers` key is emitted. `set-cookie` is
+     * never captured. See {@link selectErrorHeaders} for the selection semantics.
+     *
+     * Every selected value reaches the client alongside the rest of `error.data`,
+     * so never name a header that carries a credential — and note that a
+     * `Location` can itself carry a sensitive path, query, or token.
+     */
+    errorHeaders?: string[];
+    /**
+     * Put the full `response.url` — path and query string included — on
+     * `error.data.url`. Default: `false`, because `error.data` reaches the client
+     * and an upstream request URL routinely carries user input, internal
+     * identifiers, or an API key in its query string. The error message still
+     * names the host either way. No key is added when `response.url` is empty.
+     */
+    includeUrl?: boolean;
     /**
      * Logical service name included in the error message
      * (e.g., `'NCBI'` → `"NCBI returned HTTP 429"`). When omitted, the message
@@ -104,9 +153,10 @@ export interface HttpErrorFromResponseOptions {
  * Reads the response body (consuming it) when `captureBody` is true, so callers
  * must `response.clone()` first if they intend to read the body elsewhere.
  *
- * Always returns an `McpError` even for 1xx/2xx/3xx — the caller is expected to
- * have verified `!response.ok` first, but the helper falls back to a sensible
- * code (`InternalError`) instead of silently producing nothing.
+ * Always returns an `McpError` even for 1xx/2xx — the caller is expected to have
+ * verified `!response.ok` first, but the helper falls back to a sensible code
+ * (`InternalError`) instead of silently producing nothing. A 3xx is a real
+ * outcome here rather than a fallback: see {@link httpStatusToErrorCode}.
  *
  * @example
  * ```ts

package/dist/utils/network/httpError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"httpError.d.ts","sourceRoot":"","sources":["../../../src/utils/network/httpError.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CA+BlF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,KAAK,CAAA;CAAE,GAAG,SAAS,CAEvF;AAED,uDAAuD;AACvD,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,CAAC;IAChE;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,QAAQ,CAAC,CAmDnB"}
+{"version":3,"file":"httpError.d.ts","sourceRoot":"","sources":["../../../src/utils/network/httpError.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAgClF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,KAAK,CAAA;CAAE,GAAG,SAAS,CAEvF;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACtC;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,SAAS,CAWjD;AAED,uDAAuD;AACvD,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,CAAC;IAChE;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,QAAQ,CAAC,CAwDnB"}

package/dist/utils/network/httpError.js

@@ -11,11 +11,18 @@ import { readBoundedResponseText } from './responseBody.js';
  * 4xx/5xx range, with specific mappings for the codes most upstream APIs use to
  * signal authoritative outcomes (auth failures, conflicts, validation, rate limits).
  *
- * Returns `undefined` when the status is in the 1xx/2xx/3xx range — those are not
+ * Returns `undefined` when the status is in the 1xx/2xx range — those are not
  * errors and the caller should not be invoking error mapping on them.
  *
+ * A 3xx does reach error mapping: under `redirect: 'manual'` the caller gets the
+ * redirect back rather than the followed response, and `!response.ok` throws. It
+ * maps like an unlisted 4xx — the request as sent cannot be served at this URL —
+ * which also keeps it out of `withRetry`'s transient set, since re-issuing it
+ * returns the same redirect.
+ *
  * | Status | Code |
  * |:-------|:-----|
+ * | 3xx | `InvalidRequest` |
  * | 400 | `InvalidParams` |
  * | 401 | `Unauthorized` |
  * | 402 | `Forbidden` (payment-required, treated as access denial) |
@@ -43,8 +50,10 @@ import { readBoundedResponseText } from './responseBody.js';
  * non-transient code.
  */
 export function httpStatusToErrorCode(status) {
-    if (status < 400)
+    if (status < 300)
         return;
+    if (status < 400)
+        return JsonRpcErrorCode.InvalidRequest;
     switch (status) {
         case 400:
             return JsonRpcErrorCode.InvalidParams;
@@ -89,6 +98,42 @@ export function httpStatusToErrorCode(status) {
 export function httpStatusRetryability(status) {
     return status === 501 ? { retryable: false } : undefined;
 }
+/**
+ * Response headers no selector can reach. `set-cookie` is credential-bearing,
+ * and `Headers.get()` joins its values into a string that is not a valid
+ * reconstruction of the field, so capturing it would leak a secret and misreport
+ * it at the same time.
+ */
+const NEVER_CAPTURED_HEADERS = new Set(['set-cookie']);
+/**
+ * The selected response headers as a fragment to spread into an `McpError`'s
+ * `data`, mirroring {@link httpStatusRetryability}'s shape: `undefined` when
+ * nothing was captured, so the spread adds no `headers` key at all.
+ *
+ * Selection is case-insensitive and keys are lowercased, so `['X-Request-Id']`
+ * and `['x-request-id']` collapse to one `headers['x-request-id']` entry.
+ * Presence follows `Headers.has()` — a header carried with an empty value is
+ * captured as `''`, one the response does not carry adds no key — and a
+ * multi-valued field is captured comma-joined, as `Headers.get()` returns it.
+ *
+ * Every captured value reaches the MCP client as `structuredContent.error.data`,
+ * which is why capture is an explicit allowlist rather than a redacted copy of
+ * every header: an arbitrary upstream header name can carry a secret, so no
+ * field-name redactor can make the default safe. Both HTTP helpers route through
+ * here so the two cannot drift apart.
+ */
+export function selectErrorHeaders(headers, selector) {
+    if (!selector?.length)
+        return;
+    const captured = {};
+    for (const name of selector) {
+        const key = name.toLowerCase();
+        if (NEVER_CAPTURED_HEADERS.has(key) || !headers.has(key))
+            continue;
+        captured[key] = headers.get(key) ?? '';
+    }
+    return Object.keys(captured).length > 0 ? { headers: captured } : undefined;
+}
 const DEFAULT_BODY_LIMIT = 500;
 /**
  * Builds an `McpError` from an HTTP `Response`, with status-aware classification
@@ -97,9 +142,10 @@ const DEFAULT_BODY_LIMIT = 500;
  * Reads the response body (consuming it) when `captureBody` is true, so callers
  * must `response.clone()` first if they intend to read the body elsewhere.
  *
- * Always returns an `McpError` even for 1xx/2xx/3xx — the caller is expected to
- * have verified `!response.ok` first, but the helper falls back to a sensible
- * code (`InternalError`) instead of silently producing nothing.
+ * Always returns an `McpError` even for 1xx/2xx — the caller is expected to have
+ * verified `!response.ok` first, but the helper falls back to a sensible code
+ * (`InternalError`) instead of silently producing nothing. A 3xx is a real
+ * outcome here rather than a fallback: see {@link httpStatusToErrorCode}.
  *
  * @example
  * ```ts
@@ -127,7 +173,7 @@ const DEFAULT_BODY_LIMIT = 500;
  * ```
  */
 export async function httpErrorFromResponse(response, options = {}) {
-    const { captureBody = true, bodyLimit = DEFAULT_BODY_LIMIT, service, data: extraData, cause, codeOverride, } = options;
+    const { captureBody = true, bodyLimit = DEFAULT_BODY_LIMIT, includeUrl = false, service, data: extraData, cause, codeOverride, errorHeaders, } = options;
     const code = codeOverride?.(response.status) ??
         httpStatusToErrorCode(response.status) ??
         JsonRpcErrorCode.InternalError;
@@ -144,7 +190,9 @@ export async function httpErrorFromResponse(response, options = {}) {
     }
     const retryAfter = response.headers.get('retry-after') ?? undefined;
     const data = {
-        url: response.url || undefined,
+        // The full URL is opt-in: `error.data` reaches the client, and a request URL
+        // routinely carries user input or an API key in its query string.
+        ...(includeUrl && response.url && { url: response.url }),
         // Canonical (Fetch `Response`-aligned) field names.
         status: response.status,
         statusText: response.statusText || undefined,
@@ -156,6 +204,7 @@ export async function httpErrorFromResponse(response, options = {}) {
         ...(body !== undefined && { responseBody: body }),
         ...(retryAfter !== undefined && { retryAfter }),
         ...httpStatusRetryability(response.status),
+        ...selectErrorHeaders(response.headers, errorHeaders),
         ...extraData,
     };
     return new McpError(code, `${subject} returned HTTP ${response.status}${statusText}.`, data, cause !== undefined ? { cause } : undefined);

package/dist/utils/network/httpError.js.map

@@ -1 +1 @@
-{"version":3,"file":"httpError.js","sourceRoot":"","sources":["../../../src/utils/network/httpError.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"httpError.js","sourceRoot":"","sources":["../../../src/utils/network/httpError.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO;IACzB,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,gBAAgB,CAAC,cAAc,CAAC;IAEzD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,aAAa,CAAC;QACxC,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,YAAY,CAAC;QACvC,KAAK,GAAG,CAAC;QACT,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,SAAS,CAAC;QACpC,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,QAAQ,CAAC;QACnC,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,OAAO,CAAC;QAClC,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,QAAQ,CAAC;QACnC,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,eAAe,CAAC;QAC1C,KAAK,GAAG,CAAC;QACT,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,QAAQ,CAAC;QACnC,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,OAAO,CAAC;QAClC,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,WAAW,CAAC;QACtC,KAAK,GAAG;YACN,OAAO,gBAAgB,CAAC,OAAO,CAAC;QAClC;YACE,OAAO,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC,CAAC,gBAAgB,CAAC,cAAc,CAAC;IACjG,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAgB,EAChB,QAAuC;IAEvC,IAAI,CAAC,QAAQ,EAAE,MAAM;QAAE,OAAO;IAE9B,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC/B,IAAI,sBAAsB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QACnE,QAAQ,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9E,CAAC;AAiED,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,QAAkB,EAClB,OAAO,GAAiC,EAAE;IAE1C,MAAM,EACJ,WAAW,GAAG,IAAI,EAClB,SAAS,GAAG,kBAAkB,EAC9B,UAAU,GAAG,KAAK,EAClB,OAAO,EACP,IAAI,EAAE,SAAS,EACf,KAAK,EACL,YAAY,EACZ,YAAY,GACb,GAAG,OAAO,CAAC;IAEZ,MAAM,IAAI,GACR,YAAY,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC/B,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC;QACtC,gBAAgB,CAAC,aAAa,CAAC;IAEjC,MAAM,OAAO,GAAG,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC;IAChE,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAExE,IAAI,IAAwB,CAAC;IAC7B,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC5D,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;QACpE,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,SAAS,CAAC;IAEpE,MAAM,IAAI,GAA4B;QACpC,6EAA6E;QAC7E,kEAAkE;QAClE,GAAG,CAAC,UAAU,IAAI,QAAQ,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC;QACxD,oDAAoD;QACpD,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,UAAU,EAAE,QAAQ,CAAC,UAAU,IAAI,SAAS;QAC5C,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC;QACnC,8EAA8E;QAC9E,6EAA6E;QAC7E,wDAAwD;QACxD,UAAU,EAAE,QAAQ,CAAC,MAAM;QAC3B,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QACjD,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;QAC/C,GAAG,sBAAsB,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC1C,GAAG,kBAAkB,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;QACrD,GAAG,SAAS;KACb,CAAC;IAEF,OAAO,IAAI,QAAQ,CACjB,IAAI,EACJ,GAAG,OAAO,kBAAkB,QAAQ,CAAC,MAAM,GAAG,UAAU,GAAG,EAC3D,IAAI,EACJ,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAC5C,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;AACH,CAAC"}

package/dist/utils/network/pacer.d.ts

@@ -0,0 +1,117 @@
+/**
+ * One sliding start-rate window, e.g. `{ requests: 5, perMs: 60_000 }` for five
+ * requests a minute. Several may be declared together (per-minute and per-hour);
+ * a start needs every one of them to allow it.
+ */
+export interface PacerLimit {
+    /** Width of the sliding window in milliseconds. */
+    perMs: number;
+    /** Starts permitted within the window. */
+    requests: number;
+}
+/** Back-off applied to the shared gate when the upstream answers with a rate limit. */
+export interface PacerCooldownOptions {
+    /** First cooldown, doubled on each consecutive rate limit. */
+    baseMs: number;
+    /**
+     * Ceiling for both the doubling and an honored `Retry-After`, so a pathological
+     * upstream value cannot park the queue.
+     */
+    maxMs: number;
+}
+/** Configuration for {@link createPacer}. */
+export interface PacerOptions {
+    /** Shared 429 gate. Omitted, an upstream rate limit paces nothing by itself. */
+    cooldown?: PacerCooldownOptions;
+    /** Sliding start-rate windows. Every entry must allow a start. */
+    limits?: PacerLimit[];
+    /** In-flight ceiling. Unset, only the windows and the start gap bind. */
+    maxConcurrent?: number;
+    /**
+     * Absolute backpressure on queue length, for callers that pass no
+     * `maxWaitMs`. An arrival past it is shed at once.
+     */
+    maxQueueDepth?: number;
+    /**
+     * Minimum spacing between consecutive starts. Not expressible through
+     * {@link PacerOptions.limits} once a window admits more than one request:
+     * `{ requests: 10, perMs: 1000 }` permits ten starts in the same millisecond,
+     * which is exactly the burst the SEC and NCBI clients space out by hand.
+     */
+    minStartGapMs?: number;
+    /**
+     * Author-set label for telemetry attribution. Bounded and never
+     * caller-supplied — a metric attribute set lives until process restart.
+     */
+    name: string;
+}
+/** Per-call options for {@link Pacer.run}. */
+export interface PacerRunOptions {
+    /**
+     * Ceiling on queue time — not on the task, which bounds itself. Enqueue
+     * rejects when the projected wait already exceeds it, and a still-queued entry
+     * rejects when it elapses.
+     */
+    maxWaitMs?: number;
+    /**
+     * Caller cancellation. While queued, an abort removes the entry and rejects
+     * with `signal.reason`; once dispatched the signal is the task's own to honor,
+     * and it is what {@link Pacer.run} hands the task.
+     */
+    signal?: AbortSignal;
+}
+/** A queue in front of one upstream. Process-local; timers and `AbortSignal` only. */
+export interface Pacer extends Disposable {
+    /**
+     * Clears the dispatch timer and rejects every queued waiter with
+     * `RequestCancelled`. In-flight tasks are left to finish. Idempotent; wire it
+     * through `createApp({ teardown })`.
+     */
+    dispose(): void;
+    /**
+     * Queues `task` and runs it once a slot opens, handing it the caller's signal.
+     *
+     * @throws {McpError} `RateLimited` with `data.reason: 'pacer_shed'` when no
+     *   slot fits the caller's wait budget or the queue is at capacity.
+     */
+    run<T>(task: (signal: AbortSignal) => Promise<T>, options?: PacerRunOptions): Promise<T>;
+}
+/**
+ * Creates a FIFO pacer for one upstream.
+ *
+ * A slot is granted when every {@link PacerOptions.limits} window,
+ * {@link PacerOptions.minStartGapMs}, {@link PacerOptions.maxConcurrent}, and the
+ * cooldown gate allow it. Each window is a sliding view over recorded *start*
+ * times, so a slow response never widens the rate the upstream sees.
+ *
+ * **Composition with `withRetry`.** Retry outside, pacer inside —
+ * `withRetry(({ signal }) => pacer.run(fn, { signal }), { signal, deadlineMs })` —
+ * so each attempt re-queues and is re-paced. The cooldown gate is an absolute
+ * instant rather than a duration counted from dequeue, so `withRetry`'s
+ * `Retry-After` sleep and the gate overlap in wall-clock instead of summing: the
+ * caller waits the window the upstream named once, not twice. Pass the retry
+ * deadline's signal into `run` and the queue wait is charged to the same budget.
+ *
+ * **Runtime.** Process-local, so on Workers the limits bind per isolate, OTel is
+ * off and the metrics are inert, and `createWorkerHandler` accepts no `teardown`
+ * to call {@link Pacer.dispose} from.
+ *
+ * @example
+ * ```ts
+ * const pacer = createPacer({
+ *   name: 'courtlistener',
+ *   limits: [{ requests: 5, perMs: 60_000 }, { requests: 50, perMs: 3_600_000 }],
+ *   minStartGapMs: 100,
+ *   maxConcurrent: 2,
+ *   maxQueueDepth: 100,
+ *   cooldown: { baseMs: 5_000, maxMs: 60_000 },
+ * });
+ *
+ * const res = await pacer.run(
+ *   (signal) => fetchWithTimeout(url, 30_000, ctx, { signal }),
+ *   { signal: ctx.signal, maxWaitMs: 45_000 },
+ * );
+ * ```
+ */
+export declare function createPacer(options: PacerOptions): Pacer;
+//# sourceMappingURL=pacer.d.ts.map

package/dist/utils/network/pacer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pacer.d.ts","sourceRoot":"","sources":["../../../src/utils/network/pacer.ts"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,kEAAkE;IAClE,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,sFAAsF;AACtF,MAAM,WAAW,KAAM,SAAQ,UAAU;IACvC;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAC;IAChB;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC1F;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CAmQxD"}

package/dist/utils/network/pacer.js

@@ -0,0 +1,304 @@
+/**
+ * @fileoverview Outbound request pacer — a FIFO queue in front of a rate-limited
+ * upstream. Holds work back until every configured window, the minimum start gap,
+ * and the concurrency cap allow it; sheds callers whose wait budget cannot be met;
+ * and closes a shared cooldown gate when the upstream answers 429.
+ *
+ * The inbound `RateLimiter` (`utils/security`) is the mirror image: it is keyed
+ * per caller and rejects synchronously, so it cannot queue work against an
+ * upstream budget.
+ * @module src/utils/network/pacer
+ */
+import { JsonRpcErrorCode, McpError, rateLimited, requestCancelled, } from '../../types-global/errors.js';
+import { parseRetryAfterMs } from './retry.js';
+import { ATTR_MCP_PACER_NAME } from '../telemetry/attributes.js';
+import { createCounter, createHistogram, createUpDownCounter } from '../telemetry/metrics.js';
+let instruments;
+/**
+ * The four pacer instruments, shared across every pacer in the process and told
+ * apart by `mcp.pacer.name`. Lazy: a server that never queues emits no series.
+ */
+function getPacerMetrics() {
+    instruments ??= {
+        cooldowns: createCounter('mcp.pacer.cooldowns', 'Cooldown gates closed by an upstream rate limit', '{cooldowns}'),
+        queueDepth: createUpDownCounter('mcp.pacer.queue_depth', 'Requests waiting for a pacer slot', '{requests}'),
+        sheds: createCounter('mcp.pacer.sheds', 'Requests shed before dispatch because no slot fit the wait budget', '{requests}'),
+        wait: createHistogram('mcp.pacer.wait', 'Time a request spent waiting for a pacer slot', 'ms'),
+    };
+    return instruments;
+}
+/**
+ * Creates a FIFO pacer for one upstream.
+ *
+ * A slot is granted when every {@link PacerOptions.limits} window,
+ * {@link PacerOptions.minStartGapMs}, {@link PacerOptions.maxConcurrent}, and the
+ * cooldown gate allow it. Each window is a sliding view over recorded *start*
+ * times, so a slow response never widens the rate the upstream sees.
+ *
+ * **Composition with `withRetry`.** Retry outside, pacer inside —
+ * `withRetry(({ signal }) => pacer.run(fn, { signal }), { signal, deadlineMs })` —
+ * so each attempt re-queues and is re-paced. The cooldown gate is an absolute
+ * instant rather than a duration counted from dequeue, so `withRetry`'s
+ * `Retry-After` sleep and the gate overlap in wall-clock instead of summing: the
+ * caller waits the window the upstream named once, not twice. Pass the retry
+ * deadline's signal into `run` and the queue wait is charged to the same budget.
+ *
+ * **Runtime.** Process-local, so on Workers the limits bind per isolate, OTel is
+ * off and the metrics are inert, and `createWorkerHandler` accepts no `teardown`
+ * to call {@link Pacer.dispose} from.
+ *
+ * @example
+ * ```ts
+ * const pacer = createPacer({
+ *   name: 'courtlistener',
+ *   limits: [{ requests: 5, perMs: 60_000 }, { requests: 50, perMs: 3_600_000 }],
+ *   minStartGapMs: 100,
+ *   maxConcurrent: 2,
+ *   maxQueueDepth: 100,
+ *   cooldown: { baseMs: 5_000, maxMs: 60_000 },
+ * });
+ *
+ * const res = await pacer.run(
+ *   (signal) => fetchWithTimeout(url, 30_000, ctx, { signal }),
+ *   { signal: ctx.signal, maxWaitMs: 45_000 },
+ * );
+ * ```
+ */
+export function createPacer(options) {
+    const { cooldown, limits = [], maxConcurrent, maxQueueDepth, minStartGapMs = 0, name } = options;
+    const attributes = { [ATTR_MCP_PACER_NAME]: name };
+    /** Recorded start instants, ascending. Pruned to the longest constraint. */
+    const starts = [];
+    const retentionMs = Math.max(minStartGapMs, ...limits.map((limit) => limit.perMs), 0);
+    const queue = [];
+    let active = 0;
+    let consecutiveRateLimits = 0;
+    /** Absolute instant the shared gate reopens. */
+    let gateOpensAt = 0;
+    let dispatchTimer;
+    let disposed = false;
+    /**
+     * The earliest instant a start is permitted given `history`, evaluated at
+     * `at`. Exact over the cooldown gate, the start gap, and every window —
+     * concurrency is deliberately not modelled here, since a slot frees on an
+     * unknowable completion.
+     */
+    function earliestStart(history, at) {
+        let earliest = gateOpensAt;
+        const last = history[history.length - 1];
+        if (last !== undefined && minStartGapMs > 0) {
+            earliest = Math.max(earliest, last + minStartGapMs);
+        }
+        for (const { requests, perMs } of limits) {
+            if (requests <= 0)
+                continue;
+            let seen = 0;
+            for (let i = history.length - 1; i >= 0; i--) {
+                const start = history[i];
+                // A start exactly `perMs` old has already left the window.
+                if (start <= at - perMs)
+                    break;
+                seen++;
+                if (seen === requests) {
+                    earliest = Math.max(earliest, start + perMs);
+                    break;
+                }
+            }
+        }
+        return earliest;
+    }
+    /**
+     * When an arrival joining behind `ahead` waiters could start, by replaying the
+     * windows forward. Exact while only the windows and the gap bind; a lower
+     * bound once `maxConcurrent` does — which is what keeps a shed from ever being
+     * a false one.
+     */
+    function projectedStart(now, ahead) {
+        const simulated = starts.slice();
+        let at = now;
+        for (let i = 0; i <= ahead; i++) {
+            at = Math.max(at, earliestStart(simulated, at));
+            simulated.push(at);
+        }
+        return at;
+    }
+    /** Seconds until a slot opens, for the shed error's `retryAfter`. */
+    function secondsUntilSlot(now, ahead) {
+        return Math.ceil(Math.max(0, projectedStart(now, ahead) - now) / 1000);
+    }
+    /**
+     * The shed error. `rateLimited` with no `retryable: false`: to the calling
+     * agent this is an ordinary rate limit — wait `retryAfter`, call again — and
+     * that flag would tell them the opposite. `withRetry`'s default predicate
+     * reads `reason` instead, so an enclosing retry fails fast rather than
+     * sleeping past the deadline the shed exists to enforce.
+     */
+    function shed(retryAfter, queueDepth) {
+        getPacerMetrics().sheds.add(1, attributes);
+        return rateLimited(`No ${name} request slot available within the caller's wait budget.`, {
+            reason: 'pacer_shed',
+            retryAfter,
+            queueDepth,
+        });
+    }
+    /**
+     * Releases an entry that has left the queue: clears its shed timer and abort
+     * listener, and settles the depth gauge. Leaving the line and the gauge are
+     * the same event, so every exit — dequeued, removed, disposed — goes through
+     * here.
+     */
+    function detach(entry) {
+        if (entry.shedTimer !== undefined) {
+            clearTimeout(entry.shedTimer);
+            entry.shedTimer = undefined;
+        }
+        if (entry.onAbort && entry.signal) {
+            entry.signal.removeEventListener('abort', entry.onAbort);
+            entry.onAbort = undefined;
+        }
+        getPacerMetrics().queueDepth.add(-1, attributes);
+    }
+    /** Removes a waiter and settles the depth gauge. `false` if it already left. */
+    function remove(entry) {
+        const index = queue.indexOf(entry);
+        if (index === -1)
+            return false;
+        queue.splice(index, 1);
+        detach(entry);
+        return true;
+    }
+    function clearDispatchTimer() {
+        if (dispatchTimer === undefined)
+            return;
+        clearTimeout(dispatchTimer);
+        dispatchTimer = undefined;
+    }
+    /**
+     * Drains as much of the queue as the constraints allow, then either arms the
+     * dispatch timer for the next opening or leaves no timer at all. FIFO: only
+     * the head is ever considered, so a cheap arrival never overtakes.
+     */
+    function pump() {
+        clearDispatchTimer();
+        while (queue.length > 0) {
+            if (maxConcurrent !== undefined && active >= maxConcurrent)
+                return;
+            const now = Date.now();
+            const earliest = earliestStart(starts, now);
+            if (earliest > now) {
+                dispatchTimer = setTimeout(() => {
+                    dispatchTimer = undefined;
+                    pump();
+                }, earliest - now);
+                dispatchTimer.unref?.();
+                return;
+            }
+            const entry = queue.shift();
+            if (!entry)
+                return;
+            detach(entry);
+            starts.push(now);
+            while (starts.length > 0 && starts[0] <= now - retentionMs)
+                starts.shift();
+            entry.dispatch(now);
+        }
+    }
+    /**
+     * Closes the shared gate on an upstream rate limit:
+     * `min(max(baseMs · 2^(consecutive−1), retryAfter), maxMs)`, as an absolute
+     * instant. Any other error leaves it open; the first success resets the count.
+     */
+    function noteRateLimit(error) {
+        if (!cooldown)
+            return;
+        if (!(error instanceof McpError) || error.code !== JsonRpcErrorCode.RateLimited)
+            return;
+        consecutiveRateLimits++;
+        const doubled = cooldown.baseMs * 2 ** (consecutiveRateLimits - 1);
+        // An absent or unparseable hint contributes nothing, leaving the doubling.
+        const honored = parseRetryAfterMs(error) ?? 0;
+        const waitMs = Math.min(Math.max(doubled, honored), cooldown.maxMs);
+        gateOpensAt = Math.max(gateOpensAt, Date.now() + waitMs);
+        getPacerMetrics().cooldowns.add(1, attributes);
+    }
+    function run(task, runOptions = {}) {
+        const { maxWaitMs, signal } = runOptions;
+        if (disposed) {
+            return Promise.reject(requestCancelled(`The ${name} pacer has been disposed.`));
+        }
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        const now = Date.now();
+        const ahead = queue.length;
+        // Absolute backpressure first, so it rejects without arming a timer.
+        if (maxQueueDepth !== undefined && ahead >= maxQueueDepth) {
+            return Promise.reject(shed(secondsUntilSlot(now, ahead), ahead));
+        }
+        if (maxWaitMs !== undefined && projectedStart(now, ahead) - now > maxWaitMs) {
+            return Promise.reject(shed(secondsUntilSlot(now, ahead), ahead));
+        }
+        return new Promise((resolve, reject) => {
+            const entry = {
+                enqueuedAt: now,
+                reject,
+                signal,
+                dispatch: (startedAt) => {
+                    active++;
+                    getPacerMetrics().wait.record(startedAt - entry.enqueuedAt, attributes);
+                    // Called inside an async wrapper so a task that throws before returning
+                    // a promise rejects its own caller instead of escaping into `pump()`.
+                    void (async () => task(signal ?? new AbortController().signal))().then((value) => {
+                        consecutiveRateLimits = 0;
+                        resolve(value);
+                        active--;
+                        pump();
+                    }, (error) => {
+                        noteRateLimit(error);
+                        reject(error);
+                        active--;
+                        pump();
+                    });
+                },
+            };
+            if (maxWaitMs !== undefined) {
+                entry.shedTimer = setTimeout(() => {
+                    entry.shedTimer = undefined;
+                    if (!remove(entry))
+                        return;
+                    reject(shed(secondsUntilSlot(Date.now(), 0), queue.length));
+                    // The shed entry is gone; whoever is behind it should not wait on it.
+                    pump();
+                }, maxWaitMs);
+                entry.shedTimer.unref?.();
+            }
+            if (signal) {
+                entry.onAbort = () => {
+                    if (!remove(entry))
+                        return;
+                    reject(signal.reason);
+                    pump();
+                };
+                signal.addEventListener('abort', entry.onAbort, { once: true });
+            }
+            queue.push(entry);
+            getPacerMetrics().queueDepth.add(1, attributes);
+            pump();
+        });
+    }
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        clearDispatchTimer();
+        for (const entry of queue.splice(0, queue.length)) {
+            detach(entry);
+            entry.reject(requestCancelled(`The ${name} pacer has been disposed.`));
+        }
+    }
+    return {
+        dispose,
+        run,
+        [Symbol.dispose]: dispose,
+    };
+}
+//# sourceMappingURL=pacer.js.map