112 lines
3.7 KiB
Markdown
112 lines
3.7 KiB
Markdown
# OpenSpec Change: enterprise-server-network-hyperswarm
|
|
|
|
- **Change ID**: enterprise-server-network-hyperswarm
|
|
- **Package**: `@suaveplan/network-hyperswarm`
|
|
- **Category**: server/network
|
|
- **Target path**: `server/network/network-hyperswarm`
|
|
- **Status**: SUPERSEDED-BY-GENESIS-WAVE
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/network-hyperswarm.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/network-hyperswarm` on the genesis branch from scratch at enterprise quality. The package provides a Node.js server-side transport adapter built on [Hyperswarm](https://github.com/holepunchto/hyperswarm) — a DHT-based peer discovery and encrypted connection layer. It exposes a typed `HyperswarmAdapter` with `join(topic)` / `leave(topic)` / `connect(peerId)` / `disconnect(peerId)` / `send(peerId, data)` / `onData(handler)` and full connection lifecycle events. Connections use the Noise protocol for encryption. Genesis adds `@suaveplan/error`-aligned errors, OTel spans + gauges (peer count, message throughput), retry logic, structured logging, and 100% unit + integration coverage.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Does not exist on genesis — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | Typed `NETWORK_HYPERSWARM.*` error codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `EventBusLike` |
|
|
| `@suaveplan/events` (`workspace:^`) | Internal event bus for peer events |
|
|
| `@suaveplan/retry` (`workspace:^`) | Reconnect backoff |
|
|
| `@suaveplan/logger` (`workspace:^`) | Structured logs |
|
|
| `zod` (`catalog:forms`) | Options validation |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Spans + gauges |
|
|
| `hyperswarm` (`catalog:network`) | DHT peer discovery |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
class HyperswarmAdapter {
|
|
constructor(options: HyperswarmOptions)
|
|
join(topic: Buffer | string): Promise<void>
|
|
leave(topic: Buffer | string): Promise<void>
|
|
send(peerId: string, data: Uint8Array): Promise<void>
|
|
broadcast(topic: Buffer | string, data: Uint8Array): Promise<void>
|
|
onData(handler: (peerId: string, data: Uint8Array) => void): () => void
|
|
onPeerConnect(handler: (peerId: string) => void): () => void
|
|
onPeerDisconnect(handler: (peerId: string) => void): () => void
|
|
peers(topic?: Buffer | string): string[]
|
|
peerCount(): number
|
|
destroy(): Promise<void>
|
|
}
|
|
|
|
function createHyperswarmAdapter(options: HyperswarmOptions): HyperswarmAdapter
|
|
|
|
interface HyperswarmOptions {
|
|
keyPair?: { publicKey: Buffer; secretKey: Buffer }
|
|
maxPeers?: number // default: 64
|
|
firewall?: (remotePublicKey: Buffer) => boolean
|
|
logger?: LoggerLike
|
|
}
|
|
|
|
const HyperswarmOptionsSchema: z.ZodSchema<HyperswarmOptions>
|
|
|
|
type HyperswarmErrorCode =
|
|
| 'NETWORK_HYPERSWARM_JOIN_FAILED'
|
|
| 'NETWORK_HYPERSWARM_SEND_FAILED'
|
|
| 'NETWORK_HYPERSWARM_PEER_NOT_FOUND'
|
|
| 'NETWORK_HYPERSWARM_DESTROY_FAILED'
|
|
|
|
function registerHyperswarmErrorCodes(): void
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
server/network/network-hyperswarm/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
constants/index.ts
|
|
types/
|
|
hyperswarm.types.ts
|
|
hyperswarm.types.md
|
|
adapter/
|
|
hyperswarm-adapter/
|
|
hyperswarm-adapter.ts
|
|
hyperswarm-adapter.md
|
|
hyperswarm-adapter.types.ts
|
|
hyperswarm-adapter.test.ts
|
|
index.ts
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Downstream: decentralised network packages, peer-to-peer features in the platform. Requires Node.js and native modules — not universal.
|
|
|
|
**Prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/retry`, `@suaveplan/logger`.
|