106 lines
4.9 KiB
Markdown
106 lines
4.9 KiB
Markdown
# OpenSpec Change: network-transport-gundb
|
||
|
||
- **Change ID**: network-transport-gundb
|
||
- **Package**: `@suaveplan/network-transport-gundb`
|
||
- **Category**: browser
|
||
- **Target path**: `packages/network/network-transport-gundb`
|
||
- **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-gundb` (Wave 2)
|
||
- **Supersedes**: the original name reservation in this folder (2026-05-11)
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
Reserve and define migration scope for `@suaveplan/network-transport-gundb` — a browser-tier `Transport` implementation over GunDB gossip-over-WebSocket. Wraps the connection-management subsystem of `network-discovery-gundb` (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-gundb/`) bundles **discovery + transport** in a single package: upstream `GunDBDiscovery` (244 LOC) + `gun-node-manager` (211 LOC) bundle gossip rendezvous with the underlying Gun node lifecycle. Two implementation paths are valid; the migrating engineer chooses based on the audit:
|
||
|
||
### Option A — Split (recommended for new code)
|
||
|
||
Two genesis packages:
|
||
|
||
1. `network-discovery-gundb` — pure `DiscoveryStrategy` producing peer endpoints
|
||
2. `network-transport-gundb` — pure `Transport` implementation over GunDB gossip-over-WebSocket
|
||
|
||
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-gundb` ships both `DiscoveryStrategy` AND a `Transport` adapter. `network-transport-gundb` becomes a thin re-export of the transport surface only.
|
||
|
||
Pro: parity with upstream layout, fewer moving parts.
|
||
|
||
Con: anyone importing `network-transport-gundb` 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-gundb/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 GunDB gossip-over-WebSocket
|
||
|
||
---
|
||
|
||
## 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 GunDB gossip-over-WebSocket | ✅ | ✅ | 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-gundb` | ⬆️ | 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-gundb` ⬅ 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: `gun`.
|
||
|
||
**Blocking note.** `network-discovery-gundb` (Wave 2) must land first regardless of Option A/B — Option A pairs with it, Option B is implemented inside it.
|
||
|
||
---
|
||
|
||
## Acceptance gate
|
||
|
||
1. `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-gundb` green.
|
||
2. `bunx turbo test:coverage --filter=@suaveplan/network-transport-gundb` 100/100/100/100.
|
||
3. `bun run docs:check` green.
|
||
4. Integration test with `network-plugin-transport-manager`: register this transport, send envelope through it, verify peer receives.
|
||
5. `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).
|