xtr.dev/rondevu-client
1
0
Fork 0
mirror of https://github.com/xtr-dev/rondevu-client.git synced 2025-12-10 02:43:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update README with semver and privacy features

Browse Source
This commit is contained in:
Bas van den Aakster
2025-12-07 21:58:20 +01:00
parent fbd3be57d4
commit cbb0cc3f83
11 changed files with 319 additions and 1780 deletions
Download Patch File Download Diff File Expand all files Collapse all files

837
README.md
View File

@@ -2,9 +2,9 @@
[![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client) [![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
🌐 **WebRTC with durable connections and automatic reconnection** 🌐 **Simple, high-level WebRTC peer-to-peer connections**
TypeScript/JavaScript client for Rondevu, providing durable WebRTC connections that survive network interruptions with automatic reconnection and message queuing. TypeScript/JavaScript client for Rondevu, providing easy-to-use WebRTC connections with automatic signaling, username-based discovery, and built-in reconnection support.
**Related repositories:** **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)) - [@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,14 +15,16 @@ TypeScript/JavaScript client for Rondevu, providing durable WebRTC connections t
## Features ## Features
- **Durable Connections**: Automatic reconnection on network drops - **High-Level Wrappers**: ServiceHost and ServiceClient eliminate WebRTC boilerplate
- **Message Queuing**: Messages sent during disconnections are queued and flushed on reconnect - **Username-Based Discovery**: Connect to peers by username, not complex offer/answer exchange
- **Durable Channels**: RTCDataChannel wrappers that survive connection drops - **Semver-Compatible Matching**: Requesting chat@1.0.0 matches any compatible 1.x.x version
- **TTL Auto-Refresh**: Services automatically republish before expiration - **Privacy-First Design**: Services are hidden by default - no enumeration possible
- **Username Claiming**: Cryptographic ownership with Ed25519 signatures - **Automatic Reconnection**: Built-in retry logic with exponential backoff
- **Service Publishing**: Package-style naming (com.example.chat@1.0.0) - **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
- **TypeScript**: Full type safety and autocomplete - **TypeScript**: Full type safety and autocomplete
- **Configurable**: All timeouts, retry limits, and queue sizes are configurable - **Configurable Polling**: Exponential backoff with jitter to reduce server load
## Install ## Install
@@ -32,588 +34,400 @@ npm install @xtr-dev/rondevu-client
## Quick Start ## Quick Start
### Publishing a Service (Alice) ### Hosting a Service (Alice)
```typescript ```typescript
import { Rondevu } from '@xtr-dev/rondevu-client'; import { RondevuService, ServiceHost } from '@xtr-dev/rondevu-client'
// Initialize client and register // Step 1: Create and initialize service
const client = new Rondevu({ baseUrl: 'https://api.ronde.vu' }); const service = new RondevuService({
await client.register(); apiUrl: 'https://api.ronde.vu',
username: 'alice'
})
// Step 1: Claim username (one-time) await service.initialize() // Generates keypair
const claim = await client.usernames.claimUsername('alice'); await service.claimUsername() // Claims username with signature
client.usernames.saveKeypairToStorage('alice', claim.publicKey, claim.privateKey);
// Step 2: Expose service with handler // Step 2: Create ServiceHost
const keypair = client.usernames.loadKeypairFromStorage('alice'); const host = new ServiceHost({
service: 'chat.app@1.0.0',
rondevuService: service,
maxPeers: 5, // Accept up to 5 connections
ttl: 300000 // 5 minutes
})
const service = await client.exposeService({ // Step 3: Listen for incoming connections
username: 'alice', host.events.on('connection', (connection) => {
privateKey: keypair.privateKey, console.log('✅ New connection!')
serviceFqn: 'chat@1.0.0',
isPublic: true,
poolSize: 10, // Handle 10 concurrent connections
handler: (channel, connectionId) => {
console.log(`📡 New connection: ${connectionId}`);
channel.on('message', (data) => { connection.events.on('message', (msg) => {
console.log('📥 Received:', data); console.log('📨 Received:', msg)
channel.send(`Echo: ${data}`); connection.sendMessage('Hello from Alice!')
}); })
channel.on('close', () => { connection.events.on('state-change', (state) => {
console.log(`👋 Connection ${connectionId} closed`); console.log('Connection state:', state)
}); })
} })
});
// Start the service host.events.on('error', (error) => {
const info = await service.start(); console.error('Host error:', error)
console.log(`Service published with UUID: ${info.uuid}`); })
console.log('Waiting for connections...');
// Later: stop the service // Step 4: Start hosting
await service.stop(); await host.start()
console.log('Service is now live! Others can connect to @alice')
// Later: stop hosting
host.dispose()
``` ```
### Connecting to a Service (Bob) ### Connecting to a Service (Bob)
```typescript ```typescript
import { Rondevu } from '@xtr-dev/rondevu-client'; import { RondevuService, ServiceClient } from '@xtr-dev/rondevu-client'
// Initialize client and register // Step 1: Create and initialize service
const client = new Rondevu({ baseUrl: 'https://api.ronde.vu' }); const service = new RondevuService({
await client.register(); apiUrl: 'https://api.ronde.vu',
username: 'bob'
})
// Connect to Alice's service await service.initialize()
const connection = await client.connect('alice', 'chat@1.0.0', { await service.claimUsername()
maxReconnectAttempts: 5
});
// Create a durable channel // Step 2: Create ServiceClient
const channel = connection.createChannel('main'); const client = new ServiceClient({
username: 'alice', // Connect to Alice
serviceFqn: 'chat.app@1.0.0',
rondevuService: service,
autoReconnect: true,
maxReconnectAttempts: 5
})
channel.on('message', (data) => { // Step 3: Listen for connection events
console.log('📥 Received:', data); client.events.on('connected', (connection) => {
}); console.log('✅ Connected to Alice!')
channel.on('open', () => { connection.events.on('message', (msg) => {
console.log('✅ Channel open'); console.log('📨 Received:', msg)
channel.send('Hello Alice!'); })
});
// Listen for connection events // Send a message
connection.on('connected', () => { connection.sendMessage('Hello from Bob!')
console.log('🎉 Connected to Alice'); })
});
connection.on('reconnecting', (attempt, max, delay) => { client.events.on('disconnected', () => {
console.log(`🔄 Reconnecting... (${attempt}/${max}, retry in ${delay}ms)`); console.log('🔌 Disconnected')
}); })
connection.on('disconnected', () => { client.events.on('reconnecting', ({ attempt, maxAttempts }) => {
console.log('🔌 Disconnected'); console.log(`🔄 Reconnecting (${attempt}/${maxAttempts})...`)
}); })
connection.on('failed', (error) => { client.events.on('error', (error) => {
console.error('❌ Connection failed permanently:', error); console.error('❌ Error:', error)
}); })
// Establish the connection // Step 4: Connect
await connection.connect(); await client.connect()
// Messages sent during disconnection are automatically queued // Later: disconnect
channel.send('This will be queued if disconnected'); client.dispose()
// Later: close the connection
await connection.close();
``` ```
## Core Concepts ## Core Concepts
### DurableConnection ### RondevuService
Manages WebRTC peer lifecycle with automatic reconnection: Handles authentication and username management:
- Automatically reconnects when connection drops - Generates Ed25519 keypair for signing
- Exponential backoff with jitter (1s → 2s → 4s → 8s → ... max 30s) - Claims usernames with cryptographic proof
- Configurable max retry attempts (default: 10) - Provides API client for signaling server
- Manages multiple DurableChannel instances
### DurableChannel ### ServiceHost
Wraps RTCDataChannel with message queuing: High-level wrapper for hosting a WebRTC service:
- Queues messages during disconnection - Automatically creates and publishes offers
- Flushes queue on reconnection - Handles incoming connections
- Configurable queue size and message age limits - Manages ICE candidate exchange
- RTCDataChannel-compatible API with event emitters - Supports multiple simultaneous peers
### DurableService ### ServiceClient
Server-side service with TTL auto-refresh: High-level wrapper for connecting to services:
- Automatically republishes service before TTL expires - Discovers services by username
- Creates DurableConnection for each incoming peer - Handles offer/answer exchange automatically
- Manages connection pool for multiple simultaneous connections - 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 ## API Reference
### Main Client ### RondevuService
```typescript ```typescript
const client = new Rondevu({ const service = new RondevuService({
baseUrl: 'https://api.ronde.vu', // optional, default shown apiUrl: string, // Signaling server URL
credentials?: { peerId, secret }, // optional, skip registration username: string, // Your username
fetch?: customFetch, // optional, for Node.js < 18 keypair?: Keypair // Optional: reuse existing keypair
RTCPeerConnection?: RTCPeerConnection, // optional, for Node.js })
RTCSessionDescription?: RTCSessionDescription,
RTCIceCandidate?: RTCIceCandidate
});
// Register and get credentials // Initialize service (generates keypair if not provided)
const creds = await client.register(); await service.initialize(): Promise<void>
// { peerId: '...', secret: '...' }
// Check if authenticated // Claim username with cryptographic signature
client.isAuthenticated(); // boolean await service.claimUsername(): Promise<void>
// Get current credentials // Check if username is claimed
client.getCredentials(); // { peerId, secret } | undefined service.isUsernameClaimed(): boolean
// Get current username
service.getUsername(): string
// Get keypair
service.getKeypair(): Keypair
// Get API client
service.getAPI(): RondevuAPI
``` ```
### Username API ### ServiceHost
```typescript ```typescript
// Check username availability const host = new ServiceHost({
const check = await client.usernames.checkUsername('alice'); service: string, // Service FQN (e.g., 'chat.app@1.0.0')
// { available: true } or { available: false, expiresAt: number, publicKey: string } rondevuService: RondevuService,
maxPeers?: number, // Default: 5
ttl?: number, // Default: 300000 (5 minutes)
isPublic?: boolean, // Default: true
rtcConfiguration?: RTCConfiguration
})
// Claim username with new keypair // Start hosting
const claim = await client.usernames.claimUsername('alice'); await host.start(): Promise<void>
// { username, publicKey, privateKey, claimedAt, expiresAt }
// Save keypair to localStorage // Stop hosting and cleanup
client.usernames.saveKeypairToStorage('alice', claim.publicKey, claim.privateKey); host.dispose(): void
// Load keypair from localStorage // Get all active connections
const keypair = client.usernames.loadKeypairFromStorage('alice'); host.getConnections(): RTCDurableConnection[]
// { publicKey, privateKey } | null
// Events
host.events.on('connection', (conn: RTCDurableConnection) => {})
host.events.on('error', (error: Error) => {})
``` ```
**Username Rules:** ### ServiceClient
- 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
### Durable Service API
```typescript ```typescript
// Expose a durable service const client = new ServiceClient({
const service = await client.exposeService({ username: string, // Host username to connect to
username: 'alice', serviceFqn: string, // Service FQN (e.g., 'chat.app@1.0.0')
privateKey: keypair.privateKey, rondevuService: RondevuService,
serviceFqn: 'chat@1.0.0', autoReconnect?: boolean, // Default: true
maxReconnectAttempts?: number, // Default: 5
rtcConfiguration?: RTCConfiguration
})
// Service options // Connect to service
isPublic: true, // optional, default: false await client.connect(): Promise<RTCDurableConnection>
metadata: { version: '1.0' }, // optional
ttl: 300000, // optional, default: 5 minutes
ttlRefreshMargin: 0.2, // optional, refresh at 80% of TTL
// Connection pooling // Disconnect and cleanup
poolSize: 10, // optional, default: 1 client.dispose(): void
pollingInterval: 2000, // optional, default: 2000ms
// Connection options (applied to incoming connections) // Get current connection
maxReconnectAttempts: 10, // optional, default: 10 client.getConnection(): RTCDurableConnection | null
reconnectBackoffBase: 1000, // optional, default: 1000ms
reconnectBackoffMax: 30000, // optional, default: 30000ms
reconnectJitter: 0.2, // optional, default: 0.2 (±20%)
connectionTimeout: 30000, // optional, default: 30000ms
// Message queuing // Events
maxQueueSize: 1000, // optional, default: 1000 client.events.on('connected', (conn: RTCDurableConnection) => {})
maxMessageAge: 60000, // optional, default: 60000ms (1 minute) client.events.on('disconnected', () => {})
client.events.on('reconnecting', (info: { attempt: number, maxAttempts: number }) => {})
// WebRTC configuration client.events.on('error', (error: Error) => {})
rtcConfig: {
iceServers: [
{ urls: 'stun:stun.l.google.com:19302' }
]
},
// Connection handler
handler: (channel, connectionId) => {
// Handle incoming connection
channel.on('message', (data) => {
console.log('Received:', data);
channel.send(`Echo: ${data}`);
});
}
});
// Start the service
const info = await service.start();
// { serviceId: '...', uuid: '...', expiresAt: 1234567890 }
// Get active connections
const connections = service.getActiveConnections();
// ['conn-123', 'conn-456']
// Get service info
const serviceInfo = service.getServiceInfo();
// { serviceId: '...', uuid: '...', expiresAt: 1234567890 } | null
// Stop the service
await service.stop();
``` ```
**Service Events:** ### RTCDurableConnection
```typescript ```typescript
service.on('published', (serviceId, uuid) => { // Connection state
console.log(`Service published: ${uuid}`); connection.state: 'connected' | 'connecting' | 'disconnected'
});
service.on('connection', (connectionId) => { // Send message (returns true if sent, false if queued)
console.log(`New connection: ${connectionId}`); await connection.sendMessage(message: string): Promise<boolean>
});
service.on('disconnection', (connectionId) => { // Queue message for sending when connected
console.log(`Connection closed: ${connectionId}`); await connection.queueMessage(message: string, options?: QueueMessageOptions): Promise<void>
});
service.on('ttl-refreshed', (expiresAt) => { // Disconnect
console.log(`TTL refreshed, expires at: ${new Date(expiresAt)}`); connection.disconnect(): void
});
service.on('error', (error, context) => { // Events
console.error(`Service error (${context}):`, error); connection.events.on('message', (msg: string) => {})
}); connection.events.on('state-change', (state: ConnectionStates) => {})
service.on('closed', () => {
console.log('Service stopped');
});
``` ```
### Durable Connection API ## Configuration
### Polling Configuration
The signaling uses configurable polling with exponential backoff:
```typescript ```typescript
// Connect by username and service FQN // Default polling config
const connection = await client.connect('alice', 'chat@1.0.0', { {
// Connection options initialInterval: 500, // Start at 500ms
maxReconnectAttempts: 10, // optional, default: 10 maxInterval: 5000, // Max 5 seconds
reconnectBackoffBase: 1000, // optional, default: 1000ms backoffMultiplier: 1.5, // Increase by 1.5x each time
reconnectBackoffMax: 30000, // optional, default: 30000ms maxRetries: 50, // Max 50 attempts
reconnectJitter: 0.2, // optional, default: 0.2 (±20%) jitter: true // Add random 0-100ms to prevent thundering herd
connectionTimeout: 30000, // optional, default: 30000ms
// Message queuing
maxQueueSize: 1000, // optional, default: 1000
maxMessageAge: 60000, // optional, default: 60000ms
// WebRTC configuration
rtcConfig: {
iceServers: [
{ urls: 'stun:stun.l.google.com:19302' }
]
}
});
// Connect by UUID
const connection2 = await client.connectByUuid('service-uuid-here', {
maxReconnectAttempts: 5
});
// Create channels before connecting
const channel = connection.createChannel('main');
const fileChannel = connection.createChannel('files', {
ordered: false,
maxRetransmits: 3
});
// Get existing channel
const existingChannel = connection.getChannel('main');
// Check connection state
const state = connection.getState();
// 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'failed' | 'closed'
const isConnected = connection.isConnected();
// Connect
await connection.connect();
// Close connection
await connection.close();
```
**Connection Events:**
```typescript
connection.on('state', (newState, previousState) => {
console.log(`State: ${previousState} → ${newState}`);
});
connection.on('connected', () => {
console.log('Connected');
});
connection.on('reconnecting', (attempt, maxAttempts, delay) => {
console.log(`Reconnecting (${attempt}/${maxAttempts}) in ${delay}ms`);
});
connection.on('disconnected', () => {
console.log('Disconnected');
});
connection.on('failed', (error, permanent) => {
console.error('Connection failed:', error, 'Permanent:', permanent);
});
connection.on('closed', () => {
console.log('Connection closed');
});
```
### Durable Channel API
```typescript
const channel = connection.createChannel('chat', {
ordered: true, // optional, default: true
maxRetransmits: undefined // optional, for unordered channels
});
// Send data (queued if disconnected)
channel.send('Hello!');
channel.send(new ArrayBuffer(1024));
channel.send(new Blob(['data']));
// Check state
const state = channel.readyState;
// 'connecting' | 'open' | 'closing' | 'closed'
// Get buffered amount
const buffered = channel.bufferedAmount;
// Set buffered amount low threshold
channel.bufferedAmountLowThreshold = 16 * 1024; // 16KB
// Get queue size (for debugging)
const queueSize = channel.getQueueSize();
// Close channel
channel.close();
```
**Channel Events:**
```typescript
channel.on('open', () => {
console.log('Channel open');
});
channel.on('message', (data) => {
console.log('Received:', data);
});
channel.on('error', (error) => {
console.error('Channel error:', error);
});
channel.on('close', () => {
console.log('Channel closed');
});
channel.on('bufferedAmountLow', () => {
console.log('Buffer drained, safe to send more');
});
channel.on('queueOverflow', (droppedCount) => {
console.warn(`Queue overflow: ${droppedCount} messages dropped`);
});
```
## Configuration Options
### Connection Configuration
```typescript
interface DurableConnectionConfig {
maxReconnectAttempts?: number; // default: 10
reconnectBackoffBase?: number; // default: 1000 (1 second)
reconnectBackoffMax?: number; // default: 30000 (30 seconds)
reconnectJitter?: number; // default: 0.2 (±20%)
connectionTimeout?: number; // default: 30000 (30 seconds)
maxQueueSize?: number; // default: 1000 messages
maxMessageAge?: number; // default: 60000 (1 minute)
rtcConfig?: RTCConfiguration;
} }
``` ```
### Service Configuration This is handled automatically - no configuration needed.
### WebRTC Configuration
Provide custom STUN/TURN servers:
```typescript ```typescript
interface DurableServiceConfig extends DurableConnectionConfig { const host = new ServiceHost({
username: string; service: 'chat.app@1.0.0',
privateKey: string; rondevuService: service,
serviceFqn: string; rtcConfiguration: {
isPublic?: boolean; // default: false iceServers: [
metadata?: Record<string, any>; { urls: 'stun:stun.l.google.com:19302' },
ttl?: number; // default: 300000 (5 minutes) {
ttlRefreshMargin?: number; // default: 0.2 (refresh at 80%) urls: 'turn:turn.example.com:3478',
poolSize?: number; // default: 1 username: 'user',
pollingInterval?: number; // default: 2000 (2 seconds) credential: 'pass'
} }
]
}
})
``` ```
## 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
## Examples ## Examples
### Chat Application ### Chat Application
```typescript See [demo/demo.js](./demo/demo.js) for a complete working example.
// Server
const client = new Rondevu();
await client.register();
const claim = await client.usernames.claimUsername('alice'); ### Persistent Keypair
client.usernames.saveKeypairToStorage('alice', claim.publicKey, claim.privateKey);
const keypair = client.usernames.loadKeypairFromStorage('alice');
const service = await client.exposeService({
username: 'alice',
privateKey: keypair.privateKey,
serviceFqn: 'chat@1.0.0',
isPublic: true,
poolSize: 50, // Handle 50 concurrent users
handler: (channel, connectionId) => {
console.log(`User ${connectionId} joined`);
channel.on('message', (data) => {
console.log(`[${connectionId}]: ${data}`);
// Broadcast to all users (implement your broadcast logic)
});
channel.on('close', () => {
console.log(`User ${connectionId} left`);
});
}
});
await service.start();
// Client
const client2 = new Rondevu();
await client2.register();
const connection = await client2.connect('alice', 'chat@1.0.0');
const channel = connection.createChannel('chat');
channel.on('message', (data) => {
console.log('Message:', data);
});
await connection.connect();
channel.send('Hello everyone!');
```
### File Transfer with Progress
```typescript ```typescript
// Server // Save keypair to localStorage
const service = await client.exposeService({ const service = new RondevuService({
username: 'alice', apiUrl: 'https://api.ronde.vu',
privateKey: keypair.privateKey, username: 'alice'
serviceFqn: 'files@1.0.0', })
handler: (channel, connectionId) => {
channel.on('message', async (data) => {
const request = JSON.parse(data);
if (request.action === 'download') { await service.initialize()
const file = await fs.readFile(request.path); await service.claimUsername()
const chunkSize = 16 * 1024; // 16KB chunks
for (let i = 0; i < file.byteLength; i += chunkSize) { // Save for later
const chunk = file.slice(i, i + chunkSize); localStorage.setItem('rondevu-keypair', JSON.stringify(service.getKeypair()))
channel.send(chunk); localStorage.setItem('rondevu-username', service.getUsername())
// Wait for buffer to drain if needed // Load on next session
while (channel.bufferedAmount > 16 * 1024 * 1024) { // 16MB const savedKeypair = JSON.parse(localStorage.getItem('rondevu-keypair'))
await new Promise(resolve => setTimeout(resolve, 100)); const savedUsername = localStorage.getItem('rondevu-username')
}
}
channel.send(JSON.stringify({ done: true })); const service2 = new RondevuService({
} apiUrl: 'https://api.ronde.vu',
}); username: savedUsername,
} keypair: savedKeypair
}); })
await service.start(); await service2.initialize() // Reuses keypair
// Client
const connection = await client.connect('alice', 'files@1.0.0');
const channel = connection.createChannel('files');
const chunks = [];
channel.on('message', (data) => {
if (typeof data === 'string') {
const msg = JSON.parse(data);
if (msg.done) {
const blob = new Blob(chunks);
console.log('Download complete:', blob.size, 'bytes');
}
} else {
chunks.push(data);
console.log('Progress:', chunks.length * 16 * 1024, 'bytes');
}
});
await connection.connect();
channel.send(JSON.stringify({ action: 'download', path: '/file.zip' }));
``` ```
## Platform-Specific Setup ### 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 ### Modern Browsers
Works out of the box - no additional setup needed. Works out of the box - no additional setup needed.
### Node.js 18+ ### Node.js 18+
Native fetch is available, but you need WebRTC polyfills: Native fetch is available, but WebRTC requires polyfills:
```bash ```bash
npm install wrtc npm install wrtc
``` ```
```typescript ```typescript
import { Rondevu } from '@xtr-dev/rondevu-client'; import { WebRTCContext } from '@xtr-dev/rondevu-client'
import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc'; import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc'
const client = new Rondevu({ // Configure WebRTC context
baseUrl: 'https://api.ronde.vu', const context = new WebRTCContext({
RTCPeerConnection, RTCPeerConnection,
RTCSessionDescription, RTCSessionDescription,
RTCIceCandidate RTCIceCandidate
}); } as any)
```
### Node.js < 18
Install both fetch and WebRTC polyfills:
```bash
npm install node-fetch wrtc
```
```typescript
import { Rondevu } from '@xtr-dev/rondevu-client';
import fetch from 'node-fetch';
import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc';
const client = new Rondevu({
baseUrl: 'https://api.ronde.vu',
fetch: fetch as any,
RTCPeerConnection,
RTCSessionDescription,
RTCIceCandidate
});
``` ```
## TypeScript ## TypeScript
@@ -622,38 +436,23 @@ All types are exported:
```typescript ```typescript
import type { import type {
// Client types RondevuServiceOptions,
Credentials, ServiceHostOptions,
RondevuOptions, ServiceHostEvents,
ServiceClientOptions,
// Username types ServiceClientEvents,
UsernameCheckResult, ConnectionInterface,
UsernameClaimResult, ConnectionEvents,
ConnectionStates,
// Durable connection types Message,
DurableConnectionState, QueueMessageOptions,
DurableChannelState, Signaler,
DurableConnectionConfig, PollingConfig,
DurableChannelConfig, Credentials,
DurableServiceConfig, Keypair
QueuedMessage, } from '@xtr-dev/rondevu-client'
DurableConnectionEvents,
DurableChannelEvents,
DurableServiceEvents,
ConnectionInfo,
ServiceInfo
} from '@xtr-dev/rondevu-client';
``` ```
## Migration from v0.8.x
v0.9.0 is a **breaking change** that replaces the low-level APIs with high-level durable connections. See [MIGRATION.md](./MIGRATION.md) for detailed migration guide.
**Key Changes:**
- ❌ Removed: `client.services.*`, `client.discovery.*`, `client.createPeer()` (low-level APIs)
- ✅ Added: `client.exposeService()`, `client.connect()`, `client.connectByUuid()` (durable APIs)
- ✅ Changed: Focus on durable connections with automatic reconnection and message queuing
## License ## License
MIT MIT

141
demo/README.md
View File

@@ -1,141 +0,0 @@
# Rondevu WebRTC Local Test
Simple side-by-side demo for testing `WebRTCRondevuConnection` with **local signaling** (no server required).
## Quick Start
```bash
npm run dev
```
Opens browser at `http://localhost:3000`
## How It Works
This demo uses **local in-memory signaling** to test WebRTC connections between two peers on the same page. The `LocalSignaler` class simulates a signaling server by directly exchanging ICE candidates and SDP between peers.
### Architecture
- **LocalSignaler**: Implements the `Signaler` interface with local peer-to-peer communication
- **Host (Peer A)**: Creates the offer (offerer role)
- **Client (Peer B)**: Receives the offer and creates answer (answerer role)
- **ICE Exchange**: Candidates are automatically exchanged between peers through the linked signalers
## Usage Steps
1. **Create Host** (Peer A)
- Click "1️⃣ Create Host Connection" on the left side
- The host will create an offer and display it
- Status changes to "Connecting"
2. **Create Client** (Peer B)
- Click "2️⃣ Create Client Connection" on the right side
- The client receives the host's offer automatically
- Creates an answer and sends it back to the host
- Both peers exchange ICE candidates
3. **Connection Established**
- Watch the status indicators turn green ("Connected")
- Activity logs show the connection progress
4. **Send Messages**
- Type a message in either peer's input field
- Click "📤 Send" or press Enter
- Messages appear in the other peer's activity log
## Features
- ✅ **No signaling server required** - Everything runs locally
- ✅ **Automatic ICE candidate exchange** - Signalers handle candidate exchange
- ✅ **Real-time activity logs** - See exactly what's happening
- ✅ **Connection state indicators** - Visual feedback for connection status
- ✅ **Bidirectional messaging** - Send messages in both directions
## Code Structure
### demo.js
```javascript
// LocalSignaler - Implements local signaling
class LocalSignaler {
addIceCandidate(candidate) // Called when local peer has a candidate
addListener(callback) // Listen for remote candidates
linkTo(remoteSignaler) // Connect two signalers together
}
// Create and link signalers
const hostSignaler = new LocalSignaler('HOST', 'CLIENT')
const clientSignaler = new LocalSignaler('CLIENT', 'HOST')
hostSignaler.linkTo(clientSignaler)
clientSignaler.linkTo(hostSignaler)
// Create connections
const hostConnection = new WebRTCRondevuConnection({
id: 'test-connection',
host: 'client-peer',
service: 'test.demo@1.0.0',
offer: null, // No offer = offerer role
context: new WebRTCContext(hostSignaler)
})
const clientConnection = new WebRTCRondevuConnection({
id: 'test-connection',
host: 'host-peer',
service: 'test.demo@1.0.0',
offer: hostConnection.connection.localDescription, // With offer = answerer role
context: new WebRTCContext(clientSignaler)
})
```
### index.html
- Side-by-side layout for Host and Client
- Status indicators (disconnected/connecting/connected)
- SDP display areas (offer/answer)
- Message input and send buttons
- Activity logs for each peer
## Debugging
Open the browser console to see detailed logs:
- `[HOST]` - Logs from the host connection
- `[CLIENT]` - Logs from the client connection
- ICE candidate exchange
- Connection state changes
- Message send/receive events
## Comparison: Local vs Remote Signaling
### Local Signaling (This Demo)
```javascript
const signaler = new LocalSignaler('HOST', 'CLIENT')
signaler.linkTo(remoteSignaler) // Direct link
```
**Pros**: No server, instant testing, no network latency
**Cons**: Only works for same-page testing
### Remote Signaling (Production)
```javascript
const api = new RondevuAPI('https://api.ronde.vu', credentials)
const signaler = new RondevuSignaler(api, offerId)
```
**Pros**: Real peer discovery, works across networks
**Cons**: Requires signaling server, network latency
## Next Steps
After testing locally, you can:
1. Switch to `RondevuSignaler` for real signaling server testing
2. Test across different browsers/devices
3. Test with STUN/TURN servers for NAT traversal
4. Implement production signaling with Rondevu API
## Files
- `index.html` - UI layout and styling
- `demo.js` - Local signaling implementation and WebRTC logic
- `README.md` - This file

304
demo/demo.js
View File

@@ -1,304 +0,0 @@
import { WebRTCRondevuConnection } from '../src/index.js'
import { WebRTCContext } from '../src/webrtc-context.js'
// Local signaling implementation for testing
class LocalSignaler {
constructor(name, remoteName) {
this.name = name
this.remoteName = remoteName
this.iceCandidates = []
this.iceListeners = []
this.remote = null
this.remoteIceCandidates = []
this.offerCallbacks = []
this.answerCallbacks = []
}
// Link two signalers together
linkTo(remoteSignaler) {
this.remote = remoteSignaler
this.remoteIceCandidates = remoteSignaler.iceCandidates
}
// Set local offer (called when offer is created)
setOffer(offer) {
console.log(`[${this.name}] Setting offer`)
// Notify remote peer about the offer
if (this.remote) {
this.remote.offerCallbacks.forEach(callback => callback(offer))
}
}
// Set local answer (called when answer is created)
setAnswer(answer) {
console.log(`[${this.name}] Setting answer`)
// Notify remote peer about the answer
if (this.remote) {
this.remote.answerCallbacks.forEach(callback => callback(answer))
}
}
// Listen for offers from remote peer
addOfferListener(callback) {
this.offerCallbacks.push(callback)
return () => {
const index = this.offerCallbacks.indexOf(callback)
if (index > -1) {
this.offerCallbacks.splice(index, 1)
}
}
}
// Listen for answers from remote peer
addAnswerListener(callback) {
this.answerCallbacks.push(callback)
return () => {
const index = this.answerCallbacks.indexOf(callback)
if (index > -1) {
this.answerCallbacks.splice(index, 1)
}
}
}
// Add local ICE candidate (called by local connection)
addIceCandidate(candidate) {
console.log(`[${this.name}] Adding ICE candidate:`, candidate.candidate)
this.iceCandidates.push(candidate)
// Immediately send to remote peer if linked
if (this.remote) {
setTimeout(() => {
this.remote.iceListeners.forEach(listener => {
console.log(`[${this.name}] Sending ICE to ${this.remoteName}`)
listener(candidate)
})
}, 10)
}
}
// Listen for remote ICE candidates
addListener(callback) {
console.log(`[${this.name}] Adding ICE listener`)
this.iceListeners.push(callback)
// Send any existing remote candidates
this.remoteIceCandidates.forEach(candidate => {
setTimeout(() => callback(candidate), 10)
})
return () => {
const index = this.iceListeners.indexOf(callback)
if (index > -1) {
this.iceListeners.splice(index, 1)
}
}
}
}
// Create signalers for host and client
const hostSignaler = new LocalSignaler('HOST', 'CLIENT')
const clientSignaler = new LocalSignaler('CLIENT', 'HOST')
// Link them together for bidirectional communication
hostSignaler.linkTo(clientSignaler)
clientSignaler.linkTo(hostSignaler)
// Store connections
let hostConnection = null
let clientConnection = null
// UI Update functions
function updateStatus(peer, state) {
const statusEl = document.getElementById(`status-${peer}`)
if (statusEl) {
statusEl.className = `status ${state}`
statusEl.textContent = state.charAt(0).toUpperCase() + state.slice(1)
}
}
function addLog(peer, message) {
const logEl = document.getElementById(`log-${peer}`)
if (logEl) {
const time = new Date().toLocaleTimeString()
logEl.innerHTML += `<div class="log-entry">[${time}] ${message}</div>`
logEl.scrollTop = logEl.scrollHeight
}
}
// Create Host (Offerer)
async function createHost() {
try {
addLog('a', 'Creating host connection (offerer)...')
const hostContext = new WebRTCContext(hostSignaler)
hostConnection = new WebRTCRondevuConnection({
id: 'test-connection',
host: 'client-peer',
service: 'test.demo@1.0.0',
offer: null,
context: hostContext,
})
// Listen for state changes
hostConnection.events.on('state-change', state => {
console.log('[HOST] State changed:', state)
updateStatus('a', state)
addLog('a', `State changed to: ${state}`)
})
// Listen for messages
hostConnection.events.on('message', message => {
console.log('[HOST] Received message:', message)
addLog('a', `📨 Received: ${message}`)
})
addLog('a', '✅ Host connection created')
updateStatus('a', 'connecting')
// Wait for host to be ready (offer created and set)
await hostConnection.ready
addLog('a', '✅ Host offer created')
// Get the offer
const offer = hostConnection.connection.localDescription
document.getElementById('offer-a').value = JSON.stringify(offer, null, 2)
addLog('a', 'Offer ready to send to client')
} catch (error) {
console.error('[HOST] Error:', error)
addLog('a', `❌ Error: ${error.message}`)
updateStatus('a', 'disconnected')
}
}
// Create Client (Answerer)
async function createClient() {
try {
addLog('b', 'Creating client connection (answerer)...')
// Get offer from host
if (!hostConnection) {
alert('Please create host first!')
return
}
const offer = hostConnection.connection.localDescription
if (!offer) {
alert('Host offer not ready yet!')
return
}
addLog('b', 'Got offer from host')
const clientContext = new WebRTCContext(clientSignaler)
clientConnection = new WebRTCRondevuConnection({
id: 'test-connection',
host: 'host-peer',
service: 'test.demo@1.0.0',
offer: offer,
context: clientContext,
})
// Listen for state changes
clientConnection.events.on('state-change', state => {
console.log('[CLIENT] State changed:', state)
updateStatus('b', state)
addLog('b', `State changed to: ${state}`)
})
// Listen for messages
clientConnection.events.on('message', message => {
console.log('[CLIENT] Received message:', message)
addLog('b', `📨 Received: ${message}`)
})
addLog('b', '✅ Client connection created')
updateStatus('b', 'connecting')
// Wait for client to be ready
await clientConnection.ready
addLog('b', '✅ Client answer created')
// Get the answer
const answer = clientConnection.connection.localDescription
document.getElementById('answer-b').value = JSON.stringify(answer, null, 2)
// Set answer on host
addLog('b', 'Setting answer on host...')
await hostConnection.connection.setRemoteDescription(answer)
addLog('b', '✅ Answer set on host')
addLog('a', '✅ Answer received from client')
} catch (error) {
console.error('[CLIENT] Error:', error)
addLog('b', `❌ Error: ${error.message}`)
updateStatus('b', 'disconnected')
}
}
// Send test message from host to client
function sendFromHost() {
if (!hostConnection) {
alert('Please create host first!')
return
}
const message = document.getElementById('message-a').value || 'Hello from Host!'
addLog('a', `📤 Sending: ${message}`)
hostConnection
.sendMessage(message)
.then(success => {
if (success) {
addLog('a', '✅ Message sent successfully')
} else {
addLog('a', '⚠️ Message queued (not connected)')
}
})
.catch(error => {
addLog('a', `❌ Error sending: ${error.message}`)
})
}
// Send test message from client to host
function sendFromClient() {
if (!clientConnection) {
alert('Please create client first!')
return
}
const message = document.getElementById('message-b').value || 'Hello from Client!'
addLog('b', `📤 Sending: ${message}`)
clientConnection
.sendMessage(message)
.then(success => {
if (success) {
addLog('b', '✅ Message sent successfully')
} else {
addLog('b', '⚠️ Message queued (not connected)')
}
})
.catch(error => {
addLog('b', `❌ Error sending: ${error.message}`)
})
}
// Attach event listeners when DOM is ready
document.addEventListener('DOMContentLoaded', () => {
// Clear all textareas on load
document.getElementById('offer-a').value = ''
document.getElementById('answer-b').value = ''
// Make functions globally available (for console testing)
window.createHost = createHost
window.createClient = createClient
window.sendFromHost = sendFromHost
window.sendFromClient = sendFromClient
console.log('🚀 Local signaling test loaded')
console.log('Steps:')
console.log('1. Click "Create Host" (Peer A)')
console.log('2. Click "Create Client" (Peer B)')
console.log('3. Wait for connection to establish')
console.log('4. Send messages between peers')
})

280
demo/index.html
View File

@@ -1,280 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Rondevu WebRTC Local Test</title>
<style>
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family:
-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu,
Cantarell, sans-serif;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
min-height: 100vh;
padding: 20px;
}
.container {
max-width: 1400px;
margin: 0 auto;
}
h1 {
color: white;
text-align: center;
margin-bottom: 30px;
font-size: 2.5rem;
text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.2);
}
.peers {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 20px;
}
.peer {
background: white;
border-radius: 12px;
padding: 24px;
box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
}
.peer h2 {
color: #667eea;
margin-bottom: 20px;
font-size: 1.5rem;
border-bottom: 2px solid #667eea;
padding-bottom: 10px;
}
.status {
padding: 12px;
border-radius: 8px;
margin-bottom: 20px;
font-weight: 600;
text-align: center;
}
.status.disconnected {
background: #fee;
color: #c33;
}
.status.connecting {
background: #ffeaa7;
color: #d63031;
}
.status.connected {
background: #d4edda;
color: #155724;
}
.section {
margin-bottom: 20px;
}
.section h3 {
color: #555;
font-size: 0.9rem;
text-transform: uppercase;
margin-bottom: 8px;
letter-spacing: 0.5px;
}
textarea {
width: 100%;
padding: 12px;
border: 2px solid #e0e0e0;
border-radius: 8px;
font-family: 'Courier New', monospace;
font-size: 0.85rem;
resize: vertical;
min-height: 100px;
transition: border-color 0.3s;
}
textarea:focus {
outline: none;
border-color: #667eea;
}
input[type='text'] {
width: 100%;
padding: 12px;
border: 2px solid #e0e0e0;
border-radius: 8px;
font-size: 0.95rem;
transition: border-color 0.3s;
}
input[type='text']:focus {
outline: none;
border-color: #667eea;
}
button {
background: #667eea;
color: white;
border: none;
padding: 12px 24px;
border-radius: 8px;
font-size: 0.95rem;
font-weight: 600;
cursor: pointer;
transition: all 0.3s;
width: 100%;
margin-top: 8px;
}
button:hover {
background: #5568d3;
transform: translateY(-2px);
box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
}
button:active {
transform: translateY(0);
}
button:disabled {
background: #ccc;
cursor: not-allowed;
transform: none;
}
.log {
max-height: 300px;
overflow-y: auto;
background: #f8f9fa;
border-radius: 8px;
padding: 12px;
font-family: 'Courier New', monospace;
font-size: 0.8rem;
line-height: 1.6;
}
.log-entry {
margin-bottom: 4px;
padding: 4px;
background: white;
border-radius: 4px;
}
.message-box {
display: flex;
gap: 8px;
margin-top: 8px;
}
.message-box input {
flex: 1;
margin: 0;
}
.message-box button {
width: auto;
margin: 0;
padding: 12px 20px;
}
@media (max-width: 768px) {
.peers {
grid-template-columns: 1fr;
}
}
</style>
</head>
<body>
<div class="container">
<h1>🔗 Rondevu WebRTC Local Test</h1>
<div class="peers">
<!-- Peer A (Host) -->
<div class="peer">
<h2>Peer A (Host/Offerer)</h2>
<div class="status disconnected" id="status-a">Disconnected</div>
<div class="section">
<button onclick="createHost()">1️⃣ Create Host Connection</button>
</div>
<div class="section">
<h3>Local Offer (SDP)</h3>
<textarea
id="offer-a"
readonly
placeholder="Offer will appear here..."
></textarea>
</div>
<div class="section">
<h3>Send Message</h3>
<div class="message-box">
<input
type="text"
id="message-a"
placeholder="Type a message..."
onkeypress="if (event.key === 'Enter') sendFromHost()"
/>
<button onclick="sendFromHost()">📤 Send</button>
</div>
</div>
<div class="section">
<h3>Activity Log</h3>
<div class="log" id="log-a"></div>
</div>
</div>
<!-- Peer B (Client) -->
<div class="peer">
<h2>Peer B (Client/Answerer)</h2>
<div class="status disconnected" id="status-b">Disconnected</div>
<div class="section">
<button onclick="createClient()">2️⃣ Create Client Connection</button>
</div>
<div class="section">
<h3>Local Answer (SDP)</h3>
<textarea
id="answer-b"
readonly
placeholder="Answer will appear here..."
></textarea>
</div>
<div class="section">
<h3>Send Message</h3>
<div class="message-box">
<input
type="text"
id="message-b"
placeholder="Type a message..."
onkeypress="if (event.key === 'Enter') sendFromClient()"
/>
<button onclick="sendFromClient()">📤 Send</button>
</div>
</div>
<div class="section">
<h3>Activity Log</h3>
<div class="log" id="log-b"></div>
</div>
</div>
</div>
</div>
<script type="module" src="/demo.js"></script>
</body>
</html>

6
src/connection.ts → src/durable-connection.ts
View File

@@ -71,15 +71,11 @@ export class WebRTCRondevuConnection implements ConnectionInterface {
public readonly ready: Promise<void> public readonly ready: Promise<void>
private iceBin = createBin() private iceBin = createBin()
private ctx: WebRTCContext private ctx: WebRTCContext
public id: string
public service: string
private _conn: RTCPeerConnection | null = null private _conn: RTCPeerConnection | null = null
private _state: ConnectionInterface['state'] = 'disconnected' private _state: ConnectionInterface['state'] = 'disconnected'
constructor({ context: ctx, offer, id, service }: WebRTCRondevuConnectionOptions) { constructor({ context: ctx, offer }: WebRTCRondevuConnectionOptions) {
this.ctx = ctx this.ctx = ctx
this.id = id
this.service = service
this._conn = ctx.createPeerConnection() this._conn = ctx.createPeerConnection()
this.side = offer ? 'answer' : 'offer' this.side = offer ? 'answer' : 'offer'

35
src/noop-signaler.ts
View File

@@ -1,35 +0,0 @@
import { Signaler } from './types.js'
import { Binnable } from './bin.js'
/**
* NoOpSignaler - A signaler that does nothing
* Used as a placeholder during connection setup before the real signaler is available
*/
export class NoOpSignaler implements Signaler {
addIceCandidate(_candidate: RTCIceCandidate): void {
// No-op
}
addListener(_callback: (candidate: RTCIceCandidate) => void): Binnable {
// Return no-op cleanup function
return () => {}
}
addOfferListener(_callback: (offer: RTCSessionDescriptionInit) => void): Binnable {
// Return no-op cleanup function
return () => {}
}
addAnswerListener(_callback: (answer: RTCSessionDescriptionInit) => void): Binnable {
// Return no-op cleanup function
return () => {}
}
async setOffer(_offer: RTCSessionDescriptionInit): Promise<void> {
// No-op
}
async setAnswer(_answer: RTCSessionDescriptionInit): Promise<void> {
// No-op
}
}

0
src/rondevu-context.ts Normal file
View File

0
src/rondevu-signaler.ts Normal file
View File

247
src/service-client.ts
View File

@@ -1,247 +0,0 @@
import { WebRTCRondevuConnection } from './connection.js'
import { WebRTCContext } from './webrtc-context.js'
import { RondevuService } from './rondevu-service.js'
import { RondevuSignaler } from './signaler.js'
import { EventBus } from './event-bus.js'
import { createBin } from './bin.js'
import { ConnectionInterface } from './types.js'
export interface ServiceClientOptions {
username: string
serviceFqn: string
rondevuService: RondevuService
autoReconnect?: boolean
reconnectDelay?: number
maxReconnectAttempts?: number
rtcConfiguration?: RTCConfiguration
}
export interface ServiceClientEvents {
connected: ConnectionInterface
disconnected: { reason: string }
reconnecting: { attempt: number; maxAttempts: number }
error: Error
}
/**
* ServiceClient - Connects to a hosted service
*
* Searches for available service offers and establishes a WebRTC connection.
* Optionally supports automatic reconnection on failure.
*
* @example
* ```typescript
* const rondevuService = new RondevuService({
* apiUrl: 'https://signal.example.com',
* username: 'client-user',
* })
*
* await rondevuService.initialize()
*
* const client = new ServiceClient({
* username: 'host-user',
* serviceFqn: 'chat.app@1.0.0',
* rondevuService,
* autoReconnect: true,
* })
*
* await client.connect()
*
* client.events.on('connected', (conn) => {
* console.log('Connected to service')
* conn.sendMessage('Hello!')
* })
* ```
*/
export class ServiceClient {
private readonly username: string
private readonly serviceFqn: string
private readonly rondevuService: RondevuService
private readonly autoReconnect: boolean
private readonly reconnectDelay: number
private readonly maxReconnectAttempts: number
private readonly rtcConfiguration?: RTCConfiguration
private connection: WebRTCRondevuConnection | null = null
private reconnectAttempts = 0
private reconnectTimeout: ReturnType<typeof setTimeout> | null = null
private readonly bin = createBin()
private isConnecting = false
public readonly events = new EventBus<ServiceClientEvents>()
constructor(options: ServiceClientOptions) {
this.username = options.username
this.serviceFqn = options.serviceFqn
this.rondevuService = options.rondevuService
this.autoReconnect = options.autoReconnect !== false
this.reconnectDelay = options.reconnectDelay || 2000
this.maxReconnectAttempts = options.maxReconnectAttempts || 5
this.rtcConfiguration = options.rtcConfiguration
}
/**
* Connect to the service
*/
async connect(): Promise<WebRTCRondevuConnection> {
if (this.isConnecting) {
throw new Error('Already connecting')
}
if (this.connection && this.connection.state === 'connected') {
return this.connection
}
this.isConnecting = true
try {
// Search for available services
const services = await this.rondevuService
.getAPI()
.searchServices(this.username, this.serviceFqn)
if (services.length === 0) {
throw new Error(`No services found for ${this.username}/${this.serviceFqn}`)
}
// Get the first available service
const service = services[0]
// Get service details including SDP
const serviceDetails = await this.rondevuService.getAPI().getService(service.uuid)
// Create WebRTC context with signaler for this offer
const signaler = new RondevuSignaler(
this.rondevuService.getAPI(),
serviceDetails.offerId
)
const context = new WebRTCContext(signaler, this.rtcConfiguration)
// Create connection (answerer role)
const conn = new WebRTCRondevuConnection({
id: `client-${this.serviceFqn}-${Date.now()}`,
service: this.serviceFqn,
offer: {
type: 'offer',
sdp: serviceDetails.sdp,
},
context,
})
// Wait for answer to be created
await conn.ready
// Get answer SDP
if (!conn.connection?.localDescription?.sdp) {
throw new Error('Failed to create answer SDP')
}
const answerSdp = conn.connection.localDescription.sdp
// Send answer to server
await this.rondevuService.getAPI().answerOffer(serviceDetails.offerId, answerSdp)
// Track connection
this.connection = conn
this.reconnectAttempts = 0
// Listen for state changes
const cleanup = conn.events.on('state-change', state => {
this.handleConnectionStateChange(state)
})
this.bin(cleanup)
this.isConnecting = false
// Emit connected event when actually connected
if (conn.state === 'connected') {
this.events.emit('connected', conn)
}
return conn
} catch (error) {
this.isConnecting = false
this.events.emit('error', error as Error)
throw error
}
}
/**
* Disconnect from the service
*/
disconnect(): void {
if (this.reconnectTimeout) {
clearTimeout(this.reconnectTimeout)
this.reconnectTimeout = null
}
if (this.connection) {
this.connection.disconnect()
this.connection = null
}
this.bin.clean()
this.reconnectAttempts = 0
}
/**
* Get the current connection
*/
getConnection(): WebRTCRondevuConnection | null {
return this.connection
}
/**
* Check if currently connected
*/
isConnected(): boolean {
return this.connection?.state === 'connected'
}
/**
* Handle connection state changes
*/
private handleConnectionStateChange(state: ConnectionInterface['state']): void {
if (state === 'connected') {
this.events.emit('connected', this.connection!)
this.reconnectAttempts = 0
} else if (state === 'disconnected') {
this.events.emit('disconnected', { reason: 'Connection closed' })
// Attempt reconnection if enabled
if (this.autoReconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
this.scheduleReconnect()
}
}
}
/**
* Schedule a reconnection attempt
*/
private scheduleReconnect(): void {
if (this.reconnectTimeout) {
return
}
this.reconnectAttempts++
this.events.emit('reconnecting', {
attempt: this.reconnectAttempts,
maxAttempts: this.maxReconnectAttempts,
})
// Exponential backoff
const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1)
this.reconnectTimeout = setTimeout(() => {
this.reconnectTimeout = null
this.connect().catch(error => {
this.events.emit('error', error as Error)
// Schedule next attempt if we haven't exceeded max attempts
if (this.reconnectAttempts < this.maxReconnectAttempts) {
this.scheduleReconnect()
}
})
}, delay)
}
}

239
src/service-host.ts
View File

@@ -1,239 +0,0 @@
import { WebRTCRondevuConnection } from './connection.js'
import { WebRTCContext } from './webrtc-context.js'
import { RondevuService } from './rondevu-service.js'
import { RondevuSignaler } from './signaler.js'
import { NoOpSignaler } from './noop-signaler.js'
import { EventBus } from './event-bus.js'
import { createBin } from './bin.js'
import { ConnectionInterface } from './types.js'
export interface ServiceHostOptions {
service: string
rondevuService: RondevuService
maxPeers?: number
ttl?: number
isPublic?: boolean
metadata?: Record<string, any>
rtcConfiguration?: RTCConfiguration
}
export interface ServiceHostEvents {
connection: ConnectionInterface
'connection-closed': { connectionId: string; reason: string }
error: Error
}
/**
* ServiceHost - Manages a pool of WebRTC offers for a service
*
* Maintains up to maxPeers concurrent offers, automatically replacing
* them when connections are established or expire.
*
* @example
* ```typescript
* const rondevuService = new RondevuService({
* apiUrl: 'https://signal.example.com',
* username: 'myusername',
* })
*
* await rondevuService.initialize()
* await rondevuService.claimUsername()
*
* const host = new ServiceHost({
* service: 'chat.app@1.0.0',
* rondevuService,
* maxPeers: 5,
* })
*
* await host.start()
*
* host.events.on('connection', (conn) => {
* console.log('New connection:', conn.id)
* conn.events.on('message', (msg) => {
* console.log('Message:', msg)
* })
* })
* ```
*/
export class ServiceHost {
private connections = new Map<string, WebRTCRondevuConnection>()
private readonly service: string
private readonly rondevuService: RondevuService
private readonly maxPeers: number
private readonly ttl: number
private readonly isPublic: boolean
private readonly metadata?: Record<string, any>
private readonly rtcConfiguration?: RTCConfiguration
private readonly bin = createBin()
private isStarted = false
public readonly events = new EventBus<ServiceHostEvents>()
constructor(options: ServiceHostOptions) {
this.service = options.service
this.rondevuService = options.rondevuService
this.maxPeers = options.maxPeers || 20
this.ttl = options.ttl || 300000
this.isPublic = options.isPublic !== false
this.metadata = options.metadata
this.rtcConfiguration = options.rtcConfiguration
}
/**
* Start hosting the service - creates initial pool of offers
*/
async start(): Promise<void> {
if (this.isStarted) {
throw new Error('ServiceHost already started')
}
this.isStarted = true
await this.fillOfferPool()
}
/**
* Stop hosting - closes all connections and cleans up
*/
stop(): void {
this.isStarted = false
this.connections.forEach(conn => conn.disconnect())
this.connections.clear()
this.bin.clean()
}
/**
* Get current number of active connections
*/
getConnectionCount(): number {
return Array.from(this.connections.values()).filter(conn => conn.state === 'connected')
.length
}
/**
* Get current number of pending offers
*/
getPendingOfferCount(): number {
return Array.from(this.connections.values()).filter(conn => conn.state === 'connecting')
.length
}
/**
* Fill the offer pool up to maxPeers
*/
private async fillOfferPool(): Promise<void> {
const currentOffers = this.connections.size
const needed = this.maxPeers - currentOffers
if (needed <= 0) {
return
}
// Create multiple offers in parallel
const offerPromises: Promise<void>[] = []
for (let i = 0; i < needed; i++) {
offerPromises.push(this.createOffer())
}
await Promise.allSettled(offerPromises)
}
/**
* Create a single offer and publish it
*/
private async createOffer(): Promise<void> {
try {
// Create temporary context with NoOp signaler
const tempContext = new WebRTCContext(new NoOpSignaler(), this.rtcConfiguration)
// Create connection (offerer role)
const conn = new WebRTCRondevuConnection({
id: `${this.service}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
service: this.service,
offer: null,
context: tempContext,
})
// Wait for offer to be created
await conn.ready
// Get offer SDP
if (!conn.connection?.localDescription?.sdp) {
throw new Error('Failed to create offer SDP')
}
const sdp = conn.connection.localDescription.sdp
// Publish service offer
const service = await this.rondevuService.publishService({
serviceFqn: this.service,
sdp,
ttl: this.ttl,
isPublic: this.isPublic,
metadata: this.metadata,
})
// Replace with real signaler now that we have offerId
const realSignaler = new RondevuSignaler(this.rondevuService.getAPI(), service.offerId)
;(tempContext as any).signaler = realSignaler
// Track connection
this.connections.set(conn.id, conn)
// Listen for state changes
const cleanup = conn.events.on('state-change', state => {
this.handleConnectionStateChange(conn, state)
})
this.bin(cleanup)
} catch (error) {
this.events.emit('error', error as Error)
}
}
/**
* Handle connection state changes
*/
private handleConnectionStateChange(
conn: WebRTCRondevuConnection,
state: ConnectionInterface['state']
): void {
if (state === 'connected') {
// Connection established - emit event
this.events.emit('connection', conn)
// Create new offer to replace this one
if (this.isStarted) {
this.fillOfferPool().catch(error => {
this.events.emit('error', error as Error)
})
}
} else if (state === 'disconnected') {
// Connection closed - remove and create new offer
this.connections.delete(conn.id)
this.events.emit('connection-closed', {
connectionId: conn.id,
reason: state,
})
if (this.isStarted) {
this.fillOfferPool().catch(error => {
this.events.emit('error', error as Error)
})
}
}
}
/**
* Get all active connections
*/
getConnections(): WebRTCRondevuConnection[] {
return Array.from(this.connections.values())
}
/**
* Get a specific connection by ID
*/
getConnection(connectionId: string): WebRTCRondevuConnection | undefined {
return this.connections.get(connectionId)
}
}

10
vite.config.js
View File

@@ -1,10 +0,0 @@
import { defineConfig } from 'vite';
export default defineConfig({
root: 'demo',
server: {
port: 3000,
open: true,
allowedHosts: ['241284034b20.ngrok-free.app']
}
});