@xtr-dev/rondevu-client 0.8.3 → 0.9.2

package/dist/durable/channel.d.ts

@@ -0,0 +1,115 @@
+/**
+ * DurableChannel - Message queueing wrapper for RTCDataChannel
+ *
+ * Provides automatic message queuing during disconnections and transparent
+ * flushing when the connection is re-established.
+ */
+import { EventEmitter } from '../event-emitter.js';
+import { DurableChannelState } from './types.js';
+import type { DurableChannelConfig, DurableChannelEvents } from './types.js';
+/**
+ * Durable channel that survives WebRTC peer connection drops
+ *
+ * The DurableChannel wraps an RTCDataChannel and provides:
+ * - Automatic message queuing during disconnections
+ * - Queue flushing on reconnection
+ * - Configurable queue size and message age limits
+ * - RTCDataChannel-compatible API
+ *
+ * @example
+ * ```typescript
+ * const channel = new DurableChannel('chat', connection, {
+ *   maxQueueSize: 500,
+ *   maxMessageAge: 30000
+ * });
+ *
+ * channel.on('message', (data) => {
+ *   console.log('Received:', data);
+ * });
+ *
+ * channel.on('open', () => {
+ *   channel.send('Hello!');
+ * });
+ *
+ * // Messages sent during disconnection are automatically queued
+ * channel.send('This will be queued if disconnected');
+ * ```
+ */
+export declare class DurableChannel extends EventEmitter<DurableChannelEvents> {
+    readonly label: string;
+    readonly config: DurableChannelConfig;
+    private _state;
+    private underlyingChannel?;
+    private messageQueue;
+    private queueProcessing;
+    private _bufferedAmountLowThreshold;
+    private openHandler?;
+    private messageHandler?;
+    private errorHandler?;
+    private closeHandler?;
+    private bufferedAmountLowHandler?;
+    constructor(label: string, config?: DurableChannelConfig);
+    /**
+     * Current channel state
+     */
+    get readyState(): DurableChannelState;
+    /**
+     * Buffered amount from underlying channel (0 if no channel)
+     */
+    get bufferedAmount(): number;
+    /**
+     * Buffered amount low threshold
+     */
+    get bufferedAmountLowThreshold(): number;
+    set bufferedAmountLowThreshold(value: number);
+    /**
+     * Send data through the channel
+     *
+     * If the channel is open, sends immediately. Otherwise, queues the message
+     * for delivery when the channel reconnects.
+     *
+     * @param data - Data to send
+     */
+    send(data: string | Blob | ArrayBuffer | ArrayBufferView): void;
+    /**
+     * Close the channel
+     */
+    close(): void;
+    /**
+     * Attach to an underlying RTCDataChannel
+     *
+     * This is called when a WebRTC connection is established (or re-established).
+     * The channel will flush any queued messages and forward events.
+     *
+     * @param channel - RTCDataChannel to attach to
+     * @internal
+     */
+    attachToChannel(channel: RTCDataChannel): void;
+    /**
+     * Detach from the underlying RTCDataChannel
+     *
+     * This is called when a WebRTC connection drops. The channel remains alive
+     * and continues queuing messages.
+     *
+     * @internal
+     */
+    detachFromChannel(): void;
+    /**
+     * Enqueue a message for later delivery
+     */
+    private enqueueMessage;
+    /**
+     * Flush all queued messages through the channel
+     */
+    private flushQueue;
+    /**
+     * Remove messages older than maxMessageAge from the queue
+     */
+    private pruneOldMessages;
+    /**
+     * Get the current queue size
+     *
+     * @internal
+     */
+    getQueueSize(): number;
+}

package/dist/durable/channel.js

@@ -0,0 +1,301 @@
+/**
+ * DurableChannel - Message queueing wrapper for RTCDataChannel
+ *
+ * Provides automatic message queuing during disconnections and transparent
+ * flushing when the connection is re-established.
+ */
+import { EventEmitter } from '../event-emitter.js';
+import { DurableChannelState } from './types.js';
+/**
+ * Default configuration for durable channels
+ */
+const DEFAULT_CONFIG = {
+    maxQueueSize: 1000,
+    maxMessageAge: 60000, // 1 minute
+    ordered: true,
+    maxRetransmits: undefined
+};
+/**
+ * Durable channel that survives WebRTC peer connection drops
+ *
+ * The DurableChannel wraps an RTCDataChannel and provides:
+ * - Automatic message queuing during disconnections
+ * - Queue flushing on reconnection
+ * - Configurable queue size and message age limits
+ * - RTCDataChannel-compatible API
+ *
+ * @example
+ * ```typescript
+ * const channel = new DurableChannel('chat', connection, {
+ *   maxQueueSize: 500,
+ *   maxMessageAge: 30000
+ * });
+ *
+ * channel.on('message', (data) => {
+ *   console.log('Received:', data);
+ * });
+ *
+ * channel.on('open', () => {
+ *   channel.send('Hello!');
+ * });
+ *
+ * // Messages sent during disconnection are automatically queued
+ * channel.send('This will be queued if disconnected');
+ * ```
+ */
+export class DurableChannel extends EventEmitter {
+    constructor(label, config) {
+        super();
+        this.messageQueue = [];
+        this.queueProcessing = false;
+        this._bufferedAmountLowThreshold = 0;
+        this.label = label;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this._state = DurableChannelState.CONNECTING;
+    }
+    /**
+     * Current channel state
+     */
+    get readyState() {
+        return this._state;
+    }
+    /**
+     * Buffered amount from underlying channel (0 if no channel)
+     */
+    get bufferedAmount() {
+        return this.underlyingChannel?.bufferedAmount ?? 0;
+    }
+    /**
+     * Buffered amount low threshold
+     */
+    get bufferedAmountLowThreshold() {
+        return this._bufferedAmountLowThreshold;
+    }
+    set bufferedAmountLowThreshold(value) {
+        this._bufferedAmountLowThreshold = value;
+        if (this.underlyingChannel) {
+            this.underlyingChannel.bufferedAmountLowThreshold = value;
+        }
+    }
+    /**
+     * Send data through the channel
+     *
+     * If the channel is open, sends immediately. Otherwise, queues the message
+     * for delivery when the channel reconnects.
+     *
+     * @param data - Data to send
+     */
+    send(data) {
+        if (this._state === DurableChannelState.OPEN && this.underlyingChannel) {
+            // Channel is open - send immediately
+            try {
+                this.underlyingChannel.send(data);
+            }
+            catch (error) {
+                // Send failed - queue the message
+                this.enqueueMessage(data);
+                this.emit('error', error);
+            }
+        }
+        else if (this._state !== DurableChannelState.CLOSED) {
+            // Channel is not open but not closed - queue the message
+            this.enqueueMessage(data);
+        }
+        else {
+            // Channel is closed - throw error
+            throw new Error('Cannot send on closed channel');
+        }
+    }
+    /**
+     * Close the channel
+     */
+    close() {
+        if (this._state === DurableChannelState.CLOSED ||
+            this._state === DurableChannelState.CLOSING) {
+            return;
+        }
+        this._state = DurableChannelState.CLOSING;
+        if (this.underlyingChannel) {
+            this.underlyingChannel.close();
+        }
+        this._state = DurableChannelState.CLOSED;
+        this.emit('close');
+    }
+    /**
+     * Attach to an underlying RTCDataChannel
+     *
+     * This is called when a WebRTC connection is established (or re-established).
+     * The channel will flush any queued messages and forward events.
+     *
+     * @param channel - RTCDataChannel to attach to
+     * @internal
+     */
+    attachToChannel(channel) {
+        // Detach from any existing channel first
+        this.detachFromChannel();
+        this.underlyingChannel = channel;
+        // Set buffered amount low threshold
+        channel.bufferedAmountLowThreshold = this._bufferedAmountLowThreshold;
+        // Setup event handlers
+        this.openHandler = () => {
+            this._state = DurableChannelState.OPEN;
+            this.emit('open');
+            // Flush queued messages
+            this.flushQueue().catch(error => {
+                this.emit('error', error);
+            });
+        };
+        this.messageHandler = (event) => {
+            this.emit('message', event.data);
+        };
+        this.errorHandler = (event) => {
+            this.emit('error', new Error(`Channel error: ${event.type}`));
+        };
+        this.closeHandler = () => {
+            if (this._state !== DurableChannelState.CLOSING &&
+                this._state !== DurableChannelState.CLOSED) {
+                // Unexpected close - transition to connecting (will reconnect)
+                this._state = DurableChannelState.CONNECTING;
+            }
+        };
+        this.bufferedAmountLowHandler = () => {
+            this.emit('bufferedAmountLow');
+        };
+        // Attach handlers
+        channel.addEventListener('open', this.openHandler);
+        channel.addEventListener('message', this.messageHandler);
+        channel.addEventListener('error', this.errorHandler);
+        channel.addEventListener('close', this.closeHandler);
+        channel.addEventListener('bufferedamountlow', this.bufferedAmountLowHandler);
+        // If channel is already open, trigger open event
+        if (channel.readyState === 'open') {
+            this.openHandler();
+        }
+        else if (channel.readyState === 'connecting') {
+            this._state = DurableChannelState.CONNECTING;
+        }
+    }
+    /**
+     * Detach from the underlying RTCDataChannel
+     *
+     * This is called when a WebRTC connection drops. The channel remains alive
+     * and continues queuing messages.
+     *
+     * @internal
+     */
+    detachFromChannel() {
+        if (!this.underlyingChannel) {
+            return;
+        }
+        // Remove event listeners
+        if (this.openHandler) {
+            this.underlyingChannel.removeEventListener('open', this.openHandler);
+        }
+        if (this.messageHandler) {
+            this.underlyingChannel.removeEventListener('message', this.messageHandler);
+        }
+        if (this.errorHandler) {
+            this.underlyingChannel.removeEventListener('error', this.errorHandler);
+        }
+        if (this.closeHandler) {
+            this.underlyingChannel.removeEventListener('close', this.closeHandler);
+        }
+        if (this.bufferedAmountLowHandler) {
+            this.underlyingChannel.removeEventListener('bufferedamountlow', this.bufferedAmountLowHandler);
+        }
+        this.underlyingChannel = undefined;
+        this._state = DurableChannelState.CONNECTING;
+    }
+    /**
+     * Enqueue a message for later delivery
+     */
+    enqueueMessage(data) {
+        // Prune old messages first
+        this.pruneOldMessages();
+        const message = {
+            data,
+            enqueuedAt: Date.now(),
+            id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
+        };
+        this.messageQueue.push(message);
+        // Handle overflow
+        const maxQueueSize = this.config.maxQueueSize ?? 1000;
+        if (this.messageQueue.length > maxQueueSize) {
+            const excess = this.messageQueue.length - maxQueueSize;
+            this.messageQueue.splice(0, excess);
+            this.emit('queueOverflow', excess);
+            console.warn(`DurableChannel[${this.label}]: Dropped ${excess} messages due to queue overflow`);
+        }
+    }
+    /**
+     * Flush all queued messages through the channel
+     */
+    async flushQueue() {
+        if (this.queueProcessing || !this.underlyingChannel ||
+            this.underlyingChannel.readyState !== 'open') {
+            return;
+        }
+        this.queueProcessing = true;
+        try {
+            // Prune old messages before flushing
+            this.pruneOldMessages();
+            // Send all queued messages
+            while (this.messageQueue.length > 0) {
+                const message = this.messageQueue.shift();
+                if (!message)
+                    break;
+                try {
+                    this.underlyingChannel.send(message.data);
+                }
+                catch (error) {
+                    // Send failed - re-queue message
+                    this.messageQueue.unshift(message);
+                    throw error;
+                }
+                // If buffer is getting full, wait for it to drain
+                if (this.underlyingChannel.bufferedAmount > 16 * 1024 * 1024) { // 16MB
+                    await new Promise((resolve) => {
+                        const checkBuffer = () => {
+                            if (!this.underlyingChannel ||
+                                this.underlyingChannel.bufferedAmount < 8 * 1024 * 1024) {
+                                resolve();
+                            }
+                            else {
+                                setTimeout(checkBuffer, 100);
+                            }
+                        };
+                        checkBuffer();
+                    });
+                }
+            }
+        }
+        finally {
+            this.queueProcessing = false;
+        }
+    }
+    /**
+     * Remove messages older than maxMessageAge from the queue
+     */
+    pruneOldMessages() {
+        const maxMessageAge = this.config.maxMessageAge ?? 60000;
+        if (maxMessageAge === Infinity || maxMessageAge <= 0) {
+            return;
+        }
+        const now = Date.now();
+        const cutoff = now - maxMessageAge;
+        const originalLength = this.messageQueue.length;
+        this.messageQueue = this.messageQueue.filter(msg => msg.enqueuedAt >= cutoff);
+        const pruned = originalLength - this.messageQueue.length;
+        if (pruned > 0) {
+            console.warn(`DurableChannel[${this.label}]: Pruned ${pruned} old messages (older than ${maxMessageAge}ms)`);
+        }
+    }
+    /**
+     * Get the current queue size
+     *
+     * @internal
+     */
+    getQueueSize() {
+        return this.messageQueue.length;
+    }
+}

package/dist/durable/connection.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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 type { RondevuOffers } from '../offers.js';
+import { DurableChannel } from './channel.js';
+import { DurableConnectionState } from './types.js';
+import type { DurableConnectionConfig, DurableConnectionEvents, ConnectionInfo } from './types.js';
+/**
+ * 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 declare class DurableConnection extends EventEmitter<DurableConnectionEvents> {
+    private offersApi;
+    readonly connectionId: string;
+    readonly config: Required<DurableConnectionConfig>;
+    readonly connectionInfo: ConnectionInfo;
+    private _state;
+    private currentPeer?;
+    private channels;
+    private reconnectionScheduler?;
+    private peerConnectedHandler?;
+    private peerDisconnectedHandler?;
+    private peerFailedHandler?;
+    private peerDataChannelHandler?;
+    constructor(offersApi: RondevuOffers, connectionInfo: ConnectionInfo, config?: DurableConnectionConfig);
+    /**
+     * Current connection state
+     */
+    getState(): DurableConnectionState;
+    /**
+     * Check if connection is currently connected
+     */
+    isConnected(): boolean;
+    /**
+     * 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: string, options?: RTCDataChannelInit): DurableChannel;
+    /**
+     * Get an existing channel by label
+     */
+    getChannel(label: string): DurableChannel | undefined;
+    /**
+     * Establish the initial connection
+     *
+     * @returns Promise that resolves when connected
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the connection gracefully
+     */
+    close(): Promise<void>;
+    /**
+     * Establish a WebRTC connection
+     */
+    private establishConnection;
+    /**
+     * Connect to a service by UUID
+     */
+    private connectByUuid;
+    /**
+     * Connect to a service by username and service FQN
+     */
+    private connectByService;
+    /**
+     * Wait for peer connection to establish
+     */
+    private waitForConnection;
+    /**
+     * Setup event handlers for peer
+     */
+    private setupPeerHandlers;
+    /**
+     * Transition to connected state
+     */
+    private transitionToConnected;
+    /**
+     * Create underlying RTCDataChannel and attach to durable channel
+     */
+    private createAndAttachChannel;
+    /**
+     * Handle connection disconnection
+     */
+    private handleDisconnection;
+}