Initial Commit

openspec/specs/network-webrtc/spec.md

@@ -0,0 +1,113 @@
+# Capability Spec: network-webrtc
+
+## Capability ID
+
+`network-webrtc`
+
+## Status
+
+PROPOSED
+
+## Description
+
+WebRTC peer-to-peer transport for the tiered network mesh. Provides signaling, ICE management, data channels, peer mesh maintenance, and latency measurement.
+
+## Interfaces
+
+### `SignalingClient`
+
+```typescript
+interface SignalingClient {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  send(message: SignalingMessage): Promise<void>;
+  onMessage(handler: (msg: SignalingMessage) => void): () => void;
+}
+```
+
+### `WebRTCTransport`
+
+```typescript
+interface WebRTCTransport extends Transport {
+  createPeerConnection(peerId: string): RTCPeerConnection;
+  closePeerConnection(peerId: string): void;
+  getPeerConnection(peerId: string): RTCPeerConnection | undefined;
+}
+```
+
+### `WebRTCMesh`
+
+```typescript
+interface WebRTCMesh {
+  connectToPeer(peerId: string): Promise<void>;
+  disconnectFromPeer(peerId: string): void;
+  getConnectedPeers(): string[];
+}
+```
+
+### `PingManager`
+
+```typescript
+interface PingManager {
+  start(): void;
+  stop(): void;
+  getLatency(peerId: string): number | undefined;
+}
+```
+
+## Behaviors
+
+### NET-WEB-01 — Signaling
+
+The signaling client MUST connect to a WebSocket server, send `offer`/`answer`/`ice-candidate` messages, and receive corresponding messages from remote peers.
+
+### NET-WEB-02 — ICE Restart
+
+When `iceConnectionState` transitions to `failed`, the transport MUST automatically trigger ICE restart.
+
+### NET-WEB-03 — Data Channel
+
+The transport MUST open a reliable, ordered data channel per peer. Messages MUST be emitted as `Uint8Array` on the `NetworkBus`.
+
+### NET-WEB-04 — Backpressure
+
+The transport MUST pause sending when `bufferedAmount` exceeds a configurable threshold and resume when it drops below a lower threshold.
+
+### NET-WEB-05 — Mesh Auto-Connect
+
+The mesh MUST automatically connect to newly discovered peers and maintain a full mesh (all-to-all connections within the group).
+
+### NET-WEB-06 — Mesh Removal
+
+The mesh MUST remove peers on disconnect or heartbeat timeout and emit `peer:disconnected` on the `NetworkBus`.
+
+### NET-WEB-07 — Ping/Latency
+
+The ping manager MUST send correlated echo frames, measure RTT, apply EMA smoothing, and publish `peer:latency` on the `NetworkBus`.
+
+### NET-WEB-08 — Configurable ICE Servers
+
+The transport MUST accept configurable STUN/TURN servers.
+
+## Error codes
+
+- `NET_WEBRTC_SIGNALLING_FAILED` — WebSocket connection failed
+- `NET_WEBRTC_ICE_FAILED` — ICE connection failed after restart
+- `NET_WEBRTC_DATA_CHANNEL_CLOSED` — Data channel closed unexpectedly
+- `NET_WEBRTC_BACKPRESSURE_EXCEEDED` — Buffered amount exceeded max
+
+## Dependencies
+
+- `@suaveplan/network`
+- `@suaveplan/error`
+- `@suaveplan/types`
+- `@suaveplan/events`
+- `@suaveplan/streams`
+- `@suaveplan/timing`
+- `@opentelemetry/api`
+- `zod`
+
+## Notes
+
+- WebRTC is browser-only; Node.js peers use `network-websockets` or `network-standby-transport`.
+- The mesh size is bounded by the registry capacity (default 32 peers).