OpenSpec Change: network-discovery-peerjs

Change ID: network-discovery-peerjs
Package: @suaveplan/network-discovery-peerjs
Category: browser
Target path: packages/network/network-discovery-peerjs
Status: PROPOSED
Date: 2026-05-11
Parent: network-transport-family (2026-05-11) — Wave 2
Migration source: ../suaveplan/packages/browser/network-discovery-peerjs + ../suaveplan/enterprise/network-discovery-peerjs.md

Summary

Migrate @suaveplan/network-discovery-peerjs as the simplest possible browser-tier DiscoveryStrategy — a PeerJS signaling-server client wrapper that produces initial WebRTC peers for @suaveplan/network. First package of Wave 2 because PeerJS has the smallest API surface and the fewest external moving parts, so it doubles as the canonical template for the other 5 discovery migrations.

Why this is first in Wave 2

Smallest surface. Six upstream source files totalling ≈1.2k LOC.
Cleanest dependency. Single external (peerjs), no signaling relay we have to host.
Strategy contract. Implements DiscoveryStrategy — the same interface network-bootstrap chains and network-discovery-hybrid aggregates. Locking it in first proves the contract before the heavier packages port.

Current-state audit

Upstream (../suaveplan/packages/browser/network-discovery-peerjs/src/):

peerjs-discovery.ts (244 L) — DiscoveryStrategy implementation
peer-connection-manager.ts (257 L) — connection registry
room-manager.ts (242 L) — logical room semantics
peerjs-connection.ts (132 L) — RTCDataConnection wrapper
peerjs-message-handlers.ts (129 L) — wire-format routing
peerjs-event-emitter.ts — typed events
peerjs-intervals.ts — ping / cleanup loops
types.ts (175 L)

Upstream coverage: single test file (peerjs-discovery.browser.test.ts), .stories.tsx exists. No declared React peer dep despite the TSX story.

Parity Checklist

Capability	Upstream	Migrated	Notes
`PeerJSDiscovery implements DiscoveryStrategy`	✅	✅
`PeerConnectionManager` per-peer registry	✅	✅
`RoomManager` logical rooms over PeerJS IDs	✅	✅
`PeerJSConnection` `RTCDataConnection` wrapper	✅	✅
Typed event emission	✅	✅	Replaced with `@suaveplan/events` `EventBus` per AGENTS.md.
Ping / cleanup intervals	✅	✅	Replaced with `@suaveplan/timing` scheduler + injectable `Clock`.
Structured errors	🚫	⬆️	`defineCodes("NET_DISC_PEERJS", [...])`: `SIGNALING_FAILED`, `PEER_CONNECT_FAILED`, `ROOM_FULL`, `INVALID_OPTIONS`, `DISPOSED`.
Zod boundary validation	🚫	⬆️	Every public option struct.
OTel instrumentation	🚫	⬆️	Span `disc_peerjs.start`, counters `peers_discovered_total{outcome}`, histogram `signaling_duration_ms`.
AbortSignal	🚫	⬆️	Threaded through `start`/`stop`/`connect`.
`export *` barrels	check	⬆️	Convert to explicit named exports (§6a).
Test-runner imports	direct vitest	⬆️	Rewrite to `@suaveplan/testing/runner` (§7).
100% test coverage	🚫 (single test file)	⬆️	Add unit + integration suites, 100/100/100/100.
React Storybook story	✅ (no declared dep)	⬆️	Move stories under `react-` aware path or drop — universal-tier discovery has no UI surface. Spec out unless we add `@suaveplan/react-network-devtools` (out of scope here).
Public PeerJS server default	⚠️ (insecure default)	⬆️	`host` REQUIRED in options; no public server fallback. Constructor throws `INVALID_OPTIONS` if missing.

Available workspace deps on genesis

@suaveplan/network ✅ — DiscoveryStrategy contract
@suaveplan/network-bootstrap ⬅ Wave 1 (chains this strategy)
@suaveplan/service-discovery ⬅ Wave 1 (registers PeerJS-discovered services)
@suaveplan/types, @suaveplan/error, @suaveplan/events, @suaveplan/timing ✅
@suaveplan/testing ✅
External: peerjs — add to root catalog under network-discovery.

Blocking note. Implementation can proceed once network-bootstrap + service-discovery (Wave 1) land. Until then this proposal is approved but not started.

Acceptance gate

bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-peerjs green.
bunx turbo test:coverage --filter=@suaveplan/network-discovery-peerjs 100/100/100/100.
bun run docs:check green (sibling .md per .ts).
STATUS.md row flipped from – to ✅.
network-bootstrap chain integration test demonstrates PeerJS as a working strategy entry.

Out of scope

Server-side PeerJS broker hosting (deployment concern; users supply their own server URL).
Cross-room peer migration (covered by the WebRTC transport's mesh layer).

4.8 KiB Raw Blame History Unescape Escape