110 lines
3.5 KiB
Markdown
110 lines
3.5 KiB
Markdown
# OpenSpec Change: enterprise-server-network-trystero-server
|
|
|
|
- **Change ID**: enterprise-server-network-trystero-server
|
|
- **Package**: `@suaveplan/network-trystero-server`
|
|
- **Category**: server/network
|
|
- **Target path**: `server/network/network-trystero-server`
|
|
- **Status**: SUPERSEDED-BY-GENESIS-WAVE
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/network-trystero-server.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/network-trystero-server` on the genesis branch from scratch at enterprise quality. Trystero enables serverless WebRTC mesh networking using public signalling infrastructure (BitTorrent DHT, Nostr, Firebase, MQTT, Supabase). This server-side package provides a Node.js host that can act as a persistent relay peer within a Trystero room — bridging browser peers, relaying data, and optionally recording room state. It wraps Trystero's `joinRoom` API into a typed `TrysteroServerAdapter` with room lifecycle, peer events, typed data channels, and full OTel observability.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Does not exist on genesis — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | Typed `NETWORK_TRYSTERO.*` error codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
|
|
| `@suaveplan/events` (`workspace:^`) | Internal event routing |
|
|
| `@suaveplan/logger` (`workspace:^`) | Structured logs |
|
|
| `zod` (`catalog:forms`) | Options validation |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Gauges + counters |
|
|
| `trystero` (`catalog:network`) | WebRTC signalling library |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
class TrysteroServerAdapter {
|
|
constructor(options: TrysteroServerOptions)
|
|
join(roomId: string): Promise<void>
|
|
leave(roomId: string): Promise<void>
|
|
send(roomId: string, channelName: string, data: unknown, peerId?: string): void
|
|
onData(roomId: string, channelName: string, handler: (data: unknown, peerId: string) => void): () => void
|
|
onPeerJoin(roomId: string, handler: (peerId: string) => void): () => void
|
|
onPeerLeave(roomId: string, handler: (peerId: string) => void): () => void
|
|
peers(roomId: string): string[]
|
|
leaveAll(): Promise<void>
|
|
}
|
|
|
|
function createTrysteroServerAdapter(options: TrysteroServerOptions): TrysteroServerAdapter
|
|
|
|
interface TrysteroServerOptions {
|
|
strategy: 'torrent' | 'nostr' | 'mqtt' | 'supabase'
|
|
appId: string
|
|
password?: string
|
|
relayUrls?: string[] // for nostr / mqtt strategies
|
|
logger?: LoggerLike
|
|
}
|
|
|
|
const TrysteroServerOptionsSchema: z.ZodSchema<TrysteroServerOptions>
|
|
|
|
type TrysteroErrorCode =
|
|
| 'NETWORK_TRYSTERO_JOIN_FAILED'
|
|
| 'NETWORK_TRYSTERO_SEND_FAILED'
|
|
| 'NETWORK_TRYSTERO_LEAVE_FAILED'
|
|
| 'NETWORK_TRYSTERO_STRATEGY_UNSUPPORTED'
|
|
|
|
function registerTrysteroErrorCodes(): void
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
server/network/network-trystero-server/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
constants/index.ts
|
|
types/
|
|
trystero-server.types.ts
|
|
trystero-server.types.md
|
|
adapter/
|
|
trystero-server-adapter/
|
|
trystero-server-adapter.ts
|
|
trystero-server-adapter.md
|
|
trystero-server-adapter.types.ts
|
|
trystero-server-adapter.test.ts
|
|
index.ts
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Downstream: browser-to-server WebRTC bridge, real-time multiplayer relay. Requires Node.js and network access for integration tests.
|
|
|
|
**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`.
|