90 lines
4.6 KiB
Markdown
90 lines
4.6 KiB
Markdown
# OpenSpec Change: network-transport-hyperswarm
|
|
|
|
- **Change ID**: network-transport-hyperswarm
|
|
- **Package**: `@suaveplan/network-transport-hyperswarm`
|
|
- **Category**: server (Node-only)
|
|
- **Target path**: `packages/network/network-transport-hyperswarm`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-05-11
|
|
- **Parent**: `network-transport-family` (2026-05-11) — Wave 4
|
|
- **Migration source**: `../suaveplan/packages/server/network-hyperswarm` + `../suaveplan/enterprise/network-hyperswarm.md`
|
|
- **Supersedes**: the original name reservation in this folder (2026-05-11)
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Migrate `@suaveplan/network-hyperswarm` into genesis as `@suaveplan/network-transport-hyperswarm` — a server-tier `Transport` implementation over the [Hyperswarm](https://github.com/holepunchto/hyperswarm) DHT. Hyperswarm provides hole-punched peer-to-peer connections discovered via a Kademlia-style DHT keyed by 32-byte topics. First Wave-4 package because it's smaller in surface than libp2p and has a clearer single-purpose mission (DHT-discovered raw streams).
|
|
|
|
---
|
|
|
|
## Current-state audit
|
|
|
|
Upstream coverage: **8.98%** — major test gap. The migration writes the bulk of the test suite from scratch.
|
|
|
|
Upstream source layout (`../suaveplan/packages/server/network-hyperswarm/src/`):
|
|
|
|
- `hyperswarm-discovery.ts` — DHT topic discovery
|
|
- `hyperswarm-connections.ts` — per-peer connection registry
|
|
- `hyperswarm-messaging.ts` — wire-format encode/decode
|
|
- `hyperswarm-context.ts` — node-local state
|
|
- `hyperswarm-dht-security.ts` — DHT-level peer-ID validation
|
|
- `hyperswarm-events.ts` — typed event surface
|
|
- `hyperswarm-metrics.ts` — internal counters
|
|
- `hyperswarm-reputation.ts` — per-peer reputation tracking
|
|
- `declarations.d.ts` — Hyperswarm type augmentations
|
|
- `examples/` — usage samples
|
|
|
|
---
|
|
|
|
## Parity Checklist
|
|
|
|
| Capability | Upstream | Migrated | Notes |
|
|
|---|---|---|---|
|
|
| `Transport` contract impl | partial (Hyperswarm-shaped) | ⬆️ | Adapter wrapping `hyperswarm`'s `swarm.on('connection', ...)` into per-peer `Transport` callbacks. |
|
|
| `NetworkPlugin` wrapper | 🚫 | ⬆️ | Mirrors `WebRTCPlugin` shape. |
|
|
| DHT topic discovery | ✅ | ✅ | |
|
|
| Per-peer connection registry | ✅ | ✅ | |
|
|
| Wire-format encode/decode | ✅ | ✅ | Re-use `@suaveplan/serialize` length-prefix encoding. |
|
|
| Hole-punching | ✅ (Hyperswarm built-in) | ✅ | |
|
|
| DHT-security peer-ID validation | ✅ | ⬆️ | Tightened — Zod boundary on every wire frame; reject unsigned peer announces. |
|
|
| Per-peer reputation | ✅ | ✅ | Replaced with `@suaveplan/feature-flags` Composite strategy (re-use reputation pattern). |
|
|
| Internal metrics | ✅ (ad-hoc) | ⬆️ | Replaced with OTel: counters `hyperswarm.connections_opened_total{outcome}`, `hyperswarm.bytes_total{direction}`, histograms `hyperswarm.dht_lookup_ms`, `hyperswarm.dial_ms`. |
|
|
| Structured errors | 🚫 | ⬆️ | `defineCodes("NET_HYPERSWARM", [...])`: `DHT_LOOKUP_FAILED`, `PEER_REJECTED`, `STREAM_FAILED`, `INVALID_TOPIC`, `INVALID_OPTIONS`. |
|
|
| Zod boundary validation | 🚫 | ⬆️ | Every public option struct + wire frames. |
|
|
| AbortSignal | 🚫 | ⬆️ | Threaded through `join`/`leave`/`connect`. |
|
|
| `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 | 🚫 (8.98%) | ⬆️ | Bring to 100/100/100/100 — major test-writing effort. |
|
|
| Integration tests | 🚫 | ⬆️ | Spin up a 3-peer in-process swarm via the real `hyperswarm` package (no mocks). |
|
|
| `examples/` | ✅ | ✅ | Keep — useful as runnable docs; lint-cleaned. |
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
- `@suaveplan/network` ✅
|
|
- `@suaveplan/network-plugin-transport-manager` ✅
|
|
- `@suaveplan/serialize` ✅
|
|
- `@suaveplan/feature-flags` ✅ (reputation scoring)
|
|
- `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/retry`, `@suaveplan/timing` ✅
|
|
- `@suaveplan/testing` ✅
|
|
- External: `hyperswarm` (large transitive native deps) — add to root catalog under `network-transport`. Node-only — `package.json` declares `"engines": { "node": ">=20" }` and omits the `browser` field.
|
|
|
|
---
|
|
|
|
## Acceptance gate
|
|
|
|
1. `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-hyperswarm` green.
|
|
2. `bunx turbo test:coverage --filter=@suaveplan/network-transport-hyperswarm` 100/100/100/100.
|
|
3. `bun run docs:check` green.
|
|
4. Integration test: 3 nodes join same DHT topic, all-to-all envelope exchange completes successfully.
|
|
5. `STATUS.md` row flipped.
|
|
|
|
---
|
|
|
|
## Out of scope
|
|
|
|
- Browser support (Hyperswarm is Node-only).
|
|
- DHT bootstrap-node hosting (deployment concern).
|