SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fbc70f96e65472bcba42fbc0184dc2286cdfbc00
suaveplan/openspec/archive/2026-05-12-enterprise-browser-drive-webrtc/proposal.md
admin fbc70f96e6 Initial Commit
2026-05-27 23:29:53 +01:00

7.4 KiB
Raw Blame History

OpenSpec Change: enterprise-browser-drive-webrtc

  • Change ID: enterprise-browser-drive-webrtc
  • Package: @suaveplan/drive-webrtc
  • Category: browser
  • Target path: packages/drive/drive-webrtc
  • Status: IN PROGRESS
  • Date: 2026-04-24
  • Reference spec: /mnt/s/web/suaveplan/enterprise/drive-webrtc.md

Summary

Deliver @suaveplan/drive-webrtc on the genesis branch from scratch at enterprise quality. The package provides a WebRTC peer-to-peer mesh plugin for @suaveplan/drive, shipping the full pipeline to distribute content chunks browser-to-browser: WebRTCClient (signalling + RTC lifecycle), SignalingClient (WebSocket transport), PeerManager + PeerBandwidthTracker, DataChannelManager, ChunkDiscoveryManager + WebRTCChunkSource, SubChunkSplitter / SubChunkReassembler, ChunkIntegrityManager (hash verify + real signature verification via @suaveplan/crypto), LRUCache, RateLimiter, and WebRTCDrivePlugin. No vi.stubGlobal — WebSocket/RTC paths exercised via Playwright.

Current-state audit (genesis)

The package does not exist on genesis yet — fresh build.

Available workspace deps on genesis

Package Role
@suaveplan/drive (workspace:^) DrivePlugin interface, ChunkSource contract
@suaveplan/crypto (workspace:^) crypto.subtle-based chunk signature verification
@suaveplan/events (workspace:^) TypedEventEmitter for peer/chunk events
@suaveplan/error (workspace:^) Typed errors for signalling, peer handshake, chunk integrity
@suaveplan/types (workspace:^) LoggerLike
@suaveplan/packer (workspace:^) Chunk format / packing helpers
@suaveplan/schema-registry (workspace:^) Register signalling Zod schemas
zod (catalog:forms) Schemas for SignalingMessage family, WebRTCPluginConfig
@opentelemetry/api (catalog:observability) Peer/chunk metrics
tslib (catalog:build) Runtime helpers

No external runtime deps — uses only native Web APIs.

Dev deps: vitest, @vitest/coverage-istanbul, @playwright/test (catalog:testing), @suaveplan/testing workspace:^.

Preserved public API surface (from main branch)

All eleven subpath exports preserved:

  • WebRTCChunkSource + ChunkSourceOptions
  • WebRTCClient + WebRTCClientOptions + resolveConfig
  • DataChannelManager
  • ChunkDiscoveryManager
  • TypedEventEmitter
  • ChunkIntegrityManager + computeChunkHash + verifyChunkIntegrity + ChunkMetadata
  • LRUCache + LRUCacheOptions
  • PeerBandwidthTracker + config/metrics types
  • PeerManager
  • WebRTCDrivePlugin
  • RateLimiter + RateLimiterOptions
  • Plus: generateSecurePeerId, generateSecureRequestId, validatePeerSecurity, validateSignalingUrl, SignalingClient, SubChunkReassembler, sendSubChunks, splitIntoSubChunks, encodeToBase64, decodeFromBase64, all config/event/message/peer/stats types

New additions for genesis

1. Real chunk signature verification

ChunkIntegrityManager.verifySignature(chunk, key) implemented using crypto.subtle.verify + @suaveplan/crypto — no "forward-looking placeholder" wording anywhere.

2. Structured errors via @suaveplan/error

Error codes: SIGNALING_UNREACHABLE, PEER_HANDSHAKE_FAILED, CHUNK_INTEGRITY_FAILED, ICE_FAILED, PEER_BANDWIDTH_EXCEEDED, RATE_LIMIT_EXCEEDED.

3. ICE-restart policy

WebRTCClient detects iceConnectionState === 'failed' and triggers ICE restart; surfaces via typed 'ice:restart' event.

4. TURN / STUN configuration

First-class iceServers config in WebRTCClientOptions with Zod validation; documented ops guide for turn://user:cred@host:port?transport=udp|tcp.

5. OTel metrics

Counters drive.webrtc.peers_connected_total, drive.webrtc.chunks_served_total, drive.webrtc.chunks_rejected_total{reason}; histograms drive.webrtc.peer_rtt_ms, drive.webrtc.chunk_transfer_ms, drive.webrtc.signaling_reconnect_ms.

6. Signalling Zod schemas

SignalingMessageSchema family (offer/answer/ICE/chunk-request/chunk-response) registered in @suaveplan/schema-registry.

7. Topology strategies

TopologyStrategy interface with FullMesh, SuperPeer, and HubAndSpoke implementations in src/peer-manager/topology/.

8. Per-subpath bundle-size snapshots

Eleven snapshot tests asserting tree-shake isolation across all entry points.

File layout

packages/drive/drive-webrtc/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    client/
      client/
        client.ts
        client.md
        client.test.ts
        index.ts
      offer-answer/
        offer-answer.ts
        offer-answer.md
        offer-answer.test.ts
        index.ts
      ice/
        ice.ts
        ice.md
        ice.test.ts
        index.ts
      reconnect/
        reconnect.ts
        reconnect.md
        reconnect.test.ts
        index.ts
    signaling/
      signaling-client/
        signaling-client.ts
        signaling-client.md
        signaling-client.test.ts
        index.ts
    data-channel/
      data-channel-manager/
        data-channel-manager.ts
        data-channel-manager.md
        data-channel-manager.test.ts
        index.ts
    discovery/
      chunk-discovery-manager/
        chunk-discovery-manager.ts
        chunk-discovery-manager.md
        chunk-discovery-manager.test.ts
        index.ts
    chunk-source/
      chunk-source/
        chunk-source.ts
        chunk-source.md
        chunk-source.test.ts
        index.ts
    integrity/
      chunk-integrity/
        chunk-integrity.ts          (includes real signature verification)
        chunk-integrity.md
        chunk-integrity.types.ts
        chunk-integrity.test.ts
        index.ts
    peer-manager/
      peer-manager/
        peer-manager.ts
        peer-manager.md
        peer-manager.test.ts
        index.ts
      peer-bandwidth-tracker/
        peer-bandwidth-tracker.ts
        peer-bandwidth-tracker.md
        peer-bandwidth-tracker.test.ts
        index.ts
      topology/
        topology-strategy.ts
        full-mesh.ts
        super-peer.ts
        hub-and-spoke.ts
    plugin/
      webrtc-plugin/
        webrtc-plugin.ts
        webrtc-plugin.md
        webrtc-plugin.test.ts
        index.ts
    sub-chunk/
      sub-chunk/
        sub-chunk-splitter.ts
        sub-chunk-reassembler.ts
        sub-chunk.md
        sub-chunk.test.ts
        index.ts
    lru-cache/
      lru-cache/
        lru-cache.ts
        lru-cache.md
        lru-cache.test.ts
        index.ts
    rate-limiter/
      rate-limiter/
        rate-limiter.ts
        rate-limiter.md
        rate-limiter.test.ts
        index.ts
    security/
      security-validator/
        security-validator.ts
        security-validator.md
        security-validator.test.ts
        index.ts
    events/
      typed-event-emitter/
        typed-event-emitter.ts
        typed-event-emitter.md
        typed-event-emitter.test.ts
        index.ts
    types/
      (config, events, messages, peer, stats, drive type modules)
  tests/
    integration.test.ts
    bundle-size/
      (eleven snapshot tests)
  e2e/
    drive-webrtc.spec.ts            (two browsers, signalling, ICE, data-channel, chunk exchange)

Impact

Downstream: @suaveplan/drive, real-time P2P content distribution.

Prerequisites: @suaveplan/drive, @suaveplan/crypto, @suaveplan/events, @suaveplan/packer, @suaveplan/error on Verdaccio.

Reference in New Issue View Git Blame Copy Permalink