@xtr-dev/rondevu-client 0.18.6 → 0.18.8

package/dist/message-buffer.js

@@ -0,0 +1,106 @@
+/**
+ * Message buffering system for storing messages during disconnections
+ */
+export class MessageBuffer {
+    constructor(config) {
+        this.config = config;
+        this.buffer = [];
+        this.messageIdCounter = 0;
+    }
+    /**
+     * Add a message to the buffer
+     * Returns the buffered message with metadata
+     */
+    add(data) {
+        const message = {
+            id: `msg_${Date.now()}_${this.messageIdCounter++}`,
+            data,
+            timestamp: Date.now(),
+            attempts: 0,
+        };
+        // Check if buffer is full
+        if (this.buffer.length >= this.config.maxSize) {
+            // Remove oldest message
+            const discarded = this.buffer.shift();
+            if (discarded) {
+                return message; // Signal overflow by returning the new message
+            }
+        }
+        this.buffer.push(message);
+        return message;
+    }
+    /**
+     * Get all messages in the buffer
+     */
+    getAll() {
+        return [...this.buffer];
+    }
+    /**
+     * Get messages that haven't exceeded max age
+     */
+    getValid() {
+        const now = Date.now();
+        return this.buffer.filter((msg) => now - msg.timestamp < this.config.maxAge);
+    }
+    /**
+     * Get and remove expired messages
+     */
+    getExpired() {
+        const now = Date.now();
+        const expired = [];
+        this.buffer = this.buffer.filter((msg) => {
+            if (now - msg.timestamp >= this.config.maxAge) {
+                expired.push(msg);
+                return false;
+            }
+            return true;
+        });
+        return expired;
+    }
+    /**
+     * Remove a specific message by ID
+     */
+    remove(messageId) {
+        const index = this.buffer.findIndex((msg) => msg.id === messageId);
+        if (index === -1)
+            return null;
+        const [removed] = this.buffer.splice(index, 1);
+        return removed;
+    }
+    /**
+     * Clear all messages from the buffer
+     */
+    clear() {
+        const cleared = [...this.buffer];
+        this.buffer = [];
+        return cleared;
+    }
+    /**
+     * Increment attempt count for a message
+     */
+    incrementAttempt(messageId) {
+        const message = this.buffer.find((msg) => msg.id === messageId);
+        if (!message)
+            return false;
+        message.attempts++;
+        return true;
+    }
+    /**
+     * Get the current size of the buffer
+     */
+    size() {
+        return this.buffer.length;
+    }
+    /**
+     * Check if buffer is empty
+     */
+    isEmpty() {
+        return this.buffer.length === 0;
+    }
+    /**
+     * Check if buffer is full
+     */
+    isFull() {
+        return this.buffer.length >= this.config.maxSize;
+    }
+}

package/dist/offerer-connection.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Offerer-side WebRTC connection with offer creation and answer processing
+ */
+import { RondevuConnection } from './connection.js';
+import { RondevuAPI } from './api.js';
+import { ConnectionConfig } from './connection-config.js';
+export interface OffererOptions {
+    api: RondevuAPI;
+    serviceFqn: string;
+    offerId: string;
+    rtcConfig?: RTCConfiguration;
+    config?: Partial<ConnectionConfig>;
+}
+/**
+ * Offerer connection - creates offers and waits for answers
+ */
+export declare class OffererConnection extends RondevuConnection {
+    private api;
+    private serviceFqn;
+    private offerId;
+    constructor(options: OffererOptions);
+    /**
+     * Initialize the connection by creating offer
+     */
+    initialize(): Promise<void>;
+    /**
+     * Process an answer from the answerer
+     */
+    processAnswer(sdp: string, answererId: string): Promise<void>;
+    /**
+     * Generate a hash fingerprint of SDP for deduplication
+     */
+    private hashSdp;
+    /**
+     * Handle local ICE candidate generation
+     */
+    protected onLocalIceCandidate(candidate: RTCIceCandidate): void;
+    /**
+     * Poll for remote ICE candidates
+     */
+    protected pollIceCandidates(): void;
+    /**
+     * Attempt to reconnect
+     */
+    protected attemptReconnect(): void;
+    /**
+     * Get the offer ID
+     */
+    getOfferId(): string;
+}

package/dist/offerer-connection.js

@@ -0,0 +1,193 @@
+/**
+ * Offerer-side WebRTC connection with offer creation and answer processing
+ */
+import { RondevuConnection } from './connection.js';
+import { ConnectionState } from './connection-events.js';
+/**
+ * Offerer connection - creates offers and waits for answers
+ */
+export class OffererConnection extends RondevuConnection {
+    constructor(options) {
+        super(options.rtcConfig, options.config);
+        this.api = options.api;
+        this.serviceFqn = options.serviceFqn;
+        this.offerId = options.offerId;
+    }
+    /**
+     * Initialize the connection by creating offer
+     */
+    async initialize() {
+        this.debug('Initializing offerer connection');
+        // Create peer connection
+        this.createPeerConnection();
+        // Create data channel BEFORE creating offer
+        // This is critical to avoid race conditions
+        if (!this.pc)
+            throw new Error('Peer connection not created');
+        this.dc = this.pc.createDataChannel('data', {
+            ordered: true,
+            maxRetransmits: 3,
+        });
+        // Setup data channel handlers IMMEDIATELY after creation
+        this.setupDataChannelHandlers(this.dc);
+        // Start connection timeout
+        this.startConnectionTimeout();
+        // Create and set local description
+        const offer = await this.pc.createOffer();
+        await this.pc.setLocalDescription(offer);
+        this.transitionTo(ConnectionState.SIGNALING, 'Offer created, waiting for answer');
+    }
+    /**
+     * Process an answer from the answerer
+     */
+    async processAnswer(sdp, answererId) {
+        if (!this.pc) {
+            this.debug('Cannot process answer: peer connection not initialized');
+            return;
+        }
+        // Generate SDP fingerprint for deduplication
+        const fingerprint = await this.hashSdp(sdp);
+        // Check for duplicate answer
+        if (this.answerProcessed) {
+            if (this.answerSdpFingerprint === fingerprint) {
+                this.debug('Duplicate answer detected (same fingerprint), skipping');
+                this.emit('answer:duplicate', this.offerId);
+                return;
+            }
+            else {
+                throw new Error('Received different answer after already processing one (protocol violation)');
+            }
+        }
+        // Validate state
+        if (this.state !== ConnectionState.SIGNALING && this.state !== ConnectionState.CHECKING) {
+            this.debug(`Cannot process answer in state ${this.state}`);
+            return;
+        }
+        // Mark as processed BEFORE setRemoteDescription to prevent race conditions
+        this.answerProcessed = true;
+        this.answerSdpFingerprint = fingerprint;
+        try {
+            await this.pc.setRemoteDescription({
+                type: 'answer',
+                sdp,
+            });
+            this.debug(`Answer processed successfully from ${answererId}`);
+            this.emit('answer:processed', this.offerId, answererId);
+        }
+        catch (error) {
+            // Reset flags on error so we can try again
+            this.answerProcessed = false;
+            this.answerSdpFingerprint = null;
+            this.debug('Failed to set remote description:', error);
+            throw error;
+        }
+    }
+    /**
+     * Generate a hash fingerprint of SDP for deduplication
+     */
+    async hashSdp(sdp) {
+        // Simple hash using built-in crypto if available
+        if (typeof crypto !== 'undefined' && crypto.subtle) {
+            const encoder = new TextEncoder();
+            const data = encoder.encode(sdp);
+            const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+            const hashArray = Array.from(new Uint8Array(hashBuffer));
+            return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+        }
+        else {
+            // Fallback: use simple string hash
+            let hash = 0;
+            for (let i = 0; i < sdp.length; i++) {
+                const char = sdp.charCodeAt(i);
+                hash = (hash << 5) - hash + char;
+                hash = hash & hash;
+            }
+            return hash.toString(16);
+        }
+    }
+    /**
+     * Handle local ICE candidate generation
+     */
+    onLocalIceCandidate(candidate) {
+        this.debug('Generated local ICE candidate');
+        // Send ICE candidate to server
+        this.api
+            .addOfferIceCandidates(this.serviceFqn, this.offerId, [
+            {
+                candidate: candidate.candidate,
+                sdpMLineIndex: candidate.sdpMLineIndex,
+                sdpMid: candidate.sdpMid,
+            },
+        ])
+            .catch((error) => {
+            this.debug('Failed to send ICE candidate:', error);
+        });
+    }
+    /**
+     * Poll for remote ICE candidates
+     */
+    pollIceCandidates() {
+        this.api
+            .getOfferIceCandidates(this.serviceFqn, this.offerId, this.lastIcePollTime)
+            .then((result) => {
+            if (result.candidates.length > 0) {
+                this.debug(`Received ${result.candidates.length} remote ICE candidates`);
+                for (const iceCandidate of result.candidates) {
+                    if (iceCandidate.candidate && this.pc) {
+                        const candidate = iceCandidate.candidate;
+                        this.pc
+                            .addIceCandidate(new RTCIceCandidate(candidate))
+                            .then(() => {
+                            this.emit('ice:candidate:remote', new RTCIceCandidate(candidate));
+                        })
+                            .catch((error) => {
+                            this.debug('Failed to add ICE candidate:', error);
+                        });
+                    }
+                    // Update last poll time
+                    if (iceCandidate.createdAt > this.lastIcePollTime) {
+                        this.lastIcePollTime = iceCandidate.createdAt;
+                    }
+                }
+            }
+        })
+            .catch((error) => {
+            this.debug('Failed to poll ICE candidates:', error);
+        });
+    }
+    /**
+     * Attempt to reconnect
+     */
+    attemptReconnect() {
+        this.debug('Attempting to reconnect');
+        // For offerer, we need to create a new offer
+        // Clean up old connection
+        if (this.pc) {
+            this.pc.close();
+            this.pc = null;
+        }
+        if (this.dc) {
+            this.dc.close();
+            this.dc = null;
+        }
+        // Reset answer processing flags
+        this.answerProcessed = false;
+        this.answerSdpFingerprint = null;
+        // Reinitialize
+        this.initialize()
+            .then(() => {
+            this.emit('reconnect:success');
+        })
+            .catch((error) => {
+            this.debug('Reconnection failed:', error);
+            this.emit('reconnect:failed', error);
+            this.scheduleReconnect();
+        });
+    }
+    /**
+     * Get the offer ID
+     */
+    getOfferId() {
+        return this.offerId;
+    }
+}

package/dist/rondevu.d.ts

@@ -1,6 +1,9 @@
 import { RondevuAPI, Keypair, IceCandidate, BatcherOptions } from './api.js';
 import { CryptoAdapter } from './crypto-adapter.js';
 import { EventEmitter } from 'eventemitter3';
+import { OffererConnection } from './offerer-connection.js';
+import { AnswererConnection } from './answerer-connection.js';
+import { ConnectionConfig } from './connection-config.js';
 export type IceServerPreset = 'ipv4-turn' | 'hostname-turns' | 'google-stun' | 'relay-only';
 export declare const ICE_SERVER_PRESETS: Record<IceServerPreset, RTCIceServer[]>;
 export interface RondevuOptions {
@@ -32,6 +35,7 @@ export interface PublishServiceOptions {
     maxOffers: number;
     offerFactory?: OfferFactory;
     ttl?: number;
+    connectionConfig?: Partial<ConnectionConfig>;
 }
 export interface ConnectionContext {
     pc: RTCPeerConnection;
@@ -44,8 +48,8 @@ export interface ConnectToServiceOptions {
     serviceFqn?: string;
     service?: string;
     username?: string;
-    onConnection?: (context: ConnectionContext) => void | Promise<void>;
     rtcConfig?: RTCConfiguration;
+    connectionConfig?: Partial<ConnectionConfig>;
 }
 export interface ActiveOffer {
     offerId: string;
@@ -101,14 +105,13 @@ export declare class ConnectionError extends RondevuError {
     constructor(message: string, context?: Record<string, any>);
 }
 /**
- * Rondevu - Complete WebRTC signaling client
+ * Rondevu - Complete WebRTC signaling client with durable connections
  *
- * Provides a unified API for:
- * - Implicit username claiming (auto-claimed on first authenticated request)
- * - Service publishing with automatic signature generation
- * - Service discovery (direct, random, paginated)
- * - WebRTC signaling (offer/answer exchange, ICE relay)
- * - Keypair management
+ * v1.0.0 introduces breaking changes:
+ * - connectToService() now returns AnswererConnection instead of ConnectionContext
+ * - Automatic reconnection and message buffering built-in
+ * - Connection objects expose .send() method instead of raw DataChannel
+ * - Rich event system for connection lifecycle (connected, disconnected, reconnecting, etc.)
  *
  * @example
  * ```typescript
@@ -119,39 +122,39 @@ export declare class ConnectionError extends RondevuError {
  *   iceServers: 'ipv4-turn'  // Use preset: 'ipv4-turn', 'hostname-turns', 'google-stun', or 'relay-only'
  * })
  *
- * // Or use custom ICE servers
- * const rondevu2 = await Rondevu.connect({
- *   apiUrl: 'https://signal.example.com',
- *   username: 'bob',
- *   iceServers: [
- *     { urls: 'stun:stun.l.google.com:19302' },
- *     { urls: 'turn:turn.example.com:3478', username: 'user', credential: 'pass' }
- *   ]
- * })
- *
  * // Publish a service with automatic offer management
  * await rondevu.publishService({
  *   service: 'chat:2.0.0',
- *   maxOffers: 5,  // Maintain up to 5 concurrent offers
- *   offerFactory: async (pc) => {
- *     // pc is created by Rondevu with ICE handlers already attached
- *     const dc = pc.createDataChannel('chat')
- *     const offer = await pc.createOffer()
- *     await pc.setLocalDescription(offer)
- *     return { dc, offer }
- *   }
+ *   maxOffers: 5  // Maintain up to 5 concurrent offers
  * })
  *
  * // Start accepting connections (auto-fills offers and polls)
  * await rondevu.startFilling()
  *
- * // Access active connections
- * for (const offer of rondevu.getActiveOffers()) {
- *   offer.dc?.addEventListener('message', (e) => console.log(e.data))
- * }
+ * // Listen for connections (v1.0.0 API)
+ * rondevu.on('connection:opened', (offerId, connection) => {
+ *   connection.on('connected', () => console.log('Connected!'))
+ *   connection.on('message', (data) => console.log('Received:', data))
+ *   connection.send('Hello!')
+ * })
+ *
+ * // Connect to a service (v1.0.0 - returns AnswererConnection)
+ * const connection = await rondevu.connectToService({
+ *   serviceFqn: 'chat:2.0.0@bob'
+ * })
+ *
+ * connection.on('connected', () => {
+ *   console.log('Connected!')
+ *   connection.send('Hello!')
+ * })
+ *
+ * connection.on('message', (data) => {
+ *   console.log('Received:', data)
+ * })
  *
- * // Stop when done
- * rondevu.stopFilling()
+ * connection.on('reconnecting', (attempt) => {
+ *   console.log(`Reconnecting, attempt ${attempt}`)
+ * })
  * ```
  */
 export declare class Rondevu extends EventEmitter {
@@ -172,11 +175,12 @@ export declare class Rondevu extends EventEmitter {
     private maxOffers;
     private offerFactory;
     private ttl;
-    private activeOffers;
+    private activeConnections;
+    private connectionConfig?;
     private filling;
+    private fillingSemaphore;
     private pollingInterval;
     private lastPollTimestamp;
-    private isPolling;
     private constructor();
     /**
      * Internal debug logging - only logs if debug mode is enabled
@@ -215,26 +219,22 @@ export declare class Rondevu extends EventEmitter {
      * ```typescript
      * await rondevu.publishService({
      *   service: 'chat:2.0.0',
-     *   maxOffers: 5
+     *   maxOffers: 5,
+     *   connectionConfig: {
+     *     reconnectEnabled: true,
+     *     bufferEnabled: true
+     *   }
      * })
      * await rondevu.startFilling()
      * ```
      */
     publishService(options: PublishServiceOptions): Promise<void>;
     /**
-     * Set up ICE candidate handler to send candidates to the server
-     *
-     * Note: This is used by connectToService() where the offerId is already known.
-     * For createOffer(), we use inline ICE handling with early candidate queuing
-     * since the offerId isn't available until after the factory completes.
-     */
-    private setupIceCandidateHandler;
-    /**
-     * Create a single offer and publish it to the server
+     * Create a single offer and publish it to the server using OffererConnection
      */
     private createOffer;
     /**
-     * Fill offers to reach maxOffers count
+     * Fill offers to reach maxOffers count with semaphore protection
      */
     private fillOffers;
     /**
@@ -259,7 +259,7 @@ export declare class Rondevu extends EventEmitter {
     /**
      * Check if an offer is currently connected
      * @param offerId - The offer ID to check
-     * @returns True if the offer exists and has been answered
+     * @returns True if the offer exists and is connected
      */
     isConnected(offerId: string): boolean;
     /**
@@ -283,41 +283,45 @@ export declare class Rondevu extends EventEmitter {
      */
     private resolveServiceFqn;
     /**
-     * Start polling for remote ICE candidates
-     * Returns the polling interval ID
-     */
-    private startIcePolling;
-    /**
-     * Automatically connect to a service (answerer side)
-     * Handles the entire connection flow: discovery, WebRTC setup, answer exchange, ICE candidates
+     * Connect to a service (answerer side) - v1.0.0 API
+     * Returns an AnswererConnection with automatic reconnection and buffering
+     *
+     * BREAKING CHANGE: This now returns AnswererConnection instead of ConnectionContext
      *
      * @example
      * ```typescript
      * // Connect to specific user
      * const connection = await rondevu.connectToService({
      *   serviceFqn: 'chat:2.0.0@alice',
-     *   onConnection: ({ dc, peerUsername }) => {
-     *     console.log('Connected to', peerUsername)
-     *     dc.addEventListener('message', (e) => console.log(e.data))
-     *     dc.addEventListener('open', () => dc.send('Hello!'))
+     *   connectionConfig: {
+     *     reconnectEnabled: true,
+     *     bufferEnabled: true
      *   }
      * })
      *
+     * connection.on('connected', () => {
+     *   console.log('Connected!')
+     *   connection.send('Hello!')
+     * })
+     *
+     * connection.on('message', (data) => {
+     *   console.log('Received:', data)
+     * })
+     *
+     * connection.on('reconnecting', (attempt) => {
+     *   console.log(`Reconnecting, attempt ${attempt}`)
+     * })
+     *
      * // Discover random service
      * const connection = await rondevu.connectToService({
-     *   service: 'chat:2.0.0',
-     *   onConnection: ({ dc, peerUsername }) => {
-     *     console.log('Connected to', peerUsername)
-     *   }
+     *   service: 'chat:2.0.0'
      * })
      * ```
      */
-    connectToService(options: ConnectToServiceOptions): Promise<ConnectionContext>;
+    connectToService(options: ConnectToServiceOptions): Promise<AnswererConnection>;
     /**
      * Find a service - unified discovery method
      *
-     * Replaces getService(), discoverService(), and discoverServices() with a single method.
-     *
      * @param serviceFqn - Service identifier (e.g., 'chat:1.0.0' or 'chat:1.0.0@alice')
      * @param options - Discovery options
      *
@@ -399,6 +403,15 @@ export declare class Rondevu extends EventEmitter {
      * Get the public key
      */
     getPublicKey(): string;
+    /**
+     * Get active connections (for offerer side)
+     */
+    getActiveConnections(): Map<string, OffererConnection>;
+    /**
+     * Get all active offers (legacy compatibility)
+     * @deprecated Use getActiveConnections() instead
+     */
+    getActiveOffers(): ActiveOffer[];
     /**
      * Access to underlying API for advanced operations
      * @deprecated Use direct methods on Rondevu instance instead