157 lines
6.8 KiB
Markdown
157 lines
6.8 KiB
Markdown
# Tasks: enterprise-browser-drive-webrtc
|
|
|
|
**Change ID**: enterprise-browser-drive-webrtc
|
|
**Package**: `@suaveplan/drive-webrtc`
|
|
**Target path**: `packages/drive/drive-webrtc`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/drive`, `@suaveplan/crypto`, `@suaveplan/events`, `@suaveplan/packer`, `@suaveplan/error`, `@suaveplan/types`
|
|
|
|
---
|
|
|
|
## 1. Scaffold
|
|
|
|
- [ ] Create `packages/drive/drive-webrtc/` directory tree per layout in `proposal.md`.
|
|
- [ ] Write `package.json` at version `0.1.0`:
|
|
- `"sideEffects": false`
|
|
- Eleven subpath exports (see `proposal.md`)
|
|
- `dependencies`: `@suaveplan/drive workspace:^`, `@suaveplan/crypto workspace:^`, `@suaveplan/events workspace:^`, `@suaveplan/packer workspace:^`, `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`
|
|
- `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `@playwright/test catalog:testing`, `@suaveplan/testing workspace:^`
|
|
- [ ] Write `tsconfig.json` and `vitest.config.ts` (pool: forks).
|
|
|
|
---
|
|
|
|
## 2. Error codes (`src/error-codes.ts`)
|
|
|
|
- [ ] Define `DriveWebRTCErrorCode`: `SIGNALING_UNREACHABLE`, `PEER_HANDSHAKE_FAILED`, `CHUNK_INTEGRITY_FAILED`, `ICE_FAILED`, `PEER_BANDWIDTH_EXCEEDED`, `RATE_LIMIT_EXCEEDED`.
|
|
- [ ] Export `registerDriveWebRTCErrorCodes()` and call eagerly.
|
|
|
|
---
|
|
|
|
## 3. Typed event emitter (`src/events/typed-event-emitter/`)
|
|
|
|
- [ ] Implement `TypedEventEmitter<T>` wrapping `@suaveplan/events` `EventEmitter` with typed event map `T`.
|
|
- [ ] Write `typed-event-emitter.test.ts`, `typed-event-emitter.md`.
|
|
|
|
---
|
|
|
|
## 4. Utility modules
|
|
|
|
- [ ] `lru-cache`: LRU implementation with `get`/`set`/`delete`/`clear`, configurable max size. Tests + md.
|
|
- [ ] `rate-limiter`: token-bucket rate limiter with `consume`/`refill`, configurable window. Tests + md.
|
|
- [ ] `security-validator`: `generateSecurePeerId`, `generateSecureRequestId`, `validatePeerSecurity`, `validateSignalingUrl`. Tests + md.
|
|
- [ ] `sub-chunk`: `splitIntoSubChunks`, `sendSubChunks`, `SubChunkReassembler`. Tests + md.
|
|
|
|
---
|
|
|
|
## 5. Chunk integrity (`src/integrity/chunk-integrity/`)
|
|
|
|
- [ ] Implement `computeChunkHash(data)` using `crypto.subtle.digest('SHA-256', data)`.
|
|
- [ ] Implement `verifyChunkIntegrity(chunk, expectedHash)` — real comparison, no placeholder.
|
|
- [ ] Implement `ChunkIntegrityManager.verifySignature(chunk, key)` using `crypto.subtle.verify` + `@suaveplan/crypto` ed25519.
|
|
- [ ] Remove any "forward-looking placeholder" language; the method is fully implemented.
|
|
- [ ] Write `chunk-integrity.test.ts` with real `crypto.subtle` keys (no stubs), `chunk-integrity.md`, `chunk-integrity.types.ts`.
|
|
|
|
---
|
|
|
|
## 6. Signalling client (`src/signaling/signaling-client/`)
|
|
|
|
- [ ] Implement `SignalingClient` WebSocket wrapper: connect/reconnect with backoff, send/receive typed messages.
|
|
- [ ] Validate incoming messages with Zod `SignalingMessageSchema`.
|
|
- [ ] Wire OTel histogram `drive.webrtc.signaling_reconnect_ms`.
|
|
- [ ] Write `signaling-client.test.ts` using real WebSocket server (no `vi.stubGlobal`), `signaling-client.md`.
|
|
|
|
---
|
|
|
|
## 7. WebRTC client (`src/client/`)
|
|
|
|
- [ ] `offer-answer/offer-answer.ts`: `createOffer`, `handleAnswer`, `handleOffer` via `RTCPeerConnection`.
|
|
- [ ] `ice/ice.ts`: ICE candidate handling + ICE-restart on `iceConnectionState === 'failed'`.
|
|
- [ ] `reconnect/reconnect.ts`: reconnect policy with backoff.
|
|
- [ ] `client/client.ts`: `WebRTCClient` orchestrating the above; `resolveConfig` with TURN/STUN validation.
|
|
- [ ] No `vi.stubGlobal` — real RTCPeerConnection via Playwright E2E for end-to-end path; unit tests using MemorySignalingChannel + programmatic ICE injection.
|
|
- [ ] Write tests per sub-module, `.md` per module.
|
|
|
|
---
|
|
|
|
## 8. Data channel manager (`src/data-channel/data-channel-manager/`)
|
|
|
|
- [ ] Implement `DataChannelManager`: create/close data channels, route messages by label.
|
|
- [ ] Write `data-channel-manager.test.ts`, `data-channel-manager.md`.
|
|
|
|
---
|
|
|
|
## 9. Discovery + chunk source (`src/discovery/`, `src/chunk-source/`)
|
|
|
|
- [ ] `ChunkDiscoveryManager`: request chunks from peers, de-duplicate in-flight requests.
|
|
- [ ] `WebRTCChunkSource`: implements `ChunkSource` interface from `@suaveplan/drive`.
|
|
- [ ] Write tests per module, `.md` per module.
|
|
|
|
---
|
|
|
|
## 10. Peer manager + topology (`src/peer-manager/`)
|
|
|
|
- [ ] `PeerManager`: admit, score, evict peers; integrate with `PeerBandwidthTracker`.
|
|
- [ ] `PeerBandwidthTracker`: track per-peer RTT and bytes.
|
|
- [ ] `TopologyStrategy` interface + `FullMesh`, `SuperPeer`, `HubAndSpoke` implementations.
|
|
- [ ] Wire OTel `drive.webrtc.peers_connected_total`, `drive.webrtc.peer_rtt_ms`.
|
|
- [ ] Write tests per module, `.md` per module.
|
|
|
|
---
|
|
|
|
## 11. Drive plugin (`src/plugin/webrtc-plugin/`)
|
|
|
|
- [ ] Implement `WebRTCDrivePlugin` implementing `DrivePlugin` interface; wire all sub-components.
|
|
- [ ] Wire OTel counters for chunks served/rejected.
|
|
- [ ] Write `webrtc-plugin.test.ts`, `webrtc-plugin.md`.
|
|
|
|
---
|
|
|
|
## 12. Zod schemas
|
|
|
|
- [ ] Define `SignalingMessageSchema` family (offer/answer/ICE-candidate/chunk-request/chunk-response/peer-announce); validate in `signaling-client.ts`.
|
|
- [ ] Define `WebRTCPluginConfigSchema`; validate in `WebRTCClient.resolveConfig`.
|
|
- [ ] Register all in `@suaveplan/schema-registry`.
|
|
|
|
---
|
|
|
|
## 13. Bundle-size snapshots (`tests/bundle-size/`)
|
|
|
|
- [ ] One snapshot test per subpath export (eleven total); assert that importing one entry does not pull in other plugin sub-trees.
|
|
|
|
---
|
|
|
|
## 14. Integration test (`tests/integration.test.ts`)
|
|
|
|
- [ ] `ChunkIntegrityManager.verifySignature` with real ed25519 keys (no stubs).
|
|
- [ ] `PeerManager` admit/evict cycle.
|
|
- [ ] `SubChunkSplitter` + `SubChunkReassembler` round-trip.
|
|
- [ ] `LRUCache` eviction at capacity.
|
|
|
|
---
|
|
|
|
## 15. Playwright E2E (`e2e/drive-webrtc.spec.ts`)
|
|
|
|
- [ ] Two Chromium browser contexts + local WebSocket signalling server.
|
|
- [ ] Assert: peer discovery, ICE, data-channel open, chunk request/response, `ChunkIntegrityManager.verifyChunkIntegrity` passes.
|
|
- [ ] ICE-restart: simulate `iceConnectionState = 'failed'`; verify recovery.
|
|
|
|
---
|
|
|
|
## 16. Docs
|
|
|
|
- [ ] Write `.md` per module (≥200 words, API reference, examples).
|
|
- [ ] Write `README.md` with ICE/TURN ops guidance, subpath table, topology-strategy guide.
|
|
|
|
---
|
|
|
|
## 17. Verify and publish
|
|
|
|
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/drive-webrtc` — green.
|
|
- [ ] `bunx turbo test:coverage --filter=@suaveplan/drive-webrtc` — 100%.
|
|
- [ ] `bun run docs:check --filter=@suaveplan/drive-webrtc` — zero errors.
|
|
- [ ] No `vi.stubGlobal`, `vi.mock`, placeholder wording, `any`, `ts-ignore`, `.skip`.
|
|
- [ ] `ChunkIntegrityManager.verifySignature` implemented and tested with real WebCrypto keys.
|
|
- [ ] All eleven bundle-size snapshots green.
|
|
- [ ] Playwright E2E passes.
|
|
- [ ] `bun scripts/publish.ts --package @suaveplan/drive-webrtc`.
|
|
- [ ] Archive to `openspec/archive/2026-04-24-enterprise-browser-drive-webrtc/`.
|