@xtr-dev/rondevu-client 0.18.10 → 0.21.1

package/dist/core/offer-pool.js

@@ -0,0 +1,281 @@
+import { EventEmitter } from 'eventemitter3';
+import { OffererConnection } from '../connections/offerer.js';
+import { AsyncLock } from '../utils/async-lock.js';
+/**
+ * OfferPool manages a pool of WebRTC offers for published tags.
+ * Maintains a target number of active offers and automatically replaces
+ * offers that fail or get answered.
+ */
+export class OfferPool extends EventEmitter {
+    constructor(options) {
+        super();
+        // State
+        this.activeConnections = new Map();
+        this.fillLock = new AsyncLock();
+        this.running = false;
+        this.api = options.api;
+        this.tags = options.tags;
+        this.ownerUsername = options.ownerUsername;
+        this.webrtcAdapter = options.webrtcAdapter;
+        this.maxOffers = options.maxOffers;
+        this.offerFactory = options.offerFactory;
+        this.ttl = options.ttl;
+        this.iceServers = options.iceServers;
+        this.iceTransportPolicy = options.iceTransportPolicy;
+        this.connectionConfig = options.connectionConfig;
+        this.debugEnabled = options.debugEnabled || false;
+    }
+    /**
+     * Start filling offers
+     * Polling is managed externally by Rondevu's PollingManager
+     */
+    async start() {
+        if (this.running) {
+            this.debug('Already running');
+            return;
+        }
+        this.debug('Starting offer pool');
+        this.running = true;
+        // Fill initial offers
+        await this.fillOffers();
+    }
+    /**
+     * Stop filling offers
+     * Closes all active connections
+     */
+    stop() {
+        this.debug('Stopping offer pool');
+        this.running = false;
+        // Close all active connections
+        for (const [offerId, connection] of this.activeConnections.entries()) {
+            if (connection.isRotating()) {
+                this.debug(`Connection ${offerId} is rotating, will close anyway`);
+            }
+            this.debug(`Closing connection ${offerId}`);
+            connection.close();
+        }
+        this.activeConnections.clear();
+    }
+    /**
+     * Get count of active offers
+     */
+    getOfferCount() {
+        return this.activeConnections.size;
+    }
+    /**
+     * Get all active connections
+     */
+    getActiveConnections() {
+        return this.activeConnections;
+    }
+    /**
+     * Check if a specific offer is connected
+     */
+    isConnected(offerId) {
+        const connection = this.activeConnections.get(offerId);
+        return connection ? connection.getState() === 'connected' : false;
+    }
+    /**
+     * Disconnect all active offers
+     */
+    disconnectAll() {
+        this.debug('Disconnecting all offers');
+        for (const [offerId, connection] of this.activeConnections.entries()) {
+            this.debug(`Closing connection ${offerId}`);
+            connection.close();
+        }
+        this.activeConnections.clear();
+    }
+    /**
+     * Fill offers to reach maxOffers count
+     * Uses AsyncLock to prevent concurrent fills
+     */
+    async fillOffers() {
+        if (!this.running)
+            return;
+        return this.fillLock.run(async () => {
+            const currentCount = this.activeConnections.size;
+            const needed = this.maxOffers - currentCount;
+            this.debug(`Filling offers: current=${currentCount}, needed=${needed}`);
+            for (let i = 0; i < needed; i++) {
+                try {
+                    await this.createOffer();
+                }
+                catch (err) {
+                    console.error('[OfferPool] Failed to create offer:', err);
+                }
+            }
+        });
+    }
+    /**
+     * Create and publish an offer to the server.
+     * Shared logic used by both createOffer() and createNewOfferForRotation().
+     *
+     * @returns The offer ID, RTCPeerConnection, and optional data channel
+     */
+    async createOfferAndPublish() {
+        const rtcConfig = {
+            iceServers: this.iceServers,
+            iceTransportPolicy: this.iceTransportPolicy,
+        };
+        // 1. Create RTCPeerConnection using adapter
+        const pc = this.webrtcAdapter.createPeerConnection(rtcConfig);
+        // Collect ICE candidates during offer creation
+        // We need to set this up BEFORE setLocalDescription is called
+        const collectedCandidates = [];
+        pc.onicecandidate = event => {
+            if (event.candidate) {
+                collectedCandidates.push({
+                    candidate: event.candidate.candidate,
+                    sdpMLineIndex: event.candidate.sdpMLineIndex,
+                    sdpMid: event.candidate.sdpMid,
+                });
+            }
+        };
+        // 2. Call the factory to create offer
+        let dc;
+        let offer;
+        try {
+            const factoryResult = await this.offerFactory(pc);
+            dc = factoryResult.dc;
+            offer = factoryResult.offer;
+        }
+        catch (err) {
+            pc.close();
+            throw err;
+        }
+        // 3. Publish to server to get offerId
+        const result = await this.api.publish({
+            tags: this.tags,
+            offers: [{ sdp: offer.sdp }],
+            ttl: this.ttl,
+        });
+        const offerId = result.offers[0].offerId;
+        // 4. Send any ICE candidates we've already collected
+        if (collectedCandidates.length > 0) {
+            this.debug(`Sending ${collectedCandidates.length} early ICE candidates for offer ${offerId}`);
+            this.api.addOfferIceCandidates(offerId, collectedCandidates).catch(err => {
+                this.debug('Failed to send early ICE candidates:', err);
+            });
+        }
+        return { offerId, pc, dc };
+    }
+    /**
+     * Create a new offer for rotation (reuses existing creation logic)
+     * Similar to createOffer() but only creates the offer, doesn't create connection
+     */
+    async createNewOfferForRotation() {
+        this.debug('Creating new offer for rotation...');
+        const { offerId, pc, dc } = await this.createOfferAndPublish();
+        this.debug(`New offer created for rotation: ${offerId}`);
+        return { newOfferId: offerId, pc, dc };
+    }
+    /**
+     * Create a single offer and publish it to the server
+     */
+    async createOffer() {
+        this.debug('Creating new offer...');
+        const { offerId, pc, dc } = await this.createOfferAndPublish();
+        // Create OffererConnection instance
+        const connection = new OffererConnection({
+            api: this.api,
+            ownerUsername: this.ownerUsername,
+            offerId,
+            pc,
+            dc,
+            webrtcAdapter: this.webrtcAdapter,
+            config: {
+                ...this.connectionConfig,
+                debug: this.debugEnabled,
+            },
+        });
+        // Setup connection event handlers
+        connection.on('connected', () => {
+            this.debug(`Connection established for offer ${offerId}`);
+            this.emit('connection:opened', offerId, connection);
+        });
+        connection.on('failed', async (error) => {
+            const currentOfferId = connection.getOfferId();
+            this.debug(`Connection failed for offer ${currentOfferId}`);
+            // Double-check connection state before rotating
+            // (polling events may have already recovered the connection)
+            if (connection.getState() !== 'failed') {
+                this.debug(`Connection ${currentOfferId} recovered, skipping rotation`);
+                return;
+            }
+            this.debug(`Proceeding with rotation for offer ${currentOfferId}`);
+            try {
+                // Create new offer and rebind existing connection
+                const { newOfferId, pc, dc } = await this.createNewOfferForRotation();
+                // Rebind the connection to new offer
+                await connection.rebindToOffer(newOfferId, pc, dc);
+                // Update map: remove old offerId, add new offerId with same connection
+                this.activeConnections.delete(currentOfferId);
+                this.activeConnections.set(newOfferId, connection);
+                this.emit('connection:rotated', currentOfferId, newOfferId, connection);
+                this.debug(`Connection rotated: ${currentOfferId} → ${newOfferId}`);
+            }
+            catch (rotationError) {
+                // If rotation fails, fall back to destroying connection
+                this.debug(`Rotation failed for ${currentOfferId}:`, rotationError);
+                this.activeConnections.delete(currentOfferId);
+                this.emit('offer:failed', currentOfferId, error);
+                this.fillOffers(); // Create replacement
+            }
+        });
+        connection.on('closed', () => {
+            this.debug(`Connection closed for offer ${offerId}`);
+            this.activeConnections.delete(offerId);
+            this.fillOffers(); // Replace closed offer
+        });
+        // Store active connection
+        this.activeConnections.set(offerId, connection);
+        // Initialize the connection
+        await connection.initialize();
+        this.debug(`Offer created: ${offerId}`);
+        this.emit('offer:created', offerId, this.tags);
+    }
+    /**
+     * Handle poll:answer event from PollingManager
+     * Called by Rondevu when a poll:answer event is received
+     */
+    async handlePollAnswer(data) {
+        if (!this.running)
+            return;
+        const connection = this.activeConnections.get(data.offerId);
+        if (connection) {
+            this.debug(`Processing answer for offer ${data.offerId}`);
+            try {
+                await connection.processAnswer(data.sdp, data.answererId);
+                // Create replacement offer
+                this.fillOffers();
+            }
+            catch (err) {
+                this.debug(`Failed to process answer for offer ${data.offerId}:`, err);
+            }
+        }
+        // Silently ignore answers for offers we don't have - they may be for other connections
+    }
+    /**
+     * Handle poll:ice event from PollingManager
+     * Called by Rondevu when a poll:ice event is received
+     */
+    handlePollIce(data) {
+        if (!this.running)
+            return;
+        const connection = this.activeConnections.get(data.offerId);
+        if (connection) {
+            this.debug(`Processing ${data.candidates.length} ICE candidates for offer ${data.offerId}`);
+            connection.handleRemoteIceCandidates(data.candidates);
+        }
+        // Silently ignore ICE candidates for offers we don't have
+    }
+    /**
+     * Debug logging (only if debug enabled)
+     */
+    debug(...args) {
+        if (this.debugEnabled) {
+            console.log('[OfferPool]', ...args);
+        }
+    }
+}

package/dist/core/peer.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Peer - Clean DX wrapper for peer-to-peer connections
+ *
+ * Provides a simple interface for connecting to a peer by tags/username,
+ * with automatic reconnection and message buffering.
+ */
+import { EventEmitter } from 'eventemitter3';
+import { RondevuAPI } from '../api/client.js';
+import { AnswererConnection } from '../connections/answerer.js';
+import { ConnectionConfig } from '../connections/config.js';
+/**
+ * Simplified peer state (maps from ConnectionState)
+ */
+export type PeerState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'failed' | 'closed';
+/**
+ * Event map for Peer
+ */
+export interface PeerEventMap {
+    /** Emitted when connection state changes */
+    state: [state: PeerState, previousState: PeerState];
+    /** Emitted when connection is established */
+    open: [];
+    /** Emitted when connection is closed */
+    close: [reason?: string];
+    /** Emitted when a message is received */
+    message: [data: string | ArrayBuffer | Blob];
+    /** Emitted when an error occurs */
+    error: [error: Error];
+    /** Emitted when reconnection is attempted */
+    reconnecting: [attempt: number, maxAttempts: number];
+}
+export type PeerEventName = keyof PeerEventMap;
+/**
+ * Options for creating a Peer connection
+ */
+export interface PeerOptions {
+    /** Tags to match for peer discovery */
+    tags: string[];
+    /** Optional: connect to specific username */
+    username?: string;
+    /** Optional: custom RTC configuration */
+    rtcConfig?: RTCConfiguration;
+    /** Optional: connection behavior configuration */
+    config?: Partial<ConnectionConfig>;
+}
+/**
+ * Internal options passed from Rondevu
+ */
+export interface PeerInternalOptions extends PeerOptions {
+    api: RondevuAPI;
+    iceServers: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+    debug?: boolean;
+}
+/**
+ * Peer - A clean interface for peer-to-peer connections
+ *
+ * @example
+ * ```typescript
+ * const peer = await rondevu.peer({
+ *   username: 'alice',
+ *   tags: ['chat']
+ * })
+ *
+ * peer.on('open', () => {
+ *   console.log('Connected to', peer.peerUsername)
+ *   peer.send('Hello!')
+ * })
+ *
+ * peer.on('message', (data) => {
+ *   console.log('Received:', data)
+ * })
+ *
+ * peer.on('state', (state) => {
+ *   console.log('Connection state:', state)
+ * })
+ *
+ * // Access underlying WebRTC objects
+ * const pc = peer.peerConnection  // RTCPeerConnection
+ * const dc = peer.dataChannel     // RTCDataChannel
+ * ```
+ */
+export declare class Peer extends EventEmitter<PeerEventMap> {
+    private connection;
+    private api;
+    private tags;
+    private targetUsername?;
+    private iceServers;
+    private iceTransportPolicy?;
+    private connectionConfig?;
+    private debugEnabled;
+    private _state;
+    private _peerUsername;
+    private _offerId;
+    constructor(options: PeerInternalOptions);
+    /**
+     * Initialize the peer connection (called internally by Rondevu.peer())
+     */
+    initialize(): Promise<void>;
+    /**
+     * Setup event handlers to forward from AnswererConnection
+     */
+    private setupEventHandlers;
+    /**
+     * Map internal ConnectionState to simplified PeerState
+     */
+    private mapState;
+    /**
+     * Current connection state
+     */
+    get state(): PeerState;
+    /**
+     * Username of the connected peer
+     */
+    get peerUsername(): string;
+    /**
+     * The offer ID being used for this connection
+     */
+    get offerId(): string;
+    /**
+     * Tags used for discovery
+     */
+    get peerTags(): string[];
+    /**
+     * The underlying RTCPeerConnection (null if not connected)
+     */
+    get peerConnection(): RTCPeerConnection | null;
+    /**
+     * The underlying RTCDataChannel (null if not connected)
+     */
+    get dataChannel(): RTCDataChannel | null;
+    /**
+     * Whether the peer is currently connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Send a message to the peer
+     * Messages are buffered if not connected (when buffering is enabled)
+     *
+     * @param data - String, ArrayBuffer, or Blob to send
+     */
+    send(data: string | ArrayBuffer | Blob): void;
+    /**
+     * Close the peer connection
+     */
+    close(): void;
+    /**
+     * Get the underlying AnswererConnection for advanced use cases
+     */
+    getConnection(): AnswererConnection | null;
+    /**
+     * Debug logging
+     */
+    private debug;
+}

package/dist/core/peer.js

@@ -0,0 +1,252 @@
+/**
+ * Peer - Clean DX wrapper for peer-to-peer connections
+ *
+ * Provides a simple interface for connecting to a peer by tags/username,
+ * with automatic reconnection and message buffering.
+ */
+import { EventEmitter } from 'eventemitter3';
+import { AnswererConnection } from '../connections/answerer.js';
+import { ConnectionState } from '../connections/events.js';
+/**
+ * Peer - A clean interface for peer-to-peer connections
+ *
+ * @example
+ * ```typescript
+ * const peer = await rondevu.peer({
+ *   username: 'alice',
+ *   tags: ['chat']
+ * })
+ *
+ * peer.on('open', () => {
+ *   console.log('Connected to', peer.peerUsername)
+ *   peer.send('Hello!')
+ * })
+ *
+ * peer.on('message', (data) => {
+ *   console.log('Received:', data)
+ * })
+ *
+ * peer.on('state', (state) => {
+ *   console.log('Connection state:', state)
+ * })
+ *
+ * // Access underlying WebRTC objects
+ * const pc = peer.peerConnection  // RTCPeerConnection
+ * const dc = peer.dataChannel     // RTCDataChannel
+ * ```
+ */
+export class Peer extends EventEmitter {
+    constructor(options) {
+        super();
+        this.connection = null;
+        this._state = 'connecting';
+        this._peerUsername = '';
+        this._offerId = '';
+        this.api = options.api;
+        this.tags = options.tags;
+        this.targetUsername = options.username;
+        this.iceServers = options.iceServers;
+        this.iceTransportPolicy = options.iceTransportPolicy;
+        this.connectionConfig = options.config;
+        this.debugEnabled = options.debug || false;
+    }
+    /**
+     * Initialize the peer connection (called internally by Rondevu.peer())
+     */
+    async initialize() {
+        this.debug('Initializing peer connection');
+        this.debug(`Tags: ${this.tags.join(', ')}${this.targetUsername ? `, username: ${this.targetUsername}` : ''}`);
+        // Discover offers
+        const result = (await this.api.discover({
+            tags: this.tags,
+            limit: 100,
+        }));
+        if (!result.offers || result.offers.length === 0) {
+            throw new Error(`No peers found for tags: ${this.tags.join(', ')}`);
+        }
+        // Filter by username if specified
+        let availableOffers = result.offers;
+        if (this.targetUsername) {
+            availableOffers = result.offers.filter((o) => o.username === this.targetUsername);
+            if (availableOffers.length === 0) {
+                throw new Error(`No peers found for tags: ${this.tags.join(', ')} from @${this.targetUsername}`);
+            }
+        }
+        // Pick a random offer
+        const offer = availableOffers[Math.floor(Math.random() * availableOffers.length)];
+        this._peerUsername = offer.username;
+        this._offerId = offer.offerId;
+        this.debug(`Selected offer ${offer.offerId} from @${offer.username}`);
+        // Create the underlying AnswererConnection
+        this.connection = new AnswererConnection({
+            api: this.api,
+            ownerUsername: offer.username,
+            tags: offer.tags,
+            offerId: offer.offerId,
+            offerSdp: offer.sdp,
+            rtcConfig: {
+                iceServers: this.iceServers,
+                iceTransportPolicy: this.iceTransportPolicy,
+            },
+            config: {
+                ...this.connectionConfig,
+                debug: this.debugEnabled,
+            },
+        });
+        // Wire up events
+        this.setupEventHandlers();
+        // Start connection
+        await this.connection.initialize();
+    }
+    /**
+     * Setup event handlers to forward from AnswererConnection
+     */
+    setupEventHandlers() {
+        if (!this.connection)
+            return;
+        // Map ConnectionState to PeerState
+        this.connection.on('state:changed', ({ oldState, newState, reason }) => {
+            const mappedOld = this.mapState(oldState);
+            const mappedNew = this.mapState(newState);
+            if (mappedOld !== mappedNew) {
+                this._state = mappedNew;
+                this.emit('state', mappedNew, mappedOld);
+            }
+        });
+        // Forward connection events
+        this.connection.on('connected', () => {
+            this._state = 'connected';
+            this.emit('open');
+        });
+        this.connection.on('closed', reason => {
+            this._state = 'closed';
+            this.emit('close', reason);
+        });
+        this.connection.on('failed', error => {
+            this._state = 'failed';
+            this.emit('error', error);
+        });
+        // Forward message events
+        this.connection.on('message', data => {
+            this.emit('message', data);
+        });
+        // Forward reconnection events
+        this.connection.on('reconnect:scheduled', info => {
+            this._state = 'reconnecting';
+            this.emit('reconnecting', info.attempt, info.maxAttempts);
+        });
+        this.connection.on('reconnect:success', () => {
+            // State will be updated by 'connected' event
+        });
+        this.connection.on('reconnect:failed', error => {
+            this.emit('error', error);
+        });
+    }
+    /**
+     * Map internal ConnectionState to simplified PeerState
+     */
+    mapState(state) {
+        switch (state) {
+            case ConnectionState.INITIALIZING:
+            case ConnectionState.GATHERING:
+            case ConnectionState.SIGNALING:
+            case ConnectionState.CHECKING:
+            case ConnectionState.CONNECTING:
+                return 'connecting';
+            case ConnectionState.CONNECTED:
+                return 'connected';
+            case ConnectionState.DISCONNECTED:
+                return 'disconnected';
+            case ConnectionState.RECONNECTING:
+                return 'reconnecting';
+            case ConnectionState.FAILED:
+                return 'failed';
+            case ConnectionState.CLOSED:
+                return 'closed';
+            default:
+                return 'connecting';
+        }
+    }
+    // ========================================
+    // Public Properties
+    // ========================================
+    /**
+     * Current connection state
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Username of the connected peer
+     */
+    get peerUsername() {
+        return this._peerUsername;
+    }
+    /**
+     * The offer ID being used for this connection
+     */
+    get offerId() {
+        return this._offerId;
+    }
+    /**
+     * Tags used for discovery
+     */
+    get peerTags() {
+        return this.tags;
+    }
+    /**
+     * The underlying RTCPeerConnection (null if not connected)
+     */
+    get peerConnection() {
+        return this.connection?.getPeerConnection() ?? null;
+    }
+    /**
+     * The underlying RTCDataChannel (null if not connected)
+     */
+    get dataChannel() {
+        return this.connection?.getDataChannel() ?? null;
+    }
+    /**
+     * Whether the peer is currently connected
+     */
+    get isConnected() {
+        return this._state === 'connected';
+    }
+    // ========================================
+    // Public Methods
+    // ========================================
+    /**
+     * Send a message to the peer
+     * Messages are buffered if not connected (when buffering is enabled)
+     *
+     * @param data - String, ArrayBuffer, or Blob to send
+     */
+    send(data) {
+        if (!this.connection) {
+            throw new Error('Peer not initialized');
+        }
+        this.connection.send(data);
+    }
+    /**
+     * Close the peer connection
+     */
+    close() {
+        this.debug('Closing peer connection');
+        this.connection?.close();
+        this._state = 'closed';
+    }
+    /**
+     * Get the underlying AnswererConnection for advanced use cases
+     */
+    getConnection() {
+        return this.connection;
+    }
+    /**
+     * Debug logging
+     */
+    debug(...args) {
+        if (this.debugEnabled) {
+            console.log('[Peer]', ...args);
+        }
+    }
+}