173 lines
5.0 KiB
Markdown
173 lines
5.0 KiB
Markdown
# OpenSpec Change: enterprise-browser-network-discovery-trystero
|
|
|
|
- **Change ID**: enterprise-browser-network-discovery-trystero
|
|
- **Package**: `@suaveplan/network-discovery-trystero`
|
|
- **Category**: browser
|
|
- **Target path**: `browser/network/network-discovery-trystero`
|
|
- **Status**: SUPERSEDED-BY-GENESIS-WAVE
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/network-discovery-trystero.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/network-discovery-trystero` on the genesis branch at enterprise quality. The package wraps Trystero to provide serverless WebRTC peer discovery over four transports: BitTorrent, Nostr, MQTT, and IPFS. Ships `TrysteroDiscovery` with strict-mode, Zod-validated messages, per-strategy OTel metrics, curated relay-pool bundles, 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 |
|
|
| `@suaveplan/error` (`workspace:^`) | Typed Trystero errors |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
|
|
| `@suaveplan/crypto` (`workspace:^`) | Optional encrypted rooms + signed announcements |
|
|
| `@suaveplan/schema-registry` (`workspace:^`) | Message schema registration |
|
|
| `zod` (`catalog:forms`) | `TrysteroMessage` Zod schemas |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Per-strategy health metrics |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
External: `trystero` (Bun catalog). React in devDeps for story.
|
|
|
|
---
|
|
|
|
## Preserved public API surface
|
|
|
|
```ts
|
|
class TrysteroDiscovery implements DiscoveryStrategy {
|
|
constructor(config: TrysteroDiscoveryConfig)
|
|
start(): Promise<void>
|
|
stop(): Promise<void>
|
|
getPeers(): PeerInfo[]
|
|
on(event: string, handler: Function): void
|
|
}
|
|
|
|
interface TrysteroDiscoveryConfig {
|
|
strategy: TrysteroStrategy
|
|
roomId: string
|
|
torrent?: TorrentConfig
|
|
nostr?: NostrRelayConfig
|
|
mqtt?: MqttConfig
|
|
ipfs?: IpfsConfig
|
|
encrypt?: { password: string } // AES-GCM via @suaveplan/crypto
|
|
sign?: boolean // ed25519 signed announcements
|
|
strict?: boolean // Default true; rejects public defaults
|
|
}
|
|
type TrysteroStrategy = 'torrent' | 'nostr' | 'mqtt' | 'ipfs'
|
|
interface TorrentConfig { trackerUrls: string[] }
|
|
interface NostrRelayConfig { relayUrls: string[] }
|
|
interface MqttConfig { brokerUrl: string; topic?: string }
|
|
interface IpfsConfig { swarmAddrs?: string[] }
|
|
// + TrysteroConnectionStatus, TrysteroMessage, TrysteroMessageType, TrysteroPeerMetadata
|
|
```
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
### 1. Strict-mode relay gate
|
|
|
|
Requires explicit relay/tracker/broker per strategy; rejects known public defaults without explicit `strict: false`.
|
|
|
|
### 2. Zod-validated messages
|
|
|
|
`TrysteroMessageSchema` variants; validated in `message-handlers.ts`; malformed dropped with metric.
|
|
|
|
### 3. Encrypted rooms
|
|
|
|
`config.encrypt.password` → AES-GCM wrap via `@suaveplan/crypto`; messages unreadable without password.
|
|
|
|
### 4. Signed announcements
|
|
|
|
`config.sign: true` → ed25519 signatures on peer metadata via `@suaveplan/crypto`.
|
|
|
|
### 5. Curated relay-pool bundles (`src/presets/`)
|
|
|
|
`TORRENT_TRACKERS`, `NOSTR_RELAYS` exported with freshness metadata; no public defaults used unless opted in via presets import.
|
|
|
|
### 6. Fallback via `@suaveplan/retry`
|
|
|
|
Replace ad-hoc `fallback.ts` with `@suaveplan/retry` exponential backoff for strategy transitions.
|
|
|
|
### 7. Error codes
|
|
|
|
`TRYSTERO_RELAY_UNREACHABLE`, `TRYSTERO_ROOM_JOIN_FAILED`.
|
|
|
|
### 8. OTel metrics
|
|
|
|
Counter `discovery.trystero.peers_seen_total{strategy}`, counter `discovery.trystero.fallback_total{from,to}`, histogram `discovery.trystero.join_ms{strategy}`.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
browser/network/network-discovery-trystero/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
trystero-discovery/
|
|
trystero-discovery.ts
|
|
trystero-discovery.md
|
|
trystero-discovery.types.ts
|
|
trystero-discovery.test.ts
|
|
index.ts
|
|
message-handlers/
|
|
message-handlers.ts
|
|
message-handlers.md
|
|
message-handlers.test.ts
|
|
index.ts
|
|
room-config/
|
|
room-config.ts
|
|
room-config.md
|
|
room-config.test.ts
|
|
index.ts
|
|
trystero-room-manager/
|
|
trystero-room-manager.ts
|
|
trystero-room-manager.md
|
|
trystero-room-manager.test.ts
|
|
index.ts
|
|
intervals/
|
|
intervals.ts
|
|
intervals.md
|
|
intervals.test.ts
|
|
index.ts
|
|
event-emitter/
|
|
event-emitter.ts
|
|
event-emitter.md
|
|
event-emitter.test.ts
|
|
index.ts
|
|
presets/
|
|
presets.ts (TORRENT_TRACKERS, NOSTR_RELAYS with freshness metadata)
|
|
presets.md
|
|
index.ts
|
|
schema/
|
|
trystero-schema/
|
|
trystero-schema.ts
|
|
trystero-schema.md
|
|
index.ts
|
|
tests/
|
|
core.test.ts
|
|
messaging.test.ts
|
|
messaging-advanced.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: `@suaveplan/network-discovery-hybrid`.
|
|
|
|
**Prerequisites**: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/crypto`, `@suaveplan/retry` on Verdaccio.
|