@xtr-dev/rondevu-client 0.8.2 → 0.9.1

package/dist/durable/connection.js

@@ -0,0 +1,370 @@
+/**
+ * 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 { DurableChannel } from './channel.js';
+import { createReconnectionScheduler } from './reconnection.js';
+import { DurableConnectionState } from './types.js';
+/**
+ * Default configuration for durable connections
+ */
+const DEFAULT_CONFIG = {
+    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 {
+    constructor(offersApi, connectionInfo, config) {
+        super();
+        this.offersApi = offersApi;
+        this.channels = new Map();
+        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() {
+        return this._state;
+    }
+    /**
+     * Check if connection is currently connected
+     */
+    isConnected() {
+        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, options) {
+        // 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) {
+        return this.channels.get(label);
+    }
+    /**
+     * Establish the initial connection
+     *
+     * @returns Promise that resolves when connected
+     */
+    async connect() {
+        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() {
+        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
+     */
+    async establishConnection() {
+        // 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
+     */
+    async connectByUuid(peer, uuid) {
+        // 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
+     */
+    async connectByService(peer, username, serviceFqn) {
+        // 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
+     */
+    async waitForConnection(peer) {
+        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) => {
+                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
+     */
+    setupPeerHandlers(peer) {
+        this.peerConnectedHandler = () => {
+            // Connection established - will be handled by waitForConnection
+        };
+        this.peerDisconnectedHandler = () => {
+            if (this._state !== DurableConnectionState.CLOSED) {
+                this.handleDisconnection();
+            }
+        };
+        this.peerFailedHandler = (error) => {
+            if (this._state !== DurableConnectionState.CLOSED) {
+                console.error('Peer connection failed:', error);
+                this.handleDisconnection();
+            }
+        };
+        this.peerDataChannelHandler = (channel) => {
+            // Find or create durable channel
+            let durableChannel = this.channels.get(channel.label);
+            if (!durableChannel) {
+                // Auto-create channel for incoming data channels
+                durableChannel = new DurableChannel(channel.label, {
+                    maxQueueSize: this.config.maxQueueSize,
+                    maxMessageAge: this.config.maxMessageAge
+                });
+                this.channels.set(channel.label, durableChannel);
+            }
+            // Attach the received channel
+            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
+     */
+    transitionToConnected() {
+        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
+     */
+    createAndAttachChannel(durableChannel, options) {
+        if (!this.currentPeer) {
+            return;
+        }
+        // Check if peer already has this channel (received via datachannel event)
+        // If not, create it
+        const senders = this.currentPeer.pc.getSenders?.() || [];
+        const existingChannel = Array.from(senders)
+            .map((sender) => sender.channel)
+            .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
+     */
+    async handleDisconnection() {
+        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();
+    }
+}

package/dist/durable/reconnection.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 declare function calculateBackoff(attempt: number, base: number, max: number, jitter: number): number;
+/**
+ * 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 declare function createReconnectionScheduler(config: ReconnectionSchedulerConfig): ReconnectionScheduler;

package/dist/durable/reconnection.js

@@ -0,0 +1,127 @@
+/**
+ * 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, base, max, jitter) {
+    // 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);
+}
+/**
+ * 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) {
+    let attempt = 0;
+    let active = false;
+    let timer;
+    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
+    };
+}

package/dist/durable/service.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 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>;
+/**
+ * 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 declare class DurableService extends EventEmitter<DurableServiceEvents> {
+    private offersApi;
+    private baseUrl;
+    private credentials;
+    private handler;
+    readonly config: Required<DurableServiceConfig>;
+    private serviceId?;
+    private uuid?;
+    private expiresAt?;
+    private ttlRefreshTimer?;
+    private servicePool?;
+    private activeChannels;
+    constructor(offersApi: RondevuOffers, baseUrl: string, credentials: {
+        peerId: string;
+        secret: string;
+    }, handler: ConnectionHandler, config: DurableServiceConfig);
+    /**
+     * Start the service
+     *
+     * Publishes the service and begins accepting connections.
+     *
+     * @returns Service information
+     */
+    start(): Promise<ServiceInfo>;
+    /**
+     * Stop the service
+     *
+     * Unpublishes the service and closes all active connections.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get list of active connection IDs
+     */
+    getActiveConnections(): string[];
+    /**
+     * Get service information
+     */
+    getServiceInfo(): ServiceInfo | null;
+    /**
+     * Schedule TTL refresh
+     */
+    private scheduleRefresh;
+    /**
+     * Refresh service TTL
+     */
+    private refreshServiceTTL;
+    /**
+     * Handle new incoming connection
+     */
+    private handleNewConnection;
+}