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 — 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

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

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.

3.7 KiB Raw Permalink Blame History