SuavePlan/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
skills/plugins/document-navigator/docs/networking/drive/drive-mesh/README.md
admin 427a5bd919 updated skills
2026-06-09 21:06:27 +01:00

15 KiB
Raw Permalink Blame History

@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

- [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/…

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

Reference in New Issue View Git Blame Copy Permalink