97 lines
8.2 KiB
Markdown
97 lines
8.2 KiB
Markdown
# Network Plugins — Catalogue
|
|
|
|
Every concrete piece of network behaviour lives in a plugin. The core is small; the plugins are many. This document is the reference for what each plugin does, which capability spec block it satisfies, and its migration status.
|
|
|
|
The full plugin list comes from the `network-suite` meta-change ([proposal](../../openspec/changes/network-suite/proposal.md)) which orchestrates 21 child changes. Each plugin has its own change folder under `openspec/changes/network-plugin-<name>/`.
|
|
|
|
## Quick map
|
|
|
|
| Plugin | Spec block | Status | One-line role |
|
|
| --- | --- | --- | --- |
|
|
| `network-core` | NET-01..05, NET-12, NET-53..55, NET-113..116 | shipped (genesis) | The substrate. `NetworkNode`, `NetworkPlugin`, `NetworkBus`, `MessageEnvelope`, `Transport`. |
|
|
| `network-plugin-protocol` | NET-15..17, NET-25, NET-45, NET-57..59, NET-125 | shipped (genesis) | 13-byte header. Encoder/decoder. Pipeline. Priority queue. TTL. Loop detector. Fast path. |
|
|
| `network-plugin-registry` | NET-09, NET-13, NET-71 | shipped (genesis) | Peer identity registry. Bitpacker delta sync. |
|
|
| `network-plugin-webrtc` | NET-06..07, NET-117 | shipped (genesis) | WebRTC `Transport`. PingManager (EMA RTT). |
|
|
| `network-plugin-failover` | NET-10 | shipped (genesis) | Heartbeat FSM. Failover trigger. |
|
|
| `network-plugin-governance` | NET-08, NET-118..119 | shipped (genesis) | Elections. HostSelector + HostHistory. |
|
|
| `network-plugin-topology` | NET-11, NET-14, NET-49..52, NET-120..122 | shipped (genesis) | Tier 0/1/2 management. Latency groups. Geographic clustering. Battery-aware. Partition detection. |
|
|
| `network-websockets` | (own subpath) | shipped (genesis) | WebSocket `Transport`. Reconnect, queue, heartbeat, adapters. |
|
|
| `network-testing` | (own subpath) | shipped (genesis) | MemoryTransport, FakeWebSocket, ConditionSimulator, TestPeer, EventCapture. |
|
|
| `network-plugin-transport-manager` | NET-23..26, NET-46, NET-60, NET-123..124 | planned | Multi-transport orchestration. Pre-emptive switching. Battery-aware scheduler. Bandwidth conservator. |
|
|
| `network-plugin-content-delivery` | NET-35..36 | planned | Mesh-wide chunk redundancy + integrity. The drive layer's bus consumer for `cd:request`/`cd:response`. |
|
|
| `network-plugin-audit-mesh` | NET-37..39 | planned | Signed append-only logs. Replication across siblings. Compaction + checkpoints. |
|
|
| `network-plugin-relay` | NET-40, NET-61..70 | planned | Cross-mesh forwarding. Backbone transport. Mesh directory. Loop prevention. |
|
|
| `network-plugin-assignment` | NET-71..77 | planned | Peer→mesh assignment. Capacity tracking. Imbalance rebalancing. |
|
|
| `network-plugin-partition` | NET-78..83 | planned | Partition detection (epoch-based). Quorum resolution. Merge protocol. |
|
|
| `network-plugin-circuit-breaker` | NET-84..90 | planned | Per-path closed/open/half-open breaker. Probe + registry. |
|
|
| `network-plugin-qos` | NET-91..98 | planned | QoS classes. Per-mesh/peer/relay bandwidth quotas. Congestion alerts. |
|
|
| `network-plugin-migration` | NET-99..105 | planned | 8-step peer migration: request, accept, snapshot, transfer, tunnel, cutover, drain, complete. |
|
|
| `network-plugin-auth` | NET-106..112 | planned | MeshMembershipVerifier, CapabilityTokenIssuer, CrossMeshTrustValidator. |
|
|
| `network-plugin-server-bridge` | NET-31..34, NET-56 | planned | Tier 0 ↔ central server WebSocket. Offline mode. Log replay. Hosting-model selector. |
|
|
| `network-plugin-session` | NET-18..22 | planned | Session trees, nested hierarchies, per-session election, capacity, transitions. |
|
|
| `network-plugin-crypto-messages` | NET-27..30, NET-47..48 | planned | Ed25519 message signing. Mesh/session tokens. Plugin security verifier. Tier policies. |
|
|
| `network-plugin-middleware` | NET-41 | planned | Priority middleware pipeline. Drop-on-null. Runtime add/remove/enable/disable. |
|
|
| `network-plugin-state` | NET-42 | planned | Versioned path-based state with five reconciliation strategies. Bloom-filter divergence. |
|
|
| `network-plugin-monitor` | NET-44 | planned | Counter/Gauge/Histogram/Summary metrics. OTel-compatible distributed tracing. |
|
|
| `network-plugin-simulation` | NET-43 | planned | Deterministic virtual mesh. Time acceleration. Pre-defined scenarios (ServerFailure, NetworkPartition, ClientSurge, CascadingFailure). |
|
|
|
|
## Discovery plugins (pending — port from `main`)
|
|
|
|
These provide *peer discovery* — finding peers without an existing topology — and feed their results to `network-plugin-registry`:
|
|
|
|
| Plugin | Status | Mechanism |
|
|
| --- | --- | --- |
|
|
| `network-discovery-crdt` | pending — `main` | Yjs-based CRDT discovery. |
|
|
| `network-discovery-gundb` | pending — `main` | GunDB gossip. |
|
|
| `network-discovery-peerjs` | pending — `main` | PeerJS broker. |
|
|
| `network-discovery-trystero` | pending — `main` | Multi-strategy (BitTorrent, Nostr, MQTT). |
|
|
| `network-discovery-webtorrent` | pending — `main` | WebTorrent tracker. |
|
|
| `network-discovery-hybrid` | pending — `main` | Composes several discovery plugins with deduplication. |
|
|
|
|
## Server-side network plugins (pending — port from `main`)
|
|
|
|
These run on a central server and participate in the mesh as Tier 0:
|
|
|
|
| Plugin | Status | Role |
|
|
| --- | --- | --- |
|
|
| `network-libp2p` | pending — `main` | libp2p transport. Heavy but battle-tested. |
|
|
| `network-libp2p-server` | pending — `main` | libp2p server with auto-relay. |
|
|
| `network-hyperswarm` | pending — `main` | Hyperswarm DHT-based discovery. |
|
|
| `network-trystero-server` | pending — `main` | Trystero serverless P2P "server" relay. |
|
|
| `network-gundb-server` | pending — `main` | Gun.js relay peer. |
|
|
| `network-standby-transport` | pending — `main` | Pre-emptive WebRTC standby transport (warm spare). |
|
|
|
|
## Plugins by concern — what to install for what you need
|
|
|
|
| If you need... | Install |
|
|
| --- | --- |
|
|
| Just talk between two peers, no mesh | `network-core` + `network-plugin-webrtc` (or `network-websockets`) |
|
|
| Local-area mesh with simple roles | + `network-plugin-registry`, `network-plugin-topology`, `network-plugin-failover` |
|
|
| Resilient tiered mesh with elections | + `network-plugin-governance`, `network-plugin-session` |
|
|
| Cross-mesh forwarding (peer-to-peer-across-different-meshes) | + `network-plugin-relay`, `network-plugin-auth` |
|
|
| Partition tolerance | + `network-plugin-partition`, `network-plugin-circuit-breaker` |
|
|
| Backpressure-aware transport switching | + `network-plugin-transport-manager`, `network-plugin-qos` |
|
|
| Verified message authenticity | + `network-plugin-crypto-messages` |
|
|
| Server failover (`SERVER_TO_CLIENT_FAILOVER`) | + `network-plugin-server-bridge` |
|
|
| Audit trail | + `network-plugin-audit-mesh` |
|
|
| Drive chunk distribution over the mesh | + `network-plugin-content-delivery` (drive-mesh consumes its bus events) |
|
|
| Production observability | + `network-plugin-monitor` |
|
|
| Deterministic mesh testing | + `network-plugin-simulation` |
|
|
| Smooth peer migration during rebalances | + `network-plugin-migration`, `network-plugin-assignment` |
|
|
| Pluggable middleware | + `network-plugin-middleware` |
|
|
| State sync with conflict resolution | + `network-plugin-state` |
|
|
|
|
You don't have to install all 21. Most production deployments install ~10. Test deployments often install three (core + memory transport + registry).
|
|
|
|
## A note on the `enterprise-network` vs `network-core` collision
|
|
|
|
`network-suite` REVIEW-GAPS resolved a package-name collision: there were two proposals targeting `@suaveplan/network`. The resolution was to rename `enterprise-network` (which was a different angle entirely — a high-level network *client* abstraction) to `@suaveplan/network-client`, leaving `@suaveplan/network` to mean the genesis plugin core. If you encounter old references to `enterprise-network`, treat them as historical and read `network-core` instead.
|
|
|
|
## Reading further
|
|
|
|
- [`architecture.md`](./architecture.md) — the substrate every plugin extends.
|
|
- [`topology-and-failover.md`](./topology-and-failover.md) — how these plugins compose into the resilience model.
|
|
- [`security-and-tokens.md`](./security-and-tokens.md) — the trust model `network-plugin-crypto-messages` and `network-plugin-auth` enforce.
|
|
- [`offline-and-reintegration.md`](./offline-and-reintegration.md) — `network-plugin-server-bridge` in autonomous mode.
|
|
- [`implementation-status.md`](./implementation-status.md) — what's shipped on genesis.
|