# @suaveplan/network-bootstrap - Network bootstrap plugin: pluggable discovery-strategy chain, persistent peer cache, retry-with-jitter and NetworkBus integration for finding initial peers in the @suaveplan/network mesh

## Summary

Pluggable peer-discovery chain, persistent peer cache, and `NetworkPlugin`
wrapper for the `@suaveplan/network` mesh. Provides the canonical way for a
freshly started node to find its first peers.

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

- [discovery-chain](./src/core/discovery-chain/discovery-chain.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [discovery-chain](./src/core/discovery-chain/discovery-chain.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [peer-cache](./src/core/peer-cache/peer-cache.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [peer-cache](./src/core/peer-cache/peer-cache.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 -->
- [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 -->
- [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.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 -->  - [discovery-chain](./src/core/discovery-chain/discovery-chain.md) — <!-- begin:auto-docs --> _(no submodules)_- [peer-cache](./src/core/peer-cache/peer-cache.md) — <!-- begin:auto-docs --> _(no submodules)_- [peer-cache](./src/core/peer-cache/peer-cache.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)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.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)_- [discovery-chain](./src/core/discovery-chain/discovery-chain.md) — <!-- begin:auto-docs --> _(no submodules)_- [peer-cache](./src/core/peer-cache/peer-cache.md) — <!-- begin:auto-docs --> _(no submodules)_- [peer-cache](./src/core/peer-cache/peer-cache.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)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.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)_- [discovery-chain](./src/core/discovery-chain/discovery-chain.md) — <!-- begin:auto-docs --> _(no submodules)_- [peer-cache](./src/core/peer-cache/peer-cache.md) — <!-- begin:auto-docs --> _(no submodules)_- [peer-cache](./src/core/peer-cache/peer-cache.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)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.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)_- [discovery-chain](./src/core/discovery-chain/discovery-chain.md) — <!-- begin:auto-docs --> _(no submodules)_- [peer-cache](./src/core/peer-cache/peer-cache.md) — <!-- begin:auto-docs --> _(no submodules)_  - [peer-cache](./src/core/peer-cache/peer-cache.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)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_  - [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_  - [bootstrap-middleware](./src/plugin/bootstrap-middleware/bootstrap-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_  - [bootstrap-plugin](./src/plugin/bootstrap-plugin/bootstrap-plugin.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-bootstrap @suaveplan/network
```

## Basic Example

```ts
import { NetworkNode } from "@suaveplan/network";
import {
    BootstrapPlugin,
    type DiscoveryStrategy,
} from "@suaveplan/network-bootstrap";

const seedStrategy: DiscoveryStrategy = {
    name: "seed",
    async discover() {
        return [
            {
                peerId: "p1",
                addresses: ["/ip4/127.0.0.1/tcp/9001"],
                lastSeen: Date.now(),
                source: "seed",
            },
        ];
    },
    async isAvailable() {
        return true;
    },
};

const plugin = new BootstrapPlugin({
    strategies: [seedStrategy],
    discoveryTimeoutMs: 2000,
});

const node = new NetworkNode().use(plugin);
await node.start();
```

## Advanced Example

```ts
import { NetworkNode } from "@suaveplan/network";
import { MemoryStorage } from "@suaveplan/storage";
import { BootstrapPlugin } from "@suaveplan/network-bootstrap";

const storage = new MemoryStorage();
const plugin = new BootstrapPlugin({
    strategies: [mdnsStrategy, dhtStrategy, seedStrategy],
    cache: {
        maxPeers: 500,
        ttlMs: 600_000,
        persistKey: "net:peers",
        storage,
    },
    discoveryTimeoutMs: 2500,
    maxConcurrentDiscoveries: 3,
    retry: {
        maxAttempts: 4,
        initialDelayMs: 200,
        maxDelayMs: 5000,
        factor: 2,
    },
    maxCollectedPeers: 20,
});

const node = new NetworkNode().use(plugin);
node.networkBus.on("bootstrap:exhausted", (ev) => {
    console.log(`bootstrap done — ${ev.collected} peers found`);
});
await node.start();
```

## Subpath exports

- `@suaveplan/network-bootstrap` — full public surface.
- `@suaveplan/network-bootstrap/peer-cache` — `PeerCache` only.
- `@suaveplan/network-bootstrap/discovery-chain` — `DiscoveryChain` only.
- `@suaveplan/network-bootstrap/bootstrap-plugin` — `BootstrapPlugin` only.
- `@suaveplan/network-bootstrap/bootstrap-middleware` — middleware only.
- `@suaveplan/network-bootstrap/types` — types only.

## Errors

`NetBootstrapError` carries one of: `CHAIN_EXHAUSTED`, `CACHE_CORRUPTED`,
`STRATEGY_TIMEOUT`, `INVALID_OPTIONS`. See `src/errors/errors.md`.

## Observability

- Span: `bootstrap.chain.execute`.
- Counters: `bootstrap.peers_found_total{strategy}`,
  `bootstrap.failures_total{strategy, code}`.
- Histogram: `bootstrap.chain_duration_ms`.
- Bus events: `bootstrap:started`, `bootstrap:peer-found`,
  `bootstrap:exhausted`.