suaveplan/openspec/archive/2026-05-11-network-transport-websockets-adapter/proposal.md

OpenSpec Change: network-transport-websockets-adapter

• Change ID: network-transport-websockets-adapter
• Package: @suaveplan/network-transport-websockets (already exists at 0.1.0)
• Category: universal
• Target path: packages/network/network-transport-websockets (in place)
• Status: PROPOSED
• Date: 2026-05-11
• Parent: network-transport-family (2026-05-11) — Wave 1, audit finding 2.3

---

Summary

Refactor @suaveplan/network-transport-websockets from its current client-server WebSocketClient shape into a peer-oriented Transport implementation registered as a NetworkPlugin. The package was migrated to genesis before the Transport contract from @suaveplan/network ✅ existed; today it exposes a connect-to-a-server abstraction (typed framing, heartbeat, backpressure queue, adapters) but does NOT implement connect(peerId) / disconnect(peerId) / send(peerId, envelope) / onMessage / getConnectedPeers / close. This change adds a WebSocketTransport + WebSocketPlugin layer on top of the existing client surface so the package can plug into network-plugin-transport-manager ✅ alongside network-transport-webrtc ✅.

---

Why this is needed

Per the audit finding recorded in openspec/changes/network-transport-family/tasks.md §2.3:

network-transport-websockets predates the Transport contract and exposes a client-server WebSocketClient rather than a peer transport. Wiring it as a NetworkPlugin requires a non-trivial refactor (per-peer connections, getConnectedPeers() aggregation, transport:connected/disconnected bus emission). Deferred to a dedicated child proposal.

This is that proposal. Three downstream consumers are blocked until it lands:

1. network-plugin-transport-manager ✅ — cannot register WS as a fallback transport without the adapter.
2. network-transport-webrtc ✅ — needs WS as a fallback in its signaling channel.
3. websocket-gateway (Wave 5) — server-side rooms + presence depends on the transport contract being honoured.

---

What changes

New code

• src/transport/transport.ts — WebSocketTransport implements Transport (from @suaveplan/network)
  • connect(peerId, address) → creates a new WebSocketClient keyed by peerId
  • disconnect(peerId) → closes the per-peer client
  • send(peerId, envelope) → delegates to the per-peer client's framed send
  • onMessage(handler) → fan-in across every per-peer client
  • getConnectedPeers() → snapshot of keys
  • close() → closes every per-peer client
• src/plugin/plugin.ts — WebSocketPlugin implements NetworkPlugin mirroring WebRTCPlugin shape:
  • install(node) → node.registerTransport(this.transport)
  • start() → no-op (lazy connect)
  • stop() → close transport + unregister
  • dispose() → idempotent cleanup
• src/transport/transport.spec-conformance.test.ts — runs the Transport contract conformance suite
• src/plugin/plugin.spec-conformance.test.ts — runs the NetworkPlugin lifecycle conformance suite
• Sibling .md docs for both modules

Existing code

• src/core/client/ — keep. The new WebSocketTransport composes per-peer WebSocketClient instances.
• src/core/queue/ + src/core/heartbeat/ — keep, consumed per-peer.
• src/adapters/ — keep, injectable through the new transport.
• src/types/ — extend with WebSocketTransportConfig (per-peer client config + transport-level limits).

Error codes

• Extend the existing defineCodes("NET_WS", [...]) registry with: PEER_ALREADY_CONNECTED, PEER_UNKNOWN, TRANSPORT_CLOSED, MAX_PEERS_EXCEEDED.

Observability

• Spans: ws_transport.connect, ws_transport.disconnect, ws_transport.send.
• Counters: ws_transport.peers_connected{outcome}, ws_transport.messages_total{direction,outcome}.
• Gauges: ws_transport.active_peers.

---

Parity Checklist

Migration from upstream is already complete; this is a refactor adding the Transport adapter. The original WebSocketClient API is preserved.

Capability	Before	After	Notes
WebSocketClient typed framing	✅	✅	Unchanged.
Heartbeat / ping-pong	✅	✅	Unchanged; runs per-peer.
Backpressure queue	✅	✅	Unchanged; runs per-peer.
Injectable transport adapters	✅	✅	Unchanged.
Transport contract	🚫	⬆️	NEW — WebSocketTransport.
NetworkPlugin lifecycle	🚫	⬆️	NEW — WebSocketPlugin.
Multi-peer fan-in/fan-out	🚫	⬆️	NEW — per-peer client registry.
transport:connected/disconnected bus events	🚫	⬆️	NEW — on bus when a NetworkBus is provided via plugin.
Backward compatibility	✅	✅	Existing WebSocketClient consumers (none in genesis, but downstream @suaveplan/network-transport-webrtc signaling client uses the type) keep working — the new transport composes them.

---

Acceptance gate

1. bunx turbo lint typecheck test --filter=@suaveplan/network-transport-websockets green.
2. bunx turbo test:coverage --filter=@suaveplan/network-transport-websockets at 100/100/100/100 (currently 60 tests pass after the rename; adding the transport+plugin adds another conformance suite).
3. bun run docs:check --filter=@suaveplan/network-transport-websockets green.
4. network-plugin-transport-manager integration test confirms WS-as-fallback works end-to-end.
5. openspec/specs/network/spec.md updated under ## MODIFIED Requirements if any NET-* requirement is tightened.

---

Out of scope

• Server-side websocket-gateway (Wave 5, separate package).
• TLS / mTLS cert management for production WSS — that's a deployment concern, not a transport concern.
• Custom subprotocols beyond what the existing WebSocketClient supports.