9.6 KiB
9.6 KiB
@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.
Documentation tree
- discovery-chain — (no submodules)
- discovery-chain — (no submodules)
- peer-cache — (no submodules)
- peer-cache — (no submodules)
- errors — (no submodules)
- errors — (no submodules)
- otel — (no submodules)
- otel — (no submodules)
- bootstrap-middleware — (no submodules)
- bootstrap-middleware — (no submodules)
- bootstrap-plugin — (no submodules)
- bootstrap-plugin — (no submodules)
- types — (no submodules)
- types — (no submodules)
Install
bun add @suaveplan/network-bootstrap @suaveplan/network
Basic Example
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
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—PeerCacheonly.@suaveplan/network-bootstrap/discovery-chain—DiscoveryChainonly.@suaveplan/network-bootstrap/bootstrap-plugin—BootstrapPluginonly.@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.