OpenSpec Change: network-plugin-webrtc

Change ID: network-plugin-webrtc
Package: @suaveplan/network-plugin-webrtc (new)
Status: PROPOSED
Type: new-package
Date: 2026-04-29

Why

The core network package defines the Transport interface but ships no implementation. For browser-to-browser mesh networking — the primary use-case for the tiered host-nomination system — WebRTC is the only practical peer-to-peer transport. This plugin implements the Transport contract using RTCPeerConnection and RTCDataChannel, adds automatic mesh formation, ICE restart, RTT measurement (ping), and signaling pluggability so it can work with any signaling backend (WebSocket, HTTP POST, or a future DHT plugin).

What changes

ADDED: WebRTCPlugin class implementing NetworkPlugin and Transport.
ADDED: WebRTCTransport — manages RTCPeerConnection lifecycle per peer: create, offer/answer, ICE handling, data channel open/close.
ADDED: WebRTCMesh — automatic mesh formation: on peer discovery, initiates connection; on peer disconnect, removes from mesh. Maintains full-mesh within a group.
ADDED: DataChannelManager — opens labeled data channels, handles bufferedAmount backpressure, emits message events as Uint8Array.
ADDED: PingManager — sends correlated echo frames over any active transport (not just WebRTC), measures RTT with EMA smoothing, calculates jitter and packet loss, maintains a composite reliability score, publishes peer:latency on the bus. Can be used by network-plugin-transport-manager to health-monitor any transport type.
ADDED: SignalingClient interface — pluggable signaling: connect(), send(signal), onSignal(handler), disconnect(). Ships with a WebSocketSignalingClient implementation.
ADDED: IceManager — monitors iceConnectionState, triggers ICE restart on failure, surfaces transport:ice-restart events.
ADDED: NETWORK_WEBRTC_CODES — frozen error registry.

Out of scope

TURN server deployment or TURN credential rotation → ops concern, documented but not implemented.
DHT-based peer discovery without signaling → future network-plugin-discovery-dht.
Simulcast / SFU mode → future network-plugin-sfu.
Screen sharing or media tracks → this is a data-channel transport only.

Source mapping

This change derives from ../suaveplan/enterprise/network-webrtc.md, ../suaveplan/enterprise/drive-webrtc.md, and ../suaveplan/packages/browser/network-webrtc/.

Requirement	Source lines	Notes
WebRTC peer connection lifecycle	`drive-webrtc.md` §2, `network-webrtc/README.md`	reworded; merged with Transport interface
Data channel byte transport	`drive-webrtc.md` §2 `DataChannelManager`	verbatim contract
ICE restart on failure	`drive-webrtc.md` §3.6	verbatim
Ping / RTT measurement	`network/src/transport/legacy/base-transport.md` (stub)	new requirement — source only had a TODO
Signaling pluggability	`drive-webrtc.md` §4.8	verbatim

Requirements with no source line

Requirement	Justification
`PingManager` with EMA	Source had `"Ping not implemented"` stub; genesis implements it properly using `timing` EMA
Full-mesh within group	Required for the tiered host-nomination voting use-case
`bufferedAmount` backpressure	Prevents datachannel buffer overflow in high-throughput scenarios

Verification approach

src/transport/transport.spec-conformance.test.ts — pins Transport interface compliance (connect, disconnect, send, onMessage, getConnectedPeers).
src/mesh/mesh.spec-conformance.test.ts — pins automatic connection on peer discovery and removal on disconnect.
src/ping/ping.spec-conformance.test.ts — pins correlated echo, RTT calculation, EMA smoothing.
src/ice/ice.spec-conformance.test.ts — pins ICE restart on failed state.
src/signaling/signaling.spec-conformance.test.ts — pins SignalingClient interface and WebSocket implementation.
src/backpressure/backpressure.spec-conformance.test.ts — pins bufferedAmount pause/resume.
tests/dep-graph.test.ts — pins no browser-only APIs leak into non-browser builds.

Migration impact

None — additive only.

4.2 KiB Raw Blame History