194 lines
8.7 KiB
Markdown
194 lines
8.7 KiB
Markdown
# @suaveplan/drive-mesh — P2P Mesh Orchestration Capability
|
||
|
||
P2P mesh layer over `@suaveplan/drive-plugin-chunks`: peer registry, bitset
|
||
gossip, parallel chunk pull (multi-peer racing window), peer scoring, server
|
||
fallback (built-in `ServerFallback` HTTPS path — see "HTTPS chunk fetch via
|
||
ServerFallback" below), and bad-signature denylist. Consumes a pluggable list
|
||
of peer-to-peer `DriveTransport` implementations (currently WebRTC, via
|
||
`@suaveplan/drive-transport-webrtc`) without importing `@suaveplan/drive`
|
||
core directly.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Mesh orchestrator surface
|
||
|
||
The package SHALL expose a `DriveMesh` class with:
|
||
|
||
- `start(signal?)` — begin gossip + listen for chunk requests.
|
||
- `stop(reason?)` — drain in-flight, close transports. Idempotent.
|
||
- `requestChunk(fileId, chunkId, signal?): Promise<Uint8Array>` — fetch a
|
||
chunk from the mesh, falling back to the server if configured.
|
||
- `advertise(fileId, bitset)` / `unadvertise(fileId)` — push our local
|
||
availability through the gossip engine.
|
||
- `peers(): Iterable<PeerInfo>` — snapshot of the peer registry.
|
||
- `registry` — direct handle on the `PeerRegistry` for application glue.
|
||
- `tickGossip()` — manual tick (testable / configurable cadence).
|
||
- TypedEventEmitter for `chunk:*` / `peer:*` / `gossip:*` events.
|
||
|
||
### Requirement: Server is root of trust
|
||
|
||
`DriveMesh` SHALL treat the configured `serverPubKey` as the only authority
|
||
for chunk validity:
|
||
|
||
- Every chunk delivered by a peer MUST be passed through
|
||
`drive-plugin-chunks` signature verification before being returned to the
|
||
caller.
|
||
- A peer that delivers a chunk with an invalid signature MUST be added to
|
||
the registry's denylist (per-session by default, persistent if configured).
|
||
- A bad-sig peer MUST emit `peer:denied{peerId, reason: "bad-signature"}` so
|
||
upstream `NetworkBus` consumers can take action.
|
||
|
||
#### Scenario: Bad-sig peer evicted
|
||
|
||
- **WHEN** a peer delivers bytes whose signature fails
|
||
`verifyChunkSig(serverPubKey, …)`
|
||
- **THEN** `peerRegistry.recordBadSig(peerId)` MUST be called and the peer
|
||
MUST NOT be selected for subsequent chunk pulls.
|
||
|
||
### Requirement: PeerRegistry overlay
|
||
|
||
`PeerRegistry` SHALL track per-peer state including availability bitsets per
|
||
fileId, EMA latency (α=0.3), success / failure / bad-sig counts, and a
|
||
composite score for `rank(fileId, chunkId)`. The registry is an **overlay**
|
||
that consumes peer-identity events from `network-plugin-registry` (per the
|
||
`drive-network-integration` boundary spec); it MUST NOT duplicate peer-
|
||
identity storage.
|
||
|
||
### Requirement: Gossip engine
|
||
|
||
`GossipEngine` SHALL emit periodic outbound advertisements with compressed
|
||
bitsets per `fileId` (using `@suaveplan/drive-mesh-protocol` framed-bitset
|
||
helpers) and SHALL ingest inbound advertisements into the `PeerRegistry`.
|
||
|
||
### Requirement: Parallel puller with racing window
|
||
|
||
`ParallelPuller` SHALL issue chunk requests to the top-K candidates (default
|
||
3) within a configurable racing window (default 250 ms), accept the first
|
||
verified response, and abort the losers via a shared `AbortController`.
|
||
`maxParallelRequests` SHALL cap global concurrency (default 8). Failed or
|
||
timed-out attempts blacklist that peer for the specific chunkId only;
|
||
bad-signature is the only failure that escalates to a registry-wide denylist.
|
||
|
||
### Requirement: Server fallback
|
||
|
||
`ServerFallback` SHALL accept a `{ url, transport }` config and execute
|
||
equal-jitter exponential backoff retries when all peer attempts fail.
|
||
Server-delivered chunks MUST still pass signature verification.
|
||
|
||
#### Scenario: All-peers-fail with no fallback
|
||
|
||
- **WHEN** every peer attempt fails AND no `serverFallback` is configured
|
||
- **THEN** `requestChunk` MUST reject with `DriveMeshError(ALL_PEERS_FAILED)`.
|
||
|
||
### Requirement: Wire transports as plugins
|
||
|
||
`DriveMesh` SHALL accept a list of `DriveTransport` implementations through
|
||
its constructor and use them interchangeably. The structural `DriveTransport`
|
||
interface MUST expose:
|
||
|
||
- `requestChunk(peerId, fileId, chunkId, signal?): AsyncIterable<Uint8Array>`
|
||
- `advertise(peerId, fileId, bitset): Promise<void>`
|
||
- `onAdvertisement(handler): () => void`
|
||
- `peers(): Iterable<PeerInfo>`
|
||
- `dispose(): Promise<void>`
|
||
|
||
`@suaveplan/drive-transport-webrtc` satisfies this interface. The HTTPS
|
||
chunk-fetch path is NOT a `DriveTransport` plugin — see "HTTPS chunk fetch
|
||
via ServerFallback" below.
|
||
|
||
### Requirement: No network-plugin-registry import
|
||
|
||
`DriveMesh` MUST NOT import `@suaveplan/network-plugin-registry` directly.
|
||
Applications glue `peer:joined` / `peer:left` from `NetworkBus` to
|
||
`mesh.registry.addOrUpdate` / `mesh.registry.forget`. This enforces the
|
||
layering decision recorded in `openspec/specs/drive-network-integration/spec.md`.
|
||
|
||
### Requirement: Error registry
|
||
|
||
The package SHALL export `DriveMeshError extends SuaveplanError<…>` with 10
|
||
stable codes covering chunk unavailable, all-peers-fail, signature failure,
|
||
transport failure, fallback failure, invalid bitset, peer-denied paths.
|
||
|
||
### Requirement: AbortSignal threading
|
||
|
||
Every async surface (`start`, `stop`, `requestChunk`, `advertise`) SHALL
|
||
accept an optional `AbortSignal`. Pre-aborted signals reject before any
|
||
side effect. Mid-flight aborts cancel transport requests and racing
|
||
attempts cleanly.
|
||
|
||
### Requirement: Universal-tier-clean tests
|
||
|
||
Tests MUST NOT use `vi.mock` or `vi.stubGlobal`. The package SHALL ship
|
||
real-implementation fixtures (in-memory `Broker` + `FakeDriveTransport`,
|
||
real `ed25519` keypairs via `@suaveplan/crypto-curve`, real
|
||
`buildSignedChunk` from `@suaveplan/drive-plugin-chunks`, real
|
||
`encodeFramedBitset` from `@suaveplan/drive-mesh-protocol`). All test
|
||
imports come from `@suaveplan/testing/runner`.
|
||
|
||
### Requirement: Coverage + gate
|
||
|
||
`bunx turbo lint typecheck test:coverage --filter=@suaveplan/drive-mesh`
|
||
MUST be green and istanbul coverage MUST be 100% on every touched module
|
||
(statements / branches / functions / lines) before any release.
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: HTTPS chunk fetch via ServerFallback
|
||
|
||
The HTTPS / server-fallback chunk-fetch path SHALL be served by the
|
||
built-in `ServerFallback` module that ships inside `@suaveplan/drive-mesh`
|
||
(`./server-fallback/server-fallback`) — NOT by a separate
|
||
`DriveTransport`-shaped plugin package.
|
||
|
||
`ServerFallback` SHALL:
|
||
|
||
- Issue HTTPS `GET` to `${baseUrl}/${fileId}/${chunkId}` via an
|
||
injectable `fetchFn` (defaults to `globalThis.fetch`).
|
||
- Run every fetched chunk through `verifyChunkSig(serverPubKey, …)` from
|
||
`@suaveplan/drive-plugin-chunks` before returning bytes to the
|
||
scheduler — same root-of-trust contract as peer-served chunks.
|
||
- Apply equal-jitter exponential backoff with a caller-configurable
|
||
`maxRetries`, `backoffBaseMs`, and `backoffMaxMs`.
|
||
- Thread an `AbortSignal` through every retry.
|
||
- Surface every failure as a `DriveMeshError(FALLBACK_FAILED)` with the
|
||
underlying HTTP status / fetch error preserved in `cause`.
|
||
|
||
Bearer-token or other authentication SHALL be supplied by the consumer
|
||
through the `fetchFn` closure (e.g. wrapping `globalThis.fetch` with an
|
||
`Authorization` header) — no transport-level auth plumbing is added.
|
||
|
||
`ServerFallback` deliberately does NOT implement the
|
||
`DriveTransport` interface. Advertisement / peer-discovery / receive
|
||
semantics do not apply to a server-driven HTTPS fetch path; modelling
|
||
HTTPS as a degraded `DriveTransport` (with no-op `advertise`,
|
||
`onAdvertisement`, and a single synthetic peer) was rejected because it
|
||
adds no consumer-facing capability beyond what `ServerFallback` already
|
||
provides while doubling the surface the scheduler has to reason about.
|
||
|
||
#### Scenario: Bad-sig server chunk rejected
|
||
|
||
- **WHEN** `ServerFallback.fetchChunk(fileId, chunkId)` returns bytes whose
|
||
signature fails `verifyChunkSig(serverPubKey, …)`
|
||
- **THEN** `requestChunk` MUST reject with
|
||
`DriveMeshError(FALLBACK_FAILED)` and the chunk MUST NOT be cached.
|
||
|
||
#### Scenario: Auth wrapping happens in the consumer's fetchFn
|
||
|
||
- **WHEN** a consumer needs bearer-token authentication against the
|
||
fallback endpoint
|
||
- **THEN** the consumer SHALL pass an authenticated `fetchFn` to
|
||
`ServerFallback` (e.g. `(url, init) => fetch(url, { ...init, headers: { ...init?.headers, Authorization: 'Bearer ...' } })`)
|
||
rather than registering a separate transport.
|
||
|
||
### Requirement: No HTTPS DriveTransport plugin
|
||
|
||
There SHALL NOT be a parallel `@suaveplan/drive-transport-https` (or
|
||
similar) package implementing the `DriveTransport` interface for the
|
||
HTTPS path. The original `drive-transport-https-port` proposal was
|
||
retired on 2026-05-12 because `ServerFallback` already provides every
|
||
documented capability (HTTPS chunk fetch, signature verification,
|
||
exponential backoff with jitter, injectable `fetchFn` for tests,
|
||
`AbortSignal` threading) without inheriting the peer-shaped surface
|
||
(`advertise` / `onAdvertisement` / `peers`) that would have to be
|
||
no-ops on a unidirectional HTTPS link.
|