# 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` 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/`.