36 lines
4.4 KiB
Markdown
36 lines
4.4 KiB
Markdown
# Network
|
|
|
|
The **network** layer is the resilient, tiered, plugin-driven mesh that lets every drive in a deployment talk to every other drive — and keeps them talking when the central server goes away.
|
|
|
|
The user's framing: *"a resilient tiered network system where if the server goes down, it's all in place with meshed pockets of users with their nominated hosts / those hosts on a tier nominate their tier host."*
|
|
|
|
That is what this layer is. The canonical capability spec is the largest spec in the monorepo: [`openspec/specs/network/spec.md`](../../openspec/specs/network/spec.md) — 125 numbered requirements (`NET-01..NET-125`) covering plugins, transports, sessions, governance, partitions, relay, content delivery, and four hosting models.
|
|
|
|
## Documents in this folder
|
|
|
|
| File | Purpose |
|
|
| --- | --- |
|
|
| [`architecture.md`](./architecture.md) | `NetworkNode`, `NetworkPlugin`, `NetworkBus`, `MessageEnvelope`, `Transport`, `MessageRouter`. The plugin substrate that everything else lives on. |
|
|
| [`topology-and-failover.md`](./topology-and-failover.md) | The tier model (Tier 0 / 1 / 2), meshed pockets, host election, graceful degradation when the server disconnects, and how server reintegration reconciles. The four hosting models (`PURE_CLIENT`, `SERVER_BASED`, `SERVER_TO_CLIENT_FAILOVER`, `CLIENT_WITH_SERVER_BACKUP`). |
|
|
| [`plugins-catalog.md`](./plugins-catalog.md) | Every network plugin and what it does — protocol, registry, governance, failover, topology, transport-manager, webrtc, content-delivery, audit-mesh, relay, assignment, partition, circuit-breaker, qos, migration, auth, server-bridge, session, simulation, monitor, middleware. |
|
|
| [`security-and-tokens.md`](./security-and-tokens.md) | Ed25519 message signatures, server-signed mesh/session/capability tokens, peer identity challenge-response, plugin security verifier, tier-specific policies, cross-mesh trust validators. |
|
|
| [`offline-and-reintegration.md`](./offline-and-reintegration.md) | What the mesh does without the server — token grace periods, signed log buffering, reconciliation on reconnect, log compaction. |
|
|
| [`implementation-status.md`](./implementation-status.md) | What's shipped, pending, and the network-suite-wide cleanup needed before all 21 plugins compose cleanly. |
|
|
|
|
## One-paragraph summary
|
|
|
|
`NetworkNode` is the single entry-point: it owns a `NetworkBus` for typed pub/sub, a `MessageRouter` for envelope delivery, a transport pool, and a plugin chain. Every feature the network provides is a plugin; the core does plugin lifecycle (`install → start → stop → dispose`) and message routing, nothing else. Plugins talk to each other only via bus topics — no direct imports — so any plugin can be replaced or removed without touching the others. The result is a network that scales from a single in-process node (using `MemoryTransport`) to a worldwide tiered mesh (using `WebRTC`/`WebSocket`/`HTTPS` transports with relay, partition handling, circuit breakers, and a server bridge). Every message is signed with the sender's Ed25519 key. Every host election produces a server-attested capability token. Every cross-mesh hop is loop-detected and TTL-bounded. When the server vanishes, the mesh keeps running on signed tokens with grace-period extensions and buffers signed log entries until it returns.
|
|
|
|
## The bet
|
|
|
|
The bet is that **plugin composition** beats **monolithic protocol**. Instead of one giant network library that does everything, the genesis design has 21 small plugins each owning exactly one concern, talking only through `NetworkBus`. Add `network-plugin-relay` and you can hop across meshes; remove it and you can't. Add `network-plugin-content-delivery` and you have P2P chunks; remove it and you're a control-plane-only mesh. This is what makes the same `NetworkNode` work as a phone-to-phone WebRTC pair, a server-anchored corporate mesh, or a worldwide tiered overlay.
|
|
|
|
## Reading order
|
|
|
|
1. [`architecture.md`](./architecture.md) — the plugin substrate.
|
|
2. [`topology-and-failover.md`](./topology-and-failover.md) — tiers, meshed pockets, server failover. **Start here for resilience questions.**
|
|
3. [`plugins-catalog.md`](./plugins-catalog.md) — what each plugin does.
|
|
4. [`security-and-tokens.md`](./security-and-tokens.md) — the trust model.
|
|
5. [`offline-and-reintegration.md`](./offline-and-reintegration.md) — autonomous-mesh mode.
|
|
6. [`../drive-storage-network.md`](../drive-storage-network.md) — the whole composition.
|