mirror of
https://github.com/xtr-dev/rondevu-client.git
synced 2025-12-13 12:23:24 +00:00
Compare commits
34 Commits
177ee2ec2d
...
v0.17.0
| Author | SHA1 | Date | |
|---|---|---|---|
| 0aa9921941 | |||
| 5fc20f1be9 | |||
| 54c371f451 | |||
| 5f4743e086 | |||
| 2ce3e98df0 | |||
| 800f6eaa94 | |||
| d6a9876440 | |||
| 9262043e97 | |||
| bd16798a2f | |||
| c662161cd9 | |||
| a9a0127ccf | |||
| 4345709e9c | |||
| 43dfd72c3d | |||
| ec19ce50db | |||
| e5c82b75b1 | |||
| a2c01d530f | |||
| 7223e45b98 | |||
| d55abf2b63 | |||
| 4ce5217135 | |||
| 238cc08bf5 | |||
| f4ae5dee30 | |||
| a499062e52 | |||
| b5f36d8f77 | |||
| 214f611dc2 | |||
| 1112eeefd4 | |||
| 0fe8e82858 | |||
| c9a5e0eae6 | |||
| 239563ac5c | |||
| 3327c5b219 | |||
| b4be5e9060 | |||
| b60799a712 | |||
| 8fbb76a336 | |||
| a3b4dfa15f | |||
| 5c38f8f36c |
486
ADVANCED.md
Normal file
486
ADVANCED.md
Normal file
@@ -0,0 +1,486 @@
|
||||
# Rondevu Client - Advanced Usage
|
||||
|
||||
Comprehensive guide for advanced features, platform support, and detailed API reference.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [API Reference](#api-reference)
|
||||
- [Types](#types)
|
||||
- [Advanced Usage](#advanced-usage)
|
||||
- [Platform Support](#platform-support)
|
||||
- [Username Rules](#username-rules)
|
||||
- [Service FQN Format](#service-fqn-format)
|
||||
- [Examples](#examples)
|
||||
- [Migration Guide](#migration-guide)
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
### Rondevu Class
|
||||
|
||||
Main class for all Rondevu operations.
|
||||
|
||||
```typescript
|
||||
import { Rondevu } from '@xtr-dev/rondevu-client'
|
||||
|
||||
// Create and connect to Rondevu
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: string, // Signaling server URL
|
||||
username?: string, // Optional: your username (auto-generates anonymous if omitted)
|
||||
keypair?: Keypair, // Optional: reuse existing keypair
|
||||
cryptoAdapter?: CryptoAdapter // Optional: platform-specific crypto (defaults to WebCryptoAdapter)
|
||||
batching?: BatcherOptions | false // Optional: RPC batching configuration
|
||||
iceServers?: IceServerPreset | RTCIceServer[] // Optional: preset name or custom STUN/TURN servers
|
||||
debug?: boolean // Optional: enable debug logging (default: false)
|
||||
})
|
||||
```
|
||||
|
||||
#### Platform Support (Browser & Node.js)
|
||||
|
||||
The client supports both browser and Node.js environments using crypto adapters:
|
||||
|
||||
**Browser (default):**
|
||||
```typescript
|
||||
import { Rondevu } from '@xtr-dev/rondevu-client'
|
||||
|
||||
// WebCryptoAdapter is used by default - no configuration needed
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'alice'
|
||||
})
|
||||
```
|
||||
|
||||
**Node.js (19+ or 18 with --experimental-global-webcrypto):**
|
||||
```typescript
|
||||
import { Rondevu, NodeCryptoAdapter } from '@xtr-dev/rondevu-client'
|
||||
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'alice',
|
||||
cryptoAdapter: new NodeCryptoAdapter()
|
||||
})
|
||||
```
|
||||
|
||||
**Note:** Node.js support requires:
|
||||
- Node.js 19+ (crypto.subtle available globally), OR
|
||||
- Node.js 18 with `--experimental-global-webcrypto` flag
|
||||
- WebRTC implementation like `wrtc` or `node-webrtc` for RTCPeerConnection
|
||||
|
||||
**Custom Crypto Adapter:**
|
||||
```typescript
|
||||
import { CryptoAdapter, Keypair } from '@xtr-dev/rondevu-client'
|
||||
|
||||
class CustomCryptoAdapter implements CryptoAdapter {
|
||||
async generateKeypair(): Promise<Keypair> { /* ... */ }
|
||||
async signMessage(message: string, privateKey: string): Promise<string> { /* ... */ }
|
||||
async verifySignature(message: string, signature: string, publicKey: string): Promise<boolean> { /* ... */ }
|
||||
bytesToBase64(bytes: Uint8Array): string { /* ... */ }
|
||||
base64ToBytes(base64: string): Uint8Array { /* ... */ }
|
||||
randomBytes(length: number): Uint8Array { /* ... */ }
|
||||
}
|
||||
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
cryptoAdapter: new CustomCryptoAdapter()
|
||||
})
|
||||
```
|
||||
|
||||
#### Username Management
|
||||
|
||||
Usernames are **automatically claimed** on the first authenticated request (like `publishService()`).
|
||||
|
||||
```typescript
|
||||
// Check if username is claimed (checks server)
|
||||
await rondevu.isUsernameClaimed(): Promise<boolean>
|
||||
|
||||
// Get username
|
||||
rondevu.getUsername(): string
|
||||
|
||||
// Get public key
|
||||
rondevu.getPublicKey(): string
|
||||
|
||||
// Get keypair (for backup/storage)
|
||||
rondevu.getKeypair(): Keypair
|
||||
```
|
||||
|
||||
#### Service Publishing
|
||||
|
||||
```typescript
|
||||
// Publish service with offers
|
||||
await rondevu.publishService({
|
||||
service: string, // e.g., 'chat:1.0.0' (username auto-appended)
|
||||
maxOffers: number, // Maximum number of concurrent offers to maintain
|
||||
offerFactory?: OfferFactory, // Optional: custom offer creation (defaults to simple data channel)
|
||||
ttl?: number // Optional: milliseconds (default: 300000)
|
||||
}): Promise<void>
|
||||
```
|
||||
|
||||
#### Service Discovery
|
||||
|
||||
```typescript
|
||||
// Direct lookup by FQN (with username)
|
||||
await rondevu.getService('chat:1.0.0@alice'): Promise<ServiceOffer>
|
||||
|
||||
// Random discovery (without username)
|
||||
await rondevu.discoverService('chat:1.0.0'): Promise<ServiceOffer>
|
||||
|
||||
// Paginated discovery (returns multiple offers)
|
||||
await rondevu.discoverServices(
|
||||
'chat:1.0.0', // serviceVersion
|
||||
10, // limit
|
||||
0 // offset
|
||||
): Promise<{ services: ServiceOffer[], count: number, limit: number, offset: number }>
|
||||
```
|
||||
|
||||
#### WebRTC Signaling
|
||||
|
||||
```typescript
|
||||
// Post answer SDP
|
||||
await rondevu.postOfferAnswer(
|
||||
serviceFqn: string,
|
||||
offerId: string,
|
||||
sdp: string
|
||||
): Promise<{ success: boolean, offerId: string }>
|
||||
|
||||
// Get answer SDP (offerer polls this - deprecated, use pollOffers instead)
|
||||
await rondevu.getOfferAnswer(
|
||||
serviceFqn: string,
|
||||
offerId: string
|
||||
): Promise<{ sdp: string, offerId: string, answererId: string, answeredAt: number } | null>
|
||||
|
||||
// Combined polling for answers and ICE candidates (RECOMMENDED for offerers)
|
||||
await rondevu.pollOffers(since?: number): Promise<{
|
||||
answers: Array<{
|
||||
offerId: string
|
||||
serviceId?: string
|
||||
answererId: string
|
||||
sdp: string
|
||||
answeredAt: number
|
||||
}>
|
||||
iceCandidates: Record<string, Array<{
|
||||
candidate: RTCIceCandidateInit | null
|
||||
role: 'offerer' | 'answerer'
|
||||
peerId: string
|
||||
createdAt: number
|
||||
}>>
|
||||
}>
|
||||
|
||||
// Add ICE candidates
|
||||
await rondevu.addOfferIceCandidates(
|
||||
serviceFqn: string,
|
||||
offerId: string,
|
||||
candidates: RTCIceCandidateInit[]
|
||||
): Promise<{ count: number, offerId: string }>
|
||||
|
||||
// Get ICE candidates (with polling support)
|
||||
await rondevu.getOfferIceCandidates(
|
||||
serviceFqn: string,
|
||||
offerId: string,
|
||||
since: number = 0
|
||||
): Promise<{ candidates: IceCandidate[], offerId: string }>
|
||||
```
|
||||
|
||||
### RondevuAPI Class
|
||||
|
||||
Low-level HTTP API client (used internally by Rondevu class).
|
||||
|
||||
```typescript
|
||||
import { RondevuAPI } from '@xtr-dev/rondevu-client'
|
||||
|
||||
const api = new RondevuAPI(
|
||||
baseUrl: string,
|
||||
username: string,
|
||||
keypair: Keypair
|
||||
)
|
||||
|
||||
// Check username
|
||||
await api.checkUsername(username: string): Promise<{
|
||||
available: boolean
|
||||
publicKey?: string
|
||||
claimedAt?: number
|
||||
expiresAt?: number
|
||||
}>
|
||||
|
||||
// Note: Username claiming is now implicit - usernames are auto-claimed
|
||||
// on first authenticated request to the server
|
||||
|
||||
// ... (all other HTTP endpoints)
|
||||
```
|
||||
|
||||
#### Cryptographic Helpers
|
||||
|
||||
```typescript
|
||||
// Generate Ed25519 keypair
|
||||
const keypair = await RondevuAPI.generateKeypair(): Promise<Keypair>
|
||||
|
||||
// Sign message
|
||||
const signature = await RondevuAPI.signMessage(
|
||||
message: string,
|
||||
privateKey: string
|
||||
): Promise<string>
|
||||
|
||||
// Verify signature
|
||||
const valid = await RondevuAPI.verifySignature(
|
||||
message: string,
|
||||
signature: string,
|
||||
publicKey: string
|
||||
): Promise<boolean>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Keypair {
|
||||
publicKey: string // Base64-encoded Ed25519 public key
|
||||
privateKey: string // Base64-encoded Ed25519 private key
|
||||
}
|
||||
|
||||
interface Service {
|
||||
serviceId: string
|
||||
offers: ServiceOffer[]
|
||||
username: string
|
||||
serviceFqn: string
|
||||
createdAt: number
|
||||
expiresAt: number
|
||||
}
|
||||
|
||||
interface ServiceOffer {
|
||||
offerId: string
|
||||
sdp: string
|
||||
createdAt: number
|
||||
expiresAt: number
|
||||
}
|
||||
|
||||
interface IceCandidate {
|
||||
candidate: RTCIceCandidateInit | null
|
||||
createdAt: number
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Anonymous Username
|
||||
|
||||
```typescript
|
||||
// Auto-generate anonymous username (format: anon-{timestamp}-{random})
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu'
|
||||
// No username provided - will generate anonymous username
|
||||
})
|
||||
|
||||
console.log(rondevu.getUsername()) // e.g., "anon-lx2w34-a3f501"
|
||||
|
||||
// Anonymous users behave exactly like regular users
|
||||
await rondevu.publishService({
|
||||
service: 'chat:1.0.0',
|
||||
maxOffers: 5
|
||||
})
|
||||
|
||||
await rondevu.startFilling()
|
||||
```
|
||||
|
||||
### Persistent Keypair
|
||||
|
||||
```typescript
|
||||
// Save keypair and username to localStorage
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'alice'
|
||||
})
|
||||
|
||||
// Save for later (username will be auto-claimed on first authenticated request)
|
||||
localStorage.setItem('rondevu-username', rondevu.getUsername())
|
||||
localStorage.setItem('rondevu-keypair', JSON.stringify(rondevu.getKeypair()))
|
||||
|
||||
// Load on next session
|
||||
const savedUsername = localStorage.getItem('rondevu-username')
|
||||
const savedKeypair = JSON.parse(localStorage.getItem('rondevu-keypair'))
|
||||
|
||||
const rondevu2 = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: savedUsername,
|
||||
keypair: savedKeypair
|
||||
})
|
||||
```
|
||||
|
||||
### Service Discovery
|
||||
|
||||
```typescript
|
||||
// Get a random available service
|
||||
const service = await rondevu.discoverService('chat:1.0.0')
|
||||
console.log('Discovered:', service.username)
|
||||
|
||||
// Get multiple services (paginated)
|
||||
const result = await rondevu.discoverServices('chat:1.0.0', 10, 0)
|
||||
console.log(`Found ${result.count} services:`)
|
||||
result.services.forEach(s => console.log(` - ${s.username}`))
|
||||
```
|
||||
|
||||
### Multiple Concurrent Offers
|
||||
|
||||
```typescript
|
||||
// Publish service with multiple offers for connection pooling
|
||||
const offers = []
|
||||
const connections = []
|
||||
|
||||
for (let i = 0; i < 5; i++) {
|
||||
const pc = new RTCPeerConnection(rtcConfig)
|
||||
const dc = pc.createDataChannel('chat')
|
||||
const offer = await pc.createOffer()
|
||||
await pc.setLocalDescription(offer)
|
||||
|
||||
offers.push({ sdp: offer.sdp })
|
||||
connections.push({ pc, dc })
|
||||
}
|
||||
|
||||
const service = await rondevu.publishService({
|
||||
service: 'chat:1.0.0',
|
||||
offers,
|
||||
ttl: 300000
|
||||
})
|
||||
|
||||
// Each offer can be answered independently
|
||||
console.log(`Published ${service.offers.length} offers`)
|
||||
```
|
||||
|
||||
### Debug Logging
|
||||
|
||||
```typescript
|
||||
// Enable debug logging to see internal operations
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'alice',
|
||||
debug: true // All internal logs will be displayed with [Rondevu] prefix
|
||||
})
|
||||
|
||||
// Debug logs include:
|
||||
// - Connection establishment
|
||||
// - Keypair generation
|
||||
// - Service publishing
|
||||
// - Offer creation
|
||||
// - ICE candidate exchange
|
||||
// - Connection state changes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform Support
|
||||
|
||||
### Modern Browsers
|
||||
Works out of the box - no additional setup needed.
|
||||
|
||||
### Node.js 18+
|
||||
Native fetch is available, but WebRTC requires polyfills:
|
||||
|
||||
```bash
|
||||
npm install wrtc
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc'
|
||||
|
||||
// Use wrtc implementations
|
||||
const pc = new RTCPeerConnection()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Username Rules
|
||||
|
||||
- **Format**: Lowercase alphanumeric + dash (`a-z`, `0-9`, `-`)
|
||||
- **Length**: 3-32 characters
|
||||
- **Pattern**: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
|
||||
- **Validity**: 365 days from claim/last use
|
||||
- **Ownership**: Secured by Ed25519 public key signature
|
||||
|
||||
---
|
||||
|
||||
## Service FQN Format
|
||||
|
||||
- **Format**: `service:version@username`
|
||||
- **Service**: Lowercase alphanumeric + dash (e.g., `chat`, `video-call`)
|
||||
- **Version**: Semantic versioning (e.g., `1.0.0`, `2.1.3`)
|
||||
- **Username**: Claimed username
|
||||
- **Example**: `chat:1.0.0@alice`
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Node.js Service Host Example
|
||||
|
||||
You can host WebRTC services in Node.js that browser clients can connect to:
|
||||
|
||||
```typescript
|
||||
import { Rondevu, NodeCryptoAdapter } from '@xtr-dev/rondevu-client'
|
||||
import wrtc from 'wrtc'
|
||||
|
||||
const { RTCPeerConnection } = wrtc
|
||||
|
||||
// Initialize with Node crypto adapter
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'mybot',
|
||||
cryptoAdapter: new NodeCryptoAdapter()
|
||||
})
|
||||
|
||||
// Create peer connection (offerer creates data channel)
|
||||
const pc = new RTCPeerConnection(rtcConfig)
|
||||
const dc = pc.createDataChannel('chat')
|
||||
|
||||
// Publish service (username auto-claimed on first publish)
|
||||
await rondevu.publishService({
|
||||
service: 'chat:1.0.0',
|
||||
maxOffers: 5
|
||||
})
|
||||
|
||||
await rondevu.startFilling()
|
||||
|
||||
// Browser clients can now discover and connect to chat:1.0.0@mybot
|
||||
```
|
||||
|
||||
**See also:**
|
||||
- [React Demo](https://github.com/xtr-dev/rondevu-demo) - Complete browser UI ([live](https://ronde.vu))
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Migration from v0.3.x
|
||||
|
||||
v0.4.0 removes high-level abstractions and uses manual WebRTC setup:
|
||||
|
||||
**Removed:**
|
||||
- `ServiceHost` class (use manual WebRTC + `publishService()`)
|
||||
- `ServiceClient` class (use manual WebRTC + `getService()`)
|
||||
- `RTCDurableConnection` class (use native WebRTC APIs)
|
||||
- `RondevuService` class (merged into `Rondevu`)
|
||||
|
||||
**Added:**
|
||||
- `pollOffers()` - Combined polling for answers and ICE candidates
|
||||
- `publishService()` - Automatic offer pool management
|
||||
- `connectToService()` - Automatic answering side setup
|
||||
|
||||
**Migration Example:**
|
||||
|
||||
```typescript
|
||||
// Before (v0.3.x) - ServiceHost
|
||||
const host = new ServiceHost({
|
||||
service: 'chat@1.0.0',
|
||||
rondevuService: service
|
||||
})
|
||||
await host.start()
|
||||
|
||||
// After (v0.4.0+) - Automatic setup
|
||||
await rondevu.publishService({
|
||||
service: 'chat:1.0.0',
|
||||
maxOffers: 5
|
||||
})
|
||||
|
||||
await rondevu.startFilling()
|
||||
```
|
||||
513
README.md
513
README.md
@@ -2,9 +2,9 @@
|
||||
|
||||
[](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
|
||||
|
||||
🌐 **Simple, high-level WebRTC peer-to-peer connections**
|
||||
🌐 **Simple WebRTC signaling client with username-based discovery**
|
||||
|
||||
TypeScript/JavaScript client for Rondevu, providing easy-to-use WebRTC connections with automatic signaling, username-based discovery, and built-in reconnection support.
|
||||
TypeScript/JavaScript client for Rondevu, providing WebRTC signaling with username claiming, service publishing/discovery, and efficient batch polling.
|
||||
|
||||
**Related repositories:**
|
||||
- [@xtr-dev/rondevu-client](https://github.com/xtr-dev/rondevu-client) - TypeScript client library ([npm](https://www.npmjs.com/package/@xtr-dev/rondevu-client))
|
||||
@@ -15,18 +15,17 @@ TypeScript/JavaScript client for Rondevu, providing easy-to-use WebRTC connectio
|
||||
|
||||
## Features
|
||||
|
||||
- **High-Level Wrappers**: ServiceHost and ServiceClient eliminate WebRTC boilerplate
|
||||
- **Username-Based Discovery**: Connect to peers by username, not complex offer/answer exchange
|
||||
- **Semver-Compatible Matching**: Requesting chat@1.0.0 matches any compatible 1.x.x version
|
||||
- **Privacy-First Design**: Services are hidden by default - no enumeration possible
|
||||
- **Automatic Reconnection**: Built-in retry logic with exponential backoff
|
||||
- **Message Queuing**: Messages sent while disconnected are queued and flushed on reconnect
|
||||
- **Cryptographic Username Claiming**: Secure ownership with Ed25519 signatures
|
||||
- **Service Publishing**: Package-style naming (chat.app@1.0.0) with multiple simultaneous offers
|
||||
- **Username Claiming**: Secure ownership with Ed25519 signatures
|
||||
- **Anonymous Users**: Auto-generated anonymous usernames for quick testing
|
||||
- **Service Publishing**: Publish services with multiple offers for connection pooling
|
||||
- **Service Discovery**: Direct lookup, random discovery, or paginated search
|
||||
- **Efficient Batch Polling**: Single endpoint for answers and ICE candidates (50% fewer requests)
|
||||
- **Semantic Version Matching**: Compatible version resolution (chat:1.0.0 matches any 1.x.x)
|
||||
- **TypeScript**: Full type safety and autocomplete
|
||||
- **Configurable Polling**: Exponential backoff with jitter to reduce server load
|
||||
- **Keypair Management**: Generate or reuse Ed25519 keypairs
|
||||
- **Automatic Signatures**: All authenticated requests signed automatically
|
||||
|
||||
## Install
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @xtr-dev/rondevu-client
|
||||
@@ -34,424 +33,144 @@ npm install @xtr-dev/rondevu-client
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Hosting a Service (Alice)
|
||||
### Publishing a Service (Offerer)
|
||||
|
||||
```typescript
|
||||
import { RondevuService, ServiceHost } from '@xtr-dev/rondevu-client'
|
||||
import { Rondevu } from '@xtr-dev/rondevu-client'
|
||||
|
||||
// Step 1: Create and initialize service
|
||||
const service = new RondevuService({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'alice'
|
||||
// 1. Connect to Rondevu
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'alice', // Or omit for anonymous username
|
||||
iceServers: 'ipv4-turn' // Preset: 'ipv4-turn', 'hostname-turns', 'google-stun', 'relay-only'
|
||||
})
|
||||
|
||||
await service.initialize() // Generates keypair
|
||||
await service.claimUsername() // Claims username with signature
|
||||
// 2. Publish service with automatic offer management
|
||||
await rondevu.publishService({
|
||||
service: 'chat:1.0.0',
|
||||
maxOffers: 5, // Maintain up to 5 concurrent offers
|
||||
offerFactory: async (rtcConfig) => {
|
||||
const pc = new RTCPeerConnection(rtcConfig)
|
||||
const dc = pc.createDataChannel('chat')
|
||||
|
||||
// Step 2: Create ServiceHost
|
||||
const host = new ServiceHost({
|
||||
service: 'chat.app@1.0.0',
|
||||
rondevuService: service,
|
||||
maxPeers: 5, // Accept up to 5 connections
|
||||
ttl: 300000 // 5 minutes
|
||||
})
|
||||
|
||||
// Step 3: Listen for incoming connections
|
||||
host.events.on('connection', (connection) => {
|
||||
console.log('✅ New connection!')
|
||||
|
||||
connection.events.on('message', (msg) => {
|
||||
console.log('📨 Received:', msg)
|
||||
connection.sendMessage('Hello from Alice!')
|
||||
dc.addEventListener('open', () => {
|
||||
console.log('Connection opened!')
|
||||
dc.send('Hello from Alice!')
|
||||
})
|
||||
|
||||
connection.events.on('state-change', (state) => {
|
||||
console.log('Connection state:', state)
|
||||
})
|
||||
})
|
||||
|
||||
host.events.on('error', (error) => {
|
||||
console.error('Host error:', error)
|
||||
})
|
||||
|
||||
// Step 4: Start hosting
|
||||
await host.start()
|
||||
console.log('Service is now live! Others can connect to @alice')
|
||||
|
||||
// Later: stop hosting
|
||||
host.dispose()
|
||||
```
|
||||
|
||||
### Connecting to a Service (Bob)
|
||||
|
||||
```typescript
|
||||
import { RondevuService, ServiceClient } from '@xtr-dev/rondevu-client'
|
||||
|
||||
// Step 1: Create and initialize service
|
||||
const service = new RondevuService({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'bob'
|
||||
})
|
||||
|
||||
await service.initialize()
|
||||
await service.claimUsername()
|
||||
|
||||
// Step 2: Create ServiceClient
|
||||
const client = new ServiceClient({
|
||||
username: 'alice', // Connect to Alice
|
||||
serviceFqn: 'chat.app@1.0.0',
|
||||
rondevuService: service,
|
||||
autoReconnect: true,
|
||||
maxReconnectAttempts: 5
|
||||
})
|
||||
|
||||
// Step 3: Listen for connection events
|
||||
client.events.on('connected', (connection) => {
|
||||
console.log('✅ Connected to Alice!')
|
||||
|
||||
connection.events.on('message', (msg) => {
|
||||
console.log('📨 Received:', msg)
|
||||
dc.addEventListener('message', (e) => {
|
||||
console.log('Received:', e.data)
|
||||
})
|
||||
|
||||
// Send a message
|
||||
connection.sendMessage('Hello from Bob!')
|
||||
const offer = await pc.createOffer()
|
||||
await pc.setLocalDescription(offer)
|
||||
return { pc, dc, offer }
|
||||
}
|
||||
})
|
||||
|
||||
client.events.on('disconnected', () => {
|
||||
console.log('🔌 Disconnected')
|
||||
})
|
||||
|
||||
client.events.on('reconnecting', ({ attempt, maxAttempts }) => {
|
||||
console.log(`🔄 Reconnecting (${attempt}/${maxAttempts})...`)
|
||||
})
|
||||
|
||||
client.events.on('error', (error) => {
|
||||
console.error('❌ Error:', error)
|
||||
})
|
||||
|
||||
// Step 4: Connect
|
||||
await client.connect()
|
||||
|
||||
// Later: disconnect
|
||||
client.dispose()
|
||||
// 3. Start accepting connections
|
||||
await rondevu.startFilling()
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### RondevuService
|
||||
|
||||
Handles authentication and username management:
|
||||
- Generates Ed25519 keypair for signing
|
||||
- Claims usernames with cryptographic proof
|
||||
- Provides API client for signaling server
|
||||
|
||||
### ServiceHost
|
||||
|
||||
High-level wrapper for hosting a WebRTC service:
|
||||
- Automatically creates and publishes offers
|
||||
- Handles incoming connections
|
||||
- Manages ICE candidate exchange
|
||||
- Supports multiple simultaneous peers
|
||||
|
||||
### ServiceClient
|
||||
|
||||
High-level wrapper for connecting to services:
|
||||
- Discovers services by username
|
||||
- Handles offer/answer exchange automatically
|
||||
- Built-in auto-reconnection with exponential backoff
|
||||
- Event-driven API
|
||||
|
||||
### RTCDurableConnection
|
||||
|
||||
Low-level connection wrapper (used internally):
|
||||
- Manages WebRTC PeerConnection lifecycle
|
||||
- Handles ICE candidate polling
|
||||
- Provides message queue for reliability
|
||||
- State management and events
|
||||
|
||||
## API Reference
|
||||
|
||||
### RondevuService
|
||||
### Connecting to a Service (Answerer)
|
||||
|
||||
```typescript
|
||||
const service = new RondevuService({
|
||||
apiUrl: string, // Signaling server URL
|
||||
username: string, // Your username
|
||||
keypair?: Keypair // Optional: reuse existing keypair
|
||||
import { Rondevu } from '@xtr-dev/rondevu-client'
|
||||
|
||||
// 1. Connect to Rondevu
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'bob',
|
||||
iceServers: 'ipv4-turn'
|
||||
})
|
||||
|
||||
// Initialize service (generates keypair if not provided)
|
||||
await service.initialize(): Promise<void>
|
||||
// 2. Connect to service (automatic WebRTC setup)
|
||||
const connection = await rondevu.connectToService({
|
||||
serviceFqn: 'chat:1.0.0@alice',
|
||||
onConnection: ({ dc, peerUsername }) => {
|
||||
console.log('Connected to', peerUsername)
|
||||
|
||||
// Claim username with cryptographic signature
|
||||
await service.claimUsername(): Promise<void>
|
||||
dc.addEventListener('message', (e) => {
|
||||
console.log('Received:', e.data)
|
||||
})
|
||||
|
||||
// Check if username is claimed
|
||||
service.isUsernameClaimed(): boolean
|
||||
|
||||
// Get current username
|
||||
service.getUsername(): string
|
||||
|
||||
// Get keypair
|
||||
service.getKeypair(): Keypair
|
||||
|
||||
// Get API client
|
||||
service.getAPI(): RondevuAPI
|
||||
```
|
||||
|
||||
### ServiceHost
|
||||
|
||||
```typescript
|
||||
const host = new ServiceHost({
|
||||
service: string, // Service FQN (e.g., 'chat.app@1.0.0')
|
||||
rondevuService: RondevuService,
|
||||
maxPeers?: number, // Default: 5
|
||||
ttl?: number, // Default: 300000 (5 minutes)
|
||||
isPublic?: boolean, // Default: true
|
||||
rtcConfiguration?: RTCConfiguration
|
||||
dc.addEventListener('open', () => {
|
||||
dc.send('Hello from Bob!')
|
||||
})
|
||||
}
|
||||
})
|
||||
|
||||
// Start hosting
|
||||
await host.start(): Promise<void>
|
||||
|
||||
// Stop hosting and cleanup
|
||||
host.dispose(): void
|
||||
|
||||
// Get all active connections
|
||||
host.getConnections(): RTCDurableConnection[]
|
||||
|
||||
// Events
|
||||
host.events.on('connection', (conn: RTCDurableConnection) => {})
|
||||
host.events.on('error', (error: Error) => {})
|
||||
// Access connection
|
||||
connection.dc.send('Another message')
|
||||
connection.pc.close() // Close when done
|
||||
```
|
||||
|
||||
### ServiceClient
|
||||
## Core API
|
||||
|
||||
### Rondevu.connect()
|
||||
|
||||
```typescript
|
||||
const client = new ServiceClient({
|
||||
username: string, // Host username to connect to
|
||||
serviceFqn: string, // Service FQN (e.g., 'chat.app@1.0.0')
|
||||
rondevuService: RondevuService,
|
||||
autoReconnect?: boolean, // Default: true
|
||||
maxReconnectAttempts?: number, // Default: 5
|
||||
rtcConfiguration?: RTCConfiguration
|
||||
})
|
||||
|
||||
// Connect to service
|
||||
await client.connect(): Promise<RTCDurableConnection>
|
||||
|
||||
// Disconnect and cleanup
|
||||
client.dispose(): void
|
||||
|
||||
// Get current connection
|
||||
client.getConnection(): RTCDurableConnection | null
|
||||
|
||||
// Events
|
||||
client.events.on('connected', (conn: RTCDurableConnection) => {})
|
||||
client.events.on('disconnected', () => {})
|
||||
client.events.on('reconnecting', (info: { attempt: number, maxAttempts: number }) => {})
|
||||
client.events.on('error', (error: Error) => {})
|
||||
```
|
||||
|
||||
### RTCDurableConnection
|
||||
|
||||
```typescript
|
||||
// Connection state
|
||||
connection.state: 'connected' | 'connecting' | 'disconnected'
|
||||
|
||||
// Send message (returns true if sent, false if queued)
|
||||
await connection.sendMessage(message: string): Promise<boolean>
|
||||
|
||||
// Queue message for sending when connected
|
||||
await connection.queueMessage(message: string, options?: QueueMessageOptions): Promise<void>
|
||||
|
||||
// Disconnect
|
||||
connection.disconnect(): void
|
||||
|
||||
// Events
|
||||
connection.events.on('message', (msg: string) => {})
|
||||
connection.events.on('state-change', (state: ConnectionStates) => {})
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Polling Configuration
|
||||
|
||||
The signaling uses configurable polling with exponential backoff:
|
||||
|
||||
```typescript
|
||||
// Default polling config
|
||||
{
|
||||
initialInterval: 500, // Start at 500ms
|
||||
maxInterval: 5000, // Max 5 seconds
|
||||
backoffMultiplier: 1.5, // Increase by 1.5x each time
|
||||
maxRetries: 50, // Max 50 attempts
|
||||
jitter: true // Add random 0-100ms to prevent thundering herd
|
||||
}
|
||||
```
|
||||
|
||||
This is handled automatically - no configuration needed.
|
||||
|
||||
### WebRTC Configuration
|
||||
|
||||
Provide custom STUN/TURN servers:
|
||||
|
||||
```typescript
|
||||
const host = new ServiceHost({
|
||||
service: 'chat.app@1.0.0',
|
||||
rondevuService: service,
|
||||
rtcConfiguration: {
|
||||
iceServers: [
|
||||
{ urls: 'stun:stun.l.google.com:19302' },
|
||||
{
|
||||
urls: 'turn:turn.example.com:3478',
|
||||
username: 'user',
|
||||
credential: 'pass'
|
||||
}
|
||||
]
|
||||
}
|
||||
const rondevu = await Rondevu.connect({
|
||||
apiUrl: string, // Required: Signaling server URL
|
||||
username?: string, // Optional: your username (auto-generates anonymous if omitted)
|
||||
keypair?: Keypair, // Optional: reuse existing keypair
|
||||
iceServers?: IceServerPreset | RTCIceServer[], // Optional: preset or custom config
|
||||
debug?: boolean // Optional: enable debug logging (default: false)
|
||||
})
|
||||
```
|
||||
|
||||
## Username Rules
|
||||
### Service Publishing
|
||||
|
||||
- **Format**: Lowercase alphanumeric + dash (`a-z`, `0-9`, `-`)
|
||||
- **Length**: 3-32 characters
|
||||
- **Pattern**: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
|
||||
- **Validity**: 365 days from claim/last use
|
||||
- **Ownership**: Secured by Ed25519 public key signature
|
||||
```typescript
|
||||
await rondevu.publishService({
|
||||
service: string, // e.g., 'chat:1.0.0' (username auto-appended)
|
||||
maxOffers: number, // Maximum concurrent offers to maintain
|
||||
offerFactory?: OfferFactory, // Optional: custom offer creation
|
||||
ttl?: number // Optional: offer lifetime in ms (default: 300000)
|
||||
})
|
||||
|
||||
await rondevu.startFilling() // Start accepting connections
|
||||
rondevu.stopFilling() // Stop and close all connections
|
||||
```
|
||||
|
||||
### Service Discovery
|
||||
|
||||
```typescript
|
||||
// Direct lookup (with username)
|
||||
await rondevu.getService('chat:1.0.0@alice')
|
||||
|
||||
// Random discovery (without username)
|
||||
await rondevu.discoverService('chat:1.0.0')
|
||||
|
||||
// Paginated discovery
|
||||
await rondevu.discoverServices('chat:1.0.0', limit, offset)
|
||||
```
|
||||
|
||||
### Connecting to Services
|
||||
|
||||
```typescript
|
||||
const connection = await rondevu.connectToService({
|
||||
serviceFqn?: string, // Full FQN like 'chat:1.0.0@alice'
|
||||
service?: string, // Service without username (for discovery)
|
||||
username?: string, // Target username (combined with service)
|
||||
onConnection?: (context) => void, // Called when data channel opens
|
||||
rtcConfig?: RTCConfiguration // Optional: override ICE servers
|
||||
})
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
📚 **[ADVANCED.md](./ADVANCED.md)** - Comprehensive guide including:
|
||||
- Detailed API reference for all methods
|
||||
- Type definitions and interfaces
|
||||
- Platform support (Browser & Node.js)
|
||||
- Advanced usage patterns
|
||||
- Username rules and service FQN format
|
||||
- Examples and migration guides
|
||||
|
||||
## Examples
|
||||
|
||||
### Chat Application
|
||||
|
||||
See [demo/demo.js](./demo/demo.js) for a complete working example.
|
||||
|
||||
### Persistent Keypair
|
||||
|
||||
```typescript
|
||||
// Save keypair to localStorage
|
||||
const service = new RondevuService({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: 'alice'
|
||||
})
|
||||
|
||||
await service.initialize()
|
||||
await service.claimUsername()
|
||||
|
||||
// Save for later
|
||||
localStorage.setItem('rondevu-keypair', JSON.stringify(service.getKeypair()))
|
||||
localStorage.setItem('rondevu-username', service.getUsername())
|
||||
|
||||
// Load on next session
|
||||
const savedKeypair = JSON.parse(localStorage.getItem('rondevu-keypair'))
|
||||
const savedUsername = localStorage.getItem('rondevu-username')
|
||||
|
||||
const service2 = new RondevuService({
|
||||
apiUrl: 'https://api.ronde.vu',
|
||||
username: savedUsername,
|
||||
keypair: savedKeypair
|
||||
})
|
||||
|
||||
await service2.initialize() // Reuses keypair
|
||||
```
|
||||
|
||||
### Message Queue Example
|
||||
|
||||
```typescript
|
||||
// Messages are automatically queued if not connected yet
|
||||
client.events.on('connected', (connection) => {
|
||||
// Send immediately
|
||||
connection.sendMessage('Hello!')
|
||||
})
|
||||
|
||||
// Or queue for later
|
||||
await client.connect()
|
||||
const conn = client.getConnection()
|
||||
await conn.queueMessage('This will be sent when connected', {
|
||||
expiresAt: Date.now() + 60000 // Expire after 1 minute
|
||||
})
|
||||
```
|
||||
|
||||
## Migration from v0.9.x
|
||||
|
||||
v0.11.0+ introduces high-level wrappers, RESTful API changes, and semver-compatible discovery:
|
||||
|
||||
**API Changes:**
|
||||
- Server endpoints restructured (`/usernames/*` → `/users/*`)
|
||||
- Added `ServiceHost` and `ServiceClient` wrappers
|
||||
- Message queue fully implemented
|
||||
- Configurable polling with exponential backoff
|
||||
- Removed deprecated `cleanup()` methods (use `dispose()`)
|
||||
- **v0.11.0+**: Services use `offers` array instead of single `sdp`
|
||||
- **v0.11.0+**: Semver-compatible service discovery (chat@1.0.0 matches 1.x.x)
|
||||
- **v0.11.0+**: All services are hidden - no listing endpoint
|
||||
- **v0.11.0+**: Services support multiple simultaneous offers for connection pooling
|
||||
|
||||
**Migration Guide:**
|
||||
|
||||
```typescript
|
||||
// Before (v0.9.x) - Manual WebRTC setup
|
||||
const signaler = new RondevuSignaler(service, 'chat@1.0.0')
|
||||
const context = new WebRTCContext()
|
||||
const pc = context.createPeerConnection()
|
||||
// ... 50+ lines of boilerplate
|
||||
|
||||
// After (v0.11.0) - ServiceHost wrapper
|
||||
const host = new ServiceHost({
|
||||
service: 'chat@1.0.0',
|
||||
rondevuService: service
|
||||
})
|
||||
await host.start()
|
||||
// Done!
|
||||
```
|
||||
|
||||
## Platform Support
|
||||
|
||||
### Modern Browsers
|
||||
Works out of the box - no additional setup needed.
|
||||
|
||||
### Node.js 18+
|
||||
Native fetch is available, but WebRTC requires polyfills:
|
||||
|
||||
```bash
|
||||
npm install wrtc
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { WebRTCContext } from '@xtr-dev/rondevu-client'
|
||||
import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc'
|
||||
|
||||
// Configure WebRTC context
|
||||
const context = new WebRTCContext({
|
||||
RTCPeerConnection,
|
||||
RTCSessionDescription,
|
||||
RTCIceCandidate
|
||||
} as any)
|
||||
```
|
||||
|
||||
## TypeScript
|
||||
|
||||
All types are exported:
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
RondevuServiceOptions,
|
||||
ServiceHostOptions,
|
||||
ServiceHostEvents,
|
||||
ServiceClientOptions,
|
||||
ServiceClientEvents,
|
||||
ConnectionInterface,
|
||||
ConnectionEvents,
|
||||
ConnectionStates,
|
||||
Message,
|
||||
QueueMessageOptions,
|
||||
Signaler,
|
||||
PollingConfig,
|
||||
Credentials,
|
||||
Keypair
|
||||
} from '@xtr-dev/rondevu-client'
|
||||
```
|
||||
- [React Demo](https://github.com/xtr-dev/rondevu-demo) - Full browser UI ([live](https://ronde.vu))
|
||||
|
||||
## License
|
||||
|
||||
|
||||
281
USAGE.md
281
USAGE.md
@@ -1,281 +0,0 @@
|
||||
# Rondevu Client Usage Guide
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @xtr-dev/rondevu-client
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Register and Create Connection
|
||||
|
||||
```typescript
|
||||
import { RondevuAPI, RondevuSignaler, WebRTCRondevuConnection } from '@xtr-dev/rondevu-client';
|
||||
|
||||
const API_URL = 'https://api.ronde.vu';
|
||||
|
||||
// Register to get credentials
|
||||
const api = new RondevuAPI(API_URL);
|
||||
const credentials = await api.register();
|
||||
|
||||
// Create authenticated API client
|
||||
const authenticatedApi = new RondevuAPI(API_URL, credentials);
|
||||
```
|
||||
|
||||
### 2. Create an Offer (Offerer Side)
|
||||
|
||||
```typescript
|
||||
// Create a connection
|
||||
const connection = new WebRTCRondevuConnection(
|
||||
'connection-id',
|
||||
'host-username',
|
||||
'service-name'
|
||||
);
|
||||
|
||||
// Wait for local description
|
||||
await connection.ready;
|
||||
|
||||
// Create offer on server
|
||||
const offers = await authenticatedApi.createOffers([{
|
||||
sdp: connection.connection.localDescription!.sdp!,
|
||||
ttl: 300000 // 5 minutes
|
||||
}]);
|
||||
|
||||
const offerId = offers[0].id;
|
||||
|
||||
// Set up signaler for ICE candidate exchange
|
||||
const signaler = new RondevuSignaler(authenticatedApi, offerId);
|
||||
connection.setSignaler(signaler);
|
||||
|
||||
// Poll for answer
|
||||
const checkAnswer = setInterval(async () => {
|
||||
const answer = await authenticatedApi.getAnswer(offerId);
|
||||
if (answer) {
|
||||
clearInterval(checkAnswer);
|
||||
await connection.connection.setRemoteDescription({
|
||||
type: 'answer',
|
||||
sdp: answer.sdp
|
||||
});
|
||||
console.log('Connection established!');
|
||||
}
|
||||
}, 1000);
|
||||
```
|
||||
|
||||
### 3. Answer an Offer (Answerer Side)
|
||||
|
||||
```typescript
|
||||
// Get the offer
|
||||
const offer = await authenticatedApi.getOffer(offerId);
|
||||
|
||||
// Create connection with remote offer
|
||||
const connection = new WebRTCRondevuConnection(
|
||||
'connection-id',
|
||||
'peer-username',
|
||||
'service-name',
|
||||
{
|
||||
type: 'offer',
|
||||
sdp: offer.sdp
|
||||
}
|
||||
);
|
||||
|
||||
// Wait for local description (answer)
|
||||
await connection.ready;
|
||||
|
||||
// Send answer to server
|
||||
await authenticatedApi.answerOffer(
|
||||
offerId,
|
||||
connection.connection.localDescription!.sdp!
|
||||
);
|
||||
|
||||
// Set up signaler for ICE candidate exchange
|
||||
const signaler = new RondevuSignaler(authenticatedApi, offerId);
|
||||
connection.setSignaler(signaler);
|
||||
|
||||
console.log('Connection established!');
|
||||
```
|
||||
|
||||
## Using Services
|
||||
|
||||
### Publish a Service
|
||||
|
||||
```typescript
|
||||
import { RondevuAPI } from '@xtr-dev/rondevu-client';
|
||||
|
||||
const api = new RondevuAPI(API_URL, credentials);
|
||||
|
||||
const service = await api.publishService({
|
||||
username: 'my-username',
|
||||
serviceFqn: 'chat.app@1.0.0',
|
||||
sdp: localDescription.sdp,
|
||||
ttl: 300000,
|
||||
isPublic: true,
|
||||
metadata: { description: 'My chat service' },
|
||||
signature: '...', // Ed25519 signature
|
||||
message: '...' // Signed message
|
||||
});
|
||||
|
||||
console.log('Service UUID:', service.uuid);
|
||||
```
|
||||
|
||||
### Connect to a Service
|
||||
|
||||
```typescript
|
||||
// Search for services
|
||||
const services = await api.searchServices('username', 'chat.app@1.0.0');
|
||||
|
||||
if (services.length > 0) {
|
||||
// Get service details with offer
|
||||
const service = await api.getService(services[0].uuid);
|
||||
|
||||
// Create connection with service offer
|
||||
const connection = new WebRTCRondevuConnection(
|
||||
service.serviceId,
|
||||
service.username,
|
||||
service.serviceFqn,
|
||||
{
|
||||
type: 'offer',
|
||||
sdp: service.sdp
|
||||
}
|
||||
);
|
||||
|
||||
await connection.ready;
|
||||
|
||||
// Answer the service offer
|
||||
await api.answerOffer(
|
||||
service.offerId,
|
||||
connection.connection.localDescription!.sdp!
|
||||
);
|
||||
|
||||
// Set up signaler
|
||||
const signaler = new RondevuSignaler(api, service.offerId);
|
||||
connection.setSignaler(signaler);
|
||||
}
|
||||
```
|
||||
|
||||
## Event Handling
|
||||
|
||||
```typescript
|
||||
import { EventBus } from '@xtr-dev/rondevu-client';
|
||||
|
||||
// Connection events
|
||||
connection.events.on('state-change', (state) => {
|
||||
console.log('Connection state:', state);
|
||||
});
|
||||
|
||||
connection.events.on('message', (message) => {
|
||||
console.log('Received message:', message);
|
||||
});
|
||||
|
||||
// Custom events with EventBus
|
||||
interface MyEvents {
|
||||
'user:connected': { userId: string; timestamp: number };
|
||||
'message:sent': string;
|
||||
}
|
||||
|
||||
const events = new EventBus<MyEvents>();
|
||||
|
||||
events.on('user:connected', (data) => {
|
||||
console.log(`User ${data.userId} connected at ${data.timestamp}`);
|
||||
});
|
||||
|
||||
events.emit('user:connected', {
|
||||
userId: '123',
|
||||
timestamp: Date.now()
|
||||
});
|
||||
```
|
||||
|
||||
## Cleanup
|
||||
|
||||
```typescript
|
||||
import { createBin } from '@xtr-dev/rondevu-client';
|
||||
|
||||
const bin = createBin();
|
||||
|
||||
// Add cleanup functions
|
||||
bin(
|
||||
() => console.log('Cleanup 1'),
|
||||
() => console.log('Cleanup 2')
|
||||
);
|
||||
|
||||
// Clean all
|
||||
bin.clean();
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### RondevuAPI
|
||||
|
||||
Complete API client for Rondevu signaling server.
|
||||
|
||||
**Methods:**
|
||||
- `register()` - Register new peer
|
||||
- `createOffers(offers)` - Create offers
|
||||
- `getOffer(offerId)` - Get offer by ID
|
||||
- `answerOffer(offerId, sdp)` - Answer an offer
|
||||
- `getAnswer(offerId)` - Poll for answer
|
||||
- `searchOffers(topic)` - Search by topic
|
||||
- `addIceCandidates(offerId, candidates)` - Add ICE candidates
|
||||
- `getIceCandidates(offerId, since)` - Get ICE candidates (polling)
|
||||
- `publishService(service)` - Publish service
|
||||
- `getService(uuid)` - Get service by UUID
|
||||
- `searchServices(username, serviceFqn)` - Search services
|
||||
- `checkUsername(username)` - Check availability
|
||||
- `claimUsername(username, publicKey, signature, message)` - Claim username
|
||||
|
||||
### RondevuSignaler
|
||||
|
||||
Handles ICE candidate exchange via polling.
|
||||
|
||||
**Constructor:**
|
||||
```typescript
|
||||
new RondevuSignaler(api: RondevuAPI, offerId: string)
|
||||
```
|
||||
|
||||
**Methods:**
|
||||
- `addIceCandidate(candidate)` - Send local candidate
|
||||
- `addListener(callback)` - Poll for remote candidates (returns cleanup function)
|
||||
|
||||
### WebRTCRondevuConnection
|
||||
|
||||
WebRTC connection wrapper with type-safe events.
|
||||
|
||||
**Constructor:**
|
||||
```typescript
|
||||
new WebRTCRondevuConnection(
|
||||
id: string,
|
||||
host: string,
|
||||
service: string,
|
||||
offer?: RTCSessionDescriptionInit
|
||||
)
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- `id` - Connection ID
|
||||
- `host` - Host username
|
||||
- `service` - Service FQN
|
||||
- `state` - Connection state
|
||||
- `events` - EventBus for state changes and messages
|
||||
- `ready` - Promise that resolves when local description is set
|
||||
|
||||
**Methods:**
|
||||
- `setSignaler(signaler)` - Set signaler for ICE exchange
|
||||
- `queueMessage(message, options)` - Queue message for sending
|
||||
- `sendMessage(message)` - Send message immediately
|
||||
|
||||
### EventBus<TEvents>
|
||||
|
||||
Type-safe event emitter with inferred types.
|
||||
|
||||
**Methods:**
|
||||
- `on(event, handler)` - Subscribe
|
||||
- `once(event, handler)` - Subscribe once
|
||||
- `off(event, handler)` - Unsubscribe
|
||||
- `emit(event, data)` - Emit event
|
||||
- `clear(event?)` - Clear handlers
|
||||
- `listenerCount(event)` - Get listener count
|
||||
- `eventNames()` - Get event names
|
||||
|
||||
## Examples
|
||||
|
||||
See the demo application at https://github.com/xtr-dev/rondevu-demo for a complete working example.
|
||||
4
package-lock.json
generated
4
package-lock.json
generated
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "@xtr-dev/rondevu-client",
|
||||
"version": "0.12.0",
|
||||
"version": "0.17.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "@xtr-dev/rondevu-client",
|
||||
"version": "0.12.0",
|
||||
"version": "0.17.0",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@noble/ed25519": "^3.0.0",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@xtr-dev/rondevu-client",
|
||||
"version": "0.12.0",
|
||||
"version": "0.17.0",
|
||||
"description": "TypeScript client for Rondevu with durable WebRTC connections, automatic reconnection, and message queuing",
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
|
||||
641
src/api.ts
641
src/api.ts
@@ -1,53 +1,22 @@
|
||||
/**
|
||||
* Rondevu API Client - Single class for all API endpoints
|
||||
* Rondevu API Client - RPC interface
|
||||
*/
|
||||
|
||||
import * as ed25519 from '@noble/ed25519'
|
||||
import { CryptoAdapter, Keypair } from './crypto-adapter.js'
|
||||
import { WebCryptoAdapter } from './web-crypto-adapter.js'
|
||||
import { RpcBatcher, BatcherOptions } from './rpc-batcher.js'
|
||||
|
||||
// Set SHA-512 hash function for ed25519 (required in @noble/ed25519 v3+)
|
||||
ed25519.hashes.sha512Async = async (message: Uint8Array) => {
|
||||
return new Uint8Array(await crypto.subtle.digest('SHA-512', message as BufferSource))
|
||||
}
|
||||
|
||||
export interface Credentials {
|
||||
peerId: string
|
||||
secret: string
|
||||
}
|
||||
|
||||
export interface Keypair {
|
||||
publicKey: string
|
||||
privateKey: string
|
||||
}
|
||||
|
||||
export interface OfferRequest {
|
||||
sdp: string
|
||||
topics?: string[]
|
||||
ttl?: number
|
||||
secret?: string
|
||||
}
|
||||
|
||||
export interface Offer {
|
||||
id: string
|
||||
peerId: string
|
||||
sdp: string
|
||||
topics: string[]
|
||||
ttl: number
|
||||
createdAt: number
|
||||
expiresAt: number
|
||||
answererPeerId?: string
|
||||
}
|
||||
export type { Keypair } from './crypto-adapter.js'
|
||||
export type { BatcherOptions } from './rpc-batcher.js'
|
||||
|
||||
export interface OfferRequest {
|
||||
sdp: string
|
||||
}
|
||||
|
||||
export interface ServiceRequest {
|
||||
username: string
|
||||
serviceFqn: string
|
||||
serviceFqn: string // Must include username: service:version@username
|
||||
offers: OfferRequest[]
|
||||
ttl?: number
|
||||
isPublic?: boolean
|
||||
metadata?: Record<string, any>
|
||||
signature: string
|
||||
message: string
|
||||
}
|
||||
@@ -61,63 +30,153 @@ export interface ServiceOffer {
|
||||
|
||||
export interface Service {
|
||||
serviceId: string
|
||||
uuid: string
|
||||
offers: ServiceOffer[]
|
||||
username: string
|
||||
serviceFqn: string
|
||||
isPublic: boolean
|
||||
metadata?: Record<string, any>
|
||||
createdAt: number
|
||||
expiresAt: number
|
||||
}
|
||||
|
||||
export interface IceCandidate {
|
||||
candidate: RTCIceCandidateInit
|
||||
candidate: RTCIceCandidateInit | null
|
||||
createdAt: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Helper: Convert Uint8Array to base64 string
|
||||
* RPC request format
|
||||
*/
|
||||
function bytesToBase64(bytes: Uint8Array): string {
|
||||
const binString = Array.from(bytes, byte => String.fromCodePoint(byte)).join('')
|
||||
return btoa(binString)
|
||||
interface RpcRequest {
|
||||
method: string
|
||||
message: string
|
||||
signature: string
|
||||
publicKey?: string
|
||||
params?: any
|
||||
}
|
||||
|
||||
/**
|
||||
* Helper: Convert base64 string to Uint8Array
|
||||
* RPC response format
|
||||
*/
|
||||
function base64ToBytes(base64: string): Uint8Array {
|
||||
const binString = atob(base64)
|
||||
return Uint8Array.from(binString, char => char.codePointAt(0)!)
|
||||
interface RpcResponse {
|
||||
success: boolean
|
||||
result?: any
|
||||
error?: string
|
||||
}
|
||||
|
||||
/**
|
||||
* RondevuAPI - Complete API client for Rondevu signaling server
|
||||
* RondevuAPI - RPC-based API client for Rondevu signaling server
|
||||
*/
|
||||
export class RondevuAPI {
|
||||
private crypto: CryptoAdapter
|
||||
private batcher: RpcBatcher | null = null
|
||||
|
||||
constructor(
|
||||
private baseUrl: string,
|
||||
private credentials?: Credentials
|
||||
) {}
|
||||
private username: string,
|
||||
private keypair: Keypair,
|
||||
cryptoAdapter?: CryptoAdapter,
|
||||
batcherOptions?: BatcherOptions | false
|
||||
) {
|
||||
// Use WebCryptoAdapter by default (browser environment)
|
||||
this.crypto = cryptoAdapter || new WebCryptoAdapter()
|
||||
|
||||
/**
|
||||
* Set credentials for authentication
|
||||
*/
|
||||
setCredentials(credentials: Credentials): void {
|
||||
this.credentials = credentials
|
||||
// Create batcher if not explicitly disabled
|
||||
if (batcherOptions !== false) {
|
||||
this.batcher = new RpcBatcher(
|
||||
(requests) => this.rpcBatchDirect(requests),
|
||||
batcherOptions
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Authentication header
|
||||
* Generate authentication parameters for RPC calls
|
||||
*/
|
||||
private getAuthHeader(): Record<string, string> {
|
||||
if (!this.credentials) {
|
||||
return {}
|
||||
private async generateAuth(method: string, params: string = ''): Promise<{
|
||||
message: string
|
||||
signature: string
|
||||
}> {
|
||||
const timestamp = Date.now()
|
||||
const message = params
|
||||
? `${method}:${this.username}:${params}:${timestamp}`
|
||||
: `${method}:${this.username}:${timestamp}`
|
||||
|
||||
const signature = await this.crypto.signMessage(message, this.keypair.privateKey)
|
||||
|
||||
return { message, signature }
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute RPC call with optional batching
|
||||
*/
|
||||
private async rpc(request: RpcRequest): Promise<any> {
|
||||
// Use batcher if enabled
|
||||
if (this.batcher) {
|
||||
return await this.batcher.add(request)
|
||||
}
|
||||
return {
|
||||
Authorization: `Bearer ${this.credentials.peerId}:${this.credentials.secret}`,
|
||||
|
||||
// Direct call without batching
|
||||
return await this.rpcDirect(request)
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute single RPC call directly (bypasses batcher)
|
||||
*/
|
||||
private async rpcDirect(request: RpcRequest): Promise<any> {
|
||||
const response = await fetch(`${this.baseUrl}/rpc`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(request),
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP ${response.status}: ${response.statusText}`)
|
||||
}
|
||||
|
||||
const result: RpcResponse = await response.json()
|
||||
|
||||
if (!result.success) {
|
||||
throw new Error(result.error || 'RPC call failed')
|
||||
}
|
||||
|
||||
return result.result
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute batch RPC calls directly (bypasses batcher)
|
||||
*/
|
||||
private async rpcBatchDirect(requests: RpcRequest[]): Promise<any[]> {
|
||||
const response = await fetch(`${this.baseUrl}/rpc`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(requests),
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP ${response.status}: ${response.statusText}`)
|
||||
}
|
||||
|
||||
const results: RpcResponse[] = await response.json()
|
||||
|
||||
// Validate response is an array
|
||||
if (!Array.isArray(results)) {
|
||||
console.error('Invalid RPC batch response:', results)
|
||||
throw new Error('Server returned invalid batch response (not an array)')
|
||||
}
|
||||
|
||||
// Check response length matches request length
|
||||
if (results.length !== requests.length) {
|
||||
console.error(`Response length mismatch: expected ${requests.length}, got ${results.length}`)
|
||||
}
|
||||
|
||||
return results.map((result, i) => {
|
||||
if (!result || typeof result !== 'object') {
|
||||
throw new Error(`Invalid response at index ${i}`)
|
||||
}
|
||||
if (!result.success) {
|
||||
throw new Error(result.error || `RPC call ${i} failed`)
|
||||
}
|
||||
return result.result
|
||||
})
|
||||
}
|
||||
|
||||
// ============================================
|
||||
@@ -126,341 +185,239 @@ export class RondevuAPI {
|
||||
|
||||
/**
|
||||
* Generate an Ed25519 keypair for username claiming and service publishing
|
||||
* @param cryptoAdapter - Optional crypto adapter (defaults to WebCryptoAdapter)
|
||||
*/
|
||||
static async generateKeypair(): Promise<Keypair> {
|
||||
const privateKey = ed25519.utils.randomSecretKey()
|
||||
const publicKey = await ed25519.getPublicKeyAsync(privateKey)
|
||||
|
||||
return {
|
||||
publicKey: bytesToBase64(publicKey),
|
||||
privateKey: bytesToBase64(privateKey),
|
||||
}
|
||||
static async generateKeypair(cryptoAdapter?: CryptoAdapter): Promise<Keypair> {
|
||||
const adapter = cryptoAdapter || new WebCryptoAdapter()
|
||||
return await adapter.generateKeypair()
|
||||
}
|
||||
|
||||
/**
|
||||
* Sign a message with an Ed25519 private key
|
||||
* @param cryptoAdapter - Optional crypto adapter (defaults to WebCryptoAdapter)
|
||||
*/
|
||||
static async signMessage(message: string, privateKeyBase64: string): Promise<string> {
|
||||
const privateKey = base64ToBytes(privateKeyBase64)
|
||||
const encoder = new TextEncoder()
|
||||
const messageBytes = encoder.encode(message)
|
||||
|
||||
const signature = await ed25519.signAsync(messageBytes, privateKey)
|
||||
return bytesToBase64(signature)
|
||||
static async signMessage(
|
||||
message: string,
|
||||
privateKeyBase64: string,
|
||||
cryptoAdapter?: CryptoAdapter
|
||||
): Promise<string> {
|
||||
const adapter = cryptoAdapter || new WebCryptoAdapter()
|
||||
return await adapter.signMessage(message, privateKeyBase64)
|
||||
}
|
||||
|
||||
/**
|
||||
* Verify a signature
|
||||
* Verify an Ed25519 signature
|
||||
* @param cryptoAdapter - Optional crypto adapter (defaults to WebCryptoAdapter)
|
||||
*/
|
||||
static async verifySignature(
|
||||
message: string,
|
||||
signatureBase64: string,
|
||||
publicKeyBase64: string
|
||||
publicKeyBase64: string,
|
||||
cryptoAdapter?: CryptoAdapter
|
||||
): Promise<boolean> {
|
||||
const publicKey = base64ToBytes(publicKeyBase64)
|
||||
const signature = base64ToBytes(signatureBase64)
|
||||
const encoder = new TextEncoder()
|
||||
const messageBytes = encoder.encode(message)
|
||||
|
||||
return await ed25519.verifyAsync(signature, messageBytes, publicKey)
|
||||
const adapter = cryptoAdapter || new WebCryptoAdapter()
|
||||
return await adapter.verifySignature(message, signatureBase64, publicKeyBase64)
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// Authentication
|
||||
// Username Management
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Register a new peer and get credentials
|
||||
* Check if a username is available
|
||||
*/
|
||||
async register(): Promise<Credentials> {
|
||||
const response = await fetch(`${this.baseUrl}/register`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
async isUsernameAvailable(username: string): Promise<boolean> {
|
||||
const auth = await this.generateAuth('getUser', username)
|
||||
const result = await this.rpc({
|
||||
method: 'getUser',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
params: { username },
|
||||
})
|
||||
return result.available
|
||||
}
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Registration failed: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
/**
|
||||
* Check if current username is claimed
|
||||
*/
|
||||
async isUsernameClaimed(): Promise<boolean> {
|
||||
const auth = await this.generateAuth('getUser', this.username)
|
||||
const result = await this.rpc({
|
||||
method: 'getUser',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
params: { username: this.username },
|
||||
})
|
||||
return !result.available
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// Offers
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Create one or more offers
|
||||
*/
|
||||
async createOffers(offers: OfferRequest[]): Promise<Offer[]> {
|
||||
const response = await fetch(`${this.baseUrl}/offers`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
...this.getAuthHeader(),
|
||||
},
|
||||
body: JSON.stringify({ offers }),
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to create offers: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
}
|
||||
|
||||
/**
|
||||
* Get offer by ID
|
||||
*/
|
||||
async getOffer(offerId: string): Promise<Offer> {
|
||||
const response = await fetch(`${this.baseUrl}/offers/${offerId}`, {
|
||||
headers: this.getAuthHeader(),
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to get offer: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
}
|
||||
|
||||
/**
|
||||
* Answer a service
|
||||
*/
|
||||
async answerService(serviceUuid: string, sdp: string): Promise<{ offerId: string }> {
|
||||
const response = await fetch(`${this.baseUrl}/services/${serviceUuid}/answer`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
...this.getAuthHeader(),
|
||||
},
|
||||
body: JSON.stringify({ sdp }),
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to answer service: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
}
|
||||
|
||||
/**
|
||||
* Get answer for a service (offerer polls this)
|
||||
*/
|
||||
async getServiceAnswer(serviceUuid: string): Promise<{ sdp: string; offerId: string } | null> {
|
||||
const response = await fetch(`${this.baseUrl}/services/${serviceUuid}/answer`, {
|
||||
headers: this.getAuthHeader(),
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
// 404 means not yet answered
|
||||
if (response.status === 404) {
|
||||
return null
|
||||
}
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to get answer: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
const data = await response.json()
|
||||
return { sdp: data.sdp, offerId: data.offerId }
|
||||
}
|
||||
|
||||
/**
|
||||
* Search offers by topic
|
||||
*/
|
||||
async searchOffers(topic: string): Promise<Offer[]> {
|
||||
const response = await fetch(`${this.baseUrl}/offers?topic=${encodeURIComponent(topic)}`, {
|
||||
headers: this.getAuthHeader(),
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to search offers: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// ICE Candidates
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Add ICE candidates to a service
|
||||
*/
|
||||
async addServiceIceCandidates(serviceUuid: string, candidates: RTCIceCandidateInit[], offerId?: string): Promise<{ offerId: string }> {
|
||||
const response = await fetch(`${this.baseUrl}/services/${serviceUuid}/ice-candidates`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
...this.getAuthHeader(),
|
||||
},
|
||||
body: JSON.stringify({ candidates, offerId }),
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to add ICE candidates: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
}
|
||||
|
||||
/**
|
||||
* Get ICE candidates for a service (with polling support)
|
||||
*/
|
||||
async getServiceIceCandidates(serviceUuid: string, since: number = 0, offerId?: string): Promise<{ candidates: IceCandidate[]; offerId: string }> {
|
||||
const url = new URL(`${this.baseUrl}/services/${serviceUuid}/ice-candidates`)
|
||||
url.searchParams.set('since', since.toString())
|
||||
if (offerId) {
|
||||
url.searchParams.set('offerId', offerId)
|
||||
}
|
||||
|
||||
const response = await fetch(url.toString(), { headers: this.getAuthHeader() })
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to get ICE candidates: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
const data = await response.json()
|
||||
return {
|
||||
candidates: data.candidates || [],
|
||||
offerId: data.offerId
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// Services
|
||||
// Service Management
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Publish a service
|
||||
*/
|
||||
async publishService(service: ServiceRequest): Promise<Service> {
|
||||
const response = await fetch(`${this.baseUrl}/users/${encodeURIComponent(service.username)}/services`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
...this.getAuthHeader(),
|
||||
const auth = await this.generateAuth('publishService', service.serviceFqn)
|
||||
return await this.rpc({
|
||||
method: 'publishService',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
publicKey: this.keypair.publicKey,
|
||||
params: {
|
||||
serviceFqn: service.serviceFqn,
|
||||
offers: service.offers,
|
||||
ttl: service.ttl,
|
||||
},
|
||||
body: JSON.stringify(service),
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to publish service: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
}
|
||||
|
||||
/**
|
||||
* Get service by UUID
|
||||
* Get service by FQN (direct lookup, random, or paginated)
|
||||
*/
|
||||
async getService(uuid: string): Promise<Service & { offerId: string; sdp: string }> {
|
||||
const response = await fetch(`${this.baseUrl}/services/${uuid}`, {
|
||||
headers: this.getAuthHeader(),
|
||||
async getService(
|
||||
serviceFqn: string,
|
||||
options?: { limit?: number; offset?: number }
|
||||
): Promise<any> {
|
||||
const auth = await this.generateAuth('getService', serviceFqn)
|
||||
return await this.rpc({
|
||||
method: 'getService',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
publicKey: this.keypair.publicKey,
|
||||
params: {
|
||||
serviceFqn,
|
||||
...options,
|
||||
},
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to get service: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
}
|
||||
|
||||
/**
|
||||
* Search services by username - lists all services for a username
|
||||
* Delete a service
|
||||
*/
|
||||
async searchServicesByUsername(username: string): Promise<Service[]> {
|
||||
const response = await fetch(
|
||||
`${this.baseUrl}/users/${encodeURIComponent(username)}/services`,
|
||||
{ headers: this.getAuthHeader() }
|
||||
)
|
||||
async deleteService(serviceFqn: string): Promise<void> {
|
||||
const auth = await this.generateAuth('deleteService', serviceFqn)
|
||||
await this.rpc({
|
||||
method: 'deleteService',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
publicKey: this.keypair.publicKey,
|
||||
params: { serviceFqn },
|
||||
})
|
||||
}
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to search services: ${error.error || response.statusText}`)
|
||||
}
|
||||
// ============================================
|
||||
// WebRTC Signaling
|
||||
// ============================================
|
||||
|
||||
const data = await response.json()
|
||||
return data.services || []
|
||||
/**
|
||||
* Answer an offer
|
||||
*/
|
||||
async answerOffer(serviceFqn: string, offerId: string, sdp: string): Promise<void> {
|
||||
const auth = await this.generateAuth('answerOffer', offerId)
|
||||
await this.rpc({
|
||||
method: 'answerOffer',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
publicKey: this.keypair.publicKey,
|
||||
params: { serviceFqn, offerId, sdp },
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Search services by username AND FQN - returns full service details
|
||||
* Get answer for a specific offer (offerer polls this)
|
||||
*/
|
||||
async searchServices(username: string, serviceFqn: string): Promise<Service[]> {
|
||||
const response = await fetch(
|
||||
`${this.baseUrl}/users/${encodeURIComponent(username)}/services/${encodeURIComponent(serviceFqn)}`,
|
||||
{ headers: this.getAuthHeader() }
|
||||
)
|
||||
|
||||
if (!response.ok) {
|
||||
if (response.status === 404) {
|
||||
return []
|
||||
async getOfferAnswer(
|
||||
serviceFqn: string,
|
||||
offerId: string
|
||||
): Promise<{ sdp: string; offerId: string; answererId: string; answeredAt: number } | null> {
|
||||
try {
|
||||
const auth = await this.generateAuth('getOfferAnswer', offerId)
|
||||
return await this.rpc({
|
||||
method: 'getOfferAnswer',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
publicKey: this.keypair.publicKey,
|
||||
params: { serviceFqn, offerId },
|
||||
})
|
||||
} catch (err) {
|
||||
if ((err as Error).message.includes('not yet answered')) {
|
||||
return null
|
||||
}
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to search services: ${error.error || response.statusText}`)
|
||||
throw err
|
||||
}
|
||||
|
||||
const service = await response.json()
|
||||
return [service]
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// Usernames
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Check if username is available
|
||||
*/
|
||||
async checkUsername(username: string): Promise<{ available: boolean; owner?: string }> {
|
||||
const response = await fetch(
|
||||
`${this.baseUrl}/users/${encodeURIComponent(username)}`
|
||||
)
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to check username: ${error.error || response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
}
|
||||
|
||||
/**
|
||||
* Claim a username (requires Ed25519 signature)
|
||||
* Combined polling for answers and ICE candidates
|
||||
*/
|
||||
async claimUsername(
|
||||
username: string,
|
||||
publicKey: string,
|
||||
signature: string,
|
||||
message: string
|
||||
): Promise<{ success: boolean; username: string }> {
|
||||
const response = await fetch(`${this.baseUrl}/users/${encodeURIComponent(username)}`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
...this.getAuthHeader(),
|
||||
},
|
||||
body: JSON.stringify({
|
||||
publicKey,
|
||||
signature,
|
||||
message,
|
||||
}),
|
||||
async poll(since?: number): Promise<{
|
||||
answers: Array<{
|
||||
offerId: string
|
||||
serviceId?: string
|
||||
answererId: string
|
||||
sdp: string
|
||||
answeredAt: number
|
||||
}>
|
||||
iceCandidates: Record<
|
||||
string,
|
||||
Array<{
|
||||
candidate: RTCIceCandidateInit | null
|
||||
role: 'offerer' | 'answerer'
|
||||
peerId: string
|
||||
createdAt: number
|
||||
}>
|
||||
>
|
||||
}> {
|
||||
const auth = await this.generateAuth('poll')
|
||||
return await this.rpc({
|
||||
method: 'poll',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
publicKey: this.keypair.publicKey,
|
||||
params: { since },
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Add ICE candidates to a specific offer
|
||||
*/
|
||||
async addOfferIceCandidates(
|
||||
serviceFqn: string,
|
||||
offerId: string,
|
||||
candidates: RTCIceCandidateInit[]
|
||||
): Promise<{ count: number; offerId: string }> {
|
||||
const auth = await this.generateAuth('addIceCandidates', offerId)
|
||||
return await this.rpc({
|
||||
method: 'addIceCandidates',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
publicKey: this.keypair.publicKey,
|
||||
params: { serviceFqn, offerId, candidates },
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Get ICE candidates for a specific offer
|
||||
*/
|
||||
async getOfferIceCandidates(
|
||||
serviceFqn: string,
|
||||
offerId: string,
|
||||
since: number = 0
|
||||
): Promise<{ candidates: IceCandidate[]; offerId: string }> {
|
||||
const auth = await this.generateAuth('getIceCandidates', `${offerId}:${since}`)
|
||||
const result = await this.rpc({
|
||||
method: 'getIceCandidates',
|
||||
message: auth.message,
|
||||
signature: auth.signature,
|
||||
publicKey: this.keypair.publicKey,
|
||||
params: { serviceFqn, offerId, since },
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json().catch(() => ({ error: 'Unknown error' }))
|
||||
throw new Error(`Failed to claim username: ${error.error || response.statusText}`)
|
||||
return {
|
||||
candidates: result.candidates || [],
|
||||
offerId: result.offerId,
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
}
|
||||
}
|
||||
|
||||
42
src/bin.ts
42
src/bin.ts
@@ -1,42 +0,0 @@
|
||||
/**
|
||||
* Binnable - A cleanup function that can be synchronous or asynchronous
|
||||
*
|
||||
* Used to unsubscribe from events, close connections, or perform other cleanup operations.
|
||||
*/
|
||||
export type Binnable = () => void | Promise<void>
|
||||
|
||||
/**
|
||||
* Create a cleanup function collector (garbage bin)
|
||||
*
|
||||
* Collects cleanup functions and provides a single `clean()` method to execute all of them.
|
||||
* Useful for managing multiple cleanup operations in a single place.
|
||||
*
|
||||
* @returns A function that accepts cleanup functions and has a `clean()` method
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const bin = createBin();
|
||||
*
|
||||
* // Add cleanup functions
|
||||
* bin(
|
||||
* () => console.log('Cleanup 1'),
|
||||
* () => connection.close(),
|
||||
* () => clearInterval(timer)
|
||||
* );
|
||||
*
|
||||
* // Later, clean everything
|
||||
* bin.clean(); // Executes all cleanup functions
|
||||
* ```
|
||||
*/
|
||||
export const createBin = () => {
|
||||
const bin: Binnable[] = []
|
||||
return Object.assign((...rubbish: Binnable[]) => bin.push(...rubbish), {
|
||||
/**
|
||||
* Execute all cleanup functions and clear the bin
|
||||
*/
|
||||
clean: (): void => {
|
||||
bin.forEach(binnable => binnable())
|
||||
bin.length = 0
|
||||
},
|
||||
})
|
||||
}
|
||||
48
src/crypto-adapter.ts
Normal file
48
src/crypto-adapter.ts
Normal file
@@ -0,0 +1,48 @@
|
||||
/**
|
||||
* Crypto adapter interface for platform-independent cryptographic operations
|
||||
*/
|
||||
|
||||
export interface Keypair {
|
||||
publicKey: string
|
||||
privateKey: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Platform-independent crypto adapter interface
|
||||
* Implementations provide platform-specific crypto operations
|
||||
*/
|
||||
export interface CryptoAdapter {
|
||||
/**
|
||||
* Generate an Ed25519 keypair
|
||||
*/
|
||||
generateKeypair(): Promise<Keypair>
|
||||
|
||||
/**
|
||||
* Sign a message with an Ed25519 private key
|
||||
*/
|
||||
signMessage(message: string, privateKeyBase64: string): Promise<string>
|
||||
|
||||
/**
|
||||
* Verify an Ed25519 signature
|
||||
*/
|
||||
verifySignature(
|
||||
message: string,
|
||||
signatureBase64: string,
|
||||
publicKeyBase64: string
|
||||
): Promise<boolean>
|
||||
|
||||
/**
|
||||
* Convert Uint8Array to base64 string
|
||||
*/
|
||||
bytesToBase64(bytes: Uint8Array): string
|
||||
|
||||
/**
|
||||
* Convert base64 string to Uint8Array
|
||||
*/
|
||||
base64ToBytes(base64: string): Uint8Array
|
||||
|
||||
/**
|
||||
* Generate random bytes
|
||||
*/
|
||||
randomBytes(length: number): Uint8Array
|
||||
}
|
||||
@@ -1,290 +0,0 @@
|
||||
import {
|
||||
ConnectionEvents,
|
||||
ConnectionInterface,
|
||||
ConnectionStates,
|
||||
isConnectionState,
|
||||
Message,
|
||||
QueueMessageOptions,
|
||||
Signaler,
|
||||
} from './types.js'
|
||||
import { EventBus } from './event-bus.js'
|
||||
import { createBin } from './bin.js'
|
||||
import { WebRTCContext } from './webrtc-context'
|
||||
|
||||
export type WebRTCRondevuConnectionOptions = {
|
||||
offer?: RTCSessionDescriptionInit | null
|
||||
context: WebRTCContext
|
||||
signaler: Signaler
|
||||
}
|
||||
|
||||
/**
|
||||
* WebRTCRondevuConnection - WebRTC peer connection wrapper with Rondevu signaling
|
||||
*
|
||||
* Manages a WebRTC peer connection lifecycle including:
|
||||
* - Automatic offer/answer creation based on role
|
||||
* - ICE candidate exchange via Rondevu signaling server
|
||||
* - Connection state management with type-safe events
|
||||
* - Data channel creation and message handling
|
||||
*
|
||||
* The connection automatically determines its role (offerer or answerer) based on whether
|
||||
* an offer is provided in the constructor. The offerer creates the data channel, while
|
||||
* the answerer receives it via the 'datachannel' event.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Offerer side (creates offer)
|
||||
* const connection = new WebRTCRondevuConnection(
|
||||
* 'conn-123',
|
||||
* 'peer-username',
|
||||
* 'chat.service@1.0.0'
|
||||
* );
|
||||
*
|
||||
* await connection.ready; // Wait for local offer
|
||||
* const sdp = connection.connection.localDescription!.sdp!;
|
||||
* // Send sdp to signaling server...
|
||||
*
|
||||
* // Answerer side (receives offer)
|
||||
* const connection = new WebRTCRondevuConnection(
|
||||
* 'conn-123',
|
||||
* 'peer-username',
|
||||
* 'chat.service@1.0.0',
|
||||
* { type: 'offer', sdp: remoteOfferSdp }
|
||||
* );
|
||||
*
|
||||
* await connection.ready; // Wait for local answer
|
||||
* const answerSdp = connection.connection.localDescription!.sdp!;
|
||||
* // Send answer to signaling server...
|
||||
*
|
||||
* // Both sides: Set up signaler and listen for state changes
|
||||
* connection.setSignaler(signaler);
|
||||
* connection.events.on('state-change', (state) => {
|
||||
* console.log('Connection state:', state);
|
||||
* });
|
||||
* ```
|
||||
*/
|
||||
export class RTCDurableConnection implements ConnectionInterface {
|
||||
private readonly side: 'offer' | 'answer'
|
||||
public readonly expiresAt: number = 0
|
||||
public readonly lastActive: number = 0
|
||||
public readonly events: EventBus<ConnectionEvents> = new EventBus()
|
||||
public readonly ready: Promise<void>
|
||||
private iceBin = createBin()
|
||||
private context: WebRTCContext
|
||||
private readonly signaler: Signaler
|
||||
private _conn: RTCPeerConnection | null = null
|
||||
private _state: ConnectionInterface['state'] = 'disconnected'
|
||||
private _dataChannel: RTCDataChannel | null = null
|
||||
private messageQueue: Array<{
|
||||
message: Message
|
||||
options: QueueMessageOptions
|
||||
timestamp: number
|
||||
}> = []
|
||||
|
||||
constructor({ context, offer, signaler }: WebRTCRondevuConnectionOptions) {
|
||||
this.context = context
|
||||
this.signaler = signaler
|
||||
this._conn = context.createPeerConnection()
|
||||
this.side = offer ? 'answer' : 'offer'
|
||||
|
||||
// setup data channel
|
||||
if (offer) {
|
||||
this._conn.addEventListener('datachannel', e => {
|
||||
this._dataChannel = e.channel
|
||||
this.setupDataChannelListeners(this._dataChannel)
|
||||
})
|
||||
} else {
|
||||
this._dataChannel = this._conn.createDataChannel('vu.ronde.protocol')
|
||||
this.setupDataChannelListeners(this._dataChannel)
|
||||
}
|
||||
|
||||
// setup description exchange
|
||||
this.ready = offer
|
||||
? this._conn
|
||||
.setRemoteDescription(offer)
|
||||
.then(() => this._conn?.createAnswer())
|
||||
.then(async answer => {
|
||||
if (!answer || !this._conn) throw new Error('Connection disappeared')
|
||||
await this._conn.setLocalDescription(answer)
|
||||
return await signaler.setAnswer(answer)
|
||||
})
|
||||
: this._conn.createOffer().then(async offer => {
|
||||
if (!this._conn) throw new Error('Connection disappeared')
|
||||
await this._conn.setLocalDescription(offer)
|
||||
return await signaler.setOffer(offer)
|
||||
})
|
||||
|
||||
// propagate connection state changes
|
||||
this._conn.addEventListener('connectionstatechange', () => {
|
||||
console.log(this.side, 'connection state changed: ', this._conn!.connectionState)
|
||||
const state = isConnectionState(this._conn!.connectionState)
|
||||
? this._conn!.connectionState
|
||||
: 'disconnected'
|
||||
this.setState(state)
|
||||
})
|
||||
|
||||
this._conn.addEventListener('iceconnectionstatechange', () => {
|
||||
console.log(this.side, 'ice connection state changed: ', this._conn!.iceConnectionState)
|
||||
})
|
||||
|
||||
// start ICE candidate exchange when gathering begins
|
||||
this._conn.addEventListener('icegatheringstatechange', () => {
|
||||
if (this._conn!.iceGatheringState === 'gathering') {
|
||||
this.startIce()
|
||||
} else if (this._conn!.iceGatheringState === 'complete') {
|
||||
this.stopIce()
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Getter method for retrieving the current connection.
|
||||
*
|
||||
* @return {RTCPeerConnection|null} The current connection instance.
|
||||
*/
|
||||
public get connection(): RTCPeerConnection | null {
|
||||
return this._conn
|
||||
}
|
||||
|
||||
/**
|
||||
* Update connection state and emit state-change event
|
||||
*/
|
||||
private setState(state: ConnectionInterface['state']) {
|
||||
this._state = state
|
||||
this.events.emit('state-change', state)
|
||||
}
|
||||
|
||||
/**
|
||||
* Start ICE candidate exchange when gathering begins
|
||||
*/
|
||||
private startIce() {
|
||||
const listener = ({ candidate }: { candidate: RTCIceCandidate | null }) => {
|
||||
if (candidate) this.signaler.addIceCandidate(candidate)
|
||||
}
|
||||
if (!this._conn) throw new Error('Connection disappeared')
|
||||
this._conn.addEventListener('icecandidate', listener)
|
||||
this.iceBin(
|
||||
this.signaler.addListener((candidate: RTCIceCandidate) =>
|
||||
this._conn?.addIceCandidate(candidate)
|
||||
),
|
||||
() => this._conn?.removeEventListener('icecandidate', listener)
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop ICE candidate exchange when gathering completes
|
||||
*/
|
||||
private stopIce() {
|
||||
this.iceBin.clean()
|
||||
}
|
||||
|
||||
/**
|
||||
* Disconnects the current connection and cleans up resources.
|
||||
* Closes the active connection if it exists, resets the connection instance to null,
|
||||
* stops the ICE process, and updates the state to 'disconnected'.
|
||||
*
|
||||
* @return {void} No return value.
|
||||
*/
|
||||
disconnect(): void {
|
||||
this._conn?.close()
|
||||
this._conn = null
|
||||
this.stopIce()
|
||||
this.setState('disconnected')
|
||||
}
|
||||
|
||||
/**
|
||||
* Current connection state
|
||||
*/
|
||||
get state() {
|
||||
return this._state
|
||||
}
|
||||
|
||||
/**
|
||||
* Setup data channel event listeners
|
||||
*/
|
||||
private setupDataChannelListeners(channel: RTCDataChannel): void {
|
||||
channel.addEventListener('message', e => {
|
||||
this.events.emit('message', e.data)
|
||||
})
|
||||
|
||||
channel.addEventListener('open', () => {
|
||||
// Channel opened - flush queued messages
|
||||
this.flushQueue().catch(err => {
|
||||
console.error('Failed to flush message queue:', err)
|
||||
})
|
||||
})
|
||||
|
||||
channel.addEventListener('error', err => {
|
||||
console.error('Data channel error:', err)
|
||||
})
|
||||
|
||||
channel.addEventListener('close', () => {
|
||||
console.log('Data channel closed')
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Flush the message queue
|
||||
*/
|
||||
private async flushQueue(): Promise<void> {
|
||||
while (this.messageQueue.length > 0 && this._state === 'connected') {
|
||||
const item = this.messageQueue.shift()!
|
||||
|
||||
// Check expiration
|
||||
if (item.options.expiresAt && Date.now() > item.options.expiresAt) {
|
||||
continue
|
||||
}
|
||||
|
||||
const success = await this.sendMessage(item.message)
|
||||
if (!success) {
|
||||
// Re-queue on failure
|
||||
this.messageQueue.unshift(item)
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Queue a message for sending when connection is established
|
||||
*
|
||||
* @param message - Message to queue (string or ArrayBuffer)
|
||||
* @param options - Queue options (e.g., expiration time)
|
||||
*/
|
||||
async queueMessage(message: Message, options: QueueMessageOptions = {}): Promise<void> {
|
||||
this.messageQueue.push({
|
||||
message,
|
||||
options,
|
||||
timestamp: Date.now()
|
||||
})
|
||||
|
||||
// Try immediate send if connected
|
||||
if (this._state === 'connected') {
|
||||
await this.flushQueue()
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a message immediately
|
||||
*
|
||||
* @param message - Message to send (string or ArrayBuffer)
|
||||
* @returns Promise resolving to true if sent successfully
|
||||
*/
|
||||
async sendMessage(message: Message): Promise<boolean> {
|
||||
if (this._state !== 'connected' || !this._dataChannel) {
|
||||
return false
|
||||
}
|
||||
|
||||
if (this._dataChannel.readyState !== 'open') {
|
||||
return false
|
||||
}
|
||||
|
||||
try {
|
||||
// TypeScript has trouble with the union type, so we cast to any
|
||||
// Both string and ArrayBuffer are valid for RTCDataChannel.send()
|
||||
this._dataChannel.send(message as any)
|
||||
return true
|
||||
} catch (err) {
|
||||
console.error('Send failed:', err)
|
||||
return false
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,94 +0,0 @@
|
||||
/**
|
||||
* Type-safe EventBus with event name to payload type mapping
|
||||
*/
|
||||
|
||||
type EventHandler<T = any> = (data: T) => void
|
||||
|
||||
/**
|
||||
* EventBus - Type-safe event emitter with inferred event data types
|
||||
*
|
||||
* @example
|
||||
* interface MyEvents {
|
||||
* 'user:connected': { userId: string; timestamp: number };
|
||||
* 'user:disconnected': { userId: string };
|
||||
* 'message:received': string;
|
||||
* }
|
||||
*
|
||||
* const bus = new EventBus<MyEvents>();
|
||||
*
|
||||
* // TypeScript knows data is { userId: string; timestamp: number }
|
||||
* bus.on('user:connected', (data) => {
|
||||
* console.log(data.userId, data.timestamp);
|
||||
* });
|
||||
*
|
||||
* // TypeScript knows data is string
|
||||
* bus.on('message:received', (data) => {
|
||||
* console.log(data.toUpperCase());
|
||||
* });
|
||||
*/
|
||||
export class EventBus<TEvents extends Record<string, any>> {
|
||||
private handlers: Map<keyof TEvents, Set<EventHandler>>
|
||||
|
||||
constructor() {
|
||||
this.handlers = new Map()
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscribe to an event
|
||||
* Returns a cleanup function to unsubscribe
|
||||
*/
|
||||
on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void {
|
||||
if (!this.handlers.has(event)) {
|
||||
this.handlers.set(event, new Set())
|
||||
}
|
||||
this.handlers.get(event)!.add(handler)
|
||||
|
||||
// Return cleanup function
|
||||
return () => this.off(event, handler)
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscribe to an event once (auto-unsubscribe after first call)
|
||||
*/
|
||||
once<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): void {
|
||||
const wrappedHandler = (data: TEvents[K]) => {
|
||||
handler(data)
|
||||
this.off(event, wrappedHandler)
|
||||
}
|
||||
this.on(event, wrappedHandler)
|
||||
}
|
||||
|
||||
/**
|
||||
* Unsubscribe from an event
|
||||
*/
|
||||
off<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): void {
|
||||
const eventHandlers = this.handlers.get(event)
|
||||
if (eventHandlers) {
|
||||
eventHandlers.delete(handler)
|
||||
if (eventHandlers.size === 0) {
|
||||
this.handlers.delete(event)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Emit an event with data
|
||||
*/
|
||||
emit<K extends keyof TEvents>(event: K, data: TEvents[K]): void {
|
||||
const eventHandlers = this.handlers.get(event)
|
||||
if (eventHandlers) {
|
||||
eventHandlers.forEach(handler => handler(data))
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove all handlers for a specific event, or all handlers if no event specified
|
||||
*/
|
||||
clear<K extends keyof TEvents>(event?: K): void {
|
||||
if (event !== undefined) {
|
||||
this.handlers.delete(event)
|
||||
} else {
|
||||
this.handlers.clear()
|
||||
}
|
||||
}
|
||||
}
|
||||
39
src/index.ts
39
src/index.ts
@@ -3,42 +3,37 @@
|
||||
* WebRTC peer signaling client
|
||||
*/
|
||||
|
||||
export { EventBus } from './event-bus.js'
|
||||
export { Rondevu } from './rondevu.js'
|
||||
export { RondevuAPI } from './api.js'
|
||||
export { RondevuService } from './rondevu-service.js'
|
||||
export { RondevuSignaler } from './rondevu-signaler.js'
|
||||
export { WebRTCContext } from './webrtc-context.js'
|
||||
export { RTCDurableConnection } from './durable-connection'
|
||||
export { ServiceHost } from './service-host.js'
|
||||
export { ServiceClient } from './service-client.js'
|
||||
export { createBin } from './bin.js'
|
||||
export { RpcBatcher } from './rpc-batcher.js'
|
||||
|
||||
// Export crypto adapters
|
||||
export { WebCryptoAdapter } from './web-crypto-adapter.js'
|
||||
export { NodeCryptoAdapter } from './node-crypto-adapter.js'
|
||||
|
||||
// Export types
|
||||
export type {
|
||||
ConnectionInterface,
|
||||
QueueMessageOptions,
|
||||
Message,
|
||||
ConnectionEvents,
|
||||
Signaler,
|
||||
Binnable,
|
||||
} from './types.js'
|
||||
|
||||
export type {
|
||||
Credentials,
|
||||
Keypair,
|
||||
OfferRequest,
|
||||
Offer,
|
||||
ServiceRequest,
|
||||
Service,
|
||||
ServiceOffer,
|
||||
IceCandidate,
|
||||
} from './api.js'
|
||||
|
||||
export type { Binnable } from './bin.js'
|
||||
export type {
|
||||
RondevuOptions,
|
||||
PublishServiceOptions,
|
||||
ConnectToServiceOptions,
|
||||
ConnectionContext,
|
||||
OfferContext,
|
||||
OfferFactory
|
||||
} from './rondevu.js'
|
||||
|
||||
export type { RondevuServiceOptions, PublishServiceOptions } from './rondevu-service.js'
|
||||
|
||||
export type { ServiceHostOptions, ServiceHostEvents } from './service-host.js'
|
||||
|
||||
export type { ServiceClientOptions, ServiceClientEvents } from './service-client.js'
|
||||
|
||||
export type { PollingConfig } from './rondevu-signaler.js'
|
||||
export type { CryptoAdapter } from './crypto-adapter.js'
|
||||
|
||||
|
||||
98
src/node-crypto-adapter.ts
Normal file
98
src/node-crypto-adapter.ts
Normal file
@@ -0,0 +1,98 @@
|
||||
/**
|
||||
* Node.js Crypto adapter for Node.js environments
|
||||
* Requires Node.js 19+ or Node.js 18 with --experimental-global-webcrypto flag
|
||||
*/
|
||||
|
||||
import * as ed25519 from '@noble/ed25519'
|
||||
import { CryptoAdapter, Keypair } from './crypto-adapter.js'
|
||||
|
||||
/**
|
||||
* Node.js Crypto implementation using Node.js built-in APIs
|
||||
* Uses Buffer for base64 encoding and crypto.randomBytes for random generation
|
||||
*
|
||||
* Requirements:
|
||||
* - Node.js 19+ (crypto.subtle available globally)
|
||||
* - OR Node.js 18 with --experimental-global-webcrypto flag
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { RondevuAPI } from '@xtr-dev/rondevu-client'
|
||||
* import { NodeCryptoAdapter } from '@xtr-dev/rondevu-client/node'
|
||||
*
|
||||
* const api = new RondevuAPI(
|
||||
* 'https://signal.example.com',
|
||||
* 'alice',
|
||||
* keypair,
|
||||
* new NodeCryptoAdapter()
|
||||
* )
|
||||
* ```
|
||||
*/
|
||||
export class NodeCryptoAdapter implements CryptoAdapter {
|
||||
constructor() {
|
||||
// Set SHA-512 hash function for ed25519 using Node's crypto.subtle
|
||||
if (typeof crypto === 'undefined' || !crypto.subtle) {
|
||||
throw new Error(
|
||||
'crypto.subtle is not available. ' +
|
||||
'Node.js 19+ is required, or Node.js 18 with --experimental-global-webcrypto flag'
|
||||
)
|
||||
}
|
||||
|
||||
ed25519.hashes.sha512Async = async (message: Uint8Array) => {
|
||||
const hash = await crypto.subtle.digest('SHA-512', message as BufferSource)
|
||||
return new Uint8Array(hash)
|
||||
}
|
||||
}
|
||||
|
||||
async generateKeypair(): Promise<Keypair> {
|
||||
const privateKey = ed25519.utils.randomSecretKey()
|
||||
const publicKey = await ed25519.getPublicKeyAsync(privateKey)
|
||||
|
||||
return {
|
||||
publicKey: this.bytesToBase64(publicKey),
|
||||
privateKey: this.bytesToBase64(privateKey),
|
||||
}
|
||||
}
|
||||
|
||||
async signMessage(message: string, privateKeyBase64: string): Promise<string> {
|
||||
const privateKey = this.base64ToBytes(privateKeyBase64)
|
||||
const encoder = new TextEncoder()
|
||||
const messageBytes = encoder.encode(message)
|
||||
const signature = await ed25519.signAsync(messageBytes, privateKey)
|
||||
|
||||
return this.bytesToBase64(signature)
|
||||
}
|
||||
|
||||
async verifySignature(
|
||||
message: string,
|
||||
signatureBase64: string,
|
||||
publicKeyBase64: string
|
||||
): Promise<boolean> {
|
||||
try {
|
||||
const signature = this.base64ToBytes(signatureBase64)
|
||||
const publicKey = this.base64ToBytes(publicKeyBase64)
|
||||
const encoder = new TextEncoder()
|
||||
const messageBytes = encoder.encode(message)
|
||||
|
||||
return await ed25519.verifyAsync(signature, messageBytes, publicKey)
|
||||
} catch {
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
bytesToBase64(bytes: Uint8Array): string {
|
||||
// Node.js Buffer provides native base64 encoding
|
||||
// @ts-expect-error - Buffer is available in Node.js but not in browser TypeScript definitions
|
||||
return Buffer.from(bytes).toString('base64')
|
||||
}
|
||||
|
||||
base64ToBytes(base64: string): Uint8Array {
|
||||
// Node.js Buffer provides native base64 decoding
|
||||
// @ts-expect-error - Buffer is available in Node.js but not in browser TypeScript definitions
|
||||
return new Uint8Array(Buffer.from(base64, 'base64'))
|
||||
}
|
||||
|
||||
randomBytes(length: number): Uint8Array {
|
||||
// Use Web Crypto API's getRandomValues (available in Node 19+)
|
||||
return crypto.getRandomValues(new Uint8Array(length))
|
||||
}
|
||||
}
|
||||
@@ -1,175 +0,0 @@
|
||||
import { RondevuAPI, Credentials, Keypair, Service, ServiceRequest } from './api.js'
|
||||
|
||||
export interface RondevuServiceOptions {
|
||||
apiUrl: string
|
||||
username: string
|
||||
keypair?: Keypair
|
||||
credentials?: Credentials
|
||||
}
|
||||
|
||||
export interface PublishServiceOptions {
|
||||
serviceFqn: string
|
||||
offers: Array<{ sdp: string }>
|
||||
ttl?: number
|
||||
isPublic?: boolean
|
||||
metadata?: Record<string, any>
|
||||
}
|
||||
|
||||
/**
|
||||
* RondevuService - High-level service management with automatic signature handling
|
||||
*
|
||||
* Provides a simplified API for:
|
||||
* - Username claiming with Ed25519 signatures
|
||||
* - Service publishing with automatic signature generation
|
||||
* - Keypair management
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Initialize service (generates keypair automatically)
|
||||
* const service = new RondevuService({
|
||||
* apiUrl: 'https://signal.example.com',
|
||||
* username: 'myusername',
|
||||
* })
|
||||
*
|
||||
* await service.initialize()
|
||||
*
|
||||
* // Claim username (one time)
|
||||
* await service.claimUsername()
|
||||
*
|
||||
* // Publish a service
|
||||
* const publishedService = await service.publishService({
|
||||
* serviceFqn: 'chat.app@1.0.0',
|
||||
* offers: [{ sdp: offerSdp }],
|
||||
* ttl: 300000,
|
||||
* isPublic: true,
|
||||
* })
|
||||
* ```
|
||||
*/
|
||||
export class RondevuService {
|
||||
private readonly api: RondevuAPI
|
||||
private readonly username: string
|
||||
private keypair: Keypair | null = null
|
||||
private usernameClaimed = false
|
||||
|
||||
constructor(options: RondevuServiceOptions) {
|
||||
this.username = options.username
|
||||
this.keypair = options.keypair || null
|
||||
this.api = new RondevuAPI(options.apiUrl, options.credentials)
|
||||
}
|
||||
|
||||
/**
|
||||
* Initialize the service - generates keypair if not provided
|
||||
* Call this before using other methods
|
||||
*/
|
||||
async initialize(): Promise<void> {
|
||||
if (!this.keypair) {
|
||||
this.keypair = await RondevuAPI.generateKeypair()
|
||||
}
|
||||
|
||||
// Register with API if no credentials provided
|
||||
if (!this.api['credentials']) {
|
||||
const credentials = await this.api.register()
|
||||
this.api.setCredentials(credentials)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Claim the username with Ed25519 signature
|
||||
* Should be called once before publishing services
|
||||
*/
|
||||
async claimUsername(): Promise<void> {
|
||||
if (!this.keypair) {
|
||||
throw new Error('Service not initialized. Call initialize() first.')
|
||||
}
|
||||
|
||||
// Check if username is already claimed
|
||||
const check = await this.api.checkUsername(this.username)
|
||||
if (!check.available) {
|
||||
// Verify it's claimed by us
|
||||
if (check.owner === this.keypair.publicKey) {
|
||||
this.usernameClaimed = true
|
||||
return
|
||||
}
|
||||
throw new Error(`Username "${this.username}" is already claimed by another user`)
|
||||
}
|
||||
|
||||
// Generate signature for username claim
|
||||
const message = `claim:${this.username}:${Date.now()}`
|
||||
const signature = await RondevuAPI.signMessage(message, this.keypair.privateKey)
|
||||
|
||||
// Claim the username
|
||||
await this.api.claimUsername(this.username, this.keypair.publicKey, signature, message)
|
||||
this.usernameClaimed = true
|
||||
}
|
||||
|
||||
/**
|
||||
* Publish a service with automatic signature generation
|
||||
*/
|
||||
async publishService(options: PublishServiceOptions): Promise<Service> {
|
||||
if (!this.keypair) {
|
||||
throw new Error('Service not initialized. Call initialize() first.')
|
||||
}
|
||||
|
||||
if (!this.usernameClaimed) {
|
||||
throw new Error(
|
||||
'Username not claimed. Call claimUsername() first or the server will reject the service.'
|
||||
)
|
||||
}
|
||||
|
||||
const { serviceFqn, offers, ttl, isPublic, metadata } = options
|
||||
|
||||
// Generate signature for service publication
|
||||
const message = `publish:${this.username}:${serviceFqn}:${Date.now()}`
|
||||
const signature = await RondevuAPI.signMessage(message, this.keypair.privateKey)
|
||||
|
||||
// Create service request
|
||||
const serviceRequest: ServiceRequest = {
|
||||
username: this.username,
|
||||
serviceFqn,
|
||||
offers,
|
||||
signature,
|
||||
message,
|
||||
ttl,
|
||||
isPublic,
|
||||
metadata,
|
||||
}
|
||||
|
||||
// Publish to server
|
||||
return await this.api.publishService(serviceRequest)
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current keypair (for backup/storage)
|
||||
*/
|
||||
getKeypair(): Keypair | null {
|
||||
return this.keypair
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the username
|
||||
*/
|
||||
getUsername(): string {
|
||||
return this.username
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the public key
|
||||
*/
|
||||
getPublicKey(): string | null {
|
||||
return this.keypair?.publicKey || null
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if username has been claimed
|
||||
*/
|
||||
isUsernameClaimed(): boolean {
|
||||
return this.usernameClaimed
|
||||
}
|
||||
|
||||
/**
|
||||
* Access to underlying API for advanced operations
|
||||
*/
|
||||
getAPI(): RondevuAPI {
|
||||
return this.api
|
||||
}
|
||||
}
|
||||
@@ -1,462 +0,0 @@
|
||||
import { Signaler } from './types.js'
|
||||
import { RondevuService } from './rondevu-service.js'
|
||||
import { Binnable } from './bin.js'
|
||||
|
||||
export interface PollingConfig {
|
||||
initialInterval?: number // Default: 500ms
|
||||
maxInterval?: number // Default: 5000ms
|
||||
backoffMultiplier?: number // Default: 1.5
|
||||
maxRetries?: number // Default: 50 (50 seconds max)
|
||||
jitter?: boolean // Default: true
|
||||
}
|
||||
|
||||
/**
|
||||
* RondevuSignaler - Handles WebRTC signaling via Rondevu service
|
||||
*
|
||||
* Manages offer/answer exchange and ICE candidate polling for establishing
|
||||
* WebRTC connections through the Rondevu signaling server.
|
||||
*
|
||||
* Supports configurable polling with exponential backoff and jitter to reduce
|
||||
* server load and prevent thundering herd issues.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const signaler = new RondevuSignaler(
|
||||
* rondevuService,
|
||||
* 'chat.app@1.0.0',
|
||||
* 'peer-username',
|
||||
* { initialInterval: 500, maxInterval: 5000, jitter: true }
|
||||
* )
|
||||
*
|
||||
* // For offerer:
|
||||
* await signaler.setOffer(offer)
|
||||
* signaler.addAnswerListener(answer => {
|
||||
* // Handle remote answer
|
||||
* })
|
||||
*
|
||||
* // For answerer:
|
||||
* signaler.addOfferListener(offer => {
|
||||
* // Handle remote offer
|
||||
* })
|
||||
* await signaler.setAnswer(answer)
|
||||
* ```
|
||||
*/
|
||||
export class RondevuSignaler implements Signaler {
|
||||
private offerId: string | null = null
|
||||
private serviceUuid: string | null = null
|
||||
private offerListeners: Array<(offer: RTCSessionDescriptionInit) => void> = []
|
||||
private answerListeners: Array<(answer: RTCSessionDescriptionInit) => void> = []
|
||||
private iceListeners: Array<(candidate: RTCIceCandidate) => void> = []
|
||||
private answerPollingTimeout: ReturnType<typeof setTimeout> | null = null
|
||||
private icePollingTimeout: ReturnType<typeof setTimeout> | null = null
|
||||
private lastIceTimestamp = 0
|
||||
private isPolling = false
|
||||
private pollingConfig: Required<PollingConfig>
|
||||
|
||||
constructor(
|
||||
private readonly rondevu: RondevuService,
|
||||
private readonly service: string,
|
||||
private readonly host?: string,
|
||||
pollingConfig?: PollingConfig
|
||||
) {
|
||||
this.pollingConfig = {
|
||||
initialInterval: pollingConfig?.initialInterval ?? 500,
|
||||
maxInterval: pollingConfig?.maxInterval ?? 5000,
|
||||
backoffMultiplier: pollingConfig?.backoffMultiplier ?? 1.5,
|
||||
maxRetries: pollingConfig?.maxRetries ?? 50,
|
||||
jitter: pollingConfig?.jitter ?? true
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Publish an offer as a service
|
||||
* Used by the offerer to make their offer available
|
||||
*/
|
||||
async setOffer(offer: RTCSessionDescriptionInit): Promise<void> {
|
||||
if (!offer.sdp) {
|
||||
throw new Error('Offer SDP is required')
|
||||
}
|
||||
|
||||
// Publish service with the offer SDP
|
||||
const publishedService = await this.rondevu.publishService({
|
||||
serviceFqn: this.service,
|
||||
offers: [{ sdp: offer.sdp }],
|
||||
ttl: 300000, // 5 minutes
|
||||
isPublic: true,
|
||||
})
|
||||
|
||||
// Get the first offer from the published service
|
||||
if (!publishedService.offers || publishedService.offers.length === 0) {
|
||||
throw new Error('No offers returned from service publication')
|
||||
}
|
||||
|
||||
this.offerId = publishedService.offers[0].offerId
|
||||
this.serviceUuid = publishedService.uuid
|
||||
|
||||
// Start polling for answer
|
||||
this.startAnswerPolling()
|
||||
|
||||
// Start polling for ICE candidates
|
||||
this.startIcePolling()
|
||||
}
|
||||
|
||||
/**
|
||||
* Send an answer to the offerer
|
||||
* Used by the answerer to respond to an offer
|
||||
*/
|
||||
async setAnswer(answer: RTCSessionDescriptionInit): Promise<void> {
|
||||
if (!answer.sdp) {
|
||||
throw new Error('Answer SDP is required')
|
||||
}
|
||||
|
||||
if (!this.serviceUuid) {
|
||||
throw new Error('No service UUID available. Must receive offer first.')
|
||||
}
|
||||
|
||||
// Send answer to the service
|
||||
const result = await this.rondevu.getAPI().answerService(this.serviceUuid, answer.sdp)
|
||||
this.offerId = result.offerId
|
||||
|
||||
// Start polling for ICE candidates
|
||||
this.startIcePolling()
|
||||
}
|
||||
|
||||
/**
|
||||
* Listen for incoming offers
|
||||
* Used by the answerer to receive offers from the offerer
|
||||
*/
|
||||
addOfferListener(callback: (offer: RTCSessionDescriptionInit) => void): Binnable {
|
||||
this.offerListeners.push(callback)
|
||||
|
||||
// If we have a host, start searching for their service
|
||||
if (this.host && !this.isPolling) {
|
||||
this.searchForOffer()
|
||||
}
|
||||
|
||||
// Return cleanup function
|
||||
return () => {
|
||||
const index = this.offerListeners.indexOf(callback)
|
||||
if (index > -1) {
|
||||
this.offerListeners.splice(index, 1)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Listen for incoming answers
|
||||
* Used by the offerer to receive the answer from the answerer
|
||||
*/
|
||||
addAnswerListener(callback: (answer: RTCSessionDescriptionInit) => void): Binnable {
|
||||
this.answerListeners.push(callback)
|
||||
|
||||
// Return cleanup function
|
||||
return () => {
|
||||
const index = this.answerListeners.indexOf(callback)
|
||||
if (index > -1) {
|
||||
this.answerListeners.splice(index, 1)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Send an ICE candidate to the remote peer
|
||||
*/
|
||||
async addIceCandidate(candidate: RTCIceCandidate): Promise<void> {
|
||||
if (!this.serviceUuid) {
|
||||
console.warn('Cannot send ICE candidate: no service UUID')
|
||||
return
|
||||
}
|
||||
|
||||
const candidateData = candidate.toJSON()
|
||||
|
||||
// Skip empty candidates
|
||||
if (!candidateData.candidate || candidateData.candidate === '') {
|
||||
return
|
||||
}
|
||||
|
||||
try {
|
||||
const result = await this.rondevu.getAPI().addServiceIceCandidates(
|
||||
this.serviceUuid,
|
||||
[candidateData],
|
||||
this.offerId || undefined
|
||||
)
|
||||
// Store offerId if we didn't have it yet
|
||||
if (!this.offerId) {
|
||||
this.offerId = result.offerId
|
||||
}
|
||||
} catch (err) {
|
||||
console.error('Failed to send ICE candidate:', err)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Listen for ICE candidates from the remote peer
|
||||
*/
|
||||
addListener(callback: (candidate: RTCIceCandidate) => void): Binnable {
|
||||
this.iceListeners.push(callback)
|
||||
|
||||
// Return cleanup function
|
||||
return () => {
|
||||
const index = this.iceListeners.indexOf(callback)
|
||||
if (index > -1) {
|
||||
this.iceListeners.splice(index, 1)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Search for an offer from the host
|
||||
* Used by the answerer to find the offerer's service
|
||||
*/
|
||||
private async searchForOffer(): Promise<void> {
|
||||
if (!this.host) {
|
||||
throw new Error('No host specified for offer search')
|
||||
}
|
||||
|
||||
this.isPolling = true
|
||||
|
||||
try {
|
||||
// Search for services by username and service FQN
|
||||
const services = await this.rondevu.getAPI().searchServices(this.host, this.service)
|
||||
|
||||
if (services.length === 0) {
|
||||
console.warn(`No services found for ${this.host}/${this.service}`)
|
||||
this.isPolling = false
|
||||
return
|
||||
}
|
||||
|
||||
// Get the first available service (already has full details from searchServices)
|
||||
const service = services[0] as any
|
||||
|
||||
// Get the first available offer from the service
|
||||
if (!service.offers || service.offers.length === 0) {
|
||||
console.warn(`No offers available for service ${this.host}/${this.service}`)
|
||||
this.isPolling = false
|
||||
return
|
||||
}
|
||||
|
||||
const firstOffer = service.offers[0]
|
||||
this.offerId = firstOffer.offerId
|
||||
this.serviceUuid = service.uuid
|
||||
|
||||
// Notify offer listeners
|
||||
const offer: RTCSessionDescriptionInit = {
|
||||
type: 'offer',
|
||||
sdp: firstOffer.sdp,
|
||||
}
|
||||
|
||||
this.offerListeners.forEach(listener => {
|
||||
try {
|
||||
listener(offer)
|
||||
} catch (err) {
|
||||
console.error('Offer listener error:', err)
|
||||
}
|
||||
})
|
||||
} catch (err) {
|
||||
console.error('Failed to search for offer:', err)
|
||||
this.isPolling = false
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Start polling for answer (offerer side) with exponential backoff
|
||||
*/
|
||||
private startAnswerPolling(): void {
|
||||
if (this.answerPollingTimeout || !this.serviceUuid) {
|
||||
return
|
||||
}
|
||||
|
||||
let interval = this.pollingConfig.initialInterval
|
||||
let retries = 0
|
||||
|
||||
const poll = async () => {
|
||||
if (!this.serviceUuid) {
|
||||
this.stopAnswerPolling()
|
||||
return
|
||||
}
|
||||
|
||||
try {
|
||||
const answer = await this.rondevu.getAPI().getServiceAnswer(this.serviceUuid)
|
||||
|
||||
if (answer && answer.sdp) {
|
||||
// Store offerId if we didn't have it yet
|
||||
if (!this.offerId) {
|
||||
this.offerId = answer.offerId
|
||||
}
|
||||
|
||||
// Got answer - notify listeners and stop polling
|
||||
const answerDesc: RTCSessionDescriptionInit = {
|
||||
type: 'answer',
|
||||
sdp: answer.sdp,
|
||||
}
|
||||
|
||||
this.answerListeners.forEach(listener => {
|
||||
try {
|
||||
listener(answerDesc)
|
||||
} catch (err) {
|
||||
console.error('Answer listener error:', err)
|
||||
}
|
||||
})
|
||||
|
||||
// Stop polling once we get the answer
|
||||
this.stopAnswerPolling()
|
||||
return
|
||||
}
|
||||
|
||||
// No answer yet - exponential backoff
|
||||
retries++
|
||||
if (retries > this.pollingConfig.maxRetries) {
|
||||
console.warn('Max retries reached for answer polling')
|
||||
this.stopAnswerPolling()
|
||||
return
|
||||
}
|
||||
|
||||
interval = Math.min(
|
||||
interval * this.pollingConfig.backoffMultiplier,
|
||||
this.pollingConfig.maxInterval
|
||||
)
|
||||
|
||||
// Add jitter to prevent thundering herd
|
||||
const finalInterval = this.pollingConfig.jitter
|
||||
? interval + Math.random() * 100
|
||||
: interval
|
||||
|
||||
this.answerPollingTimeout = setTimeout(poll, finalInterval)
|
||||
|
||||
} catch (err) {
|
||||
// 404 is expected when answer isn't available yet
|
||||
if (err instanceof Error && !err.message?.includes('404')) {
|
||||
console.error('Error polling for answer:', err)
|
||||
}
|
||||
|
||||
// Retry with backoff
|
||||
const finalInterval = this.pollingConfig.jitter
|
||||
? interval + Math.random() * 100
|
||||
: interval
|
||||
this.answerPollingTimeout = setTimeout(poll, finalInterval)
|
||||
}
|
||||
}
|
||||
|
||||
poll() // Start immediately
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop polling for answer
|
||||
*/
|
||||
private stopAnswerPolling(): void {
|
||||
if (this.answerPollingTimeout) {
|
||||
clearTimeout(this.answerPollingTimeout)
|
||||
this.answerPollingTimeout = null
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Start polling for ICE candidates with adaptive backoff
|
||||
*/
|
||||
private startIcePolling(): void {
|
||||
if (this.icePollingTimeout || !this.serviceUuid) {
|
||||
return
|
||||
}
|
||||
|
||||
let interval = this.pollingConfig.initialInterval
|
||||
|
||||
const poll = async () => {
|
||||
if (!this.serviceUuid) {
|
||||
this.stopIcePolling()
|
||||
return
|
||||
}
|
||||
|
||||
try {
|
||||
const result = await this.rondevu
|
||||
.getAPI()
|
||||
.getServiceIceCandidates(this.serviceUuid, this.lastIceTimestamp, this.offerId || undefined)
|
||||
|
||||
// Store offerId if we didn't have it yet
|
||||
if (!this.offerId) {
|
||||
this.offerId = result.offerId
|
||||
}
|
||||
|
||||
let foundCandidates = false
|
||||
|
||||
for (const item of result.candidates) {
|
||||
if (item.candidate && item.candidate.candidate && item.candidate.candidate !== '') {
|
||||
foundCandidates = true
|
||||
try {
|
||||
const rtcCandidate = new RTCIceCandidate(item.candidate)
|
||||
|
||||
this.iceListeners.forEach(listener => {
|
||||
try {
|
||||
listener(rtcCandidate)
|
||||
} catch (err) {
|
||||
console.error('ICE listener error:', err)
|
||||
}
|
||||
})
|
||||
|
||||
this.lastIceTimestamp = item.createdAt
|
||||
} catch (err) {
|
||||
console.warn('Failed to process ICE candidate:', err)
|
||||
this.lastIceTimestamp = item.createdAt
|
||||
}
|
||||
} else {
|
||||
this.lastIceTimestamp = item.createdAt
|
||||
}
|
||||
}
|
||||
|
||||
// If candidates found, reset interval to initial value
|
||||
// Otherwise, increase interval with backoff
|
||||
if (foundCandidates) {
|
||||
interval = this.pollingConfig.initialInterval
|
||||
} else {
|
||||
interval = Math.min(
|
||||
interval * this.pollingConfig.backoffMultiplier,
|
||||
this.pollingConfig.maxInterval
|
||||
)
|
||||
}
|
||||
|
||||
// Add jitter
|
||||
const finalInterval = this.pollingConfig.jitter
|
||||
? interval + Math.random() * 100
|
||||
: interval
|
||||
|
||||
this.icePollingTimeout = setTimeout(poll, finalInterval)
|
||||
|
||||
} catch (err) {
|
||||
// 404/410 means offer expired, stop polling
|
||||
if (err instanceof Error && (err.message?.includes('404') || err.message?.includes('410'))) {
|
||||
console.warn('Offer not found or expired, stopping ICE polling')
|
||||
this.stopIcePolling()
|
||||
} else if (err instanceof Error && !err.message?.includes('404')) {
|
||||
console.error('Error polling for ICE candidates:', err)
|
||||
// Continue polling despite errors
|
||||
const finalInterval = this.pollingConfig.jitter
|
||||
? interval + Math.random() * 100
|
||||
: interval
|
||||
this.icePollingTimeout = setTimeout(poll, finalInterval)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
poll() // Start immediately
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop polling for ICE candidates
|
||||
*/
|
||||
private stopIcePolling(): void {
|
||||
if (this.icePollingTimeout) {
|
||||
clearTimeout(this.icePollingTimeout)
|
||||
this.icePollingTimeout = null
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop all polling and cleanup
|
||||
*/
|
||||
dispose(): void {
|
||||
this.stopAnswerPolling()
|
||||
this.stopIcePolling()
|
||||
this.offerListeners = []
|
||||
this.answerListeners = []
|
||||
this.iceListeners = []
|
||||
}
|
||||
}
|
||||
888
src/rondevu.ts
Normal file
888
src/rondevu.ts
Normal file
@@ -0,0 +1,888 @@
|
||||
import { RondevuAPI, Keypair, IceCandidate, BatcherOptions } from './api.js'
|
||||
import { CryptoAdapter } from './crypto-adapter.js'
|
||||
|
||||
// ICE server preset names
|
||||
export type IceServerPreset = 'ipv4-turn' | 'hostname-turns' | 'google-stun' | 'relay-only'
|
||||
|
||||
// ICE server presets
|
||||
export const ICE_SERVER_PRESETS: Record<IceServerPreset, RTCIceServer[]> = {
|
||||
'ipv4-turn': [
|
||||
{ urls: 'stun:57.129.61.67:3478' },
|
||||
{
|
||||
urls: [
|
||||
'turn:57.129.61.67:3478?transport=tcp',
|
||||
'turn:57.129.61.67:3478?transport=udp',
|
||||
],
|
||||
username: 'webrtcuser',
|
||||
credential: 'supersecretpassword'
|
||||
}
|
||||
],
|
||||
'hostname-turns': [
|
||||
{ urls: 'stun:turn.share.fish:3478' },
|
||||
{
|
||||
urls: [
|
||||
'turns:turn.share.fish:5349?transport=tcp',
|
||||
'turns:turn.share.fish:5349?transport=udp',
|
||||
'turn:turn.share.fish:3478?transport=tcp',
|
||||
'turn:turn.share.fish:3478?transport=udp',
|
||||
],
|
||||
username: 'webrtcuser',
|
||||
credential: 'supersecretpassword'
|
||||
}
|
||||
],
|
||||
'google-stun': [
|
||||
{ urls: 'stun:stun.l.google.com:19302' },
|
||||
{ urls: 'stun:stun1.l.google.com:19302' }
|
||||
],
|
||||
'relay-only': [
|
||||
{ urls: 'stun:57.129.61.67:3478' },
|
||||
{
|
||||
urls: [
|
||||
'turn:57.129.61.67:3478?transport=tcp',
|
||||
'turn:57.129.61.67:3478?transport=udp',
|
||||
],
|
||||
username: 'webrtcuser',
|
||||
credential: 'supersecretpassword',
|
||||
// @ts-expect-error - iceTransportPolicy is valid but not in RTCIceServer type
|
||||
iceTransportPolicy: 'relay'
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
export interface RondevuOptions {
|
||||
apiUrl: string
|
||||
username?: string // Optional, will generate anonymous if not provided
|
||||
keypair?: Keypair // Optional, will generate if not provided
|
||||
cryptoAdapter?: CryptoAdapter // Optional, defaults to WebCryptoAdapter
|
||||
batching?: BatcherOptions | false // Optional, defaults to enabled with default options
|
||||
iceServers?: IceServerPreset | RTCIceServer[] // Optional: preset name or custom STUN/TURN servers
|
||||
debug?: boolean // Optional: enable debug logging (default: false)
|
||||
}
|
||||
|
||||
export interface OfferContext {
|
||||
pc: RTCPeerConnection
|
||||
dc?: RTCDataChannel
|
||||
offer: RTCSessionDescriptionInit
|
||||
}
|
||||
|
||||
export type OfferFactory = (rtcConfig: RTCConfiguration) => Promise<OfferContext>
|
||||
|
||||
export interface PublishServiceOptions {
|
||||
service: string // Service name and version (e.g., "chat:2.0.0") - username will be auto-appended
|
||||
maxOffers: number // Maximum number of concurrent offers to maintain
|
||||
offerFactory?: OfferFactory // Optional: custom offer creation (defaults to simple data channel)
|
||||
ttl?: number // Time-to-live for offers in milliseconds (default: 300000)
|
||||
}
|
||||
|
||||
export interface ConnectionContext {
|
||||
pc: RTCPeerConnection
|
||||
dc: RTCDataChannel
|
||||
serviceFqn: string
|
||||
offerId: string
|
||||
peerUsername: string
|
||||
}
|
||||
|
||||
export interface ConnectToServiceOptions {
|
||||
serviceFqn?: string // Full FQN like 'chat:2.0.0@alice'
|
||||
service?: string // Service without username (for discovery)
|
||||
username?: string // Target username (combined with service)
|
||||
onConnection?: (context: ConnectionContext) => void | Promise<void> // Called when data channel opens
|
||||
rtcConfig?: RTCConfiguration // Optional: override default ICE servers
|
||||
}
|
||||
|
||||
interface ActiveOffer {
|
||||
offerId: string
|
||||
serviceFqn: string
|
||||
pc: RTCPeerConnection
|
||||
dc?: RTCDataChannel
|
||||
answered: boolean
|
||||
createdAt: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Rondevu - Complete WebRTC signaling client
|
||||
*
|
||||
* Provides a unified API for:
|
||||
* - Implicit username claiming (auto-claimed on first authenticated request)
|
||||
* - Service publishing with automatic signature generation
|
||||
* - Service discovery (direct, random, paginated)
|
||||
* - WebRTC signaling (offer/answer exchange, ICE relay)
|
||||
* - Keypair management
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Create and initialize Rondevu instance with preset ICE servers
|
||||
* const rondevu = await Rondevu.connect({
|
||||
* apiUrl: 'https://signal.example.com',
|
||||
* username: 'alice',
|
||||
* iceServers: 'ipv4-turn' // Use preset: 'ipv4-turn', 'hostname-turns', 'google-stun', or 'relay-only'
|
||||
* })
|
||||
*
|
||||
* // Or use custom ICE servers
|
||||
* const rondevu2 = await Rondevu.connect({
|
||||
* apiUrl: 'https://signal.example.com',
|
||||
* username: 'bob',
|
||||
* iceServers: [
|
||||
* { urls: 'stun:stun.l.google.com:19302' },
|
||||
* { urls: 'turn:turn.example.com:3478', username: 'user', credential: 'pass' }
|
||||
* ]
|
||||
* })
|
||||
*
|
||||
* // Publish a service with automatic offer management
|
||||
* await rondevu.publishService({
|
||||
* service: 'chat:2.0.0',
|
||||
* maxOffers: 5, // Maintain up to 5 concurrent offers
|
||||
* offerFactory: async (rtcConfig) => {
|
||||
* const pc = new RTCPeerConnection(rtcConfig)
|
||||
* const dc = pc.createDataChannel('chat')
|
||||
* const offer = await pc.createOffer()
|
||||
* await pc.setLocalDescription(offer)
|
||||
* return { pc, dc, offer }
|
||||
* }
|
||||
* })
|
||||
*
|
||||
* // Start accepting connections (auto-fills offers and polls)
|
||||
* await rondevu.startFilling()
|
||||
*
|
||||
* // Access active connections
|
||||
* for (const offer of rondevu.getActiveOffers()) {
|
||||
* offer.dc?.addEventListener('message', (e) => console.log(e.data))
|
||||
* }
|
||||
*
|
||||
* // Stop when done
|
||||
* rondevu.stopFilling()
|
||||
* ```
|
||||
*/
|
||||
export class Rondevu {
|
||||
// Constants
|
||||
private static readonly DEFAULT_TTL_MS = 300000 // 5 minutes
|
||||
private static readonly POLLING_INTERVAL_MS = 1000 // 1 second
|
||||
|
||||
private api: RondevuAPI
|
||||
private readonly apiUrl: string
|
||||
private username: string
|
||||
private keypair: Keypair
|
||||
private usernameClaimed = false
|
||||
private cryptoAdapter?: CryptoAdapter
|
||||
private batchingOptions?: BatcherOptions | false
|
||||
private iceServers: RTCIceServer[]
|
||||
private debugEnabled: boolean
|
||||
|
||||
// Service management
|
||||
private currentService: string | null = null
|
||||
private maxOffers = 0
|
||||
private offerFactory: OfferFactory | null = null
|
||||
private ttl = Rondevu.DEFAULT_TTL_MS
|
||||
private activeOffers = new Map<string, ActiveOffer>()
|
||||
|
||||
// Polling
|
||||
private filling = false
|
||||
private pollingInterval: ReturnType<typeof setInterval> | null = null
|
||||
private lastPollTimestamp = 0
|
||||
|
||||
private constructor(
|
||||
apiUrl: string,
|
||||
username: string,
|
||||
keypair: Keypair,
|
||||
api: RondevuAPI,
|
||||
iceServers: RTCIceServer[],
|
||||
cryptoAdapter?: CryptoAdapter,
|
||||
batchingOptions?: BatcherOptions | false,
|
||||
debugEnabled = false
|
||||
) {
|
||||
this.apiUrl = apiUrl
|
||||
this.username = username
|
||||
this.keypair = keypair
|
||||
this.api = api
|
||||
this.iceServers = iceServers
|
||||
this.cryptoAdapter = cryptoAdapter
|
||||
this.batchingOptions = batchingOptions
|
||||
this.debugEnabled = debugEnabled
|
||||
|
||||
this.debug('Instance created:', {
|
||||
username: this.username,
|
||||
publicKey: this.keypair.publicKey,
|
||||
hasIceServers: iceServers.length > 0,
|
||||
batchingEnabled: batchingOptions !== false
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Internal debug logging - only logs if debug mode is enabled
|
||||
*/
|
||||
private debug(message: string, ...args: any[]): void {
|
||||
if (this.debugEnabled) {
|
||||
console.log(`[Rondevu] ${message}`, ...args)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create and initialize a Rondevu client
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const rondevu = await Rondevu.connect({
|
||||
* apiUrl: 'https://api.ronde.vu',
|
||||
* username: 'alice'
|
||||
* })
|
||||
* ```
|
||||
*/
|
||||
static async connect(options: RondevuOptions): Promise<Rondevu> {
|
||||
const username = options.username || Rondevu.generateAnonymousUsername()
|
||||
|
||||
// Handle preset string or custom array
|
||||
let iceServers: RTCIceServer[]
|
||||
if (typeof options.iceServers === 'string') {
|
||||
iceServers = ICE_SERVER_PRESETS[options.iceServers]
|
||||
} else {
|
||||
iceServers = options.iceServers || [
|
||||
{ urls: 'stun:stun.l.google.com:19302' }
|
||||
]
|
||||
}
|
||||
|
||||
if (options.debug) {
|
||||
console.log('[Rondevu] Connecting:', {
|
||||
username,
|
||||
hasKeypair: !!options.keypair,
|
||||
iceServers: iceServers.length,
|
||||
batchingEnabled: options.batching !== false
|
||||
})
|
||||
}
|
||||
|
||||
// Generate keypair if not provided
|
||||
let keypair = options.keypair
|
||||
if (!keypair) {
|
||||
if (options.debug) console.log('[Rondevu] Generating new keypair...')
|
||||
keypair = await RondevuAPI.generateKeypair(options.cryptoAdapter)
|
||||
if (options.debug) console.log('[Rondevu] Generated keypair, publicKey:', keypair.publicKey)
|
||||
} else {
|
||||
if (options.debug) console.log('[Rondevu] Using existing keypair, publicKey:', keypair.publicKey)
|
||||
}
|
||||
|
||||
// Create API instance
|
||||
const api = new RondevuAPI(
|
||||
options.apiUrl,
|
||||
username,
|
||||
keypair,
|
||||
options.cryptoAdapter,
|
||||
options.batching
|
||||
)
|
||||
if (options.debug) console.log('[Rondevu] Created API instance')
|
||||
|
||||
return new Rondevu(
|
||||
options.apiUrl,
|
||||
username,
|
||||
keypair,
|
||||
api,
|
||||
iceServers,
|
||||
options.cryptoAdapter,
|
||||
options.batching,
|
||||
options.debug || false
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate an anonymous username with timestamp and random component
|
||||
*/
|
||||
private static generateAnonymousUsername(): string {
|
||||
const timestamp = Date.now().toString(36)
|
||||
const random = Array.from(crypto.getRandomValues(new Uint8Array(3)))
|
||||
.map(b => b.toString(16).padStart(2, '0')).join('')
|
||||
return `anon-${timestamp}-${random}`
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// Username Management
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Check if username has been claimed (checks with server)
|
||||
*/
|
||||
async isUsernameClaimed(): Promise<boolean> {
|
||||
try {
|
||||
const claimed = await this.api.isUsernameClaimed()
|
||||
|
||||
// Update internal flag to match server state
|
||||
this.usernameClaimed = claimed
|
||||
|
||||
return claimed
|
||||
} catch (err) {
|
||||
console.error('Failed to check username claim status:', err)
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// Service Publishing
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Default offer factory - creates a simple data channel connection
|
||||
*/
|
||||
private async defaultOfferFactory(rtcConfig: RTCConfiguration): Promise<OfferContext> {
|
||||
const pc = new RTCPeerConnection(rtcConfig)
|
||||
const dc = pc.createDataChannel('default')
|
||||
|
||||
const offer = await pc.createOffer()
|
||||
await pc.setLocalDescription(offer)
|
||||
|
||||
return { pc, dc, offer }
|
||||
}
|
||||
|
||||
/**
|
||||
* Publish a service with automatic offer management
|
||||
* Call startFilling() to begin accepting connections
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* await rondevu.publishService({
|
||||
* service: 'chat:2.0.0',
|
||||
* maxOffers: 5
|
||||
* })
|
||||
* await rondevu.startFilling()
|
||||
* ```
|
||||
*/
|
||||
async publishService(options: PublishServiceOptions): Promise<void> {
|
||||
const { service, maxOffers, offerFactory, ttl } = options
|
||||
|
||||
this.currentService = service
|
||||
this.maxOffers = maxOffers
|
||||
this.offerFactory = offerFactory || this.defaultOfferFactory.bind(this)
|
||||
this.ttl = ttl || Rondevu.DEFAULT_TTL_MS
|
||||
|
||||
this.debug(`Publishing service: ${service} with maxOffers: ${maxOffers}`)
|
||||
this.usernameClaimed = true
|
||||
}
|
||||
|
||||
/**
|
||||
* Set up ICE candidate handler to send candidates to the server
|
||||
*/
|
||||
private setupIceCandidateHandler(
|
||||
pc: RTCPeerConnection,
|
||||
serviceFqn: string,
|
||||
offerId: string
|
||||
): void {
|
||||
pc.onicecandidate = async (event) => {
|
||||
if (event.candidate) {
|
||||
try {
|
||||
await this.api.addOfferIceCandidates(
|
||||
serviceFqn,
|
||||
offerId,
|
||||
[event.candidate.toJSON()]
|
||||
)
|
||||
} catch (err) {
|
||||
console.error('[Rondevu] Failed to send ICE candidate:', err)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a single offer and publish it to the server
|
||||
*/
|
||||
private async createOffer(): Promise<void> {
|
||||
if (!this.currentService || !this.offerFactory) {
|
||||
throw new Error('Service not published. Call publishService() first.')
|
||||
}
|
||||
|
||||
const rtcConfig: RTCConfiguration = {
|
||||
iceServers: this.iceServers
|
||||
}
|
||||
|
||||
this.debug('Creating new offer...')
|
||||
|
||||
// Create the offer using the factory
|
||||
const { pc, dc, offer } = await this.offerFactory(rtcConfig)
|
||||
|
||||
// Auto-append username to service
|
||||
const serviceFqn = `${this.currentService}@${this.username}`
|
||||
|
||||
// Publish to server
|
||||
const result = await this.api.publishService({
|
||||
serviceFqn,
|
||||
offers: [{ sdp: offer.sdp! }],
|
||||
ttl: this.ttl,
|
||||
signature: '',
|
||||
message: '',
|
||||
})
|
||||
|
||||
const offerId = result.offers[0].offerId
|
||||
|
||||
// Store active offer
|
||||
this.activeOffers.set(offerId, {
|
||||
offerId,
|
||||
serviceFqn,
|
||||
pc,
|
||||
dc,
|
||||
answered: false,
|
||||
createdAt: Date.now()
|
||||
})
|
||||
|
||||
this.debug(`Offer created: ${offerId}`)
|
||||
|
||||
// Set up ICE candidate handler
|
||||
this.setupIceCandidateHandler(pc, serviceFqn, offerId)
|
||||
|
||||
// Monitor connection state
|
||||
pc.onconnectionstatechange = () => {
|
||||
this.debug(`Offer ${offerId} connection state: ${pc.connectionState}`)
|
||||
|
||||
if (pc.connectionState === 'failed' || pc.connectionState === 'closed') {
|
||||
this.activeOffers.delete(offerId)
|
||||
this.fillOffers() // Try to replace failed offer
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Fill offers to reach maxOffers count
|
||||
*/
|
||||
private async fillOffers(): Promise<void> {
|
||||
if (!this.filling || !this.currentService) return
|
||||
|
||||
const currentCount = this.activeOffers.size
|
||||
const needed = this.maxOffers - currentCount
|
||||
|
||||
this.debug(`Filling offers: current=${currentCount}, needed=${needed}`)
|
||||
|
||||
for (let i = 0; i < needed; i++) {
|
||||
try {
|
||||
await this.createOffer()
|
||||
} catch (err) {
|
||||
console.error('[Rondevu] Failed to create offer:', err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Poll for answers and ICE candidates (internal use for automatic offer management)
|
||||
*/
|
||||
private async pollInternal(): Promise<void> {
|
||||
if (!this.filling) return
|
||||
|
||||
try {
|
||||
const result = await this.api.poll(this.lastPollTimestamp)
|
||||
|
||||
// Process answers
|
||||
for (const answer of result.answers) {
|
||||
const activeOffer = this.activeOffers.get(answer.offerId)
|
||||
if (activeOffer && !activeOffer.answered) {
|
||||
this.debug(`Received answer for offer ${answer.offerId}`)
|
||||
|
||||
await activeOffer.pc.setRemoteDescription({
|
||||
type: 'answer',
|
||||
sdp: answer.sdp
|
||||
})
|
||||
|
||||
activeOffer.answered = true
|
||||
this.lastPollTimestamp = answer.answeredAt
|
||||
|
||||
// Create replacement offer
|
||||
this.fillOffers()
|
||||
}
|
||||
}
|
||||
|
||||
// Process ICE candidates
|
||||
for (const [offerId, candidates] of Object.entries(result.iceCandidates)) {
|
||||
const activeOffer = this.activeOffers.get(offerId)
|
||||
if (activeOffer) {
|
||||
const answererCandidates = candidates.filter(c => c.role === 'answerer')
|
||||
|
||||
for (const item of answererCandidates) {
|
||||
if (item.candidate) {
|
||||
await activeOffer.pc.addIceCandidate(new RTCIceCandidate(item.candidate))
|
||||
this.lastPollTimestamp = Math.max(this.lastPollTimestamp, item.createdAt)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
console.error('[Rondevu] Polling error:', err)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Start filling offers and polling for answers/ICE
|
||||
* Call this after publishService() to begin accepting connections
|
||||
*/
|
||||
async startFilling(): Promise<void> {
|
||||
if (this.filling) {
|
||||
this.debug('Already filling')
|
||||
return
|
||||
}
|
||||
|
||||
if (!this.currentService) {
|
||||
throw new Error('No service published. Call publishService() first.')
|
||||
}
|
||||
|
||||
this.debug('Starting offer filling and polling')
|
||||
this.filling = true
|
||||
|
||||
// Fill initial offers
|
||||
await this.fillOffers()
|
||||
|
||||
// Start polling
|
||||
this.pollingInterval = setInterval(() => {
|
||||
this.pollInternal()
|
||||
}, Rondevu.POLLING_INTERVAL_MS)
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop filling offers and polling
|
||||
* Closes all active peer connections
|
||||
*/
|
||||
stopFilling(): void {
|
||||
this.debug('Stopping offer filling and polling')
|
||||
this.filling = false
|
||||
|
||||
// Stop polling
|
||||
if (this.pollingInterval) {
|
||||
clearInterval(this.pollingInterval)
|
||||
this.pollingInterval = null
|
||||
}
|
||||
|
||||
// Close all active connections
|
||||
for (const [offerId, offer] of this.activeOffers.entries()) {
|
||||
this.debug(`Closing offer ${offerId}`)
|
||||
offer.dc?.close()
|
||||
offer.pc.close()
|
||||
}
|
||||
|
||||
this.activeOffers.clear()
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the full service FQN from various input options
|
||||
* Supports direct FQN, service+username, or service discovery
|
||||
*/
|
||||
private async resolveServiceFqn(options: ConnectToServiceOptions): Promise<string> {
|
||||
const { serviceFqn, service, username } = options
|
||||
|
||||
if (serviceFqn) {
|
||||
return serviceFqn
|
||||
} else if (service && username) {
|
||||
return `${service}@${username}`
|
||||
} else if (service) {
|
||||
// Discovery mode - get random service
|
||||
this.debug(`Discovering service: ${service}`)
|
||||
const discovered = await this.discoverService(service)
|
||||
return discovered.serviceFqn
|
||||
} else {
|
||||
throw new Error('Either serviceFqn or service must be provided')
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Start polling for remote ICE candidates
|
||||
* Returns the polling interval ID
|
||||
*/
|
||||
private startIcePolling(
|
||||
pc: RTCPeerConnection,
|
||||
serviceFqn: string,
|
||||
offerId: string
|
||||
): ReturnType<typeof setInterval> {
|
||||
let lastIceTimestamp = 0
|
||||
|
||||
return setInterval(async () => {
|
||||
try {
|
||||
const result = await this.api.getOfferIceCandidates(
|
||||
serviceFqn,
|
||||
offerId,
|
||||
lastIceTimestamp
|
||||
)
|
||||
for (const item of result.candidates) {
|
||||
if (item.candidate) {
|
||||
await pc.addIceCandidate(new RTCIceCandidate(item.candidate))
|
||||
lastIceTimestamp = item.createdAt
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
console.error('[Rondevu] Failed to poll ICE candidates:', err)
|
||||
}
|
||||
}, Rondevu.POLLING_INTERVAL_MS)
|
||||
}
|
||||
|
||||
/**
|
||||
* Automatically connect to a service (answerer side)
|
||||
* Handles the entire connection flow: discovery, WebRTC setup, answer exchange, ICE candidates
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Connect to specific user
|
||||
* const connection = await rondevu.connectToService({
|
||||
* serviceFqn: 'chat:2.0.0@alice',
|
||||
* onConnection: ({ dc, peerUsername }) => {
|
||||
* console.log('Connected to', peerUsername)
|
||||
* dc.addEventListener('message', (e) => console.log(e.data))
|
||||
* dc.addEventListener('open', () => dc.send('Hello!'))
|
||||
* }
|
||||
* })
|
||||
*
|
||||
* // Discover random service
|
||||
* const connection = await rondevu.connectToService({
|
||||
* service: 'chat:2.0.0',
|
||||
* onConnection: ({ dc, peerUsername }) => {
|
||||
* console.log('Connected to', peerUsername)
|
||||
* }
|
||||
* })
|
||||
* ```
|
||||
*/
|
||||
async connectToService(options: ConnectToServiceOptions): Promise<ConnectionContext> {
|
||||
const { onConnection, rtcConfig } = options
|
||||
|
||||
// Validate inputs
|
||||
if (options.serviceFqn !== undefined && typeof options.serviceFqn === 'string' && !options.serviceFqn.trim()) {
|
||||
throw new Error('serviceFqn cannot be empty')
|
||||
}
|
||||
if (options.service !== undefined && typeof options.service === 'string' && !options.service.trim()) {
|
||||
throw new Error('service cannot be empty')
|
||||
}
|
||||
if (options.username !== undefined && typeof options.username === 'string' && !options.username.trim()) {
|
||||
throw new Error('username cannot be empty')
|
||||
}
|
||||
|
||||
// Determine the full service FQN
|
||||
const fqn = await this.resolveServiceFqn(options)
|
||||
this.debug(`Connecting to service: ${fqn}`)
|
||||
|
||||
// 1. Get service offer
|
||||
const serviceData = await this.api.getService(fqn)
|
||||
this.debug(`Found service from @${serviceData.username}`)
|
||||
|
||||
// 2. Create RTCPeerConnection
|
||||
const rtcConfiguration = rtcConfig || {
|
||||
iceServers: this.iceServers
|
||||
}
|
||||
const pc = new RTCPeerConnection(rtcConfiguration)
|
||||
|
||||
// 3. Set up data channel handler (answerer receives it from offerer)
|
||||
let dc: RTCDataChannel | null = null
|
||||
const dataChannelPromise = new Promise<RTCDataChannel>((resolve) => {
|
||||
pc.ondatachannel = (event) => {
|
||||
this.debug('Data channel received from offerer')
|
||||
dc = event.channel
|
||||
resolve(dc)
|
||||
}
|
||||
})
|
||||
|
||||
// 4. Set up ICE candidate exchange
|
||||
this.setupIceCandidateHandler(pc, serviceData.serviceFqn, serviceData.offerId)
|
||||
|
||||
// 5. Poll for remote ICE candidates
|
||||
const icePollInterval = this.startIcePolling(pc, serviceData.serviceFqn, serviceData.offerId)
|
||||
|
||||
// 6. Set remote description
|
||||
await pc.setRemoteDescription({
|
||||
type: 'offer',
|
||||
sdp: serviceData.sdp
|
||||
})
|
||||
|
||||
// 7. Create and send answer
|
||||
const answer = await pc.createAnswer()
|
||||
await pc.setLocalDescription(answer)
|
||||
await this.api.answerOffer(
|
||||
serviceData.serviceFqn,
|
||||
serviceData.offerId,
|
||||
answer.sdp!
|
||||
)
|
||||
|
||||
// 8. Wait for data channel to be established
|
||||
dc = await dataChannelPromise
|
||||
|
||||
// Create connection context
|
||||
const context: ConnectionContext = {
|
||||
pc,
|
||||
dc,
|
||||
serviceFqn: serviceData.serviceFqn,
|
||||
offerId: serviceData.offerId,
|
||||
peerUsername: serviceData.username
|
||||
}
|
||||
|
||||
// 9. Set up connection state monitoring
|
||||
pc.onconnectionstatechange = () => {
|
||||
this.debug(`Connection state: ${pc.connectionState}`)
|
||||
if (pc.connectionState === 'failed' || pc.connectionState === 'closed') {
|
||||
clearInterval(icePollInterval)
|
||||
}
|
||||
}
|
||||
|
||||
// 10. Wait for data channel to open and call onConnection
|
||||
if (dc.readyState === 'open') {
|
||||
this.debug('Data channel already open')
|
||||
if (onConnection) {
|
||||
await onConnection(context)
|
||||
}
|
||||
} else {
|
||||
await new Promise<void>((resolve) => {
|
||||
dc!.addEventListener('open', async () => {
|
||||
this.debug('Data channel opened')
|
||||
if (onConnection) {
|
||||
await onConnection(context)
|
||||
}
|
||||
resolve()
|
||||
})
|
||||
})
|
||||
}
|
||||
|
||||
return context
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// Service Discovery
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Get service by FQN (with username) - Direct lookup
|
||||
* Example: chat:1.0.0@alice
|
||||
*/
|
||||
async getService(serviceFqn: string): Promise<{
|
||||
serviceId: string
|
||||
username: string
|
||||
serviceFqn: string
|
||||
offerId: string
|
||||
sdp: string
|
||||
createdAt: number
|
||||
expiresAt: number
|
||||
}> {
|
||||
return await this.api.getService(serviceFqn)
|
||||
}
|
||||
|
||||
/**
|
||||
* Discover a random available service without knowing the username
|
||||
* Example: chat:1.0.0 (without @username)
|
||||
*/
|
||||
async discoverService(serviceVersion: string): Promise<{
|
||||
serviceId: string
|
||||
username: string
|
||||
serviceFqn: string
|
||||
offerId: string
|
||||
sdp: string
|
||||
createdAt: number
|
||||
expiresAt: number
|
||||
}> {
|
||||
return await this.api.getService(serviceVersion)
|
||||
}
|
||||
|
||||
/**
|
||||
* Discover multiple available services with pagination
|
||||
* Example: chat:1.0.0 (without @username)
|
||||
*/
|
||||
async discoverServices(serviceVersion: string, limit: number = 10, offset: number = 0): Promise<{
|
||||
services: Array<{
|
||||
serviceId: string
|
||||
username: string
|
||||
serviceFqn: string
|
||||
offerId: string
|
||||
sdp: string
|
||||
createdAt: number
|
||||
expiresAt: number
|
||||
}>
|
||||
count: number
|
||||
limit: number
|
||||
offset: number
|
||||
}> {
|
||||
return await this.api.getService(serviceVersion, { limit, offset })
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// WebRTC Signaling
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Post answer SDP to specific offer
|
||||
*/
|
||||
async postOfferAnswer(serviceFqn: string, offerId: string, sdp: string): Promise<{
|
||||
success: boolean
|
||||
offerId: string
|
||||
}> {
|
||||
await this.api.answerOffer(serviceFqn, offerId, sdp)
|
||||
return { success: true, offerId }
|
||||
}
|
||||
|
||||
/**
|
||||
* Get answer SDP (offerer polls this)
|
||||
*/
|
||||
async getOfferAnswer(serviceFqn: string, offerId: string): Promise<{
|
||||
sdp: string
|
||||
offerId: string
|
||||
answererId: string
|
||||
answeredAt: number
|
||||
} | null> {
|
||||
return await this.api.getOfferAnswer(serviceFqn, offerId)
|
||||
}
|
||||
|
||||
/**
|
||||
* Combined polling for answers and ICE candidates
|
||||
* Returns all answered offers and ICE candidates for all peer's offers since timestamp
|
||||
*/
|
||||
async poll(since?: number): Promise<{
|
||||
answers: Array<{
|
||||
offerId: string
|
||||
serviceId?: string
|
||||
answererId: string
|
||||
sdp: string
|
||||
answeredAt: number
|
||||
}>
|
||||
iceCandidates: Record<string, Array<{
|
||||
candidate: RTCIceCandidateInit | null
|
||||
role: 'offerer' | 'answerer'
|
||||
peerId: string
|
||||
createdAt: number
|
||||
}>>
|
||||
}> {
|
||||
return await this.api.poll(since)
|
||||
}
|
||||
|
||||
/**
|
||||
* Add ICE candidates to specific offer
|
||||
*/
|
||||
async addOfferIceCandidates(serviceFqn: string, offerId: string, candidates: RTCIceCandidateInit[]): Promise<{
|
||||
count: number
|
||||
offerId: string
|
||||
}> {
|
||||
return await this.api.addOfferIceCandidates(serviceFqn, offerId, candidates)
|
||||
}
|
||||
|
||||
/**
|
||||
* Get ICE candidates for specific offer (with polling support)
|
||||
*/
|
||||
async getOfferIceCandidates(serviceFqn: string, offerId: string, since: number = 0): Promise<{
|
||||
candidates: IceCandidate[]
|
||||
offerId: string
|
||||
}> {
|
||||
return await this.api.getOfferIceCandidates(serviceFqn, offerId, since)
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// Utility Methods
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Get the current keypair (for backup/storage)
|
||||
*/
|
||||
getKeypair(): Keypair {
|
||||
return this.keypair
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the username
|
||||
*/
|
||||
getUsername(): string {
|
||||
return this.username
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the public key
|
||||
*/
|
||||
getPublicKey(): string {
|
||||
return this.keypair.publicKey
|
||||
}
|
||||
|
||||
/**
|
||||
* Access to underlying API for advanced operations
|
||||
* @deprecated Use direct methods on Rondevu instance instead
|
||||
*/
|
||||
getAPIPublic(): RondevuAPI {
|
||||
return this.api
|
||||
}
|
||||
}
|
||||
157
src/rpc-batcher.ts
Normal file
157
src/rpc-batcher.ts
Normal file
@@ -0,0 +1,157 @@
|
||||
/**
|
||||
* RPC Batcher - Throttles and batches RPC requests to reduce HTTP overhead
|
||||
*/
|
||||
|
||||
export interface BatcherOptions {
|
||||
/**
|
||||
* Maximum number of requests to batch together
|
||||
* Default: 10
|
||||
*/
|
||||
maxBatchSize?: number
|
||||
|
||||
/**
|
||||
* Maximum time to wait before sending a batch (ms)
|
||||
* Default: 50ms
|
||||
*/
|
||||
maxWaitTime?: number
|
||||
|
||||
/**
|
||||
* Minimum time between batches (ms)
|
||||
* Default: 10ms
|
||||
*/
|
||||
throttleInterval?: number
|
||||
}
|
||||
|
||||
interface QueuedRequest {
|
||||
request: any
|
||||
resolve: (value: any) => void
|
||||
reject: (error: Error) => void
|
||||
}
|
||||
|
||||
/**
|
||||
* Batches and throttles RPC requests to optimize network usage
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const batcher = new RpcBatcher(
|
||||
* (requests) => api.rpcBatch(requests),
|
||||
* { maxBatchSize: 10, maxWaitTime: 50 }
|
||||
* )
|
||||
*
|
||||
* // These will be batched together if called within maxWaitTime
|
||||
* const result1 = await batcher.add(request1)
|
||||
* const result2 = await batcher.add(request2)
|
||||
* const result3 = await batcher.add(request3)
|
||||
* ```
|
||||
*/
|
||||
export class RpcBatcher {
|
||||
private queue: QueuedRequest[] = []
|
||||
private batchTimeout: ReturnType<typeof setTimeout> | null = null
|
||||
private lastBatchTime: number = 0
|
||||
private options: Required<BatcherOptions>
|
||||
private sendBatch: (requests: any[]) => Promise<any[]>
|
||||
|
||||
constructor(
|
||||
sendBatch: (requests: any[]) => Promise<any[]>,
|
||||
options?: BatcherOptions
|
||||
) {
|
||||
this.sendBatch = sendBatch
|
||||
this.options = {
|
||||
maxBatchSize: options?.maxBatchSize ?? 10,
|
||||
maxWaitTime: options?.maxWaitTime ?? 50,
|
||||
throttleInterval: options?.throttleInterval ?? 10,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Add an RPC request to the batch queue
|
||||
* Returns a promise that resolves when the request completes
|
||||
*/
|
||||
async add(request: any): Promise<any> {
|
||||
return new Promise((resolve, reject) => {
|
||||
this.queue.push({ request, resolve, reject })
|
||||
|
||||
// Send immediately if batch is full
|
||||
if (this.queue.length >= this.options.maxBatchSize) {
|
||||
this.flush()
|
||||
return
|
||||
}
|
||||
|
||||
// Schedule batch if not already scheduled
|
||||
if (!this.batchTimeout) {
|
||||
this.batchTimeout = setTimeout(() => {
|
||||
this.flush()
|
||||
}, this.options.maxWaitTime)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Flush the queue immediately
|
||||
*/
|
||||
async flush(): Promise<void> {
|
||||
// Clear timeout if set
|
||||
if (this.batchTimeout) {
|
||||
clearTimeout(this.batchTimeout)
|
||||
this.batchTimeout = null
|
||||
}
|
||||
|
||||
// Nothing to flush
|
||||
if (this.queue.length === 0) {
|
||||
return
|
||||
}
|
||||
|
||||
// Throttle: wait if we sent a batch too recently
|
||||
const now = Date.now()
|
||||
const timeSinceLastBatch = now - this.lastBatchTime
|
||||
if (timeSinceLastBatch < this.options.throttleInterval) {
|
||||
const waitTime = this.options.throttleInterval - timeSinceLastBatch
|
||||
await new Promise(resolve => setTimeout(resolve, waitTime))
|
||||
}
|
||||
|
||||
// Extract requests from queue
|
||||
const batch = this.queue.splice(0, this.options.maxBatchSize)
|
||||
const requests = batch.map(item => item.request)
|
||||
|
||||
this.lastBatchTime = Date.now()
|
||||
|
||||
try {
|
||||
// Send batch request
|
||||
const results = await this.sendBatch(requests)
|
||||
|
||||
// Resolve individual promises
|
||||
for (let i = 0; i < batch.length; i++) {
|
||||
batch[i].resolve(results[i])
|
||||
}
|
||||
} catch (error) {
|
||||
// Reject all promises in batch
|
||||
for (const item of batch) {
|
||||
item.reject(error as Error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get current queue size
|
||||
*/
|
||||
getQueueSize(): number {
|
||||
return this.queue.length
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear the queue without sending
|
||||
*/
|
||||
clear(): void {
|
||||
if (this.batchTimeout) {
|
||||
clearTimeout(this.batchTimeout)
|
||||
this.batchTimeout = null
|
||||
}
|
||||
|
||||
// Reject all pending requests
|
||||
for (const item of this.queue) {
|
||||
item.reject(new Error('Batch queue cleared'))
|
||||
}
|
||||
|
||||
this.queue = []
|
||||
}
|
||||
}
|
||||
@@ -1,203 +0,0 @@
|
||||
import { RondevuService } from './rondevu-service.js'
|
||||
import { RondevuSignaler } from './rondevu-signaler.js'
|
||||
import { WebRTCContext } from './webrtc-context.js'
|
||||
import { RTCDurableConnection } from './durable-connection.js'
|
||||
import { EventBus } from './event-bus.js'
|
||||
|
||||
export interface ServiceClientOptions {
|
||||
username: string // Host username
|
||||
serviceFqn: string // e.g., 'chat.app@1.0.0'
|
||||
rondevuService: RondevuService
|
||||
autoReconnect?: boolean // Default: true
|
||||
maxReconnectAttempts?: number // Default: 5
|
||||
rtcConfiguration?: RTCConfiguration
|
||||
}
|
||||
|
||||
export interface ServiceClientEvents {
|
||||
connected: RTCDurableConnection
|
||||
disconnected: void
|
||||
reconnecting: { attempt: number; maxAttempts: number }
|
||||
error: Error
|
||||
}
|
||||
|
||||
/**
|
||||
* ServiceClient - High-level wrapper for connecting to a WebRTC service
|
||||
*
|
||||
* Simplifies client connection by handling:
|
||||
* - Service discovery
|
||||
* - Offer/answer exchange
|
||||
* - ICE candidate polling
|
||||
* - Automatic reconnection
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const client = new ServiceClient({
|
||||
* username: 'host-user',
|
||||
* serviceFqn: 'chat.app@1.0.0',
|
||||
* rondevuService: myService
|
||||
* })
|
||||
*
|
||||
* client.events.on('connected', conn => {
|
||||
* conn.events.on('message', msg => console.log('Received:', msg))
|
||||
* conn.sendMessage('Hello from client!')
|
||||
* })
|
||||
*
|
||||
* await client.connect()
|
||||
* ```
|
||||
*/
|
||||
export class ServiceClient {
|
||||
events: EventBus<ServiceClientEvents>
|
||||
|
||||
private signaler: RondevuSignaler | null = null
|
||||
private webrtcContext: WebRTCContext
|
||||
private connection: RTCDurableConnection | null = null
|
||||
private autoReconnect: boolean
|
||||
private maxReconnectAttempts: number
|
||||
private reconnectAttempts = 0
|
||||
private isConnecting = false
|
||||
|
||||
constructor(private options: ServiceClientOptions) {
|
||||
this.events = new EventBus<ServiceClientEvents>()
|
||||
this.webrtcContext = new WebRTCContext(options.rtcConfiguration)
|
||||
this.autoReconnect = options.autoReconnect !== undefined ? options.autoReconnect : true
|
||||
this.maxReconnectAttempts = options.maxReconnectAttempts || 5
|
||||
}
|
||||
|
||||
/**
|
||||
* Connect to the service
|
||||
*/
|
||||
async connect(): Promise<RTCDurableConnection> {
|
||||
if (this.isConnecting) {
|
||||
throw new Error('Connection already in progress')
|
||||
}
|
||||
|
||||
if (this.connection) {
|
||||
throw new Error('Already connected. Disconnect first.')
|
||||
}
|
||||
|
||||
this.isConnecting = true
|
||||
|
||||
try {
|
||||
// Create signaler
|
||||
this.signaler = new RondevuSignaler(
|
||||
this.options.rondevuService,
|
||||
this.options.serviceFqn,
|
||||
this.options.username
|
||||
)
|
||||
|
||||
// Wait for remote offer from signaler
|
||||
const remoteOffer = await new Promise<RTCSessionDescriptionInit>((resolve, reject) => {
|
||||
const timeout = setTimeout(() => {
|
||||
reject(new Error('Service discovery timeout'))
|
||||
}, 30000)
|
||||
|
||||
this.signaler!.addOfferListener((offer) => {
|
||||
clearTimeout(timeout)
|
||||
resolve(offer)
|
||||
})
|
||||
})
|
||||
|
||||
// Create connection with remote offer (makes us the answerer)
|
||||
const connection = new RTCDurableConnection({
|
||||
context: this.webrtcContext,
|
||||
signaler: this.signaler,
|
||||
offer: remoteOffer
|
||||
})
|
||||
|
||||
// Wait for connection to be ready
|
||||
await connection.ready
|
||||
|
||||
// Set up connection event listeners
|
||||
connection.events.on('state-change', (state) => {
|
||||
if (state === 'connected') {
|
||||
this.reconnectAttempts = 0
|
||||
this.events.emit('connected', connection)
|
||||
} else if (state === 'disconnected') {
|
||||
this.events.emit('disconnected', undefined)
|
||||
if (this.autoReconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
|
||||
this.attemptReconnect()
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
this.connection = connection
|
||||
this.isConnecting = false
|
||||
|
||||
return connection
|
||||
|
||||
} catch (err) {
|
||||
this.isConnecting = false
|
||||
const error = err instanceof Error ? err : new Error(String(err))
|
||||
this.events.emit('error', error)
|
||||
throw error
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Disconnect from the service
|
||||
*/
|
||||
dispose(): void {
|
||||
if (this.signaler) {
|
||||
this.signaler.dispose()
|
||||
this.signaler = null
|
||||
}
|
||||
|
||||
if (this.connection) {
|
||||
this.connection.disconnect()
|
||||
this.connection = null
|
||||
}
|
||||
|
||||
this.isConnecting = false
|
||||
this.reconnectAttempts = 0
|
||||
}
|
||||
|
||||
/**
|
||||
* @deprecated Use dispose() instead
|
||||
*/
|
||||
disconnect(): void {
|
||||
this.dispose()
|
||||
}
|
||||
|
||||
/**
|
||||
* Attempt to reconnect
|
||||
*/
|
||||
private async attemptReconnect(): Promise<void> {
|
||||
this.reconnectAttempts++
|
||||
this.events.emit('reconnecting', {
|
||||
attempt: this.reconnectAttempts,
|
||||
maxAttempts: this.maxReconnectAttempts
|
||||
})
|
||||
|
||||
// Cleanup old connection
|
||||
if (this.signaler) {
|
||||
this.signaler.dispose()
|
||||
this.signaler = null
|
||||
}
|
||||
|
||||
if (this.connection) {
|
||||
this.connection = null
|
||||
}
|
||||
|
||||
// Wait a bit before reconnecting
|
||||
await new Promise(resolve => setTimeout(resolve, 1000 * this.reconnectAttempts))
|
||||
|
||||
try {
|
||||
await this.connect()
|
||||
} catch (err) {
|
||||
console.error('Reconnection attempt failed:', err)
|
||||
if (this.reconnectAttempts < this.maxReconnectAttempts) {
|
||||
this.attemptReconnect()
|
||||
} else {
|
||||
const error = new Error('Max reconnection attempts reached')
|
||||
this.events.emit('error', error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current connection
|
||||
*/
|
||||
getConnection(): RTCDurableConnection | null {
|
||||
return this.connection
|
||||
}
|
||||
}
|
||||
@@ -1,158 +0,0 @@
|
||||
import { RondevuService } from './rondevu-service.js'
|
||||
import { RondevuSignaler } from './rondevu-signaler.js'
|
||||
import { WebRTCContext } from './webrtc-context.js'
|
||||
import { RTCDurableConnection } from './durable-connection.js'
|
||||
import { EventBus } from './event-bus.js'
|
||||
|
||||
export interface ServiceHostOptions {
|
||||
service: string // e.g., 'chat.app@1.0.0'
|
||||
rondevuService: RondevuService
|
||||
maxPeers?: number // Default: 5
|
||||
ttl?: number // Default: 300000 (5 min)
|
||||
isPublic?: boolean // Default: true
|
||||
rtcConfiguration?: RTCConfiguration
|
||||
metadata?: Record<string, any>
|
||||
}
|
||||
|
||||
export interface ServiceHostEvents {
|
||||
connection: RTCDurableConnection
|
||||
error: Error
|
||||
}
|
||||
|
||||
/**
|
||||
* ServiceHost - High-level wrapper for hosting a WebRTC service
|
||||
*
|
||||
* Simplifies hosting by handling:
|
||||
* - Offer/answer exchange
|
||||
* - ICE candidate polling
|
||||
* - Connection pool management
|
||||
* - Automatic reconnection
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const host = new ServiceHost({
|
||||
* service: 'chat.app@1.0.0',
|
||||
* rondevuService: myService,
|
||||
* maxPeers: 5
|
||||
* })
|
||||
*
|
||||
* host.events.on('connection', conn => {
|
||||
* conn.events.on('message', msg => console.log('Received:', msg))
|
||||
* conn.sendMessage('Hello!')
|
||||
* })
|
||||
*
|
||||
* await host.start()
|
||||
* ```
|
||||
*/
|
||||
export class ServiceHost {
|
||||
events: EventBus<ServiceHostEvents>
|
||||
|
||||
private signaler: RondevuSignaler | null = null
|
||||
private webrtcContext: WebRTCContext
|
||||
private connections: RTCDurableConnection[] = []
|
||||
private maxPeers: number
|
||||
private running = false
|
||||
|
||||
constructor(private options: ServiceHostOptions) {
|
||||
this.events = new EventBus<ServiceHostEvents>()
|
||||
this.webrtcContext = new WebRTCContext(options.rtcConfiguration)
|
||||
this.maxPeers = options.maxPeers || 5
|
||||
}
|
||||
|
||||
/**
|
||||
* Start hosting the service
|
||||
*/
|
||||
async start(): Promise<void> {
|
||||
if (this.running) {
|
||||
throw new Error('ServiceHost already running')
|
||||
}
|
||||
|
||||
this.running = true
|
||||
|
||||
// Create signaler
|
||||
this.signaler = new RondevuSignaler(
|
||||
this.options.rondevuService,
|
||||
this.options.service
|
||||
)
|
||||
|
||||
// Create first connection (offerer)
|
||||
const connection = new RTCDurableConnection({
|
||||
context: this.webrtcContext,
|
||||
signaler: this.signaler,
|
||||
offer: null // null means we're the offerer
|
||||
})
|
||||
|
||||
// Wait for connection to be ready
|
||||
await connection.ready
|
||||
|
||||
// Set up connection event listeners
|
||||
connection.events.on('state-change', (state) => {
|
||||
if (state === 'connected') {
|
||||
this.connections.push(connection)
|
||||
this.events.emit('connection', connection)
|
||||
|
||||
// Create next connection if under maxPeers
|
||||
if (this.connections.length < this.maxPeers) {
|
||||
this.createNextConnection().catch(err => {
|
||||
console.error('Failed to create next connection:', err)
|
||||
this.events.emit('error', err)
|
||||
})
|
||||
}
|
||||
} else if (state === 'disconnected') {
|
||||
// Remove from connections list
|
||||
const index = this.connections.indexOf(connection)
|
||||
if (index > -1) {
|
||||
this.connections.splice(index, 1)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
// Publish service with the offer
|
||||
const offer = connection.connection?.localDescription
|
||||
if (!offer?.sdp) {
|
||||
throw new Error('Offer SDP is empty')
|
||||
}
|
||||
|
||||
await this.signaler.setOffer(offer)
|
||||
}
|
||||
|
||||
/**
|
||||
* Create the next connection for incoming peers
|
||||
*/
|
||||
private async createNextConnection(): Promise<void> {
|
||||
if (!this.signaler || !this.running) {
|
||||
return
|
||||
}
|
||||
|
||||
// For now, we'll use the same offer for all connections
|
||||
// In a production scenario, you'd create multiple offers
|
||||
// This is a limitation of the current service model
|
||||
// which publishes one offer per service
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop hosting the service
|
||||
*/
|
||||
dispose(): void {
|
||||
this.running = false
|
||||
|
||||
// Cleanup signaler
|
||||
if (this.signaler) {
|
||||
this.signaler.dispose()
|
||||
this.signaler = null
|
||||
}
|
||||
|
||||
// Disconnect all connections
|
||||
for (const conn of this.connections) {
|
||||
conn.disconnect()
|
||||
}
|
||||
this.connections = []
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all active connections
|
||||
*/
|
||||
getConnections(): RTCDurableConnection[] {
|
||||
return [...this.connections]
|
||||
}
|
||||
}
|
||||
40
src/types.ts
40
src/types.ts
@@ -1,39 +1,15 @@
|
||||
/**
|
||||
* Core connection types
|
||||
* Core signaling types
|
||||
*/
|
||||
import { EventBus } from './event-bus.js'
|
||||
import { Binnable } from './bin.js'
|
||||
|
||||
export type Message = string | ArrayBuffer
|
||||
|
||||
export interface QueueMessageOptions {
|
||||
expiresAt?: number
|
||||
}
|
||||
|
||||
export interface ConnectionEvents {
|
||||
'state-change': ConnectionInterface['state']
|
||||
message: Message
|
||||
}
|
||||
|
||||
export const ConnectionStates = [
|
||||
'connected',
|
||||
'disconnected',
|
||||
'connecting'
|
||||
] as const
|
||||
|
||||
export const isConnectionState = (state: string): state is (typeof ConnectionStates)[number] =>
|
||||
ConnectionStates.includes(state as any)
|
||||
|
||||
export interface ConnectionInterface {
|
||||
state: (typeof ConnectionStates)[number]
|
||||
lastActive: number
|
||||
expiresAt?: number
|
||||
events: EventBus<ConnectionEvents>
|
||||
|
||||
queueMessage(message: Message, options?: QueueMessageOptions): Promise<void>
|
||||
sendMessage(message: Message): Promise<boolean>
|
||||
}
|
||||
/**
|
||||
* Cleanup function returned by listener methods
|
||||
*/
|
||||
export type Binnable = () => void
|
||||
|
||||
/**
|
||||
* Signaler interface for WebRTC offer/answer/ICE exchange
|
||||
*/
|
||||
export interface Signaler {
|
||||
addIceCandidate(candidate: RTCIceCandidate): Promise<void>
|
||||
addListener(callback: (candidate: RTCIceCandidate) => void): Binnable
|
||||
|
||||
67
src/web-crypto-adapter.ts
Normal file
67
src/web-crypto-adapter.ts
Normal file
@@ -0,0 +1,67 @@
|
||||
/**
|
||||
* Web Crypto adapter for browser environments
|
||||
*/
|
||||
|
||||
import * as ed25519 from '@noble/ed25519'
|
||||
import { CryptoAdapter, Keypair } from './crypto-adapter.js'
|
||||
|
||||
// Set SHA-512 hash function for ed25519 (required in @noble/ed25519 v3+)
|
||||
ed25519.hashes.sha512Async = async (message: Uint8Array) => {
|
||||
return new Uint8Array(await crypto.subtle.digest('SHA-512', message as BufferSource))
|
||||
}
|
||||
|
||||
/**
|
||||
* Web Crypto implementation using browser APIs
|
||||
* Uses btoa/atob for base64 encoding and crypto.getRandomValues for random bytes
|
||||
*/
|
||||
export class WebCryptoAdapter implements CryptoAdapter {
|
||||
async generateKeypair(): Promise<Keypair> {
|
||||
const privateKey = ed25519.utils.randomSecretKey()
|
||||
const publicKey = await ed25519.getPublicKeyAsync(privateKey)
|
||||
|
||||
return {
|
||||
publicKey: this.bytesToBase64(publicKey),
|
||||
privateKey: this.bytesToBase64(privateKey),
|
||||
}
|
||||
}
|
||||
|
||||
async signMessage(message: string, privateKeyBase64: string): Promise<string> {
|
||||
const privateKey = this.base64ToBytes(privateKeyBase64)
|
||||
const encoder = new TextEncoder()
|
||||
const messageBytes = encoder.encode(message)
|
||||
const signature = await ed25519.signAsync(messageBytes, privateKey)
|
||||
|
||||
return this.bytesToBase64(signature)
|
||||
}
|
||||
|
||||
async verifySignature(
|
||||
message: string,
|
||||
signatureBase64: string,
|
||||
publicKeyBase64: string
|
||||
): Promise<boolean> {
|
||||
try {
|
||||
const signature = this.base64ToBytes(signatureBase64)
|
||||
const publicKey = this.base64ToBytes(publicKeyBase64)
|
||||
const encoder = new TextEncoder()
|
||||
const messageBytes = encoder.encode(message)
|
||||
|
||||
return await ed25519.verifyAsync(signature, messageBytes, publicKey)
|
||||
} catch {
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
bytesToBase64(bytes: Uint8Array): string {
|
||||
const binString = Array.from(bytes, byte => String.fromCodePoint(byte)).join('')
|
||||
return btoa(binString)
|
||||
}
|
||||
|
||||
base64ToBytes(base64: string): Uint8Array {
|
||||
const binString = atob(base64)
|
||||
return Uint8Array.from(binString, char => char.codePointAt(0)!)
|
||||
}
|
||||
|
||||
randomBytes(length: number): Uint8Array {
|
||||
return crypto.getRandomValues(new Uint8Array(length))
|
||||
}
|
||||
}
|
||||
@@ -1,39 +0,0 @@
|
||||
import { Signaler } from './types'
|
||||
|
||||
const DEFAULT_RTC_CONFIGURATION: RTCConfiguration = {
|
||||
iceServers: [
|
||||
{
|
||||
urls: 'stun:stun.relay.metered.ca:80',
|
||||
},
|
||||
{
|
||||
urls: 'turn:standard.relay.metered.ca:80',
|
||||
username: 'c53a9c971da5e6f3bc959d8d',
|
||||
credential: 'QaccPqtPPaxyokXp',
|
||||
},
|
||||
{
|
||||
urls: 'turn:standard.relay.metered.ca:80?transport=tcp',
|
||||
username: 'c53a9c971da5e6f3bc959d8d',
|
||||
credential: 'QaccPqtPPaxyokXp',
|
||||
},
|
||||
{
|
||||
urls: 'turn:standard.relay.metered.ca:443',
|
||||
username: 'c53a9c971da5e6f3bc959d8d',
|
||||
credential: 'QaccPqtPPaxyokXp',
|
||||
},
|
||||
{
|
||||
urls: 'turns:standard.relay.metered.ca:443?transport=tcp',
|
||||
username: 'c53a9c971da5e6f3bc959d8d',
|
||||
credential: 'QaccPqtPPaxyokXp',
|
||||
},
|
||||
],
|
||||
}
|
||||
|
||||
export class WebRTCContext {
|
||||
constructor(
|
||||
private readonly config?: RTCConfiguration
|
||||
) {}
|
||||
|
||||
createPeerConnection(): RTCPeerConnection {
|
||||
return new RTCPeerConnection(this.config || DEFAULT_RTC_CONFIGURATION)
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user