@mcpwarp/ws-mixer 0.6.0

package/dist/client.d.ts

@@ -0,0 +1,453 @@
+/**
+ * Public client entry point: `connect(url, opts)`. Owns the WebSocket
+ * handshake (subprotocol, headers, size limits), and the reconnect/backoff
+ * policy from docs/research/2026-08-26-control-channel-and-connection-lifecycle.md
+ * and WIRE.md section 2.9's reconnect table. `MixerConn` (conn.ts) owns
+ * everything about one already-connected socket; this file owns the loop
+ * that replaces it.
+ *
+ * State machine (single source of truth for "are we allowed to dial /
+ * reconnect right now"): idle -> dialing -> connected -> backoff -> ...,
+ * terminating in closed (either `close()` was called, a fatal close code
+ * was hit, or maxAttempts was exhausted). `dialing` and `backoff` both loop
+ * back to `dialing` on success; every terminal transition happens exactly
+ * once, in `terminal()`/`goFatal()`/`giveUp()`.
+ */
+import { EventEmitter } from "node:events";
+import type { AgentInfo, DrainMsg, WelcomeMsg } from "./control.js";
+import { WsMixerError } from "./errors.js";
+import { MixerConn, type WSLike } from "./conn.js";
+import type { MixerStream } from "./stream.js";
+export declare const SUBPROTOCOL = "ws-mixer.v1";
+export declare const SDK_VERSION = "0.6.0";
+export type ClientState = "idle" | "dialing" | "connected" | "backoff" | "closed";
+export interface ReconnectOptions {
+    /** Base delay for exponential backoff, ms. Default 1000. */
+    base?: number;
+    /** Backoff cap, ms. Default 60000. */
+    cap?: number;
+    /** Per-attempt connect timeout, ms. Default 10000. */
+    connectTimeout?: number;
+    /**
+     * Max reconnect attempts before giving up. Default Infinity. Counts
+     * consecutive reconnects *without a stable connection in between*
+     * (`stableAfter` below) -- since `attempt` itself only resets at
+     * stability now, a server that welcomes and then always disconnects
+     * before a connection ever proves stable exhausts this ceiling and goes
+     * fatal exactly like a server that never welcomes at all.
+     */
+    maxAttempts?: number;
+    /**
+     * How long (ms) a connection must stay up past `welcome` before it's
+     * considered stable (WIRE.md section 2.9's `stable`). The backoff attempt
+     * counter, and every once-only retry budget re-armed alongside it (e.g.
+     * 4013 KEEPALIVE_TIMEOUT's one immediate retry, and the one-time
+     * token-provider refresh-retry for a pre-welcome auth rejection), are
+     * reset only once a connection has stayed up this long -- not on
+     * `welcome` itself -- so a server that welcomes and then immediately
+     * closes can't reset them every cycle and turn backoff (or a refresh-retry
+     * loop against the token endpoint) into a redial-roughly-once-a-second
+     * loop forever. Default 10000.
+     */
+    stableAfter?: number;
+}
+/** Structural subset of `ws`'s WebSocket needed during the dial (before a MixerConn exists). Lets tests inject a fake transport via `_wsFactory`. */
+/**
+ * Structural subset of Node's `http.ClientRequest`, as seen on `ws`'s
+ * `unexpected-response` event. `ws` only calls its own `abortHandshake`
+ * cleanup when nothing is listening for `unexpected-response` -- since this
+ * SDK does listen (to read `statusCode`/`Retry-After`), it owns draining and
+ * destroying `req`/`res` itself, or the request/socket leaks.
+ */
+export interface DialRequest {
+    destroy?(err?: Error): void;
+}
+/** Structural subset of Node's `http.IncomingMessage`, as seen on `ws`'s `unexpected-response` event. */
+export interface DialResponse {
+    statusCode?: number;
+    headers: Record<string, string | string[] | undefined>;
+    resume?(): void;
+    destroy?(err?: Error): void;
+}
+export interface DialSocket extends WSLike {
+    readonly protocol: string;
+    once(event: "open", listener: () => void): this;
+    once(event: "unexpected-response", listener: (req: DialRequest, res: DialResponse) => void): this;
+    once(event: "error", listener: (err: Error) => void): this;
+}
+export interface WSFactoryOptions {
+    perMessageDeflate: boolean;
+    maxPayload: number;
+    headers: Record<string, string>;
+}
+/** Test-only dial hook: replaces `new WebSocket(url, [SUBPROTOCOL], options)`. */
+export type WSFactory = (url: string, protocols: string[], options: WSFactoryOptions) => DialSocket;
+/**
+ * A ws-mixer token: either a static string or a callback returning a fresh
+ * token (sync or `Promise`). Per CLIENT-SDK.md's "Token provider" and "Provider failure" rows, the callback MUST
+ * be invoked on every dial, never cached across reconnects, and a
+ * throw/rejection is fatal -- surfaced verbatim as `DisconnectReason.cause` --
+ * UNLESS it's a `TokenUnavailableError` (thrown directly, or reachable by
+ * following `.cause`): that marks a temporary failure to OBTAIN a token
+ * (network still down, auth server briefly unreachable) and is instead
+ * treated like a failed dial -- normal backoff, no fatal.
+ */
+export type TokenProvider = string | (() => Promise<string> | string);
+/** Where a disconnect originated, per CLIENT-SDK.md's "Disconnect reason shape" row. */
+export type DisconnectPhase = "dial" | "handshake" | "connected";
+/**
+ * The shape every disconnect (recoverable or fatal) is reported with, per
+ * CLIENT-SDK.md's "Disconnect reason shape" row. `httpStatus` is set only for a dial failure whose
+ * response was an HTTP status (401/403/404/429); `cause` is set only when a
+ * token provider threw/rejected.
+ */
+export interface DisconnectReason {
+    phase: DisconnectPhase;
+    /**
+     * The WebSocket close code, when a WS close occurred. When derived from a
+     * ws-mixer error (this side's own `WsMixerError`/`ConnError`, or a peer's
+     * `error{code}`), this is always the semantic `4000+error_code` -- for an
+     * `error_code` outside the legal WS close range (>= 0x1000_0000, an
+     * application-layer code that is legal for a stream RESET but never was
+     * for a connection close), that can differ from the *actual* bytes this
+     * side puts on the wire, which are clamped to `4000+INTERNAL_ERROR` (4002)
+     * instead (conn.ts's `wireCloseCode`, mirroring go/wsmixer's
+     * `wsCloseCode`) -- `errorCode` always keeps the real, unclamped code
+     * either way. When instead observed directly from a bare close frame
+     * (`onSocketClose`, no preceding `error{}`), `wsCode` is exactly what was
+     * on the wire, since there is nothing else it could be.
+     */
+    wsCode?: number;
+    errorCode?: number;
+    errorName?: string;
+    httpStatus?: number;
+    fatal: boolean;
+    message: string;
+    /**
+     * The reason field of the close frame *received from the peer*, verbatim
+     * -- never this side's own outgoing reason (CLIENT-SDK.md's `closeReason`
+     * row). Absent or empty whenever no reason was received from the peer:
+     * this includes an abnormal closure (no close frame at all), this side
+     * having initiated the close itself (a peer's echo carries no information
+     * and RFC 6455 doesn't require it to copy the reason), and the SDK closing
+     * on a peer's `error{}` without reading whatever close frame follows it,
+     * as WIRE.md section 2.7 allows ("logs, surfaces and closes"). The
+     * human-readable text is in `message` for all of those cases instead --
+     * consumers SHOULD prefer `closeReason` and fall back to `message`.
+     */
+    closeReason?: string;
+    cause?: unknown;
+}
+/**
+ * The actual runtime payload for every disconnect: `DisconnectReason` plus
+ * the pre-existing loud "SDK bug" fields (item 7) for a protocol-bug close
+ * (4001/4003/4004) -- kept alongside `errorCode`/`errorName` rather than
+ * replacing them, so existing `protocolError`/`code`/`name` consumers keep
+ * working.
+ */
+export type DisconnectPayload = DisconnectReason & ({
+    protocolError: true;
+    code: number;
+    name: string;
+} | {
+    protocolError?: false;
+});
+export interface ConnectOptions {
+    token: TokenProvider;
+    meta?: unknown;
+    agent?: Partial<AgentInfo>;
+    window?: number;
+    maxStreams?: number;
+    capabilities?: string[];
+    headers?: Record<string, string>;
+    /**
+     * Delivered, along with `onApp`/`onDrain`, in wire order from one delivery
+     * loop per connection, one at a time -- never concurrently with each other
+     * or with themselves (CLIENT-SDK.md's "Handler delivery" row). An event
+     * already received when the connection ends is still owed to this
+     * callback: it MAY therefore still fire shortly after `close()`/
+     * `close({message})`'s own promise has resolved, for a stream/message/drain
+     * that arrived before whatever ended the connection.
+     */
+    onStream?: (stream: MixerStream) => void;
+    /** See `onStream`'s doc comment: same wire-order/post-close-flush guarantees. */
+    onApp?: (body: Record<string, unknown>) => void;
+    /** See `onStream`'s doc comment: same wire-order/post-close-flush guarantees. */
+    onDrain?: (msg: {
+        reason: string;
+        deadlineMs?: number;
+        message?: string;
+        lastStreamId: number;
+    }) => void;
+    onConnect?: (welcome: WelcomeMsg) => void;
+    /**
+     * Fires on every disconnect, recoverable or not (see stats() note in
+     * docs/DESIGN.md). This is the SDK's loud, always-invoked channel
+     * -- unlike `'error'`, it is not gated on a listener being attached, so a
+     * `4001`/`4003`/`4004` close (WIRE.md section 2.9: "these mean an SDK
+     * bug and a silent retry loop hides it") always reaches an `onDisconnect`
+     * the caller supplied, with `protocolError: true` plus the offending
+     * `code`/`name` to make it impossible to miss.
+     */
+    onDisconnect?: (reason: DisconnectPayload) => void;
+    reconnect?: ReconnectOptions;
+    /** Test-only: injects a fake WebSocket-like transport for the dial. Never used in production. */
+    _wsFactory?: WSFactory;
+}
+/** Options for an application-initiated `MixerClient.close()` (CLIENT-SDK.md's "Application close" row). See `close()`'s doc comment. */
+export interface CloseOptions {
+    /**
+     * The mode is chosen by presence, not value: supplying `message` (even
+     * `""`) closes the connection with `error{code: ErrorCode.APPLICATION_CLOSE,
+     * message}` then WS close `4014`, instead of the default graceful drain --
+     * WIRE.md section 2.8 makes `APPLICATION_CLOSE` the only code an
+     * application may close a *connection* with, so there is no caller-chosen
+     * code (D-2026-09-25-01). Truncated to 123 UTF-8 bytes on a character
+     * boundary for the WS close reason. Leaving `message` undefined -- `close()`
+     * or `close({})` -- takes the graceful path instead. A `code` key (e.g. a
+     * plain-JS caller still passing `{code: 14}`) makes `close()` throw a
+     * `TypeError` synchronously, with or without `message`.
+     */
+    message?: string;
+}
+export declare interface MixerClient {
+    on(event: "welcome", listener: (welcome: WelcomeMsg) => void): this;
+    on(event: "stream", listener: (stream: MixerStream) => void): this;
+    on(event: "app", listener: (body: Record<string, unknown>) => void): this;
+    on(event: "drain", listener: (msg: DrainMsg) => void): this;
+    on(event: "reconnecting", listener: (info: {
+        attempt: number;
+        delayMs: number;
+        cause: string;
+    }) => void): this;
+    on(event: "close", listener: (info: DisconnectPayload) => void): this;
+    on(event: "error", listener: (err: WsMixerError) => void): this;
+    on(event: "fatal", listener: (err: WsMixerError) => void): this;
+    on(event: "pong", listener: (info: {
+        id: number;
+        rttMs: number;
+    }) => void): this;
+}
+/**
+ * MixerClient owns the reconnect loop: it replaces `conn` with a fresh
+ * MixerConn on every disconnect, per the policy in
+ * docs/research/2026-08-26-control-channel-and-connection-lifecycle.md.
+ *
+ * In-flight streams are lost on reconnect -- there is no resumption
+ * (WIRE.md section 2.9). A handler must tell "the response ended" (EOF)
+ * from "the tunnel died" (its stream is destroyed with an error) itself;
+ * this SDK does not paper over the difference.
+ */
+export declare class MixerClient extends EventEmitter {
+    private readonly url;
+    private readonly opts;
+    private readonly reconnectOpts;
+    private state;
+    /** The confirmed-live connection (welcome received). Null while dialing/backing off. */
+    private conn;
+    /** A MixerConn mid-handshake, not yet promoted to `conn`. Tracked so close() can tear it down too. */
+    private dialingConn;
+    /**
+     * Set only while a `drain`-triggered parallel reconnect is in flight: the
+     * connection that sent `drain`, still alive and finishing in-flight
+     * streams. Torn down (fail()) as soon as its replacement's `welcome`
+     * lands, so a superseded connection never lingers past that point.
+     */
+    private retiringConn;
+    private attempt;
+    private everConnected;
+    private closing;
+    private fatal;
+    /** Set when `drain` already started a parallel reconnect, so the close that follows it doesn't schedule a second one. */
+    private drainReconnectScheduled;
+    /**
+     * Set when `drain` arrives with reconnect disabled (`maxAttempts:0`):
+     * WIRE.md section 2.9 says in-flight streams finish normally until the
+     * server's own deadline, at which point it closes with 4012 -- so the conn
+     * stays up and this flag just tells the eventual close handler to report
+     * that close as the one fatal "drained; reconnect disabled" disconnect
+     * instead of treating 4012 as an ordinary going-away reconnect trigger.
+     */
+    private drainedNoReconnect;
+    /** WIRE.md section 2.9: close 4013 gets exactly one immediate retry before falling back to normal backoff. Re-armed at stability, not at welcome -- see armStabilityTimer. */
+    private keepaliveImmediateRetryUsed;
+    /**
+     * CLIENT-SDK.md's "Rejected token" row: a pre-welcome token rejection (an HTTP 401 on
+     * the upgrade, or a handshake-phase UNAUTHORIZED/4011, with or without a
+     * preceding `error{}`) gets exactly one immediate provider refresh-retry
+     * -- ONE budget shared across both rejection shapes, and across every
+     * `connectOnce()` call, not reset on every dial/redial. Re-armed only at
+     * stability (armStabilityTimer), same as `keepaliveImmediateRetryUsed`:
+     * without that, a server that welcomes and then closes shortly after could
+     * make the client hit the token endpoint again on every single reconnect
+     * cycle forever, instead of only once per genuinely-unstable run. After a
+     * long healthy (stable) session, the budget is available again -- an
+     * ordinary token expiry on some later reconnect still gets its retry.
+     */
+    private unauthorizedRetryUsed;
+    private reconnectTimer;
+    /** Resolves connectOnce's backoff-delay await; settled directly by clearReconnectTimer() so close()/goFatal()/giveUp() during backoff don't leave that await dangling forever. */
+    private reconnectTimerResolve;
+    /**
+     * One-shot timer armed on `welcome` (armStabilityTimer): fires once the
+     * *current* conn has stayed up for `reconnectOpts.stableAfter` ms, at
+     * which point `attempt` and the once-only retry budgets it gates
+     * (`keepaliveImmediateRetryUsed`, `unauthorizedRetryUsed`) reset.
+     * `unref()`'d so it never keeps the process alive, and cleared on every
+     * path that ends a conn or the client itself (conn close, close()/
+     * close({message}), goFatal, a drain hand-over's retired conn) so a stale
+     * timer can never fire against a conn that's no longer the active one --
+     * though the `this.conn === conn` check inside it is also always
+     * re-verified regardless, belt and suspenders. Per-connection: a
+     * drain-superseded predecessor closing well after its replacement's own
+     * `welcome` must never clear the replacement's still-ticking timer (see
+     * the `wasActive` guard in wireConn's 'close' handler below).
+     */
+    private stabilityTimer;
+    private startResolve;
+    private startReject;
+    constructor(url: string, opts: ConnectOptions);
+    /** Starts the first connection attempt and resolves once `welcome` completes (or rejects if it never gets there and reconnecting is pointless: a fatal auth failure, or maxAttempts exhausted before the first success). */
+    start(): Promise<void>;
+    /** The currently active MixerConn, if connected. */
+    currentConn(): MixerConn | null;
+    /** Current reconnect state machine position: idle/dialing/connected/backoff/closed. */
+    currentState(): ClientState;
+    /**
+     * Writes an `app` frame; resolves once `ws.send`'s callback confirms it
+     * actually reached the socket (docs/DESIGN.md), or rejects with the
+     * connection's terminal error if it fails first -- conn.ts's control queue
+     * carries the same per-write resolver `sendData()` already uses for stream
+     * bytes.
+     */
+    sendApp(body: Record<string, unknown>): Promise<void>;
+    /** "Ignore and count" counters for the active connection (item 11); `undefined` when there is none. */
+    stats(): ReturnType<MixerConn["stats"]> | undefined;
+    /**
+     * Graceful client shutdown: stops reconnecting for good and closes every
+     * live/in-flight connection. A dial already in flight when this is called
+     * is closed as soon as it resolves (see connectOnce); nothing reconnects
+     * after this returns.
+     *
+     * With `opts.message`, this is instead an application-initiated close
+     * (CLIENT-SDK.md's "Application close" row): `error{code:
+     * ErrorCode.APPLICATION_CLOSE, message}` on stream 0, WS close `4014`
+     * (message truncated to 123 UTF-8 bytes on a character boundary), then
+     * the socket -- `MixerConn.fail()`'s `teardownConn` already performs
+     * exactly those three steps in order. No `drain`, no grace period.
+     * `APPLICATION_CLOSE` is the only code an application may close a
+     * *connection* with (WIRE.md section 2.8), so there is no caller-chosen
+     * code here (D-2026-09-25-01): an `opts` with a `code` key (a plain-JS
+     * caller still on the old `close({code, message})` shape) throws a
+     * `TypeError` synchronously, before either connection is touched.
+     *
+     * A callback for a stream/`app`/`drain` event received before this close
+     * can still fire shortly after this promise resolves: it doesn't wait for
+     * `onStream`/`onApp`/`onDrain`'s delivery loop to finish flushing whatever
+     * was already queued (CLIENT-SDK.md's "Handler delivery" row) -- see those
+     * options' own doc comments.
+     */
+    close(opts?: CloseOptions): Promise<void>;
+    private closeImpl;
+    private isClosed;
+    /** Cancels a pending backoff timer, if any, and settles connectOnce's awaited delay promise so it doesn't dangle. */
+    private clearReconnectTimer;
+    /** Cancels the pending stability timer, if any (see the field's own doc comment). Idempotent. */
+    private clearStabilityTimer;
+    /**
+     * Arms the one-shot stability timer for `conn`, replacing (and so
+     * implicitly clearing) whatever timer was pending before -- there is only
+     * ever one conn worth timing at once: a drain-superseded predecessor is
+     * torn down as soon as the replacement's own `welcome` lands (connectOnce),
+     * which is exactly the moment this is called for the replacement, so the
+     * predecessor's own now-irrelevant timer never outlives this call.
+     */
+    private armStabilityTimer;
+    private connectOnce;
+    /**
+     * One dial + handshake attempt: resolves the token provider (fresh, per
+     * CLIENT-SDK.md's "Token provider" row), opens the socket, and -- if that succeeds --
+     * builds a `MixerConn` and waits for `welcome`. Returns a discriminated
+     * result rather than throwing, so connectOnce's retry loop above can
+     * decide what to do with a failure (retry once, or finalize it) without a
+     * second round of reclassifying the same error: `unauthorized` is true for
+     * exactly the two pre-welcome rejection shapes eligible for that retry (an
+     * HTTP 401 on the upgrade, or a handshake-phase UNAUTHORIZED, 4011, with
+     * or without a preceding `error{}`); `cancelled` is true when `close()`
+     * raced the dial/handshake and there is nothing left to report.
+     */
+    private dialAndHandshakeOnce;
+    private wireConn;
+    private notifyDisconnect;
+    /** Builds the final `DisconnectPayload` for a `DisconnectContext`, filling in `fatal` and, when present, the exhaustion message override. */
+    private buildPayload;
+    private rejectStartIfNeverConnected;
+    /** Fatal per WIRE.md section 2.9: never reconnect, surface loudly, and fail start() if it never got a first connection. One report only. */
+    private goFatal;
+    /**
+     * maxAttempts exhausted: stop, but connect() must reject if it never
+     * succeeded once. Reports exactly one `DisconnectReason` -- the merged
+     * exhaustion report, `fatal: true` with the exhaustion `message`, but
+     * carrying the underlying failure's `wsCode`/`errorCode`/`httpStatus`/
+     * `cause` from `ctx` -- never a second report on top of the one the
+     * failure itself would otherwise have gotten (blocker 1).
+     *
+     * Mirrors goFatal: clears the stability timer too (a live connection can
+     * still have one ticking, e.g. a drain hand-over's parallel dial failing
+     * while the old connection it was replacing is still up), and detaches
+     * every live/in-flight conn -- `conn`, `dialingConn`, `retiringConn`,
+     * which a drain hand-over can leave all pointing at the very same live
+     * connection, hence the reference-dedup below -- before failing it, so
+     * each one's own 'close' handler sees `this.conn`/`this.retiringConn`/
+     * `this.dialingConn` already cleared and produces no report of its own;
+     * this call is still the one report. Without this, an exhausted client
+     * left a still-live socket (and its ping/watchdog timers, and the
+     * now-orphaned stability timer) running past "closed".
+     */
+    private giveUp;
+    /**
+     * The single point where a recoverable disconnect either gets its one
+     * report and a scheduled retry, or -- if `maxAttempts` is already
+     * exhausted -- gets folded into `giveUp`'s one merged exhaustion report
+     * instead. Exhaustion is checked *before* any report goes out, which is
+     * what makes "exactly one `DisconnectReason` per disconnect" (blocker 1)
+     * hold: the two outcomes are mutually exclusive, never both.
+     */
+    private reportAndSchedule;
+    /**
+     * Close 4012 / close 1001 with no preceding `drain`: reconnect
+     * immediately, jitter random(0, 2000)ms only -- but still counts toward
+     * `attempt`/`maxAttempts`, so a 4012 flap loop (a server stuck
+     * accepting-then-immediately-draining) still respects the ceiling instead
+     * of retrying forever. (The `drain`-triggered parallel reconnect is a
+     * separate, direct connectOnce() call in the `drain` handler above and
+     * does not bump `attempt` -- it is the server telling us to move, not a
+     * failure being retried.)
+     */
+    private reconnectImmediately;
+    /**
+     * Close 4013 KEEPALIVE_TIMEOUT: one immediate attempt, then normal backoff
+     * (WIRE.md section 2.9). The immediate attempt goes through
+     * reportAndSchedule -- same as the 4012 path (reconnectImmediately) -- so
+     * it respects the maxAttempts ceiling too: a 4013 flap loop with no budget
+     * left gives up (one merged `fatal: true` report) instead of dialing a
+     * socket reportAndSchedule would otherwise have refused to allow.
+     *
+     * `keepaliveImmediateRetryUsed` is a once-only budget re-armed ONLY at
+     * stability (armStabilityTimer) -- deliberately never un-set here on the
+     * second (or any later) 4013: doing that would let the budget "spend then
+     * immediately un-spend itself" on the very next 4013, so four 4013s in a
+     * row with no intervening stable connection would go immediate, backoff,
+     * immediate, backoff... forever, instead of immediate once and backoff
+     * every time after that until the client actually goes stable.
+     */
+    private scheduleReconnectAfterKeepaliveTimeout;
+    /** Close 4009 ENHANCE_YOUR_CALM: start backoff at the cap, not at base. */
+    private scheduleReconnectAtCap;
+    /** Normal AWS full-jitter backoff: everything not covered by a more specific rule above. */
+    private scheduleReconnect;
+}
+/** AWS "full jitter": random(0, min(cap, base * 2^attempt)). */
+export declare function fullJitterDelay(attempt: number, base: number, cap: number): number;
+/** Connects to a ws-mixer.v1 server and starts the reconnect-managed client. Resolves once the first `welcome` lands. */
+export declare function connect(url: string, opts: ConnectOptions): Promise<MixerClient>;