@inkbox/sdk 0.2.15 → 0.3.0

package/dist/tunnels/client/_ws_url_edge_bridge.js

@@ -0,0 +1,256 @@
+/**
+ * inkbox-tunnels/client/_ws_url_edge_bridge.ts
+ *
+ * Edge-mode URL WebSocket bridge.
+ *
+ * The third party's WS frames arrive over the bridge stream as
+ * length-prefixed JSON envelopes wrapped in outer WS BINARY frames
+ * (the standard inkbox bridge protocol). We translate each direction:
+ *
+ * * Bridge → upstream: outer WS frames → inner JSON envelopes →
+ *   RFC 6455 frames (masked, h1 client-side) written to the upstream
+ *   socket.
+ * * Upstream → bridge: RFC 6455 frames (server, unmasked) → JSON
+ *   envelopes → outer WS BINARY frames (masked) sent on the bridge
+ *   via ``WsBridgeIO.sendFrame``.
+ *
+ * PING / PONG control frames are answered locally and not propagated.
+ */
+import { WS_OPCODE_BINARY, WS_OPCODE_CLOSE, WS_OPCODE_PING, WS_OPCODE_PONG, WS_OPCODE_TEXT, WsEnvelopeDecoder, WsFrameDecoder, encodeWsEnvelope, encodeWsFrame, } from "./_wsframe.js";
+import { decodeClientFrame } from "./_ws_passthrough.js";
+export async function pumpWsUrlEdgeBridge(opts) {
+    const { upstream, bridge } = opts;
+    const socket = upstream.socket;
+    // Upstream → bridge.
+    // The inkbox bridge protocol carries complete WS messages inside
+    // ``websocket.send`` envelopes; it cannot represent fragmentation.
+    // RFC 6455 lets the upstream split a TEXT/BINARY message into a
+    // first frame (TEXT/BINARY, FIN=0) followed by CONTINUATION frames
+    // until FIN=1. Reassemble client-side so we emit one envelope per
+    // message even when upstream streams it as fragments.
+    const upstreamBuf = [];
+    if (upstream.leftover.length > 0)
+        upstreamBuf.push(upstream.leftover);
+    let upstreamClosed = false;
+    let bridgeClosed = false;
+    let messageOpcode = null;
+    let messageChunks = [];
+    // Wake the bridge.recv() iteration on abrupt upstream close. Without
+    // it, the bridge→upstream loop sits inside the iterator until the
+    // third party sends another frame (which an idle upstream peer
+    // crash leaves indefinitely).
+    let signalUpstreamClosed = () => { };
+    const upstreamClosedSignal = new Promise((resolve) => {
+        signalUpstreamClosed = resolve;
+    });
+    const drainUpstream = async () => {
+        while (!bridgeClosed) {
+            const decoded = decodeClientFrame(upstreamBuf, { requireMask: false });
+            if (decoded.kind === "need-more")
+                return;
+            if (decoded.kind === "rejected") {
+                upstreamClosed = true;
+                return;
+            }
+            const { opcode, payload, fin } = decoded;
+            if (opcode === WS_OPCODE_PING) {
+                try {
+                    socket.write(encodeWsFrame(WS_OPCODE_PONG, payload, { mask: true }));
+                }
+                catch {
+                    return;
+                }
+                continue;
+            }
+            if (opcode === WS_OPCODE_PONG)
+                continue;
+            if (opcode === WS_OPCODE_CLOSE) {
+                const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1000;
+                const env = encodeWsEnvelope({
+                    type: "websocket.close",
+                    code,
+                    reason: "",
+                });
+                try {
+                    await bridge.sendFrame(encodeWsFrame(WS_OPCODE_BINARY, env, { mask: true }));
+                }
+                catch {
+                    /* swallow */
+                }
+                upstreamClosed = true;
+                return;
+            }
+            if (opcode === WS_OPCODE_TEXT || opcode === WS_OPCODE_BINARY) {
+                // Start of a (possibly fragmented) message. RFC 6455 §5.4
+                // requires no two TEXT/BINARY without a FIN=1 between them.
+                if (messageOpcode !== null) {
+                    // Defensive: upstream framed badly — drop and close.
+                    upstreamClosed = true;
+                    return;
+                }
+                messageOpcode = opcode;
+                messageChunks = [payload];
+            }
+            else if (opcode === 0x0) {
+                // CONTINUATION
+                if (messageOpcode === null) {
+                    upstreamClosed = true;
+                    return;
+                }
+                messageChunks.push(payload);
+            }
+            else {
+                // Unknown opcode — ignore safely.
+                continue;
+            }
+            if (fin && messageOpcode !== null) {
+                const full = Buffer.concat(messageChunks);
+                const startedOpcode = messageOpcode;
+                messageOpcode = null;
+                messageChunks = [];
+                if (startedOpcode === WS_OPCODE_TEXT) {
+                    let text;
+                    try {
+                        text = full.toString("utf-8");
+                    }
+                    catch {
+                        upstreamClosed = true;
+                        return;
+                    }
+                    const env = encodeWsEnvelope({ type: "websocket.send", text });
+                    try {
+                        await bridge.sendFrame(encodeWsFrame(WS_OPCODE_BINARY, env, { mask: true }));
+                    }
+                    catch {
+                        return;
+                    }
+                }
+                else {
+                    const env = encodeWsEnvelope({
+                        type: "websocket.send",
+                        bytes: full,
+                    });
+                    try {
+                        await bridge.sendFrame(encodeWsFrame(WS_OPCODE_BINARY, env, { mask: true }));
+                    }
+                    catch {
+                        return;
+                    }
+                }
+            }
+        }
+    };
+    let draining = false;
+    const triggerDrain = () => {
+        if (draining)
+            return;
+        draining = true;
+        drainUpstream()
+            .catch(() => undefined)
+            .finally(() => {
+            draining = false;
+        });
+    };
+    socket.on("data", (chunk) => {
+        upstreamBuf.push(chunk);
+        triggerDrain();
+    });
+    socket.once("close", () => {
+        upstreamClosed = true;
+        signalUpstreamClosed();
+    });
+    socket.once("error", () => {
+        upstreamClosed = true;
+        signalUpstreamClosed();
+    });
+    // The upstream may already be gone between openWsUpstream returning
+    // and pumpWsUrlEdgeBridge attaching listeners (especially for an
+    // upstream that destroys after writing 101). "close" is one-shot, so
+    // a listener attached after the fact never fires — check explicitly.
+    if (socket.destroyed) {
+        upstreamClosed = true;
+        signalUpstreamClosed();
+    }
+    // Kick off in case the upgrade already shipped trailing frame bytes.
+    triggerDrain();
+    // Bridge → upstream.
+    const frameDecoder = new WsFrameDecoder();
+    const envelopeDecoder = new WsEnvelopeDecoder();
+    const it = bridge.recv()[Symbol.asyncIterator]();
+    try {
+        while (!upstreamClosed && !bridgeClosed) {
+            const next = await Promise.race([
+                it.next(),
+                upstreamClosedSignal.then(() => ({ done: true, value: undefined })),
+            ]);
+            if (next.done)
+                break;
+            const chunk = next.value;
+            for (const frame of frameDecoder.feed(chunk)) {
+                if (frame.opcode === WS_OPCODE_PING) {
+                    await bridge.sendFrame(encodeWsFrame(WS_OPCODE_PONG, frame.payload, { mask: true }));
+                    continue;
+                }
+                if (frame.opcode === WS_OPCODE_PONG)
+                    continue;
+                if (frame.opcode === WS_OPCODE_CLOSE) {
+                    bridgeClosed = true;
+                    break;
+                }
+                if (frame.opcode === WS_OPCODE_BINARY ||
+                    frame.opcode === WS_OPCODE_TEXT) {
+                    for (const env of envelopeDecoder.feed(frame.payload)) {
+                        if (env.type === "text") {
+                            try {
+                                socket.write(encodeWsFrame(WS_OPCODE_TEXT, Buffer.from(env.data, "utf-8"), { mask: true }));
+                            }
+                            catch {
+                                bridgeClosed = true;
+                                break;
+                            }
+                        }
+                        else if (env.type === "binary") {
+                            try {
+                                socket.write(encodeWsFrame(WS_OPCODE_BINARY, env.data, { mask: true }));
+                            }
+                            catch {
+                                bridgeClosed = true;
+                                break;
+                            }
+                        }
+                        else if (env.type === "close") {
+                            const codeBuf = Buffer.alloc(2);
+                            codeBuf.writeUInt16BE(env.code, 0);
+                            try {
+                                socket.write(encodeWsFrame(WS_OPCODE_CLOSE, codeBuf, { mask: true }));
+                            }
+                            catch {
+                                /* swallow */
+                            }
+                            bridgeClosed = true;
+                            break;
+                        }
+                    }
+                }
+            }
+            if (bridgeClosed)
+                break;
+        }
+    }
+    catch {
+        /* bridge stream closed */
+    }
+    finally {
+        bridgeClosed = true;
+        // Release the recv iterator (esp. when we exited via the
+        // upstream-closed race) so the underlying h2 stream queue isn't
+        // left with a parked consumer.
+        try {
+            await it.return?.();
+        }
+        catch {
+            /* swallow */
+        }
+    }
+}
+//# sourceMappingURL=_ws_url_edge_bridge.js.map

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

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

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

@@ -0,0 +1,142 @@
+/**
+ * inkbox-tunnels/client/_wsframe.ts
+ *
+ * RFC 6455 WebSocket frame codec, plus the length-prefixed JSON envelope
+ * format the WS-bridge stream carries.
+ *
+ * Pure / synchronous; no I/O. Used by both the WS upgrade bridge and
+ * the passthrough TCP bridge (which tunnels raw bytes inside WS BINARY
+ * frames on an extended-CONNECT stream).
+ *
+ * ## Statefulness — the decoder MUST accumulate across calls
+ *
+ * A single h2 DATA frame can carry zero, one, many, or partial WS
+ * frames; a single WS frame (with extended length) can span multiple
+ * DATA boundaries. Use {@link WsFrameDecoder.feed} which retains a
+ * carry buffer between calls. Do not implement
+ * one-frame-per-DATA-callback in callers.
+ *
+ * ## Partial-bytes-at-EOF policy (M3 T0 — matches Python)
+ *
+ * If the bridge stream ends ("end" or "reset" h2 event) while the carry
+ * buffer still contains a partial WS frame, the policy is:
+ *   **drop the trailing bytes silently and close the WS session.**
+ *   No RST_STREAM. No error surfaced to the user.
+ *
+ * Verified against Python `_runtime.py` (`_pump_ws`): on a stream-end /
+ * stream-reset event, `recv_done` is set and the loop exits, abandoning
+ * `wire_buf` and `env_buf` without any cleanup write. The TS port
+ * mirrors that exactly.
+ */
+export declare const WS_OPCODE_CONTINUATION = 0;
+export declare const WS_OPCODE_TEXT = 1;
+export declare const WS_OPCODE_BINARY = 2;
+export declare const WS_OPCODE_CLOSE = 8;
+export declare const WS_OPCODE_PING = 9;
+export declare const WS_OPCODE_PONG = 10;
+export interface WsFrame {
+    opcode: number;
+    payload: Buffer;
+    fin: boolean;
+}
+/**
+ * Stateful WS frame decoder. Hold one per bridge stream; call
+ * {@link feed} as h2 DATA chunks arrive.
+ */
+export declare class WsFrameDecoder {
+    private buf;
+    /**
+     * Feed a chunk of wire bytes; return any newly-decodable frames.
+     * Trailing partial bytes stay in the carry buffer for the next call.
+     */
+    feed(chunk: Buffer): WsFrame[];
+    /** True iff there are partial bytes still in the carry buffer. */
+    hasPartial(): boolean;
+    /** Bytes currently buffered (test-only inspection). */
+    partialBytes(): number;
+}
+export interface EncodeOptions {
+    /** RFC 6455 requires client→server frames to be masked. Default: true. */
+    mask?: boolean;
+    /**
+     * RFC 6455 FIN bit. Default: true (single-frame message). Set false to
+     * produce a fragment that expects a continuation; needed by the URL
+     * passthrough bridge so multi-frame messages aren't silently coalesced.
+     */
+    fin?: boolean;
+}
+/**
+ * Encode a single WS frame. ``mask=true`` is required for
+ * client→server traffic per RFC 6455.
+ */
+export declare function encodeWsFrame(opcode: number, payload: Buffer, options?: EncodeOptions): Buffer;
+/**
+ * Outbound WS-envelope shape exchanged on the bridge stream.
+ *
+ * The wire shape is `length-prefixed (4 BE bytes) JSON`:
+ *
+ *   - `{type: "text",   data: <utf-8 string>}`
+ *   - `{type: "binary", data: <base64 ascii>}`
+ *   - `{type: "close",  code: <int>, reason: <string>}`
+ *
+ * Binary payloads are base64-wrapped to match the server's bridge
+ * contract (server `b64encode`/`b64decode`).
+ */
+export type OutboundWsMsg = {
+    type: "websocket.send";
+    text: string;
+} | {
+    type: "websocket.send";
+    bytes: Buffer;
+} | {
+    type: "websocket.close";
+    code?: number;
+    reason?: string;
+};
+export declare function encodeWsEnvelope(msg: OutboundWsMsg): Buffer;
+/**
+ * Inbound bridge envelope decoded from a string/binary WS frame
+ * payload.
+ */
+export type InboundWsEnvelope = {
+    type: "text";
+    data: string;
+} | {
+    type: "binary";
+    data: Buffer;
+} | {
+    type: "close";
+    code: number;
+    reason?: string;
+};
+/**
+ * Length-prefixed-JSON envelope decoder. Stateful — call repeatedly
+ * with concatenated WS-frame payloads, get back fully-formed envelopes
+ * as they emerge.
+ *
+ * Binary envelopes have their `data` field strictly base64-validated
+ * (per the server contract). Malformed base64 is logged and dropped —
+ * the empty result is what the runtime delivers, mirroring Python's
+ * `_ws.py` behavior at the validate=True boundary.
+ */
+export declare class WsEnvelopeDecoder {
+    private buf;
+    feed(chunk: Buffer): InboundWsEnvelope[];
+    hasPartial(): boolean;
+}
+/**
+ * Strict base64 decode: rejects non-base64 characters, requires
+ * padding. Mirrors Python `base64.b64decode(..., validate=True)`.
+ *
+ * Node's `Buffer.from(s, "base64")` is permissive (silently strips
+ * non-base64 chars and tolerates missing padding). We need the strict
+ * shape to match the server's outbound encoding exactly — otherwise a
+ * garbage `"@@@@"` decodes to an empty Buffer the user's app would
+ * mistake for a real binary message.
+ */
+declare function decodeStrictBase64(s: string): Buffer | null;
+export declare const __testing: {
+    decodeStrictBase64: typeof decodeStrictBase64;
+};
+export {};
+//# sourceMappingURL=_wsframe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"_wsframe.d.ts","sourceRoot":"","sources":["../../../src/tunnels/client/_wsframe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,eAAO,MAAM,sBAAsB,IAAM,CAAC;AAC1C,eAAO,MAAM,cAAc,IAAM,CAAC;AAClC,eAAO,MAAM,gBAAgB,IAAM,CAAC;AACpC,eAAO,MAAM,eAAe,IAAM,CAAC;AACnC,eAAO,MAAM,cAAc,IAAM,CAAC;AAClC,eAAO,MAAM,cAAc,KAAM,CAAC;AAElC,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,GAAG,CAA2B;IAEtC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE;IAsD9B,kEAAkE;IAClE,UAAU,IAAI,OAAO;IAIrB,uDAAuD;IACvD,YAAY,IAAI,MAAM;CAGvB;AAED,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAoCR;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwB3D;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;;;;GASG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,GAAG,CAA2B;IAEtC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE;IA4BxC,UAAU,IAAI,OAAO;CAGtB;AA2BD;;;;;;;;;GASG;AACH,iBAAS,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASpD;AAED,eAAO,MAAM,SAAS;;CAAyB,CAAC"}