223 lines
6.8 KiB
Markdown
223 lines
6.8 KiB
Markdown
# OpenSpec Change: enterprise-browser-network-webrtc
|
|
|
|
- **Change ID**: enterprise-browser-network-webrtc
|
|
- **Package**: `@suaveplan/network-webrtc`
|
|
- **Category**: browser
|
|
- **Target path**: `browser/network/network-webrtc`
|
|
- **Status**: SUPERSEDED-BY-GENESIS-WAVE
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/network-webrtc.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/network-webrtc` on the genesis branch from scratch at enterprise quality. The package provides the browser-side WebRTC transport for `@suaveplan/network`: a `WebRTCTransport` wrapping `RTCPeerConnection` + `RTCDataChannel`, a dual-channel system for reliable + unreliable messaging, a `ChannelRouter` dispatching by topic, and a first-class `SignalingChannel` interface with Memory / WebSocket / WebTorrent implementations. No React dependencies — demo UI moves to a React companion package.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
The package does not exist on genesis yet — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/network` (`workspace:^`) | `Transport` interface, `NetworkError`, connection lifecycle types |
|
|
| `@suaveplan/error` (`workspace:^`) | Typed WebRTC errors |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `EventBusLike` |
|
|
| `@suaveplan/events` (`workspace:^`) | `EventEmitter` for transport event maps |
|
|
| `@suaveplan/serialize` (`workspace:^`) | Structured message encoding/decoding |
|
|
| `@suaveplan/schema-registry` (`workspace:^`) | Register signalling Zod schemas |
|
|
| `zod` (`catalog:forms`) | Schemas for signalling message types |
|
|
| `@opentelemetry/api` (`catalog:observability`) | WebRTC metrics |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `@playwright/test` (`catalog:testing`), `@suaveplan/testing workspace:^`.
|
|
|
|
---
|
|
|
|
## Preserved public API surface (from main branch)
|
|
|
|
### Core transport
|
|
|
|
```ts
|
|
class WebRTCTransport {
|
|
constructor(config: WebRTCConfig)
|
|
dial(signal: SignalingChannel): Promise<void>
|
|
close(): void
|
|
send(data: Uint8Array | string): void
|
|
sendUnreliable(data: Uint8Array | string): void
|
|
onMessage(handler: (data: Uint8Array | string) => void): void
|
|
onClose(handler: () => void): void
|
|
getStats(): Promise<RTCStatsReport>
|
|
readonly state: RTCPeerConnectionState
|
|
}
|
|
|
|
interface WebRTCConfig {
|
|
iceServers?: RTCIceServer[]
|
|
ordered?: boolean
|
|
maxRetransmits?: number
|
|
allowedWorkletUrls?: string[]
|
|
}
|
|
```
|
|
|
|
### Dual channel
|
|
|
|
```ts
|
|
class DualChannel {
|
|
constructor(connection: RTCPeerConnection, config?: DualChannelConfig)
|
|
sendReliable(data: Uint8Array | string): void
|
|
sendUnreliable(data: Uint8Array | string): void
|
|
onMessage(handler: (data: Uint8Array | string, reliable: boolean) => void): void
|
|
close(): void
|
|
}
|
|
```
|
|
|
|
### Channel router
|
|
|
|
```ts
|
|
class ChannelRouter {
|
|
register(channelId: string, handler: ChannelHandler): void
|
|
unregister(channelId: string): void
|
|
route(message: ChannelMessage): void
|
|
send(channelId: string, payload: unknown): void
|
|
}
|
|
|
|
interface ChannelMessage { channelId: string; payload: unknown; reliable?: boolean }
|
|
type ChannelHandler = (payload: unknown) => void
|
|
```
|
|
|
|
### Signalling interface
|
|
|
|
```ts
|
|
interface SignalingChannel {
|
|
sendOffer(offer: RTCSessionDescriptionInit): Promise<void>
|
|
sendAnswer(answer: RTCSessionDescriptionInit): Promise<void>
|
|
sendIceCandidate(candidate: RTCIceCandidateInit): Promise<void>
|
|
onOffer(handler: (offer: RTCSessionDescriptionInit) => void): void
|
|
onAnswer(handler: (answer: RTCSessionDescriptionInit) => void): void
|
|
onIceCandidate(handler: (candidate: RTCIceCandidateInit) => void): void
|
|
close(): void
|
|
}
|
|
|
|
class MemorySignalingChannel implements SignalingChannel { ... }
|
|
class WebSocketSignalingChannel implements SignalingChannel { constructor(url: string) }
|
|
```
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
### 1. Structured errors via `@suaveplan/error`
|
|
|
|
Error codes: `WEBRTC_DIAL_FAILED`, `WEBRTC_ICE_FAILED`, `WEBRTC_CHANNEL_CLOSED`, `WEBRTC_SIGNALING_TIMEOUT`, `WEBRTC_INVALID_STATE`.
|
|
|
|
### 2. Perfect-negotiation pattern
|
|
|
|
`PeerConnection` implements "polite peer" logic — avoids offer/answer glare on simultaneous negotiation.
|
|
|
|
### 3. ICE-restart policy
|
|
|
|
Detect `iceConnectionState === 'failed'`; auto-restart ICE; surface as typed event `'ice:restart'`.
|
|
|
|
### 4. Flow control + back-pressure
|
|
|
|
`DualChannel.sendReliable` tracks `RTCDataChannel.bufferedAmount`; blocks or queues when buffer exceeds a configurable watermark.
|
|
|
|
### 5. OTel metrics
|
|
|
|
Counters `webrtc.dial_total`, `webrtc.bytes_in_total`, `webrtc.bytes_out_total`; histogram `webrtc.ice_gather_ms`, `webrtc.rtt_ms`.
|
|
|
|
### 6. Signalling message Zod schemas
|
|
|
|
Schemas for offer/answer/ICE-candidate messages registered in `@suaveplan/schema-registry`.
|
|
|
|
### 7. STUN/TURN configuration helpers
|
|
|
|
Curated `iceServers` bundles with validation helper; `TURN_CONFIG` constants for common providers.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
browser/network/network-webrtc/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
webrtc/
|
|
peer-connection/
|
|
peer-connection.ts (RTCPeerConnection wrapper + ICE restart + perfect negotiation)
|
|
peer-connection.md
|
|
peer-connection.test.ts
|
|
index.ts
|
|
data-channel/
|
|
data-channel.ts
|
|
data-channel.md
|
|
data-channel.test.ts
|
|
index.ts
|
|
signaling-handlers/
|
|
signaling-handlers.ts
|
|
signaling-handlers.md
|
|
signaling-handlers.test.ts
|
|
index.ts
|
|
webrtc-transport/
|
|
webrtc-transport.ts
|
|
webrtc-transport.md
|
|
webrtc-transport.types.ts
|
|
webrtc-transport.test.ts
|
|
index.ts
|
|
dual-channel/
|
|
dual-channel/
|
|
dual-channel.ts
|
|
dual-channel.md
|
|
dual-channel.test.ts
|
|
index.ts
|
|
channel-router/
|
|
channel-router/
|
|
channel-router.ts
|
|
channel-router.md
|
|
channel-router.test.ts
|
|
index.ts
|
|
signaling/
|
|
signaling-channel/
|
|
signaling-channel.ts (interface + MemorySignalingChannel)
|
|
signaling-channel.md
|
|
signaling-channel.test.ts
|
|
index.ts
|
|
websocket-signaling/
|
|
websocket-signaling.ts
|
|
websocket-signaling.md
|
|
websocket-signaling.test.ts
|
|
index.ts
|
|
config/
|
|
ice-servers/
|
|
ice-servers.ts
|
|
ice-servers.md
|
|
index.ts
|
|
tests/
|
|
integration.test.ts
|
|
e2e/
|
|
webrtc.spec.ts (Playwright two-browser offer/answer/ICE/dial/send)
|
|
examples/ (NOT in package.json "files")
|
|
basic-usage.ts
|
|
memory-signaling.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: `@suaveplan/drive-webrtc`, `@suaveplan/network-discovery-webtorrent`, WebRTC-based game networking.
|
|
|
|
**Breaking changes**: `react` removed from runtime deps (demo moved to companion); examples moved out of published tarball.
|
|
|
|
**Prerequisites**: `@suaveplan/network`, `@suaveplan/serialize`, `@suaveplan/error`, `@suaveplan/events` on Verdaccio.
|