@statewalker/cellb 0.0.0-stage → 0.1.1

package/dist/ws/client.d.ts

@@ -0,0 +1,25 @@
+/** Opens the transport of a socket: resolves with the MessagePort once the server accepted (101). */
+export type WebSocketConnector = (url: string, protocols: string[]) => Promise<{
+    port: MessagePort;
+    protocol?: string;
+}>;
+export interface CellsWebSocketOptions {
+    /** Liveness ping period (ms); 0 disables. The peer is declared dead after 2 missed periods. */
+    heartbeatMs?: number;
+    /**
+     * Interval timers for the heartbeat. On a page's main thread pass worker-timers'
+     * `setInterval`/`clearInterval`: background-tab throttling of main-thread timers would
+     * otherwise delay pings and make the server drop a live socket. Workers and Node do not
+     * throttle, so the built-in timers are the default.
+     */
+    timers?: {
+        setInterval(fn: () => void, ms: number): unknown;
+        clearInterval(id: unknown): void;
+    };
+}
+/**
+ * A WHATWG `WebSocket` class whose sockets reach a Worker through `connect`. Typed as the
+ * platform's `WebSocket` (the class implements that interface; its own state is private).
+ */
+export declare function createWebSocketClass(connect: WebSocketConnector, options?: CellsWebSocketOptions): typeof WebSocket;
+export type CellsWebSocketClass = ReturnType<typeof createWebSocketClass>;

package/dist/ws/client.js

@@ -0,0 +1,203 @@
+import { byteSize, CellsCloseEvent, checkClose, DEFAULT_HEARTBEAT_MS, toFrameData, } from "./frames.js";
+/**
+ * A WHATWG-WebSocket-compatible class whose transport is a MessagePort obtained
+ * from `connect` (page → ServiceWorker → owning shard worker, or in-process).
+ * Installed for user code through webrun-modules `~deps` (provided `WebSocket`),
+ * so the real `globalThis.WebSocket` is left untouched.
+ */
+/** RFC 7230 token (subprotocol names). */
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * A WHATWG `WebSocket` class whose sockets reach a Worker through `connect`. Typed as the
+ * platform's `WebSocket` (the class implements that interface; its own state is private).
+ */
+export function createWebSocketClass(connect, options = {}) {
+    const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+    const timers = options.timers ?? {
+        setInterval: (fn, ms) => setInterval(fn, ms),
+        clearInterval: (id) => clearInterval(id),
+    };
+    class CellsWebSocket extends EventTarget {
+        static CONNECTING = 0;
+        static OPEN = 1;
+        static CLOSING = 2;
+        static CLOSED = 3;
+        CONNECTING = 0;
+        OPEN = 1;
+        CLOSING = 2;
+        CLOSED = 3;
+        url;
+        readyState = 0;
+        protocol = "";
+        extensions = "";
+        #buffered = 0;
+        /** Sizes of the messages posted and not acknowledged yet, in order (the port keeps it). */
+        #unacked = [];
+        /** Bytes sent and not yet received by the server end (it acknowledges each message). */
+        get bufferedAmount() {
+            return this.#buffered;
+        }
+        #binaryType = "blob";
+        get binaryType() {
+            return this.#binaryType;
+        }
+        /** Only "blob" and "arraybuffer" are taken; any other value is ignored (WHATWG). */
+        set binaryType(v) {
+            if (v === "blob" || v === "arraybuffer")
+                this.#binaryType = v;
+        }
+        onopen = null;
+        onmessage = null;
+        onclose = null;
+        onerror = null;
+        #port;
+        #pendingClose;
+        #beat;
+        #lastPong = 0;
+        #startHeartbeat() {
+            if (!heartbeatMs)
+                return;
+            this.#lastPong = Date.now();
+            this.#beat = timers.setInterval(() => {
+                if (this.readyState >= 3)
+                    return this.#stopHeartbeat();
+                if (Date.now() - this.#lastPong > 2 * heartbeatMs)
+                    return this.#fail(); // peer gone
+                this.#port?.postMessage({ t: "p", hb: heartbeatMs });
+            }, heartbeatMs);
+            this.#port?.postMessage({ t: "p", hb: heartbeatMs });
+        }
+        #stopHeartbeat() {
+            if (this.#beat !== undefined)
+                timers.clearInterval(this.#beat);
+            this.#beat = undefined;
+        }
+        constructor(url, protocols = []) {
+            super();
+            // WHATWG "new WebSocket(url, protocols)" validation, in spec order.
+            let u;
+            try {
+                u = new URL(String(url), globalThis.location?.href ?? "http://localhost/");
+            }
+            catch {
+                throw new DOMException(`The URL '${String(url)}' is invalid.`, "SyntaxError");
+            }
+            if (u.protocol === "http:")
+                u.protocol = "ws:";
+            if (u.protocol === "https:")
+                u.protocol = "wss:";
+            if (u.protocol !== "ws:" && u.protocol !== "wss:")
+                throw new DOMException(`The URL's scheme must be either 'ws' or 'wss'.`, "SyntaxError");
+            if (u.hash || String(url).includes("#"))
+                throw new DOMException("The URL contains a fragment identifier.", "SyntaxError");
+            const list = typeof protocols === "string" ? [protocols] : [...protocols];
+            const seen = new Set();
+            for (const p of list) {
+                if (!TOKEN.test(p))
+                    throw new DOMException(`The subprotocol '${p}' is invalid.`, "SyntaxError");
+                if (seen.has(p.toLowerCase()))
+                    throw new DOMException(`The subprotocol '${p}' is duplicated.`, "SyntaxError");
+                seen.add(p.toLowerCase());
+            }
+            this.url = u.toString();
+            connect(this.url, list).then(({ port, protocol }) => this.#opened(port, protocol ?? ""), () => this.#fail());
+        }
+        #emit(ev, handler) {
+            handler?.call(this, ev);
+            this.dispatchEvent(ev);
+        }
+        #opened(port, protocol) {
+            if (this.readyState === 3) {
+                port.close();
+                return;
+            }
+            this.#port = port;
+            this.protocol = protocol;
+            port.onmessage = (e) => this.#frame(e.data);
+            port.start?.();
+            if (this.#pendingClose) {
+                // close() was called while connecting
+                this.readyState = 2;
+                port.postMessage({
+                    t: "c",
+                    code: this.#pendingClose.code ?? 1000,
+                    reason: this.#pendingClose.reason ?? "",
+                });
+                return;
+            }
+            this.readyState = 1;
+            this.#startHeartbeat();
+            this.#emit(new Event("open"), this.onopen);
+        }
+        #fail() {
+            if (this.readyState === 3)
+                return;
+            this.#stopHeartbeat();
+            this.#port?.close();
+            this.readyState = 3;
+            this.#emit(new Event("error"), this.onerror);
+            this.#emit(new CellsCloseEvent("close", { code: 1006, reason: "", wasClean: false }), this.onclose);
+        }
+        #frame(f) {
+            if (f.t === "q") {
+                this.#lastPong = Date.now();
+                return;
+            }
+            if (f.t === "p")
+                return;
+            if (f.t === "a") {
+                this.#buffered -= this.#unacked.shift() ?? 0;
+                return;
+            }
+            if (f.t === "m") {
+                if (this.readyState !== 1)
+                    return;
+                let data = f.d;
+                if (typeof data !== "string" && this.binaryType === "blob")
+                    data = new Blob([data]);
+                this.#emit(new MessageEvent("message", { data, origin: new URL(this.url).origin }), this.onmessage);
+            }
+            else {
+                const echo = this.readyState === 1;
+                if (echo)
+                    this.#port.postMessage({ t: "c", code: f.code, reason: f.reason }); // close handshake
+                this.readyState = 3;
+                this.#stopHeartbeat();
+                this.#port.close();
+                this.#emit(new CellsCloseEvent("close", { code: f.code, reason: f.reason, wasClean: true }), this.onclose);
+            }
+        }
+        send(data) {
+            if (this.readyState === 0)
+                throw new DOMException("Still in CONNECTING state.", "InvalidStateError");
+            if (this.readyState !== 1)
+                return; // spec: silently discarded after closing
+            if (data instanceof Blob) {
+                this.#buffered += data.size;
+                void data.arrayBuffer().then((b) => this.readyState === 1 && this.#post(b));
+                return;
+            }
+            const d = toFrameData(data);
+            this.#buffered += byteSize(d);
+            this.#post(d);
+        }
+        #post(d) {
+            this.#unacked.push(byteSize(d));
+            this.#port.postMessage({ t: "m", d }, typeof d === "string" ? [] : [d]);
+        }
+        close(code, reason) {
+            checkClose(code, reason);
+            if (this.readyState >= 2)
+                return;
+            if (this.readyState === 0) {
+                this.#pendingClose = { code, reason };
+                this.readyState = 2;
+                return;
+            }
+            this.readyState = 2;
+            this.#port.postMessage({ t: "c", code: code ?? 1005, reason: reason ?? "" });
+        }
+    }
+    return CellsWebSocket;
+}
+//# sourceMappingURL=client.js.map

package/dist/ws/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/ws/client.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  byteSize,\n  CellsCloseEvent,\n  checkClose,\n  DEFAULT_HEARTBEAT_MS,\n  type Frame,\n  toFrameData,\n} from \"./frames.js\";\n\n/** Opens the transport of a socket: resolves with the MessagePort once the server accepted (101). */\nexport type WebSocketConnector = (\n  url: string,\n  protocols: string[],\n) => Promise<{ port: MessagePort; protocol?: string }>;\n\ntype Handler = ((ev: any) => void) | null;\n\n/**\n * A WHATWG-WebSocket-compatible class whose transport is a MessagePort obtained\n * from `connect` (page → ServiceWorker → owning shard worker, or in-process).\n * Installed for user code through webrun-modules `~deps` (provided `WebSocket`),\n * so the real `globalThis.WebSocket` is left untouched.\n */\n/** RFC 7230 token (subprotocol names). */\nconst TOKEN = /^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$/;\n\nexport interface CellsWebSocketOptions {\n  /** Liveness ping period (ms); 0 disables. The peer is declared dead after 2 missed periods. */\n  heartbeatMs?: number;\n  /**\n   * Interval timers for the heartbeat. On a page's main thread pass worker-timers'\n   * `setInterval`/`clearInterval`: background-tab throttling of main-thread timers would\n   * otherwise delay pings and make the server drop a live socket. Workers and Node do not\n   * throttle, so the built-in timers are the default.\n   */\n  timers?: { setInterval(fn: () => void, ms: number): unknown; clearInterval(id: unknown): void };\n}\n\n/**\n * A WHATWG `WebSocket` class whose sockets reach a Worker through `connect`. Typed as the\n * platform's `WebSocket` (the class implements that interface; its own state is private).\n */\nexport function createWebSocketClass(\n  connect: WebSocketConnector,\n  options: CellsWebSocketOptions = {},\n): typeof WebSocket {\n  const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;\n  const timers = options.timers ?? {\n    setInterval: (fn: () => void, ms: number) => setInterval(fn, ms),\n    clearInterval: (id: unknown) => clearInterval(id as ReturnType<typeof setInterval>),\n  };\n  class CellsWebSocket extends EventTarget {\n    static readonly CONNECTING = 0;\n    static readonly OPEN = 1;\n    static readonly CLOSING = 2;\n    static readonly CLOSED = 3;\n    readonly CONNECTING = 0;\n    readonly OPEN = 1;\n    readonly CLOSING = 2;\n    readonly CLOSED = 3;\n\n    readonly url: string;\n    readyState = 0;\n    protocol = \"\";\n    extensions = \"\";\n    #buffered = 0;\n    /** Sizes of the messages posted and not acknowledged yet, in order (the port keeps it). */\n    #unacked: number[] = [];\n    /** Bytes sent and not yet received by the server end (it acknowledges each message). */\n    get bufferedAmount(): number {\n      return this.#buffered;\n    }\n    #binaryType: \"blob\" | \"arraybuffer\" = \"blob\";\n    get binaryType(): \"blob\" | \"arraybuffer\" {\n      return this.#binaryType;\n    }\n    /** Only \"blob\" and \"arraybuffer\" are taken; any other value is ignored (WHATWG). */\n    set binaryType(v: \"blob\" | \"arraybuffer\") {\n      if (v === \"blob\" || v === \"arraybuffer\") this.#binaryType = v;\n    }\n    onopen: Handler = null;\n    onmessage: Handler = null;\n    onclose: Handler = null;\n    onerror: Handler = null;\n    #port: MessagePort | undefined;\n    #pendingClose: { code?: number; reason?: string } | undefined;\n    #beat: unknown;\n    #lastPong = 0;\n\n    #startHeartbeat(): void {\n      if (!heartbeatMs) return;\n      this.#lastPong = Date.now();\n      this.#beat = timers.setInterval(() => {\n        if (this.readyState >= 3) return this.#stopHeartbeat();\n        if (Date.now() - this.#lastPong > 2 * heartbeatMs) return this.#fail(); // peer gone\n        this.#port?.postMessage({ t: \"p\", hb: heartbeatMs } satisfies Frame);\n      }, heartbeatMs);\n      this.#port?.postMessage({ t: \"p\", hb: heartbeatMs } satisfies Frame);\n    }\n    #stopHeartbeat(): void {\n      if (this.#beat !== undefined) timers.clearInterval(this.#beat);\n      this.#beat = undefined;\n    }\n\n    constructor(url: string | URL, protocols: string | string[] = []) {\n      super();\n      // WHATWG \"new WebSocket(url, protocols)\" validation, in spec order.\n      let u: URL;\n      try {\n        u = new URL(String(url), (globalThis as any).location?.href ?? \"http://localhost/\");\n      } catch {\n        throw new DOMException(`The URL '${String(url)}' is invalid.`, \"SyntaxError\");\n      }\n      if (u.protocol === \"http:\") u.protocol = \"ws:\";\n      if (u.protocol === \"https:\") u.protocol = \"wss:\";\n      if (u.protocol !== \"ws:\" && u.protocol !== \"wss:\")\n        throw new DOMException(`The URL's scheme must be either 'ws' or 'wss'.`, \"SyntaxError\");\n      if (u.hash || String(url).includes(\"#\"))\n        throw new DOMException(\"The URL contains a fragment identifier.\", \"SyntaxError\");\n      const list = typeof protocols === \"string\" ? [protocols] : [...protocols];\n      const seen = new Set<string>();\n      for (const p of list) {\n        if (!TOKEN.test(p))\n          throw new DOMException(`The subprotocol '${p}' is invalid.`, \"SyntaxError\");\n        if (seen.has(p.toLowerCase()))\n          throw new DOMException(`The subprotocol '${p}' is duplicated.`, \"SyntaxError\");\n        seen.add(p.toLowerCase());\n      }\n      this.url = u.toString();\n      connect(this.url, list).then(\n        ({ port, protocol }) => this.#opened(port, protocol ?? \"\"),\n        () => this.#fail(),\n      );\n    }\n\n    #emit(ev: Event, handler: Handler): void {\n      handler?.call(this, ev);\n      this.dispatchEvent(ev);\n    }\n\n    #opened(port: MessagePort, protocol: string): void {\n      if (this.readyState === 3) {\n        port.close();\n        return;\n      }\n      this.#port = port;\n      this.protocol = protocol;\n      port.onmessage = (e) => this.#frame(e.data as Frame);\n      port.start?.();\n      if (this.#pendingClose) {\n        // close() was called while connecting\n        this.readyState = 2;\n        port.postMessage({\n          t: \"c\",\n          code: this.#pendingClose.code ?? 1000,\n          reason: this.#pendingClose.reason ?? \"\",\n        } satisfies Frame);\n        return;\n      }\n      this.readyState = 1;\n      this.#startHeartbeat();\n      this.#emit(new Event(\"open\"), this.onopen);\n    }\n\n    #fail(): void {\n      if (this.readyState === 3) return;\n      this.#stopHeartbeat();\n      this.#port?.close();\n      this.readyState = 3;\n      this.#emit(new Event(\"error\"), this.onerror);\n      this.#emit(\n        new CellsCloseEvent(\"close\", { code: 1006, reason: \"\", wasClean: false }),\n        this.onclose,\n      );\n    }\n\n    #frame(f: Frame): void {\n      if (f.t === \"q\") {\n        this.#lastPong = Date.now();\n        return;\n      }\n      if (f.t === \"p\") return;\n      if (f.t === \"a\") {\n        this.#buffered -= this.#unacked.shift() ?? 0;\n        return;\n      }\n      if (f.t === \"m\") {\n        if (this.readyState !== 1) return;\n        let data: unknown = f.d;\n        if (typeof data !== \"string\" && this.binaryType === \"blob\")\n          data = new Blob([data as ArrayBuffer]);\n        this.#emit(\n          new MessageEvent(\"message\", { data, origin: new URL(this.url).origin }),\n          this.onmessage,\n        );\n      } else {\n        const echo = this.readyState === 1;\n        if (echo)\n          this.#port!.postMessage({ t: \"c\", code: f.code, reason: f.reason } satisfies Frame); // close handshake\n        this.readyState = 3;\n        this.#stopHeartbeat();\n        this.#port!.close();\n        this.#emit(\n          new CellsCloseEvent(\"close\", { code: f.code, reason: f.reason, wasClean: true }),\n          this.onclose,\n        );\n      }\n    }\n\n    send(data: string | ArrayBuffer | ArrayBufferView | Blob): void {\n      if (this.readyState === 0)\n        throw new DOMException(\"Still in CONNECTING state.\", \"InvalidStateError\");\n      if (this.readyState !== 1) return; // spec: silently discarded after closing\n      if (data instanceof Blob) {\n        this.#buffered += data.size;\n        void data.arrayBuffer().then((b) => this.readyState === 1 && this.#post(b));\n        return;\n      }\n      const d = toFrameData(data);\n      this.#buffered += byteSize(d);\n      this.#post(d);\n    }\n\n    #post(d: string | ArrayBuffer): void {\n      this.#unacked.push(byteSize(d));\n      this.#port!.postMessage({ t: \"m\", d } satisfies Frame, typeof d === \"string\" ? [] : [d]);\n    }\n\n    close(code?: number, reason?: string): void {\n      checkClose(code, reason);\n      if (this.readyState >= 2) return;\n      if (this.readyState === 0) {\n        this.#pendingClose = { code, reason };\n        this.readyState = 2;\n        return;\n      }\n      this.readyState = 2;\n      this.#port!.postMessage({ t: \"c\", code: code ?? 1005, reason: reason ?? \"\" } satisfies Frame);\n    }\n  }\n  return CellsWebSocket as unknown as typeof WebSocket;\n}\n\nexport type CellsWebSocketClass = ReturnType<typeof createWebSocketClass>;\n"]}

package/dist/ws/control.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Control channel of a shard link: a raw MessagePort next to the HTTP links,
+ * used for what HTTP-over-Duplex cannot carry — transferring WebSocket ports.
+ *
+ * Messages (the port rides in the payload so this works in browsers and Node):
+ *   router → shard   { t: "ws-connect", id, url, protocols, headers }
+ *   shard  → router  { t: "ws-accept", id, protocol, port }   (reply, or cross-shard hand-over)
+ *   shard  → router  { t: "ws-refuse", id, message }
+ * Ids: "r:<n>" = opened by the router (a page's socket); "s<shard>:<n>" = opened by a
+ * Worker running in shard <shard> through a stub in another shard.
+ */
+export interface ControlPort {
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    onmessage: ((ev: MessageEvent) => void) | null;
+    start?(): void;
+}
+export type ControlMessage = {
+    t: "ws-connect";
+    id: string;
+    url: string;
+    protocols: string[];
+    headers?: [string, string][];
+} | {
+    t: "ws-accept";
+    id: string;
+    protocol?: string;
+    port: MessagePort;
+} | {
+    t: "ws-refuse";
+    id: string;
+    message: string;
+};
+/** Shard that must receive a control message addressed by id, or undefined for the router. */
+export declare function shardOfControlId(id: string): number | undefined;
+/** Waits for ports by id; tolerates a port arriving before anyone waits for it. */
+export declare class PortRendezvous {
+    #private;
+    deliver(id: string, value: {
+        port: MessagePort;
+        protocol?: string;
+    } | Error): void;
+    wait(id: string, timeoutMs?: number): Promise<{
+        port: MessagePort;
+        protocol?: string;
+    }>;
+    /** Fails every waiter whose id matches (e.g. its shard's owner is gone). */
+    failAll(match: (id: string) => boolean, error: Error): void;
+}

package/dist/ws/control.js

@@ -0,0 +1,44 @@
+/** Shard that must receive a control message addressed by id, or undefined for the router. */
+export function shardOfControlId(id) {
+    const m = /^s(\d+):/.exec(id);
+    return m ? Number(m[1]) : undefined;
+}
+/** Waits for ports by id; tolerates a port arriving before anyone waits for it. */
+export class PortRendezvous {
+    #arrived = new Map();
+    #waiting = new Map();
+    deliver(id, value) {
+        const w = this.#waiting.get(id);
+        if (!w)
+            return void this.#arrived.set(id, value);
+        this.#waiting.delete(id);
+        value instanceof Error ? w.reject(value) : w.resolve(value);
+    }
+    wait(id, timeoutMs = 15_000) {
+        const early = this.#arrived.get(id);
+        if (early) {
+            this.#arrived.delete(id);
+            return early instanceof Error ? Promise.reject(early) : Promise.resolve(early);
+        }
+        return new Promise((resolve, reject) => {
+            const t = setTimeout(() => {
+                this.#waiting.delete(id);
+                reject(new Error(`WebSocket port ${id} did not arrive within ${timeoutMs} ms`));
+            }, timeoutMs);
+            this.#waiting.set(id, {
+                resolve: (v) => (clearTimeout(t), resolve(v)),
+                reject: (e) => (clearTimeout(t), reject(e)),
+            });
+        });
+    }
+    /** Fails every waiter whose id matches (e.g. its shard's owner is gone). */
+    failAll(match, error) {
+        for (const [id, w] of [...this.#waiting]) {
+            if (!match(id))
+                continue;
+            this.#waiting.delete(id);
+            w.reject(error);
+        }
+    }
+}
+//# sourceMappingURL=control.js.map

package/dist/ws/control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/ws/control.ts"],"names":[],"mappings":"AAsBA,8FAA8F;AAC9F,MAAM,UAAU,gBAAgB,CAAC,EAAU;IACzC,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACtC,CAAC;AAED,mFAAmF;AACnF,MAAM,OAAO,cAAc;IACzB,QAAQ,GAAG,IAAI,GAAG,EAA4D,CAAC;IAC/E,QAAQ,GAAG,IAAI,GAAG,EAGf,CAAC;IAEJ,OAAO,CAAC,EAAU,EAAE,KAAuD;QACzE,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,CAAC,EAAU,EAAE,SAAS,GAAG,MAAM;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACzB,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE;gBACxB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACzB,MAAM,CAAC,IAAI,KAAK,CAAC,kBAAkB,EAAE,0BAA0B,SAAS,KAAK,CAAC,CAAC,CAAC;YAClF,CAAC,EAAE,SAAS,CAAC,CAAC;YACd,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE;gBACpB,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;gBAC7C,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;aAC5C,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,OAAO,CAAC,KAA8B,EAAE,KAAY;QAClD,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAAE,SAAS;YACzB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACzB,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF","sourcesContent":["/**\n * Control channel of a shard link: a raw MessagePort next to the HTTP links,\n * used for what HTTP-over-Duplex cannot carry — transferring WebSocket ports.\n *\n * Messages (the port rides in the payload so this works in browsers and Node):\n *   router → shard   { t: \"ws-connect\", id, url, protocols, headers }\n *   shard  → router  { t: \"ws-accept\", id, protocol, port }   (reply, or cross-shard hand-over)\n *   shard  → router  { t: \"ws-refuse\", id, message }\n * Ids: \"r:<n>\" = opened by the router (a page's socket); \"s<shard>:<n>\" = opened by a\n * Worker running in shard <shard> through a stub in another shard.\n */\nexport interface ControlPort {\n  postMessage(message: unknown, transfer?: Transferable[]): void;\n  onmessage: ((ev: MessageEvent) => void) | null;\n  start?(): void;\n}\n\nexport type ControlMessage =\n  | { t: \"ws-connect\"; id: string; url: string; protocols: string[]; headers?: [string, string][] }\n  | { t: \"ws-accept\"; id: string; protocol?: string; port: MessagePort }\n  | { t: \"ws-refuse\"; id: string; message: string };\n\n/** Shard that must receive a control message addressed by id, or undefined for the router. */\nexport function shardOfControlId(id: string): number | undefined {\n  const m = /^s(\\d+):/.exec(id);\n  return m ? Number(m[1]) : undefined;\n}\n\n/** Waits for ports by id; tolerates a port arriving before anyone waits for it. */\nexport class PortRendezvous {\n  #arrived = new Map<string, { port: MessagePort; protocol?: string } | Error>();\n  #waiting = new Map<\n    string,\n    { resolve: (v: { port: MessagePort; protocol?: string }) => void; reject: (e: Error) => void }\n  >();\n\n  deliver(id: string, value: { port: MessagePort; protocol?: string } | Error): void {\n    const w = this.#waiting.get(id);\n    if (!w) return void this.#arrived.set(id, value);\n    this.#waiting.delete(id);\n    value instanceof Error ? w.reject(value) : w.resolve(value);\n  }\n\n  wait(id: string, timeoutMs = 15_000): Promise<{ port: MessagePort; protocol?: string }> {\n    const early = this.#arrived.get(id);\n    if (early) {\n      this.#arrived.delete(id);\n      return early instanceof Error ? Promise.reject(early) : Promise.resolve(early);\n    }\n    return new Promise((resolve, reject) => {\n      const t = setTimeout(() => {\n        this.#waiting.delete(id);\n        reject(new Error(`WebSocket port ${id} did not arrive within ${timeoutMs} ms`));\n      }, timeoutMs);\n      this.#waiting.set(id, {\n        resolve: (v) => (clearTimeout(t), resolve(v)),\n        reject: (e) => (clearTimeout(t), reject(e)),\n      });\n    });\n  }\n\n  /** Fails every waiter whose id matches (e.g. its shard's owner is gone). */\n  failAll(match: (id: string) => boolean, error: Error): void {\n    for (const [id, w] of [...this.#waiting]) {\n      if (!match(id)) continue;\n      this.#waiting.delete(id);\n      w.reject(error);\n    }\n  }\n}\n"]}

package/dist/ws/frames.d.ts

@@ -0,0 +1,38 @@
+/** Wire protocol of a WebSocket carried by a MessagePort (both directions). */
+export type Frame = {
+    t: "m";
+    d: string | ArrayBuffer;
+} | {
+    t: "c";
+    code: number;
+    reason: string;
+} | {
+    t: "p";
+    hb: number;
+} | {
+    t: "q";
+} | {
+    t: "a";
+};
+/**
+ * MessagePorts never report that the other side died (no `close` event in
+ * browsers), so both ends run a heartbeat: the client pings every `hb` ms and
+ * closes with 1006 when pongs stop for 2·hb; the server closes with 1006 when
+ * pings stop for 3·hb. This is what makes a socket notice a closed tab.
+ */
+export declare const DEFAULT_HEARTBEAT_MS = 10000;
+/** What a message adds to the sender's `bufferedAmount` (WHATWG: UTF-8 bytes of a string). */
+export declare function byteSize(d: string | ArrayBuffer): number;
+export declare function toFrameData(data: unknown): string | ArrayBuffer;
+export declare function checkClose(code?: number, reason?: string): void;
+/** CloseEvent is not a global in every runtime (Node 22): a compatible Event subclass. */
+export declare class CellsCloseEvent extends Event {
+    readonly code: number;
+    readonly reason: string;
+    readonly wasClean: boolean;
+    constructor(type: string, init?: {
+        code?: number;
+        reason?: string;
+        wasClean?: boolean;
+    });
+}

package/dist/ws/frames.js

@@ -0,0 +1,39 @@
+/**
+ * MessagePorts never report that the other side died (no `close` event in
+ * browsers), so both ends run a heartbeat: the client pings every `hb` ms and
+ * closes with 1006 when pongs stop for 2·hb; the server closes with 1006 when
+ * pings stop for 3·hb. This is what makes a socket notice a closed tab.
+ */
+export const DEFAULT_HEARTBEAT_MS = 10_000;
+/** What a message adds to the sender's `bufferedAmount` (WHATWG: UTF-8 bytes of a string). */
+export function byteSize(d) {
+    return typeof d === "string" ? new TextEncoder().encode(d).byteLength : d.byteLength;
+}
+export function toFrameData(data) {
+    if (typeof data === "string")
+        return data;
+    if (data instanceof ArrayBuffer)
+        return data.slice(0);
+    if (ArrayBuffer.isView(data))
+        return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+    throw new TypeError("WebSocket.send: unsupported data type (string, ArrayBuffer or ArrayBufferView)");
+}
+export function checkClose(code, reason) {
+    if (code !== undefined && code !== 1000 && (code < 3000 || code > 4999))
+        throw new DOMException(`The close code must be either 1000, or between 3000 and 4999. ${code} is neither.`, "InvalidAccessError");
+    if (reason !== undefined && new TextEncoder().encode(reason).byteLength > 123)
+        throw new DOMException("The close reason must not be greater than 123 UTF-8 bytes.", "SyntaxError");
+}
+/** CloseEvent is not a global in every runtime (Node 22): a compatible Event subclass. */
+export class CellsCloseEvent extends Event {
+    code;
+    reason;
+    wasClean;
+    constructor(type, init = {}) {
+        super(type);
+        this.code = init.code ?? 1005;
+        this.reason = init.reason ?? "";
+        this.wasClean = init.wasClean ?? false;
+    }
+}
+//# sourceMappingURL=frames.js.map

package/dist/ws/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../src/ws/frames.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C,8FAA8F;AAC9F,MAAM,UAAU,QAAQ,CAAC,CAAuB;IAC9C,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;AACvF,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,IAAI,YAAY,WAAW;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAgB,CAAC;IAC9F,MAAM,IAAI,SAAS,CACjB,gFAAgF,CACjF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAa,EAAE,MAAe;IACvD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,IAAI,CAAC;QACrE,MAAM,IAAI,YAAY,CACpB,iEAAiE,IAAI,cAAc,EACnF,oBAAoB,CACrB,CAAC;IACJ,IAAI,MAAM,KAAK,SAAS,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,UAAU,GAAG,GAAG;QAC3E,MAAM,IAAI,YAAY,CACpB,4DAA4D,EAC5D,aAAa,CACd,CAAC;AACN,CAAC;AAED,0FAA0F;AAC1F,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAS;IACb,MAAM,CAAS;IACf,QAAQ,CAAU;IAC3B,YAAY,IAAY,EAAE,IAAI,GAA2D,EAAE;QACzF,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;IACzC,CAAC;CACF","sourcesContent":["/** Wire protocol of a WebSocket carried by a MessagePort (both directions). */\nexport type Frame =\n  | { t: \"m\"; d: string | ArrayBuffer } // message\n  | { t: \"c\"; code: number; reason: string } // close (initiating or echo)\n  | { t: \"p\"; hb: number } // ping (client → server), carries the heartbeat period\n  | { t: \"q\" } // pong (server → client)\n  | { t: \"a\" }; // ack: the server end dispatched the oldest message not acknowledged yet\n\n/**\n * MessagePorts never report that the other side died (no `close` event in\n * browsers), so both ends run a heartbeat: the client pings every `hb` ms and\n * closes with 1006 when pongs stop for 2·hb; the server closes with 1006 when\n * pings stop for 3·hb. This is what makes a socket notice a closed tab.\n */\nexport const DEFAULT_HEARTBEAT_MS = 10_000;\n\n/** What a message adds to the sender's `bufferedAmount` (WHATWG: UTF-8 bytes of a string). */\nexport function byteSize(d: string | ArrayBuffer): number {\n  return typeof d === \"string\" ? new TextEncoder().encode(d).byteLength : d.byteLength;\n}\n\nexport function toFrameData(data: unknown): string | ArrayBuffer {\n  if (typeof data === \"string\") return data;\n  if (data instanceof ArrayBuffer) return data.slice(0);\n  if (ArrayBuffer.isView(data))\n    return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;\n  throw new TypeError(\n    \"WebSocket.send: unsupported data type (string, ArrayBuffer or ArrayBufferView)\",\n  );\n}\n\nexport function checkClose(code?: number, reason?: string): void {\n  if (code !== undefined && code !== 1000 && (code < 3000 || code > 4999))\n    throw new DOMException(\n      `The close code must be either 1000, or between 3000 and 4999. ${code} is neither.`,\n      \"InvalidAccessError\",\n    );\n  if (reason !== undefined && new TextEncoder().encode(reason).byteLength > 123)\n    throw new DOMException(\n      \"The close reason must not be greater than 123 UTF-8 bytes.\",\n      \"SyntaxError\",\n    );\n}\n\n/** CloseEvent is not a global in every runtime (Node 22): a compatible Event subclass. */\nexport class CellsCloseEvent extends Event {\n  readonly code: number;\n  readonly reason: string;\n  readonly wasClean: boolean;\n  constructor(type: string, init: { code?: number; reason?: string; wasClean?: boolean } = {}) {\n    super(type);\n    this.code = init.code ?? 1005;\n    this.reason = init.reason ?? \"\";\n    this.wasClean = init.wasClean ?? false;\n  }\n}\n"]}

package/dist/ws/server.d.ts

@@ -0,0 +1,99 @@
+declare const kPort: unique symbol;
+/**
+ * Cloudflare Workers' server-side WebSocket (one end of a WebSocketPair):
+ * events are delivered only after `accept()`; `send`/`close` as in workerd.
+ * Hibernation (`ctx.acceptWebSocket`) is a later prototype.
+ */
+export declare class CfWebSocket extends EventTarget {
+    #private;
+    static readonly READY_STATE_CONNECTING = 0;
+    static readonly READY_STATE_OPEN = 1;
+    static readonly READY_STATE_CLOSING = 2;
+    static readonly READY_STATE_CLOSED = 3;
+    readyState: number;
+    url: string | null;
+    protocol: string | null;
+    extensions: string | null;
+    /** How binary messages arrive; other values are ignored, as in browsers. */
+    get binaryType(): "blob" | "arraybuffer";
+    set binaryType(v: "blob" | "arraybuffer");
+    [kPort]: MessagePort | undefined;
+    constructor(port: MessagePort);
+    /** The other end of the WebSocketPair (the runtime checks how the server end was accepted). */
+    peer?: CfWebSocket;
+    /** Accepted through ctx.acceptWebSocket() (hibernatable) rather than accept(). */
+    hibernatable: boolean;
+    get accepted(): boolean;
+    accept(): void;
+    serializeAttachment(v: unknown): void;
+    deserializeAttachment(): unknown;
+    /**
+     * Closes every server end accepted in this realm with 1001 (going away). A shard worker that
+     * hands its cells to another tab does it before it stops, so that clients reconnect at once
+     * instead of noticing through the heartbeat; Worker code cannot send 1001 itself (`close`).
+     */
+    static goAway(reason?: string): void;
+    send(data: string | ArrayBuffer | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * The `WebSocket` global of Worker code. On workerd one class covers both ends of a
+ * WebSocketPair and the client sockets `new WebSocket(url)` opens, and libraries rely on that:
+ * the Agents SDK (partyserver) reads attachments with
+ * `WebSocket.prototype.deserializeAttachment.call(ws)` and compares `readyState` with
+ * `WebSocket.READY_STATE_OPEN`. So its prototype is the server end's (`CfWebSocket`), its
+ * statics are workerd's, `instanceof` holds for both kinds, and `new WebSocket(url)` still opens
+ * the host's client socket.
+ */
+export declare const WorkersWebSocket: typeof CfWebSocket & {
+    new (url: string, protocols?: string | string[]): CfWebSocket;
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+/** `new WebSocketPair()` → `{ 0: client, 1: server }`, entangled over a MessageChannel. */
+export declare class WebSocketPair {
+    0: CfWebSocket;
+    1: CfWebSocket;
+    constructor();
+    /** `const [client, server] = new WebSocketPair()`, as in workerd. */
+    [Symbol.iterator](): IterableIterator<CfWebSocket>;
+}
+/**
+ * `WebSocketPair` under the `websocket_standard_binary_type` compatibility flag: both ends
+ * start with `binaryType` "blob", as browsers' WebSockets do. Without it they start with
+ * "arraybuffer", workerd's older default.
+ */
+export declare class StandardWebSocketPair extends WebSocketPair {
+    constructor();
+}
+/**
+ * Detaches the transport of the CLIENT end returned in a 101 response, so the
+ * runtime can hand the raw MessagePort to the real client (transferable).
+ */
+export declare function takeClientPort(ws: CfWebSocket): MessagePort;
+export declare class CellsResponse extends Response {
+    #private;
+    readonly webSocket: CfWebSocket | null;
+    constructor(body?: BodyInit | null, init?: ResponseInit & {
+        webSocket?: CfWebSocket | null;
+    });
+    get status(): number;
+    /**
+     * Every platform `Response` is a Workers `Response`, as on workerd: `Response.json()`,
+     * `Response.redirect()` and `Response.error()` (the platform's static helpers, which build
+     * platform instances, not instances of this subclass) and `fetch()` results pass
+     * `instanceof Response` in Worker code. Astro checks every endpoint's result that way.
+     */
+    static [Symbol.hasInstance](v: unknown): boolean;
+    static json(data: unknown, init?: ResponseInit): Response;
+    static redirect(url: string | URL, status?: number): Response;
+}
+/** Workers `WebSocketRequestResponsePair` (ctx.setWebSocketAutoResponse). */
+export declare class WebSocketRequestResponsePair {
+    readonly request: string;
+    readonly response: string;
+    constructor(request: string, response: string);
+}
+export {};