@statewalker/cellb 0.0.0-stage → 0.1.0

package/dist/router/cell-router.js

@@ -0,0 +1,247 @@
+import { idFromName, namespaceKey } from "../core/id.js";
+import { shardOf } from "../core/shard.js";
+import { errorResponse, stripControl } from "../transport/cells-http.js";
+import { H } from "../transport/cells-link.js";
+import { PortRendezvous, shardOfControlId, } from "../ws/control.js";
+/** Thrown into in-flight requests of a shard whose owner is gone (CF: "Durable Object reset"). */
+export class ShardOwnerLostError extends Error {
+    constructor(shard) {
+        super(`Owner of cell shard ${shard} was lost; the request may or may not have been applied`);
+        this.name = "ShardOwnerLostError";
+    }
+}
+/**
+ * The single "server" of an origin (ServiceWorker, page or Node main thread):
+ * knows which shard owns which cell and holds one HTTP link per shard worker.
+ *
+ * - `ingress(req)`: public requests → any live shard's Worker `fetch`. Control
+ *   headers are stripped first, so clients cannot address objects directly.
+ * - `internal(req)`: requests from shard workers (DO → DO across shards) →
+ *   forwarded to the owning shard, control headers intact.
+ */
+export class CellRouter {
+    #opts;
+    #links = new Map();
+    #watchdog;
+    #waiters = new Map();
+    #rr = 0;
+    #wsSeq = 0;
+    #wsShard = new Map();
+    #ports = new PortRendezvous();
+    constructor(opts) {
+        this.#opts = opts;
+    }
+    get attachedShards() {
+        return [...this.#links]
+            .filter(([, l]) => !l.draining)
+            .map(([shard]) => shard)
+            .sort((a, b) => a - b);
+    }
+    /**
+     * Attaches the link of a shard. Replacing a link means the previous owner is
+     * gone (Web Locks / leases guarantee a single live owner): its in-flight
+     * requests fail at once instead of hanging on a dead port.
+     */
+    attach(shard, send, token, ctl) {
+        const prev = this.#links.get(shard);
+        this.#links.set(shard, { send, token, inflight: new Set(), ctl });
+        if (ctl) {
+            ctl.onmessage = (e) => this.#onControl(e.data);
+            ctl.start?.();
+        }
+        if (prev)
+            this.#fail(shard, prev);
+        if (token !== undefined && this.#opts.watchOwner)
+            this.#opts.watchOwner(shard, token).then(() => this.#links.get(shard)?.token === token && this.detach(shard), () => { });
+        for (const wake of this.#waiters.get(shard) ?? [])
+            wake();
+        this.#waiters.delete(shard);
+    }
+    detach(shard, send) {
+        const link = this.#links.get(shard);
+        if (!link || (send && link.send !== send))
+            return;
+        this.#links.delete(shard);
+        this.#fail(shard, link);
+    }
+    /**
+     * A planned hand-over of `shard`: new requests wait for the next owner to attach, the ones in
+     * flight get up to `timeoutMs` to finish, then the link goes (the rest fail as when an owner is
+     * lost). Only the link attached with `token` is drained.
+     */
+    async drain(shard, token, timeoutMs) {
+        const link = this.#links.get(shard);
+        if (!link || link.token !== token)
+            return;
+        link.draining = true;
+        const end = Date.now() + timeoutMs;
+        while (link.inflight.size && Date.now() < end && this.#links.get(shard) === link)
+            await new Promise((r) => setTimeout(r, 20));
+        this.detach(shard, link.send);
+    }
+    /** Number of requests currently forwarded to a shard (diagnostics/tests). */
+    inflight(shard) {
+        return this.#links.get(shard)?.inflight.size ?? 0;
+    }
+    /**
+     * WebSocket ingress (a ServiceWorker cannot intercept WebSockets): asks a live
+     * shard, over its control channel, to run the Worker's fetch with an Upgrade
+     * request; resolves with the client end's port (transfer it to the page).
+     */
+    async connectWebSocket(url, protocols = [], headers) {
+        const shard = this.#pick();
+        const link = await this.#linkFor(shard);
+        if (!link.ctl)
+            throw new Error(`shard ${shard} has no control channel: WebSockets unavailable`);
+        const id = `r:${++this.#wsSeq}`;
+        this.#wsShard.set(id, shard);
+        link.ctl.postMessage({ t: "ws-connect", id, url, protocols, headers });
+        try {
+            return await this.#ports.wait(id);
+        }
+        finally {
+            this.#wsShard.delete(id);
+        }
+    }
+    #onControl(m) {
+        if (m.t !== "ws-accept" && m.t !== "ws-refuse")
+            return;
+        const target = shardOfControlId(m.id);
+        if (target !== undefined) {
+            // Cross-shard hand-over: the Worker that asked lives in shard `target`.
+            const ctl = this.#links.get(target)?.ctl;
+            if (!ctl) {
+                if (m.t === "ws-accept")
+                    m.port.close();
+                return;
+            }
+            ctl.postMessage(m, m.t === "ws-accept" ? [m.port] : []);
+            return;
+        }
+        this.#ports.deliver(m.id, m.t === "ws-accept" ? { port: m.port, protocol: m.protocol } : new Error(m.message));
+    }
+    #fail(shard, link) {
+        this.#ports.failAll((id) => this.#wsShard.get(id) === shard, new ShardOwnerLostError(shard));
+        for (const ac of link.inflight)
+            ac.abort(new ShardOwnerLostError(shard));
+        link.inflight.clear();
+    }
+    /** Forwards with an abort handle; the handle lives until the response body ends. */
+    async #forward(shard, req) {
+        const link = await this.#linkFor(shard);
+        const ac = new AbortController();
+        link.inflight.add(ac);
+        this.#ensureWatchdog();
+        const done = () => link.inflight.delete(ac);
+        const lost = new Promise((_, reject) => ac.signal.addEventListener("abort", () => reject(ac.signal.reason), { once: true }));
+        lost.catch(() => { });
+        try {
+            const signal = AbortSignal.any([req.signal, ac.signal]);
+            const res = await Promise.race([
+                link.send(new Request(req, { signal, duplex: "half" })),
+                lost,
+            ]);
+            if (!res.body)
+                return done(), res;
+            const { readable, writable } = new TransformStream();
+            res.body.pipeTo(writable, { signal: ac.signal }).then(done, done);
+            return new Response(readable, res);
+        }
+        catch (e) {
+            done();
+            throw ac.signal.aborted ? ac.signal.reason : e;
+        }
+    }
+    #ensureWatchdog() {
+        if (this.#watchdog || !this.#opts.isAlive)
+            return;
+        this.#watchdog = setInterval(async () => {
+            const busy = [...this.#links].filter(([, l]) => l.inflight.size > 0);
+            if (!busy.length) {
+                clearInterval(this.#watchdog);
+                this.#watchdog = undefined;
+                return;
+            }
+            for (const [shard, link] of busy) {
+                const alive = await this.#opts.isAlive(shard, link.token).catch(() => true);
+                if (!alive && this.#links.get(shard) === link)
+                    this.detach(shard);
+            }
+        }, this.#opts.livenessIntervalMs ?? 1000);
+    }
+    /**
+     * The shard for ingress: the live one with the fewest requests in flight (a long request
+     * keeps its shard busy, wherever its Durable Objects run), round robin among equals.
+     */
+    #pick() {
+        const live = this.attachedShards;
+        if (!live.length)
+            return 0;
+        const start = this.#rr++ % live.length;
+        let best = live[start];
+        for (let i = 1; i < live.length; i++) {
+            const s = live[(start + i) % live.length];
+            if (this.inflight(s) < this.inflight(best))
+                best = s;
+        }
+        return best;
+    }
+    ingress = async (req) => {
+        const shard = this.#pick();
+        try {
+            // The page's cookies (x-cellb-cookie, set by the ServiceWorker) go on to the shard.
+            return await this.#forward(shard, stripControl(req, [H.cookie]));
+        }
+        catch (e) {
+            return new Response(`Cell shard ${shard} unavailable: ${e.message}`, {
+                status: 503,
+            });
+        }
+    };
+    internal = async (req) => {
+        const kind = req.headers.get(H.kind);
+        try {
+            if (kind === "describe")
+                return Response.json({ bindings: this.#opts.bindings });
+            if (kind !== "fetch" && kind !== "rpc")
+                return await this.ingress(req);
+            return await this.#forward(this.shardOfRequest(req), req);
+        }
+        catch (e) {
+            return errorResponse(e, 503);
+        }
+    };
+    shardOfRequest(req) {
+        const explicit = req.headers.get(H.shard);
+        if (explicit !== null) {
+            const shard = Number(explicit);
+            if (Number.isInteger(shard) && shard >= 0 && shard < this.#opts.shards)
+                return shard;
+            throw new Error(`Invalid cell shard "${explicit}"`);
+        }
+        const binding = req.headers.get(H.binding) ?? "";
+        const target = req.headers.get(H.target) ?? "";
+        const className = this.#opts.bindings[binding];
+        if (!className)
+            throw new Error(`Unknown Durable Object binding "${binding}"`);
+        const hex = target.startsWith("name:")
+            ? idFromName(namespaceKey(this.#opts.scriptName ?? "worker", className), target.slice(5)).toString()
+            : target.slice(3);
+        return shardOf(hex, this.#opts.shards);
+    }
+    async #linkFor(shard) {
+        const link = this.#links.get(shard);
+        if (link && !link.draining)
+            return link;
+        this.#opts.onMissingShard?.(shard);
+        const timeout = this.#opts.attachTimeoutMs ?? 10_000;
+        await new Promise((resolve, reject) => {
+            const t = setTimeout(() => reject(new Error(`shard ${shard} not attached within ${timeout} ms`)), timeout);
+            const list = this.#waiters.get(shard) ?? [];
+            list.push(() => (clearTimeout(t), resolve()));
+            this.#waiters.set(shard, list);
+        });
+        return this.#links.get(shard);
+    }
+}
+//# sourceMappingURL=cell-router.js.map

package/dist/router/cell-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-router.js","sourceRoot":"","sources":["../../src/router/cell-router.ts"],"names":[],"mappings":"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","sourcesContent":["import { idFromName, namespaceKey } from \"../core/id.js\";\nimport { shardOf } from \"../core/shard.js\";\nimport { errorResponse, stripControl } from \"../transport/cells-http.js\";\nimport { H, type Send } from \"../transport/cells-link.js\";\nimport {\n  type ControlMessage,\n  type ControlPort,\n  PortRendezvous,\n  shardOfControlId,\n} from \"../ws/control.js\";\n\nexport interface CellRouterOptions {\n  shards: number;\n  /** Durable Object binding → class name, as in wrangler config. */\n  bindings: Record<string, string>;\n  /** The Worker script's name: ids derive from it (default \"worker\", as the runtime's). */\n  scriptName?: string;\n  /** Called when a request needs a shard that has no live link (e.g. ask pages to re-attach). */\n  onMissingShard?: (shard: number) => void;\n  /** How long a request waits for its shard to be attached (default 10 s). */\n  attachTimeoutMs?: number;\n  /**\n   * Liveness probe of the owner that attached `token`. Polled every\n   * `livenessIntervalMs` while the shard has requests in flight; `false`\n   * invalidates the link. In a ServiceWorker: is the shard's Web Lock still\n   * held by the same holder? (MessagePort has no close event in Chromium.)\n   */\n  isAlive?: (shard: number, token: unknown) => Promise<boolean>;\n  livenessIntervalMs?: number;\n  /**\n   * Event-driven liveness (preferred over polling): resolves when the owner that\n   * attached `token` is gone. Browser: a pending request on the owner's own Web\n   * Lock, granted the moment its worker/tab dies. Node: worker \"exit\".\n   */\n  watchOwner?: (shard: number, token: unknown) => Promise<unknown>;\n}\n\n/** Thrown into in-flight requests of a shard whose owner is gone (CF: \"Durable Object reset\"). */\nexport class ShardOwnerLostError extends Error {\n  constructor(shard: number) {\n    super(`Owner of cell shard ${shard} was lost; the request may or may not have been applied`);\n    this.name = \"ShardOwnerLostError\";\n  }\n}\n\ninterface Link {\n  send: Send;\n  token: unknown;\n  inflight: Set<AbortController>;\n  ctl?: ControlPort;\n  /** Being handed over: no new requests (they wait for the next owner), the current ones finish. */\n  draining?: boolean;\n}\n\n/**\n * The single \"server\" of an origin (ServiceWorker, page or Node main thread):\n * knows which shard owns which cell and holds one HTTP link per shard worker.\n *\n * - `ingress(req)`: public requests → any live shard's Worker `fetch`. Control\n *   headers are stripped first, so clients cannot address objects directly.\n * - `internal(req)`: requests from shard workers (DO → DO across shards) →\n *   forwarded to the owning shard, control headers intact.\n */\nexport class CellRouter {\n  readonly #opts: CellRouterOptions;\n  readonly #links = new Map<number, Link>();\n  #watchdog: ReturnType<typeof setInterval> | undefined;\n  readonly #waiters = new Map<number, (() => void)[]>();\n  #rr = 0;\n  #wsSeq = 0;\n  readonly #wsShard = new Map<string, number>();\n  readonly #ports = new PortRendezvous();\n\n  constructor(opts: CellRouterOptions) {\n    this.#opts = opts;\n  }\n\n  get attachedShards(): number[] {\n    return [...this.#links]\n      .filter(([, l]) => !l.draining)\n      .map(([shard]) => shard)\n      .sort((a, b) => a - b);\n  }\n\n  /**\n   * Attaches the link of a shard. Replacing a link means the previous owner is\n   * gone (Web Locks / leases guarantee a single live owner): its in-flight\n   * requests fail at once instead of hanging on a dead port.\n   */\n  attach(shard: number, send: Send, token?: unknown, ctl?: ControlPort): void {\n    const prev = this.#links.get(shard);\n    this.#links.set(shard, { send, token, inflight: new Set(), ctl });\n    if (ctl) {\n      ctl.onmessage = (e) => this.#onControl(e.data as ControlMessage);\n      ctl.start?.();\n    }\n    if (prev) this.#fail(shard, prev);\n    if (token !== undefined && this.#opts.watchOwner)\n      this.#opts.watchOwner(shard, token).then(\n        () => this.#links.get(shard)?.token === token && this.detach(shard),\n        () => {},\n      );\n    for (const wake of this.#waiters.get(shard) ?? []) wake();\n    this.#waiters.delete(shard);\n  }\n\n  detach(shard: number, send?: Send): void {\n    const link = this.#links.get(shard);\n    if (!link || (send && link.send !== send)) return;\n    this.#links.delete(shard);\n    this.#fail(shard, link);\n  }\n\n  /**\n   * A planned hand-over of `shard`: new requests wait for the next owner to attach, the ones in\n   * flight get up to `timeoutMs` to finish, then the link goes (the rest fail as when an owner is\n   * lost). Only the link attached with `token` is drained.\n   */\n  async drain(shard: number, token: unknown, timeoutMs: number): Promise<void> {\n    const link = this.#links.get(shard);\n    if (!link || link.token !== token) return;\n    link.draining = true;\n    const end = Date.now() + timeoutMs;\n    while (link.inflight.size && Date.now() < end && this.#links.get(shard) === link)\n      await new Promise((r) => setTimeout(r, 20));\n    this.detach(shard, link.send);\n  }\n\n  /** Number of requests currently forwarded to a shard (diagnostics/tests). */\n  inflight(shard: number): number {\n    return this.#links.get(shard)?.inflight.size ?? 0;\n  }\n\n  /**\n   * WebSocket ingress (a ServiceWorker cannot intercept WebSockets): asks a live\n   * shard, over its control channel, to run the Worker's fetch with an Upgrade\n   * request; resolves with the client end's port (transfer it to the page).\n   */\n  async connectWebSocket(url: string, protocols: string[] = [], headers?: [string, string][]) {\n    const shard = this.#pick();\n    const link = await this.#linkFor(shard);\n    if (!link.ctl) throw new Error(`shard ${shard} has no control channel: WebSockets unavailable`);\n    const id = `r:${++this.#wsSeq}`;\n    this.#wsShard.set(id, shard);\n    link.ctl.postMessage({ t: \"ws-connect\", id, url, protocols, headers } satisfies ControlMessage);\n    try {\n      return await this.#ports.wait(id);\n    } finally {\n      this.#wsShard.delete(id);\n    }\n  }\n\n  #onControl(m: ControlMessage): void {\n    if (m.t !== \"ws-accept\" && m.t !== \"ws-refuse\") return;\n    const target = shardOfControlId(m.id);\n    if (target !== undefined) {\n      // Cross-shard hand-over: the Worker that asked lives in shard `target`.\n      const ctl = this.#links.get(target)?.ctl;\n      if (!ctl) {\n        if (m.t === \"ws-accept\") m.port.close();\n        return;\n      }\n      ctl.postMessage(m, m.t === \"ws-accept\" ? [m.port as unknown as Transferable] : []);\n      return;\n    }\n    this.#ports.deliver(\n      m.id,\n      m.t === \"ws-accept\" ? { port: m.port, protocol: m.protocol } : new Error(m.message),\n    );\n  }\n\n  #fail(shard: number, link: Link): void {\n    this.#ports.failAll((id) => this.#wsShard.get(id) === shard, new ShardOwnerLostError(shard));\n    for (const ac of link.inflight) ac.abort(new ShardOwnerLostError(shard));\n    link.inflight.clear();\n  }\n\n  /** Forwards with an abort handle; the handle lives until the response body ends. */\n  async #forward(shard: number, req: Request): Promise<Response> {\n    const link = await this.#linkFor(shard);\n    const ac = new AbortController();\n    link.inflight.add(ac);\n    this.#ensureWatchdog();\n    const done = () => link.inflight.delete(ac);\n    const lost = new Promise<never>((_, reject) =>\n      ac.signal.addEventListener(\"abort\", () => reject(ac.signal.reason), { once: true }),\n    );\n    lost.catch(() => {});\n    try {\n      const signal = AbortSignal.any([req.signal, ac.signal]);\n      const res = await Promise.race([\n        link.send(new Request(req, { signal, duplex: \"half\" } as RequestInit)),\n        lost,\n      ]);\n      if (!res.body) return done(), res;\n      const { readable, writable } = new TransformStream();\n      res.body.pipeTo(writable, { signal: ac.signal }).then(done, done);\n      return new Response(readable, res);\n    } catch (e) {\n      done();\n      throw ac.signal.aborted ? ac.signal.reason : e;\n    }\n  }\n\n  #ensureWatchdog(): void {\n    if (this.#watchdog || !this.#opts.isAlive) return;\n    this.#watchdog = setInterval(async () => {\n      const busy = [...this.#links].filter(([, l]) => l.inflight.size > 0);\n      if (!busy.length) {\n        clearInterval(this.#watchdog);\n        this.#watchdog = undefined;\n        return;\n      }\n      for (const [shard, link] of busy) {\n        const alive = await this.#opts.isAlive!(shard, link.token).catch(() => true);\n        if (!alive && this.#links.get(shard) === link) this.detach(shard);\n      }\n    }, this.#opts.livenessIntervalMs ?? 1000);\n  }\n\n  /**\n   * The shard for ingress: the live one with the fewest requests in flight (a long request\n   * keeps its shard busy, wherever its Durable Objects run), round robin among equals.\n   */\n  #pick(): number {\n    const live = this.attachedShards;\n    if (!live.length) return 0;\n    const start = this.#rr++ % live.length;\n    let best = live[start];\n    for (let i = 1; i < live.length; i++) {\n      const s = live[(start + i) % live.length];\n      if (this.inflight(s) < this.inflight(best)) best = s;\n    }\n    return best;\n  }\n\n  ingress = async (req: Request): Promise<Response> => {\n    const shard = this.#pick();\n    try {\n      // The page's cookies (x-cellb-cookie, set by the ServiceWorker) go on to the shard.\n      return await this.#forward(shard, stripControl(req, [H.cookie]));\n    } catch (e) {\n      return new Response(`Cell shard ${shard} unavailable: ${(e as Error).message}`, {\n        status: 503,\n      });\n    }\n  };\n\n  internal = async (req: Request): Promise<Response> => {\n    const kind = req.headers.get(H.kind);\n    try {\n      if (kind === \"describe\") return Response.json({ bindings: this.#opts.bindings });\n      if (kind !== \"fetch\" && kind !== \"rpc\") return await this.ingress(req);\n      return await this.#forward(this.shardOfRequest(req), req);\n    } catch (e) {\n      return errorResponse(e, 503);\n    }\n  };\n\n  shardOfRequest(req: Request): number {\n    const explicit = req.headers.get(H.shard);\n    if (explicit !== null) {\n      const shard = Number(explicit);\n      if (Number.isInteger(shard) && shard >= 0 && shard < this.#opts.shards) return shard;\n      throw new Error(`Invalid cell shard \"${explicit}\"`);\n    }\n    const binding = req.headers.get(H.binding) ?? \"\";\n    const target = req.headers.get(H.target) ?? \"\";\n    const className = this.#opts.bindings[binding];\n    if (!className) throw new Error(`Unknown Durable Object binding \"${binding}\"`);\n    const hex = target.startsWith(\"name:\")\n      ? idFromName(\n          namespaceKey(this.#opts.scriptName ?? \"worker\", className),\n          target.slice(5),\n        ).toString()\n      : target.slice(3);\n    return shardOf(hex, this.#opts.shards);\n  }\n\n  async #linkFor(shard: number): Promise<Link> {\n    const link = this.#links.get(shard);\n    if (link && !link.draining) return link;\n    this.#opts.onMissingShard?.(shard);\n    const timeout = this.#opts.attachTimeoutMs ?? 10_000;\n    await new Promise<void>((resolve, reject) => {\n      const t = setTimeout(\n        () => reject(new Error(`shard ${shard} not attached within ${timeout} ms`)),\n        timeout,\n      );\n      const list = this.#waiters.get(shard) ?? [];\n      list.push(() => (clearTimeout(t), resolve()));\n      this.#waiters.set(shard, list);\n    });\n    return this.#links.get(shard)!;\n  }\n}\n"]}

package/dist/router/shard-worker.d.ts

@@ -0,0 +1,44 @@
+import { type CellRuntime, type CellRuntimeOptions } from "../core/runtime.js";
+import { type CellPort } from "../transport/port.js";
+import { type ControlPort } from "../ws/control.js";
+export interface ShardWorkerOptions extends Omit<CellRuntimeOptions, "route"> {
+    shard: number;
+    shards: number;
+}
+export interface ShardWorker {
+    readonly runtime: CellRuntime;
+    /**
+     * (Re)connects to a router: `down` = router → shard (served here),
+     * `up` = shard → router (for DO calls into other shards), `ctl` = control
+     * channel for WebSocket port hand-over. Called again when the router restarts
+     * (a ServiceWorker is killed when idle and loses its ports).
+     */
+    link(down: CellPort, up: CellPort, ctl?: ControlPort): Promise<void>;
+    /**
+     * Drops the links of a router that is gone (a stopped ServiceWorker leaves no trace on its
+     * ports): calls into other shards wait for the next `link`, and `onUnlinked` is told so.
+     */
+    unlink(): void;
+}
+/** Runs one shard: hosts the cells of shard `shard`, forwards the others upstream. */
+export declare function createShardWorker(opts: ShardWorkerOptions): ShardWorker;
+/**
+ * The router side of a shard, for a runtime built elsewhere (a project's, in a browser worker):
+ * `route` sends the cells of other shards up to the router (waiting until it is linked);
+ * `attach(runtime)` gives the runtime its links to the router.
+ */
+export declare function shardRouting(opts: {
+    shard: number;
+    shards: number;
+    /** A call into another shard waits after `unlink`: wake the router (once per `unlink`). */
+    onUnlinked?: () => void;
+    /**
+     * Called every `keepAliveMs` (default 20 s) while calls into other shards are in flight: they
+     * are no events for the router's ServiceWorker, which the browser stops when idle (~30 s).
+     */
+    keepAlive?: () => void;
+    keepAliveMs?: number;
+}): {
+    route: NonNullable<CellRuntimeOptions["route"]>;
+    attach(runtime: CellRuntime): ShardWorker;
+};

package/dist/router/shard-worker.js

@@ -0,0 +1,163 @@
+import { createCellRuntime } from "../core/runtime.js";
+import { shardOf } from "../core/shard.js";
+import { H, keepUpgrade } from "../transport/cells-link.js";
+import { linkOverPort, serveRuntime } from "../transport/port.js";
+import { PortRendezvous } from "../ws/control.js";
+import { CellsResponse, CfWebSocket } from "../ws/server.js";
+/** Runs one shard: hosts the cells of shard `shard`, forwards the others upstream. */
+export function createShardWorker(opts) {
+    const shard = shardRouting(opts);
+    const runtime = createCellRuntime({
+        ...opts,
+        vars: { ...opts.vars, SHARD: opts.shard },
+        route: shard.route,
+    });
+    return shard.attach(runtime);
+}
+/**
+ * The router side of a shard, for a runtime built elsewhere (a project's, in a browser worker):
+ * `route` sends the cells of other shards up to the router (waiting until it is linked);
+ * `attach(runtime)` gives the runtime its links to the router.
+ */
+export function shardRouting(opts) {
+    let upstream;
+    let control;
+    const pending = [];
+    const ports = new PortRendezvous();
+    let wsSeq = 0;
+    let unlinked = false;
+    let wokeAt = 0;
+    let outstanding = 0; // calls into other shards in flight
+    let keepAliveTimer;
+    const started = () => {
+        if (outstanding++ === 0 && opts.keepAlive)
+            keepAliveTimer = setInterval(opts.keepAlive, opts.keepAliveMs ?? 20_000);
+    };
+    const finished = () => {
+        if (--outstanding === 0)
+            clearInterval(keepAliveTimer);
+    };
+    /** Calls in flight over the current links: a dead link never answers them. */
+    let inflight = new Set();
+    const dropInflight = () => {
+        const lost = inflight;
+        inflight = new Set();
+        const err = new Error("The router was lost while this call was in flight; it may or may not have been applied");
+        for (const fail of lost)
+            fail(err);
+    };
+    const rawUp = async (req) => {
+        // Woken once per unlink, again if the router is still not back after a while.
+        if (!upstream && unlinked && Date.now() - wokeAt > 2_000) {
+            wokeAt = Date.now();
+            opts.onUnlinked?.();
+        }
+        while (!upstream)
+            await new Promise((r) => pending.push(r));
+        const send = upstream;
+        const calls = inflight;
+        started();
+        return new Promise((resolve, reject) => {
+            calls.add(reject);
+            send(req)
+                .then(resolve, reject)
+                .finally(() => calls.delete(reject));
+        }).finally(finished);
+    };
+    // DO → DO calls into other shards. A WebSocket upgrade gets an id; the owning
+    // shard hands the socket's port over the control channel (via the router).
+    const up = async (req) => {
+        if (req.headers.get("Upgrade")?.toLowerCase() !== "websocket")
+            return rawUp(req);
+        const id = `s${opts.shard}:${++wsSeq}`;
+        const headers = new Headers(req.headers);
+        headers.set(H.ws, id);
+        headers.set(H.upgrade, "websocket"); // hop-by-hop `Upgrade` does not survive the HTTP/1.1 link
+        const offered = req.headers.get("Sec-WebSocket-Protocol"); // forbidden in browser Requests
+        if (offered)
+            headers.set(H.wsProtocol, offered);
+        const res = await rawUp(new Request(req.url, { method: req.method, headers }));
+        if (res.headers.get(H.wsAccepted) !== id)
+            return res; // refused upgrade (plain HTTP answer)
+        const { port, protocol } = await ports.wait(id);
+        return new CellsResponse(null, {
+            status: 101,
+            webSocket: new CfWebSocket(port),
+            headers: protocol ? { "Sec-WebSocket-Protocol": protocol } : {},
+        });
+    };
+    // The owner travels with the request: the router need not derive it (it cannot for a
+    // project's internal namespaces, whose ids come from other keys).
+    const route = (_key, id) => {
+        const owner = shardOf(id.toString(), opts.shards);
+        if (owner === opts.shard)
+            return undefined;
+        return (req) => {
+            const headers = new Headers(req.headers);
+            headers.set(H.shard, String(owner));
+            return up(keepUpgrade(req, new Request(req, { headers })));
+        };
+    };
+    let runtime;
+    const post = (m) => control?.postMessage(m, m.t === "ws-accept" ? [m.port] : []);
+    const onControl = async (e) => {
+        const m = e.data;
+        if (m.t === "ws-accept")
+            return ports.deliver(m.id, { port: m.port, protocol: m.protocol });
+        if (m.t === "ws-refuse")
+            return ports.deliver(m.id, new Error(m.message));
+        if (m.t === "ws-connect") {
+            try {
+                const { port, protocol } = await runtime.connectWebSocket(m.url, m.protocols, m.headers);
+                post({ t: "ws-accept", id: m.id, protocol, port });
+            }
+            catch (err) {
+                post({ t: "ws-refuse", id: m.id, message: String(err?.message ?? err) });
+            }
+        }
+    };
+    let stopDown;
+    let closeUp;
+    const attach = (rt) => {
+        runtime = rt;
+        return {
+            runtime,
+            link,
+            unlink() {
+                if (!upstream)
+                    return;
+                upstream = undefined;
+                unlinked = true;
+                wokeAt = 0;
+                dropInflight();
+                const [prevStop, prevClose] = [stopDown, closeUp];
+                stopDown = closeUp = undefined;
+                void Promise.allSettled([prevStop?.(), prevClose?.()]);
+            },
+        };
+    };
+    const link = async (down, upPort, ctl) => {
+        const [prevStop, prevClose] = [stopDown, closeUp];
+        if (ctl) {
+            control = ctl;
+            ctl.onmessage = (e) => void onControl(e);
+            ctl.start?.();
+        }
+        stopDown = await serveRuntime(down, runtime, {
+            // A Worker in another shard opened a socket to one of our objects.
+            onUpgrade: (id, port, protocol) => post({ t: "ws-accept", id, protocol, port }),
+        });
+        const l = await linkOverPort(upPort);
+        closeUp = l.close;
+        // A new router: the previous one is gone, and so are the answers to calls sent to it.
+        if (upstream)
+            dropInflight();
+        upstream = l.send;
+        unlinked = false;
+        for (const w of pending.splice(0))
+            w();
+        await Promise.allSettled([prevStop?.(), prevClose?.()]);
+    };
+    return { route, attach };
+}
+//# sourceMappingURL=shard-worker.js.map

package/dist/router/shard-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-worker.js","sourceRoot":"","sources":["../../src/router/shard-worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6C,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAClG,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,CAAC,EAAE,WAAW,EAAa,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAiB,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAyC,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAuB7D,sFAAsF;AACtF,MAAM,UAAU,iBAAiB,CAAC,IAAwB;IACxD,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,iBAAiB,CAAC;QAChC,GAAG,IAAI;QACP,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;QACzC,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAW5B;IAIC,IAAI,QAA0B,CAAC;IAC/B,IAAI,OAAgC,CAAC;IACrC,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,IAAI,cAAc,EAAE,CAAC;IACnC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC,oCAAoC;IACzD,IAAI,cAA0D,CAAC;IAC/D,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,IAAI,WAAW,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS;YACvC,cAAc,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,CAAC;IAC7E,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,IAAI,EAAE,WAAW,KAAK,CAAC;YAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACzD,CAAC,CAAC;IACF,8EAA8E;IAC9E,IAAI,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC/C,MAAM,YAAY,GAAG,GAAG,EAAE;QACxB,MAAM,IAAI,GAAG,QAAQ,CAAC;QACtB,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,IAAI,KAAK,CACnB,wFAAwF,CACzF,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC,CAAC;IAEF,MAAM,KAAK,GAAS,KAAK,EAAE,GAAG,EAAE,EAAE;QAChC,8EAA8E;QAC9E,IAAI,CAAC,QAAQ,IAAI,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,GAAG,KAAK,EAAE,CAAC;YACzD,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACpB,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QACtB,CAAC;QACD,OAAO,CAAC,QAAQ;YAAE,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,QAAQ,CAAC;QACtB,MAAM,KAAK,GAAG,QAAQ,CAAC;QACvB,OAAO,EAAE,CAAC;QACV,OAAO,IAAI,OAAO,CAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC/C,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAClB,IAAI,CAAC,GAAG,CAAC;iBACN,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC;iBACrB,OAAO,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvB,CAAC,CAAC;IACF,8EAA8E;IAC9E,2EAA2E;IAC3E,MAAM,EAAE,GAAS,KAAK,EAAE,GAAG,EAAE,EAAE;QAC7B,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC;QACjF,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,0DAA0D;QAC/F,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,gCAAgC;QAC3F,IAAI,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAChD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;QAC/E,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,EAAE;YAAE,OAAO,GAAG,CAAC,CAAC,sCAAsC;QAC5F,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChD,OAAO,IAAI,aAAa,CAAC,IAAI,EAAE;YAC7B,MAAM,EAAE,GAAG;YACX,SAAS,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC;YAChC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,wBAAwB,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE;SAChE,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,qFAAqF;IACrF,kEAAkE;IAClE,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,EAA0B,EAAoB,EAAE;QAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC3C,OAAO,CAAC,GAAG,EAAE,EAAE;YACb,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACpC,OAAO,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7D,CAAC,CAAC;IACJ,CAAC,CAAC;IACF,IAAI,OAAqB,CAAC;IAE1B,MAAM,IAAI,GAAG,CAAC,CAAiB,EAAE,EAAE,CACjC,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAA+B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1F,MAAM,SAAS,GAAG,KAAK,EAAE,CAAe,EAAE,EAAE;QAC1C,MAAM,CAAC,GAAG,CAAC,CAAC,IAAsB,CAAC;QACnC,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC5F,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;QAC1E,IAAI,CAAC,CAAC,CAAC,KAAK,YAAY,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;gBACzF,IAAI,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,CAAE,GAAa,EAAE,OAAO,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC;YACtF,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,QAA2C,CAAC;IAChD,IAAI,OAA0C,CAAC;IAC/C,MAAM,MAAM,GAAG,CAAC,EAAe,EAAe,EAAE;QAC9C,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO;YACP,IAAI;YACJ,MAAM;gBACJ,IAAI,CAAC,QAAQ;oBAAE,OAAO;gBACtB,QAAQ,GAAG,SAAS,CAAC;gBACrB,QAAQ,GAAG,IAAI,CAAC;gBAChB,MAAM,GAAG,CAAC,CAAC;gBACX,YAAY,EAAE,CAAC;gBACf,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAClD,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;gBAC/B,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;YACzD,CAAC;SACF,CAAC;IACJ,CAAC,CAAC;IACF,MAAM,IAAI,GAAwB,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;QAC5D,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAClD,IAAI,GAAG,EAAE,CAAC;YACR,OAAO,GAAG,GAAG,CAAC;YACd,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC;YACzC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC;QAChB,CAAC;QACD,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE;YAC3C,mEAAmE;YACnE,SAAS,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;SAChF,CAAC,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;QACrC,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC;QAClB,sFAAsF;QACtF,IAAI,QAAQ;YAAE,YAAY,EAAE,CAAC;QAC7B,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC;QAClB,QAAQ,GAAG,KAAK,CAAC;QACjB,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YAAE,CAAC,EAAE,CAAC;QACvC,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC","sourcesContent":["import { type CellRuntime, type CellRuntimeOptions, createCellRuntime } from \"../core/runtime.js\";\nimport { shardOf } from \"../core/shard.js\";\nimport { H, keepUpgrade, type Send } from \"../transport/cells-link.js\";\nimport { type CellPort, linkOverPort, serveRuntime } from \"../transport/port.js\";\nimport { type ControlMessage, type ControlPort, PortRendezvous } from \"../ws/control.js\";\nimport { CellsResponse, CfWebSocket } from \"../ws/server.js\";\n\nexport interface ShardWorkerOptions extends Omit<CellRuntimeOptions, \"route\"> {\n  shard: number;\n  shards: number;\n}\n\nexport interface ShardWorker {\n  readonly runtime: CellRuntime;\n  /**\n   * (Re)connects to a router: `down` = router → shard (served here),\n   * `up` = shard → router (for DO calls into other shards), `ctl` = control\n   * channel for WebSocket port hand-over. Called again when the router restarts\n   * (a ServiceWorker is killed when idle and loses its ports).\n   */\n  link(down: CellPort, up: CellPort, ctl?: ControlPort): Promise<void>;\n  /**\n   * Drops the links of a router that is gone (a stopped ServiceWorker leaves no trace on its\n   * ports): calls into other shards wait for the next `link`, and `onUnlinked` is told so.\n   */\n  unlink(): void;\n}\n\n/** Runs one shard: hosts the cells of shard `shard`, forwards the others upstream. */\nexport function createShardWorker(opts: ShardWorkerOptions): ShardWorker {\n  const shard = shardRouting(opts);\n  const runtime = createCellRuntime({\n    ...opts,\n    vars: { ...opts.vars, SHARD: opts.shard },\n    route: shard.route,\n  });\n  return shard.attach(runtime);\n}\n\n/**\n * The router side of a shard, for a runtime built elsewhere (a project's, in a browser worker):\n * `route` sends the cells of other shards up to the router (waiting until it is linked);\n * `attach(runtime)` gives the runtime its links to the router.\n */\nexport function shardRouting(opts: {\n  shard: number;\n  shards: number;\n  /** A call into another shard waits after `unlink`: wake the router (once per `unlink`). */\n  onUnlinked?: () => void;\n  /**\n   * Called every `keepAliveMs` (default 20 s) while calls into other shards are in flight: they\n   * are no events for the router's ServiceWorker, which the browser stops when idle (~30 s).\n   */\n  keepAlive?: () => void;\n  keepAliveMs?: number;\n}): {\n  route: NonNullable<CellRuntimeOptions[\"route\"]>;\n  attach(runtime: CellRuntime): ShardWorker;\n} {\n  let upstream: Send | undefined;\n  let control: ControlPort | undefined;\n  const pending: (() => void)[] = [];\n  const ports = new PortRendezvous();\n  let wsSeq = 0;\n  let unlinked = false;\n  let wokeAt = 0;\n  let outstanding = 0; // calls into other shards in flight\n  let keepAliveTimer: ReturnType<typeof setInterval> | undefined;\n  const started = () => {\n    if (outstanding++ === 0 && opts.keepAlive)\n      keepAliveTimer = setInterval(opts.keepAlive, opts.keepAliveMs ?? 20_000);\n  };\n  const finished = () => {\n    if (--outstanding === 0) clearInterval(keepAliveTimer);\n  };\n  /** Calls in flight over the current links: a dead link never answers them. */\n  let inflight = new Set<(err: Error) => void>();\n  const dropInflight = () => {\n    const lost = inflight;\n    inflight = new Set();\n    const err = new Error(\n      \"The router was lost while this call was in flight; it may or may not have been applied\",\n    );\n    for (const fail of lost) fail(err);\n  };\n\n  const rawUp: Send = async (req) => {\n    // Woken once per unlink, again if the router is still not back after a while.\n    if (!upstream && unlinked && Date.now() - wokeAt > 2_000) {\n      wokeAt = Date.now();\n      opts.onUnlinked?.();\n    }\n    while (!upstream) await new Promise<void>((r) => pending.push(r));\n    const send = upstream;\n    const calls = inflight;\n    started();\n    return new Promise<Response>((resolve, reject) => {\n      calls.add(reject);\n      send(req)\n        .then(resolve, reject)\n        .finally(() => calls.delete(reject));\n    }).finally(finished);\n  };\n  // DO → DO calls into other shards. A WebSocket upgrade gets an id; the owning\n  // shard hands the socket's port over the control channel (via the router).\n  const up: Send = async (req) => {\n    if (req.headers.get(\"Upgrade\")?.toLowerCase() !== \"websocket\") return rawUp(req);\n    const id = `s${opts.shard}:${++wsSeq}`;\n    const headers = new Headers(req.headers);\n    headers.set(H.ws, id);\n    headers.set(H.upgrade, \"websocket\"); // hop-by-hop `Upgrade` does not survive the HTTP/1.1 link\n    const offered = req.headers.get(\"Sec-WebSocket-Protocol\"); // forbidden in browser Requests\n    if (offered) headers.set(H.wsProtocol, offered);\n    const res = await rawUp(new Request(req.url, { method: req.method, headers }));\n    if (res.headers.get(H.wsAccepted) !== id) return res; // refused upgrade (plain HTTP answer)\n    const { port, protocol } = await ports.wait(id);\n    return new CellsResponse(null, {\n      status: 101,\n      webSocket: new CfWebSocket(port),\n      headers: protocol ? { \"Sec-WebSocket-Protocol\": protocol } : {},\n    });\n  };\n\n  // The owner travels with the request: the router need not derive it (it cannot for a\n  // project's internal namespaces, whose ids come from other keys).\n  const route = (_key: string, id: { toString(): string }): Send | undefined => {\n    const owner = shardOf(id.toString(), opts.shards);\n    if (owner === opts.shard) return undefined;\n    return (req) => {\n      const headers = new Headers(req.headers);\n      headers.set(H.shard, String(owner));\n      return up(keepUpgrade(req, new Request(req, { headers })));\n    };\n  };\n  let runtime!: CellRuntime;\n\n  const post = (m: ControlMessage) =>\n    control?.postMessage(m, m.t === \"ws-accept\" ? [m.port as unknown as Transferable] : []);\n  const onControl = async (e: MessageEvent) => {\n    const m = e.data as ControlMessage;\n    if (m.t === \"ws-accept\") return ports.deliver(m.id, { port: m.port, protocol: m.protocol });\n    if (m.t === \"ws-refuse\") return ports.deliver(m.id, new Error(m.message));\n    if (m.t === \"ws-connect\") {\n      try {\n        const { port, protocol } = await runtime.connectWebSocket(m.url, m.protocols, m.headers);\n        post({ t: \"ws-accept\", id: m.id, protocol, port });\n      } catch (err) {\n        post({ t: \"ws-refuse\", id: m.id, message: String((err as Error)?.message ?? err) });\n      }\n    }\n  };\n\n  let stopDown: (() => Promise<void>) | undefined;\n  let closeUp: (() => Promise<void>) | undefined;\n  const attach = (rt: CellRuntime): ShardWorker => {\n    runtime = rt;\n    return {\n      runtime,\n      link,\n      unlink() {\n        if (!upstream) return;\n        upstream = undefined;\n        unlinked = true;\n        wokeAt = 0;\n        dropInflight();\n        const [prevStop, prevClose] = [stopDown, closeUp];\n        stopDown = closeUp = undefined;\n        void Promise.allSettled([prevStop?.(), prevClose?.()]);\n      },\n    };\n  };\n  const link: ShardWorker[\"link\"] = async (down, upPort, ctl) => {\n    const [prevStop, prevClose] = [stopDown, closeUp];\n    if (ctl) {\n      control = ctl;\n      ctl.onmessage = (e) => void onControl(e);\n      ctl.start?.();\n    }\n    stopDown = await serveRuntime(down, runtime, {\n      // A Worker in another shard opened a socket to one of our objects.\n      onUpgrade: (id, port, protocol) => post({ t: \"ws-accept\", id, protocol, port }),\n    });\n    const l = await linkOverPort(upPort);\n    closeUp = l.close;\n    // A new router: the previous one is gone, and so are the answers to calls sent to it.\n    if (upstream) dropInflight();\n    upstream = l.send;\n    unlinked = false;\n    for (const w of pending.splice(0)) w();\n    await Promise.allSettled([prevStop?.(), prevClose?.()]);\n  };\n  return { route, attach };\n}\n"]}

package/dist/transport/cells-http.d.ts

@@ -0,0 +1,25 @@
+import { DurableObjectNamespace } from "../core/namespace.js";
+import type { CellRuntime } from "../core/runtime.js";
+import type { ValueCodec } from "../ports.js";
+import { type Send } from "./cells-link.js";
+export interface CellsHttpOptions {
+    codec?: ValueCodec;
+    /**
+     * A stub.fetch answered 101 with a WebSocket: hand the client end's port to the
+     * caller out of band (the HTTP link cannot carry ports). Without it, WebSocket
+     * upgrades cannot cross this link.
+     */
+    onUpgrade?: (id: string, port: MessagePort, protocol?: string) => void;
+}
+/** Server side: exposes a runtime as one HTTP handler. */
+export declare function errorResponse(e: unknown, status?: number): Response;
+export declare function cellsHttpHandler(runtime: CellRuntime, opts?: CellsHttpOptions): (req: Request) => Promise<Response>;
+export interface RemoteRuntime {
+    /** Ingress into the remote Worker's default fetch handler. */
+    fetch(req: Request): Promise<Response>;
+    /** Namespaces whose stubs send HTTP over the link (idFromName computed locally). */
+    readonly env: Record<string, DurableObjectNamespace>;
+}
+/** Client side over any `send` (fetchOverDuplex over a port / WebSocket / peer, or the handler itself). */
+export declare function remoteRuntime(send: Send, opts?: CellsHttpOptions): Promise<RemoteRuntime>;
+export declare function stripControl(req: Request, keep?: string[]): Request;