120 lines
7.8 KiB
Markdown
120 lines
7.8 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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.
|
|
|
|
```text
|
|
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.
|