3.0 KiB
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
interface SignalingClient {
connect(): Promise<void>;
disconnect(): Promise<void>;
send(message: SignalingMessage): Promise<void>;
onMessage(handler: (msg: SignalingMessage) => void): () => void;
}
WebRTCTransport
interface WebRTCTransport extends Transport {
createPeerConnection(peerId: string): RTCPeerConnection;
closePeerConnection(peerId: string): void;
getPeerConnection(peerId: string): RTCPeerConnection | undefined;
}
WebRTCMesh
interface WebRTCMesh {
connectToPeer(peerId: string): Promise<void>;
disconnectFromPeer(peerId: string): void;
getConnectedPeers(): string[];
}
PingManager
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 failedNET_WEBRTC_ICE_FAILED— ICE connection failed after restartNET_WEBRTC_DATA_CHANNEL_CLOSED— Data channel closed unexpectedlyNET_WEBRTC_BACKPRESSURE_EXCEEDED— Buffered amount exceeded max
Dependencies
@suaveplan/network@suaveplan/error@suaveplan/types@suaveplan/events@suaveplan/streams@suaveplan/timing@opentelemetry/apizod
Notes
- WebRTC is browser-only; Node.js peers use
network-websocketsornetwork-standby-transport. - The mesh size is bounded by the registry capacity (default 32 peers).