@statewalker/cellb 0.0.0-stage → 0.1.0

package/dist/ws/server.js

@@ -0,0 +1,295 @@
+import { CellsCloseEvent, checkClose, toFrameData } from "./frames.js";
+const kPort = Symbol("cellb.ws.port");
+/** Server ends accepted in this realm and not yet closed (see `CfWebSocket.goAway`). */
+const acceptedEnds = new Set();
+/**
+ * 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 class CfWebSocket extends EventTarget {
+    static READY_STATE_CONNECTING = 0;
+    static READY_STATE_OPEN = 1;
+    static READY_STATE_CLOSING = 2;
+    static READY_STATE_CLOSED = 3;
+    readyState = 1;
+    url = null;
+    protocol = null;
+    extensions = null;
+    #binaryType = "arraybuffer";
+    /** How binary messages arrive; other values are ignored, as in browsers. */
+    get binaryType() {
+        return this.#binaryType;
+    }
+    set binaryType(v) {
+        if (v === "blob" || v === "arraybuffer")
+            this.#binaryType = v;
+    }
+    [kPort];
+    #accepted = false;
+    #queued = [];
+    #attachment;
+    #lastPing = 0;
+    #watch;
+    constructor(port) {
+        super();
+        this[kPort] = port;
+        port.onmessage = (e) => {
+            const f = e.data;
+            if (f.t === "p")
+                return this.#ping(f.hb); // answered even before accept()
+            if (this.#accepted)
+                this.#frame(f);
+            else
+                this.#queued.push(f);
+        };
+    }
+    /** Heartbeat: answer the client's ping; close 1006 when pings stop for 3 periods. */
+    #ping(hb) {
+        this.#lastPing = Date.now();
+        this[kPort]?.postMessage({ t: "q" });
+        if (this.#watch || !hb)
+            return;
+        this.#watch = setInterval(() => {
+            if (this.readyState === 3)
+                return clearInterval(this.#watch);
+            if (Date.now() - this.#lastPing > 3 * hb)
+                this.#gone();
+        }, hb);
+    }
+    /** The client stopped pinging (tab closed, worker killed): abnormal closure. */
+    #gone() {
+        clearInterval(this.#watch);
+        if (this.readyState === 3)
+            return;
+        this.readyState = 3;
+        acceptedEnds.delete(this);
+        this[kPort]?.close();
+        this.dispatchEvent(new CellsCloseEvent("close", { code: 1006, reason: "", wasClean: false }));
+    }
+    /** The other end of the WebSocketPair (the runtime checks how the server end was accepted). */
+    peer;
+    /** Accepted through ctx.acceptWebSocket() (hibernatable) rather than accept(). */
+    hibernatable = false;
+    get accepted() {
+        return this.#accepted;
+    }
+    accept() {
+        if (this.#accepted)
+            return;
+        if (!this[kPort])
+            throw new TypeError("This WebSocket end was handed to a client; it cannot be accepted.");
+        this.#accepted = true;
+        acceptedEnds.add(this);
+        this[kPort].start?.();
+        for (const f of this.#queued.splice(0))
+            this.#frame(f);
+    }
+    serializeAttachment(v) {
+        this.#attachment = structuredClone(v);
+    }
+    deserializeAttachment() {
+        return structuredClone(this.#attachment);
+    }
+    #frame(f) {
+        if (f.t === "m") {
+            const data = typeof f.d !== "string" && this.#binaryType === "blob" ? new Blob([f.d]) : f.d;
+            this.dispatchEvent(new MessageEvent("message", { data }));
+            this[kPort]?.postMessage({ t: "a" }); // the sender's bufferedAmount drains
+            return;
+        }
+        if (f.t !== "c")
+            return;
+        const wasOpen = this.readyState === 1;
+        if (wasOpen)
+            this[kPort].postMessage({ t: "c", code: f.code, reason: f.reason });
+        this.readyState = 3;
+        acceptedEnds.delete(this);
+        clearInterval(this.#watch);
+        this[kPort].close();
+        this.dispatchEvent(new CellsCloseEvent("close", { code: f.code, reason: f.reason, wasClean: true }));
+    }
+    /**
+     * 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 = "moving to another worker") {
+        for (const ws of acceptedEnds) {
+            acceptedEnds.delete(ws);
+            if (ws.readyState >= 2)
+                continue;
+            ws.readyState = 2;
+            ws[kPort]?.postMessage({ t: "c", code: 1001, reason });
+        }
+    }
+    send(data) {
+        // celld lets either end of a pair send before accept() (workerd refuses); frames wait in
+        // the port until the other end listens.
+        if (this.readyState !== 1)
+            throw new TypeError("Can't call WebSocket send() after close().");
+        const d = toFrameData(data);
+        this[kPort].postMessage({ t: "m", d }, typeof d === "string" ? [] : [d]);
+    }
+    close(code, reason) {
+        checkClose(code, reason);
+        if (this.readyState >= 2)
+            return;
+        this.readyState = 2;
+        this[kPort].postMessage({ t: "c", code: code ?? 1005, reason: reason ?? "" });
+    }
+}
+/** The host's own WebSocket (Node's, or the browser's): the client sockets Worker code opens. */
+const HostWebSocket = globalThis.WebSocket;
+/**
+ * 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 const WorkersWebSocket = (() => {
+    function WebSocket(url, protocols) {
+        if (!new.target)
+            throw new TypeError("Failed to construct 'WebSocket': Please use the 'new' operator.");
+        if (!HostWebSocket)
+            throw new Error("WebSocket clients are not available in this realm.");
+        return new HostWebSocket(url, protocols);
+    }
+    WebSocket.prototype = CfWebSocket.prototype;
+    const states = { CONNECTING: 0, OPEN: 1, CLOSING: 2, CLOSED: 3 };
+    for (const [name, value] of Object.entries(states)) {
+        Object.defineProperty(WebSocket, name, { value, enumerable: true });
+        Object.defineProperty(WebSocket, `READY_STATE_${name}`, { value, enumerable: true });
+    }
+    Object.defineProperty(WebSocket, Symbol.hasInstance, {
+        value: (v) => v instanceof CfWebSocket || (HostWebSocket !== undefined && v instanceof HostWebSocket),
+    });
+    return WebSocket;
+})();
+/** `new WebSocketPair()` → `{ 0: client, 1: server }`, entangled over a MessageChannel. */
+export class WebSocketPair {
+    0;
+    1;
+    constructor() {
+        const { port1, port2 } = new MessageChannel();
+        this[0] = new CfWebSocket(port1);
+        this[1] = new CfWebSocket(port2);
+        this[0].peer = this[1];
+        this[1].peer = this[0];
+    }
+    /** `const [client, server] = new WebSocketPair()`, as in workerd. */
+    *[Symbol.iterator]() {
+        yield this[0];
+        yield this[1];
+    }
+}
+/**
+ * `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 class StandardWebSocketPair extends WebSocketPair {
+    constructor() {
+        super();
+        this[0].binaryType = "blob";
+        this[1].binaryType = "blob";
+    }
+}
+/**
+ * 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 function takeClientPort(ws) {
+    const port = ws[kPort];
+    if (!port)
+        throw new TypeError("WebSocket end already handed over");
+    ws[kPort] = undefined;
+    port.onmessage = null;
+    ws.readyState = 3; // handed over: this end must not answer pings any more
+    return port;
+}
+/**
+ * `Response` that also accepts Cloudflare's `{ status: 101, webSocket }` init —
+ * the platform `Response` rejects status 101. Provided to user code via ~deps.
+ */
+/** The platform `Response`, as this module sees it (it is external to user bundles). */
+const HostResponse = Response;
+/** Browsers drop `Set-Cookie` from every Response they build (Node keeps it). */
+const dropsSetCookie = !new HostResponse(null, { headers: { "set-cookie": "a=b" } }).headers.has("set-cookie");
+export class CellsResponse extends Response {
+    #status;
+    webSocket;
+    constructor(body, init = {}) {
+        const upgrade = init.status === 101;
+        // The init's members read one by one, as Fetch reads a dictionary: an init that is itself a
+        // Response (`new Response(body, response)`, as opencode's SDK does) keeps its headers and
+        // statusText, which a spread would drop (they are getters on its prototype).
+        super(upgrade ? null : body, {
+            status: upgrade ? 200 : init.status,
+            statusText: init.statusText,
+            headers: init.headers,
+        });
+        this.#status = init.status ?? 200;
+        this.webSocket = init.webSocket ?? null;
+        if (dropsSetCookie) {
+            // In a browser the platform's headers drop `Set-Cookie`, which Workers set (Astro appends
+            // its cookies to the response): the response keeps its headers in a standalone `Headers`,
+            // the ones the platform derived (content-type) plus the Set-Cookie values of the init.
+            const headers = new Headers(super.headers);
+            const given = init.headers instanceof Headers ? init.headers : new Headers(init.headers);
+            for (const c of given.getSetCookie())
+                headers.append("set-cookie", c);
+            Object.defineProperty(this, "headers", {
+                value: headers,
+                configurable: true,
+                enumerable: true,
+            });
+        }
+    }
+    get status() {
+        // Static helpers (CellsResponse.json(), .redirect(), .error()) may build instances
+        // without running this constructor: fall back to the platform's status.
+        return #status in this ? this.#status : super.status;
+    }
+    /**
+     * 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) {
+        return v instanceof HostResponse;
+    }
+    // In a browser the platform's static helpers build platform responses, whose headers drop
+    // `Set-Cookie`: these build instances of this class there (`Response.json()` is how most
+    // APIs answer, and their cookies are appended to it afterwards).
+    static json(data, init = {}) {
+        if (!dropsSetCookie)
+            return super.json(data, init);
+        const headers = new Headers(init.headers);
+        if (!headers.has("content-type"))
+            headers.set("content-type", "application/json");
+        return new CellsResponse(JSON.stringify(data), { ...init, headers });
+    }
+    static redirect(url, status = 302) {
+        if (!dropsSetCookie)
+            return super.redirect(url, status);
+        if (![301, 302, 303, 307, 308].includes(status))
+            throw new RangeError(`Invalid status ${status}`);
+        const base = globalThis.location?.href;
+        return new CellsResponse(null, { status, headers: { location: new URL(url, base).href } });
+    }
+}
+/** Workers `WebSocketRequestResponsePair` (ctx.setWebSocketAutoResponse). */
+export class WebSocketRequestResponsePair {
+    request;
+    response;
+    constructor(request, response) {
+        this.request = request;
+        this.response = response;
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/ws/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/ws/server.ts"],"names":[],"mappings":"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","sourcesContent":["import { CellsCloseEvent, checkClose, type Frame, toFrameData } from \"./frames.js\";\n\nconst kPort = Symbol(\"cellb.ws.port\");\n/** Server ends accepted in this realm and not yet closed (see `CfWebSocket.goAway`). */\nconst acceptedEnds = new Set<CfWebSocket>();\n\n/**\n * Cloudflare Workers' server-side WebSocket (one end of a WebSocketPair):\n * events are delivered only after `accept()`; `send`/`close` as in workerd.\n * Hibernation (`ctx.acceptWebSocket`) is a later prototype.\n */\nexport class CfWebSocket extends EventTarget {\n  static readonly READY_STATE_CONNECTING = 0;\n  static readonly READY_STATE_OPEN = 1;\n  static readonly READY_STATE_CLOSING = 2;\n  static readonly READY_STATE_CLOSED = 3;\n  readyState = 1;\n  url: string | null = null;\n\n  protocol: string | null = null;\n  extensions: string | null = null;\n  #binaryType: \"blob\" | \"arraybuffer\" = \"arraybuffer\";\n  /** How binary messages arrive; other values are ignored, as in browsers. */\n  get binaryType(): \"blob\" | \"arraybuffer\" {\n    return this.#binaryType;\n  }\n  set binaryType(v: \"blob\" | \"arraybuffer\") {\n    if (v === \"blob\" || v === \"arraybuffer\") this.#binaryType = v;\n  }\n  [kPort]: MessagePort | undefined;\n  #accepted = false;\n  #queued: Frame[] = [];\n  #attachment: unknown;\n\n  #lastPing = 0;\n  #watch: ReturnType<typeof setInterval> | undefined;\n\n  constructor(port: MessagePort) {\n    super();\n    this[kPort] = port;\n    port.onmessage = (e) => {\n      const f = e.data as Frame;\n      if (f.t === \"p\") return this.#ping(f.hb); // answered even before accept()\n      if (this.#accepted) this.#frame(f);\n      else this.#queued.push(f);\n    };\n  }\n\n  /** Heartbeat: answer the client's ping; close 1006 when pings stop for 3 periods. */\n  #ping(hb: number): void {\n    this.#lastPing = Date.now();\n    this[kPort]?.postMessage({ t: \"q\" } satisfies Frame);\n    if (this.#watch || !hb) return;\n    this.#watch = setInterval(() => {\n      if (this.readyState === 3) return clearInterval(this.#watch);\n      if (Date.now() - this.#lastPing > 3 * hb) this.#gone();\n    }, hb);\n  }\n\n  /** The client stopped pinging (tab closed, worker killed): abnormal closure. */\n  #gone(): void {\n    clearInterval(this.#watch);\n    if (this.readyState === 3) return;\n    this.readyState = 3;\n    acceptedEnds.delete(this);\n    this[kPort]?.close();\n    this.dispatchEvent(new CellsCloseEvent(\"close\", { code: 1006, reason: \"\", wasClean: false }));\n  }\n\n  /** The other end of the WebSocketPair (the runtime checks how the server end was accepted). */\n  peer?: CfWebSocket;\n  /** Accepted through ctx.acceptWebSocket() (hibernatable) rather than accept(). */\n  hibernatable = false;\n  get accepted(): boolean {\n    return this.#accepted;\n  }\n\n  accept(): void {\n    if (this.#accepted) return;\n    if (!this[kPort])\n      throw new TypeError(\"This WebSocket end was handed to a client; it cannot be accepted.\");\n    this.#accepted = true;\n    acceptedEnds.add(this);\n    this[kPort].start?.();\n    for (const f of this.#queued.splice(0)) this.#frame(f);\n  }\n\n  serializeAttachment(v: unknown): void {\n    this.#attachment = structuredClone(v);\n  }\n  deserializeAttachment(): unknown {\n    return structuredClone(this.#attachment);\n  }\n\n  #frame(f: Frame): void {\n    if (f.t === \"m\") {\n      const data = typeof f.d !== \"string\" && this.#binaryType === \"blob\" ? new Blob([f.d]) : f.d;\n      this.dispatchEvent(new MessageEvent(\"message\", { data }));\n      this[kPort]?.postMessage({ t: \"a\" } satisfies Frame); // the sender's bufferedAmount drains\n      return;\n    }\n    if (f.t !== \"c\") return;\n    const wasOpen = this.readyState === 1;\n    if (wasOpen)\n      this[kPort]!.postMessage({ t: \"c\", code: f.code, reason: f.reason } satisfies Frame);\n    this.readyState = 3;\n    acceptedEnds.delete(this);\n    clearInterval(this.#watch);\n    this[kPort]!.close();\n    this.dispatchEvent(\n      new CellsCloseEvent(\"close\", { code: f.code, reason: f.reason, wasClean: true }),\n    );\n  }\n\n  /**\n   * Closes every server end accepted in this realm with 1001 (going away). A shard worker that\n   * hands its cells to another tab does it before it stops, so that clients reconnect at once\n   * instead of noticing through the heartbeat; Worker code cannot send 1001 itself (`close`).\n   */\n  static goAway(reason = \"moving to another worker\"): void {\n    for (const ws of acceptedEnds) {\n      acceptedEnds.delete(ws);\n      if (ws.readyState >= 2) continue;\n      ws.readyState = 2;\n      ws[kPort]?.postMessage({ t: \"c\", code: 1001, reason } satisfies Frame);\n    }\n  }\n\n  send(data: string | ArrayBuffer | ArrayBufferView): void {\n    // celld lets either end of a pair send before accept() (workerd refuses); frames wait in\n    // the port until the other end listens.\n    if (this.readyState !== 1) throw new TypeError(\"Can't call WebSocket send() after close().\");\n    const d = toFrameData(data);\n    this[kPort]!.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    this.readyState = 2;\n    this[kPort]!.postMessage({ t: \"c\", code: code ?? 1005, reason: reason ?? \"\" } satisfies Frame);\n  }\n}\n\n/** The host's own WebSocket (Node's, or the browser's): the client sockets Worker code opens. */\nconst HostWebSocket = (\n  globalThis as { WebSocket?: new (url: string, p?: string | string[]) => object }\n).WebSocket;\n\n/**\n * The `WebSocket` global of Worker code. On workerd one class covers both ends of a\n * WebSocketPair and the client sockets `new WebSocket(url)` opens, and libraries rely on that:\n * the Agents SDK (partyserver) reads attachments with\n * `WebSocket.prototype.deserializeAttachment.call(ws)` and compares `readyState` with\n * `WebSocket.READY_STATE_OPEN`. So its prototype is the server end's (`CfWebSocket`), its\n * statics are workerd's, `instanceof` holds for both kinds, and `new WebSocket(url)` still opens\n * the host's client socket.\n */\nexport const WorkersWebSocket = (() => {\n  function WebSocket(this: unknown, url: string, protocols?: string | string[]): object {\n    if (!new.target)\n      throw new TypeError(\"Failed to construct 'WebSocket': Please use the 'new' operator.\");\n    if (!HostWebSocket) throw new Error(\"WebSocket clients are not available in this realm.\");\n    return new HostWebSocket(url, protocols);\n  }\n  WebSocket.prototype = CfWebSocket.prototype;\n  const states = { CONNECTING: 0, OPEN: 1, CLOSING: 2, CLOSED: 3 } as const;\n  for (const [name, value] of Object.entries(states)) {\n    Object.defineProperty(WebSocket, name, { value, enumerable: true });\n    Object.defineProperty(WebSocket, `READY_STATE_${name}`, { value, enumerable: true });\n  }\n  Object.defineProperty(WebSocket, Symbol.hasInstance, {\n    value: (v: unknown) =>\n      v instanceof CfWebSocket || (HostWebSocket !== undefined && v instanceof HostWebSocket),\n  });\n  return WebSocket as unknown as typeof CfWebSocket & {\n    new (url: string, protocols?: string | string[]): CfWebSocket;\n    readonly CONNECTING: 0;\n    readonly OPEN: 1;\n    readonly CLOSING: 2;\n    readonly CLOSED: 3;\n  };\n})();\n\n/** `new WebSocketPair()` → `{ 0: client, 1: server }`, entangled over a MessageChannel. */\nexport class WebSocketPair {\n  0: CfWebSocket;\n  1: CfWebSocket;\n  constructor() {\n    const { port1, port2 } = new MessageChannel();\n    this[0] = new CfWebSocket(port1);\n    this[1] = new CfWebSocket(port2);\n    this[0].peer = this[1];\n    this[1].peer = this[0];\n  }\n  /** `const [client, server] = new WebSocketPair()`, as in workerd. */\n  *[Symbol.iterator](): IterableIterator<CfWebSocket> {\n    yield this[0];\n    yield this[1];\n  }\n}\n\n/**\n * `WebSocketPair` under the `websocket_standard_binary_type` compatibility flag: both ends\n * start with `binaryType` \"blob\", as browsers' WebSockets do. Without it they start with\n * \"arraybuffer\", workerd's older default.\n */\nexport class StandardWebSocketPair extends WebSocketPair {\n  constructor() {\n    super();\n    this[0].binaryType = \"blob\";\n    this[1].binaryType = \"blob\";\n  }\n}\n\n/**\n * Detaches the transport of the CLIENT end returned in a 101 response, so the\n * runtime can hand the raw MessagePort to the real client (transferable).\n */\nexport function takeClientPort(ws: CfWebSocket): MessagePort {\n  const port = ws[kPort];\n  if (!port) throw new TypeError(\"WebSocket end already handed over\");\n  ws[kPort] = undefined;\n  port.onmessage = null;\n  ws.readyState = 3; // handed over: this end must not answer pings any more\n  return port;\n}\n\n/**\n * `Response` that also accepts Cloudflare's `{ status: 101, webSocket }` init —\n * the platform `Response` rejects status 101. Provided to user code via ~deps.\n */\n/** The platform `Response`, as this module sees it (it is external to user bundles). */\nconst HostResponse = Response;\n\n/** Browsers drop `Set-Cookie` from every Response they build (Node keeps it). */\nconst dropsSetCookie = !new HostResponse(null, { headers: { \"set-cookie\": \"a=b\" } }).headers.has(\n  \"set-cookie\",\n);\n\nexport class CellsResponse extends Response {\n  readonly #status: number;\n  readonly webSocket: CfWebSocket | null;\n  constructor(\n    body?: BodyInit | null,\n    init: ResponseInit & { webSocket?: CfWebSocket | null } = {},\n  ) {\n    const upgrade = init.status === 101;\n    // The init's members read one by one, as Fetch reads a dictionary: an init that is itself a\n    // Response (`new Response(body, response)`, as opencode's SDK does) keeps its headers and\n    // statusText, which a spread would drop (they are getters on its prototype).\n    super(upgrade ? null : body, {\n      status: upgrade ? 200 : init.status,\n      statusText: init.statusText,\n      headers: init.headers,\n    });\n    this.#status = init.status ?? 200;\n    this.webSocket = init.webSocket ?? null;\n    if (dropsSetCookie) {\n      // In a browser the platform's headers drop `Set-Cookie`, which Workers set (Astro appends\n      // its cookies to the response): the response keeps its headers in a standalone `Headers`,\n      // the ones the platform derived (content-type) plus the Set-Cookie values of the init.\n      const headers = new Headers(super.headers);\n      const given = init.headers instanceof Headers ? init.headers : new Headers(init.headers);\n      for (const c of given.getSetCookie()) headers.append(\"set-cookie\", c);\n      Object.defineProperty(this, \"headers\", {\n        value: headers,\n        configurable: true,\n        enumerable: true,\n      });\n    }\n  }\n  get status(): number {\n    // Static helpers (CellsResponse.json(), .redirect(), .error()) may build instances\n    // without running this constructor: fall back to the platform's status.\n    return #status in this ? this.#status : super.status;\n  }\n\n  /**\n   * Every platform `Response` is a Workers `Response`, as on workerd: `Response.json()`,\n   * `Response.redirect()` and `Response.error()` (the platform's static helpers, which build\n   * platform instances, not instances of this subclass) and `fetch()` results pass\n   * `instanceof Response` in Worker code. Astro checks every endpoint's result that way.\n   */\n  static [Symbol.hasInstance](v: unknown): boolean {\n    return v instanceof HostResponse;\n  }\n\n  // In a browser the platform's static helpers build platform responses, whose headers drop\n  // `Set-Cookie`: these build instances of this class there (`Response.json()` is how most\n  // APIs answer, and their cookies are appended to it afterwards).\n  static override json(data: unknown, init: ResponseInit = {}): Response {\n    if (!dropsSetCookie) return super.json(data, init);\n    const headers = new Headers(init.headers);\n    if (!headers.has(\"content-type\")) headers.set(\"content-type\", \"application/json\");\n    return new CellsResponse(JSON.stringify(data), { ...init, headers });\n  }\n\n  static override redirect(url: string | URL, status = 302): Response {\n    if (!dropsSetCookie) return super.redirect(url, status);\n    if (![301, 302, 303, 307, 308].includes(status))\n      throw new RangeError(`Invalid status ${status}`);\n    const base = (globalThis as { location?: { href: string } }).location?.href;\n    return new CellsResponse(null, { status, headers: { location: new URL(url, base).href } });\n  }\n}\n\n/** Workers `WebSocketRequestResponsePair` (ctx.setWebSocketAutoResponse). */\nexport class WebSocketRequestResponsePair {\n  readonly request: string;\n  readonly response: string;\n  constructor(request: string, response: string) {\n    this.request = request;\n    this.response = response;\n  }\n}\n"]}

package/dist/ws/sw-connector.d.ts

@@ -0,0 +1,10 @@
+import type { WebSocketConnector } from "./client.js";
+/** The message a page posts to the ServiceWorker to open a socket (a reply port rides along). */
+export declare const SW_SOCKET = "cells-ws";
+/**
+ * Page-side connector: asks the controlling ServiceWorker (a CellRouter) to open
+ * a socket and receives the socket's MessagePort in return.
+ * `new (createWebSocketClass(serviceWorkerConnector()))(url)` then behaves like a
+ * browser WebSocket towards a Durable Object in a shard worker.
+ */
+export declare function serviceWorkerConnector(sw?: () => Promise<ServiceWorker>): WebSocketConnector;

package/dist/ws/sw-connector.js

@@ -0,0 +1,25 @@
+/** The message a page posts to the ServiceWorker to open a socket (a reply port rides along). */
+export const SW_SOCKET = "cells-ws";
+/**
+ * Page-side connector: asks the controlling ServiceWorker (a CellRouter) to open
+ * a socket and receives the socket's MessagePort in return.
+ * `new (createWebSocketClass(serviceWorkerConnector()))(url)` then behaves like a
+ * browser WebSocket towards a Durable Object in a shard worker.
+ */
+export function serviceWorkerConnector(sw = async () => {
+    const reg = await navigator.serviceWorker.ready;
+    return navigator.serviceWorker.controller ?? reg.active;
+}) {
+    return async (url, protocols) => {
+        const target = await sw();
+        const { port1, port2 } = new MessageChannel();
+        const answer = new Promise((resolve) => (port1.onmessage = (e) => resolve(e.data)));
+        target.postMessage({ type: SW_SOCKET, url, protocols }, [port2]);
+        const a = await answer;
+        port1.close();
+        if (!a.ok || !a.port)
+            throw new Error(a.error ?? "WebSocket refused");
+        return { port: a.port, protocol: a.protocol };
+    };
+}
+//# sourceMappingURL=sw-connector.js.map

package/dist/ws/sw-connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sw-connector.js","sourceRoot":"","sources":["../../src/ws/sw-connector.ts"],"names":[],"mappings":"AAEA,iGAAiG;AACjG,MAAM,CAAC,MAAM,SAAS,GAAG,UAAU,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,EAAE,GAAiC,KAAK,IAAI,EAAE;IAC5C,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC;IAChD,OAAO,SAAS,CAAC,aAAa,CAAC,UAAU,IAAK,GAAG,CAAC,MAAwB,CAAC;AAC7E,CAAC;IAED,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAC1B,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,cAAc,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,OAAO,CAKvB,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;QACjE,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC;QACvB,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,mBAAmB,CAAC,CAAC;QACtE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;IAChD,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import type { WebSocketConnector } from \"./client.js\";\n\n/** The message a page posts to the ServiceWorker to open a socket (a reply port rides along). */\nexport const SW_SOCKET = \"cells-ws\";\n\n/**\n * Page-side connector: asks the controlling ServiceWorker (a CellRouter) to open\n * a socket and receives the socket's MessagePort in return.\n * `new (createWebSocketClass(serviceWorkerConnector()))(url)` then behaves like a\n * browser WebSocket towards a Durable Object in a shard worker.\n */\nexport function serviceWorkerConnector(\n  sw: () => Promise<ServiceWorker> = async () => {\n    const reg = await navigator.serviceWorker.ready;\n    return navigator.serviceWorker.controller ?? (reg.active as ServiceWorker);\n  },\n): WebSocketConnector {\n  return async (url, protocols) => {\n    const target = await sw();\n    const { port1, port2 } = new MessageChannel();\n    const answer = new Promise<{\n      ok: boolean;\n      port?: MessagePort;\n      protocol?: string;\n      error?: string;\n    }>((resolve) => (port1.onmessage = (e) => resolve(e.data)));\n    target.postMessage({ type: SW_SOCKET, url, protocols }, [port2]);\n    const a = await answer;\n    port1.close();\n    if (!a.ok || !a.port) throw new Error(a.error ?? \"WebSocket refused\");\n    return { port: a.port, protocol: a.protocol };\n  };\n}\n"]}

package/dist/ws/upgrade.d.ts

@@ -0,0 +1,28 @@
+export declare function withUpgrade<R extends Request>(req: R, value?: string, extra?: HeadersInit): R;
+/**
+ * `req` with `extra` headers set on top of its own, as an own `headers` property (a standalone
+ * `Headers`, which keeps the names a browser drops from Requests: `Cookie`, `Upgrade`, `Sec-*`).
+ */
+export declare function withHeaders<R extends Request>(req: R, extra: HeadersInit): R;
+/**
+ * Copies `Upgrade`, `Sec-WebSocket-*` and `Cookie` from `from` onto a rebuilt request (no-op if
+ * none): a browser drops them from every `new Request()`.
+ */
+export declare function carryWebSocketHeaders<R extends Request>(from: Headers, to: R): R;
+declare const HostRequest: {
+    new (input: RequestInfo | URL, init?: RequestInit): Request;
+    prototype: Request;
+};
+/**
+ * The `Request` global of Worker code. A browser drops `Upgrade`, `Sec-WebSocket-*` and `Cookie`
+ * from every `new Request()`, so a Worker that copies an upgrade request (`new Request(req)`, as
+ * partyserver does before it forwards a socket to its Durable Object) or a request with cookies
+ * would lose them; this one carries them over, like the rest of the headers. Requests the host
+ * makes are instances too.
+ */
+export declare class CellsRequest extends HostRequest {
+    constructor(input: RequestInfo | URL, init?: RequestInit);
+    clone(): Request;
+    static [Symbol.hasInstance](v: unknown): boolean;
+}
+export {};

package/dist/ws/upgrade.js

@@ -0,0 +1,75 @@
+/**
+ * Browsers silently drop FORBIDDEN request headers from `new Request(...)`: `Upgrade`,
+ * and every `Sec-*` header such as `Sec-WebSocket-Protocol` (Node/undici keeps them).
+ * Cloudflare code reads `request.headers.get("Upgrade")` and the offered subprotocols,
+ * so the runtime re-attaches them as an own `headers` property backed by a standalone
+ * `Headers` object (guard "none" accepts any name).
+ */
+const isWebSocketHeader = (name) => name === "upgrade" || name.startsWith("sec-websocket-");
+export function withUpgrade(req, value = "websocket", extra) {
+    const headers = new Headers(req.headers);
+    headers.set("Upgrade", value);
+    for (const [k, v] of new Headers(extra))
+        headers.set(k, v);
+    Object.defineProperty(req, "headers", { value: headers, configurable: true, enumerable: true });
+    return req;
+}
+/**
+ * `req` with `extra` headers set on top of its own, as an own `headers` property (a standalone
+ * `Headers`, which keeps the names a browser drops from Requests: `Cookie`, `Upgrade`, `Sec-*`).
+ */
+export function withHeaders(req, extra) {
+    const headers = new Headers(req.headers);
+    for (const [k, v] of new Headers(extra))
+        headers.set(k, v);
+    Object.defineProperty(req, "headers", { value: headers, configurable: true, enumerable: true });
+    return req;
+}
+/**
+ * Copies `Upgrade`, `Sec-WebSocket-*` and `Cookie` from `from` onto a rebuilt request (no-op if
+ * none): a browser drops them from every `new Request()`.
+ */
+export function carryWebSocketHeaders(from, to) {
+    const upgrade = from.get("Upgrade");
+    const cookie = from.get("Cookie");
+    if (cookie !== null && to.headers.get("Cookie") !== cookie)
+        withHeaders(to, { cookie });
+    if (!upgrade)
+        return to;
+    const extra = [];
+    for (const [k, v] of from)
+        if (k !== "upgrade" && isWebSocketHeader(k))
+            extra.push([k, v]);
+    return withUpgrade(to, upgrade, extra);
+}
+const HostRequest = globalThis.Request;
+/**
+ * The `Request` global of Worker code. A browser drops `Upgrade`, `Sec-WebSocket-*` and `Cookie`
+ * from every `new Request()`, so a Worker that copies an upgrade request (`new Request(req)`, as
+ * partyserver does before it forwards a socket to its Durable Object) or a request with cookies
+ * would lose them; this one carries them over, like the rest of the headers. Requests the host
+ * makes are instances too.
+ */
+export class CellsRequest extends HostRequest {
+    constructor(input, init) {
+        super(input, init);
+        // `init.headers` replaces the input's headers, as in `Request` itself.
+        // Not a fresh `Headers` from a Request's own: a browser's would drop what it carries.
+        const from = init?.headers !== undefined
+            ? init.headers instanceof Headers
+                ? init.headers
+                : new Headers(init.headers)
+            : input instanceof HostRequest
+                ? input.headers
+                : undefined;
+        if (from)
+            carryWebSocketHeaders(from, this);
+    }
+    clone() {
+        return carryWebSocketHeaders(this.headers, super.clone());
+    }
+    static [Symbol.hasInstance](v) {
+        return v instanceof HostRequest;
+    }
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/ws/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../src/ws/upgrade.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Browsers silently drop FORBIDDEN request headers from `new Request(...)`: `Upgrade`,\n * and every `Sec-*` header such as `Sec-WebSocket-Protocol` (Node/undici keeps them).\n * Cloudflare code reads `request.headers.get(\"Upgrade\")` and the offered subprotocols,\n * so the runtime re-attaches them as an own `headers` property backed by a standalone\n * `Headers` object (guard \"none\" accepts any name).\n */\nconst isWebSocketHeader = (name: string) => name === \"upgrade\" || name.startsWith(\"sec-websocket-\");\n\nexport function withUpgrade<R extends Request>(\n  req: R,\n  value = \"websocket\",\n  extra?: HeadersInit,\n): R {\n  const headers = new Headers(req.headers);\n  headers.set(\"Upgrade\", value);\n  for (const [k, v] of new Headers(extra)) headers.set(k, v);\n  Object.defineProperty(req, \"headers\", { value: headers, configurable: true, enumerable: true });\n  return req;\n}\n\n/**\n * `req` with `extra` headers set on top of its own, as an own `headers` property (a standalone\n * `Headers`, which keeps the names a browser drops from Requests: `Cookie`, `Upgrade`, `Sec-*`).\n */\nexport function withHeaders<R extends Request>(req: R, extra: HeadersInit): R {\n  const headers = new Headers(req.headers);\n  for (const [k, v] of new Headers(extra)) headers.set(k, v);\n  Object.defineProperty(req, \"headers\", { value: headers, configurable: true, enumerable: true });\n  return req;\n}\n\n/**\n * Copies `Upgrade`, `Sec-WebSocket-*` and `Cookie` from `from` onto a rebuilt request (no-op if\n * none): a browser drops them from every `new Request()`.\n */\nexport function carryWebSocketHeaders<R extends Request>(from: Headers, to: R): R {\n  const upgrade = from.get(\"Upgrade\");\n  const cookie = from.get(\"Cookie\");\n  if (cookie !== null && to.headers.get(\"Cookie\") !== cookie) withHeaders(to, { cookie });\n  if (!upgrade) return to;\n  const extra: [string, string][] = [];\n  for (const [k, v] of from) if (k !== \"upgrade\" && isWebSocketHeader(k)) extra.push([k, v]);\n  return withUpgrade(to, upgrade, extra);\n}\n\nconst HostRequest = globalThis.Request;\n\n/**\n * The `Request` global of Worker code. A browser drops `Upgrade`, `Sec-WebSocket-*` and `Cookie`\n * from every `new Request()`, so a Worker that copies an upgrade request (`new Request(req)`, as\n * partyserver does before it forwards a socket to its Durable Object) or a request with cookies\n * would lose them; this one carries them over, like the rest of the headers. Requests the host\n * makes are instances too.\n */\nexport class CellsRequest extends HostRequest {\n  constructor(input: RequestInfo | URL, init?: RequestInit) {\n    super(input, init);\n    // `init.headers` replaces the input's headers, as in `Request` itself.\n    // Not a fresh `Headers` from a Request's own: a browser's would drop what it carries.\n    const from =\n      init?.headers !== undefined\n        ? init.headers instanceof Headers\n          ? init.headers\n          : new Headers(init.headers)\n        : input instanceof HostRequest\n          ? input.headers\n          : undefined;\n    if (from) carryWebSocketHeaders(from, this);\n  }\n\n  override clone(): Request {\n    return carryWebSocketHeaders(this.headers, super.clone());\n  }\n\n  static [Symbol.hasInstance](v: unknown): boolean {\n    return v instanceof HostRequest;\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,114 @@
 {
   "name": "@statewalker/cellb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "cellb: isomorphic Durable Objects runtime (celld/Cloudflare-compatible surface) for browsers and servers",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statewalker/cellb.dev.git",
+    "directory": "packages/cellb"
+  },
+  "homepage": "https://github.com/statewalker/cellb.dev/tree/main/packages/cellb#readme",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./host-modules": {
+      "types": "./dist/project/host-modules.d.ts",
+      "default": "./dist/project/host-modules.js"
+    },
+    "./isolate-worker": {
+      "types": "./dist/isolate/isolate-worker.d.ts",
+      "default": "./dist/isolate/isolate-worker.js"
+    }
+  },
+  "files": [
+    "dist",
+    "vendor",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.8.0",
+    "@sqlite.org/sqlite-wasm": "^3.53.4-build1",
+    "@statewalker/webrun-files": "^0.10.0",
+    "@statewalker/webrun-files-browser": "^0.10.0",
+    "@statewalker/webrun-files-mem": "^0.10.0",
+    "@statewalker/webrun-http-browser": "^0.7.0",
+    "@statewalker/webrun-http-streams": "^0.3.0",
+    "@statewalker/webrun-modules": "^0.3.5",
+    "@statewalker/webrun-rpc": "^0.5.0",
+    "@statewalker/webrun-site-builder": "^0.2.0",
+    "@statewalker/webrun-site-host": "^0.3.0",
+    "@statewalker/webrun-streams": "^0.2.0",
+    "acorn": "^8.19.0",
+    "assert": "^2.1.0",
+    "buffer": "^6.0.3",
+    "events": "^3.3.0",
+    "path-browserify": "^1.0.1",
+    "sqlite-vec": "^0.1.7",
+    "util": "^0.12.5",
+    "worker-timers": "^8.0.0",
+    "ws": "^8.22.0"
+  },
+  "peerDependencies": {
+    "esbuild": ">=0.25"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@sparticuz/chromium": "^153.0.0",
+    "@statewalker/webrun-http-browser": "^0.7.0",
+    "@types/node": "^26.6.4",
+    "@types/ws": "^8.18.2",
+    "esbuild": "^0.28.0",
+    "html-rewriter-wasm": "^0.4.1",
+    "miniflare": "4.20260730.0",
+    "sqlite-vec-wasm-demo": "0.1.6",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3",
+    "zod": "^3.25.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "vitest run",
+    "test:unit": "vitest run test/",
+    "test:e2e": "vitest run e2e/",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p e2e-browser/pages/tsconfig.json",
+    "mutate": "node scripts/mutate.mjs",
+    "browser:prepare": "mkdir -p e2e-browser/pages/public/vendor && cp node_modules/@statewalker/webrun-http-browser/dist/sw-worker.js e2e-browser/pages/public/vendor/webrun-http-sw-worker.js",
+    "browser:dev": "pnpm run browser:prepare && vite e2e-browser/pages --config e2e-browser/pages/vite.config.ts",
+    "browser:build": "pnpm run browser:prepare && vite build e2e-browser/pages --config e2e-browser/pages/vite.config.ts",
+    "e2e": "playwright test",
+    "e2e:firefox": "PW_BROWSERS=firefox playwright test",
+    "e2e:webkit": "PW_BROWSERS=webkit playwright test",
+    "interop": "scripts/interop-env.sh vitest run e2e/ test/p09-celld-conformance.test.ts",
+    "interop:browser": "scripts/interop-env.sh playwright test celld-bucket opfs-bucket",
+    "e2e:npm-chromium": "PW_CHROMIUM=\"$(node scripts/npm-chromium.mjs)\" playwright test",
+    "mutate:browser": "node scripts/mutate-browser.mjs",
+    "mutate:check": "node scripts/mutate.mjs --check && node scripts/mutate-browser.mjs --check",
+    "probes:browser": "PW_CHROMIUM=\"${PW_CHROMIUM:-$(node scripts/npm-chromium.mjs)}\" playwright test --config playwright.probes.config.ts --reporter=line",
+    "probes:node": "node --no-warnings probes/sqlite-lock.probe.mjs"
+  }
 }