146 lines
4.5 KiB
Markdown
146 lines
4.5 KiB
Markdown
# OpenSpec Change: enterprise-browser-network-discovery-webtorrent
|
|
|
|
- **Change ID**: enterprise-browser-network-discovery-webtorrent
|
|
- **Package**: `@suaveplan/network-discovery-webtorrent`
|
|
- **Category**: browser
|
|
- **Target path**: `browser/network/network-discovery-webtorrent`
|
|
- **Status**: SUPERSEDED-BY-GENESIS-WAVE
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/network-discovery-webtorrent.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/network-discovery-webtorrent` on the genesis branch at enterprise quality. The package wraps `p2pt` for WebTorrent-tracker-based WebRTC peer discovery, replacing the main-branch `describe.skip` stub with real unit tests and a Playwright E2E. Ships strict-mode (no public tracker defaults), a typed `P2PTPeer` interface, tracker health tracking + failover, OTel metrics, and optional encrypted/signed announcements.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Fresh build — does not exist on genesis yet.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/network` (`workspace:^`) | `DiscoveryStrategy` interface, `PeerInfo` |
|
|
| `@suaveplan/events` (`workspace:^`) | `EventEmitter` base |
|
|
| `@suaveplan/error` (`workspace:^`) | Typed errors |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
|
|
| `@suaveplan/crypto` (`workspace:^`) | Optional signed/encrypted announcements |
|
|
| `@suaveplan/schema-registry` (`workspace:^`) | Register envelope schema |
|
|
| `zod` (`catalog:forms`) | `P2PTPeer` + envelope Zod schemas |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Tracker/peer metrics |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
External: `p2pt` (Bun catalog).
|
|
|
|
---
|
|
|
|
## Preserved public API surface
|
|
|
|
```ts
|
|
class WebTorrentDiscovery extends EventEmitter<DiscoveryEvents> {
|
|
constructor(config: WebTorrentDiscoveryConfig)
|
|
start(): Promise<void>
|
|
stop(): Promise<void>
|
|
}
|
|
|
|
interface WebTorrentDiscoveryConfig {
|
|
trackerUrls: string[] // Required; no public tracker defaults when strict: true
|
|
announceId: string // Must include tenant/app hash; namespaced
|
|
strict?: boolean // Default true
|
|
encrypt?: boolean
|
|
sign?: boolean
|
|
}
|
|
|
|
interface P2PTPeer { id: string; address?: string }
|
|
interface PeerInfo { id: PeerId; multiaddrs: Multiaddr[] }
|
|
interface DiscoveryEvents { peer: (info: PeerInfo) => void; error: (err: Error) => void }
|
|
// + PeerId, Multiaddr, Discovery interface
|
|
```
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
### 1. Real unit tests — no `describe.skip`
|
|
|
|
Vitest suites using a typed `P2PTP2PTAdapter` interface so `p2pt` can be driven without stubs (or with a typed adapter that implements the real interface for unit isolation).
|
|
|
|
### 2. Strict-mode tracker config
|
|
|
|
Refuses to start with the four default public WebTorrent trackers unless `strict: false`.
|
|
|
|
### 3. `announceId` namespacing enforcement
|
|
|
|
`announceId` must include a non-trivial prefix (≥8 chars); optionally hashed with a tenant salt.
|
|
|
|
### 4. Tracker health + failover
|
|
|
|
Per-tracker health bookkeeping; rotate away from trackers emitting `trackerwarning`.
|
|
|
|
### 5. Optional encryption + signed announcements
|
|
|
|
`config.encrypt: true` → AES-GCM wrap of peer messages via `@suaveplan/crypto`.
|
|
`config.sign: true` → ed25519 signatures on announcements.
|
|
|
|
### 6. Error codes
|
|
|
|
`WEBTORRENT_TRACKER_UNREACHABLE`, `WEBTORRENT_ANNOUNCE_FAILED`.
|
|
|
|
### 7. OTel metrics
|
|
|
|
Counter `discovery.webtorrent.peers_seen_total`, histogram `discovery.webtorrent.tracker_rtt_ms`.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
browser/network/network-discovery-webtorrent/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
lib/
|
|
network-discovery-webtorrent/
|
|
network-discovery-webtorrent.ts
|
|
network-discovery-webtorrent.md
|
|
network-discovery-webtorrent.types.ts
|
|
network-discovery-webtorrent.test.ts
|
|
index.ts
|
|
p2pt-adapter/
|
|
p2pt-adapter.ts (P2PTP2PTAdapter interface + real p2pt wrapper)
|
|
p2pt-adapter.md
|
|
p2pt-adapter.test.ts
|
|
index.ts
|
|
tracker-health/
|
|
tracker-health.ts
|
|
tracker-health.md
|
|
tracker-health.test.ts
|
|
index.ts
|
|
schema/
|
|
envelope-schema/
|
|
envelope-schema.ts
|
|
envelope-schema.md
|
|
index.ts
|
|
tests/
|
|
integration.test.ts
|
|
e2e/
|
|
webtorrent-discovery.spec.ts (real WSS tracker)
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: `@suaveplan/network-webrtc` (signalling example), `@suaveplan/network-discovery-hybrid`.
|
|
|
|
**Prerequisites**: `@suaveplan/network`, `@suaveplan/events`, `@suaveplan/error`, `@suaveplan/crypto` on Verdaccio.
|