skills/plugins/document-navigator/docs/networking/drive/drive-mesh

@suaveplan/drive-mesh - P2P mesh orchestrator for the drive chunks plugin. Peer registry, availability gossip, parallel-pull scheduler with racing window, server fallback, and bad-sig denylist. Consumes ChunkSource (drive-plugin-chunks) and DriveTransport (drive-transport-*).

Summary

P2P mesh orchestrator over the drive chunks plugin. Consumes ChunkSource (from @suaveplan/drive-plugin-chunks) and one or more DriveTransport implementations (HTTPS, WebRTC, libp2p, in-memory). Provides parallel chunk pull with a first-byte racing window, peer scoring, bad-signature denylist, availability bitset gossip, and server fallback.

The package is universal: zero browser- or React-specific code. It composes on the server (Node) for vault / CDN sources, in the browser for distributed clients, and inside test harnesses with in-memory transports.

Documentation tree

• error-codes — Defines the frozen error-code registry for @suaveplan/drive-mesh via defineCodes("DRIVE_MESH", …) from `@suaveplan/…
  • error-codes — Defines the frozen error-code registry for @suaveplan/drive-mesh via defineCodes("DRIVE_MESH", …) from `@suaveplan/…
• gossip-engine — (no submodules)
  • gossip-engine — (no submodules)
• typed-event-emitter — (no submodules)
  • typed-event-emitter — (no submodules)
• drive-mesh — (no submodules)
  • drive-mesh — (no submodules)
• peer-registry — (no submodules)
  • peer-registry — (no submodules)
• parallel-puller — (no submodules)
  • parallel-puller — (no submodules)
• server-fallback — (no submodules)
  • server-fallback — (no submodules)

- [gossip-engine](./src/gossip/gossip-engine/gossip-engine.md) — _(no submodules)_- [typed-event-emitter](./src/internal/typed-event-emitter/typed-event-emitter.md) — _(no submodules)_- [typed-event-emitter](./src/internal/typed-event-emitter/typed-event-emitter.md) — _(no submodules)_- [drive-mesh](./src/mesh/drive-mesh/drive-mesh.md) — _(no submodules)_- [drive-mesh](./src/mesh/drive-mesh/drive-mesh.md) — _(no submodules)_- [peer-registry](./src/peer-registry/peer-registry/peer-registry.md) — _(no submodules)_- [peer-registry](./src/peer-registry/peer-registry/peer-registry.md) — _(no submodules)_- [parallel-puller](./src/scheduler/parallel-puller/parallel-puller.md) — _(no submodules)_- [parallel-puller](./src/scheduler/parallel-puller/parallel-puller.md) — _(no submodules)_- [server-fallback](./src/server-fallback/server-fallback/server-fallback.md) — _(no submodules)_- [server-fallback](./src/server-fallback/server-fallback/server-fallback.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the frozen error-code registry for `@suaveplan/drive-mesh` via `defineCodes("DRIVE_MESH", …)` from `@suaveplan/…

• gossip-engine — (no submodules)- typed-event-emitter — (no submodules)- typed-event-emitter — (no submodules)- drive-mesh — (no submodules)- drive-mesh — (no submodules)- peer-registry — (no submodules)- peer-registry — (no submodules)- parallel-puller — (no submodules)- parallel-puller — (no submodules)- server-fallback — (no submodules)- server-fallback — (no submodules)- error-codes — Defines the frozen error-code registry for @suaveplan/drive-mesh via defineCodes("DRIVE_MESH", …) from `@suaveplan/…
• gossip-engine — (no submodules)- typed-event-emitter — (no submodules)- typed-event-emitter — (no submodules)- drive-mesh — (no submodules)- drive-mesh — (no submodules)- peer-registry — (no submodules)- peer-registry — (no submodules)- parallel-puller — (no submodules)- parallel-puller — (no submodules)- server-fallback — (no submodules)- server-fallback — (no submodules)- error-codes — Defines the frozen error-code registry for @suaveplan/drive-mesh via defineCodes("DRIVE_MESH", …) from `@suaveplan/…
• gossip-engine — (no submodules)- typed-event-emitter — (no submodules) - typed-event-emitter — (no submodules)- drive-mesh — (no submodules) - drive-mesh — (no submodules)- peer-registry — (no submodules) - peer-registry — (no submodules)- parallel-puller — (no submodules) - parallel-puller — (no submodules)- server-fallback — (no submodules) - server-fallback — (no submodules)- error-codes — Defines the frozen error-code registry for @suaveplan/drive-mesh via defineCodes("DRIVE_MESH", …) from `@suaveplan/…

Quick start

import { DriveMesh } from "@suaveplan/drive-mesh";

const mesh = new DriveMesh({
    chunks,                       // ChunkSource from chunksPlugin
    transports: [httpsTransport], // any DriveTransport-compatible impl
    serverPubKey,                 // server's ed25519 public key
    serverFallback: { url: "https://cdn.example.com/chunks", transport: "https" },
});
await mesh.start();
const chunkBytes = await mesh.requestChunk(fileIdHex, 0);
await mesh.stop();

Layering

┌──────────────────────────────────────────────────────────────┐
│                  application (vault / drive)                  │
├──────────────────────────────────────────────────────────────┤
│            @suaveplan/drive-mesh   (this package)             │
│   peer registry · gossip · racing puller · server fallback    │
├──────────────────────────────────────────────────────────────┤
│ @suaveplan/drive-mesh-protocol      (envelopes + bitsets)     │
├──────────────────────────────────────────────────────────────┤
│ @suaveplan/drive-plugin-chunks      (sig-verify, manifest)    │
├──────────────────────────────────────────────────────────────┤
│ DriveTransport implementations  (HTTPS / WebRTC / libp2p)     │
└──────────────────────────────────────────────────────────────┘

DriveMesh is the only public class most callers construct. The four subsystems (PeerRegistry, GossipEngine, ParallelPuller, ServerFallback) are exported under subpaths so advanced consumers can compose them directly.

Subpath table

Subpath	What
@suaveplan/drive-mesh	Root barrel — DriveMesh + types.
@suaveplan/drive-mesh/mesh/drive-mesh	DriveMesh class.
@suaveplan/drive-mesh/peer-registry/peer-registry	PeerRegistry.
@suaveplan/drive-mesh/gossip/gossip-engine	GossipEngine.
@suaveplan/drive-mesh/scheduler/parallel-puller	ParallelPuller.
@suaveplan/drive-mesh/server-fallback/server-fallback	ServerFallback.
@suaveplan/drive-mesh/types	All public types.
@suaveplan/drive-mesh/schemas	Zod schemas.
@suaveplan/drive-mesh/errors	DRIVE_MESH_CODES, DriveMeshError.

Trust model

The server's ed25519 public key (serverPubKey) is the only root of trust. Every chunk returned by a peer or the fallback URL must pass verifyChunkSig against this key before drive-mesh resolves its requestChunk promise. A peer that ever returns a chunk with an invalid signature is moved to a denylist — denylistMode: "session" (default) clears the list on mesh.stop(); "persistent" survives stops.

Mesh never holds file decryption keys. Plaintext only ever materialises inside the chunks plugin's decrypt pipeline, which is keyed by the recipient's per-vault key.

Scoring formula

PeerRegistry ranks peers per (fileId, chunkId) using a weighted sum:

score = 2 · (100 / (rttMs + 1))
      + 3 · successRate
      − 5 · errorRate

• rttMs is an EMA (α = 0.3) of observed chunk-fetch wall time.
• successRate and errorRate are over the lifetime of the registry entry. Peers with no observations start at successRate = 0.5 (neutral) and errorRate = 0.
• Bad-sig peers are pinned at -Infinity so they never appear in rank() output once denied.

OpenTelemetry metrics

The mesh emits the following events; consumers wire them to whichever OTel meter they prefer. Drive-mesh stays metric-emitter-agnostic so it does not pin a meter provider on universal consumers.

Event	Suggested metric	Type
chunk:served	drive.mesh.chunks_served_total{outcome="peer"}	counter
chunk:fallback	drive.mesh.chunks_served_total{outcome="fallback"}	counter
chunk:failed	drive.mesh.chunks_served_total{outcome="fail"}	counter
chunk:served	drive.mesh.chunk_fetch_ms{outcome="peer"}	histogram
chunk:fallback	drive.mesh.chunk_fetch_ms{outcome="fallback"}	histogram
peer:joined	drive.mesh.peers_admitted_total	counter
peer:denied	drive.mesh.peers_denied_total{reason}	counter
gossip:sent	drive.mesh.gossip_size_bytes	histogram

Error codes

Code	When
DRIVE_MESH.INVALID_OPTIONS	Construction or fileId shape rejected.
DRIVE_MESH.NOT_STARTED	requestChunk before start().
DRIVE_MESH.CHUNK_UNAVAILABLE	No candidate peers and no fallback configured.
DRIVE_MESH.SIG_VERIFY_FAILED	Winning peer returned a chunk with bad sig.
DRIVE_MESH.ALL_PEERS_FAILED	Every candidate failed; no fallback configured.
DRIVE_MESH.FALLBACK_FAILED	Peers + fallback both failed.
DRIVE_MESH.INVALID_BITSET	advertise got bad totalChunks.
DRIVE_MESH.TRANSPORT_FAILED	Single-attempt transport failure (internal).
DRIVE_MESH.PEER_DENIED	Peer on denylist (manual operations).
DRIVE_MESH.ABORTED	Caller-supplied AbortSignal aborted.

License

MIT © Suaveplan