@xtr-dev/rondevu-client 0.7.12 → 0.8.1

package/dist/service-pool.js

@@ -0,0 +1,339 @@
+import { RondevuOffers } from './offers.js';
+import { RondevuUsername } from './usernames.js';
+import RondevuPeer from './peer/index.js';
+import { OfferPool } from './offer-pool.js';
+/**
+ * Manages a pooled service with multiple concurrent connections
+ *
+ * ServicePool coordinates offer creation, answer polling, and connection
+ * management for services that need to handle multiple simultaneous connections.
+ */
+export class ServicePool {
+    constructor(baseUrl, credentials, options) {
+        this.baseUrl = baseUrl;
+        this.credentials = credentials;
+        this.options = options;
+        this.connections = new Map();
+        this.status = {
+            activeOffers: 0,
+            activeConnections: 0,
+            totalConnectionsHandled: 0,
+            failedOfferCreations: 0
+        };
+        this.offersApi = new RondevuOffers(baseUrl, credentials);
+        this.usernameApi = new RondevuUsername(baseUrl);
+    }
+    /**
+     * Start the pooled service
+     */
+    async start() {
+        const poolSize = this.options.poolSize || 1;
+        // 1. Create initial service (publishes first offer)
+        const service = await this.publishInitialService();
+        this.serviceId = service.serviceId;
+        this.uuid = service.uuid;
+        // 2. Create additional offers for pool (poolSize - 1)
+        const additionalOffers = [];
+        if (poolSize > 1) {
+            try {
+                const offers = await this.createOffers(poolSize - 1);
+                additionalOffers.push(...offers);
+            }
+            catch (error) {
+                this.handleError(error, 'initial-offer-creation');
+            }
+        }
+        // 3. Initialize OfferPool with all offers
+        this.offerPool = new OfferPool(this.offersApi, {
+            poolSize,
+            pollingInterval: this.options.pollingInterval || 2000,
+            onAnswered: (answer) => this.handleConnection(answer),
+            onRefill: (count) => this.createOffers(count),
+            onError: (err, ctx) => this.handleError(err, ctx)
+        });
+        // Add all offers to pool
+        const allOffers = [
+            { id: service.offerId, peerId: this.credentials.peerId, sdp: '', topics: [], expiresAt: service.expiresAt, lastSeen: Date.now() },
+            ...additionalOffers
+        ];
+        await this.offerPool.addOffers(allOffers);
+        // 4. Start polling
+        await this.offerPool.start();
+        // Update status
+        this.updateStatus();
+        // 5. Return handle
+        return {
+            serviceId: this.serviceId,
+            uuid: this.uuid,
+            offerId: service.offerId,
+            unpublish: () => this.stop(),
+            getStatus: () => this.getStatus(),
+            addOffers: (count) => this.manualRefill(count)
+        };
+    }
+    /**
+     * Stop the pooled service and clean up
+     */
+    async stop() {
+        // 1. Stop accepting new connections
+        if (this.offerPool) {
+            await this.offerPool.stop();
+        }
+        // 2. Delete remaining offers
+        if (this.offerPool) {
+            const offerIds = this.offerPool.getActiveOfferIds();
+            await Promise.allSettled(offerIds.map(id => this.offersApi.delete(id).catch(() => { })));
+        }
+        // 3. Close active connections
+        const closePromises = Array.from(this.connections.values()).map(async (conn) => {
+            try {
+                // Give a brief moment for graceful closure
+                await new Promise(resolve => setTimeout(resolve, 100));
+                conn.peer.pc.close();
+            }
+            catch {
+                // Ignore errors during cleanup
+            }
+        });
+        await Promise.allSettled(closePromises);
+        // 4. Delete service if we have a serviceId
+        if (this.serviceId) {
+            try {
+                const response = await fetch(`${this.baseUrl}/services/${this.serviceId}`, {
+                    method: 'DELETE',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${this.credentials.peerId}:${this.credentials.secret}`
+                    },
+                    body: JSON.stringify({ username: this.options.username })
+                });
+                if (!response.ok) {
+                    console.error('Failed to delete service:', await response.text());
+                }
+            }
+            catch (error) {
+                console.error('Error deleting service:', error);
+            }
+        }
+        // Clear all state
+        this.connections.clear();
+        this.offerPool = undefined;
+    }
+    /**
+     * Handle an answered offer by setting up the connection
+     */
+    async handleConnection(answer) {
+        const connectionId = this.generateConnectionId();
+        try {
+            // Create peer connection
+            const peer = new RondevuPeer(this.offersApi, this.options.rtcConfig || {
+                iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+            });
+            peer.role = 'offerer';
+            peer.offerId = answer.offerId;
+            // Set remote description (the answer)
+            await peer.pc.setRemoteDescription({
+                type: 'answer',
+                sdp: answer.sdp
+            });
+            // Wait for data channel (answerer creates it, we receive it)
+            const channel = await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => reject(new Error('Timeout waiting for data channel')), 30000);
+                peer.on('datachannel', (ch) => {
+                    clearTimeout(timeout);
+                    resolve(ch);
+                });
+                // Also check if channel already exists
+                if (peer.pc.ondatachannel) {
+                    const existingHandler = peer.pc.ondatachannel;
+                    peer.pc.ondatachannel = (event) => {
+                        clearTimeout(timeout);
+                        resolve(event.channel);
+                        if (existingHandler)
+                            existingHandler.call(peer.pc, event);
+                    };
+                }
+                else {
+                    peer.pc.ondatachannel = (event) => {
+                        clearTimeout(timeout);
+                        resolve(event.channel);
+                    };
+                }
+            });
+            // Register connection
+            this.connections.set(connectionId, {
+                peer,
+                channel,
+                connectedAt: Date.now(),
+                offerId: answer.offerId
+            });
+            this.status.activeConnections++;
+            this.status.totalConnectionsHandled++;
+            // Setup cleanup on disconnect
+            peer.on('disconnected', () => {
+                this.connections.delete(connectionId);
+                this.status.activeConnections--;
+                this.updateStatus();
+            });
+            peer.on('failed', () => {
+                this.connections.delete(connectionId);
+                this.status.activeConnections--;
+                this.updateStatus();
+            });
+            // Update status
+            this.updateStatus();
+            // Invoke user handler (wrapped in try-catch)
+            try {
+                this.options.handler(channel, peer, connectionId);
+            }
+            catch (handlerError) {
+                this.handleError(handlerError, 'handler');
+            }
+        }
+        catch (error) {
+            this.handleError(error, 'connection-setup');
+        }
+    }
+    /**
+     * Create multiple offers
+     */
+    async createOffers(count) {
+        if (count <= 0) {
+            return [];
+        }
+        // Server supports max 10 offers per request
+        const batchSize = Math.min(count, 10);
+        const offers = [];
+        try {
+            // Create peer connections and generate offers
+            const offerRequests = [];
+            for (let i = 0; i < batchSize; i++) {
+                const pc = new RTCPeerConnection(this.options.rtcConfig || {
+                    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+                });
+                // Create data channel (required for offers)
+                pc.createDataChannel('rondevu-service');
+                // Create offer
+                const offer = await pc.createOffer();
+                await pc.setLocalDescription(offer);
+                if (!offer.sdp) {
+                    pc.close();
+                    throw new Error('Failed to generate SDP');
+                }
+                offerRequests.push({
+                    sdp: offer.sdp,
+                    topics: [], // V2 doesn't use topics
+                    ttl: this.options.ttl
+                });
+                // Close the PC immediately - we only needed the SDP
+                pc.close();
+            }
+            // Batch create offers
+            const createdOffers = await this.offersApi.create(offerRequests);
+            offers.push(...createdOffers);
+        }
+        catch (error) {
+            this.status.failedOfferCreations++;
+            this.handleError(error, 'offer-creation');
+            throw error;
+        }
+        return offers;
+    }
+    /**
+     * Publish the initial service (creates first offer)
+     */
+    async publishInitialService() {
+        const { username, privateKey, serviceFqn, rtcConfig, isPublic, metadata, ttl } = this.options;
+        // Create peer connection for initial offer
+        const pc = new RTCPeerConnection(rtcConfig || {
+            iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+        });
+        pc.createDataChannel('rondevu-service');
+        // Create offer
+        const offer = await pc.createOffer();
+        await pc.setLocalDescription(offer);
+        if (!offer.sdp) {
+            pc.close();
+            throw new Error('Failed to generate SDP');
+        }
+        // Create signature
+        const timestamp = Date.now();
+        const message = `publish:${username}:${serviceFqn}:${timestamp}`;
+        const signature = await this.usernameApi.signMessage(message, privateKey);
+        // Publish service
+        const response = await fetch(`${this.baseUrl}/services`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.credentials.peerId}:${this.credentials.secret}`
+            },
+            body: JSON.stringify({
+                username,
+                serviceFqn,
+                sdp: offer.sdp,
+                ttl,
+                isPublic,
+                metadata,
+                signature,
+                message
+            })
+        });
+        pc.close();
+        if (!response.ok) {
+            const error = await response.json();
+            throw new Error(error.error || 'Failed to publish service');
+        }
+        const data = await response.json();
+        return {
+            serviceId: data.serviceId,
+            uuid: data.uuid,
+            offerId: data.offerId,
+            expiresAt: data.expiresAt
+        };
+    }
+    /**
+     * Manually add offers to the pool
+     */
+    async manualRefill(count) {
+        if (!this.offerPool) {
+            throw new Error('Pool not started');
+        }
+        const offers = await this.createOffers(count);
+        await this.offerPool.addOffers(offers);
+        this.updateStatus();
+    }
+    /**
+     * Get current pool status
+     */
+    getStatus() {
+        return { ...this.status };
+    }
+    /**
+     * Update status and notify listeners
+     */
+    updateStatus() {
+        if (this.offerPool) {
+            this.status.activeOffers = this.offerPool.getActiveOfferCount();
+        }
+        if (this.options.onPoolStatus) {
+            this.options.onPoolStatus(this.getStatus());
+        }
+    }
+    /**
+     * Handle errors
+     */
+    handleError(error, context) {
+        if (this.options.onError) {
+            this.options.onError(error, context);
+        }
+        else {
+            console.error(`ServicePool error (${context}):`, error);
+        }
+    }
+    /**
+     * Generate a unique connection ID
+     */
+    generateConnectionId() {
+        return `conn-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+}

package/dist/services.d.ts

@@ -0,0 +1,79 @@
+import RondevuPeer from './peer/index.js';
+import { PooledServiceHandle, PoolStatus } from './service-pool.js';
+/**
+ * Service publish result
+ */
+export interface ServicePublishResult {
+    serviceId: string;
+    uuid: string;
+    offerId: string;
+    expiresAt: number;
+}
+/**
+ * Service publish options
+ */
+export interface PublishServiceOptions {
+    username: string;
+    privateKey: string;
+    serviceFqn: string;
+    rtcConfig?: RTCConfiguration;
+    isPublic?: boolean;
+    metadata?: Record<string, any>;
+    ttl?: number;
+    onConnection?: (peer: RondevuPeer) => void;
+}
+/**
+ * Service handle for managing an exposed service
+ */
+export interface ServiceHandle {
+    serviceId: string;
+    uuid: string;
+    offerId: string;
+    unpublish: () => Promise<void>;
+}
+/**
+ * Rondevu Services API
+ * Handles service publishing and management
+ */
+export declare class RondevuServices {
+    private baseUrl;
+    private credentials;
+    private usernameApi;
+    private offersApi;
+    constructor(baseUrl: string, credentials: {
+        peerId: string;
+        secret: string;
+    });
+    /**
+     * Publishes a service
+     */
+    publishService(options: PublishServiceOptions): Promise<ServicePublishResult>;
+    /**
+     * Unpublishes a service
+     */
+    unpublishService(serviceId: string, username: string): Promise<void>;
+    /**
+     * Exposes a service with an automatic connection handler
+     * This is a convenience method that publishes the service and manages connections
+     *
+     * Set poolSize > 1 to enable offer pooling for handling multiple concurrent connections
+     */
+    exposeService(options: Omit<PublishServiceOptions, 'onConnection'> & {
+        handler: (channel: RTCDataChannel, peer: RondevuPeer, connectionId?: string) => void;
+        poolSize?: number;
+        pollingInterval?: number;
+        onPoolStatus?: (status: PoolStatus) => void;
+        onError?: (error: Error, context: string) => void;
+    }): Promise<ServiceHandle | PooledServiceHandle>;
+    /**
+     * Validates service FQN format
+     */
+    private validateServiceFqn;
+    /**
+     * Parses a service FQN into name and version
+     */
+    parseServiceFqn(fqn: string): {
+        name: string;
+        version: string;
+    };
+}

package/dist/services.js

@@ -0,0 +1,206 @@
+import { RondevuUsername } from './usernames.js';
+import RondevuPeer from './peer/index.js';
+import { RondevuOffers } from './offers.js';
+import { ServicePool } from './service-pool.js';
+/**
+ * Rondevu Services API
+ * Handles service publishing and management
+ */
+export class RondevuServices {
+    constructor(baseUrl, credentials) {
+        this.baseUrl = baseUrl;
+        this.credentials = credentials;
+        this.usernameApi = new RondevuUsername(baseUrl);
+        this.offersApi = new RondevuOffers(baseUrl, credentials);
+    }
+    /**
+     * Publishes a service
+     */
+    async publishService(options) {
+        const { username, privateKey, serviceFqn, rtcConfig, isPublic = false, metadata, ttl } = options;
+        // Validate FQN format
+        this.validateServiceFqn(serviceFqn);
+        // Create WebRTC peer connection to generate offer
+        const pc = new RTCPeerConnection(rtcConfig || {
+            iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+        });
+        // Add a data channel (required for datachannel-based services)
+        pc.createDataChannel('rondevu-service');
+        // Create offer
+        const offer = await pc.createOffer();
+        await pc.setLocalDescription(offer);
+        if (!offer.sdp) {
+            throw new Error('Failed to generate SDP');
+        }
+        // Create signature for username verification
+        const timestamp = Date.now();
+        const message = `publish:${username}:${serviceFqn}:${timestamp}`;
+        const signature = await this.usernameApi.signMessage(message, privateKey);
+        // Publish service
+        const response = await fetch(`${this.baseUrl}/services`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.credentials.peerId}:${this.credentials.secret}`
+            },
+            body: JSON.stringify({
+                username,
+                serviceFqn,
+                sdp: offer.sdp,
+                ttl,
+                isPublic,
+                metadata,
+                signature,
+                message
+            })
+        });
+        if (!response.ok) {
+            const error = await response.json();
+            pc.close();
+            throw new Error(error.error || 'Failed to publish service');
+        }
+        const data = await response.json();
+        // Close the connection for now (would be kept open in a real implementation)
+        pc.close();
+        return {
+            serviceId: data.serviceId,
+            uuid: data.uuid,
+            offerId: data.offerId,
+            expiresAt: data.expiresAt
+        };
+    }
+    /**
+     * Unpublishes a service
+     */
+    async unpublishService(serviceId, username) {
+        const response = await fetch(`${this.baseUrl}/services/${serviceId}`, {
+            method: 'DELETE',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.credentials.peerId}:${this.credentials.secret}`
+            },
+            body: JSON.stringify({ username })
+        });
+        if (!response.ok) {
+            const error = await response.json();
+            throw new Error(error.error || 'Failed to unpublish service');
+        }
+    }
+    /**
+     * Exposes a service with an automatic connection handler
+     * This is a convenience method that publishes the service and manages connections
+     *
+     * Set poolSize > 1 to enable offer pooling for handling multiple concurrent connections
+     */
+    async exposeService(options) {
+        const { username, privateKey, serviceFqn, rtcConfig, isPublic, metadata, ttl, handler, poolSize, pollingInterval, onPoolStatus, onError } = options;
+        // If poolSize > 1, use pooled implementation
+        if (poolSize && poolSize > 1) {
+            const pool = new ServicePool(this.baseUrl, this.credentials, {
+                username,
+                privateKey,
+                serviceFqn,
+                rtcConfig,
+                isPublic,
+                metadata,
+                ttl,
+                handler: (channel, peer, connectionId) => handler(channel, peer, connectionId),
+                poolSize,
+                pollingInterval,
+                onPoolStatus,
+                onError
+            });
+            return await pool.start();
+        }
+        // Otherwise, use existing single-offer logic (UNCHANGED)
+        // Validate FQN
+        this.validateServiceFqn(serviceFqn);
+        // Create peer connection
+        const pc = new RTCPeerConnection(rtcConfig || {
+            iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+        });
+        // Create data channel
+        const channel = pc.createDataChannel('rondevu-service');
+        // Set up handler
+        channel.onopen = () => {
+            const peer = new RondevuPeer(this.offersApi, rtcConfig || {
+                iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+            });
+            handler(channel, peer);
+        };
+        // Create offer
+        const offer = await pc.createOffer();
+        await pc.setLocalDescription(offer);
+        if (!offer.sdp) {
+            pc.close();
+            throw new Error('Failed to generate SDP');
+        }
+        // Create signature
+        const timestamp = Date.now();
+        const message = `publish:${username}:${serviceFqn}:${timestamp}`;
+        const signature = await this.usernameApi.signMessage(message, privateKey);
+        // Publish service
+        const response = await fetch(`${this.baseUrl}/services`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.credentials.peerId}:${this.credentials.secret}`
+            },
+            body: JSON.stringify({
+                username,
+                serviceFqn,
+                sdp: offer.sdp,
+                ttl,
+                isPublic,
+                metadata,
+                signature,
+                message
+            })
+        });
+        if (!response.ok) {
+            const error = await response.json();
+            pc.close();
+            throw new Error(error.error || 'Failed to expose service');
+        }
+        const data = await response.json();
+        return {
+            serviceId: data.serviceId,
+            uuid: data.uuid,
+            offerId: data.offerId,
+            unpublish: () => this.unpublishService(data.serviceId, username)
+        };
+    }
+    /**
+     * Validates service FQN format
+     */
+    validateServiceFqn(fqn) {
+        const parts = fqn.split('@');
+        if (parts.length !== 2) {
+            throw new Error('Service FQN must be in format: service-name@version');
+        }
+        const [serviceName, version] = parts;
+        // Validate service name (reverse domain notation)
+        const serviceNameRegex = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+        if (!serviceNameRegex.test(serviceName)) {
+            throw new Error('Service name must be reverse domain notation (e.g., com.example.service)');
+        }
+        if (serviceName.length < 3 || serviceName.length > 128) {
+            throw new Error('Service name must be 3-128 characters');
+        }
+        // Validate version (semantic versioning)
+        const versionRegex = /^[0-9]+\.[0-9]+\.[0-9]+(-[a-z0-9.-]+)?$/;
+        if (!versionRegex.test(version)) {
+            throw new Error('Version must be semantic versioning (e.g., 1.0.0, 2.1.3-beta)');
+        }
+    }
+    /**
+     * Parses a service FQN into name and version
+     */
+    parseServiceFqn(fqn) {
+        const parts = fqn.split('@');
+        if (parts.length !== 2) {
+            throw new Error('Invalid FQN format');
+        }
+        return { name: parts[0], version: parts[1] };
+    }
+}

package/dist/usernames.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Username claim result
+ */
+export interface UsernameClaimResult {
+    username: string;
+    publicKey: string;
+    privateKey: string;
+    claimedAt: number;
+    expiresAt: number;
+}
+/**
+ * Username availability check result
+ */
+export interface UsernameCheckResult {
+    username: string;
+    available: boolean;
+    claimedAt?: number;
+    expiresAt?: number;
+    publicKey?: string;
+}
+/**
+ * Rondevu Username API
+ * Handles username claiming with Ed25519 cryptographic proof
+ */
+export declare class RondevuUsername {
+    private baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Generates an Ed25519 keypair for username claiming
+     */
+    generateKeypair(): Promise<{
+        publicKey: string;
+        privateKey: string;
+    }>;
+    /**
+     * Signs a message with an Ed25519 private key
+     */
+    signMessage(message: string, privateKeyBase64: string): Promise<string>;
+    /**
+     * Claims a username
+     * Generates a new keypair if one is not provided
+     */
+    claimUsername(username: string, existingKeypair?: {
+        publicKey: string;
+        privateKey: string;
+    }): Promise<UsernameClaimResult>;
+    /**
+     * Checks if a username is available
+     */
+    checkUsername(username: string): Promise<UsernameCheckResult>;
+    /**
+     * Helper: Save keypair to localStorage
+     * WARNING: This stores the private key in localStorage which is not the most secure
+     * For production use, consider using IndexedDB with encryption or hardware security modules
+     */
+    saveKeypairToStorage(username: string, publicKey: string, privateKey: string): void;
+    /**
+     * Helper: Load keypair from localStorage
+     */
+    loadKeypairFromStorage(username: string): {
+        publicKey: string;
+        privateKey: string;
+    } | null;
+    /**
+     * Helper: Delete keypair from localStorage
+     */
+    deleteKeypairFromStorage(username: string): void;
+    /**
+     * Export keypair as JSON string (for backup)
+     */
+    exportKeypair(publicKey: string, privateKey: string): string;
+    /**
+     * Import keypair from JSON string
+     */
+    importKeypair(json: string): {
+        publicKey: string;
+        privateKey: string;
+    };
+}