@inkbox/sdk 0.2.16 → 0.3.1

package/dist/tunnels/client/_ws.js

@@ -0,0 +1,351 @@
+/**
+ * inkbox-tunnels/client/_ws.ts
+ *
+ * In-process WebSocket session driver.
+ *
+ * Public types: {@link InkboxWebSocket}, {@link InkboxWsHandler},
+ * {@link WsAcceptDeadlineExceeded}, {@link WsProtocolMismatch},
+ * {@link WsClosed}.
+ *
+ * Internal types: {@link buildAcceptReply}, the lifecycle driver
+ * {@link dispatchWsUpgradeInProcess}.
+ *
+ */
+import { HOP_BY_HOP_RESPONSE } from "./_protocol.js";
+import { WS_OPCODE_BINARY, WS_OPCODE_CLOSE, WS_OPCODE_PING, WS_OPCODE_PONG, WS_OPCODE_TEXT, WsEnvelopeDecoder, WsFrameDecoder, encodeWsEnvelope, encodeWsFrame, } from "./_wsframe.js";
+// --- Public exception types ----------------------------------------------
+export class WsAcceptDeadlineExceeded extends Error {
+    constructor(message = "WebSocket accept deadline exceeded") {
+        super(message);
+        this.name = "WsAcceptDeadlineExceeded";
+    }
+}
+export class WsProtocolMismatch extends Error {
+    constructor(requested, offered) {
+        super(`requested subprotocol ${JSON.stringify(requested)} is not in the ` +
+            `peer's offered set ${JSON.stringify(offered)}`);
+        this.name = "WsProtocolMismatch";
+    }
+}
+export class WsClosed extends Error {
+    constructor(message = "WebSocket is closed") {
+        super(message);
+        this.name = "WsClosed";
+    }
+}
+// --- Pure helpers (M1 — unit-testable independent of the runtime) --------
+/**
+ * Parse a `Sec-WebSocket-Protocol` header into an ordered list of
+ * offered subprotocols. Comma-split, trimmed, empties dropped.
+ */
+export function parseOfferedSubprotocols(forwardedHeaders) {
+    const out = [];
+    for (const [k, v] of forwardedHeaders) {
+        if (k.toLowerCase() !== "sec-websocket-protocol")
+            continue;
+        for (const piece of v.split(",")) {
+            const trimmed = piece.trim();
+            if (trimmed)
+                out.push(trimmed);
+        }
+    }
+    return out;
+}
+/**
+ * Build the upgrade-reply headers the runtime posts back to
+ * `/_system/response/{requestId}` once the user's handler has called
+ * `accept()`.
+ *
+ * Hop-by-hop headers are stripped; an explicit `subprotocol` is added
+ * as `sec-websocket-protocol`.
+ */
+export function buildAcceptReply(acceptOpts) {
+    const out = [];
+    if (acceptOpts?.protocol) {
+        out.push(["sec-websocket-protocol", acceptOpts.protocol]);
+    }
+    for (const [k, v] of acceptOpts?.headers ?? []) {
+        if (HOP_BY_HOP_RESPONSE.has(k.toLowerCase()))
+            continue;
+        out.push([k, v]);
+    }
+    return out;
+}
+/**
+ * Build the inbound headers map exposed to the user's handler. Strips
+ * hop-by-hop request headers; preserves the rest verbatim.
+ */
+export function buildInboundHeaders(envelope) {
+    const out = new Map();
+    for (const [k, v] of envelope.forwardedHeaders) {
+        out.set(k.toLowerCase(), v);
+    }
+    return out;
+}
+/**
+ * The full WS-upgrade lifecycle from envelope → handler → message
+ * pump → CLOSE. The runtime calls this from its dispatch loop after
+ * confirming the envelope is a `ws-upgrade` route kind.
+ */
+export async function dispatchWsUpgradeInProcess(opts) {
+    const { envelope, handler, publicHost, acceptDeadlineMs, bridge } = opts;
+    const offered = parseOfferedSubprotocols(envelope.forwardedHeaders);
+    const url = `wss://${publicHost}${envelope.path}`;
+    const headers = buildInboundHeaders(envelope);
+    const session = new WsSession({
+        url,
+        headers,
+        offeredProtocols: offered,
+        acceptDeadlineMs,
+        bridge,
+    });
+    // Drive the user handler. The session manages accept-deadline,
+    // pumps, and shutdown internally.
+    await session.run(handler);
+}
+class WsSession {
+    url;
+    headers;
+    offeredProtocols;
+    bridge;
+    acceptDeadlineMs;
+    acceptCalled = false;
+    acceptResolved = false;
+    acceptReply = null;
+    closeRequested = false;
+    closeResolved = false;
+    inboundQueue = [];
+    inboundWaiter = null;
+    envelopeDecoder = new WsEnvelopeDecoder();
+    frameDecoder = new WsFrameDecoder();
+    constructor(opts) {
+        this.url = opts.url;
+        this.headers = opts.headers;
+        this.offeredProtocols = opts.offeredProtocols;
+        this.bridge = opts.bridge;
+        this.acceptDeadlineMs = opts.acceptDeadlineMs;
+    }
+    // --- public InkboxWebSocket surface ------------------------------------
+    async accept(opts) {
+        if (this.acceptCalled)
+            return;
+        if (opts?.protocol !== undefined) {
+            if (!this.offeredProtocols.includes(opts.protocol)) {
+                throw new WsProtocolMismatch(opts.protocol, this.offeredProtocols);
+            }
+        }
+        this.acceptCalled = true;
+        this.acceptReply = buildAcceptReply(opts);
+        await this.bridge.postUpgradeReply(this.acceptReply);
+        this.acceptResolved = true;
+    }
+    async send(data) {
+        if (this.closeRequested)
+            throw new WsClosed();
+        if (!this.acceptResolved) {
+            throw new WsClosed("send() before accept()");
+        }
+        let envelope;
+        if (typeof data === "string") {
+            envelope = encodeWsEnvelope({ type: "websocket.send", text: data });
+        }
+        else {
+            envelope = encodeWsEnvelope({ type: "websocket.send", bytes: data });
+        }
+        await this.bridge.sendFrame(encodeWsFrame(WS_OPCODE_BINARY, envelope, { mask: true }));
+    }
+    async close(code = 1000, reason = "") {
+        if (this.closeRequested)
+            return;
+        this.closeRequested = true;
+        if (!this.acceptResolved) {
+            // Handler called close before accept — reject the upgrade.
+            try {
+                await this.bridge.rejectUpgrade(403, "handler rejected upgrade");
+            }
+            catch {
+                /* swallow */
+            }
+            this.closeResolved = true;
+            return;
+        }
+        // Send wire-envelope CLOSE and a real WS CLOSE frame.
+        const closeEnv = encodeWsEnvelope({ type: "websocket.close", code, reason });
+        try {
+            await this.bridge.sendFrame(encodeWsFrame(WS_OPCODE_BINARY, closeEnv, { mask: true }));
+            const closePayload = Buffer.alloc(2 + Buffer.byteLength(reason, "utf-8"));
+            closePayload.writeUInt16BE(code, 0);
+            Buffer.from(reason, "utf-8").copy(closePayload, 2);
+            await this.bridge.sendFrame(encodeWsFrame(WS_OPCODE_CLOSE, closePayload, { mask: true }));
+        }
+        catch {
+            /* swallow — bridge may already be torn down */
+        }
+        try {
+            await this.bridge.closeStream();
+        }
+        catch {
+            /* swallow */
+        }
+        this.closeResolved = true;
+        this.pushInbound({ kind: "close" });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                while (true) {
+                    const item = this.inboundQueue.shift();
+                    if (item !== undefined) {
+                        if (item.kind === "msg") {
+                            return { value: item.data, done: false };
+                        }
+                        if (item.kind === "close") {
+                            return { value: undefined, done: true };
+                        }
+                        throw item.err;
+                    }
+                    await new Promise((resolve) => {
+                        this.inboundWaiter = resolve;
+                    });
+                }
+            },
+        };
+    }
+    // --- runtime-facing driver --------------------------------------------
+    async run(handler) {
+        // Race the handler vs. the accept-deadline. Use a clearable timer
+        // and a manually-rejectable promise so we don't leak the timer
+        // after accept resolves.
+        let deadlineTimer = null;
+        const acceptDeadline = new Promise((_, reject) => {
+            deadlineTimer = setTimeout(() => {
+                if (!this.acceptCalled) {
+                    reject(new WsAcceptDeadlineExceeded());
+                }
+            }, this.acceptDeadlineMs);
+        });
+        // Holder for the pump task; assigned by `pumpStarter` once accept
+        // resolves. Typed as a single-element record so the `null` case
+        // doesn't get narrowed to `never` by control-flow analysis.
+        const pumpHolder = { promise: null };
+        const handlerPromise = (async () => {
+            try {
+                await handler(this);
+            }
+            finally {
+                if (this.acceptResolved && !this.closeRequested) {
+                    await this.close(1000, "");
+                }
+                else if (!this.acceptResolved && !this.closeRequested) {
+                    await this.bridge.rejectUpgrade(500, "handler returned without accept");
+                    this.closeResolved = true;
+                }
+            }
+        })();
+        // Start the inbound pump only AFTER accept resolves — otherwise
+        // `recv()` can see a still-null bridge-stream id and exit early
+        // before any data arrives. We start a watcher that observes
+        // `acceptResolved` and kicks off the pump exactly once.
+        const pumpStarter = (async () => {
+            while (!this.acceptResolved &&
+                !this.closeRequested) {
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+            if (this.acceptResolved && !this.closeRequested) {
+                pumpHolder.promise = this.runInboundPump();
+            }
+        })();
+        try {
+            await Promise.race([handlerPromise, acceptDeadline]);
+        }
+        catch (err) {
+            if (err instanceof WsAcceptDeadlineExceeded) {
+                try {
+                    await this.bridge.rejectUpgrade(504, "ws upgrade timed out");
+                }
+                catch {
+                    /* swallow */
+                }
+                // Mark the session terminal so ``pumpStarter``'s wait loop and
+                // ``recv()`` consumers exit promptly. Without this, a handler
+                // that ignores the deadline would keep ``acceptResolved`` and
+                // ``closeRequested`` both false, leaving ``pumpStarter``
+                // spinning until the runtime finally tore the bridge down.
+                this.closeRequested = true;
+                this.closeResolved = true;
+                this.pushInbound({ kind: "error", err });
+                // Surface the timeout to caller without blocking on the
+                // handler. Detach with a no-op catch so an unhandled-rejection
+                // doesn't fire if the handler eventually throws (handler is a
+                // user-supplied promise and may take arbitrarily long; we
+                // posted the 504 already, so further work is just observable
+                // bookkeeping).
+                handlerPromise.catch(() => undefined);
+            }
+            throw err;
+        }
+        finally {
+            if (deadlineTimer !== null)
+                clearTimeout(deadlineTimer);
+            await pumpStarter.catch(() => undefined);
+            if (pumpHolder.promise !== null) {
+                await pumpHolder.promise.catch(() => undefined);
+            }
+        }
+    }
+    async runInboundPump() {
+        try {
+            for await (const chunk of this.bridge.recv()) {
+                const frames = this.frameDecoder.feed(chunk);
+                for (const frame of frames) {
+                    if (frame.opcode === WS_OPCODE_PING) {
+                        await this.bridge.sendFrame(encodeWsFrame(WS_OPCODE_PONG, frame.payload, { mask: true }));
+                        continue;
+                    }
+                    if (frame.opcode === WS_OPCODE_PONG)
+                        continue;
+                    if (frame.opcode === WS_OPCODE_CLOSE) {
+                        this.pushInbound({ kind: "close" });
+                        return;
+                    }
+                    if (frame.opcode === WS_OPCODE_BINARY ||
+                        frame.opcode === WS_OPCODE_TEXT) {
+                        const envs = this.envelopeDecoder.feed(frame.payload);
+                        for (const env of envs) {
+                            if (env.type === "text") {
+                                this.pushInbound({ kind: "msg", data: env.data });
+                            }
+                            else if (env.type === "binary") {
+                                this.pushInbound({ kind: "msg", data: env.data });
+                            }
+                            else if (env.type === "close") {
+                                this.pushInbound({ kind: "close" });
+                                return;
+                            }
+                        }
+                    }
+                }
+            }
+            // Stream ended without an explicit CLOSE envelope.
+            // Per partial-bytes-at-EOF policy: drop trailing buffer bytes
+            // silently and signal close to the iterator.
+            this.pushInbound({ kind: "close" });
+        }
+        catch (err) {
+            this.pushInbound({
+                kind: "error",
+                err: err instanceof Error ? err : new Error(String(err)),
+            });
+        }
+    }
+    pushInbound(item) {
+        this.inboundQueue.push(item);
+        const waiter = this.inboundWaiter;
+        if (waiter !== null) {
+            this.inboundWaiter = null;
+            waiter();
+        }
+    }
+}
+export const __testing = { WsSession };
+//# sourceMappingURL=_ws.js.map

package/dist/tunnels/client/_ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ws.js","sourceRoot":"","sources":["../../../src/tunnels/client/_ws.ts"],"names":[],"mappings":"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"}

package/dist/tunnels/client/_ws_passthrough.d.ts

@@ -0,0 +1,129 @@
+/**
+ * inkbox-tunnels/client/_ws_passthrough.ts
+ *
+ * WebSocket support for passthrough mode.
+ *
+ * The h1 parser and h2 transcoder hand a {@link WebSocketSink} to the
+ * dispatcher when the inbound is a WS upgrade. The dispatcher completes
+ * the handshake via `accept` then bridges frames via `sendFrame` /
+ * `recvFrame`. The `bridgeWsHandlerOverSink` helper wires an
+ * `InkboxWsHandler` to one of those sinks so the same handler shape
+ * serves h1 `Upgrade: websocket` and h2 RFC 8441 Extended CONNECT.
+ */
+import type { InkboxWsHandler } from "./_ws.js";
+export declare function computeWsAccept(key: string): string;
+/**
+ * Encode an unmasked server-to-client frame. RFC 6455 §5.1 — server
+ * frames MUST NOT be masked. The shared `_wsframe.encodeWsFrame`
+ * defaults to client semantics (masked); this helper enforces unmasked.
+ */
+export declare function encodeServerFrame(opcode: number, payload: Buffer, fin?: boolean): Buffer;
+/**
+ * Decode one complete client-to-server frame from `buf`.
+ *
+ * For h1 WebSockets (RFC 6455 §5.1) client frames MUST be masked;
+ * pass `requireMask=true` (default) and the decoder rejects unmasked
+ * frames. For h2 WebSockets (RFC 8441 §5.1) frames are NEVER masked —
+ * the transcoder passes `requireMask=false` so unmasked payloads are
+ * returned verbatim.
+ */
+export declare function decodeClientFrame(buf: Buffer[], opts?: {
+    requireMask?: boolean;
+}): {
+    kind: "frame";
+    opcode: number;
+    payload: Buffer;
+    fin: boolean;
+} | {
+    kind: "need-more";
+} | {
+    kind: "rejected";
+};
+export interface WebSocketSink {
+    accept(opts?: {
+        subprotocol?: string;
+        extraHeaders?: Array<[string, string]>;
+    }): Promise<void>;
+    reject(opts?: {
+        status?: number;
+        reason?: string;
+    }): Promise<void>;
+    sendFrame(opcode: number, payload: Buffer, opts?: {
+        fin?: boolean;
+    }): Promise<void>;
+    recvFrame(): Promise<{
+        opcode: number;
+        payload: Buffer;
+        fin: boolean;
+    } | null>;
+    aclose(): Promise<void>;
+}
+export interface WsPassthroughRequestMeta {
+    url: string;
+    headers: ReadonlyMap<string, string>;
+    offeredSubprotocols: string[];
+}
+/**
+ * Drive an `InkboxWsHandler` against a `WebSocketSink`. Constructs an
+ * `InkboxWebSocket`-shaped object whose lifecycle (`accept`, `send`,
+ * `close`, async-iterator) maps onto the sink's frame I/O.
+ */
+export declare function bridgeWsHandlerOverSink(opts: {
+    handler: InkboxWsHandler;
+    sink: WebSocketSink;
+    meta: WsPassthroughRequestMeta;
+}): Promise<void>;
+export interface ByteChannelSinkOpts {
+    /** Plaintext bytes to write back on the wire. */
+    sendPlaintext: (data: Buffer) => Promise<void>;
+    /** Build the protocol-appropriate accept response (h1 = 101 head; h2 = :status 200). */
+    buildAcceptResponse: (subprotocol: string | null, extraHeaders: Array<[string, string]> | null) => Buffer;
+    /** Build the protocol-appropriate reject response. */
+    buildRejectResponse: (status: number) => Buffer;
+    /** Optional teardown callback. */
+    onClose?: () => Promise<void>;
+    /**
+     * h1 transports require client-to-server frames to be masked
+     * (RFC 6455 §5.1); h2 transports require them to be unmasked
+     * (RFC 8441 §5.1). Default: true.
+     */
+    requireClientMask?: boolean;
+}
+/**
+ * Common `WebSocketSink` impl backed by an inbound byte queue + outbound
+ * send callback. The h1 parser drives this from a node:http upgrade
+ * socket; the h2 transcoder drives the same shape from Extended-CONNECT
+ * stream DATA frames.
+ */
+export declare class ByteChannelWebSocketSink implements WebSocketSink {
+    private readonly sendPlaintext;
+    private readonly buildAccept;
+    private readonly buildReject;
+    private readonly onCloseHook?;
+    private readonly requireClientMask;
+    private inboundChunks;
+    private inboundResolvers;
+    private inboundClosed;
+    private accepted;
+    private closed;
+    constructor(opts: ByteChannelSinkOpts);
+    feedInbound(data: Buffer): void;
+    signalInboundEof(): void;
+    accept(opts?: {
+        subprotocol?: string;
+        extraHeaders?: Array<[string, string]>;
+    }): Promise<void>;
+    reject(opts?: {
+        status?: number;
+    }): Promise<void>;
+    sendFrame(opcode: number, payload: Buffer, opts?: {
+        fin?: boolean;
+    }): Promise<void>;
+    recvFrame(): Promise<{
+        opcode: number;
+        payload: Buffer;
+        fin: boolean;
+    } | null>;
+    aclose(): Promise<void>;
+}
+//# sourceMappingURL=_ws_passthrough.d.ts.map

package/dist/tunnels/client/_ws_passthrough.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ws_passthrough.d.ts","sourceRoot":"","sources":["../../../src/tunnels/client/_ws_passthrough.ts"],"names":[],"mappings":"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"}