@xtr-dev/rondevu-client 0.18.10 → 0.21.1

package/dist/connections/offerer.js

@@ -0,0 +1,306 @@
+/**
+ * Offerer-side WebRTC connection with offer creation and answer processing
+ */
+import { RondevuConnection } from './base.js';
+import { ConnectionState } from './events.js';
+import { AsyncLock } from '../utils/async-lock.js';
+/**
+ * Offerer connection - manages already-created offers and waits for answers
+ */
+export class OffererConnection extends RondevuConnection {
+    constructor(options) {
+        // Force reconnectEnabled: false for offerer connections (offers are ephemeral)
+        super(undefined, { ...options.config, reconnectEnabled: false }, options.webrtcAdapter);
+        this._peerUsername = null;
+        // Rotation tracking
+        this.rotationLock = new AsyncLock();
+        this.rotating = false;
+        this.rotationAttempts = 0;
+        // ICE candidate buffering (for candidates received before answer is processed)
+        this.pendingIceCandidates = [];
+        this.api = options.api;
+        this.ownerUsername = options.ownerUsername;
+        this.offerId = options.offerId;
+        // Use the already-created peer connection and data channel
+        this.pc = options.pc;
+        this.dc = options.dc || null;
+    }
+    /**
+     * Initialize the connection - setup handlers for already-created offer
+     */
+    async initialize() {
+        this.debug('Initializing offerer connection');
+        if (!this.pc)
+            throw new Error('Peer connection not provided');
+        // Setup peer connection event handlers
+        this.pc.onicecandidate = event => this.handleIceCandidate(event);
+        this.pc.oniceconnectionstatechange = () => this.handleIceConnectionStateChange();
+        this.pc.onconnectionstatechange = () => this.handleConnectionStateChange();
+        this.pc.onicegatheringstatechange = () => this.handleIceGatheringStateChange();
+        // Setup data channel handlers if we have one
+        if (this.dc) {
+            this.setupDataChannelHandlers(this.dc);
+        }
+        // Start connection timeout
+        this.startConnectionTimeout();
+        // Transition to signaling state (offer already created and published)
+        this.transitionTo(ConnectionState.SIGNALING, 'Offer published, waiting for answer');
+    }
+    /**
+     * Process an answer from the answerer
+     */
+    async processAnswer(sdp, answererId) {
+        if (!this.pc) {
+            this.debug('Cannot process answer: peer connection not initialized');
+            return;
+        }
+        // Generate SDP fingerprint for deduplication
+        const fingerprint = await this.hashSdp(sdp);
+        // Check for duplicate answer
+        if (this.answerProcessed) {
+            if (this.answerSdpFingerprint === fingerprint) {
+                this.debug('Duplicate answer detected (same fingerprint), skipping');
+                this.emit('answer:duplicate', this.offerId);
+                return;
+            }
+            else {
+                throw new Error('Received different answer after already processing one (protocol violation)');
+            }
+        }
+        // Validate state - allow SIGNALING, CHECKING, and FAILED (for late-arriving answers before rotation)
+        if (this.state !== ConnectionState.SIGNALING &&
+            this.state !== ConnectionState.CHECKING &&
+            this.state !== ConnectionState.FAILED) {
+            this.debug(`Cannot process answer in state ${this.state}`);
+            return;
+        }
+        // Mark as processed BEFORE setRemoteDescription to prevent race conditions
+        this.answerProcessed = true;
+        this.answerSdpFingerprint = fingerprint;
+        try {
+            await this.pc.setRemoteDescription({
+                type: 'answer',
+                sdp,
+            });
+            // Store the peer username
+            this._peerUsername = answererId;
+            this.debug(`Answer processed successfully from ${answererId}`);
+            this.emit('answer:processed', this.offerId, answererId);
+            // Apply any buffered ICE candidates that arrived before the answer
+            if (this.pendingIceCandidates.length > 0) {
+                this.debug(`Applying ${this.pendingIceCandidates.length} buffered ICE candidates`);
+                const buffered = this.pendingIceCandidates;
+                this.pendingIceCandidates = [];
+                this.applyIceCandidates(buffered);
+            }
+        }
+        catch (error) {
+            // Reset flags on error so we can try again
+            this.answerProcessed = false;
+            this.answerSdpFingerprint = null;
+            this.debug('Failed to set remote description:', error);
+            throw error;
+        }
+    }
+    /**
+     * Rebind this connection to a new offer (when previous offer failed)
+     * Keeps the same connection object alive but with new underlying WebRTC
+     */
+    async rebindToOffer(newOfferId, newPc, newDc) {
+        return this.rotationLock.run(async () => {
+            if (this.rotating) {
+                throw new Error('Rotation already in progress');
+            }
+            this.rotating = true;
+            try {
+                this.rotationAttempts++;
+                if (this.rotationAttempts > OffererConnection.MAX_ROTATION_ATTEMPTS) {
+                    throw new Error('Max rotation attempts exceeded');
+                }
+                this.debug(`Rebinding connection from ${this.offerId} to ${newOfferId}`);
+                // 1. Clean up old peer connection
+                if (this.pc) {
+                    this.pc.close();
+                }
+                if (this.dc && this.dc !== newDc) {
+                    this.dc.close();
+                }
+                // 2. Update to new offer
+                this.offerId = newOfferId;
+                this.pc = newPc;
+                this.dc = newDc || null;
+                // 3. Reset answer processing flags, peer username, and pending candidates
+                this.answerProcessed = false;
+                this.answerSdpFingerprint = null;
+                this._peerUsername = null;
+                this.pendingIceCandidates = [];
+                // 4. Setup event handlers for new peer connection
+                this.pc.onicecandidate = event => this.handleIceCandidate(event);
+                this.pc.oniceconnectionstatechange = () => this.handleIceConnectionStateChange();
+                this.pc.onconnectionstatechange = () => this.handleConnectionStateChange();
+                this.pc.onicegatheringstatechange = () => this.handleIceGatheringStateChange();
+                // 5. Setup data channel handlers if we have one
+                if (this.dc) {
+                    this.setupDataChannelHandlers(this.dc);
+                }
+                // 6. Restart connection timeout
+                this.startConnectionTimeout();
+                // 7. Transition to SIGNALING state (waiting for answer)
+                this.transitionTo(ConnectionState.SIGNALING, 'Offer rotated, waiting for answer');
+                // Note: Message buffer is NOT cleared - it persists!
+                this.debug(`Rebind complete. Buffer has ${this.messageBuffer?.size() ?? 0} messages`);
+            }
+            finally {
+                this.rotating = false;
+            }
+        });
+    }
+    /**
+     * Check if connection is currently rotating
+     */
+    isRotating() {
+        return this.rotating;
+    }
+    /**
+     * Override onConnected to reset rotation attempts
+     */
+    onConnected() {
+        super.onConnected();
+        this.rotationAttempts = 0;
+        this.debug('Connection established, rotation attempts reset');
+    }
+    /**
+     * Generate a hash fingerprint of SDP for deduplication
+     */
+    async hashSdp(sdp) {
+        // Simple hash using built-in crypto if available
+        if (typeof crypto !== 'undefined' && crypto.subtle) {
+            const encoder = new TextEncoder();
+            const data = encoder.encode(sdp);
+            const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+            const hashArray = Array.from(new Uint8Array(hashBuffer));
+            return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+        }
+        else {
+            // Fallback: use simple string hash
+            let hash = 0;
+            for (let i = 0; i < sdp.length; i++) {
+                const char = sdp.charCodeAt(i);
+                hash = (hash << 5) - hash + char;
+                hash = hash & hash;
+            }
+            return hash.toString(16);
+        }
+    }
+    /**
+     * Handle local ICE candidate generation
+     */
+    onLocalIceCandidate(candidate) {
+        this.debug('Generated local ICE candidate');
+        // Send ICE candidate to server
+        this.api
+            .addOfferIceCandidates(this.offerId, [
+            {
+                candidate: candidate.candidate,
+                sdpMLineIndex: candidate.sdpMLineIndex,
+                sdpMid: candidate.sdpMid,
+            },
+        ])
+            .catch(error => {
+            this.debug('Failed to send ICE candidate:', error);
+        });
+    }
+    /**
+     * Get the API instance
+     */
+    getApi() {
+        return this.api;
+    }
+    /**
+     * Get the owner username
+     */
+    getOwnerUsername() {
+        return this.ownerUsername;
+    }
+    /**
+     * Offerers accept all ICE candidates (no filtering)
+     */
+    getIceCandidateRole() {
+        return null;
+    }
+    /**
+     * Attempt to reconnect (required by abstract base class)
+     *
+     * For OffererConnection, traditional reconnection is NOT used.
+     * Instead, the OfferPool handles failures via offer rotation:
+     *
+     * 1. When this connection fails, the 'failed' event is emitted
+     * 2. OfferPool detects the failure and calls createNewOfferForRotation()
+     * 3. The new offer is published to the server
+     * 4. This connection is rebound via rebindToOffer()
+     *
+     * This approach ensures the answerer always gets a fresh offer
+     * rather than trying to reconnect to a stale one.
+     *
+     * @see OfferPool.createNewOfferForRotation() - creates replacement offer
+     * @see OffererConnection.rebindToOffer() - rebinds connection to new offer
+     */
+    attemptReconnect() {
+        this.debug('Reconnection delegated to OfferPool rotation mechanism');
+        this.emit('reconnect:failed', new Error('Offerer uses rotation, not reconnection'));
+    }
+    /**
+     * Get the offer ID
+     */
+    getOfferId() {
+        return this.offerId;
+    }
+    /**
+     * Get the peer username (who answered this offer)
+     * Returns null if no answer has been processed yet
+     */
+    get peerUsername() {
+        return this._peerUsername;
+    }
+    /**
+     * Handle remote ICE candidates received from polling
+     * Called by OfferPool when poll:ice event is received
+     */
+    handleRemoteIceCandidates(candidates) {
+        if (!this.pc) {
+            this.debug('Cannot add ICE candidates: peer connection not initialized');
+            return;
+        }
+        // If answer hasn't been processed yet, buffer the candidates
+        if (!this.answerProcessed) {
+            this.debug(`Buffering ${candidates.length} ICE candidates (waiting for answer)`);
+            this.pendingIceCandidates.push(...candidates);
+            return;
+        }
+        // Answer is processed, apply candidates immediately
+        this.applyIceCandidates(candidates);
+    }
+    /**
+     * Apply ICE candidates to the peer connection
+     */
+    applyIceCandidates(candidates) {
+        if (!this.pc)
+            return;
+        for (const iceCandidate of candidates) {
+            // Offerer accepts answerer's candidates (no role filtering needed here
+            // since OfferPool already filters by offerId)
+            if (iceCandidate.candidate) {
+                const rtcCandidate = this.webrtcAdapter.createIceCandidate(iceCandidate.candidate);
+                this.pc
+                    .addIceCandidate(rtcCandidate)
+                    .then(() => {
+                    this.emit('ice:candidate:remote', rtcCandidate);
+                })
+                    .catch(error => {
+                    this.debug('Failed to add ICE candidate:', error);
+                });
+            }
+        }
+    }
+}
+OffererConnection.MAX_ROTATION_ATTEMPTS = 5;

package/dist/core/ice-config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ICE Configuration Types and Presets
+ *
+ * Provides typed ICE server presets for common WebRTC configurations.
+ */
+/**
+ * Available ICE server preset names
+ */
+export type IceServerPreset = 'rondevu' | 'rondevu-relay' | 'rondevu-ipv4' | 'rondevu-ipv4-relay' | 'google-stun' | 'public-stun';
+/**
+ * ICE preset configuration containing servers and optional transport policy.
+ * The iceTransportPolicy belongs on RTCConfiguration, not RTCIceServer.
+ */
+export interface IcePresetConfig {
+    iceServers: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+}
+/**
+ * Pre-configured ICE server presets.
+ *
+ * - `rondevu`: Official Rondevu TURN/STUN servers (recommended)
+ * - `rondevu-relay`: Same as rondevu but forces relay mode (hides client IPs)
+ * - `rondevu-ipv4`: Direct IPv4 address (for networks with DNS issues)
+ * - `rondevu-ipv4-relay`: IPv4 with forced relay mode
+ * - `google-stun`: Google's free STUN servers (no relay, direct connections only)
+ * - `public-stun`: Multiple public STUN servers for redundancy
+ */
+export declare const ICE_SERVER_PRESETS: Record<IceServerPreset, IcePresetConfig>;
+/**
+ * Get the full RTCConfiguration for a preset or custom ICE servers.
+ *
+ * @param iceServers - Either a preset name or custom ICE servers array
+ * @returns Partial RTCConfiguration with iceServers and optional iceTransportPolicy
+ */
+export declare function getIceConfiguration(iceServers?: IceServerPreset | RTCIceServer[]): Pick<RTCConfiguration, 'iceServers' | 'iceTransportPolicy'>;

package/dist/core/ice-config.js

@@ -0,0 +1,111 @@
+/**
+ * ICE Configuration Types and Presets
+ *
+ * Provides typed ICE server presets for common WebRTC configurations.
+ */
+/**
+ * Pre-configured ICE server presets.
+ *
+ * - `rondevu`: Official Rondevu TURN/STUN servers (recommended)
+ * - `rondevu-relay`: Same as rondevu but forces relay mode (hides client IPs)
+ * - `rondevu-ipv4`: Direct IPv4 address (for networks with DNS issues)
+ * - `rondevu-ipv4-relay`: IPv4 with forced relay mode
+ * - `google-stun`: Google's free STUN servers (no relay, direct connections only)
+ * - `public-stun`: Multiple public STUN servers for redundancy
+ */
+export const ICE_SERVER_PRESETS = {
+    rondevu: {
+        iceServers: [
+            { urls: 'stun:relay.ronde.vu:3478' },
+            {
+                urls: [
+                    'turns:relay.ronde.vu:5349?transport=tcp',
+                    'turn:relay.ronde.vu:3478?transport=tcp',
+                    'turn:relay.ronde.vu:3478?transport=udp',
+                ],
+                username: 'rondevu',
+                credential: 'rondevu-public-turn',
+            },
+        ],
+    },
+    'rondevu-relay': {
+        iceServers: [
+            { urls: 'stun:relay.ronde.vu:3478' },
+            {
+                urls: [
+                    'turns:relay.ronde.vu:5349?transport=tcp',
+                    'turn:relay.ronde.vu:3478?transport=tcp',
+                    'turn:relay.ronde.vu:3478?transport=udp',
+                ],
+                username: 'rondevu',
+                credential: 'rondevu-public-turn',
+            },
+        ],
+        iceTransportPolicy: 'relay', // Force relay mode - hides client IPs
+    },
+    'rondevu-ipv4': {
+        iceServers: [
+            { urls: 'stun:57.129.61.67:3478' },
+            {
+                urls: [
+                    'turn:57.129.61.67:3478?transport=tcp',
+                    'turn:57.129.61.67:3478?transport=udp',
+                ],
+                username: 'rondevu',
+                credential: 'rondevu-public-turn',
+            },
+        ],
+    },
+    'rondevu-ipv4-relay': {
+        iceServers: [
+            { urls: 'stun:57.129.61.67:3478' },
+            {
+                urls: [
+                    'turn:57.129.61.67:3478?transport=tcp',
+                    'turn:57.129.61.67:3478?transport=udp',
+                ],
+                username: 'rondevu',
+                credential: 'rondevu-public-turn',
+            },
+        ],
+        iceTransportPolicy: 'relay',
+    },
+    'google-stun': {
+        iceServers: [
+            { urls: 'stun:stun.l.google.com:19302' },
+            { urls: 'stun:stun1.l.google.com:19302' },
+        ],
+    },
+    'public-stun': {
+        iceServers: [
+            { urls: 'stun:stun.l.google.com:19302' },
+            { urls: 'stun:stun1.l.google.com:19302' },
+            { urls: 'stun:stun.cloudflare.com:3478' },
+            { urls: 'stun:stun.relay.metered.ca:80' },
+        ],
+    },
+};
+/**
+ * Get the full RTCConfiguration for a preset or custom ICE servers.
+ *
+ * @param iceServers - Either a preset name or custom ICE servers array
+ * @returns Partial RTCConfiguration with iceServers and optional iceTransportPolicy
+ */
+export function getIceConfiguration(iceServers) {
+    if (typeof iceServers === 'string') {
+        const preset = ICE_SERVER_PRESETS[iceServers];
+        return {
+            iceServers: preset.iceServers,
+            iceTransportPolicy: preset.iceTransportPolicy,
+        };
+    }
+    // Default to rondevu preset if no ICE servers specified
+    if (!iceServers) {
+        const preset = ICE_SERVER_PRESETS.rondevu;
+        return {
+            iceServers: preset.iceServers,
+            iceTransportPolicy: preset.iceTransportPolicy,
+        };
+    }
+    return { iceServers };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @xtr-dev/rondevu-client
+ * WebRTC peer signaling client
+ *
+ * Simple API:
+ *   const rondevu = await Rondevu.connect()
+ *
+ *   // Host: publish offers (auto-starts)
+ *   const offer = await rondevu.offer({ tags: ['chat'], maxOffers: 5 })
+ *   rondevu.on('connection:opened', (id, conn) => { ... })
+ *   // Later: offer.cancel()
+ *
+ *   // Guest: connect to a peer
+ *   const peer = await rondevu.peer({ tags: ['chat'] })
+ *   peer.on('open', () => peer.send('Hello!'))
+ */
+export { Rondevu } from './rondevu.js';
+export { Peer } from './peer.js';
+export { ICE_SERVER_PRESETS } from './ice-config.js';
+export type { RondevuOptions, OfferOptions, OfferHandle, DiscoverOptions, DiscoverResult, } from './rondevu.js';
+export type { PeerState, PeerOptions } from './peer.js';
+export type { IceServerPreset } from './ice-config.js';

package/dist/core/index.js

@@ -0,0 +1,22 @@
+/**
+ * @xtr-dev/rondevu-client
+ * WebRTC peer signaling client
+ *
+ * Simple API:
+ *   const rondevu = await Rondevu.connect()
+ *
+ *   // Host: publish offers (auto-starts)
+ *   const offer = await rondevu.offer({ tags: ['chat'], maxOffers: 5 })
+ *   rondevu.on('connection:opened', (id, conn) => { ... })
+ *   // Later: offer.cancel()
+ *
+ *   // Guest: connect to a peer
+ *   const peer = await rondevu.peer({ tags: ['chat'] })
+ *   peer.on('open', () => peer.send('Hello!'))
+ */
+// Main entry point
+export { Rondevu } from './rondevu.js';
+// Simplified peer connection
+export { Peer } from './peer.js';
+// ICE server configuration presets
+export { ICE_SERVER_PRESETS } from './ice-config.js';

package/dist/core/offer-pool.d.ts

@@ -0,0 +1,113 @@
+import { EventEmitter } from 'eventemitter3';
+import { RondevuAPI } from '../api/client.js';
+import { OffererConnection } from '../connections/offerer.js';
+import { ConnectionConfig } from '../connections/config.js';
+import { WebRTCAdapter } from '../webrtc/adapter.js';
+import type { PollAnswerEvent, PollIceEvent } from './polling-manager.js';
+export type OfferFactory = (pc: RTCPeerConnection) => Promise<{
+    dc?: RTCDataChannel;
+    offer: RTCSessionDescriptionInit;
+}>;
+export interface OfferPoolOptions {
+    api: RondevuAPI;
+    tags: string[];
+    ownerUsername: string;
+    maxOffers: number;
+    offerFactory: OfferFactory;
+    ttl: number;
+    iceServers: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+    webrtcAdapter: WebRTCAdapter;
+    connectionConfig?: Partial<ConnectionConfig>;
+    debugEnabled?: boolean;
+}
+interface OfferPoolEvents {
+    'connection:opened': (offerId: string, connection: OffererConnection) => void;
+    'offer:created': (offerId: string, tags: string[]) => void;
+    'offer:failed': (offerId: string, error: Error) => void;
+    'connection:rotated': (oldOfferId: string, newOfferId: string, connection: OffererConnection) => void;
+}
+/**
+ * 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 declare class OfferPool extends EventEmitter<OfferPoolEvents> {
+    private readonly api;
+    private readonly tags;
+    private readonly ownerUsername;
+    private readonly maxOffers;
+    private readonly offerFactory;
+    private readonly ttl;
+    private readonly iceServers;
+    private readonly iceTransportPolicy?;
+    private readonly webrtcAdapter;
+    private readonly connectionConfig?;
+    private readonly debugEnabled;
+    private readonly activeConnections;
+    private readonly fillLock;
+    private running;
+    constructor(options: OfferPoolOptions);
+    /**
+     * Start filling offers
+     * Polling is managed externally by Rondevu's PollingManager
+     */
+    start(): Promise<void>;
+    /**
+     * Stop filling offers
+     * Closes all active connections
+     */
+    stop(): void;
+    /**
+     * Get count of active offers
+     */
+    getOfferCount(): number;
+    /**
+     * Get all active connections
+     */
+    getActiveConnections(): Map<string, OffererConnection>;
+    /**
+     * Check if a specific offer is connected
+     */
+    isConnected(offerId: string): boolean;
+    /**
+     * Disconnect all active offers
+     */
+    disconnectAll(): void;
+    /**
+     * Fill offers to reach maxOffers count
+     * Uses AsyncLock to prevent concurrent fills
+     */
+    private fillOffers;
+    /**
+     * 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
+     */
+    private createOfferAndPublish;
+    /**
+     * Create a new offer for rotation (reuses existing creation logic)
+     * Similar to createOffer() but only creates the offer, doesn't create connection
+     */
+    private createNewOfferForRotation;
+    /**
+     * Create a single offer and publish it to the server
+     */
+    private createOffer;
+    /**
+     * Handle poll:answer event from PollingManager
+     * Called by Rondevu when a poll:answer event is received
+     */
+    handlePollAnswer(data: PollAnswerEvent): Promise<void>;
+    /**
+     * Handle poll:ice event from PollingManager
+     * Called by Rondevu when a poll:ice event is received
+     */
+    handlePollIce(data: PollIceEvent): void;
+    /**
+     * Debug logging (only if debug enabled)
+     */
+    private debug;
+}
+export {};