114 lines
3.0 KiB
Markdown
114 lines
3.0 KiB
Markdown
# 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).
|