4.7 KiB
4.7 KiB
OpenSpec Change: network-transport-standby
- Change ID: network-transport-standby
- Package:
@suaveplan/network-transport-standby - Category: universal
- Target path:
packages/network/network-transport-standby - Status: PROPOSED
- Date: 2026-05-11
- Parent:
network-transport-family(2026-05-11) — Wave 3 - Migration source:
../suaveplan/packages/universal/network-standby-transport+../suaveplan/enterprise/network-standby-transport.md - Supersedes: the original name reservation in this folder (2026-05-11)
Summary
Migrate @suaveplan/network-standby-transport into genesis as @suaveplan/network-transport-standby (per the family-naming convention from the parent proposal). The package provides pre-emptive WebRTC standby — maintains a pool of warm RTCPeerConnection slots so consumer code experiences ~10 ms peer attach instead of the typical 1-3 s ICE/DTLS handshake. First package of Wave 3 because it cleanly builds on shipped network-transport-webrtc ✅ and has the smallest external surface.
Why this is first in Wave 3
- Pure WebRTC extension. Consumes
RTCPeerConnectiondirectly; no new external dep beyond whatnetwork-transport-webrtc✅ already uses. - Highest user-visible payoff. Sub-100 ms peer attach is a dramatic UX win for real-time apps.
- Reference implementation. Establishes the "extends an existing transport via pre-emption / pooling" pattern that Wave 4's
network-transport-hyperswarmwill mirror.
Current-state audit
Upstream source layout (../suaveplan/packages/universal/network-standby-transport/src/):
core/— connection-pool engine (min/max slots, eviction, warm-up scheduler)health/— per-slot connection-quality scoring + auto-reconnect FSMtransport/—Transportadapter (connect/disconnect/send/onMessage/getConnectedPeers/close)types/—ConnectionState,ConnectionRequest, pool optionsindex.ts— barrel
Upstream coverage: 99.04% statement, no E2E.
Parity Checklist
| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| Pre-emptive connection pool | ✅ | ✅ | |
| Min/max slot config + eviction | ✅ | ✅ | |
| Warm-up scheduler | ✅ | ✅ | Backed by @suaveplan/timing scheduler + injectable Clock. |
| Per-slot health scoring | ✅ | ✅ | EMA-smoothed RTT + jitter + loss composite. Re-uses network-transport-webrtc's PingManager shape. |
| Auto-reconnect with exponential backoff | ✅ | ⬆️ | Replaced ad-hoc loop with @suaveplan/retry policy + jitter. |
Transport contract impl |
✅ | ✅ | Registers with network-plugin-transport-manager ✅. |
NetworkPlugin wrapper |
partial | ⬆️ | NEW — mirrors WebRTCPlugin shape so the manager treats standby uniformly. |
| Event-driven observability | ✅ | ✅ | Replaced custom emitter with @suaveplan/events NetworkBus. Emits transport:standby:warm, :promoted, :evicted. |
| Structured errors | 🚫 | ⬆️ | defineCodes("NET_STANDBY", [...]): POOL_EXHAUSTED, SLOT_UNHEALTHY, PROMOTION_FAILED, INVALID_OPTIONS. |
| Zod boundary validation | partial | ⬆️ | Every public option struct. |
| OTel instrumentation | partial | ⬆️ | Gauge standby.warm_slots, counters standby.promotions_total{outcome}, histogram standby.warmup_duration_ms. |
| AbortSignal | partial | ⬆️ | Threaded through every async path. |
export * barrels |
check | ⬆️ | Convert to explicit named exports per §6a. |
| Test-runner imports | direct vitest | ⬆️ | Rewrite to @suaveplan/testing/runner per §7. |
| 100% test coverage | 🚫 (99.04%) | ⬆️ | Bring to 100/100/100/100. |
| fast-check property tests | 🚫 | ⬆️ | Pool invariants (min ≤ active ≤ max), eviction fairness, promotion atomicity. |
Available workspace deps on genesis
@suaveplan/network✅@suaveplan/network-transport-webrtc✅@suaveplan/network-plugin-transport-manager✅@suaveplan/retry✅,@suaveplan/timing✅,@suaveplan/events✅,@suaveplan/error✅,@suaveplan/types✅@suaveplan/testing✅- No new external deps.
Acceptance gate
bunx turbo lint typecheck test --filter=@suaveplan/network-transport-standbygreen.bunx turbo test:coverage --filter=@suaveplan/network-transport-standby100/100/100/100.bun run docs:checkgreen.- Integration test with
network-plugin-transport-manager: standby warms 4 slots, manager promotes one to active in < 100 ms. STATUS.mdrow flipped from–to✅.
Out of scope
- Pre-emption strategies tied to specific application heuristics — left as user-provided callbacks.
- Server-side standby pools (Wave 4 hyperswarm/libp2p have their own pooling stories).