# @suaveplan/network-transport-hyperswarm - Server-tier Hyperswarm DHT transport for @suaveplan/network — hole-punched peer-to-peer streams discovered via Kademlia DHT topics

## Summary

Server-tier Hyperswarm DHT transport for `@suaveplan/network`. Provides hole-punched peer-to-peer streams discovered via Kademlia DHT topics.

This package is **server-only** — it depends on the `hyperswarm` npm package, which is Node-only. Browser consumers should use a different transport (`@suaveplan/network-transport-websockets`, `@suaveplan/network-transport-webrtc`).

<!-- begin:auto-docs -->
## Documentation tree

- [connections](./src/connections/connections.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [connections](./src/connections/connections.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [connections](./src/connections/connections.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_- [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_- [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [connections](./src/connections/connections.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_- [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_- [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [connections](./src/connections/connections.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_- [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_- [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [connections](./src/connections/connections.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_  - [discovery](./src/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_  - [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_  - [messaging](./src/messaging/messaging.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_  - [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_  - [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_  - [reputation](./src/reputation/reputation.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_  - [security](./src/security/security.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_  - [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_  - [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_
## Install

```bash
bun add @suaveplan/network-transport-hyperswarm
```

## Quick start

```ts
import {
    HyperswarmPlugin,
    type HyperswarmFactory,
} from "@suaveplan/network-transport-hyperswarm";

const factory: HyperswarmFactory = () => {
    // Production: wire to real hyperswarm
    // const Hyperswarm = require("hyperswarm");
    // return new Hyperswarm({ maxPeers: 100 });
    throw new Error("wire to real hyperswarm at the application boundary");
};

const plugin = new HyperswarmPlugin({
    topic: "my-room",
    hyperswarmFactory: factory,
});

plugin.install(node);
await plugin.start();
```

## Modules

- `transport` — `HyperswarmTransport implements Transport`
- `plugin` — `HyperswarmPlugin implements NetworkPlugin`
- `messaging` — wire-frame codec (`encodeFrame` / `FrameDecoder` / `prepareTopic`)
- `connections` — per-peer registry (`ConnectionRegistry` / `writeFrame`)
- `discovery` — `joinTopic` / `leaveTopic`
- `security` — `validatePeer` boundary
- `reputation` — `ReputationStore`
- `errors` — `NetHyperswarmError` + `NET_HYPERSWARM_CODES`
- `otel` — counters, histograms, gauge

See the co-located `.md` next to each `.ts` for the full reference.

## License

MIT