4.9 KiB
OpenSpec Change: enterprise-browser-network-discovery-peerjs
- Change ID: enterprise-browser-network-discovery-peerjs
- Package:
@suaveplan/network-discovery-peerjs - Category: browser
- Target path:
browser/network/network-discovery-peerjs - Status: SUPERSEDED-BY-GENESIS-WAVE
- Date: 2026-04-24
- Reference spec:
/mnt/s/web/suaveplan/enterprise/network-discovery-peerjs.md
Summary
Deliver @suaveplan/network-discovery-peerjs on the genesis branch at enterprise quality. The package implements DiscoveryStrategy for @suaveplan/network wrapping the PeerJS signalling client. Ships PeerJSDiscovery, PeerConnectionManager, RoomManager, PeerJSEventEmitter, PeerJSIntervals, and PeerJSMessageHandlers with strict-mode that refuses the public PeerJS cloud, Zod-validated messages, full unit tests for every module, and an ICE-passthrough config.
Current-state audit (genesis)
Fresh build — does not exist on genesis yet.
Available workspace deps on genesis
| Package | Role |
|---|---|
@suaveplan/network (workspace:^) |
DiscoveryStrategy interface |
@suaveplan/error (workspace:^) |
Typed PeerJS errors |
@suaveplan/types (workspace:^) |
LoggerLike |
@suaveplan/crypto (workspace:^) |
Optional signed metadata |
@suaveplan/schema-registry (workspace:^) |
Message schema registration |
zod (catalog:forms) |
PeerJSMessage Zod schemas |
@opentelemetry/api (catalog:observability) |
Connection/room metrics |
tslib (catalog:build) |
Runtime helpers |
External: peerjs (Bun catalog). React in devDeps for story.
Preserved public API surface
class PeerJSDiscovery implements DiscoveryStrategy {
constructor(config: PeerJSDiscoveryConfig)
start(): Promise<void>
stop(): Promise<void>
getPeers(): PeerInfo[]
on(event: string, handler: Function): void
static selfHosted(options: { host: string; port: number; path: string; secure: boolean }): PeerJSDiscovery
}
interface PeerJSDiscoveryConfig {
host: string // Required; no default to 0.peerjs.com
port: number
path: string
secure: boolean // Must be true in production
roomId: string
iceServers?: RTCIceServer[]
strict?: boolean // Default true; rejects default cloud host
}
// + PeerJSMessage, PeerJSMessageType, PeerJSPeerMetadata
New additions for genesis
1. Strict-mode gate
Refuses to start if host is the public PeerJS cloud (0.peerjs.com / peerjs.com) when strict: true.
2. selfHosted static factory
PeerJSDiscovery.selfHosted({ host, port, path, secure }) — a self-hosting preset that enforces strict mode automatically.
3. Zod-validated messages
PeerJSMessageSchema variants for PEER_ANNOUNCE, PEER_LEAVE, PING, PONG; validated in PeerJSMessageHandlers with PEERJS_MESSAGE_REJECTED on failure.
4. Reconnection policy
Exponential backoff + jitter on signalling dropouts; 'connection:lost' + 'connection:restored' typed events.
5. Optional signed metadata
When config.sign: true, metadata signed with @suaveplan/crypto ed25519.
6. ICE server passthrough
PeerJSDiscoveryConfig.iceServers forwarded to PeerJS's WebRTC config.
7. Error codes
PEERJS_SIGNALING_UNREACHABLE, PEERJS_ROOM_FULL, PEERJS_CONNECTION_FAILED, PEERJS_MESSAGE_REJECTED.
8. OTel metrics
Counter discovery.peerjs.connections_opened_total, counter discovery.peerjs.rooms_joined_total, histogram discovery.peerjs.signaling_rtt_ms.
File layout
browser/network/network-discovery-peerjs/
package.json
tsconfig.json
vitest.config.ts
src/
index.ts
error-codes.ts
peerjs-discovery/
peerjs-discovery.ts
peerjs-discovery.md
peerjs-discovery.types.ts
peerjs-discovery.test.ts
index.ts
peer-connection-manager/
peer-connection-manager.ts
peer-connection-manager.md
peer-connection-manager.test.ts
index.ts
room-manager/
room-manager.ts
room-manager.md
room-manager.test.ts
index.ts
peerjs-connection/
peerjs-connection.ts
peerjs-connection.md
peerjs-connection.test.ts
index.ts
peerjs-message-handlers/
peerjs-message-handlers.ts
peerjs-message-handlers.md
peerjs-message-handlers.test.ts
index.ts
peerjs-intervals/
peerjs-intervals.ts
peerjs-intervals.md
peerjs-intervals.test.ts
index.ts
peerjs-event-emitter/
peerjs-event-emitter.ts
peerjs-event-emitter.md
peerjs-event-emitter.test.ts
index.ts
schema/
peerjs-schema/
peerjs-schema.ts
peerjs-schema.md
index.ts
tests/
integration.test.ts
Impact
Downstream: @suaveplan/network-discovery-hybrid.
Prerequisites: @suaveplan/network, @suaveplan/error, @suaveplan/crypto on Verdaccio.