@xtr-dev/rondevu-client 0.9.2 → 0.10.0

package/dist/connection-manager.js

@@ -0,0 +1,324 @@
+/**
+ * ConnectionManager - Manages WebRTC peer connections with automatic reconnection
+ *
+ * Provides high-level API for:
+ * - Hosting services (creating offers and publishing them)
+ * - Connecting to services (finding and answering offers)
+ * - Automatic reconnection when connections fail
+ * - Connection lifecycle management
+ */
+import { WebRTCContext } from './webrtc-context.js';
+import { WebRTCRondevuConnection } from './connection.js';
+import { RondevuAPI } from './api.js';
+import { RondevuSignaler } from './signaler.js';
+import { createBin } from './bin.js';
+/**
+ * ConnectionManager - High-level connection management
+ *
+ * @example
+ * // Host a service
+ * const manager = new ConnectionManager({
+ *   apiUrl: 'https://api.ronde.vu',
+ *   credentials: await api.register()
+ * })
+ *
+ * await manager.hostService({
+ *   service: 'chat.app@1.0.0',
+ *   onConnection: (conn) => {
+ *     conn.events.on('message', msg => console.log('Received:', msg))
+ *   }
+ * })
+ *
+ * @example
+ * // Connect to a service
+ * const connection = await manager.connectToService({
+ *   username: 'alice',
+ *   service: 'chat.app@1.0.0'
+ * })
+ *
+ * await connection.sendMessage('Hello!')
+ */
+export class ConnectionManager {
+    constructor(options) {
+        this.connections = new Map();
+        this.bin = createBin();
+        this.api = new RondevuAPI(options.apiUrl, options.credentials);
+        this.username = options.username;
+        this.autoReconnect = options.autoReconnect ?? true;
+        this.reconnectDelay = options.reconnectDelay ?? 5000;
+        this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+    }
+    /**
+     * Host a service - Creates an offer and publishes it to the signaling server
+     *
+     * The service will automatically accept incoming connections and manage them.
+     * Each new connection triggers the onConnection callback.
+     *
+     * @param options - Service hosting options
+     * @returns Promise that resolves when the service is published
+     */
+    async hostService(options) {
+        const { service, ttl = 300000, onConnection } = options;
+        console.log(`[ConnectionManager] Hosting service: ${service}`);
+        // Create WebRTC context with a temporary signaler
+        // We'll replace it once we have the offer ID
+        const tempSignaler = this.createTempSignaler();
+        const context = new WebRTCContext(tempSignaler);
+        // Create connection (offerer role)
+        const connection = new WebRTCRondevuConnection({
+            id: `host-${service}-${Date.now()}`,
+            host: this.username,
+            service,
+            offer: null,
+            context,
+        });
+        // Wait for offer to be created
+        await connection.ready;
+        // Get the offer SDP
+        if (!connection.connection) {
+            throw new Error('RTCPeerConnection not initialized');
+        }
+        const offerSdp = connection.connection.localDescription?.sdp;
+        if (!offerSdp) {
+            throw new Error('Failed to create offer');
+        }
+        console.log(`[ConnectionManager] Offer created for ${service}`);
+        // Create offer on server
+        const offers = await this.api.createOffers([
+            {
+                sdp: offerSdp,
+                ttl,
+            },
+        ]);
+        const offerId = offers[0].id;
+        console.log(`[ConnectionManager] Offer published: ${offerId}`);
+        // Now create the real signaler with the offer ID
+        const signaler = new RondevuSignaler(this.api, offerId);
+        context.signaler = signaler;
+        // Set up connection tracking
+        const bin = createBin();
+        // Track connection state
+        bin(connection.events.on('state-change', state => {
+            console.log(`[ConnectionManager] ${service} state: ${state}`);
+            if (state === 'connected' && onConnection) {
+                onConnection(connection);
+            }
+            // Handle disconnection
+            if (state === 'disconnected' && this.autoReconnect) {
+                this.scheduleReconnect(connection.id, service, offerId);
+            }
+        }));
+        // Cleanup function
+        const cleanup = () => bin.clean();
+        // Store managed connection
+        this.connections.set(connection.id, {
+            connection,
+            offerId,
+            service,
+            cleanup,
+            reconnectAttempts: 0,
+            isReconnecting: false,
+        });
+        // Clean up on expiry
+        setTimeout(() => {
+            console.log(`[ConnectionManager] Service ${service} expired`);
+            this.removeConnection(connection.id);
+        }, ttl - 1000);
+        console.log(`[ConnectionManager] Service ${service} is now hosted`);
+    }
+    /**
+     * Connect to a hosted service
+     *
+     * Searches for the service, retrieves the offer, and creates an answering connection.
+     *
+     * @param options - Connection options
+     * @returns The established connection
+     */
+    async connectToService(options) {
+        const { username, service, onConnection } = options;
+        console.log(`[ConnectionManager] Connecting to ${username}/${service}`);
+        // Search for the service
+        const services = await this.api.searchServices(username, service);
+        if (services.length === 0) {
+            throw new Error(`Service not found: ${username}/${service}`);
+        }
+        // Get the first available service
+        const serviceInfo = services[0];
+        console.log(`[ConnectionManager] Found service: ${serviceInfo.uuid}`);
+        // Get the service details (includes offer)
+        const serviceDetails = await this.api.getService(serviceInfo.uuid);
+        const offerId = serviceDetails.offerId;
+        // Get the offer
+        const offer = await this.api.getOffer(offerId);
+        console.log(`[ConnectionManager] Retrieved offer: ${offerId}`);
+        // Create signaler
+        const signaler = new RondevuSignaler(this.api, offerId);
+        const context = new WebRTCContext(signaler);
+        // Create connection (answerer role)
+        const connection = new WebRTCRondevuConnection({
+            id: `client-${service}-${Date.now()}`,
+            host: username,
+            service,
+            offer: {
+                type: 'offer',
+                sdp: offer.sdp,
+            },
+            context,
+        });
+        // Wait for answer to be created
+        await connection.ready;
+        // Get the answer SDP
+        if (!connection.connection) {
+            throw new Error('RTCPeerConnection not initialized');
+        }
+        const answerSdp = connection.connection.localDescription?.sdp;
+        if (!answerSdp) {
+            throw new Error('Failed to create answer');
+        }
+        console.log(`[ConnectionManager] Answer created`);
+        // Send answer to server
+        await this.api.answerOffer(offerId, answerSdp);
+        console.log(`[ConnectionManager] Answer sent to server`);
+        // Set up connection tracking
+        const bin = createBin();
+        // Track connection state
+        bin(connection.events.on('state-change', state => {
+            console.log(`[ConnectionManager] Client ${service} state: ${state}`);
+            if (state === 'connected' && onConnection) {
+                onConnection(connection);
+            }
+            // Handle disconnection
+            if (state === 'disconnected' && this.autoReconnect) {
+                this.scheduleReconnect(connection.id, service, offerId);
+            }
+        }));
+        // Cleanup function
+        const cleanup = () => bin.clean();
+        // Store managed connection
+        this.connections.set(connection.id, {
+            connection,
+            offerId,
+            service,
+            cleanup,
+            reconnectAttempts: 0,
+            isReconnecting: false,
+        });
+        return connection;
+    }
+    /**
+     * Get a connection by ID
+     */
+    getConnection(id) {
+        return this.connections.get(id)?.connection;
+    }
+    /**
+     * Get all managed connections
+     */
+    getAllConnections() {
+        return Array.from(this.connections.values()).map(mc => mc.connection);
+    }
+    /**
+     * Remove a connection
+     */
+    removeConnection(id) {
+        const managed = this.connections.get(id);
+        if (managed) {
+            managed.cleanup();
+            this.connections.delete(id);
+            console.log(`[ConnectionManager] Removed connection: ${id}`);
+        }
+    }
+    /**
+     * Schedule reconnection for a failed connection
+     */
+    scheduleReconnect(connectionId, service, offerId) {
+        const managed = this.connections.get(connectionId);
+        if (!managed)
+            return;
+        if (managed.isReconnecting) {
+            console.log(`[ConnectionManager] Already reconnecting: ${connectionId}`);
+            return;
+        }
+        if (managed.reconnectAttempts >= this.maxReconnectAttempts) {
+            console.log(`[ConnectionManager] Max reconnect attempts reached for ${connectionId}`);
+            this.removeConnection(connectionId);
+            return;
+        }
+        managed.isReconnecting = true;
+        managed.reconnectAttempts++;
+        console.log(`[ConnectionManager] Scheduling reconnect for ${service} (attempt ${managed.reconnectAttempts}/${this.maxReconnectAttempts})`);
+        setTimeout(() => {
+            this.attemptReconnect(connectionId, service, offerId);
+        }, this.reconnectDelay);
+    }
+    /**
+     * Attempt to reconnect a failed connection
+     */
+    async attemptReconnect(connectionId, service, offerId) {
+        const managed = this.connections.get(connectionId);
+        if (!managed)
+            return;
+        try {
+            console.log(`[ConnectionManager] Attempting reconnect for ${service}`);
+            // Get fresh offer from server
+            const offer = await this.api.getOffer(offerId);
+            // Create new signaler
+            const signaler = new RondevuSignaler(this.api, offerId);
+            const context = new WebRTCContext(signaler);
+            // Create new connection
+            const newConnection = new WebRTCRondevuConnection({
+                id: connectionId,
+                host: managed.connection.host,
+                service,
+                offer: {
+                    type: 'offer',
+                    sdp: offer.sdp,
+                },
+                context,
+            });
+            // Wait for answer
+            await newConnection.ready;
+            // Send answer
+            if (newConnection.connection) {
+                const answerSdp = newConnection.connection.localDescription?.sdp;
+                if (answerSdp) {
+                    await this.api.answerOffer(offerId, answerSdp);
+                }
+            }
+            // Replace old connection
+            managed.connection = newConnection;
+            managed.isReconnecting = false;
+            console.log(`[ConnectionManager] Reconnected ${service}`);
+        }
+        catch (error) {
+            console.error(`[ConnectionManager] Reconnect failed:`, error);
+            managed.isReconnecting = false;
+            // Schedule next attempt
+            this.scheduleReconnect(connectionId, service, offerId);
+        }
+    }
+    /**
+     * Create a temporary signaler (used during initial offer creation)
+     */
+    createTempSignaler() {
+        return {
+            addIceCandidate: () => { },
+            addListener: () => () => { },
+            setOffer: () => { },
+            setAnswer: () => { },
+        };
+    }
+    /**
+     * Clean up all connections and resources
+     */
+    destroy() {
+        console.log('[ConnectionManager] Destroying connection manager');
+        // Clean up all connections
+        for (const [id, managed] of this.connections.entries()) {
+            managed.cleanup();
+            this.connections.delete(id);
+        }
+        // Clean up global resources
+        this.bin.clean();
+    }
+}

package/dist/connection.d.ts

@@ -0,0 +1,112 @@
+import { ConnectionEvents, ConnectionInterface, Message, QueueMessageOptions } from './types.js';
+import { EventBus } from './event-bus.js';
+import { WebRTCContext } from './webrtc-context';
+export type WebRTCRondevuConnectionOptions = {
+    id: string;
+    service: string;
+    offer: RTCSessionDescriptionInit | null;
+    context: WebRTCContext;
+};
+/**
+ * WebRTCRondevuConnection - WebRTC peer connection wrapper with Rondevu signaling
+ *
+ * Manages a WebRTC peer connection lifecycle including:
+ * - Automatic offer/answer creation based on role
+ * - ICE candidate exchange via Rondevu signaling server
+ * - Connection state management with type-safe events
+ * - Data channel creation and message handling
+ *
+ * The connection automatically determines its role (offerer or answerer) based on whether
+ * an offer is provided in the constructor. The offerer creates the data channel, while
+ * the answerer receives it via the 'datachannel' event.
+ *
+ * @example
+ * ```typescript
+ * // Offerer side (creates offer)
+ * const connection = new WebRTCRondevuConnection(
+ *   'conn-123',
+ *   'peer-username',
+ *   'chat.service@1.0.0'
+ * );
+ *
+ * await connection.ready; // Wait for local offer
+ * const sdp = connection.connection.localDescription!.sdp!;
+ * // Send sdp to signaling server...
+ *
+ * // Answerer side (receives offer)
+ * const connection = new WebRTCRondevuConnection(
+ *   'conn-123',
+ *   'peer-username',
+ *   'chat.service@1.0.0',
+ *   { type: 'offer', sdp: remoteOfferSdp }
+ * );
+ *
+ * await connection.ready; // Wait for local answer
+ * const answerSdp = connection.connection.localDescription!.sdp!;
+ * // Send answer to signaling server...
+ *
+ * // Both sides: Set up signaler and listen for state changes
+ * connection.setSignaler(signaler);
+ * connection.events.on('state-change', (state) => {
+ *   console.log('Connection state:', state);
+ * });
+ * ```
+ */
+export declare class WebRTCRondevuConnection implements ConnectionInterface {
+    private readonly side;
+    readonly expiresAt: number;
+    readonly lastActive: number;
+    readonly events: EventBus<ConnectionEvents>;
+    readonly ready: Promise<void>;
+    private iceBin;
+    private ctx;
+    id: string;
+    service: string;
+    private _conn;
+    private _state;
+    constructor({ context: ctx, offer, id, service }: WebRTCRondevuConnectionOptions);
+    /**
+     * Getter method for retrieving the current connection.
+     *
+     * @return {RTCPeerConnection|null} The current connection instance.
+     */
+    get connection(): RTCPeerConnection | null;
+    /**
+     * Update connection state and emit state-change event
+     */
+    private setState;
+    /**
+     * Start ICE candidate exchange when gathering begins
+     */
+    private startIce;
+    /**
+     * Stop ICE candidate exchange when gathering completes
+     */
+    private stopIce;
+    /**
+     * Disconnects the current connection and cleans up resources.
+     * Closes the active connection if it exists, resets the connection instance to null,
+     * stops the ICE process, and updates the state to 'disconnected'.
+     *
+     * @return {void} No return value.
+     */
+    disconnect(): void;
+    /**
+     * Current connection state
+     */
+    get state(): "connected" | "disconnected" | "connecting";
+    /**
+     * Queue a message for sending when connection is established
+     *
+     * @param message - Message to queue (string or ArrayBuffer)
+     * @param options - Queue options (e.g., expiration time)
+     */
+    queueMessage(message: Message, options?: QueueMessageOptions): Promise<void>;
+    /**
+     * Send a message immediately
+     *
+     * @param message - Message to send (string or ArrayBuffer)
+     * @returns Promise resolving to true if sent successfully
+     */
+    sendMessage(message: Message): Promise<boolean>;
+}

package/dist/connection.js

@@ -0,0 +1,194 @@
+import { isConnectionState, } from './types.js';
+import { EventBus } from './event-bus.js';
+import { createBin } from './bin.js';
+/**
+ * WebRTCRondevuConnection - WebRTC peer connection wrapper with Rondevu signaling
+ *
+ * Manages a WebRTC peer connection lifecycle including:
+ * - Automatic offer/answer creation based on role
+ * - ICE candidate exchange via Rondevu signaling server
+ * - Connection state management with type-safe events
+ * - Data channel creation and message handling
+ *
+ * The connection automatically determines its role (offerer or answerer) based on whether
+ * an offer is provided in the constructor. The offerer creates the data channel, while
+ * the answerer receives it via the 'datachannel' event.
+ *
+ * @example
+ * ```typescript
+ * // Offerer side (creates offer)
+ * const connection = new WebRTCRondevuConnection(
+ *   'conn-123',
+ *   'peer-username',
+ *   'chat.service@1.0.0'
+ * );
+ *
+ * await connection.ready; // Wait for local offer
+ * const sdp = connection.connection.localDescription!.sdp!;
+ * // Send sdp to signaling server...
+ *
+ * // Answerer side (receives offer)
+ * const connection = new WebRTCRondevuConnection(
+ *   'conn-123',
+ *   'peer-username',
+ *   'chat.service@1.0.0',
+ *   { type: 'offer', sdp: remoteOfferSdp }
+ * );
+ *
+ * await connection.ready; // Wait for local answer
+ * const answerSdp = connection.connection.localDescription!.sdp!;
+ * // Send answer to signaling server...
+ *
+ * // Both sides: Set up signaler and listen for state changes
+ * connection.setSignaler(signaler);
+ * connection.events.on('state-change', (state) => {
+ *   console.log('Connection state:', state);
+ * });
+ * ```
+ */
+export class WebRTCRondevuConnection {
+    constructor({ context: ctx, offer, id, service }) {
+        this.expiresAt = 0;
+        this.lastActive = 0;
+        this.events = new EventBus();
+        this.iceBin = createBin();
+        this._conn = null;
+        this._state = 'disconnected';
+        this.ctx = ctx;
+        this.id = id;
+        this.service = service;
+        this._conn = ctx.createPeerConnection();
+        this.side = offer ? 'answer' : 'offer';
+        // setup data channel
+        if (offer) {
+            this._conn.addEventListener('datachannel', e => {
+                const channel = e.channel;
+                channel.addEventListener('message', e => {
+                    console.log('Message from peer:', e);
+                });
+                channel.addEventListener('open', () => {
+                    channel.send('I am ' + this.side);
+                });
+            });
+        }
+        else {
+            const channel = this._conn.createDataChannel('vu.ronde.protocol');
+            channel.addEventListener('message', e => {
+                console.log('Message from peer:', e);
+            });
+            channel.addEventListener('open', () => {
+                channel.send('I am ' + this.side);
+            });
+        }
+        // setup description exchange
+        this.ready = offer
+            ? this._conn
+                .setRemoteDescription(offer)
+                .then(() => this._conn?.createAnswer())
+                .then(async (answer) => {
+                if (!answer || !this._conn)
+                    throw new Error('Connection disappeared');
+                await this._conn.setLocalDescription(answer);
+                return await ctx.signaler.setAnswer(answer);
+            })
+            : this._conn.createOffer().then(async (offer) => {
+                if (!this._conn)
+                    throw new Error('Connection disappeared');
+                await this._conn.setLocalDescription(offer);
+                return await ctx.signaler.setOffer(offer);
+            });
+        // propagate connection state changes
+        this._conn.addEventListener('connectionstatechange', () => {
+            console.log(this.side, 'connection state changed: ', this._conn.connectionState);
+            const state = isConnectionState(this._conn.connectionState)
+                ? this._conn.connectionState
+                : 'disconnected';
+            this.setState(state);
+        });
+        this._conn.addEventListener('iceconnectionstatechange', () => {
+            console.log(this.side, 'ice connection state changed: ', this._conn.iceConnectionState);
+        });
+        // start ICE candidate exchange when gathering begins
+        this._conn.addEventListener('icegatheringstatechange', () => {
+            if (this._conn.iceGatheringState === 'gathering') {
+                this.startIce();
+            }
+            else if (this._conn.iceGatheringState === 'complete') {
+                this.stopIce();
+            }
+        });
+    }
+    /**
+     * Getter method for retrieving the current connection.
+     *
+     * @return {RTCPeerConnection|null} The current connection instance.
+     */
+    get connection() {
+        return this._conn;
+    }
+    /**
+     * Update connection state and emit state-change event
+     */
+    setState(state) {
+        this._state = state;
+        this.events.emit('state-change', state);
+    }
+    /**
+     * Start ICE candidate exchange when gathering begins
+     */
+    startIce() {
+        const listener = ({ candidate }) => {
+            if (candidate)
+                this.ctx.signaler.addIceCandidate(candidate);
+        };
+        if (!this._conn)
+            throw new Error('Connection disappeared');
+        this._conn.addEventListener('icecandidate', listener);
+        this.iceBin(this.ctx.signaler.addListener((candidate) => this._conn?.addIceCandidate(candidate)), () => this._conn?.removeEventListener('icecandidate', listener));
+    }
+    /**
+     * Stop ICE candidate exchange when gathering completes
+     */
+    stopIce() {
+        this.iceBin.clean();
+    }
+    /**
+     * Disconnects the current connection and cleans up resources.
+     * Closes the active connection if it exists, resets the connection instance to null,
+     * stops the ICE process, and updates the state to 'disconnected'.
+     *
+     * @return {void} No return value.
+     */
+    disconnect() {
+        this._conn?.close();
+        this._conn = null;
+        this.stopIce();
+        this.setState('disconnected');
+    }
+    /**
+     * Current connection state
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Queue a message for sending when connection is established
+     *
+     * @param message - Message to queue (string or ArrayBuffer)
+     * @param options - Queue options (e.g., expiration time)
+     */
+    queueMessage(message, options = {}) {
+        // TODO: Implement message queuing
+        return Promise.resolve(undefined);
+    }
+    /**
+     * Send a message immediately
+     *
+     * @param message - Message to send (string or ArrayBuffer)
+     * @returns Promise resolving to true if sent successfully
+     */
+    sendMessage(message) {
+        // TODO: Implement message sending via data channel
+        return Promise.resolve(false);
+    }
+}

package/dist/event-bus.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Type-safe EventBus with event name to payload type mapping
+ */
+type EventHandler<T = any> = (data: T) => void;
+/**
+ * EventBus - Type-safe event emitter with inferred event data types
+ *
+ * @example
+ * interface MyEvents {
+ *   'user:connected': { userId: string; timestamp: number };
+ *   'user:disconnected': { userId: string };
+ *   'message:received': string;
+ * }
+ *
+ * const bus = new EventBus<MyEvents>();
+ *
+ * // TypeScript knows data is { userId: string; timestamp: number }
+ * bus.on('user:connected', (data) => {
+ *   console.log(data.userId, data.timestamp);
+ * });
+ *
+ * // TypeScript knows data is string
+ * bus.on('message:received', (data) => {
+ *   console.log(data.toUpperCase());
+ * });
+ */
+export declare class EventBus<TEvents extends Record<string, any>> {
+    private handlers;
+    constructor();
+    /**
+     * Subscribe to an event
+     * Returns a cleanup function to unsubscribe
+     */
+    on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void;
+    /**
+     * Subscribe to an event once (auto-unsubscribe after first call)
+     */
+    once<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): void;
+    /**
+     * Emit an event with data
+     */
+    emit<K extends keyof TEvents>(event: K, data: TEvents[K]): void;
+    /**
+     * Remove all handlers for a specific event, or all handlers if no event specified
+     */
+    clear<K extends keyof TEvents>(event?: K): void;
+}
+export {};