mirror of
https://github.com/xtr-dev/rondevu-client.git
synced 2025-12-08 00:33:24 +00:00
feat: v0.9.0 - durable WebRTC connections with automatic reconnection
Major refactor replacing low-level APIs with high-level durable connections.
New Features:
- Automatic reconnection with exponential backoff (1s → 2s → 4s → ... max 30s)
- Message queuing during disconnections
- Durable channels that survive connection drops
- TTL auto-refresh for services (refreshes at 80% of TTL by default)
- Full configuration of timeouts, retry limits, and queue sizes
New API:
- client.exposeService() - Create durable service with automatic TTL refresh
- client.connect() - Create durable connection with automatic reconnection
- client.connectByUuid() - Connect by service UUID
- DurableChannel - Event-based channel wrapper with message queuing
- DurableConnection - Connection manager with reconnection logic
- DurableService - Service manager with TTL auto-refresh
Files Added:
- src/durable/types.ts - Type definitions and enums
- src/durable/reconnection.ts - Exponential backoff utilities
- src/durable/channel.ts - DurableChannel class (358 lines)
- src/durable/connection.ts - DurableConnection class (441 lines)
- src/durable/service.ts - DurableService class (329 lines)
- MIGRATION.md - Comprehensive migration guide
Files Removed:
- src/services.ts - Replaced by DurableService
- src/discovery.ts - Replaced by DurableConnection
BREAKING CHANGES:
- Removed: client.services.*, client.discovery.*, client.createPeer()
- Added: client.exposeService(), client.connect(), client.connectByUuid()
- Handler signature: (channel, peer, connectionId?) → (channel, connectionId)
- Event handlers: .onmessage → .on('message')
- Services: Must call service.start() to begin accepting connections
- Connections: Must call connection.connect() to establish connection
This commit is contained in:
547
MIGRATION.md
Normal file
547
MIGRATION.md
Normal file
@@ -0,0 +1,547 @@
|
||||
# Migration Guide: v0.8.x → v0.9.0
|
||||
|
||||
This guide helps you migrate from Rondevu Client v0.8.x to v0.9.0.
|
||||
|
||||
## Overview
|
||||
|
||||
v0.9.0 is a **breaking change** that completely replaces low-level APIs with high-level durable connections featuring automatic reconnection and message queuing.
|
||||
|
||||
### What's New
|
||||
|
||||
✅ **Durable Connections**: Automatic reconnection on network drops
|
||||
✅ **Message Queuing**: Messages sent during disconnections are queued and flushed on reconnect
|
||||
✅ **Durable Channels**: RTCDataChannel wrappers that survive connection drops
|
||||
✅ **TTL Auto-Refresh**: Services automatically republish before expiration
|
||||
✅ **Simplified API**: Direct methods on main client instead of nested APIs
|
||||
|
||||
### What's Removed
|
||||
|
||||
❌ **Low-level APIs**: `client.services.*`, `client.discovery.*`, `client.createPeer()` no longer exported
|
||||
❌ **Manual Connection Management**: No need to handle WebRTC peer lifecycle manually
|
||||
❌ **Service Handles**: Replaced with DurableService instances
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
### 1. Service Exposure
|
||||
|
||||
#### v0.8.x (Old)
|
||||
```typescript
|
||||
import { Rondevu } from '@xtr-dev/rondevu-client';
|
||||
|
||||
const client = new Rondevu();
|
||||
await client.register();
|
||||
|
||||
const handle = await client.services.exposeService({
|
||||
username: 'alice',
|
||||
privateKey: keypair.privateKey,
|
||||
serviceFqn: 'chat@1.0.0',
|
||||
isPublic: true,
|
||||
handler: (channel, peer) => {
|
||||
channel.onmessage = (e) => {
|
||||
console.log('Received:', e.data);
|
||||
channel.send(`Echo: ${e.data}`);
|
||||
};
|
||||
}
|
||||
});
|
||||
|
||||
// Unpublish
|
||||
await handle.unpublish();
|
||||
```
|
||||
|
||||
#### v0.9.0 (New)
|
||||
```typescript
|
||||
import { Rondevu } from '@xtr-dev/rondevu-client';
|
||||
|
||||
const client = new Rondevu();
|
||||
await client.register();
|
||||
|
||||
const service = await client.exposeService({
|
||||
username: 'alice',
|
||||
privateKey: keypair.privateKey,
|
||||
serviceFqn: 'chat@1.0.0',
|
||||
isPublic: true,
|
||||
poolSize: 10, // NEW: Handle multiple concurrent connections
|
||||
handler: (channel, connectionId) => {
|
||||
// NEW: DurableChannel with event emitters
|
||||
channel.on('message', (data) => {
|
||||
console.log('Received:', data);
|
||||
channel.send(`Echo: ${data}`);
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
// NEW: Start the service
|
||||
await service.start();
|
||||
|
||||
// NEW: Stop the service
|
||||
await service.stop();
|
||||
```
|
||||
|
||||
**Key Differences:**
|
||||
- `client.services.exposeService()` → `client.exposeService()`
|
||||
- Returns `DurableService` instead of `ServiceHandle`
|
||||
- Handler receives `DurableChannel` instead of `RTCDataChannel`
|
||||
- Handler receives `connectionId` string instead of `RondevuPeer`
|
||||
- DurableChannel uses `.on('message', ...)` instead of `.onmessage = ...`
|
||||
- Must call `service.start()` to begin accepting connections
|
||||
- Use `service.stop()` instead of `handle.unpublish()`
|
||||
|
||||
### 2. Connecting to Services
|
||||
|
||||
#### v0.8.x (Old)
|
||||
```typescript
|
||||
// Connect by username + FQN
|
||||
const { peer, channel } = await client.discovery.connect(
|
||||
'alice',
|
||||
'chat@1.0.0'
|
||||
);
|
||||
|
||||
channel.onmessage = (e) => {
|
||||
console.log('Received:', e.data);
|
||||
};
|
||||
|
||||
channel.onopen = () => {
|
||||
channel.send('Hello!');
|
||||
};
|
||||
|
||||
peer.on('connected', () => {
|
||||
console.log('Connected');
|
||||
});
|
||||
|
||||
peer.on('failed', (error) => {
|
||||
console.error('Failed:', error);
|
||||
});
|
||||
```
|
||||
|
||||
#### v0.9.0 (New)
|
||||
```typescript
|
||||
// Connect by username + FQN
|
||||
const connection = await client.connect('alice', 'chat@1.0.0', {
|
||||
maxReconnectAttempts: 10 // NEW: Configurable reconnection
|
||||
});
|
||||
|
||||
// NEW: Create durable channel
|
||||
const channel = connection.createChannel('main');
|
||||
|
||||
channel.on('message', (data) => {
|
||||
console.log('Received:', data);
|
||||
});
|
||||
|
||||
channel.on('open', () => {
|
||||
channel.send('Hello!');
|
||||
});
|
||||
|
||||
// NEW: Connection lifecycle events
|
||||
connection.on('connected', () => {
|
||||
console.log('Connected');
|
||||
});
|
||||
|
||||
connection.on('reconnecting', (attempt, max, delay) => {
|
||||
console.log(`Reconnecting (${attempt}/${max})...`);
|
||||
});
|
||||
|
||||
connection.on('failed', (error) => {
|
||||
console.error('Failed permanently:', error);
|
||||
});
|
||||
|
||||
// NEW: Must explicitly connect
|
||||
await connection.connect();
|
||||
```
|
||||
|
||||
**Key Differences:**
|
||||
- `client.discovery.connect()` → `client.connect()`
|
||||
- Returns `DurableConnection` instead of `{ peer, channel }`
|
||||
- Must create channels with `connection.createChannel()`
|
||||
- Must call `connection.connect()` to establish connection
|
||||
- Automatic reconnection with configurable retry limits
|
||||
- Messages sent during disconnection are automatically queued
|
||||
|
||||
### 3. Connecting by UUID
|
||||
|
||||
#### v0.8.x (Old)
|
||||
```typescript
|
||||
const { peer, channel } = await client.discovery.connectByUuid('service-uuid');
|
||||
|
||||
channel.onmessage = (e) => {
|
||||
console.log('Received:', e.data);
|
||||
};
|
||||
```
|
||||
|
||||
#### v0.9.0 (New)
|
||||
```typescript
|
||||
const connection = await client.connectByUuid('service-uuid', {
|
||||
maxReconnectAttempts: 5
|
||||
});
|
||||
|
||||
const channel = connection.createChannel('main');
|
||||
|
||||
channel.on('message', (data) => {
|
||||
console.log('Received:', data);
|
||||
});
|
||||
|
||||
await connection.connect();
|
||||
```
|
||||
|
||||
**Key Differences:**
|
||||
- `client.discovery.connectByUuid()` → `client.connectByUuid()`
|
||||
- Returns `DurableConnection` instead of `{ peer, channel }`
|
||||
- Must create channels and connect explicitly
|
||||
|
||||
### 4. Multi-Connection Services (Offer Pooling)
|
||||
|
||||
#### v0.8.x (Old)
|
||||
```typescript
|
||||
const handle = await client.services.exposeService({
|
||||
username: 'alice',
|
||||
privateKey: keypair.privateKey,
|
||||
serviceFqn: 'chat@1.0.0',
|
||||
poolSize: 5,
|
||||
pollingInterval: 2000,
|
||||
handler: (channel, peer, connectionId) => {
|
||||
console.log(`Connection: ${connectionId}`);
|
||||
},
|
||||
onPoolStatus: (status) => {
|
||||
console.log('Pool status:', status);
|
||||
}
|
||||
});
|
||||
|
||||
const status = handle.getStatus();
|
||||
await handle.addOffers(3);
|
||||
```
|
||||
|
||||
#### v0.9.0 (New)
|
||||
```typescript
|
||||
const service = await client.exposeService({
|
||||
username: 'alice',
|
||||
privateKey: keypair.privateKey,
|
||||
serviceFqn: 'chat@1.0.0',
|
||||
poolSize: 5, // SAME: Pool size
|
||||
pollingInterval: 2000, // SAME: Polling interval
|
||||
handler: (channel, connectionId) => {
|
||||
console.log(`Connection: ${connectionId}`);
|
||||
}
|
||||
});
|
||||
|
||||
await service.start();
|
||||
|
||||
// Get active connections
|
||||
const connections = service.getActiveConnections();
|
||||
|
||||
// Listen for connection events
|
||||
service.on('connection', (connectionId) => {
|
||||
console.log('New connection:', connectionId);
|
||||
});
|
||||
```
|
||||
|
||||
**Key Differences:**
|
||||
- `onPoolStatus` callback removed (use `service.on('connection')` instead)
|
||||
- `handle.getStatus()` replaced with `service.getActiveConnections()`
|
||||
- `handle.addOffers()` removed (pool auto-manages offers)
|
||||
- Handler receives `DurableChannel` instead of `RTCDataChannel`
|
||||
|
||||
## Feature Comparison
|
||||
|
||||
| Feature | v0.8.x | v0.9.0 |
|
||||
|---------|--------|--------|
|
||||
| Service exposure | `client.services.exposeService()` | `client.exposeService()` |
|
||||
| Connection | `client.discovery.connect()` | `client.connect()` |
|
||||
| Connection by UUID | `client.discovery.connectByUuid()` | `client.connectByUuid()` |
|
||||
| Channel type | `RTCDataChannel` | `DurableChannel` |
|
||||
| Event handling | `.onmessage`, `.onopen`, etc. | `.on('message')`, `.on('open')`, etc. |
|
||||
| Automatic reconnection | ❌ No | ✅ Yes (configurable) |
|
||||
| Message queuing | ❌ No | ✅ Yes (during disconnections) |
|
||||
| TTL auto-refresh | ❌ No | ✅ Yes (configurable) |
|
||||
| Peer lifecycle | Manual | Automatic |
|
||||
| Connection pooling | ✅ Yes | ✅ Yes (same API) |
|
||||
|
||||
## API Mapping
|
||||
|
||||
### Removed Exports
|
||||
|
||||
These are no longer exported in v0.9.0:
|
||||
|
||||
```typescript
|
||||
// ❌ Removed
|
||||
import {
|
||||
RondevuServices,
|
||||
RondevuDiscovery,
|
||||
RondevuPeer,
|
||||
ServiceHandle,
|
||||
PooledServiceHandle,
|
||||
ConnectResult
|
||||
} from '@xtr-dev/rondevu-client';
|
||||
```
|
||||
|
||||
### New Exports
|
||||
|
||||
These are new in v0.9.0:
|
||||
|
||||
```typescript
|
||||
// ✅ New
|
||||
import {
|
||||
DurableConnection,
|
||||
DurableChannel,
|
||||
DurableService,
|
||||
DurableConnectionState,
|
||||
DurableChannelState,
|
||||
DurableConnectionConfig,
|
||||
DurableChannelConfig,
|
||||
DurableServiceConfig,
|
||||
DurableConnectionEvents,
|
||||
DurableChannelEvents,
|
||||
DurableServiceEvents,
|
||||
ConnectionInfo,
|
||||
ServiceInfo,
|
||||
QueuedMessage
|
||||
} from '@xtr-dev/rondevu-client';
|
||||
```
|
||||
|
||||
### Unchanged Exports
|
||||
|
||||
These work the same in both versions:
|
||||
|
||||
```typescript
|
||||
// ✅ Unchanged
|
||||
import {
|
||||
Rondevu,
|
||||
RondevuAuth,
|
||||
RondevuUsername,
|
||||
Credentials,
|
||||
UsernameClaimResult,
|
||||
UsernameCheckResult
|
||||
} from '@xtr-dev/rondevu-client';
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### New Connection Options
|
||||
|
||||
v0.9.0 adds extensive configuration for automatic reconnection and message queuing:
|
||||
|
||||
```typescript
|
||||
const connection = await client.connect('alice', 'chat@1.0.0', {
|
||||
// Reconnection
|
||||
maxReconnectAttempts: 10, // default: 10
|
||||
reconnectBackoffBase: 1000, // default: 1000ms
|
||||
reconnectBackoffMax: 30000, // default: 30000ms (30 seconds)
|
||||
reconnectJitter: 0.2, // default: 0.2 (±20%)
|
||||
connectionTimeout: 30000, // default: 30000ms
|
||||
|
||||
// Message queuing
|
||||
maxQueueSize: 1000, // default: 1000 messages
|
||||
maxMessageAge: 60000, // default: 60000ms (1 minute)
|
||||
|
||||
// WebRTC
|
||||
rtcConfig: {
|
||||
iceServers: [...]
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### New Service Options
|
||||
|
||||
Services can now auto-refresh TTL:
|
||||
|
||||
```typescript
|
||||
const service = await client.exposeService({
|
||||
username: 'alice',
|
||||
privateKey: keypair.privateKey,
|
||||
serviceFqn: 'chat@1.0.0',
|
||||
|
||||
// TTL auto-refresh (NEW)
|
||||
ttl: 300000, // default: 300000ms (5 minutes)
|
||||
ttlRefreshMargin: 0.2, // default: 0.2 (refresh at 80% of TTL)
|
||||
|
||||
// All connection options also apply to incoming connections
|
||||
maxReconnectAttempts: 10,
|
||||
maxQueueSize: 1000,
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
- [ ] Replace `client.services.exposeService()` with `client.exposeService()`
|
||||
- [ ] Add `await service.start()` after creating service
|
||||
- [ ] Replace `handle.unpublish()` with `service.stop()`
|
||||
- [ ] Replace `client.discovery.connect()` with `client.connect()`
|
||||
- [ ] Replace `client.discovery.connectByUuid()` with `client.connectByUuid()`
|
||||
- [ ] Create channels with `connection.createChannel()` instead of receiving them directly
|
||||
- [ ] Add `await connection.connect()` to establish connection
|
||||
- [ ] Update handlers from `(channel, peer, connectionId?)` to `(channel, connectionId)`
|
||||
- [ ] Replace `.onmessage` with `.on('message', ...)`
|
||||
- [ ] Replace `.onopen` with `.on('open', ...)`
|
||||
- [ ] Replace `.onclose` with `.on('close', ...)`
|
||||
- [ ] Replace `.onerror` with `.on('error', ...)`
|
||||
- [ ] Add reconnection event handlers (`connection.on('reconnecting', ...)`)
|
||||
- [ ] Review and configure reconnection options if needed
|
||||
- [ ] Review and configure message queue limits if needed
|
||||
- [ ] Update TypeScript imports to use new types
|
||||
- [ ] Test automatic reconnection behavior
|
||||
- [ ] Test message queuing during disconnections
|
||||
|
||||
## Common Migration Patterns
|
||||
|
||||
### Pattern 1: Simple Echo Service
|
||||
|
||||
#### Before (v0.8.x)
|
||||
```typescript
|
||||
await client.services.exposeService({
|
||||
username: 'alice',
|
||||
privateKey: keypair.privateKey,
|
||||
serviceFqn: 'echo@1.0.0',
|
||||
handler: (channel) => {
|
||||
channel.onmessage = (e) => {
|
||||
channel.send(`Echo: ${e.data}`);
|
||||
};
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### After (v0.9.0)
|
||||
```typescript
|
||||
const service = await client.exposeService({
|
||||
username: 'alice',
|
||||
privateKey: keypair.privateKey,
|
||||
serviceFqn: 'echo@1.0.0',
|
||||
handler: (channel) => {
|
||||
channel.on('message', (data) => {
|
||||
channel.send(`Echo: ${data}`);
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
await service.start();
|
||||
```
|
||||
|
||||
### Pattern 2: Connection with Error Handling
|
||||
|
||||
#### Before (v0.8.x)
|
||||
```typescript
|
||||
try {
|
||||
const { peer, channel } = await client.discovery.connect('alice', 'chat@1.0.0');
|
||||
|
||||
channel.onopen = () => {
|
||||
channel.send('Hello!');
|
||||
};
|
||||
|
||||
peer.on('failed', (error) => {
|
||||
console.error('Connection failed:', error);
|
||||
// Manual reconnection logic here
|
||||
});
|
||||
} catch (error) {
|
||||
console.error('Failed to connect:', error);
|
||||
}
|
||||
```
|
||||
|
||||
#### After (v0.9.0)
|
||||
```typescript
|
||||
const connection = await client.connect('alice', 'chat@1.0.0', {
|
||||
maxReconnectAttempts: 5
|
||||
});
|
||||
|
||||
const channel = connection.createChannel('main');
|
||||
|
||||
channel.on('open', () => {
|
||||
channel.send('Hello!');
|
||||
});
|
||||
|
||||
connection.on('reconnecting', (attempt, max, delay) => {
|
||||
console.log(`Reconnecting (${attempt}/${max}) in ${delay}ms`);
|
||||
});
|
||||
|
||||
connection.on('failed', (error) => {
|
||||
console.error('Connection failed permanently:', error);
|
||||
});
|
||||
|
||||
try {
|
||||
await connection.connect();
|
||||
} catch (error) {
|
||||
console.error('Initial connection failed:', error);
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 3: Multi-User Chat Server
|
||||
|
||||
#### Before (v0.8.x)
|
||||
```typescript
|
||||
const connections = new Map();
|
||||
|
||||
await client.services.exposeService({
|
||||
username: 'alice',
|
||||
privateKey: keypair.privateKey,
|
||||
serviceFqn: 'chat@1.0.0',
|
||||
poolSize: 10,
|
||||
handler: (channel, peer, connectionId) => {
|
||||
connections.set(connectionId, channel);
|
||||
|
||||
channel.onmessage = (e) => {
|
||||
// Broadcast to all
|
||||
for (const [id, ch] of connections) {
|
||||
if (id !== connectionId) {
|
||||
ch.send(e.data);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
channel.onclose = () => {
|
||||
connections.delete(connectionId);
|
||||
};
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### After (v0.9.0)
|
||||
```typescript
|
||||
const channels = new Map();
|
||||
|
||||
const service = await client.exposeService({
|
||||
username: 'alice',
|
||||
privateKey: keypair.privateKey,
|
||||
serviceFqn: 'chat@1.0.0',
|
||||
poolSize: 10,
|
||||
handler: (channel, connectionId) => {
|
||||
channels.set(connectionId, channel);
|
||||
|
||||
channel.on('message', (data) => {
|
||||
// Broadcast to all
|
||||
for (const [id, ch] of channels) {
|
||||
if (id !== connectionId) {
|
||||
ch.send(data);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
channel.on('close', () => {
|
||||
channels.delete(connectionId);
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
await service.start();
|
||||
|
||||
// Optional: Track connections
|
||||
service.on('connection', (connectionId) => {
|
||||
console.log(`User ${connectionId} joined`);
|
||||
});
|
||||
|
||||
service.on('disconnection', (connectionId) => {
|
||||
console.log(`User ${connectionId} left`);
|
||||
});
|
||||
```
|
||||
|
||||
## Benefits of Migration
|
||||
|
||||
1. **Reliability**: Automatic reconnection handles network hiccups transparently
|
||||
2. **Simplicity**: No need to manage WebRTC peer lifecycle manually
|
||||
3. **Durability**: Messages sent during disconnections are queued and delivered when connection restores
|
||||
4. **Uptime**: Services automatically refresh TTL before expiration
|
||||
5. **Type Safety**: Better TypeScript types with DurableChannel event emitters
|
||||
6. **Debugging**: Queue size monitoring, connection state tracking, and detailed events
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues during migration:
|
||||
1. Check the [README](./README.md) for complete API documentation
|
||||
2. Review the examples for common patterns
|
||||
3. Open an issue on [GitHub](https://github.com/xtr-dev/rondevu-client/issues)
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "@xtr-dev/rondevu-client",
|
||||
"version": "0.8.3",
|
||||
"description": "TypeScript client for Rondevu DNS-like WebRTC with username claiming and service discovery",
|
||||
"version": "0.9.0",
|
||||
"description": "TypeScript client for Rondevu with durable WebRTC connections, automatic reconnection, and message queuing",
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
"types": "dist/index.d.ts",
|
||||
|
||||
276
src/discovery.ts
276
src/discovery.ts
@@ -1,276 +0,0 @@
|
||||
import RondevuPeer from './peer/index.js';
|
||||
import { RondevuOffers } from './offers.js';
|
||||
|
||||
/**
|
||||
* Service info from discovery
|
||||
*/
|
||||
export interface ServiceInfo {
|
||||
uuid: string;
|
||||
isPublic: boolean;
|
||||
serviceFqn?: string;
|
||||
metadata?: Record<string, any>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Service list result
|
||||
*/
|
||||
export interface ServiceListResult {
|
||||
username: string;
|
||||
services: ServiceInfo[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Service query result
|
||||
*/
|
||||
export interface ServiceQueryResult {
|
||||
uuid: string;
|
||||
allowed: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Service details
|
||||
*/
|
||||
export interface ServiceDetails {
|
||||
serviceId: string;
|
||||
username: string;
|
||||
serviceFqn: string;
|
||||
offerId: string;
|
||||
sdp: string;
|
||||
isPublic: boolean;
|
||||
metadata?: Record<string, any>;
|
||||
createdAt: number;
|
||||
expiresAt: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Connect result
|
||||
*/
|
||||
export interface ConnectResult {
|
||||
peer: RondevuPeer;
|
||||
channel: RTCDataChannel;
|
||||
}
|
||||
|
||||
/**
|
||||
* Rondevu Discovery API
|
||||
* Handles service discovery and connections
|
||||
*/
|
||||
export class RondevuDiscovery {
|
||||
private offersApi: RondevuOffers;
|
||||
|
||||
constructor(
|
||||
private baseUrl: string,
|
||||
private credentials: { peerId: string; secret: string }
|
||||
) {
|
||||
this.offersApi = new RondevuOffers(baseUrl, credentials);
|
||||
}
|
||||
|
||||
/**
|
||||
* Lists all services for a username
|
||||
* Returns UUIDs only for private services, full details for public
|
||||
*/
|
||||
async listServices(username: string): Promise<ServiceListResult> {
|
||||
const response = await fetch(`${this.baseUrl}/usernames/${username}/services`);
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error('Failed to list services');
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
return {
|
||||
username: data.username,
|
||||
services: data.services
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Queries a service by FQN
|
||||
* Returns UUID if service exists and is allowed
|
||||
*/
|
||||
async queryService(username: string, serviceFqn: string): Promise<ServiceQueryResult> {
|
||||
const response = await fetch(`${this.baseUrl}/index/${username}/query`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ serviceFqn })
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(error.error || 'Service not found');
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
return {
|
||||
uuid: data.uuid,
|
||||
allowed: data.allowed
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets service details by UUID
|
||||
*/
|
||||
async getServiceDetails(uuid: string): Promise<ServiceDetails> {
|
||||
const response = await fetch(`${this.baseUrl}/services/${uuid}`);
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(error.error || 'Service not found');
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
return {
|
||||
serviceId: data.serviceId,
|
||||
username: data.username,
|
||||
serviceFqn: data.serviceFqn,
|
||||
offerId: data.offerId,
|
||||
sdp: data.sdp,
|
||||
isPublic: data.isPublic,
|
||||
metadata: data.metadata,
|
||||
createdAt: data.createdAt,
|
||||
expiresAt: data.expiresAt
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Connects to a service by UUID
|
||||
*/
|
||||
async connectToService(
|
||||
uuid: string,
|
||||
options?: {
|
||||
rtcConfig?: RTCConfiguration;
|
||||
onConnected?: () => void;
|
||||
onData?: (data: any) => void;
|
||||
}
|
||||
): Promise<RondevuPeer> {
|
||||
// Get service details
|
||||
const service = await this.getServiceDetails(uuid);
|
||||
|
||||
// Create peer with the offer
|
||||
const peer = new RondevuPeer(
|
||||
this.offersApi,
|
||||
options?.rtcConfig || {
|
||||
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
|
||||
}
|
||||
);
|
||||
|
||||
// Set up event handlers
|
||||
if (options?.onConnected) {
|
||||
peer.on('connected', options.onConnected);
|
||||
}
|
||||
|
||||
if (options?.onData) {
|
||||
peer.on('datachannel', (channel: RTCDataChannel) => {
|
||||
channel.onmessage = (e) => options.onData!(e.data);
|
||||
});
|
||||
}
|
||||
|
||||
// Answer the offer
|
||||
await peer.answer(service.offerId, service.sdp, {
|
||||
topics: [], // V2 doesn't use topics
|
||||
rtcConfig: options?.rtcConfig
|
||||
});
|
||||
|
||||
return peer;
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience method: Query and connect in one call
|
||||
* Returns both peer and data channel
|
||||
*/
|
||||
async connect(
|
||||
username: string,
|
||||
serviceFqn: string,
|
||||
options?: {
|
||||
rtcConfig?: RTCConfiguration;
|
||||
}
|
||||
): Promise<ConnectResult> {
|
||||
// Query service
|
||||
const query = await this.queryService(username, serviceFqn);
|
||||
|
||||
if (!query.allowed) {
|
||||
throw new Error('Service access denied');
|
||||
}
|
||||
|
||||
// Get service details
|
||||
const service = await this.getServiceDetails(query.uuid);
|
||||
|
||||
// Create peer
|
||||
const peer = new RondevuPeer(
|
||||
this.offersApi,
|
||||
options?.rtcConfig || {
|
||||
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
|
||||
}
|
||||
);
|
||||
|
||||
// Answer the offer
|
||||
await peer.answer(service.offerId, service.sdp, {
|
||||
topics: [], // V2 doesn't use topics
|
||||
rtcConfig: options?.rtcConfig
|
||||
});
|
||||
|
||||
// Wait for data channel
|
||||
const channel = await new Promise<RTCDataChannel>((resolve, reject) => {
|
||||
const timeout = setTimeout(() => {
|
||||
reject(new Error('Timeout waiting for data channel'));
|
||||
}, 30000);
|
||||
|
||||
peer.on('datachannel', (ch: RTCDataChannel) => {
|
||||
clearTimeout(timeout);
|
||||
resolve(ch);
|
||||
});
|
||||
|
||||
peer.on('failed', (error: Error) => {
|
||||
clearTimeout(timeout);
|
||||
reject(error);
|
||||
});
|
||||
});
|
||||
|
||||
return { peer, channel };
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience method: Connect to service by UUID with channel
|
||||
*/
|
||||
async connectByUuid(
|
||||
uuid: string,
|
||||
options?: { rtcConfig?: RTCConfiguration }
|
||||
): Promise<ConnectResult> {
|
||||
// Get service details
|
||||
const service = await this.getServiceDetails(uuid);
|
||||
|
||||
// Create peer
|
||||
const peer = new RondevuPeer(
|
||||
this.offersApi,
|
||||
options?.rtcConfig || {
|
||||
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
|
||||
}
|
||||
);
|
||||
|
||||
// Answer the offer
|
||||
await peer.answer(service.offerId, service.sdp, {
|
||||
topics: [], // V2 doesn't use topics
|
||||
rtcConfig: options?.rtcConfig
|
||||
});
|
||||
|
||||
// Wait for data channel
|
||||
const channel = await new Promise<RTCDataChannel>((resolve, reject) => {
|
||||
const timeout = setTimeout(() => {
|
||||
reject(new Error('Timeout waiting for data channel'));
|
||||
}, 30000);
|
||||
|
||||
peer.on('datachannel', (ch: RTCDataChannel) => {
|
||||
clearTimeout(timeout);
|
||||
resolve(ch);
|
||||
});
|
||||
|
||||
peer.on('failed', (error: Error) => {
|
||||
clearTimeout(timeout);
|
||||
reject(error);
|
||||
});
|
||||
});
|
||||
|
||||
return { peer, channel };
|
||||
}
|
||||
}
|
||||
361
src/durable/channel.ts
Normal file
361
src/durable/channel.ts
Normal file
@@ -0,0 +1,361 @@
|
||||
/**
|
||||
* DurableChannel - Message queueing wrapper for RTCDataChannel
|
||||
*
|
||||
* Provides automatic message queuing during disconnections and transparent
|
||||
* flushing when the connection is re-established.
|
||||
*/
|
||||
|
||||
import { EventEmitter } from '../event-emitter.js';
|
||||
import {
|
||||
DurableChannelState
|
||||
} from './types.js';
|
||||
import type {
|
||||
DurableChannelConfig,
|
||||
DurableChannelEvents,
|
||||
QueuedMessage
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Default configuration for durable channels
|
||||
*/
|
||||
const DEFAULT_CONFIG = {
|
||||
maxQueueSize: 1000,
|
||||
maxMessageAge: 60000, // 1 minute
|
||||
ordered: true,
|
||||
maxRetransmits: undefined
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Durable channel that survives WebRTC peer connection drops
|
||||
*
|
||||
* The DurableChannel wraps an RTCDataChannel and provides:
|
||||
* - Automatic message queuing during disconnections
|
||||
* - Queue flushing on reconnection
|
||||
* - Configurable queue size and message age limits
|
||||
* - RTCDataChannel-compatible API
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const channel = new DurableChannel('chat', connection, {
|
||||
* maxQueueSize: 500,
|
||||
* maxMessageAge: 30000
|
||||
* });
|
||||
*
|
||||
* channel.on('message', (data) => {
|
||||
* console.log('Received:', data);
|
||||
* });
|
||||
*
|
||||
* channel.on('open', () => {
|
||||
* channel.send('Hello!');
|
||||
* });
|
||||
*
|
||||
* // Messages sent during disconnection are automatically queued
|
||||
* channel.send('This will be queued if disconnected');
|
||||
* ```
|
||||
*/
|
||||
export class DurableChannel extends EventEmitter<DurableChannelEvents> {
|
||||
readonly label: string;
|
||||
readonly config: DurableChannelConfig;
|
||||
|
||||
private _state: DurableChannelState;
|
||||
private underlyingChannel?: RTCDataChannel;
|
||||
private messageQueue: QueuedMessage[] = [];
|
||||
private queueProcessing: boolean = false;
|
||||
private _bufferedAmountLowThreshold: number = 0;
|
||||
|
||||
// Event handlers that need cleanup
|
||||
private openHandler?: () => void;
|
||||
private messageHandler?: (event: MessageEvent) => void;
|
||||
private errorHandler?: (event: Event) => void;
|
||||
private closeHandler?: () => void;
|
||||
private bufferedAmountLowHandler?: () => void;
|
||||
|
||||
constructor(
|
||||
label: string,
|
||||
config?: DurableChannelConfig
|
||||
) {
|
||||
super();
|
||||
this.label = label;
|
||||
this.config = { ...DEFAULT_CONFIG, ...config };
|
||||
this._state = DurableChannelState.CONNECTING;
|
||||
}
|
||||
|
||||
/**
|
||||
* Current channel state
|
||||
*/
|
||||
get readyState(): DurableChannelState {
|
||||
return this._state;
|
||||
}
|
||||
|
||||
/**
|
||||
* Buffered amount from underlying channel (0 if no channel)
|
||||
*/
|
||||
get bufferedAmount(): number {
|
||||
return this.underlyingChannel?.bufferedAmount ?? 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Buffered amount low threshold
|
||||
*/
|
||||
get bufferedAmountLowThreshold(): number {
|
||||
return this._bufferedAmountLowThreshold;
|
||||
}
|
||||
|
||||
set bufferedAmountLowThreshold(value: number) {
|
||||
this._bufferedAmountLowThreshold = value;
|
||||
if (this.underlyingChannel) {
|
||||
this.underlyingChannel.bufferedAmountLowThreshold = value;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Send data through the channel
|
||||
*
|
||||
* If the channel is open, sends immediately. Otherwise, queues the message
|
||||
* for delivery when the channel reconnects.
|
||||
*
|
||||
* @param data - Data to send
|
||||
*/
|
||||
send(data: string | Blob | ArrayBuffer | ArrayBufferView): void {
|
||||
if (this._state === DurableChannelState.OPEN && this.underlyingChannel) {
|
||||
// Channel is open - send immediately
|
||||
try {
|
||||
this.underlyingChannel.send(data as any);
|
||||
} catch (error) {
|
||||
// Send failed - queue the message
|
||||
this.enqueueMessage(data);
|
||||
this.emit('error', error as Error);
|
||||
}
|
||||
} else if (this._state !== DurableChannelState.CLOSED) {
|
||||
// Channel is not open but not closed - queue the message
|
||||
this.enqueueMessage(data);
|
||||
} else {
|
||||
// Channel is closed - throw error
|
||||
throw new Error('Cannot send on closed channel');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Close the channel
|
||||
*/
|
||||
close(): void {
|
||||
if (this._state === DurableChannelState.CLOSED ||
|
||||
this._state === DurableChannelState.CLOSING) {
|
||||
return;
|
||||
}
|
||||
|
||||
this._state = DurableChannelState.CLOSING;
|
||||
|
||||
if (this.underlyingChannel) {
|
||||
this.underlyingChannel.close();
|
||||
}
|
||||
|
||||
this._state = DurableChannelState.CLOSED;
|
||||
this.emit('close');
|
||||
}
|
||||
|
||||
/**
|
||||
* Attach to an underlying RTCDataChannel
|
||||
*
|
||||
* This is called when a WebRTC connection is established (or re-established).
|
||||
* The channel will flush any queued messages and forward events.
|
||||
*
|
||||
* @param channel - RTCDataChannel to attach to
|
||||
* @internal
|
||||
*/
|
||||
attachToChannel(channel: RTCDataChannel): void {
|
||||
// Detach from any existing channel first
|
||||
this.detachFromChannel();
|
||||
|
||||
this.underlyingChannel = channel;
|
||||
|
||||
// Set buffered amount low threshold
|
||||
channel.bufferedAmountLowThreshold = this._bufferedAmountLowThreshold;
|
||||
|
||||
// Setup event handlers
|
||||
this.openHandler = () => {
|
||||
this._state = DurableChannelState.OPEN;
|
||||
this.emit('open');
|
||||
|
||||
// Flush queued messages
|
||||
this.flushQueue().catch(error => {
|
||||
this.emit('error', error);
|
||||
});
|
||||
};
|
||||
|
||||
this.messageHandler = (event: MessageEvent) => {
|
||||
this.emit('message', event.data);
|
||||
};
|
||||
|
||||
this.errorHandler = (event: Event) => {
|
||||
this.emit('error', new Error(`Channel error: ${event.type}`));
|
||||
};
|
||||
|
||||
this.closeHandler = () => {
|
||||
if (this._state !== DurableChannelState.CLOSING &&
|
||||
this._state !== DurableChannelState.CLOSED) {
|
||||
// Unexpected close - transition to connecting (will reconnect)
|
||||
this._state = DurableChannelState.CONNECTING;
|
||||
}
|
||||
};
|
||||
|
||||
this.bufferedAmountLowHandler = () => {
|
||||
this.emit('bufferedAmountLow');
|
||||
};
|
||||
|
||||
// Attach handlers
|
||||
channel.addEventListener('open', this.openHandler);
|
||||
channel.addEventListener('message', this.messageHandler);
|
||||
channel.addEventListener('error', this.errorHandler);
|
||||
channel.addEventListener('close', this.closeHandler);
|
||||
channel.addEventListener('bufferedamountlow', this.bufferedAmountLowHandler);
|
||||
|
||||
// If channel is already open, trigger open event
|
||||
if (channel.readyState === 'open') {
|
||||
this.openHandler();
|
||||
} else if (channel.readyState === 'connecting') {
|
||||
this._state = DurableChannelState.CONNECTING;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Detach from the underlying RTCDataChannel
|
||||
*
|
||||
* This is called when a WebRTC connection drops. The channel remains alive
|
||||
* and continues queuing messages.
|
||||
*
|
||||
* @internal
|
||||
*/
|
||||
detachFromChannel(): void {
|
||||
if (!this.underlyingChannel) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Remove event listeners
|
||||
if (this.openHandler) {
|
||||
this.underlyingChannel.removeEventListener('open', this.openHandler);
|
||||
}
|
||||
if (this.messageHandler) {
|
||||
this.underlyingChannel.removeEventListener('message', this.messageHandler);
|
||||
}
|
||||
if (this.errorHandler) {
|
||||
this.underlyingChannel.removeEventListener('error', this.errorHandler);
|
||||
}
|
||||
if (this.closeHandler) {
|
||||
this.underlyingChannel.removeEventListener('close', this.closeHandler);
|
||||
}
|
||||
if (this.bufferedAmountLowHandler) {
|
||||
this.underlyingChannel.removeEventListener('bufferedamountlow', this.bufferedAmountLowHandler);
|
||||
}
|
||||
|
||||
this.underlyingChannel = undefined;
|
||||
this._state = DurableChannelState.CONNECTING;
|
||||
}
|
||||
|
||||
/**
|
||||
* Enqueue a message for later delivery
|
||||
*/
|
||||
private enqueueMessage(data: string | Blob | ArrayBuffer | ArrayBufferView): void {
|
||||
// Prune old messages first
|
||||
this.pruneOldMessages();
|
||||
|
||||
const message: QueuedMessage = {
|
||||
data,
|
||||
enqueuedAt: Date.now(),
|
||||
id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
|
||||
};
|
||||
|
||||
this.messageQueue.push(message);
|
||||
|
||||
// Handle overflow
|
||||
const maxQueueSize = this.config.maxQueueSize ?? 1000;
|
||||
if (this.messageQueue.length > maxQueueSize) {
|
||||
const excess = this.messageQueue.length - maxQueueSize;
|
||||
this.messageQueue.splice(0, excess);
|
||||
this.emit('queueOverflow', excess);
|
||||
console.warn(
|
||||
`DurableChannel[${this.label}]: Dropped ${excess} messages due to queue overflow`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Flush all queued messages through the channel
|
||||
*/
|
||||
private async flushQueue(): Promise<void> {
|
||||
if (this.queueProcessing || !this.underlyingChannel ||
|
||||
this.underlyingChannel.readyState !== 'open') {
|
||||
return;
|
||||
}
|
||||
|
||||
this.queueProcessing = true;
|
||||
|
||||
try {
|
||||
// Prune old messages before flushing
|
||||
this.pruneOldMessages();
|
||||
|
||||
// Send all queued messages
|
||||
while (this.messageQueue.length > 0) {
|
||||
const message = this.messageQueue.shift();
|
||||
if (!message) break;
|
||||
|
||||
try {
|
||||
this.underlyingChannel.send(message.data as any);
|
||||
} catch (error) {
|
||||
// Send failed - re-queue message
|
||||
this.messageQueue.unshift(message);
|
||||
throw error;
|
||||
}
|
||||
|
||||
// If buffer is getting full, wait for it to drain
|
||||
if (this.underlyingChannel.bufferedAmount > 16 * 1024 * 1024) { // 16MB
|
||||
await new Promise<void>((resolve) => {
|
||||
const checkBuffer = () => {
|
||||
if (!this.underlyingChannel ||
|
||||
this.underlyingChannel.bufferedAmount < 8 * 1024 * 1024) {
|
||||
resolve();
|
||||
} else {
|
||||
setTimeout(checkBuffer, 100);
|
||||
}
|
||||
};
|
||||
checkBuffer();
|
||||
});
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
this.queueProcessing = false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove messages older than maxMessageAge from the queue
|
||||
*/
|
||||
private pruneOldMessages(): void {
|
||||
const maxMessageAge = this.config.maxMessageAge ?? 60000;
|
||||
if (maxMessageAge === Infinity || maxMessageAge <= 0) {
|
||||
return;
|
||||
}
|
||||
|
||||
const now = Date.now();
|
||||
const cutoff = now - maxMessageAge;
|
||||
|
||||
const originalLength = this.messageQueue.length;
|
||||
this.messageQueue = this.messageQueue.filter(msg => msg.enqueuedAt >= cutoff);
|
||||
|
||||
const pruned = originalLength - this.messageQueue.length;
|
||||
if (pruned > 0) {
|
||||
console.warn(
|
||||
`DurableChannel[${this.label}]: Pruned ${pruned} old messages (older than ${maxMessageAge}ms)`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current queue size
|
||||
*
|
||||
* @internal
|
||||
*/
|
||||
getQueueSize(): number {
|
||||
return this.messageQueue.length;
|
||||
}
|
||||
}
|
||||
444
src/durable/connection.ts
Normal file
444
src/durable/connection.ts
Normal file
@@ -0,0 +1,444 @@
|
||||
/**
|
||||
* DurableConnection - WebRTC connection with automatic reconnection
|
||||
*
|
||||
* Manages the WebRTC peer lifecycle and automatically reconnects on
|
||||
* connection drops with exponential backoff.
|
||||
*/
|
||||
|
||||
import { EventEmitter } from '../event-emitter.js';
|
||||
import RondevuPeer from '../peer/index.js';
|
||||
import type { RondevuOffers } from '../offers.js';
|
||||
import { DurableChannel } from './channel.js';
|
||||
import { createReconnectionScheduler, type ReconnectionScheduler } from './reconnection.js';
|
||||
import {
|
||||
DurableConnectionState
|
||||
} from './types.js';
|
||||
import type {
|
||||
DurableConnectionConfig,
|
||||
DurableConnectionEvents,
|
||||
ConnectionInfo
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Default configuration for durable connections
|
||||
*/
|
||||
const DEFAULT_CONFIG: Required<DurableConnectionConfig> = {
|
||||
maxReconnectAttempts: 10,
|
||||
reconnectBackoffBase: 1000,
|
||||
reconnectBackoffMax: 30000,
|
||||
reconnectJitter: 0.2,
|
||||
connectionTimeout: 30000,
|
||||
maxQueueSize: 1000,
|
||||
maxMessageAge: 60000,
|
||||
rtcConfig: {
|
||||
iceServers: [
|
||||
{ urls: 'stun:stun.l.google.com:19302' },
|
||||
{ urls: 'stun:stun1.l.google.com:19302' }
|
||||
]
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Durable WebRTC connection that automatically reconnects
|
||||
*
|
||||
* The DurableConnection manages the lifecycle of a WebRTC peer connection
|
||||
* and provides:
|
||||
* - Automatic reconnection with exponential backoff
|
||||
* - Multiple durable channels that survive reconnections
|
||||
* - Configurable retry limits and timeouts
|
||||
* - High-level connection state events
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const connection = new DurableConnection(
|
||||
* offersApi,
|
||||
* { username: 'alice', serviceFqn: 'chat@1.0.0' },
|
||||
* { maxReconnectAttempts: 5 }
|
||||
* );
|
||||
*
|
||||
* connection.on('connected', () => {
|
||||
* console.log('Connected!');
|
||||
* });
|
||||
*
|
||||
* connection.on('reconnecting', (attempt, max, delay) => {
|
||||
* console.log(`Reconnecting... (${attempt}/${max}, retry in ${delay}ms)`);
|
||||
* });
|
||||
*
|
||||
* const channel = connection.createChannel('chat');
|
||||
* channel.on('message', (data) => {
|
||||
* console.log('Received:', data);
|
||||
* });
|
||||
*
|
||||
* await connection.connect();
|
||||
* ```
|
||||
*/
|
||||
export class DurableConnection extends EventEmitter<DurableConnectionEvents> {
|
||||
readonly connectionId: string;
|
||||
readonly config: Required<DurableConnectionConfig>;
|
||||
readonly connectionInfo: ConnectionInfo;
|
||||
|
||||
private _state: DurableConnectionState;
|
||||
private currentPeer?: RondevuPeer;
|
||||
private channels: Map<string, DurableChannel> = new Map();
|
||||
private reconnectionScheduler?: ReconnectionScheduler;
|
||||
|
||||
// Track peer event handlers for cleanup
|
||||
private peerConnectedHandler?: () => void;
|
||||
private peerDisconnectedHandler?: () => void;
|
||||
private peerFailedHandler?: (error: Error) => void;
|
||||
private peerDataChannelHandler?: (channel: RTCDataChannel) => void;
|
||||
|
||||
constructor(
|
||||
private offersApi: RondevuOffers,
|
||||
connectionInfo: ConnectionInfo,
|
||||
config?: DurableConnectionConfig
|
||||
) {
|
||||
super();
|
||||
this.connectionId = `conn-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
|
||||
this.config = { ...DEFAULT_CONFIG, ...config };
|
||||
this.connectionInfo = connectionInfo;
|
||||
this._state = DurableConnectionState.CONNECTING;
|
||||
}
|
||||
|
||||
/**
|
||||
* Current connection state
|
||||
*/
|
||||
getState(): DurableConnectionState {
|
||||
return this._state;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if connection is currently connected
|
||||
*/
|
||||
isConnected(): boolean {
|
||||
return this._state === DurableConnectionState.CONNECTED;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a durable channel on this connection
|
||||
*
|
||||
* The channel will be created on the current peer connection if available,
|
||||
* otherwise it will be created when the connection is established.
|
||||
*
|
||||
* @param label - Channel label
|
||||
* @param options - RTCDataChannel init options
|
||||
* @returns DurableChannel instance
|
||||
*/
|
||||
createChannel(label: string, options?: RTCDataChannelInit): DurableChannel {
|
||||
// Check if channel already exists
|
||||
if (this.channels.has(label)) {
|
||||
throw new Error(`Channel with label '${label}' already exists`);
|
||||
}
|
||||
|
||||
// Create durable channel
|
||||
const durableChannel = new DurableChannel(label, {
|
||||
maxQueueSize: this.config.maxQueueSize,
|
||||
maxMessageAge: this.config.maxMessageAge,
|
||||
ordered: options?.ordered ?? true,
|
||||
maxRetransmits: options?.maxRetransmits
|
||||
});
|
||||
|
||||
this.channels.set(label, durableChannel);
|
||||
|
||||
// If we have a current peer, attach the channel
|
||||
if (this.currentPeer && this._state === DurableConnectionState.CONNECTED) {
|
||||
this.createAndAttachChannel(durableChannel, options);
|
||||
}
|
||||
|
||||
return durableChannel;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get an existing channel by label
|
||||
*/
|
||||
getChannel(label: string): DurableChannel | undefined {
|
||||
return this.channels.get(label);
|
||||
}
|
||||
|
||||
/**
|
||||
* Establish the initial connection
|
||||
*
|
||||
* @returns Promise that resolves when connected
|
||||
*/
|
||||
async connect(): Promise<void> {
|
||||
if (this._state !== DurableConnectionState.CONNECTING) {
|
||||
throw new Error(`Cannot connect from state: ${this._state}`);
|
||||
}
|
||||
|
||||
try {
|
||||
await this.establishConnection();
|
||||
} catch (error) {
|
||||
this._state = DurableConnectionState.DISCONNECTED;
|
||||
await this.handleDisconnection();
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Close the connection gracefully
|
||||
*/
|
||||
async close(): Promise<void> {
|
||||
if (this._state === DurableConnectionState.CLOSED) {
|
||||
return;
|
||||
}
|
||||
|
||||
const previousState = this._state;
|
||||
this._state = DurableConnectionState.CLOSED;
|
||||
|
||||
// Cancel any ongoing reconnection
|
||||
if (this.reconnectionScheduler) {
|
||||
this.reconnectionScheduler.cancel();
|
||||
}
|
||||
|
||||
// Close all channels
|
||||
for (const channel of this.channels.values()) {
|
||||
channel.close();
|
||||
}
|
||||
|
||||
// Close peer connection
|
||||
if (this.currentPeer) {
|
||||
await this.currentPeer.close();
|
||||
this.currentPeer = undefined;
|
||||
}
|
||||
|
||||
this.emit('state', this._state, previousState);
|
||||
this.emit('closed');
|
||||
}
|
||||
|
||||
/**
|
||||
* Establish a WebRTC connection
|
||||
*/
|
||||
private async establishConnection(): Promise<void> {
|
||||
// Create new peer
|
||||
const peer = new RondevuPeer(this.offersApi, this.config.rtcConfig);
|
||||
this.currentPeer = peer;
|
||||
|
||||
// Setup peer event handlers
|
||||
this.setupPeerHandlers(peer);
|
||||
|
||||
// Determine connection method based on connection info
|
||||
if (this.connectionInfo.uuid) {
|
||||
// Connect by UUID
|
||||
await this.connectByUuid(peer, this.connectionInfo.uuid);
|
||||
} else if (this.connectionInfo.username && this.connectionInfo.serviceFqn) {
|
||||
// Connect by username and service FQN
|
||||
await this.connectByService(peer, this.connectionInfo.username, this.connectionInfo.serviceFqn);
|
||||
} else {
|
||||
throw new Error('Invalid connection info: must provide either uuid or (username + serviceFqn)');
|
||||
}
|
||||
|
||||
// Wait for connection with timeout
|
||||
await this.waitForConnection(peer);
|
||||
|
||||
// Connection established
|
||||
this.transitionToConnected();
|
||||
}
|
||||
|
||||
/**
|
||||
* Connect to a service by UUID
|
||||
*/
|
||||
private async connectByUuid(peer: RondevuPeer, uuid: string): Promise<void> {
|
||||
// Get service details
|
||||
const response = await fetch(`${this.offersApi['baseUrl']}/services/${uuid}`);
|
||||
if (!response.ok) {
|
||||
throw new Error(`Service not found: ${uuid}`);
|
||||
}
|
||||
|
||||
const service = await response.json();
|
||||
|
||||
// Answer the offer
|
||||
await peer.answer(service.offerId, service.sdp, {
|
||||
secret: this.offersApi['credentials'].secret,
|
||||
topics: []
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Connect to a service by username and service FQN
|
||||
*/
|
||||
private async connectByService(peer: RondevuPeer, username: string, serviceFqn: string): Promise<void> {
|
||||
// Query service to get UUID
|
||||
const response = await fetch(`${this.offersApi['baseUrl']}/index/${username}/query`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ serviceFqn })
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`Service not found: ${username}/${serviceFqn}`);
|
||||
}
|
||||
|
||||
const { uuid } = await response.json();
|
||||
|
||||
// Connect by UUID
|
||||
await this.connectByUuid(peer, uuid);
|
||||
}
|
||||
|
||||
/**
|
||||
* Wait for peer connection to establish
|
||||
*/
|
||||
private async waitForConnection(peer: RondevuPeer): Promise<void> {
|
||||
return new Promise((resolve, reject) => {
|
||||
const timeout = setTimeout(() => {
|
||||
reject(new Error('Connection timeout'));
|
||||
}, this.config.connectionTimeout);
|
||||
|
||||
const onConnected = () => {
|
||||
clearTimeout(timeout);
|
||||
peer.off('connected', onConnected);
|
||||
peer.off('failed', onFailed);
|
||||
resolve();
|
||||
};
|
||||
|
||||
const onFailed = (error: Error) => {
|
||||
clearTimeout(timeout);
|
||||
peer.off('connected', onConnected);
|
||||
peer.off('failed', onFailed);
|
||||
reject(error);
|
||||
};
|
||||
|
||||
peer.on('connected', onConnected);
|
||||
peer.on('failed', onFailed);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Setup event handlers for peer
|
||||
*/
|
||||
private setupPeerHandlers(peer: RondevuPeer): void {
|
||||
this.peerConnectedHandler = () => {
|
||||
// Connection established - will be handled by waitForConnection
|
||||
};
|
||||
|
||||
this.peerDisconnectedHandler = () => {
|
||||
if (this._state !== DurableConnectionState.CLOSED) {
|
||||
this.handleDisconnection();
|
||||
}
|
||||
};
|
||||
|
||||
this.peerFailedHandler = (error: Error) => {
|
||||
if (this._state !== DurableConnectionState.CLOSED) {
|
||||
console.error('Peer connection failed:', error);
|
||||
this.handleDisconnection();
|
||||
}
|
||||
};
|
||||
|
||||
this.peerDataChannelHandler = (channel: RTCDataChannel) => {
|
||||
// Find matching durable channel and attach
|
||||
const durableChannel = this.channels.get(channel.label);
|
||||
if (durableChannel) {
|
||||
durableChannel.attachToChannel(channel);
|
||||
}
|
||||
};
|
||||
|
||||
peer.on('connected', this.peerConnectedHandler);
|
||||
peer.on('disconnected', this.peerDisconnectedHandler);
|
||||
peer.on('failed', this.peerFailedHandler);
|
||||
peer.on('datachannel', this.peerDataChannelHandler);
|
||||
}
|
||||
|
||||
/**
|
||||
* Transition to connected state
|
||||
*/
|
||||
private transitionToConnected(): void {
|
||||
const previousState = this._state;
|
||||
this._state = DurableConnectionState.CONNECTED;
|
||||
|
||||
// Reset reconnection scheduler if it exists
|
||||
if (this.reconnectionScheduler) {
|
||||
this.reconnectionScheduler.reset();
|
||||
}
|
||||
|
||||
// Attach all channels to the new peer connection
|
||||
for (const [label, channel] of this.channels) {
|
||||
if (this.currentPeer) {
|
||||
this.createAndAttachChannel(channel);
|
||||
}
|
||||
}
|
||||
|
||||
this.emit('state', this._state, previousState);
|
||||
this.emit('connected');
|
||||
}
|
||||
|
||||
/**
|
||||
* Create underlying RTCDataChannel and attach to durable channel
|
||||
*/
|
||||
private createAndAttachChannel(
|
||||
durableChannel: DurableChannel,
|
||||
options?: RTCDataChannelInit
|
||||
): void {
|
||||
if (!this.currentPeer) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Check if peer already has this channel (received via datachannel event)
|
||||
// If not, create it
|
||||
const senders = (this.currentPeer.pc as any).getSenders?.() || [];
|
||||
const existingChannel = Array.from(senders as RTCRtpSender[])
|
||||
.map((sender) => (sender as any).channel as RTCDataChannel)
|
||||
.find(ch => ch && ch.label === durableChannel.label);
|
||||
|
||||
if (existingChannel) {
|
||||
durableChannel.attachToChannel(existingChannel);
|
||||
} else {
|
||||
// Create new channel on peer
|
||||
const rtcChannel = this.currentPeer.createDataChannel(
|
||||
durableChannel.label,
|
||||
options
|
||||
);
|
||||
durableChannel.attachToChannel(rtcChannel);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle connection disconnection
|
||||
*/
|
||||
private async handleDisconnection(): Promise<void> {
|
||||
if (this._state === DurableConnectionState.CLOSED ||
|
||||
this._state === DurableConnectionState.FAILED) {
|
||||
return;
|
||||
}
|
||||
|
||||
const previousState = this._state;
|
||||
this._state = DurableConnectionState.RECONNECTING;
|
||||
|
||||
this.emit('state', this._state, previousState);
|
||||
this.emit('disconnected');
|
||||
|
||||
// Detach all channels (but keep them alive)
|
||||
for (const channel of this.channels.values()) {
|
||||
channel.detachFromChannel();
|
||||
}
|
||||
|
||||
// Close old peer
|
||||
if (this.currentPeer) {
|
||||
await this.currentPeer.close();
|
||||
this.currentPeer = undefined;
|
||||
}
|
||||
|
||||
// Create or use existing reconnection scheduler
|
||||
if (!this.reconnectionScheduler) {
|
||||
this.reconnectionScheduler = createReconnectionScheduler({
|
||||
maxAttempts: this.config.maxReconnectAttempts,
|
||||
backoffBase: this.config.reconnectBackoffBase,
|
||||
backoffMax: this.config.reconnectBackoffMax,
|
||||
jitter: this.config.reconnectJitter,
|
||||
onReconnect: async () => {
|
||||
await this.establishConnection();
|
||||
},
|
||||
onMaxAttemptsExceeded: (error) => {
|
||||
const prevState = this._state;
|
||||
this._state = DurableConnectionState.FAILED;
|
||||
this.emit('state', this._state, prevState);
|
||||
this.emit('failed', error, true);
|
||||
},
|
||||
onBeforeAttempt: (attempt, max, delay) => {
|
||||
this.emit('reconnecting', attempt, max, delay);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// Schedule reconnection
|
||||
this.reconnectionScheduler.schedule();
|
||||
}
|
||||
}
|
||||
200
src/durable/reconnection.ts
Normal file
200
src/durable/reconnection.ts
Normal file
@@ -0,0 +1,200 @@
|
||||
/**
|
||||
* Reconnection utilities for durable connections
|
||||
*
|
||||
* This module provides utilities for managing reconnection logic with
|
||||
* exponential backoff and jitter.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Calculate exponential backoff delay with jitter
|
||||
*
|
||||
* @param attempt - Current attempt number (0-indexed)
|
||||
* @param base - Base delay in milliseconds
|
||||
* @param max - Maximum delay in milliseconds
|
||||
* @param jitter - Jitter factor (0-1), e.g., 0.2 for ±20%
|
||||
* @returns Delay in milliseconds with jitter applied
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* calculateBackoff(0, 1000, 30000, 0.2) // ~1000ms ± 20%
|
||||
* calculateBackoff(1, 1000, 30000, 0.2) // ~2000ms ± 20%
|
||||
* calculateBackoff(2, 1000, 30000, 0.2) // ~4000ms ± 20%
|
||||
* calculateBackoff(5, 1000, 30000, 0.2) // ~30000ms ± 20% (capped at max)
|
||||
* ```
|
||||
*/
|
||||
export function calculateBackoff(
|
||||
attempt: number,
|
||||
base: number,
|
||||
max: number,
|
||||
jitter: number
|
||||
): number {
|
||||
// Calculate exponential delay: base * 2^attempt
|
||||
const exponential = base * Math.pow(2, attempt);
|
||||
|
||||
// Cap at maximum
|
||||
const capped = Math.min(exponential, max);
|
||||
|
||||
// Apply jitter: ± (jitter * capped)
|
||||
const jitterAmount = capped * jitter;
|
||||
const randomJitter = (Math.random() * 2 - 1) * jitterAmount;
|
||||
|
||||
// Return delay with jitter, ensuring it's not negative
|
||||
return Math.max(0, capped + randomJitter);
|
||||
}
|
||||
|
||||
/**
|
||||
* Configuration for reconnection scheduler
|
||||
*/
|
||||
export interface ReconnectionSchedulerConfig {
|
||||
/** Maximum number of reconnection attempts */
|
||||
maxAttempts: number;
|
||||
|
||||
/** Base delay for exponential backoff */
|
||||
backoffBase: number;
|
||||
|
||||
/** Maximum delay between attempts */
|
||||
backoffMax: number;
|
||||
|
||||
/** Jitter factor for randomizing delays */
|
||||
jitter: number;
|
||||
|
||||
/** Callback invoked for each reconnection attempt */
|
||||
onReconnect: () => Promise<void>;
|
||||
|
||||
/** Callback invoked when max attempts exceeded */
|
||||
onMaxAttemptsExceeded: (error: Error) => void;
|
||||
|
||||
/** Optional callback invoked before each attempt */
|
||||
onBeforeAttempt?: (attempt: number, maxAttempts: number, delay: number) => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reconnection scheduler state
|
||||
*/
|
||||
export interface ReconnectionScheduler {
|
||||
/** Current attempt number */
|
||||
attempt: number;
|
||||
|
||||
/** Whether scheduler is active */
|
||||
active: boolean;
|
||||
|
||||
/** Schedule next reconnection attempt */
|
||||
schedule: () => void;
|
||||
|
||||
/** Cancel scheduled reconnection */
|
||||
cancel: () => void;
|
||||
|
||||
/** Reset attempt counter */
|
||||
reset: () => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a reconnection scheduler
|
||||
*
|
||||
* @param config - Scheduler configuration
|
||||
* @returns Reconnection scheduler instance
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const scheduler = createReconnectionScheduler({
|
||||
* maxAttempts: 10,
|
||||
* backoffBase: 1000,
|
||||
* backoffMax: 30000,
|
||||
* jitter: 0.2,
|
||||
* onReconnect: async () => {
|
||||
* await connect();
|
||||
* },
|
||||
* onMaxAttemptsExceeded: (error) => {
|
||||
* console.error('Failed to reconnect:', error);
|
||||
* },
|
||||
* onBeforeAttempt: (attempt, max, delay) => {
|
||||
* console.log(`Reconnecting in ${delay}ms (${attempt}/${max})...`);
|
||||
* }
|
||||
* });
|
||||
*
|
||||
* // Start reconnection
|
||||
* scheduler.schedule();
|
||||
*
|
||||
* // Cancel reconnection
|
||||
* scheduler.cancel();
|
||||
* ```
|
||||
*/
|
||||
export function createReconnectionScheduler(
|
||||
config: ReconnectionSchedulerConfig
|
||||
): ReconnectionScheduler {
|
||||
let attempt = 0;
|
||||
let active = false;
|
||||
let timer: ReturnType<typeof setTimeout> | undefined;
|
||||
|
||||
const schedule = () => {
|
||||
// Cancel any existing timer
|
||||
if (timer) {
|
||||
clearTimeout(timer);
|
||||
timer = undefined;
|
||||
}
|
||||
|
||||
// Check if max attempts exceeded
|
||||
if (attempt >= config.maxAttempts) {
|
||||
active = false;
|
||||
config.onMaxAttemptsExceeded(
|
||||
new Error(`Max reconnection attempts exceeded (${config.maxAttempts})`)
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
// Calculate delay
|
||||
const delay = calculateBackoff(
|
||||
attempt,
|
||||
config.backoffBase,
|
||||
config.backoffMax,
|
||||
config.jitter
|
||||
);
|
||||
|
||||
// Notify before attempt
|
||||
if (config.onBeforeAttempt) {
|
||||
config.onBeforeAttempt(attempt + 1, config.maxAttempts, delay);
|
||||
}
|
||||
|
||||
// Mark as active
|
||||
active = true;
|
||||
|
||||
// Schedule reconnection
|
||||
timer = setTimeout(async () => {
|
||||
attempt++;
|
||||
try {
|
||||
await config.onReconnect();
|
||||
// Success - reset scheduler
|
||||
attempt = 0;
|
||||
active = false;
|
||||
} catch (error) {
|
||||
// Failure - schedule next attempt
|
||||
schedule();
|
||||
}
|
||||
}, delay);
|
||||
};
|
||||
|
||||
const cancel = () => {
|
||||
if (timer) {
|
||||
clearTimeout(timer);
|
||||
timer = undefined;
|
||||
}
|
||||
active = false;
|
||||
};
|
||||
|
||||
const reset = () => {
|
||||
cancel();
|
||||
attempt = 0;
|
||||
};
|
||||
|
||||
return {
|
||||
get attempt() {
|
||||
return attempt;
|
||||
},
|
||||
get active() {
|
||||
return active;
|
||||
},
|
||||
schedule,
|
||||
cancel,
|
||||
reset
|
||||
};
|
||||
}
|
||||
329
src/durable/service.ts
Normal file
329
src/durable/service.ts
Normal file
@@ -0,0 +1,329 @@
|
||||
/**
|
||||
* DurableService - Service with automatic TTL refresh
|
||||
*
|
||||
* Manages service publishing with automatic reconnection for incoming
|
||||
* connections and TTL auto-refresh to prevent expiration.
|
||||
*/
|
||||
|
||||
import { EventEmitter } from '../event-emitter.js';
|
||||
import { ServicePool, type PoolStatus } from '../service-pool.js';
|
||||
import type { RondevuOffers } from '../offers.js';
|
||||
import { DurableChannel } from './channel.js';
|
||||
import type {
|
||||
DurableServiceConfig,
|
||||
DurableServiceEvents,
|
||||
ServiceInfo
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Connection handler callback
|
||||
*/
|
||||
export type ConnectionHandler = (
|
||||
channel: DurableChannel,
|
||||
connectionId: string
|
||||
) => void | Promise<void>;
|
||||
|
||||
/**
|
||||
* Default configuration for durable services
|
||||
*/
|
||||
const DEFAULT_CONFIG = {
|
||||
isPublic: false,
|
||||
ttlRefreshMargin: 0.2,
|
||||
poolSize: 1,
|
||||
pollingInterval: 2000,
|
||||
maxReconnectAttempts: 10,
|
||||
reconnectBackoffBase: 1000,
|
||||
reconnectBackoffMax: 30000,
|
||||
reconnectJitter: 0.2,
|
||||
connectionTimeout: 30000,
|
||||
maxQueueSize: 1000,
|
||||
maxMessageAge: 60000,
|
||||
rtcConfig: {
|
||||
iceServers: [
|
||||
{ urls: 'stun:stun.l.google.com:19302' },
|
||||
{ urls: 'stun:stun1.l.google.com:19302' }
|
||||
]
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Durable service that automatically refreshes TTL and handles reconnections
|
||||
*
|
||||
* The DurableService manages service publishing and provides:
|
||||
* - Automatic TTL refresh before expiration
|
||||
* - Durable connections for incoming peers
|
||||
* - Connection pooling for multiple simultaneous connections
|
||||
* - High-level connection lifecycle events
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const service = new DurableService(
|
||||
* offersApi,
|
||||
* (channel, connectionId) => {
|
||||
* channel.on('message', (data) => {
|
||||
* console.log(`Message from ${connectionId}:`, data);
|
||||
* channel.send(`Echo: ${data}`);
|
||||
* });
|
||||
* },
|
||||
* {
|
||||
* username: 'alice',
|
||||
* privateKey: keypair.privateKey,
|
||||
* serviceFqn: 'chat@1.0.0',
|
||||
* poolSize: 10
|
||||
* }
|
||||
* );
|
||||
*
|
||||
* service.on('published', (serviceId, uuid) => {
|
||||
* console.log(`Service published: ${uuid}`);
|
||||
* });
|
||||
*
|
||||
* service.on('connection', (connectionId) => {
|
||||
* console.log(`New connection: ${connectionId}`);
|
||||
* });
|
||||
*
|
||||
* await service.start();
|
||||
* ```
|
||||
*/
|
||||
export class DurableService extends EventEmitter<DurableServiceEvents> {
|
||||
readonly config: Required<DurableServiceConfig>;
|
||||
|
||||
private serviceId?: string;
|
||||
private uuid?: string;
|
||||
private expiresAt?: number;
|
||||
private ttlRefreshTimer?: ReturnType<typeof setTimeout>;
|
||||
private servicePool?: ServicePool;
|
||||
private activeChannels: Map<string, DurableChannel> = new Map();
|
||||
|
||||
constructor(
|
||||
private offersApi: RondevuOffers,
|
||||
private baseUrl: string,
|
||||
private credentials: { peerId: string; secret: string },
|
||||
private handler: ConnectionHandler,
|
||||
config: DurableServiceConfig
|
||||
) {
|
||||
super();
|
||||
this.config = { ...DEFAULT_CONFIG, ...config } as Required<DurableServiceConfig>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Start the service
|
||||
*
|
||||
* Publishes the service and begins accepting connections.
|
||||
*
|
||||
* @returns Service information
|
||||
*/
|
||||
async start(): Promise<ServiceInfo> {
|
||||
if (this.servicePool) {
|
||||
throw new Error('Service already started');
|
||||
}
|
||||
|
||||
// Create and start service pool
|
||||
this.servicePool = new ServicePool(
|
||||
this.baseUrl,
|
||||
this.credentials,
|
||||
{
|
||||
username: this.config.username,
|
||||
privateKey: this.config.privateKey,
|
||||
serviceFqn: this.config.serviceFqn,
|
||||
rtcConfig: this.config.rtcConfig,
|
||||
isPublic: this.config.isPublic,
|
||||
metadata: this.config.metadata,
|
||||
ttl: this.config.ttl,
|
||||
poolSize: this.config.poolSize,
|
||||
pollingInterval: this.config.pollingInterval,
|
||||
handler: (channel, peer, connectionId) => {
|
||||
this.handleNewConnection(channel, connectionId);
|
||||
},
|
||||
onPoolStatus: (status) => {
|
||||
// Could emit pool status event if needed
|
||||
},
|
||||
onError: (error, context) => {
|
||||
this.emit('error', error, context);
|
||||
}
|
||||
}
|
||||
);
|
||||
|
||||
const handle = await this.servicePool.start();
|
||||
|
||||
// Store service info
|
||||
this.serviceId = handle.serviceId;
|
||||
this.uuid = handle.uuid;
|
||||
this.expiresAt = Date.now() + (this.config.ttl || 300000); // Default 5 minutes
|
||||
|
||||
this.emit('published', this.serviceId, this.uuid);
|
||||
|
||||
// Schedule TTL refresh
|
||||
this.scheduleRefresh();
|
||||
|
||||
return {
|
||||
serviceId: this.serviceId,
|
||||
uuid: this.uuid,
|
||||
expiresAt: this.expiresAt
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop the service
|
||||
*
|
||||
* Unpublishes the service and closes all active connections.
|
||||
*/
|
||||
async stop(): Promise<void> {
|
||||
// Cancel TTL refresh
|
||||
if (this.ttlRefreshTimer) {
|
||||
clearTimeout(this.ttlRefreshTimer);
|
||||
this.ttlRefreshTimer = undefined;
|
||||
}
|
||||
|
||||
// Close all active channels
|
||||
for (const channel of this.activeChannels.values()) {
|
||||
channel.close();
|
||||
}
|
||||
this.activeChannels.clear();
|
||||
|
||||
// Stop service pool
|
||||
if (this.servicePool) {
|
||||
await this.servicePool.stop();
|
||||
this.servicePool = undefined;
|
||||
}
|
||||
|
||||
this.emit('closed');
|
||||
}
|
||||
|
||||
/**
|
||||
* Get list of active connection IDs
|
||||
*/
|
||||
getActiveConnections(): string[] {
|
||||
return Array.from(this.activeChannels.keys());
|
||||
}
|
||||
|
||||
/**
|
||||
* Get service information
|
||||
*/
|
||||
getServiceInfo(): ServiceInfo | null {
|
||||
if (!this.serviceId || !this.uuid || !this.expiresAt) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return {
|
||||
serviceId: this.serviceId,
|
||||
uuid: this.uuid,
|
||||
expiresAt: this.expiresAt
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Schedule TTL refresh
|
||||
*/
|
||||
private scheduleRefresh(): void {
|
||||
if (!this.expiresAt || !this.config.ttl) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Cancel existing timer
|
||||
if (this.ttlRefreshTimer) {
|
||||
clearTimeout(this.ttlRefreshTimer);
|
||||
}
|
||||
|
||||
// Calculate refresh time (default: refresh at 80% of TTL)
|
||||
const timeUntilExpiry = this.expiresAt - Date.now();
|
||||
const refreshMargin = timeUntilExpiry * this.config.ttlRefreshMargin;
|
||||
const refreshTime = Math.max(0, timeUntilExpiry - refreshMargin);
|
||||
|
||||
// Schedule refresh
|
||||
this.ttlRefreshTimer = setTimeout(() => {
|
||||
this.refreshServiceTTL().catch(error => {
|
||||
this.emit('error', error, 'ttl-refresh');
|
||||
// Retry after short delay
|
||||
setTimeout(() => this.scheduleRefresh(), 5000);
|
||||
});
|
||||
}, refreshTime);
|
||||
}
|
||||
|
||||
/**
|
||||
* Refresh service TTL
|
||||
*/
|
||||
private async refreshServiceTTL(): Promise<void> {
|
||||
if (!this.serviceId || !this.uuid) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Delete old service
|
||||
await this.servicePool?.stop();
|
||||
|
||||
// Recreate service pool (this republishes the service)
|
||||
this.servicePool = new ServicePool(
|
||||
this.baseUrl,
|
||||
this.credentials,
|
||||
{
|
||||
username: this.config.username,
|
||||
privateKey: this.config.privateKey,
|
||||
serviceFqn: this.config.serviceFqn,
|
||||
rtcConfig: this.config.rtcConfig,
|
||||
isPublic: this.config.isPublic,
|
||||
metadata: this.config.metadata,
|
||||
ttl: this.config.ttl,
|
||||
poolSize: this.config.poolSize,
|
||||
pollingInterval: this.config.pollingInterval,
|
||||
handler: (channel, peer, connectionId) => {
|
||||
this.handleNewConnection(channel, connectionId);
|
||||
},
|
||||
onPoolStatus: (status) => {
|
||||
// Could emit pool status event if needed
|
||||
},
|
||||
onError: (error, context) => {
|
||||
this.emit('error', error, context);
|
||||
}
|
||||
}
|
||||
);
|
||||
|
||||
const handle = await this.servicePool.start();
|
||||
|
||||
// Update service info
|
||||
this.serviceId = handle.serviceId;
|
||||
this.uuid = handle.uuid;
|
||||
this.expiresAt = Date.now() + (this.config.ttl || 300000);
|
||||
|
||||
this.emit('ttl-refreshed', this.expiresAt);
|
||||
|
||||
// Schedule next refresh
|
||||
this.scheduleRefresh();
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle new incoming connection
|
||||
*/
|
||||
private handleNewConnection(channel: RTCDataChannel, connectionId: string): void {
|
||||
// Create durable channel
|
||||
const durableChannel = new DurableChannel(channel.label, {
|
||||
maxQueueSize: this.config.maxQueueSize,
|
||||
maxMessageAge: this.config.maxMessageAge
|
||||
});
|
||||
|
||||
// Attach to underlying channel
|
||||
durableChannel.attachToChannel(channel);
|
||||
|
||||
// Track channel
|
||||
this.activeChannels.set(connectionId, durableChannel);
|
||||
|
||||
// Setup cleanup on close
|
||||
durableChannel.on('close', () => {
|
||||
this.activeChannels.delete(connectionId);
|
||||
this.emit('disconnection', connectionId);
|
||||
});
|
||||
|
||||
// Emit connection event
|
||||
this.emit('connection', connectionId);
|
||||
|
||||
// Invoke user handler
|
||||
try {
|
||||
const result = this.handler(durableChannel, connectionId);
|
||||
if (result && typeof result.then === 'function') {
|
||||
result.catch(error => {
|
||||
this.emit('error', error, 'handler');
|
||||
});
|
||||
}
|
||||
} catch (error) {
|
||||
this.emit('error', error as Error, 'handler');
|
||||
}
|
||||
}
|
||||
}
|
||||
184
src/durable/types.ts
Normal file
184
src/durable/types.ts
Normal file
@@ -0,0 +1,184 @@
|
||||
/**
|
||||
* Type definitions for durable WebRTC connections
|
||||
*
|
||||
* This module defines all interfaces, enums, and types used by the durable
|
||||
* connection system for automatic reconnection and message queuing.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Connection state enum
|
||||
*/
|
||||
export enum DurableConnectionState {
|
||||
CONNECTING = 'connecting',
|
||||
CONNECTED = 'connected',
|
||||
RECONNECTING = 'reconnecting',
|
||||
DISCONNECTED = 'disconnected',
|
||||
FAILED = 'failed',
|
||||
CLOSED = 'closed'
|
||||
}
|
||||
|
||||
/**
|
||||
* Channel state enum
|
||||
*/
|
||||
export enum DurableChannelState {
|
||||
CONNECTING = 'connecting',
|
||||
OPEN = 'open',
|
||||
CLOSING = 'closing',
|
||||
CLOSED = 'closed'
|
||||
}
|
||||
|
||||
/**
|
||||
* Configuration for durable connections
|
||||
*/
|
||||
export interface DurableConnectionConfig {
|
||||
/** Maximum number of reconnection attempts (default: 10) */
|
||||
maxReconnectAttempts?: number;
|
||||
|
||||
/** Base delay for exponential backoff in milliseconds (default: 1000) */
|
||||
reconnectBackoffBase?: number;
|
||||
|
||||
/** Maximum delay between reconnection attempts in milliseconds (default: 30000) */
|
||||
reconnectBackoffMax?: number;
|
||||
|
||||
/** Jitter factor for randomizing reconnection delays (default: 0.2 = ±20%) */
|
||||
reconnectJitter?: number;
|
||||
|
||||
/** Timeout for initial connection attempt in milliseconds (default: 30000) */
|
||||
connectionTimeout?: number;
|
||||
|
||||
/** Maximum number of messages to queue during disconnection (default: 1000) */
|
||||
maxQueueSize?: number;
|
||||
|
||||
/** Maximum age of queued messages in milliseconds (default: 60000) */
|
||||
maxMessageAge?: number;
|
||||
|
||||
/** WebRTC configuration */
|
||||
rtcConfig?: RTCConfiguration;
|
||||
}
|
||||
|
||||
/**
|
||||
* Configuration for durable channels
|
||||
*/
|
||||
export interface DurableChannelConfig {
|
||||
/** Maximum number of messages to queue (default: 1000) */
|
||||
maxQueueSize?: number;
|
||||
|
||||
/** Maximum age of queued messages in milliseconds (default: 60000) */
|
||||
maxMessageAge?: number;
|
||||
|
||||
/** Whether messages should be delivered in order (default: true) */
|
||||
ordered?: boolean;
|
||||
|
||||
/** Maximum retransmits for unordered channels (default: undefined) */
|
||||
maxRetransmits?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Configuration for durable services
|
||||
*/
|
||||
export interface DurableServiceConfig extends DurableConnectionConfig {
|
||||
/** Username that owns the service */
|
||||
username: string;
|
||||
|
||||
/** Private key for signing service operations */
|
||||
privateKey: string;
|
||||
|
||||
/** Fully qualified service name (e.g., com.example.chat@1.0.0) */
|
||||
serviceFqn: string;
|
||||
|
||||
/** Whether the service is publicly discoverable (default: false) */
|
||||
isPublic?: boolean;
|
||||
|
||||
/** Optional metadata for the service */
|
||||
metadata?: Record<string, any>;
|
||||
|
||||
/** Time-to-live for service in milliseconds (default: server default) */
|
||||
ttl?: number;
|
||||
|
||||
/** Margin before TTL expiry to trigger refresh (default: 0.2 = refresh at 80%) */
|
||||
ttlRefreshMargin?: number;
|
||||
|
||||
/** Number of simultaneous open offers to maintain (default: 1) */
|
||||
poolSize?: number;
|
||||
|
||||
/** Polling interval for checking answers in milliseconds (default: 2000) */
|
||||
pollingInterval?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Queued message structure
|
||||
*/
|
||||
export interface QueuedMessage {
|
||||
/** Message data */
|
||||
data: string | Blob | ArrayBuffer | ArrayBufferView;
|
||||
|
||||
/** Timestamp when message was enqueued */
|
||||
enqueuedAt: number;
|
||||
|
||||
/** Unique message ID */
|
||||
id: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Event type map for DurableConnection
|
||||
*/
|
||||
export interface DurableConnectionEvents extends Record<string, (...args: any[]) => void> {
|
||||
'state': (state: DurableConnectionState, previousState: DurableConnectionState) => void;
|
||||
'connected': () => void;
|
||||
'reconnecting': (attempt: number, maxAttempts: number, nextRetryIn: number) => void;
|
||||
'disconnected': () => void;
|
||||
'failed': (error: Error, permanent: boolean) => void;
|
||||
'closed': () => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Event type map for DurableChannel
|
||||
*/
|
||||
export interface DurableChannelEvents extends Record<string, (...args: any[]) => void> {
|
||||
'open': () => void;
|
||||
'message': (data: any) => void;
|
||||
'error': (error: Error) => void;
|
||||
'close': () => void;
|
||||
'bufferedAmountLow': () => void;
|
||||
'queueOverflow': (droppedCount: number) => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Event type map for DurableService
|
||||
*/
|
||||
export interface DurableServiceEvents extends Record<string, (...args: any[]) => void> {
|
||||
'published': (serviceId: string, uuid: string) => void;
|
||||
'connection': (connectionId: string) => void;
|
||||
'disconnection': (connectionId: string) => void;
|
||||
'ttl-refreshed': (expiresAt: number) => void;
|
||||
'error': (error: Error, context: string) => void;
|
||||
'closed': () => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Information about a durable connection
|
||||
*/
|
||||
export interface ConnectionInfo {
|
||||
/** Username (for username-based connections) */
|
||||
username?: string;
|
||||
|
||||
/** Service FQN (for service-based connections) */
|
||||
serviceFqn?: string;
|
||||
|
||||
/** UUID (for UUID-based connections) */
|
||||
uuid?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Service information returned when service is published
|
||||
*/
|
||||
export interface ServiceInfo {
|
||||
/** Service ID */
|
||||
serviceId: string;
|
||||
|
||||
/** Service UUID for discovery */
|
||||
uuid: string;
|
||||
|
||||
/** Expiration timestamp */
|
||||
expiresAt: number;
|
||||
}
|
||||
54
src/index.ts
54
src/index.ts
@@ -1,6 +1,6 @@
|
||||
/**
|
||||
* @xtr-dev/rondevu-client
|
||||
* WebRTC peer signaling and discovery client with topic-based discovery
|
||||
* WebRTC peer signaling and discovery client with durable connections
|
||||
*/
|
||||
|
||||
// Export main client class
|
||||
@@ -11,44 +11,26 @@ export type { RondevuOptions } from './rondevu.js';
|
||||
export { RondevuAuth } from './auth.js';
|
||||
export type { Credentials, FetchFunction } from './auth.js';
|
||||
|
||||
// Export offers API
|
||||
export { RondevuOffers } from './offers.js';
|
||||
export type {
|
||||
CreateOfferRequest,
|
||||
Offer,
|
||||
IceCandidate,
|
||||
TopicInfo
|
||||
} from './offers.js';
|
||||
|
||||
// Export peer manager
|
||||
export { default as RondevuPeer } from './peer/index.js';
|
||||
export type {
|
||||
PeerOptions,
|
||||
PeerEvents,
|
||||
PeerTimeouts
|
||||
} from './peer/index.js';
|
||||
|
||||
// Export username API
|
||||
export { RondevuUsername } from './usernames.js';
|
||||
export type { UsernameClaimResult, UsernameCheckResult } from './usernames.js';
|
||||
|
||||
// Export services API
|
||||
export { RondevuServices } from './services.js';
|
||||
export type {
|
||||
ServicePublishResult,
|
||||
PublishServiceOptions,
|
||||
ServiceHandle
|
||||
} from './services.js';
|
||||
// Export durable connection APIs
|
||||
export { DurableConnection } from './durable/connection.js';
|
||||
export { DurableChannel } from './durable/channel.js';
|
||||
export { DurableService } from './durable/service.js';
|
||||
|
||||
// Export discovery API
|
||||
export { RondevuDiscovery } from './discovery.js';
|
||||
// Export durable connection types
|
||||
export type {
|
||||
ServiceInfo,
|
||||
ServiceListResult,
|
||||
ServiceQueryResult,
|
||||
ServiceDetails,
|
||||
ConnectResult
|
||||
} from './discovery.js';
|
||||
|
||||
// Export pool types
|
||||
export type { PoolStatus, PooledServiceHandle } from './service-pool.js';
|
||||
DurableConnectionState,
|
||||
DurableChannelState,
|
||||
DurableConnectionConfig,
|
||||
DurableChannelConfig,
|
||||
DurableServiceConfig,
|
||||
QueuedMessage,
|
||||
DurableConnectionEvents,
|
||||
DurableChannelEvents,
|
||||
DurableServiceEvents,
|
||||
ConnectionInfo,
|
||||
ServiceInfo
|
||||
} from './durable/types.js';
|
||||
|
||||
170
src/rondevu.ts
170
src/rondevu.ts
@@ -1,9 +1,15 @@
|
||||
import { RondevuAuth, Credentials, FetchFunction } from './auth.js';
|
||||
import { RondevuOffers } from './offers.js';
|
||||
import { RondevuUsername } from './usernames.js';
|
||||
import { RondevuServices } from './services.js';
|
||||
import { RondevuDiscovery } from './discovery.js';
|
||||
import RondevuPeer from './peer/index.js';
|
||||
import { DurableService } from './durable/service.js';
|
||||
import { DurableConnection } from './durable/connection.js';
|
||||
import { DurableChannel } from './durable/channel.js';
|
||||
import type {
|
||||
DurableServiceConfig,
|
||||
DurableConnectionConfig,
|
||||
ConnectionInfo
|
||||
} from './durable/types.js';
|
||||
|
||||
export interface RondevuOptions {
|
||||
/**
|
||||
@@ -71,8 +77,6 @@ export class Rondevu {
|
||||
readonly usernames: RondevuUsername;
|
||||
|
||||
private _offers?: RondevuOffers;
|
||||
private _services?: RondevuServices;
|
||||
private _discovery?: RondevuDiscovery;
|
||||
private credentials?: Credentials;
|
||||
private baseUrl: string;
|
||||
private fetchFn?: FetchFunction;
|
||||
@@ -93,14 +97,12 @@ export class Rondevu {
|
||||
if (options.credentials) {
|
||||
this.credentials = options.credentials;
|
||||
this._offers = new RondevuOffers(this.baseUrl, this.credentials, this.fetchFn);
|
||||
this._services = new RondevuServices(this.baseUrl, this.credentials);
|
||||
this._discovery = new RondevuDiscovery(this.baseUrl, this.credentials);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get offers API (low-level access, requires authentication)
|
||||
* For most use cases, use services and discovery APIs instead
|
||||
* For most use cases, use the durable connection APIs instead
|
||||
*/
|
||||
get offers(): RondevuOffers {
|
||||
if (!this._offers) {
|
||||
@@ -109,26 +111,6 @@ export class Rondevu {
|
||||
return this._offers;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get services API (requires authentication)
|
||||
*/
|
||||
get services(): RondevuServices {
|
||||
if (!this._services) {
|
||||
throw new Error('Not authenticated. Call register() first or provide credentials.');
|
||||
}
|
||||
return this._services;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get discovery API (requires authentication)
|
||||
*/
|
||||
get discovery(): RondevuDiscovery {
|
||||
if (!this._discovery) {
|
||||
throw new Error('Not authenticated. Call register() first or provide credentials.');
|
||||
}
|
||||
return this._discovery;
|
||||
}
|
||||
|
||||
/**
|
||||
* Register and initialize authenticated client
|
||||
* Generates a cryptographically random peer ID (128-bit)
|
||||
@@ -136,14 +118,12 @@ export class Rondevu {
|
||||
async register(): Promise<Credentials> {
|
||||
this.credentials = await this.auth.register();
|
||||
|
||||
// Create API instances
|
||||
// Create offers API instance
|
||||
this._offers = new RondevuOffers(
|
||||
this.baseUrl,
|
||||
this.credentials,
|
||||
this.fetchFn
|
||||
);
|
||||
this._services = new RondevuServices(this.baseUrl, this.credentials);
|
||||
this._discovery = new RondevuDiscovery(this.baseUrl, this.credentials);
|
||||
|
||||
return this.credentials;
|
||||
}
|
||||
@@ -183,4 +163,134 @@ export class Rondevu {
|
||||
this.rtcIceCandidate
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Expose a durable service with automatic reconnection and TTL refresh
|
||||
*
|
||||
* Creates a service that handles incoming connections with automatic
|
||||
* reconnection and message queuing during network interruptions.
|
||||
*
|
||||
* @param config Service configuration
|
||||
* @returns DurableService instance
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const service = await client.exposeService({
|
||||
* username: 'alice',
|
||||
* privateKey: keypair.privateKey,
|
||||
* serviceFqn: 'chat@1.0.0',
|
||||
* poolSize: 10,
|
||||
* handler: (channel, connectionId) => {
|
||||
* channel.on('message', (data) => {
|
||||
* console.log('Received:', data);
|
||||
* channel.send(`Echo: ${data}`);
|
||||
* });
|
||||
* }
|
||||
* });
|
||||
*
|
||||
* await service.start();
|
||||
* ```
|
||||
*/
|
||||
async exposeService(
|
||||
config: DurableServiceConfig & {
|
||||
handler: (channel: DurableChannel, connectionId: string) => void | Promise<void>;
|
||||
}
|
||||
): Promise<DurableService> {
|
||||
if (!this._offers || !this.credentials) {
|
||||
throw new Error('Not authenticated. Call register() first or provide credentials.');
|
||||
}
|
||||
|
||||
const service = new DurableService(
|
||||
this._offers,
|
||||
this.baseUrl,
|
||||
this.credentials,
|
||||
config.handler,
|
||||
config
|
||||
);
|
||||
|
||||
return service;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a durable connection to a service by username and service FQN
|
||||
*
|
||||
* Establishes a WebRTC connection with automatic reconnection and
|
||||
* message queuing during network interruptions.
|
||||
*
|
||||
* @param username Username of the service provider
|
||||
* @param serviceFqn Fully qualified service name
|
||||
* @param config Optional connection configuration
|
||||
* @returns DurableConnection instance
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const connection = await client.connect('alice', 'chat@1.0.0', {
|
||||
* maxReconnectAttempts: 5
|
||||
* });
|
||||
*
|
||||
* const channel = connection.createChannel('main');
|
||||
* channel.on('message', (data) => {
|
||||
* console.log('Received:', data);
|
||||
* });
|
||||
*
|
||||
* await connection.connect();
|
||||
* channel.send('Hello!');
|
||||
* ```
|
||||
*/
|
||||
async connect(
|
||||
username: string,
|
||||
serviceFqn: string,
|
||||
config?: DurableConnectionConfig
|
||||
): Promise<DurableConnection> {
|
||||
if (!this._offers) {
|
||||
throw new Error('Not authenticated. Call register() first or provide credentials.');
|
||||
}
|
||||
|
||||
const connectionInfo: ConnectionInfo = {
|
||||
username,
|
||||
serviceFqn
|
||||
};
|
||||
|
||||
return new DurableConnection(this._offers, connectionInfo, config);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a durable connection to a service by UUID
|
||||
*
|
||||
* Establishes a WebRTC connection with automatic reconnection and
|
||||
* message queuing during network interruptions.
|
||||
*
|
||||
* @param uuid Service UUID
|
||||
* @param config Optional connection configuration
|
||||
* @returns DurableConnection instance
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const connection = await client.connectByUuid('service-uuid-here', {
|
||||
* maxReconnectAttempts: 5
|
||||
* });
|
||||
*
|
||||
* const channel = connection.createChannel('main');
|
||||
* channel.on('message', (data) => {
|
||||
* console.log('Received:', data);
|
||||
* });
|
||||
*
|
||||
* await connection.connect();
|
||||
* channel.send('Hello!');
|
||||
* ```
|
||||
*/
|
||||
async connectByUuid(
|
||||
uuid: string,
|
||||
config?: DurableConnectionConfig
|
||||
): Promise<DurableConnection> {
|
||||
if (!this._offers) {
|
||||
throw new Error('Not authenticated. Call register() first or provide credentials.');
|
||||
}
|
||||
|
||||
const connectionInfo: ConnectionInfo = {
|
||||
uuid
|
||||
};
|
||||
|
||||
return new DurableConnection(this._offers, connectionInfo, config);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -2,7 +2,6 @@ import { RondevuOffers, Offer } from './offers.js';
|
||||
import { RondevuUsername } from './usernames.js';
|
||||
import RondevuPeer from './peer/index.js';
|
||||
import { OfferPool, AnsweredOffer } from './offer-pool.js';
|
||||
import { ServiceHandle } from './services.js';
|
||||
|
||||
/**
|
||||
* Connection information for tracking active connections
|
||||
@@ -73,9 +72,21 @@ export interface ServicePoolOptions {
|
||||
}
|
||||
|
||||
/**
|
||||
* Extended service handle with pool-specific methods
|
||||
* Service handle with pool-specific methods
|
||||
*/
|
||||
export interface PooledServiceHandle extends ServiceHandle {
|
||||
export interface PooledServiceHandle {
|
||||
/** Service ID */
|
||||
serviceId: string;
|
||||
|
||||
/** Service UUID */
|
||||
uuid: string;
|
||||
|
||||
/** Offer ID */
|
||||
offerId: string;
|
||||
|
||||
/** Unpublish the service */
|
||||
unpublish: () => Promise<void>;
|
||||
|
||||
/** Get current pool status */
|
||||
getStatus: () => PoolStatus;
|
||||
|
||||
|
||||
308
src/services.ts
308
src/services.ts
@@ -1,308 +0,0 @@
|
||||
import { RondevuUsername } from './usernames.js';
|
||||
import RondevuPeer from './peer/index.js';
|
||||
import { RondevuOffers } from './offers.js';
|
||||
import { ServicePool, ServicePoolOptions, PooledServiceHandle, PoolStatus } from './service-pool.js';
|
||||
|
||||
/**
|
||||
* Service publish result
|
||||
*/
|
||||
export interface ServicePublishResult {
|
||||
serviceId: string;
|
||||
uuid: string;
|
||||
offerId: string;
|
||||
expiresAt: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Service publish options
|
||||
*/
|
||||
export interface PublishServiceOptions {
|
||||
username: string;
|
||||
privateKey: string;
|
||||
serviceFqn: string;
|
||||
rtcConfig?: RTCConfiguration;
|
||||
isPublic?: boolean;
|
||||
metadata?: Record<string, any>;
|
||||
ttl?: number;
|
||||
onConnection?: (peer: RondevuPeer) => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Service handle for managing an exposed service
|
||||
*/
|
||||
export interface ServiceHandle {
|
||||
serviceId: string;
|
||||
uuid: string;
|
||||
offerId: string;
|
||||
unpublish: () => Promise<void>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Rondevu Services API
|
||||
* Handles service publishing and management
|
||||
*/
|
||||
export class RondevuServices {
|
||||
private usernameApi: RondevuUsername;
|
||||
private offersApi: RondevuOffers;
|
||||
|
||||
constructor(
|
||||
private baseUrl: string,
|
||||
private credentials: { peerId: string; secret: string }
|
||||
) {
|
||||
this.usernameApi = new RondevuUsername(baseUrl);
|
||||
this.offersApi = new RondevuOffers(baseUrl, credentials);
|
||||
}
|
||||
|
||||
/**
|
||||
* Publishes a service
|
||||
*/
|
||||
async publishService(options: PublishServiceOptions): Promise<ServicePublishResult> {
|
||||
const {
|
||||
username,
|
||||
privateKey,
|
||||
serviceFqn,
|
||||
rtcConfig,
|
||||
isPublic = false,
|
||||
metadata,
|
||||
ttl
|
||||
} = options;
|
||||
|
||||
// Validate FQN format
|
||||
this.validateServiceFqn(serviceFqn);
|
||||
|
||||
// Create WebRTC peer connection to generate offer
|
||||
const pc = new RTCPeerConnection(rtcConfig || {
|
||||
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
|
||||
});
|
||||
|
||||
// Add a data channel (required for datachannel-based services)
|
||||
pc.createDataChannel('rondevu-service');
|
||||
|
||||
// Create offer
|
||||
const offer = await pc.createOffer();
|
||||
await pc.setLocalDescription(offer);
|
||||
|
||||
if (!offer.sdp) {
|
||||
throw new Error('Failed to generate SDP');
|
||||
}
|
||||
|
||||
// Create signature for username verification
|
||||
const timestamp = Date.now();
|
||||
const message = `publish:${username}:${serviceFqn}:${timestamp}`;
|
||||
const signature = await this.usernameApi.signMessage(message, privateKey);
|
||||
|
||||
// Publish service
|
||||
const response = await fetch(`${this.baseUrl}/services`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${this.credentials.peerId}:${this.credentials.secret}`
|
||||
},
|
||||
body: JSON.stringify({
|
||||
username,
|
||||
serviceFqn,
|
||||
sdp: offer.sdp,
|
||||
ttl,
|
||||
isPublic,
|
||||
metadata,
|
||||
signature,
|
||||
message
|
||||
})
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
pc.close();
|
||||
throw new Error(error.error || 'Failed to publish service');
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
// Close the connection for now (would be kept open in a real implementation)
|
||||
pc.close();
|
||||
|
||||
return {
|
||||
serviceId: data.serviceId,
|
||||
uuid: data.uuid,
|
||||
offerId: data.offerId,
|
||||
expiresAt: data.expiresAt
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Unpublishes a service
|
||||
*/
|
||||
async unpublishService(serviceId: string, username: string): Promise<void> {
|
||||
const response = await fetch(`${this.baseUrl}/services/${serviceId}`, {
|
||||
method: 'DELETE',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${this.credentials.peerId}:${this.credentials.secret}`
|
||||
},
|
||||
body: JSON.stringify({ username })
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(error.error || 'Failed to unpublish service');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Exposes a service with an automatic connection handler
|
||||
* This is a convenience method that publishes the service and manages connections
|
||||
*
|
||||
* Set poolSize > 1 to enable offer pooling for handling multiple concurrent connections
|
||||
*/
|
||||
async exposeService(options: Omit<PublishServiceOptions, 'onConnection'> & {
|
||||
handler: (channel: RTCDataChannel, peer: RondevuPeer, connectionId?: string) => void;
|
||||
poolSize?: number;
|
||||
pollingInterval?: number;
|
||||
onPoolStatus?: (status: PoolStatus) => void;
|
||||
onError?: (error: Error, context: string) => void;
|
||||
}): Promise<ServiceHandle | PooledServiceHandle> {
|
||||
const {
|
||||
username,
|
||||
privateKey,
|
||||
serviceFqn,
|
||||
rtcConfig,
|
||||
isPublic,
|
||||
metadata,
|
||||
ttl,
|
||||
handler,
|
||||
poolSize,
|
||||
pollingInterval,
|
||||
onPoolStatus,
|
||||
onError
|
||||
} = options;
|
||||
|
||||
// If poolSize > 1, use pooled implementation
|
||||
if (poolSize && poolSize > 1) {
|
||||
const pool = new ServicePool(this.baseUrl, this.credentials, {
|
||||
username,
|
||||
privateKey,
|
||||
serviceFqn,
|
||||
rtcConfig,
|
||||
isPublic,
|
||||
metadata,
|
||||
ttl,
|
||||
handler: (channel, peer, connectionId) => handler(channel, peer, connectionId),
|
||||
poolSize,
|
||||
pollingInterval,
|
||||
onPoolStatus,
|
||||
onError
|
||||
});
|
||||
return await pool.start();
|
||||
}
|
||||
|
||||
// Otherwise, use existing single-offer logic (UNCHANGED)
|
||||
// Validate FQN
|
||||
this.validateServiceFqn(serviceFqn);
|
||||
|
||||
// Create peer connection
|
||||
const pc = new RTCPeerConnection(rtcConfig || {
|
||||
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
|
||||
});
|
||||
|
||||
// Create data channel
|
||||
const channel = pc.createDataChannel('rondevu-service');
|
||||
|
||||
// Set up handler
|
||||
channel.onopen = () => {
|
||||
const peer = new RondevuPeer(
|
||||
this.offersApi,
|
||||
rtcConfig || {
|
||||
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
|
||||
}
|
||||
);
|
||||
handler(channel, peer);
|
||||
};
|
||||
|
||||
// Create offer
|
||||
const offer = await pc.createOffer();
|
||||
await pc.setLocalDescription(offer);
|
||||
|
||||
if (!offer.sdp) {
|
||||
pc.close();
|
||||
throw new Error('Failed to generate SDP');
|
||||
}
|
||||
|
||||
// Create signature
|
||||
const timestamp = Date.now();
|
||||
const message = `publish:${username}:${serviceFqn}:${timestamp}`;
|
||||
const signature = await this.usernameApi.signMessage(message, privateKey);
|
||||
|
||||
// Publish service
|
||||
const response = await fetch(`${this.baseUrl}/services`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${this.credentials.peerId}:${this.credentials.secret}`
|
||||
},
|
||||
body: JSON.stringify({
|
||||
username,
|
||||
serviceFqn,
|
||||
sdp: offer.sdp,
|
||||
ttl,
|
||||
isPublic,
|
||||
metadata,
|
||||
signature,
|
||||
message
|
||||
})
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
pc.close();
|
||||
throw new Error(error.error || 'Failed to expose service');
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
return {
|
||||
serviceId: data.serviceId,
|
||||
uuid: data.uuid,
|
||||
offerId: data.offerId,
|
||||
unpublish: () => this.unpublishService(data.serviceId, username)
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates service FQN format
|
||||
*/
|
||||
private validateServiceFqn(fqn: string): void {
|
||||
const parts = fqn.split('@');
|
||||
if (parts.length !== 2) {
|
||||
throw new Error('Service FQN must be in format: service-name@version');
|
||||
}
|
||||
|
||||
const [serviceName, version] = parts;
|
||||
|
||||
// Validate service name (reverse domain notation)
|
||||
const serviceNameRegex = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
|
||||
if (!serviceNameRegex.test(serviceName)) {
|
||||
throw new Error('Service name must be reverse domain notation (e.g., com.example.service)');
|
||||
}
|
||||
|
||||
if (serviceName.length < 3 || serviceName.length > 128) {
|
||||
throw new Error('Service name must be 3-128 characters');
|
||||
}
|
||||
|
||||
// Validate version (semantic versioning)
|
||||
const versionRegex = /^[0-9]+\.[0-9]+\.[0-9]+(-[a-z0-9.-]+)?$/;
|
||||
if (!versionRegex.test(version)) {
|
||||
throw new Error('Version must be semantic versioning (e.g., 1.0.0, 2.1.3-beta)');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Parses a service FQN into name and version
|
||||
*/
|
||||
parseServiceFqn(fqn: string): { name: string; version: string } {
|
||||
const parts = fqn.split('@');
|
||||
if (parts.length !== 2) {
|
||||
throw new Error('Invalid FQN format');
|
||||
}
|
||||
return { name: parts[0], version: parts[1] };
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user