@xtr-dev/rondevu-client 0.18.10 → 0.20.1

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
 
-🌐 **Simple WebRTC signaling client with username-based discovery**
+🌐 **WebRTC signaling client with durable connections**
 
-TypeScript/JavaScript client for Rondevu, providing WebRTC signaling with username claiming, service publishing/discovery, and efficient batch polling.
+TypeScript/JavaScript client for Rondevu, providing WebRTC signaling with **automatic reconnection**, **message buffering**, username claiming, service publishing/discovery, and efficient batch polling.
 
 **Related repositories:**
 - [@xtr-dev/rondevu-client](https://github.com/xtr-dev/rondevu-client) - TypeScript client library ([npm](https://www.npmjs.com/package/@xtr-dev/rondevu-client))
@@ -15,15 +15,24 @@ TypeScript/JavaScript client for Rondevu, providing WebRTC signaling with userna
 
 ## Features
 
+### ✨ New in v0.20.0
+- **🔄 Automatic Reconnection**: Built-in exponential backoff for failed connections
+- **📦 Message Buffering**: Queues messages during disconnections, replays on reconnect
+- **🔄 Connection Persistence**: OffererConnection objects persist across disconnections via offer rotation
+- **📊 Connection State Machine**: Explicit lifecycle tracking with native RTC events
+- **🎯 Rich Event System**: 20+ events for monitoring connection health including `connection:rotated`
+- **⚡ Improved Reliability**: ICE polling lifecycle management, proper cleanup, rotation fallback
+- **🏗️ Internal Refactoring**: Cleaner codebase with OfferPool extraction and consolidated ICE polling
+
+### Core Features
 - **Username Claiming**: Secure ownership with Ed25519 signatures
 - **Anonymous Users**: Auto-generated anonymous usernames for quick testing
 - **Service Publishing**: Publish services with multiple offers for connection pooling
 - **Service Discovery**: Direct lookup, random discovery, or paginated search
-- **Efficient Batch Polling**: Single endpoint for answers and ICE candidates (50% fewer requests)
+- **Efficient Batch Polling**: Single endpoint for answers and ICE candidates
 - **Semantic Version Matching**: Compatible version resolution (chat:1.0.0 matches any 1.x.x)
 - **TypeScript**: Full type safety and autocomplete
 - **Keypair Management**: Generate or reuse Ed25519 keypairs
-- **Automatic Signatures**: All authenticated requests signed automatically
 
 ## Installation
 
@@ -49,27 +58,35 @@ const rondevu = await Rondevu.connect({
 await rondevu.publishService({
   service: 'chat:1.0.0',
   maxOffers: 5,  // Maintain up to 5 concurrent offers
-  offerFactory: async (pc) => {
-    // pc is created by Rondevu with ICE handlers already attached
-    const dc = pc.createDataChannel('chat')
-
-    dc.addEventListener('open', () => {
-      console.log('Connection opened!')
-      dc.send('Hello from Alice!')
-    })
-
-    dc.addEventListener('message', (e) => {
-      console.log('Received:', e.data)
-    })
-
-    const offer = await pc.createOffer()
-    await pc.setLocalDescription(offer)
-    return { dc, offer }
+  connectionConfig: {
+    reconnectEnabled: true,    // Auto-reconnect on failures
+    bufferEnabled: true,       // Buffer messages during disconnections
+    connectionTimeout: 30000   // 30 second timeout
   }
 })
 
 // 3. Start accepting connections
 await rondevu.startFilling()
+
+// 4. Handle incoming connections
+rondevu.on('connection:opened', (offerId, connection) => {
+  console.log('New connection:', offerId)
+
+  // Listen for messages
+  connection.on('message', (data) => {
+    console.log('Received:', data)
+  })
+
+  // Monitor connection state
+  connection.on('connected', () => {
+    console.log('Fully connected!')
+    connection.send('Hello from Alice!')
+  })
+
+  connection.on('disconnected', () => {
+    console.log('Connection lost, will auto-reconnect')
+  })
+})
 ```
 
 ### Connecting to a Service (Answerer)
@@ -84,25 +101,38 @@ const rondevu = await Rondevu.connect({
   iceServers: 'ipv4-turn'
 })
 
-// 2. Connect to service (automatic WebRTC setup)
+// 2. Connect to service - returns AnswererConnection
 const connection = await rondevu.connectToService({
   serviceFqn: 'chat:1.0.0@alice',
-  onConnection: ({ dc, peerUsername }) => {
-    console.log('Connected to', peerUsername)
+  connectionConfig: {
+    reconnectEnabled: true,
+    bufferEnabled: true,
+    maxReconnectAttempts: 5
+  }
+})
 
-    dc.addEventListener('message', (e) => {
-      console.log('Received:', e.data)
-    })
+// 3. Setup event handlers
+connection.on('connected', () => {
+  console.log('Connected to alice!')
+  connection.send('Hello from Bob!')
+})
 
-    dc.addEventListener('open', () => {
-      dc.send('Hello from Bob!')
-    })
-  }
+connection.on('message', (data) => {
+  console.log('Received:', data)
+})
+
+// 4. Monitor connection health
+connection.on('reconnecting', (attempt) => {
+  console.log(`Reconnecting... attempt ${attempt}`)
 })
 
-// Access connection
-connection.dc.send('Another message')
-connection.pc.close()  // Close when done
+connection.on('reconnect:success', () => {
+  console.log('Back online!')
+})
+
+connection.on('failed', (error) => {
+  console.error('Connection failed:', error)
+})
 ```
 
 ## Core API
@@ -126,52 +156,299 @@ await rondevu.publishService({
   service: string,        // e.g., 'chat:1.0.0' (username auto-appended)
   maxOffers: number,      // Maximum concurrent offers to maintain
   offerFactory?: OfferFactory,  // Optional: custom offer creation
-  ttl?: number           // Optional: offer lifetime in ms (default: 300000)
+  ttl?: number,           // Optional: offer lifetime in ms (default: 300000)
+  connectionConfig?: Partial<ConnectionConfig>  // Optional: durability settings
 })
 
 await rondevu.startFilling()  // Start accepting connections
 rondevu.stopFilling()         // Stop and close all connections
 ```
 
+### Connecting to Services
+
+**⚠️ Breaking Change in v0.18.9+:** `connectToService()` now returns `AnswererConnection` instead of `ConnectionContext`.
+
+```typescript
+// New API (v0.18.9/v0.18.11+)
+const connection = await rondevu.connectToService({
+  serviceFqn?: string,     // Full FQN like 'chat:1.0.0@alice'
+  service?: string,        // Service without username (for discovery)
+  username?: string,       // Target username (combined with service)
+  connectionConfig?: Partial<ConnectionConfig>,  // Durability settings
+  rtcConfig?: RTCConfiguration  // Optional: override ICE servers
+})
+
+// Setup event handlers
+connection.on('connected', () => {
+  connection.send('Hello!')
+})
+
+connection.on('message', (data) => {
+  console.log(data)
+})
+```
+
+### Connection Configuration
+
+```typescript
+interface ConnectionConfig {
+  // Timeouts
+  connectionTimeout: number      // Default: 30000ms (30s)
+  iceGatheringTimeout: number    // Default: 10000ms (10s)
+
+  // Reconnection
+  reconnectEnabled: boolean      // Default: true
+  maxReconnectAttempts: number   // Default: 5 (0 = infinite)
+  reconnectBackoffBase: number   // Default: 1000ms
+  reconnectBackoffMax: number    // Default: 30000ms (30s)
+
+  // Message buffering
+  bufferEnabled: boolean         // Default: true
+  maxBufferSize: number          // Default: 100 messages
+  maxBufferAge: number           // Default: 60000ms (1 min)
+
+  // Debug
+  debug: boolean                 // Default: false
+}
+```
+
+### Connection Events
+
+```typescript
+// Lifecycle events
+connection.on('connecting', () => {})
+connection.on('connected', () => {})
+connection.on('disconnected', (reason) => {})
+connection.on('failed', (error) => {})
+connection.on('closed', (reason) => {})
+
+// Reconnection events
+connection.on('reconnecting', (attempt) => {})
+connection.on('reconnect:success', () => {})
+connection.on('reconnect:failed', (error) => {})
+connection.on('reconnect:exhausted', (attempts) => {})
+
+// Message events
+connection.on('message', (data) => {})
+connection.on('message:buffered', (data) => {})
+connection.on('message:replayed', (message) => {})
+
+// ICE events
+connection.on('ice:connection:state', (state) => {})
+connection.on('ice:polling:started', () => {})
+connection.on('ice:polling:stopped', () => {})
+```
+
 ### Service Discovery
 
 ```typescript
-// Direct lookup (with username)
-await rondevu.getService('chat:1.0.0@alice')
+// Unified discovery API
+const service = await rondevu.findService(
+  'chat:1.0.0@alice',  // Direct lookup (with username)
+  { mode: 'direct' }
+)
+
+const service = await rondevu.findService(
+  'chat:1.0.0',  // Random discovery (without username)
+  { mode: 'random' }
+)
+
+const result = await rondevu.findService(
+  'chat:1.0.0',
+  {
+    mode: 'paginated',
+    limit: 20,
+    offset: 0
+  }
+)
+```
+
+## Migration Guide
+
+**Upgrading from v0.18.10 or earlier?** See [MIGRATION.md](./MIGRATION.md) for detailed upgrade instructions.
 
-// Random discovery (without username)
-await rondevu.discoverService('chat:1.0.0')
+### Quick Migration Summary
 
-// Paginated discovery
-await rondevu.discoverServices('chat:1.0.0', limit, offset)
+**Before (v0.18.7/v0.18.10):**
+```typescript
+const context = await rondevu.connectToService({
+  serviceFqn: 'chat:1.0.0@alice',
+  onConnection: ({ dc }) => {
+    dc.addEventListener('message', (e) => console.log(e.data))
+    dc.send('Hello')
+  }
+})
 ```
 
-### Connecting to Services
+**After (v0.18.9/v0.18.11):**
+```typescript
+const connection = await rondevu.connectToService({
+  serviceFqn: 'chat:1.0.0@alice'
+})
+
+connection.on('connected', () => {
+  connection.send('Hello')  // Use connection.send()
+})
+
+connection.on('message', (data) => {
+  console.log(data)  // data is already extracted
+})
+```
+
+## Advanced Usage
+
+### Custom Offer Factory
+
+```typescript
+await rondevu.publishService({
+  service: 'file-transfer:1.0.0',
+  maxOffers: 3,
+  offerFactory: async (pc) => {
+    // Customize data channel settings
+    const dc = pc.createDataChannel('files', {
+      ordered: true,
+      maxRetransmits: 10
+    })
+
+    // Add custom listeners
+    dc.addEventListener('open', () => {
+      console.log('Transfer channel ready')
+    })
+
+    const offer = await pc.createOffer()
+    await pc.setLocalDescription(offer)
+    return { dc, offer }
+  }
+})
+```
+
+### Accessing Raw RTCPeerConnection
+
+```typescript
+const connection = await rondevu.connectToService({ ... })
+
+// Get raw objects if needed
+const pc = connection.getPeerConnection()
+const dc = connection.getDataChannel()
+
+// Note: Using raw DataChannel bypasses buffering/reconnection features
+if (dc) {
+  dc.addEventListener('message', (e) => {
+    console.log('Raw message:', e.data)
+  })
+}
+```
+
+### Disabling Durability Features
 
 ```typescript
 const connection = await rondevu.connectToService({
-  serviceFqn?: string,     // Full FQN like 'chat:1.0.0@alice'
-  service?: string,        // Service without username (for discovery)
-  username?: string,       // Target username (combined with service)
-  onConnection?: (context) => void,  // Called when data channel opens
-  rtcConfig?: RTCConfiguration  // Optional: override ICE servers
+  serviceFqn: 'chat:1.0.0@alice',
+  connectionConfig: {
+    reconnectEnabled: false,  // Disable auto-reconnect
+    bufferEnabled: false,     // Disable message buffering
+  }
 })
 ```
 
 ## Documentation
 
+📚 **[MIGRATION.md](./MIGRATION.md)** - Upgrade guide from v0.18.7 to v0.18.9
+
 📚 **[ADVANCED.md](./ADVANCED.md)** - Comprehensive guide including:
 - Detailed API reference for all methods
 - Type definitions and interfaces
 - Platform support (Browser & Node.js)
 - Advanced usage patterns
 - Username rules and service FQN format
-- Examples and migration guides
+
+## Connection Persistence (v0.20.0+)
+
+Connection objects now persist across disconnections via **"offer rotation"**. When a connection fails, the same connection object is rebound to a new offer instead of being destroyed:
+
+```typescript
+rondevu.on('connection:opened', (offerId, connection) => {
+    console.log(`Connection ${offerId} opened`)
+
+    // Listen for offer rotation
+    rondevu.on('connection:rotated', (oldOfferId, newOfferId, conn) => {
+        if (conn === connection) {
+            console.log(`Connection rotated: ${oldOfferId} → ${newOfferId}`)
+            // Same connection object! Event listeners still work
+            // Message buffer preserved
+        }
+    })
+
+    connection.on('message', (data) => {
+        console.log('Received:', data)
+        // This listener continues working even after rotation
+    })
+
+    connection.on('failed', () => {
+        console.log('Connection failed, will auto-rotate to new offer')
+    })
+})
+```
+
+**Benefits:**
+- ✅ Same connection object remains usable through disconnections
+- ✅ Message buffer preserved during temporary disconnections
+- ✅ Event listeners don't need to be re-registered
+- ✅ Seamless reconnection experience for offerer side
 
 ## Examples
 
 - [React Demo](https://github.com/xtr-dev/rondevu-demo) - Full browser UI ([live](https://ronde.vu))
 
+## Changelog
+
+### v0.20.0 (Latest)
+- **Connection Persistence** - OffererConnection objects now persist across disconnections
+- **Offer Rotation** - When connection fails, same object is rebound to new offer
+- **Message Buffering** - Now works seamlessly on offerer side through rotations
+- **New Event**: `connection:rotated` emitted when offer is rotated
+- **Internal**: Added `OffererConnection.rebindToOffer()` method
+- **Internal**: Modified OfferPool failure handler to rotate offers instead of destroying connections
+- **Internal**: Added rotation lock to prevent concurrent rotations
+- **Internal**: Added max rotation attempts limit (default: 5)
+- 100% backward compatible - no breaking changes
+
+### v0.19.0
+- **Internal Refactoring** - Improved codebase maintainability (no API changes)
+- Extract OfferPool class for offer lifecycle management
+- Consolidate ICE polling logic (remove ~86 lines of duplicate code)
+- Add AsyncLock utility for race-free concurrent operations
+- Disable reconnection for offerer connections (offers are ephemeral)
+- 100% backward compatible - upgrade without code changes
+
+### v0.18.11
+- Restore EventEmitter-based durable connections (same as v0.18.9)
+- Durable WebRTC connections with state machine
+- Automatic reconnection with exponential backoff
+- Message buffering during disconnections
+- ICE polling lifecycle management
+- **Breaking:** `connectToService()` returns `AnswererConnection` instead of `ConnectionContext`
+- See [MIGRATION.md](./MIGRATION.md) for upgrade guide
+
+### v0.18.10
+- Temporary revert to callback-based API (reverted in v0.18.11)
+
+### v0.18.9
+- Add durable WebRTC connections with state machine
+- Implement automatic reconnection with exponential backoff
+- Add message buffering during disconnections
+- Fix ICE polling lifecycle (stops when connected)
+- Add fillOffers() semaphore to prevent exceeding maxOffers
+- **Breaking:** `connectToService()` returns `AnswererConnection` instead of `ConnectionContext`
+- **Breaking:** `connection:opened` event signature changed
+- See [MIGRATION.md](./MIGRATION.md) for upgrade guide
+
+### v0.18.8
+- Initial durable connections implementation
+
+### v0.18.3
+- Fix EventEmitter cross-platform compatibility
+
 ## License
 
 MIT

package/dist/{api.d.ts → api/client.d.ts}

@@ -1,10 +1,10 @@
 /**
  * Rondevu API Client - RPC interface
  */
-import { CryptoAdapter, Keypair } from './crypto-adapter.js';
-import { BatcherOptions } from './rpc-batcher.js';
-export type { Keypair } from './crypto-adapter.js';
-export type { BatcherOptions } from './rpc-batcher.js';
+import { CryptoAdapter, Keypair } from '../crypto/adapter.js';
+import { BatcherOptions } from './batcher.js';
+export type { Keypair } from '../crypto/adapter.js';
+export type { BatcherOptions } from './batcher.js';
 export interface OfferRequest {
     sdp: string;
 }
@@ -12,8 +12,6 @@ export interface ServiceRequest {
     serviceFqn: string;
     offers: OfferRequest[];
     ttl?: number;
-    signature: string;
-    message: string;
 }
 export interface ServiceOffer {
     offerId: string;
@@ -45,9 +43,19 @@ export declare class RondevuAPI {
     private batcher;
     constructor(baseUrl: string, username: string, keypair: Keypair, cryptoAdapter?: CryptoAdapter, batcherOptions?: BatcherOptions | false);
     /**
-     * Generate authentication parameters for RPC calls
+     * Create canonical JSON string with sorted keys for deterministic signing
      */
-    private generateAuth;
+    private canonicalJSON;
+    /**
+     * Generate authentication headers for RPC request
+     * Signs the payload (method + params + timestamp + username)
+     */
+    private generateAuthHeaders;
+    /**
+     * Generate authentication fields embedded in request body (for batch requests)
+     * Signs the payload (method + params + timestamp + username)
+     */
+    private generateAuthForRequest;
     /**
      * Execute RPC call with optional batching
      */
@@ -58,6 +66,7 @@ export declare class RondevuAPI {
     private rpcDirect;
     /**
      * Execute batch RPC calls directly (bypasses batcher)
+     * Each request in the batch has its own embedded authentication (signature, timestamp, username, publicKey)
      */
     private rpcBatchDirect;
     /**