91 lines
4.7 KiB
Markdown
91 lines
4.7 KiB
Markdown
# 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 `RTCPeerConnection` directly; no new external dep beyond what `network-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-hyperswarm` will 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 FSM
|
||
- `transport/` — `Transport` adapter (`connect`/`disconnect`/`send`/`onMessage`/`getConnectedPeers`/`close`)
|
||
- `types/` — `ConnectionState`, `ConnectionRequest`, pool options
|
||
- `index.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
|
||
|
||
1. `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-standby` green.
|
||
2. `bunx turbo test:coverage --filter=@suaveplan/network-transport-standby` 100/100/100/100.
|
||
3. `bun run docs:check` green.
|
||
4. Integration test with `network-plugin-transport-manager`: standby warms 4 slots, manager promotes one to active in < 100 ms.
|
||
5. `STATUS.md` row 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).
|