64 lines
4.2 KiB
Markdown
64 lines
4.2 KiB
Markdown
# 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.
|