first commit
This commit is contained in:
138
docs/networking/network/network-transport-libp2p/README.md
Normal file
138
docs/networking/network/network-transport-libp2p/README.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# @suaveplan/network-transport-libp2p - Universal libp2p Transport for @suaveplan/network — WebSockets/WebRTC sub-transports with Noise + Yamux, identify + ping + bootstrap + circuit-relay-v2, fully injectable libp2p factory
|
||||
|
||||
## Summary
|
||||
|
||||
Universal libp2p `Transport` for `@suaveplan/network`. Composes WebSockets or WebRTC sub-transports with Noise + Yamux, identify + ping + bootstrap + circuit-relay-v2, all wired through an injectable libp2p factory so the package itself never bundles `libp2p` at module-eval.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [connection](./src/connection/connection.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [connection](./src/connection/connection.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 -->
|
||||
- [frame](./src/messaging/frame.md) — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…
|
||||
- [peer-message](./src/messaging/peer-message.md) — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the `@suaveplan/serialize` Mess…
|
||||
- [send](./src/messaging/send.md) — Outbound stream-based envelope shipping over libp2p. Each `send` opens a new protocol stream, writes a single framed en…
|
||||
- [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 -->
|
||||
- [streams](./src/streams/streams.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [streams](./src/streams/streams.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 --> - [connection](./src/connection/connection.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)_- [frame](./src/messaging/frame.md) — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…
|
||||
- [peer-message](./src/messaging/peer-message.md) — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the `@suaveplan/serialize` Mess…
|
||||
- [send](./src/messaging/send.md) — Outbound stream-based envelope shipping over libp2p. Each `send` opens a new protocol stream, writes a single framed en…
|
||||
- [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)_- [streams](./src/streams/streams.md) — <!-- begin:auto-docs --> _(no submodules)_- [streams](./src/streams/streams.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)_- [connection](./src/connection/connection.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)_- [frame](./src/messaging/frame.md) — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…
|
||||
- [peer-message](./src/messaging/peer-message.md) — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the `@suaveplan/serialize` Mess…
|
||||
- [send](./src/messaging/send.md) — Outbound stream-based envelope shipping over libp2p. Each `send` opens a new protocol stream, writes a single framed en…
|
||||
- [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)_- [streams](./src/streams/streams.md) — <!-- begin:auto-docs --> _(no submodules)_- [streams](./src/streams/streams.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)_- [connection](./src/connection/connection.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)_- [frame](./src/messaging/frame.md) — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…
|
||||
- [peer-message](./src/messaging/peer-message.md) — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the `@suaveplan/serialize` Mess…
|
||||
- [send](./src/messaging/send.md) — Outbound stream-based envelope shipping over libp2p. Each `send` opens a new protocol stream, writes a single framed en…
|
||||
- [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)_- [streams](./src/streams/streams.md) — <!-- begin:auto-docs --> _(no submodules)_- [streams](./src/streams/streams.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)_- [connection](./src/connection/connection.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)_- [frame](./src/messaging/frame.md) — Implements length-prefixed binary framing for envelopes traversing a libp2p stream. Each frame is a 4-byte big-endian l…
|
||||
- [peer-message](./src/messaging/peer-message.md) — Defines the wire-format codec for envelopes flowing between libp2p peers. Encoding uses the `@suaveplan/serialize` Mess…
|
||||
- [send](./src/messaging/send.md) — Outbound stream-based envelope shipping over libp2p. Each `send` opens a new protocol stream, writes a single framed en…
|
||||
- [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)_- [streams](./src/streams/streams.md) — <!-- begin:auto-docs --> _(no submodules)_ - [streams](./src/streams/streams.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-libp2p
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```ts
|
||||
import { Libp2pPlugin, Libp2pTransport } from "@suaveplan/network-transport-libp2p";
|
||||
|
||||
const transport = new Libp2pTransport({
|
||||
libp2pFactory: async (cfg) => {
|
||||
const { createLibp2p } = await import("libp2p");
|
||||
const { websockets } = await import("@libp2p/websockets");
|
||||
const { noise } = await import("@chainsafe/libp2p-noise");
|
||||
const { yamux } = await import("@chainsafe/libp2p-yamux");
|
||||
const { bootstrap } = await import("@libp2p/bootstrap");
|
||||
const { identify } = await import("@libp2p/identify");
|
||||
const { ping } = await import("@libp2p/ping");
|
||||
|
||||
return (await createLibp2p({
|
||||
addresses: { listen: cfg.addresses.listen as string[] },
|
||||
transports: [websockets()],
|
||||
connectionEncryption: [noise()],
|
||||
streamMuxers: [yamux()],
|
||||
peerDiscovery: [bootstrap({ list: cfg.bootstrap as string[] })],
|
||||
services: { identify: identify(), ping: ping() },
|
||||
connectionManager: {
|
||||
maxConnections: cfg.maxConnections,
|
||||
dialTimeout: cfg.dialTimeoutMs,
|
||||
},
|
||||
})) as unknown as import("@suaveplan/network-transport-libp2p").Libp2pNodeLike;
|
||||
},
|
||||
bootstrap: ["/dns4/bootstrap.example/tcp/443/wss/p2p/Qm…"],
|
||||
subTransport: "websockets",
|
||||
});
|
||||
|
||||
await transport.start();
|
||||
```
|
||||
|
||||
## Sub-Transport Selection
|
||||
|
||||
| `subTransport` | Default `addresses.listen` | Notes |
|
||||
|---|---|---|
|
||||
| `"websockets"` (default) | `/ip4/0.0.0.0/tcp/0/ws` | Universal — works in browser and Node. |
|
||||
| `"webrtc"` | `/webrtc` | Browser-tier sub-transport; relies on the libp2p `webrtc` module. |
|
||||
|
||||
TCP and mDNS are deferred to a server-tier sibling package.
|
||||
|
||||
## Plugin Wrapper
|
||||
|
||||
```ts
|
||||
import { Libp2pPlugin } from "@suaveplan/network-transport-libp2p";
|
||||
|
||||
const plugin = new Libp2pPlugin({
|
||||
libp2pFactory,
|
||||
bootstrap: bootstrapList,
|
||||
});
|
||||
node.use(plugin);
|
||||
await node.start();
|
||||
```
|
||||
|
||||
## Security & Hardening
|
||||
|
||||
- `bootstrap` is **mandatory** — empty list rejected at construction with `INVALID_OPTIONS`. There is no public-bootstrap fallback.
|
||||
- `libp2pFactory` is **mandatory** — the package never falls back to a default libp2p constructor; callers control the security posture.
|
||||
- All public boundaries validated by Zod.
|
||||
- 11-code structured error registry.
|
||||
- `AbortSignal` threaded through every async path.
|
||||
- Default frame cap: 1 MiB. Default message timeout: 5 s. Default dial timeout: 10 s.
|
||||
|
||||
## Observability
|
||||
|
||||
| Instrument | Type | Attributes |
|
||||
|---|---|---|
|
||||
| `libp2p.connections_opened_total` | counter | `outcome` |
|
||||
| `libp2p.streams_opened_total` | counter | — |
|
||||
| `libp2p.bytes_total` | counter | `direction` |
|
||||
| `libp2p.dial_ms` | histogram | — |
|
||||
| `libp2p.stream_ttfb_ms` | histogram | — |
|
||||
| `libp2p.active_peers` | gauge | — |
|
||||
|
||||
## Demo
|
||||
|
||||
The 749-line React demo lives in a separate Wave-7 package (`@suaveplan/react-network-libp2p-demo`) so this package stays React-free.
|
||||
|
||||
## Module Layout
|
||||
|
||||
- [`src/types/`](./src/types/types.md) — structural type contracts.
|
||||
- [`src/errors/`](./src/errors/errors.md) — `NET_LIBP2P_CODES` + `NetLibp2pError`.
|
||||
- [`src/otel/`](./src/otel/otel.md) — counters, histograms, gauges, span helper.
|
||||
- [`src/messaging/peer-message.md`](./src/messaging/peer-message.md) — wire format.
|
||||
- [`src/messaging/frame.md`](./src/messaging/frame.md) — length-prefixed framing.
|
||||
- [`src/messaging/send.md`](./src/messaging/send.md) — outbound stream send.
|
||||
- [`src/streams/`](./src/streams/streams.md) — inbound stream handler + drain.
|
||||
- [`src/connection/`](./src/connection/connection.md) — node lifecycle.
|
||||
- [`src/transport/`](./src/transport/transport.md) — `Libp2pTransport`.
|
||||
- [`src/plugin/`](./src/plugin/plugin.md) — `Libp2pPlugin`.
|
||||
Reference in New Issue
Block a user