@xtr-dev/rondevu-client 0.18.6 → 0.18.8

package/dist/connection.js

@@ -0,0 +1,481 @@
+/**
+ * Base connection class with state machine, reconnection, and message buffering
+ */
+import { EventEmitter } from 'eventemitter3';
+import { mergeConnectionConfig } from './connection-config.js';
+import { ConnectionState, } from './connection-events.js';
+import { ExponentialBackoff } from './exponential-backoff.js';
+import { MessageBuffer } from './message-buffer.js';
+/**
+ * Abstract base class for WebRTC connections with durability features
+ */
+export class RondevuConnection extends EventEmitter {
+    constructor(rtcConfig, userConfig) {
+        super();
+        this.rtcConfig = rtcConfig;
+        this.pc = null;
+        this.dc = null;
+        this.state = ConnectionState.INITIALIZING;
+        // Message buffering
+        this.messageBuffer = null;
+        // Reconnection
+        this.backoff = null;
+        this.reconnectTimeout = null;
+        this.reconnectAttempts = 0;
+        // Timeouts
+        this.connectionTimeout = null;
+        this.iceGatheringTimeout = null;
+        // ICE polling
+        this.icePollingInterval = null;
+        this.lastIcePollTime = 0;
+        // Answer fingerprinting (for offerer)
+        this.answerProcessed = false;
+        this.answerSdpFingerprint = null;
+        this.config = mergeConnectionConfig(userConfig);
+        // Initialize message buffer if enabled
+        if (this.config.bufferEnabled) {
+            this.messageBuffer = new MessageBuffer({
+                maxSize: this.config.maxBufferSize,
+                maxAge: this.config.maxBufferAge,
+            });
+        }
+        // Initialize backoff if reconnection enabled
+        if (this.config.reconnectEnabled) {
+            this.backoff = new ExponentialBackoff({
+                base: this.config.reconnectBackoffBase,
+                max: this.config.reconnectBackoffMax,
+                jitter: this.config.reconnectJitter,
+            });
+        }
+    }
+    /**
+     * Transition to a new state and emit events
+     */
+    transitionTo(newState, reason) {
+        if (this.state === newState)
+            return;
+        const oldState = this.state;
+        this.state = newState;
+        this.debug(`State transition: ${oldState} → ${newState}${reason ? ` (${reason})` : ''}`);
+        this.emit('state:changed', { oldState, newState, reason });
+        // Emit specific lifecycle events
+        switch (newState) {
+            case ConnectionState.CONNECTING:
+                this.emit('connecting');
+                break;
+            case ConnectionState.CONNECTED:
+                this.emit('connected');
+                break;
+            case ConnectionState.DISCONNECTED:
+                this.emit('disconnected', reason);
+                break;
+            case ConnectionState.FAILED:
+                this.emit('failed', new Error(reason || 'Connection failed'));
+                break;
+            case ConnectionState.CLOSED:
+                this.emit('closed', reason);
+                break;
+        }
+    }
+    /**
+     * Create and configure RTCPeerConnection
+     */
+    createPeerConnection() {
+        this.pc = new RTCPeerConnection(this.rtcConfig);
+        // Setup event handlers BEFORE any signaling
+        this.pc.onicecandidate = (event) => this.handleIceCandidate(event);
+        this.pc.oniceconnectionstatechange = () => this.handleIceConnectionStateChange();
+        this.pc.onconnectionstatechange = () => this.handleConnectionStateChange();
+        this.pc.onicegatheringstatechange = () => this.handleIceGatheringStateChange();
+        return this.pc;
+    }
+    /**
+     * Setup data channel event handlers
+     */
+    setupDataChannelHandlers(dc) {
+        dc.onopen = () => this.handleDataChannelOpen();
+        dc.onclose = () => this.handleDataChannelClose();
+        dc.onerror = (error) => this.handleDataChannelError(error);
+        dc.onmessage = (event) => this.handleMessage(event);
+    }
+    /**
+     * Handle local ICE candidate generation
+     */
+    handleIceCandidate(event) {
+        this.emit('ice:candidate:local', event.candidate);
+        if (event.candidate) {
+            this.onLocalIceCandidate(event.candidate);
+        }
+    }
+    /**
+     * Handle ICE connection state changes (primary state driver)
+     */
+    handleIceConnectionStateChange() {
+        if (!this.pc)
+            return;
+        const iceState = this.pc.iceConnectionState;
+        this.emit('ice:connection:state', iceState);
+        this.debug(`ICE connection state: ${iceState}`);
+        switch (iceState) {
+            case 'checking':
+                if (this.state === ConnectionState.SIGNALING) {
+                    this.transitionTo(ConnectionState.CHECKING, 'ICE checking started');
+                }
+                this.startIcePolling();
+                break;
+            case 'connected':
+            case 'completed':
+                this.stopIcePolling();
+                // Wait for data channel to open before transitioning to CONNECTED
+                if (this.dc?.readyState === 'open') {
+                    this.transitionTo(ConnectionState.CONNECTED, 'ICE connected and data channel open');
+                    this.onConnected();
+                }
+                break;
+            case 'disconnected':
+                if (this.state === ConnectionState.CONNECTED) {
+                    this.transitionTo(ConnectionState.DISCONNECTED, 'ICE disconnected');
+                    this.scheduleReconnect();
+                }
+                break;
+            case 'failed':
+                this.stopIcePolling();
+                this.transitionTo(ConnectionState.FAILED, 'ICE connection failed');
+                this.scheduleReconnect();
+                break;
+            case 'closed':
+                this.stopIcePolling();
+                this.transitionTo(ConnectionState.CLOSED, 'ICE connection closed');
+                break;
+        }
+    }
+    /**
+     * Handle connection state changes (backup validation)
+     */
+    handleConnectionStateChange() {
+        if (!this.pc)
+            return;
+        const connState = this.pc.connectionState;
+        this.emit('connection:state', connState);
+        this.debug(`Connection state: ${connState}`);
+        // Connection state provides backup validation
+        if (connState === 'failed' && this.state !== ConnectionState.FAILED) {
+            this.transitionTo(ConnectionState.FAILED, 'PeerConnection failed');
+            this.scheduleReconnect();
+        }
+        else if (connState === 'closed' && this.state !== ConnectionState.CLOSED) {
+            this.transitionTo(ConnectionState.CLOSED, 'PeerConnection closed');
+        }
+    }
+    /**
+     * Handle ICE gathering state changes
+     */
+    handleIceGatheringStateChange() {
+        if (!this.pc)
+            return;
+        const gatheringState = this.pc.iceGatheringState;
+        this.emit('ice:gathering:state', gatheringState);
+        this.debug(`ICE gathering state: ${gatheringState}`);
+        if (gatheringState === 'gathering' && this.state === ConnectionState.INITIALIZING) {
+            this.transitionTo(ConnectionState.GATHERING, 'ICE gathering started');
+            this.startIceGatheringTimeout();
+        }
+        else if (gatheringState === 'complete') {
+            this.clearIceGatheringTimeout();
+        }
+    }
+    /**
+     * Handle data channel open event
+     */
+    handleDataChannelOpen() {
+        this.debug('Data channel opened');
+        this.emit('datachannel:open');
+        // Only transition to CONNECTED if ICE is also connected
+        if (this.pc && (this.pc.iceConnectionState === 'connected' || this.pc.iceConnectionState === 'completed')) {
+            this.transitionTo(ConnectionState.CONNECTED, 'Data channel opened and ICE connected');
+            this.onConnected();
+        }
+    }
+    /**
+     * Handle data channel close event
+     */
+    handleDataChannelClose() {
+        this.debug('Data channel closed');
+        this.emit('datachannel:close');
+        if (this.state === ConnectionState.CONNECTED) {
+            this.transitionTo(ConnectionState.DISCONNECTED, 'Data channel closed');
+            this.scheduleReconnect();
+        }
+    }
+    /**
+     * Handle data channel error event
+     */
+    handleDataChannelError(error) {
+        this.debug('Data channel error:', error);
+        this.emit('datachannel:error', error);
+    }
+    /**
+     * Handle incoming message
+     */
+    handleMessage(event) {
+        this.emit('message', event.data);
+    }
+    /**
+     * Called when connection is successfully established
+     */
+    onConnected() {
+        this.clearConnectionTimeout();
+        this.reconnectAttempts = 0;
+        this.backoff?.reset();
+        // Replay buffered messages
+        if (this.messageBuffer && !this.messageBuffer.isEmpty()) {
+            const messages = this.messageBuffer.getValid();
+            this.debug(`Replaying ${messages.length} buffered messages`);
+            for (const message of messages) {
+                try {
+                    this.sendDirect(message.data);
+                    this.emit('message:replayed', message);
+                    this.messageBuffer.remove(message.id);
+                }
+                catch (error) {
+                    this.debug('Failed to replay message:', error);
+                }
+            }
+            // Remove expired messages
+            const expired = this.messageBuffer.getExpired();
+            for (const msg of expired) {
+                this.emit('message:buffer:expired', msg);
+            }
+        }
+    }
+    /**
+     * Start ICE candidate polling
+     */
+    startIcePolling() {
+        if (this.icePollingInterval)
+            return;
+        this.debug('Starting ICE polling');
+        this.emit('ice:polling:started');
+        this.lastIcePollTime = Date.now();
+        this.icePollingInterval = setInterval(() => {
+            const elapsed = Date.now() - this.lastIcePollTime;
+            if (elapsed > this.config.icePollingTimeout) {
+                this.debug('ICE polling timeout');
+                this.stopIcePolling();
+                return;
+            }
+            this.pollIceCandidates();
+        }, this.config.icePollingInterval);
+    }
+    /**
+     * Stop ICE candidate polling
+     */
+    stopIcePolling() {
+        if (!this.icePollingInterval)
+            return;
+        this.debug('Stopping ICE polling');
+        clearInterval(this.icePollingInterval);
+        this.icePollingInterval = null;
+        this.emit('ice:polling:stopped');
+    }
+    /**
+     * Start connection timeout
+     */
+    startConnectionTimeout() {
+        this.clearConnectionTimeout();
+        this.connectionTimeout = setTimeout(() => {
+            if (this.state !== ConnectionState.CONNECTED) {
+                this.debug('Connection timeout');
+                this.emit('connection:timeout');
+                this.transitionTo(ConnectionState.FAILED, 'Connection timeout');
+                this.scheduleReconnect();
+            }
+        }, this.config.connectionTimeout);
+    }
+    /**
+     * Clear connection timeout
+     */
+    clearConnectionTimeout() {
+        if (this.connectionTimeout) {
+            clearTimeout(this.connectionTimeout);
+            this.connectionTimeout = null;
+        }
+    }
+    /**
+     * Start ICE gathering timeout
+     */
+    startIceGatheringTimeout() {
+        this.clearIceGatheringTimeout();
+        this.iceGatheringTimeout = setTimeout(() => {
+            if (this.pc && this.pc.iceGatheringState !== 'complete') {
+                this.debug('ICE gathering timeout');
+                this.emit('ice:gathering:timeout');
+            }
+        }, this.config.iceGatheringTimeout);
+    }
+    /**
+     * Clear ICE gathering timeout
+     */
+    clearIceGatheringTimeout() {
+        if (this.iceGatheringTimeout) {
+            clearTimeout(this.iceGatheringTimeout);
+            this.iceGatheringTimeout = null;
+        }
+    }
+    /**
+     * Schedule reconnection attempt
+     */
+    scheduleReconnect() {
+        if (!this.config.reconnectEnabled || !this.backoff)
+            return;
+        // Check if we've exceeded max attempts
+        if (this.config.maxReconnectAttempts > 0 && this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+            this.debug('Max reconnection attempts reached');
+            this.emit('reconnect:exhausted', this.reconnectAttempts);
+            return;
+        }
+        const delay = this.backoff.next();
+        this.reconnectAttempts++;
+        this.debug(`Scheduling reconnection attempt ${this.reconnectAttempts} in ${delay}ms`);
+        this.emit('reconnect:scheduled', {
+            attempt: this.reconnectAttempts,
+            delay,
+            maxAttempts: this.config.maxReconnectAttempts,
+        });
+        this.transitionTo(ConnectionState.RECONNECTING, `Attempt ${this.reconnectAttempts}`);
+        this.reconnectTimeout = setTimeout(() => {
+            this.emit('reconnect:attempting', this.reconnectAttempts);
+            this.attemptReconnect();
+        }, delay);
+    }
+    /**
+     * Cancel scheduled reconnection
+     */
+    cancelReconnect() {
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+    }
+    /**
+     * Send a message directly (bypasses buffer)
+     */
+    sendDirect(data) {
+        if (!this.dc || this.dc.readyState !== 'open') {
+            throw new Error('Data channel is not open');
+        }
+        // Handle different data types explicitly
+        this.dc.send(data);
+    }
+    /**
+     * Send a message with automatic buffering
+     */
+    send(data) {
+        if (this.state === ConnectionState.CONNECTED && this.dc?.readyState === 'open') {
+            // Send directly
+            try {
+                this.sendDirect(data);
+                this.emit('message:sent', data, false);
+            }
+            catch (error) {
+                this.debug('Failed to send message:', error);
+                this.bufferMessage(data);
+            }
+        }
+        else {
+            // Buffer for later
+            this.bufferMessage(data);
+        }
+    }
+    /**
+     * Buffer a message for later delivery
+     */
+    bufferMessage(data) {
+        if (!this.messageBuffer) {
+            this.debug('Message buffering disabled, message dropped');
+            return;
+        }
+        if (this.messageBuffer.isFull()) {
+            const oldest = this.messageBuffer.getAll()[0];
+            this.emit('message:buffer:overflow', oldest);
+        }
+        const message = this.messageBuffer.add(data);
+        this.emit('message:buffered', data);
+        this.emit('message:sent', data, true);
+        this.debug(`Message buffered (${this.messageBuffer.size()}/${this.config.maxBufferSize})`);
+    }
+    /**
+     * Get current connection state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get the data channel
+     */
+    getDataChannel() {
+        return this.dc;
+    }
+    /**
+     * Get the peer connection
+     */
+    getPeerConnection() {
+        return this.pc;
+    }
+    /**
+     * Close the connection
+     */
+    close() {
+        this.debug('Closing connection');
+        this.transitionTo(ConnectionState.CLOSED, 'User requested close');
+        this.cleanup();
+    }
+    /**
+     * Complete cleanup of all resources
+     */
+    cleanup() {
+        this.debug('Cleaning up connection');
+        this.emit('cleanup:started');
+        // Clear all timeouts
+        this.clearConnectionTimeout();
+        this.clearIceGatheringTimeout();
+        this.cancelReconnect();
+        // Stop ICE polling
+        this.stopIcePolling();
+        // Close data channel
+        if (this.dc) {
+            this.dc.onopen = null;
+            this.dc.onclose = null;
+            this.dc.onerror = null;
+            this.dc.onmessage = null;
+            if (this.dc.readyState !== 'closed') {
+                this.dc.close();
+            }
+            this.dc = null;
+        }
+        // Close peer connection
+        if (this.pc) {
+            this.pc.onicecandidate = null;
+            this.pc.oniceconnectionstatechange = null;
+            this.pc.onconnectionstatechange = null;
+            this.pc.onicegatheringstatechange = null;
+            if (this.pc.connectionState !== 'closed') {
+                this.pc.close();
+            }
+            this.pc = null;
+        }
+        // Clear message buffer if not preserving
+        if (this.messageBuffer && !this.config.preserveBufferOnClose) {
+            this.messageBuffer.clear();
+        }
+        this.emit('cleanup:complete');
+    }
+    /**
+     * Debug logging helper
+     */
+    debug(...args) {
+        if (this.config.debug) {
+            console.log('[RondevuConnection]', ...args);
+        }
+    }
+}

package/dist/exponential-backoff.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Exponential backoff utility for connection reconnection
+ */
+export interface BackoffConfig {
+    base: number;
+    max: number;
+    jitter: number;
+}
+export declare class ExponentialBackoff {
+    private config;
+    private attempt;
+    constructor(config: BackoffConfig);
+    /**
+     * Calculate the next delay based on the current attempt number
+     * Formula: min(base * 2^attempt, max) with jitter
+     */
+    next(): number;
+    /**
+     * Get the current attempt number
+     */
+    getAttempt(): number;
+    /**
+     * Reset the backoff state
+     */
+    reset(): void;
+    /**
+     * Peek at what the next delay would be without incrementing
+     */
+    peek(): number;
+}

package/dist/exponential-backoff.js

@@ -0,0 +1,46 @@
+/**
+ * Exponential backoff utility for connection reconnection
+ */
+export class ExponentialBackoff {
+    constructor(config) {
+        this.config = config;
+        this.attempt = 0;
+        if (config.jitter < 0 || config.jitter > 1) {
+            throw new Error('Jitter must be between 0 and 1');
+        }
+    }
+    /**
+     * Calculate the next delay based on the current attempt number
+     * Formula: min(base * 2^attempt, max) with jitter
+     */
+    next() {
+        const exponentialDelay = this.config.base * Math.pow(2, this.attempt);
+        const cappedDelay = Math.min(exponentialDelay, this.config.max);
+        // Add jitter: delay ± (jitter * delay)
+        const jitterAmount = cappedDelay * this.config.jitter;
+        const jitter = (Math.random() * 2 - 1) * jitterAmount; // Random value between -jitterAmount and +jitterAmount
+        const finalDelay = Math.max(0, cappedDelay + jitter);
+        this.attempt++;
+        return Math.round(finalDelay);
+    }
+    /**
+     * Get the current attempt number
+     */
+    getAttempt() {
+        return this.attempt;
+    }
+    /**
+     * Reset the backoff state
+     */
+    reset() {
+        this.attempt = 0;
+    }
+    /**
+     * Peek at what the next delay would be without incrementing
+     */
+    peek() {
+        const exponentialDelay = this.config.base * Math.pow(2, this.attempt);
+        const cappedDelay = Math.min(exponentialDelay, this.config.max);
+        return cappedDelay;
+    }
+}

package/dist/index.d.ts

@@ -5,9 +5,18 @@
 export { Rondevu, RondevuError, NetworkError, ValidationError, ConnectionError } from './rondevu.js';
 export { RondevuAPI } from './api.js';
 export { RpcBatcher } from './rpc-batcher.js';
+export { RondevuConnection } from './connection.js';
+export { OffererConnection } from './offerer-connection.js';
+export { AnswererConnection } from './answerer-connection.js';
+export { ExponentialBackoff } from './exponential-backoff.js';
+export { MessageBuffer } from './message-buffer.js';
 export { WebCryptoAdapter } from './web-crypto-adapter.js';
 export { NodeCryptoAdapter } from './node-crypto-adapter.js';
 export type { Signaler, Binnable, } from './types.js';
 export type { Keypair, OfferRequest, ServiceRequest, Service, ServiceOffer, IceCandidate, } from './api.js';
 export type { RondevuOptions, PublishServiceOptions, ConnectToServiceOptions, ConnectionContext, OfferContext, OfferFactory, ActiveOffer, FindServiceOptions, ServiceResult, PaginatedServiceResult } from './rondevu.js';
 export type { CryptoAdapter } from './crypto-adapter.js';
+export type { ConnectionConfig, } from './connection-config.js';
+export type { ConnectionState, BufferedMessage, ReconnectInfo, StateChangeInfo, ConnectionEventMap, ConnectionEventName, ConnectionEventArgs, } from './connection-events.js';
+export type { OffererOptions, } from './offerer-connection.js';
+export type { AnswererOptions, } from './answerer-connection.js';

package/dist/index.js

@@ -5,6 +5,13 @@
 export { Rondevu, RondevuError, NetworkError, ValidationError, ConnectionError } from './rondevu.js';
 export { RondevuAPI } from './api.js';
 export { RpcBatcher } from './rpc-batcher.js';
+// Export connection classes
+export { RondevuConnection } from './connection.js';
+export { OffererConnection } from './offerer-connection.js';
+export { AnswererConnection } from './answerer-connection.js';
+// Export utilities
+export { ExponentialBackoff } from './exponential-backoff.js';
+export { MessageBuffer } from './message-buffer.js';
 // Export crypto adapters
 export { WebCryptoAdapter } from './web-crypto-adapter.js';
 export { NodeCryptoAdapter } from './node-crypto-adapter.js';

package/dist/message-buffer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Message buffering system for storing messages during disconnections
+ */
+import { BufferedMessage } from './connection-events.js';
+export interface MessageBufferConfig {
+    maxSize: number;
+    maxAge: number;
+}
+export declare class MessageBuffer {
+    private config;
+    private buffer;
+    private messageIdCounter;
+    constructor(config: MessageBufferConfig);
+    /**
+     * Add a message to the buffer
+     * Returns the buffered message with metadata
+     */
+    add(data: string | ArrayBuffer | Blob): BufferedMessage;
+    /**
+     * Get all messages in the buffer
+     */
+    getAll(): BufferedMessage[];
+    /**
+     * Get messages that haven't exceeded max age
+     */
+    getValid(): BufferedMessage[];
+    /**
+     * Get and remove expired messages
+     */
+    getExpired(): BufferedMessage[];
+    /**
+     * Remove a specific message by ID
+     */
+    remove(messageId: string): BufferedMessage | null;
+    /**
+     * Clear all messages from the buffer
+     */
+    clear(): BufferedMessage[];
+    /**
+     * Increment attempt count for a message
+     */
+    incrementAttempt(messageId: string): boolean;
+    /**
+     * Get the current size of the buffer
+     */
+    size(): number;
+    /**
+     * Check if buffer is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if buffer is full
+     */
+    isFull(): boolean;
+}