suaveplan/openspec/archive/2026-05-12-enterprise-browser-drive-webrtc/tasks.md

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