feat: WebSocket support via functional events

[brainkim]

Summary

• Adds websocketmessage and websocketclose as new ServiceWorker functional events (ExtendableEvent subclasses)
• FetchEvent.upgradeWebSocket() upgrades connections — no HTTP Response created (101 is invalid in Node.js)
• Pool returns typed WebSocketUpgradeResult instead of monkeypatched Response objects
• Node.js adapter uses ws package with lazy loading; Bun uses native Bun.serve WebSocket support
• createDirectModePool() provides pool-compatible interface for single-worker deployments
• Full TypeScript types in globals.d.ts (WebSocketClient, event types, upgradeWebSocket on FetchEvent)

User-facing API

self.addEventListener("fetch", (event) => {
  if (event.request.headers.get("upgrade") === "websocket") {
    event.upgradeWebSocket({ data: { room: "lobby" } });
    return;
  }
  event.respondWith(new Response("Hello"));
});

self.addEventListener("websocketmessage", (event) => {
  event.source.send(`Echo: ${event.data}`);
});

self.addEventListener("websocketclose", (event) => {
  console.log(`Closed: ${event.code} ${event.reason}`);
});

Test plan

• All 194 package tests pass
• 24 build tests pass
• 19 e2e direct mode tests pass
• 17 e2e bundling tests pass
• TypeScript clean across all 3 platform packages
• ESLint clean
• Manual WebSocket echo server test
• Multi-worker WebSocket sticky routing test

🤖 Generated with Claude Code

[brainkim]

Closing in favor of a redesign

After extensive design discussion, we're not merging this PR. The core issue: it shoehorns WebSockets into the ServiceWorker Clients abstraction (WebSocketClient extends Client, matchAll({type: "websocket"}), ClientQueryOptions extension), and that's a direction we can't defend as standards-adjacent. The Client interface models browsing contexts the SW controls; an inbound WebSocket connection isn't one, and making it pretend to be breaks the abstraction in several places (postMessage semantics, frameType, type enum).

Design principle we landed on

Extend via new event types and methods on new event classes we own. Never modify standards classes (WebSocket, FetchEvent, Client, Clients, BroadcastChannel).

This preserves the option for future standards to evolve without conflicting with Shovel, keeps the "portable web standards" promise honest, and surgically contains the invention to surfaces we own.

New direction (sketch)

Three new event types on ServiceWorkerGlobalScope:

"websocketupgrade"  -> WebSocketUpgradeEvent extends ExtendableEvent
"websocketmessage"  -> WebSocketMessageEvent extends ExtendableEvent
"websocketclose"    -> WebSocketCloseEvent extends ExtendableEvent

All interaction happens via methods on these new classes. Users never see a WebSocket instance. IDs and send/close/subscribe/unsubscribe live on the event objects. Cross-isolate fanout piggybacks on BroadcastChannel via one semantic rule (BC messages published on a channel name are forwarded as send() to every WebSocket that subscribe()'d to that channel). No extensions to BroadcastChannel itself.

No touches to WebSocket, FetchEvent, Client, Clients, ClientQueryOptions, or BroadcastChannel. Estimated surface: ~20-30 lines in globals.d.ts, vs 63 here.

What's preserved

The commits on feat/websocket-events remain on the branch. The 35 regression tests encode real behavior we want the new implementation to maintain (echo, binary frames, close-during-upgrade, non-cloneable data, hibernation rehydration, phantom client cleanup). They'll port over with API substitution.

The Cloudflare DO hibernation plumbing in packages/platform-cloudflare/src/websocket-do.ts is largely reusable — the semantics change (subscription-based forwarding instead of Client registration) but the DO lifecycle and serializeAttachment patterns carry forward.

Next step

New PR against a fresh branch, starting from globals.d.ts and writing types first to ground every API question before touching runtime code.