94 lines
4.8 KiB
Markdown
94 lines
4.8 KiB
Markdown
# 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
|
||
|
||
1. `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-peerjs` green.
|
||
2. `bunx turbo test:coverage --filter=@suaveplan/network-discovery-peerjs` 100/100/100/100.
|
||
3. `bun run docs:check` green (sibling `.md` per `.ts`).
|
||
4. `STATUS.md` row flipped from `–` to `✅`.
|
||
5. `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).
|