@xtr-dev/rondevu-client 0.18.7 → 0.18.9

package/dist/answerer-connection.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Answerer-side WebRTC connection with answer creation and offer processing
+ */
+import { RondevuConnection } from './connection.js';
+import { RondevuAPI } from './api.js';
+import { ConnectionConfig } from './connection-config.js';
+export interface AnswererOptions {
+    api: RondevuAPI;
+    serviceFqn: string;
+    offerId: string;
+    offerSdp: string;
+    rtcConfig?: RTCConfiguration;
+    config?: Partial<ConnectionConfig>;
+}
+/**
+ * Answerer connection - processes offers and creates answers
+ */
+export declare class AnswererConnection extends RondevuConnection {
+    private api;
+    private serviceFqn;
+    private offerId;
+    private offerSdp;
+    constructor(options: AnswererOptions);
+    /**
+     * Initialize the connection by processing offer and creating answer
+     */
+    initialize(): Promise<void>;
+    /**
+     * Handle local ICE candidate generation
+     */
+    protected onLocalIceCandidate(candidate: RTCIceCandidate): void;
+    /**
+     * Poll for remote ICE candidates (from offerer)
+     */
+    protected pollIceCandidates(): void;
+    /**
+     * Attempt to reconnect
+     */
+    protected attemptReconnect(): void;
+    /**
+     * Get the offer ID we're answering
+     */
+    getOfferId(): string;
+}

package/dist/answerer-connection.js

@@ -0,0 +1,145 @@
+/**
+ * Answerer-side WebRTC connection with answer creation and offer processing
+ */
+import { RondevuConnection } from './connection.js';
+import { ConnectionState } from './connection-events.js';
+/**
+ * Answerer connection - processes offers and creates answers
+ */
+export class AnswererConnection extends RondevuConnection {
+    constructor(options) {
+        super(options.rtcConfig, options.config);
+        this.api = options.api;
+        this.serviceFqn = options.serviceFqn;
+        this.offerId = options.offerId;
+        this.offerSdp = options.offerSdp;
+    }
+    /**
+     * Initialize the connection by processing offer and creating answer
+     */
+    async initialize() {
+        this.debug('Initializing answerer connection');
+        // Create peer connection
+        this.createPeerConnection();
+        if (!this.pc)
+            throw new Error('Peer connection not created');
+        // Setup ondatachannel handler BEFORE setting remote description
+        // This is critical to avoid race conditions
+        this.pc.ondatachannel = (event) => {
+            this.debug('Received data channel');
+            this.dc = event.channel;
+            this.setupDataChannelHandlers(this.dc);
+        };
+        // Start connection timeout
+        this.startConnectionTimeout();
+        // Set remote description (offer)
+        await this.pc.setRemoteDescription({
+            type: 'offer',
+            sdp: this.offerSdp,
+        });
+        this.transitionTo(ConnectionState.SIGNALING, 'Offer received, creating answer');
+        // Create and set local description (answer)
+        const answer = await this.pc.createAnswer();
+        await this.pc.setLocalDescription(answer);
+        this.debug('Answer created, sending to server');
+        // Send answer to server
+        await this.api.answerOffer(this.serviceFqn, this.offerId, answer.sdp);
+        this.debug('Answer sent successfully');
+    }
+    /**
+     * Handle local ICE candidate generation
+     */
+    onLocalIceCandidate(candidate) {
+        this.debug('Generated local ICE candidate');
+        // For answerer, we add ICE candidates to the offer
+        // The server will make them available for the offerer to poll
+        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 (from offerer)
+     */
+    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) {
+                    // Only process ICE candidates from the offerer
+                    if (iceCandidate.role === 'offerer' && 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 answerer, we need to fetch a new offer and create a new answer
+        // Clean up old connection
+        if (this.pc) {
+            this.pc.close();
+            this.pc = null;
+        }
+        if (this.dc) {
+            this.dc.close();
+            this.dc = null;
+        }
+        // Fetch new offer from service
+        this.api
+            .getService(this.serviceFqn)
+            .then((service) => {
+            if (!service || !service.offers || service.offers.length === 0) {
+                throw new Error('No offers available for reconnection');
+            }
+            // Pick a random offer
+            const offer = service.offers[Math.floor(Math.random() * service.offers.length)];
+            this.offerId = offer.offerId;
+            this.offerSdp = offer.sdp;
+            // Reinitialize with new offer
+            return 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 we're answering
+     */
+    getOfferId() {
+        return this.offerId;
+    }
+}

package/dist/connection-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Connection configuration interfaces and defaults
+ */
+export interface ConnectionConfig {
+    connectionTimeout: number;
+    iceGatheringTimeout: number;
+    reconnectEnabled: boolean;
+    maxReconnectAttempts: number;
+    reconnectBackoffBase: number;
+    reconnectBackoffMax: number;
+    reconnectJitter: number;
+    bufferEnabled: boolean;
+    maxBufferSize: number;
+    maxBufferAge: number;
+    preserveBufferOnClose: boolean;
+    icePollingInterval: number;
+    icePollingTimeout: number;
+    debug: boolean;
+}
+export declare const DEFAULT_CONNECTION_CONFIG: ConnectionConfig;
+export declare function mergeConnectionConfig(userConfig?: Partial<ConnectionConfig>): ConnectionConfig;

package/dist/connection-config.js

@@ -0,0 +1,30 @@
+/**
+ * Connection configuration interfaces and defaults
+ */
+export const DEFAULT_CONNECTION_CONFIG = {
+    // Timeouts
+    connectionTimeout: 30000, // 30 seconds
+    iceGatheringTimeout: 10000, // 10 seconds
+    // Reconnection
+    reconnectEnabled: true,
+    maxReconnectAttempts: 5, // 5 attempts before giving up
+    reconnectBackoffBase: 1000, // Start with 1 second
+    reconnectBackoffMax: 30000, // Cap at 30 seconds
+    reconnectJitter: 0.1, // 10% jitter
+    // Message buffering
+    bufferEnabled: true,
+    maxBufferSize: 100, // 100 messages
+    maxBufferAge: 60000, // 1 minute
+    preserveBufferOnClose: false, // Clear buffer on close
+    // ICE polling
+    icePollingInterval: 500, // Poll every 500ms
+    icePollingTimeout: 30000, // Stop polling after 30s
+    // Debug
+    debug: false,
+};
+export function mergeConnectionConfig(userConfig) {
+    return {
+        ...DEFAULT_CONNECTION_CONFIG,
+        ...userConfig,
+    };
+}

package/dist/connection-events.d.ts

@@ -0,0 +1,78 @@
+/**
+ * TypeScript event type definitions for RondevuConnection
+ */
+export declare enum ConnectionState {
+    INITIALIZING = "initializing",// Creating peer connection
+    GATHERING = "gathering",// ICE gathering in progress
+    SIGNALING = "signaling",// Exchanging offer/answer
+    CHECKING = "checking",// ICE connectivity checks
+    CONNECTING = "connecting",// ICE connection attempts
+    CONNECTED = "connected",// Data channel open, working
+    DISCONNECTED = "disconnected",// Temporarily disconnected
+    RECONNECTING = "reconnecting",// Attempting reconnection
+    FAILED = "failed",// Connection failed
+    CLOSED = "closed"
+}
+export interface BufferedMessage {
+    id: string;
+    data: string | ArrayBuffer | Blob;
+    timestamp: number;
+    attempts: number;
+}
+export interface ReconnectInfo {
+    attempt: number;
+    delay: number;
+    maxAttempts: number;
+}
+export interface StateChangeInfo {
+    oldState: ConnectionState;
+    newState: ConnectionState;
+    reason?: string;
+}
+/**
+ * Event map for RondevuConnection
+ * Maps event names to their payload types
+ */
+export interface ConnectionEventMap {
+    'state:changed': [StateChangeInfo];
+    'connecting': [];
+    'connected': [];
+    'disconnected': [reason?: string];
+    'failed': [error: Error];
+    'closed': [reason?: string];
+    'reconnect:scheduled': [ReconnectInfo];
+    'reconnect:attempting': [attempt: number];
+    'reconnect:success': [];
+    'reconnect:failed': [error: Error];
+    'reconnect:exhausted': [attempts: number];
+    'message': [data: string | ArrayBuffer | Blob];
+    'message:sent': [data: string | ArrayBuffer | Blob, buffered: boolean];
+    'message:buffered': [data: string | ArrayBuffer | Blob];
+    'message:replayed': [message: BufferedMessage];
+    'message:buffer:overflow': [discardedMessage: BufferedMessage];
+    'message:buffer:expired': [message: BufferedMessage];
+    'ice:candidate:local': [candidate: RTCIceCandidate | null];
+    'ice:candidate:remote': [candidate: RTCIceCandidate | null];
+    'ice:connection:state': [state: RTCIceConnectionState];
+    'ice:gathering:state': [state: RTCIceGatheringState];
+    'ice:polling:started': [];
+    'ice:polling:stopped': [];
+    'answer:processed': [offerId: string, answererId: string];
+    'answer:duplicate': [offerId: string];
+    'datachannel:open': [];
+    'datachannel:close': [];
+    'datachannel:error': [error: Event];
+    'cleanup:started': [];
+    'cleanup:complete': [];
+    'connection:state': [state: RTCPeerConnectionState];
+    'connection:timeout': [];
+    'ice:gathering:timeout': [];
+}
+/**
+ * Helper type to extract event names from the event map
+ */
+export type ConnectionEventName = keyof ConnectionEventMap;
+/**
+ * Helper type to extract event arguments for a specific event
+ */
+export type ConnectionEventArgs<T extends ConnectionEventName> = ConnectionEventMap[T];

package/dist/connection-events.js

@@ -0,0 +1,16 @@
+/**
+ * TypeScript event type definitions for RondevuConnection
+ */
+export var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState["INITIALIZING"] = "initializing";
+    ConnectionState["GATHERING"] = "gathering";
+    ConnectionState["SIGNALING"] = "signaling";
+    ConnectionState["CHECKING"] = "checking";
+    ConnectionState["CONNECTING"] = "connecting";
+    ConnectionState["CONNECTED"] = "connected";
+    ConnectionState["DISCONNECTED"] = "disconnected";
+    ConnectionState["RECONNECTING"] = "reconnecting";
+    ConnectionState["FAILED"] = "failed";
+    ConnectionState["CLOSED"] = "closed";
+})(ConnectionState || (ConnectionState = {}));

package/dist/connection.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Base connection class with state machine, reconnection, and message buffering
+ */
+import { EventEmitter } from 'eventemitter3';
+import { ConnectionConfig } from './connection-config.js';
+import { ConnectionState, ConnectionEventMap } 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 declare abstract class RondevuConnection extends EventEmitter<ConnectionEventMap> {
+    protected rtcConfig?: RTCConfiguration | undefined;
+    protected pc: RTCPeerConnection | null;
+    protected dc: RTCDataChannel | null;
+    protected state: ConnectionState;
+    protected config: ConnectionConfig;
+    protected messageBuffer: MessageBuffer | null;
+    protected backoff: ExponentialBackoff | null;
+    protected reconnectTimeout: ReturnType<typeof setTimeout> | null;
+    protected reconnectAttempts: number;
+    protected connectionTimeout: ReturnType<typeof setTimeout> | null;
+    protected iceGatheringTimeout: ReturnType<typeof setTimeout> | null;
+    protected icePollingInterval: ReturnType<typeof setInterval> | null;
+    protected lastIcePollTime: number;
+    protected answerProcessed: boolean;
+    protected answerSdpFingerprint: string | null;
+    constructor(rtcConfig?: RTCConfiguration | undefined, userConfig?: Partial<ConnectionConfig>);
+    /**
+     * Transition to a new state and emit events
+     */
+    protected transitionTo(newState: ConnectionState, reason?: string): void;
+    /**
+     * Create and configure RTCPeerConnection
+     */
+    protected createPeerConnection(): RTCPeerConnection;
+    /**
+     * Setup data channel event handlers
+     */
+    protected setupDataChannelHandlers(dc: RTCDataChannel): void;
+    /**
+     * Handle local ICE candidate generation
+     */
+    protected handleIceCandidate(event: RTCPeerConnectionIceEvent): void;
+    /**
+     * Handle ICE connection state changes (primary state driver)
+     */
+    protected handleIceConnectionStateChange(): void;
+    /**
+     * Handle connection state changes (backup validation)
+     */
+    protected handleConnectionStateChange(): void;
+    /**
+     * Handle ICE gathering state changes
+     */
+    protected handleIceGatheringStateChange(): void;
+    /**
+     * Handle data channel open event
+     */
+    protected handleDataChannelOpen(): void;
+    /**
+     * Handle data channel close event
+     */
+    protected handleDataChannelClose(): void;
+    /**
+     * Handle data channel error event
+     */
+    protected handleDataChannelError(error: Event): void;
+    /**
+     * Handle incoming message
+     */
+    protected handleMessage(event: MessageEvent): void;
+    /**
+     * Called when connection is successfully established
+     */
+    protected onConnected(): void;
+    /**
+     * Start ICE candidate polling
+     */
+    protected startIcePolling(): void;
+    /**
+     * Stop ICE candidate polling
+     */
+    protected stopIcePolling(): void;
+    /**
+     * Start connection timeout
+     */
+    protected startConnectionTimeout(): void;
+    /**
+     * Clear connection timeout
+     */
+    protected clearConnectionTimeout(): void;
+    /**
+     * Start ICE gathering timeout
+     */
+    protected startIceGatheringTimeout(): void;
+    /**
+     * Clear ICE gathering timeout
+     */
+    protected clearIceGatheringTimeout(): void;
+    /**
+     * Schedule reconnection attempt
+     */
+    protected scheduleReconnect(): void;
+    /**
+     * Cancel scheduled reconnection
+     */
+    protected cancelReconnect(): void;
+    /**
+     * Send a message directly (bypasses buffer)
+     */
+    protected sendDirect(data: string | ArrayBuffer | Blob): void;
+    /**
+     * Send a message with automatic buffering
+     */
+    send(data: string | ArrayBuffer | Blob): void;
+    /**
+     * Buffer a message for later delivery
+     */
+    protected bufferMessage(data: string | ArrayBuffer | Blob): void;
+    /**
+     * Get current connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Get the data channel
+     */
+    getDataChannel(): RTCDataChannel | null;
+    /**
+     * Get the peer connection
+     */
+    getPeerConnection(): RTCPeerConnection | null;
+    /**
+     * Close the connection
+     */
+    close(): void;
+    /**
+     * Complete cleanup of all resources
+     */
+    protected cleanup(): void;
+    /**
+     * Debug logging helper
+     */
+    protected debug(...args: any[]): void;
+    protected abstract onLocalIceCandidate(candidate: RTCIceCandidate): void;
+    protected abstract pollIceCandidates(): void;
+    protected abstract attemptReconnect(): void;
+}