@basein/runner 0.2.11 → 0.3.0

package/dist/upstream/http-client.d.ts

@@ -11,18 +11,68 @@
  *     message is a POST to one endpoint. The reply comes back as a JSON body or
  *     as an SSE stream carrying it. A session id handed out in the
  *     `Mcp-Session-Id` response header must be echoed on every later request.
- *     Server-initiated messages arrive on a standing GET stream, opened lazily
- *     after `initialize` and skipped when the server answers 405.
+ *     Server-initiated messages arrive on a standing GET stream, opened once the
+ *     handshake is done and skipped when the server answers 405.
  *   - **legacy SSE** (`--transport sse`): a long-lived GET carries every reply
  *     and announces the POST endpoint with an `endpoint` event, so the handshake
  *     is inverted — you must be listening before you can send.
  *
+ * THE RULES THIS FILE KEEPS, because a wrapped server must behave at least as
+ * well as the same server connected directly:
+ *
+ *   1. **Every request the host sends is answered.** A network error, a non-2xx,
+ *      an HTML page from an SSO or captive proxy, a body that is not the
+ *      JSON-RPC answer, an SSE reply that ends or resets before the answer, an
+ *      answer over the size cap, a legacy event stream that drops with requests
+ *      in flight — each becomes a short, fixed JSON-RPC error for that id. The
+ *      upstream's body is never echoed (it can be a login page or carry gateway
+ *      internals), and 401/403 say "requires sign-in" rather than dumping HTML.
+ *   2. **Only the handshake is ordered.** `initialize` and then
+ *      `notifications/initialized` go one after the other (the session id comes
+ *      back on the first, and Python-SDK servers refuse traffic before the
+ *      second). Every later POST is independent, as in the MCP SDK the host
+ *      would otherwise use: parallel tool calls run in parallel, a
+ *      `notifications/cancelled` is not queued behind the call it cancels, and
+ *      the host's answer to a server-initiated request (roots, elicitation,
+ *      sampling) is never stuck behind the very tool call waiting for it —
+ *      which, serialised, was a deadlock.
+ *   3. **Legacy SSE sends wait for the endpoint.** Nothing is POSTed until the
+ *      stream has announced where to POST (sent to the GET URL, the host's
+ *      `initialize` got a 405 and the server showed as failed every session).
+ *      A stream that ends — cleanly or not — is noticed, the requests riding it
+ *      are answered, and it is re-established with backoff; the new session is
+ *      re-initialised with the host's own `initialize` before anything else.
+ *   4. **Session expiry is survivable.** A 404 to a request that carried a
+ *      session means the server forgot us (a redeploy, an idle timeout). The
+ *      spec says start a new session; the proxy does it for the host — replays
+ *      the host's cached `initialize` under a `bir:` id, sends `initialized`,
+ *      and retries the request once.
+ *   5. **No timeout shorter than the host's.** The transport (http-transport.ts)
+ *      bounds the connect only; how long a tool may take is Claude Code's call,
+ *      and its cancellation reaches the server immediately (rule 2). What no
+ *      host waits on is bounded here instead, so nothing holds a connection
+ *      forever: the proxy's own calls (a replayed scenario step) are cancelled
+ *      upstream when their caller gives up, and a notification or response the
+ *      server has not answered in 60 s is dropped.
+ *
  * AUTH (§9). The host's own OAuth authenticates the server it is *configured*
  * with, which is now the proxy — so a remote upstream's credentials have to
  * reach us some other way. They come from `--header` / the environment at spawn
- * time and are held in memory only; nothing is written to disk here.
+ * time and are held in memory only; nothing is written to disk here. They are
+ * sent only to the configured origin: a legacy `endpoint` elsewhere is refused
+ * (as the MCP SDK does), a redirect off-origin drops every one of them, and a
+ * redirect from https to plain http is refused (http-transport.ts).
+ *
+ * STDERR IS FOR NEWS. Claude Code files every stderr line of bir-proxy as a
+ * "Server stderr" error, so what a remote server does routinely — a load
+ * balancer cutting an idle event stream every minute or two (60 s on an AWS
+ * ALB, 100 s on Cloudflare), and the reconnect and re-initialise that follow —
+ * is `BIR_VERBOSE` detail. What stays on stderr: requests answered with an
+ * error because a stream was lost, the first failure of an outage and its
+ * recovery, a session the server forgot, and a stream that keeps dropping as
+ * soon as it opens (once an hour per server at most).
  */
-import type { JsonRpcMessage } from "../jsonrpc/types.js";
+import { type JsonRpcMessage } from "../jsonrpc/types.js";
 import { BaseUpstreamClient } from "./client.js";
 import { Readable } from "node:stream";
 export interface HttpUpstreamOptions {
@@ -32,42 +82,183 @@ export interface HttpUpstreamOptions {
     /** Extra headers (auth, tenancy) sent on every request. */
     headers?: Record<string, string>;
     label?: string;
-    /** How long to wait for the SSE `endpoint` announcement. Default 15s. */
+    /**
+     * Legacy SSE: how long the whole connect may take — response headers *and*
+     * the `endpoint` announcement. Default 15 s. Also bounds waiting for the
+     * answer to a replayed `initialize`.
+     */
     connectTimeoutMs?: number;
+    /**
+     * Every request: DNS + TCP + TLS must finish within this. Default 10 s;
+     * `BIR_UPSTREAM_CONNECT_TIMEOUT_MS` overrides. Nothing bounds the answer.
+     */
+    socketConnectTimeoutMs?: number;
+    /** First delay before re-opening a dropped SSE stream; doubles to 30 s. Default 500 ms. */
+    reconnectBaseMs?: number;
+    /**
+     * Largest single answer (a JSON body, one SSE event). Default 128 MiB;
+     * `BIR_UPSTREAM_MAX_MESSAGE_BYTES` overrides.
+     */
+    maxMessageBytes?: number;
+    /** How long an idle pooled socket is kept. Default 4 s (see http-transport.ts). */
+    idleSocketTimeoutMs?: number;
+    /**
+     * A POST nothing waits on (a notification, the host's answer to a server
+     * request) is abandoned if the server has not finished answering it in this
+     * long. Default 60 s.
+     */
+    unansweredPostTimeoutMs?: number;
+    /**
+     * An event stream (the standing GET, the legacy stream) that stayed up this
+     * long was healthy: its drop restarts the backoff and is routine, not news.
+     * Default 60 s. Tests shorten it.
+     */
+    healthyStreamMs?: number;
 }
 export declare class HttpUpstreamClient extends BaseUpstreamClient {
     readonly ready: Promise<void>;
     private readonly url;
+    private readonly origin;
     private readonly transport;
     private readonly headers;
     private readonly label;
     private readonly connectTimeoutMs;
+    private readonly socketConnectTimeoutMs;
+    private readonly reconnectBaseMs;
+    private readonly maxMessageBytes;
+    private readonly unansweredPostTimeoutMs;
+    private readonly healthyStreamMs;
+    private readonly agents;
     private sessionId?;
-    /** Legacy SSE only: where to POST, announced by the stream's `endpoint` event. */
+    /** Negotiated in `initialize`, echoed as `MCP-Protocol-Version` afterwards. */
+    private protocolVersion?;
+    /** The host's `initialize` params, replayed when the server loses our session. */
+    private initParams?;
+    private hostInitId?;
+    private reinitCount;
+    /**
+     * The handshake gate. `initialize` and `notifications/initialized` chain onto
+     * it; every other message waits for it and then goes on its own (rule 2).
+     */
+    private gate;
+    private recovery?;
+    private readonly outstanding;
+    /** Every in-flight POST's aborter, so close() can drop them all. */
+    private readonly inflight;
+    /** Answers to this client's own replayed `initialize`, consumed before the relay. */
+    private readonly internalWaiters;
+    /** Where to POST, announced by the stream's `endpoint` event. Unset while down. */
     private postUrl?;
-    private readonly abort;
-    /** Serialises POSTs so messages leave in the order the host sent them. */
-    private chain;
-    private standingStreamOpened;
+    /** Bumped per announced stream; a request's answer can only ride the stream it was posted on. */
+    private generation;
+    private streamAbort?;
+    private connecting?;
+    private reconnectTimer?;
+    private reconnectFailures;
+    /** Streams that ended soon after connecting, in a row: they back off like failures. */
+    private streamDrops;
+    private streamOpenedAt;
+    private standing;
+    private standingAbort?;
+    private standingTimer?;
+    private standingDrops;
+    private standingLastEventId?;
+    private standingRetryMs?;
+    private standingParser?;
     constructor(opts: HttpUpstreamOptions);
-    private connect;
+    send(msg: JsonRpcMessage): void;
+    /** Never rejects: whatever goes wrong, a request still gets its answer. */
+    private postMessage;
+    private postOnce;
+    /** A JSON (or unexpected) reply body. Whatever it holds, the request gets an answer. */
+    private readReply;
+    /** A reply delivered as an SSE body. If it ends before the answer, answer anyway. */
+    private pumpReply;
+    /** Parse one inbound payload (a body or an SSE event). False if it was not JSON. */
+    private dispatchData;
+    /** Hand one inbound JSON-RPC message to the relay (or to a `bir:` waiter). */
+    private deliver;
+    /** Answer a request ourselves, once, unless the host no longer wants it. */
+    private answerError;
+    private noteProtocolVersion;
+    private handlerFailed;
+    /**
+     * The server refused the handshake for want of credentials. Said once per
+     * server, as `upstream.auth_required`, so `bir doctor` can explain a remote
+     * server that was wrapped without the headers it needs (an opt-in remote
+     * entry whose sign-in only the host could do) instead of "it fails".
+     */
+    private noteAuthRequired;
+    /**
+     * The server answered 404 to a request sent on session `staleKey`. Start a
+     * new session once, however many requests noticed at the same moment, and
+     * hold new traffic until it exists. Resolves true when a retry makes sense.
+     */
+    private recoverSession;
+    /** Which session a POST speaks for: the session id, or the legacy stream generation. */
+    private sessionKey;
+    /**
+     * Replay the host's `initialize` (under a `bir:` id) and `initialized`.
+     * `news`: say it on stderr when it worked — after a forgotten session or an
+     * outage; after a routine reconnect it is detail. A failure is always said.
+     */
+    private reinitialize;
+    /**
+     * Open the event stream and resolve once it has announced its endpoint. The
+     * whole connect — response headers included — is bounded by
+     * `connectTimeoutMs`: a server that never sent headers used to hold `ready`
+     * for fetch's 300 s, far past the host's own MCP connect timeout.
+     */
     private openSseEndpointStream;
     /**
-     * Streamable HTTP: open the standing GET stream that carries server-initiated
-     * requests (`sampling/createMessage`, `elicitation/create`, list-changed
-     * notifications). A 405 means this server does not offer one — normal, and not
-     * an error: everything it sends will ride the POST responses instead.
+     * The stream a set of requests was answered on is gone. Their answers can
+     * never arrive (a new stream is a new session), so answer them now.
+     *
+     * Said on stderr when that cost the host an answer. Otherwise `routine`
+     * (a healthy stream's idle cut, a drop a recovery already said) is detail,
+     * and anything else — a stream that dropped soon after it opened — is said
+     * once an hour per server at most.
+     */
+    private onSseStreamLost;
+    /** Legacy: is there an endpoint to POST to? Waits for one reconnect attempt at most. */
+    private ensureStream;
+    /**
+     * One reconnect attempt (shared by everyone who asks meanwhile). A host
+     * request that arrives while the stream is down pulls the next attempt
+     * forward rather than waiting out the backoff, and gets an error — not a
+     * hang — if that attempt fails.
+     *
+     * `afterExpiry`: the server forgot the session (a 404), which is worth a
+     * line when the new one is initialised. A routine reconnect that works at
+     * the first try is detail; one that ends an outage is said.
+     */
+    private reconnect;
+    private scheduleReconnect;
+    /**
+     * Open the standing GET stream that carries server-initiated requests
+     * (`sampling/createMessage`, `elicitation/create`, list-changed
+     * notifications). A 405 means this server does not offer one — normal, and
+     * not an error: everything it sends will ride the POST responses instead.
+     * When it drops it is re-opened with backoff (with `Last-Event-ID` when the
+     * server numbers its events), so a load balancer's idle cut does not silently
+     * lose every later list-changed or elicitation.
      */
     private openStandingStream;
-    /** Read an SSE body, calling `onEvent(eventName, data)` per complete event. */
-    private pumpSse;
-    /** Hand one inbound JSON-RPC payload to the relay (or to a `bir:` waiter). */
-    private dispatch;
-    private target;
+    /** The standing stream is not open: anything that was promised an answer on it gets one now. */
+    private standingDown;
+    private scheduleStandingReopen;
+    /** A new session is starting: the old standing stream belongs to the old one. */
+    private resetStandingStream;
+    private call;
     private sessionHeaders;
-    send(msg: JsonRpcMessage): void;
-    private post;
+    /**
+     * A network failure with a proxy configured that this process cannot use is
+     * the likeliest cause; say so once in the audit log (`bir doctor` reads it).
+     */
+    private proxyHint;
     close(): void;
+    /** Stop every timer, stream and request; end the server-side session if there is one. */
+    private teardown;
 }
 /**
  * Adapt a Node stream of newline-delimited JSON into the message callback shape,