OpenSpec Change: network-transport-peerjs

Change ID: network-transport-peerjs
Package: @suaveplan/network-transport-peerjs
Category: browser
Target path: packages/network/network-transport-peerjs
Status: PROPOSED (architecture decision required at implementation time — see §"Split vs. fold")
Date: 2026-05-11
Parent: network-transport-family (2026-05-11) — Wave 3
Sibling: network-discovery-peerjs (Wave 2)
Supersedes: the original name reservation in this folder (2026-05-11)

Summary

Reserve and define migration scope for @suaveplan/network-transport-peerjs — a browser-tier Transport implementation over PeerJS-signaled WebRTC DataChannels. Wraps the connection-management subsystem of network-discovery-peerjs (Wave 2) into a standalone Transport that registers with @suaveplan/network-plugin-transport-manager ✅.

Split vs. fold — architecture decision required

Upstream (../suaveplan/packages/browser/network-discovery-peerjs/) bundles discovery + transport in a single package: the upstream PeerJSDiscovery class owns both DiscoveryStrategy and PeerConnectionManager/PeerJSConnection (≈390 LOC of transport work). Two implementation paths are valid; the migrating engineer chooses based on the audit:

Option A — Split (recommended for new code)

Two genesis packages:

network-discovery-peerjs — pure DiscoveryStrategy producing peer endpoints
network-transport-peerjs — pure Transport implementation over PeerJS-signaled WebRTC DataChannels

Pro: cleaner separation, transport-manager can pick this transport without inheriting the discovery package. Matches the family-naming convention.

Con: more genesis packages, more boundaries to maintain, divergence from upstream layout.

Option B — Fold

Single genesis package: network-discovery-peerjs ships both DiscoveryStrategy AND a Transport adapter. network-transport-peerjs becomes a thin re-export of the transport surface only.

Pro: parity with upstream layout, fewer moving parts.

Con: anyone importing network-transport-peerjs drags in the discovery dep.

Decision deferred to the implementing proposal. This proposal reserves the name + path under both options.

Current-state audit

See parallel proposal openspec/changes/network-discovery-peerjs/proposal.md for the full upstream surface inventory (it covers both the discovery and transport subsystems).

Transport-specific subsystem (extracted from the bundled upstream package):

Per-peer connection wrapper
Connection lifecycle (open / close / heartbeat / cleanup)
Wire-format encoding/decoding over PeerJS-signaled WebRTC DataChannels

Parity Checklist

Capability	Upstream	Migrated	Notes
Per-peer connection wrapper	✅	✅
`Transport` contract impl	partial (embedded in discovery class)	⬆️	NEW `Transport` adapter or extracted from bundled code per Option A/B.
`NetworkPlugin` wrapper	partial	⬆️	Mirrors `WebRTCPlugin` shape.
Wire-format framing over PeerJS-signaled WebRTC DataChannels	✅	✅	Re-use `@suaveplan/serialize` length-prefix where applicable.
Structured errors	🚫	⬆️	Strategy-specific code registry.
Zod boundary validation	🚫	⬆️	Every public option struct.
OTel instrumentation	🚫	⬆️	Spans + counters + histograms.
AbortSignal	🚫	⬆️	Threaded everywhere.
Insecure default rejection	inherited from `network-discovery-peerjs`	⬆️	Same — no public-relay/tracker/broker fallbacks.
Test-runner imports	direct vitest	⬆️	`@suaveplan/testing/runner` per §7.
100% test coverage	🚫	⬆️	Bring to 100/100/100/100.

Available workspace deps on genesis

@suaveplan/network ✅
@suaveplan/network-plugin-transport-manager ✅
@suaveplan/network-transport-webrtc ✅ (composes RTCPeerConnection where applicable)
network-discovery-peerjs ⬅ Wave 2 (sibling — required if Option B, optional peer-dep if Option A)
@suaveplan/types, @suaveplan/error, @suaveplan/events, @suaveplan/timing, @suaveplan/retry ✅
@suaveplan/testing ✅
External: peerjs.

Blocking note. network-discovery-peerjs (Wave 2) must land first regardless of Option A/B — Option A pairs with it, Option B is implemented inside it.

Acceptance gate

bunx turbo lint typecheck test --filter=@suaveplan/network-transport-peerjs green.
bunx turbo test:coverage --filter=@suaveplan/network-transport-peerjs 100/100/100/100.
bun run docs:check green.
Integration test with network-plugin-transport-manager: register this transport, send envelope through it, verify peer receives.
STATUS.md row flipped from – to ✅.

Out of scope

Hosting / running any required relays, trackers, or brokers (deployment concern).
Cross-transport peer migration (covered by transport-manager + standby).

4.9 KiB Raw Blame History Unescape Escape