feat: WebSocket support via functional events

[brainkim]

Summary

WebSocket support for Shovel via functional events, across all three platforms (Node, Bun, Cloudflare). Supersedes #82.

Built on one strict rule: no modifications to standards classes. WebSocket, Client, Clients, BroadcastChannel, ClientQueryOptions are untouched. Everything new lives on new event classes we own, plus a single FetchEvent.upgradeWebSocket() method (shape-analogous to respondWith/waitUntil). See the #82 closing rationale for why the earlier WebSocketClient extends Client approach was abandoned.

User-facing API

interface WebSocketConnection {
  readonly id: string;
  send(data: string | ArrayBuffer): void;
  close(code?: number, reason?: string): void;
  subscribe(channel: string): void;
  unsubscribe(channel: string): void;
}

interface FetchEvent {
  upgradeWebSocket(): WebSocketConnection;
}

interface WebSocketMessageEvent extends ExtendableEvent {
  readonly source: WebSocketConnection;
  readonly data: string | ArrayBuffer;
}

interface WebSocketCloseEvent extends ExtendableEvent {
  readonly id: string;
  readonly code: number;
  readonly reason: string;
  readonly wasClean: boolean;
}

self.addEventListener("fetch", async (event) => {
  if (event.request.headers.get("upgrade") === "websocket") {
    const ws = event.upgradeWebSocket();
    ws.subscribe("room:lobby");
    ws.send(JSON.stringify({type: "welcome"}));
    return;
  }
  event.respondWith(new Response("..."));
});

self.addEventListener("websocketmessage", (event) => {
  new BroadcastChannel("room:lobby").postMessage(event.data);
});

self.addEventListener("websocketclose", async (event) => {
  await storage.hdel("ws:users", event.id);
});

Cross-isolate fan-out piggybacks on BroadcastChannel via one semantic rule: a message published on a channel name is delivered as send() to every WebSocket that subscribe()'d to that channel — publishable from a cron handler, another isolate, anywhere.

Scope

• Core runtime: ShovelWebSocketConnection, upgradeWebSocket(), websocketmessage / websocketclose dispatch, per-connection ordered delivery (globals.d.ts, runtime.ts, index.ts).
• Node adapter (ws package, lazy-loaded) — direct + pool modes.
• Bun adapter (native Bun.serve) — direct + pool modes.
• Cloudflare adapter — Durable Object with the Hibernation API (websocket-do.ts), and a pub/sub DO (pubsub.ts) that holds a persisted per-channel registry of subscriber DO IDs and wakes hibernated subscriber DOs on publish via fetch("/_shovel_publish"). This is what makes channel fan-out correct on Cloudflare even when a subscriber's DO is evicted.
• Pool IPC: WorkerUpgradeMessage / WebSocketPoolHandlers thread subscriber identity across the worker-thread boundary.
• Example: examples/chat — single-room chat + e2e test.

Reviewer guidance — where to focus

This is a large PR; the highest-leverage areas for review:

1. Cloudflare cross-isolate delivery semantics (pubsub.ts) — the registry/wake model is the load-bearing, newest piece. See "Known limitations" below; the central question is whether at-most-once, fire-and-forget delivery is the right v1 contract.
2. Hibernation lifecycle (websocket-do.ts) — serializeAttachment/rehydration on wake, the webSocketError→websocketclose dedup, per-connection ordered dispatch.
3. Per-adapter duplication — the ordered-dispatch chain, the PendingFrame buffer-then-flush relay, and toHttpErrorResponse are each reimplemented per adapter. Intentional for now, but a candidate for a shared runtime helper (noted below).

Known limitations (intentional v1 tradeoffs — flagged for discussion)

Surfaced by review and deliberately not patched here, because they're design decisions rather than bugs:

• Cross-isolate delivery is fire-and-forget / at-most-once. A failed /subscribe or /_shovel_publish is logged, not retried; there's no ack or reconciliation. A transiently-failed subscribe can leave an isolate locally subscribed but absent from the registry.
• No registry reaping. A subscriber DO evicted/crashed without a clean /unsubscribe leaves its (channel, doId) entry in storage, so future publishes keep waking a dead DO. No TTL/liveness pruning yet.
• Non-DO receive socket doesn't reconnect if the pub/sub DO is evicted mid-session.
• websocketmessage waitUntil is awaited inside the per-connection ordered chain, so a slow background task head-of-line-blocks later frames on that connection. Fixing correctly means plumbing ctx.waitUntil through the message event — a deliberate change.

If reviewers consider any of these blockers rather than follow-ups, I'll address them in this PR.

Review fixes already applied

From an initial review pass (latest commit):

• webSocketError now dispatches websocketclose (workerd may fire error without a follow-up close), with a #finalized guard so the handler runs exactly once.
• Fixed a pendingFrames leak on failed pool-upgrade handshakes (Node + Bun).
• Hot-path efficiency: serialize the publish payload once per publish (not per subscriber); re-serialize the hibernation attachment only when subscriptions change; capture _dispatchPubSubMessage to drop a per-delivery dynamic import.

Testing

• Platform package suites (Node/Bun/Cloudflare/core): 257 pass.
• Cloudflare e2e (Miniflare): cloudflare-websocket, cloudflare-pubsub-hibernation (wake + publish ordering), pool-websocket-close.
• build / lint / typecheck / test green in CI.

Note: the Miniflare-based cloudflare-*.test.* files are run in separate bun test invocations (see bunfig.toml) to avoid a workerd "Broken pipe on fd=3" flake when run concurrently.

🤖 Generated with Claude Code