OpenSpec Change: network-plugin-content-delivery

Change ID: network-plugin-content-delivery
Package: @suaveplan/network-plugin-content-delivery (new)
Status: PROPOSED
Type: new-package
Date: 2026-04-29

Why

Instead of relying on a CDN for file distribution, the mesh itself can act as a content delivery network. Peers cache file chunks in their local @suaveplan/drive storage and serve them to neighbors on request. This reduces bandwidth costs, improves availability when the server is offline, and leverages the physical proximity of mesh peers. Files are packed with @suaveplan/packer into chunks, then distributed via WebRTC data channels for high-throughput transfer. Key chunks are replicated with configurable redundancy across the mesh.

What changes

ADDED: ContentDeliveryPlugin class implementing NetworkPlugin.
ADDED: ChunkIndex — maintains a distributed index of which peers hold which chunks. Uses gossip protocol for propagation. Index entries: { chunkHash, fileId, chunkIndex, holders: peerId[], redundancyTarget }.
ADDED: ChunkRequestRouter — routes chunk requests to the nearest peer that has the chunk, using latency data from network-plugin-webrtc. Falls back to server if no mesh peer has the chunk.
ADDED: ChunkStore — interface over @suaveplan/drive for persisting chunks in browser (OPFS/IndexedDB) or Node.js (filesystem). TTL-based eviction with LRU.
ADDED: RedundancyManager — ensures each chunk is stored on at least N peers in the mesh. Monitors peer departures and triggers re-replication when a holder leaves. Uses network-plugin-assignment for selecting replacement holders.
ADDED: PackerIntegration — consumes @suaveplan/packer output. A packed file produces a manifest: { fileId, totalChunks, chunkHashes[], packerVersion }. The manifest is small enough to broadcast on the NetworkBus.
ADDED: PrefetchEngine — proactively fetches chunks based on predicted need (e.g., next level assets, nearby player textures). Uses network-plugin-session scope to limit prefetch to relevant peers.
ADDED: IntegrityVerifier — verifies chunk integrity via BLAKE3 hash before storing. Rejects corrupted chunks and blacklists the sender temporarily.
ADDED: BandwidthThrottler — uses @suaveplan/rate-limiter to throttle chunk transfers so they don't starve CRITICAL control messages. Integrates with network-plugin-transport-manager BULK priority.
ADDED: NETWORK_CD_CODES — frozen error registry.

Chunk flow

Packer packs file → manifest broadcast on bus
                    ↓
Peer A requests chunk-3 of file-X
                    ↓
ChunkIndex finds holders: [Peer-B, Peer-C]
                    ↓
Request routed to Peer-B (lowest latency)
                    ↓
Peer-B serves chunk via WebRTC datachannel (BULK priority)
                    ↓
Peer-A verifies hash, stores in drive, announces "I have chunk-3"
                    ↓
RedundancyManager checks: is chunk-3 on ≥ N peers?
  No → selects Peer-D, replicates chunk-3
  Yes → done

Redundancy strategy

File type	Redundancy `N`	Rationale
Critical game assets (executable chunks)	5	Must survive even if multiple peers leave
Shared textures/models	3	Important but replaceable from server
User-generated content	2	Nice-to-have, server has master copy
Telemetry/logs	1	Ephemeral, server will collect when online

Boundary with drive-mesh

network-plugin-content-delivery owns mesh-wide chunk redundancy, prefetch, and integrity — it decides where chunks should be stored and whether they need re-replication. It does NOT schedule individual chunk fetches; that is the responsibility of @suaveplan/drive-mesh, which implements the parallel-pull scheduler, racing window, and peer scoring for individual chunk requests.

ContentDelivery (policy)          DriveMesh (scheduling)
     ↓                                    ↓
"Ensure 3 copies of chunk-7"     "Fetch chunk-7 from Peer-B"
     ↓                                    ↓
RedundancyManager               Scheduler + PeerScore

drive-mesh consumes chunk availability from ContentDeliveryPlugin via the NetworkBus (cd:advertise events) and reports fetch completions back (cd:fetched).

Out of scope

Video streaming with adaptive bitrate → future network-plugin-streaming.
Real-time voice chat → future network-plugin-voice.
Server as chunk source → the server is a fallback; this plugin focuses on P2P mesh distribution.
Individual chunk fetch scheduling → handled by drive-mesh.

Deferred to follow-up changes

To keep this initial change feature-complete on the surface it claims (per openspec/AGENTS.md §2c), four integration-heavy subsystems originally listed under What changes are split into separate proposals so the core mesh-CDN primitives ship without coupling them. None of the listed ## ADDED registry elements are removed — they migrate, with their conformance tests, into the follow-up changes:

ChunkStore → follow-up network-plugin-content-delivery-store. @suaveplan/drive integration (OPFS/IndexedDB browser, filesystem Node), TTL eviction, LRU.
PackerIntegration → follow-up network-plugin-content-delivery-packer. @suaveplan/packer manifest ingestion + bus broadcast.
PrefetchEngine → follow-up network-plugin-content-delivery-prefetch. Predictive prefetch driven by network-plugin-session scope.
BandwidthThrottler → follow-up network-plugin-content-delivery-throttle. @suaveplan/rate-limiter integration + network-plugin-transport-manager BULK priority.

The core change shipped here covers: ChunkIndex, ChunkRequestRouter, RedundancyManager, IntegrityVerifier, and the ContentDeliveryPlugin facade. The deferred verification entries (bandwidth-throttler.spec-conformance.test.ts, prefetch-engine.spec-conformance.test.ts, plus the tests/dep-graph.test.ts line that asserts @suaveplan/packer / @suaveplan/drive imports) are deferred along with the implementations.

Source mapping

This derives from ../suaveplan/enterprise/drive.md, ../suaveplan/enterprise/drive-webrtc.md, and ../suaveplan/enterprise/packer.md.

Requirement	Source lines	Notes
P2P chunk exchange	`drive-webrtc/README.md` §DataChannelManager	verbatim contract
Chunk discovery	`drive/README.md` §Chunk Registry	reworded; distributed index instead of central

Requirements with no source line

Requirement	Justification
Distributed chunk index with gossip	No central registry needed; peers discover holders organically
Redundancy manager with re-replication	Ensures content survives peer churn
Latency-aware request routing	Fetch from closest peer, not random
BLAKE3 integrity verification	Detect and reject corrupted chunks
BULK priority transport integration	File transfers must not starve control messages
Prefetch engine	Reduces load-time latency by predictive fetching

Verification approach

src/index/chunk-index.spec-conformance.test.ts — pins gossip propagation, holder lookup.
src/router/chunk-request-router.spec-conformance.test.ts — pins latency-aware routing, fallback.
src/redundancy/redundancy-manager.spec-conformance.test.ts — pins N-copy enforcement, re-replication.
src/integrity/integrity-verifier.spec-conformance.test.ts — pins hash verification, blacklist.
src/throttle/bandwidth-throttler.spec-conformance.test.ts — pins rate limiting, BULK priority.
src/prefetch/prefetch-engine.spec-conformance.test.ts — pins prediction, session-scoped fetch.
tests/dep-graph.test.ts — pins direct import of @suaveplan/packer, @suaveplan/drive.

Migration impact

None — additive only.

7.8 KiB Raw Blame History