@ruvector/edge-net 0.4.2 → 0.4.3

package/webrtc.js

@@ -12,48 +12,152 @@
  * - Connection quality monitoring
  * - Automatic reconnection
  * - QDAG synchronization over data channels
+ * - Configurable TURN/STUN via environment variables
+ * - ICE connection diagnostics
  */
 
 import { EventEmitter } from 'events';
 import { createHash, randomBytes } from 'crypto';
 
-// WebRTC Configuration
-export const WEBRTC_CONFIG = {
-    iceServers: [
-        // STUN servers (free, for NAT discovery)
+/**
+ * Environment variable configuration for ICE servers
+ *
+ * Environment Variables:
+ * - EDGE_NET_STUN_SERVERS: Comma-separated STUN server URLs
+ * - EDGE_NET_TURN_URL: TURN server URL
+ * - EDGE_NET_TURN_USERNAME: TURN username
+ * - EDGE_NET_TURN_CREDENTIAL: TURN password/credential
+ * - EDGE_NET_TURN_URL_TCP: TURN server URL for TCP transport
+ * - EDGE_NET_ICE_TRANSPORT_POLICY: 'all' or 'relay' (force TURN)
+ * - EDGE_NET_SIGNALING_SERVERS: Comma-separated signaling server URLs
+ */
+
+// Get environment safely (works in Node.js, browser with bundler support)
+const getEnv = (key, defaultValue = '') => {
+    if (typeof process !== 'undefined' && process.env) {
+        return process.env[key] || defaultValue;
+    }
+    if (typeof globalThis !== 'undefined' && globalThis.__EDGE_NET_ENV__) {
+        return globalThis.__EDGE_NET_ENV__[key] || defaultValue;
+    }
+    return defaultValue;
+};
+
+/**
+ * Parse STUN servers from environment or use defaults
+ */
+function getStunServers() {
+    const envStun = getEnv('EDGE_NET_STUN_SERVERS');
+    if (envStun) {
+        return envStun.split(',').map(url => ({ urls: url.trim() }));
+    }
+    // Default STUN servers (free, reliable)
+    return [
         { urls: 'stun:stun.l.google.com:19302' },
         { urls: 'stun:stun1.l.google.com:19302' },
+        { urls: 'stun:stun2.l.google.com:19302' },
         { urls: 'stun:stun.cloudflare.com:3478' },
         { urls: 'stun:stun.services.mozilla.com:3478' },
-        // Free TURN servers for NAT traversal (relay)
-        {
-            urls: 'turn:openrelay.metered.ca:80',
-            username: 'openrelayproject',
-            credential: 'openrelayproject',
-        },
-        {
-            urls: 'turn:openrelay.metered.ca:443',
-            username: 'openrelayproject',
-            credential: 'openrelayproject',
-        },
-        {
-            urls: 'turn:openrelay.metered.ca:443?transport=tcp',
-            username: 'openrelayproject',
-            credential: 'openrelayproject',
-        },
-        // Alternative free TURN
-        {
-            urls: 'turn:relay.metered.ca:80',
-            username: 'e8a437a4c4d4e5f6a7b8c9d0',
-            credential: 'freePublicTurnServer',
-        },
-    ],
-    // Signaling server endpoints (priority order)
-    signalingServers: [
+        { urls: 'stun:stun.stunprotocol.org:3478' },
+    ];
+}
+
+/**
+ * Parse TURN servers from environment or use defaults
+ */
+function getTurnServers() {
+    const turnUrl = getEnv('EDGE_NET_TURN_URL');
+    const turnUsername = getEnv('EDGE_NET_TURN_USERNAME');
+    const turnCredential = getEnv('EDGE_NET_TURN_CREDENTIAL');
+    const turnUrlTcp = getEnv('EDGE_NET_TURN_URL_TCP');
+
+    const servers = [];
+
+    // Custom TURN from environment
+    if (turnUrl && turnUsername && turnCredential) {
+        servers.push({
+            urls: turnUrl,
+            username: turnUsername,
+            credential: turnCredential,
+        });
+
+        // Add TCP transport variant if specified
+        if (turnUrlTcp) {
+            servers.push({
+                urls: turnUrlTcp,
+                username: turnUsername,
+                credential: turnCredential,
+            });
+        }
+    }
+
+    // Add default free TURN servers if no custom ones
+    if (servers.length === 0) {
+        servers.push(
+            // Metered.ca free tier (limited bandwidth, good for testing)
+            {
+                urls: 'turn:openrelay.metered.ca:80',
+                username: 'openrelayproject',
+                credential: 'openrelayproject',
+            },
+            {
+                urls: 'turn:openrelay.metered.ca:443',
+                username: 'openrelayproject',
+                credential: 'openrelayproject',
+            },
+            {
+                urls: 'turn:openrelay.metered.ca:443?transport=tcp',
+                username: 'openrelayproject',
+                credential: 'openrelayproject',
+            },
+            // Alternative relay
+            {
+                urls: 'turn:relay.metered.ca:80',
+                username: 'e8a437a4c4d4e5f6a7b8c9d0',
+                credential: 'freePublicTurnServer',
+            }
+        );
+    }
+
+    return servers;
+}
+
+/**
+ * Get signaling servers from environment or use defaults
+ */
+function getSignalingServers() {
+    const envSignaling = getEnv('EDGE_NET_SIGNALING_SERVERS');
+    if (envSignaling) {
+        return envSignaling.split(',').map(url => url.trim());
+    }
+    return [
         'ws://localhost:8787',                    // Local signaling server first
         'ws://127.0.0.1:8787',                    // Local alternative
         'wss://edge-net-signal.ruvector.dev',    // Production (when deployed)
-    ],
+    ];
+}
+
+/**
+ * Build complete ICE configuration
+ */
+function buildIceConfig() {
+    const iceTransportPolicy = getEnv('EDGE_NET_ICE_TRANSPORT_POLICY', 'all');
+
+    return {
+        iceServers: [...getStunServers(), ...getTurnServers()],
+        iceTransportPolicy, // 'all' = STUN+TURN, 'relay' = TURN only
+        iceCandidatePoolSize: 10, // Pre-gather candidates for faster connection
+        bundlePolicy: 'max-bundle',
+        rtcpMuxPolicy: 'require',
+    };
+}
+
+// WebRTC Configuration
+export const WEBRTC_CONFIG = {
+    // Dynamic ICE configuration
+    ...buildIceConfig(),
+    // Signaling server endpoints (priority order)
+    signalingServers: getSignalingServers(),
     // Fallback to local DHT if no signaling available
     fallbackToSimulation: false,
     fallbackToDHT: true,
@@ -78,6 +182,91 @@ export const WEBRTC_CONFIG = {
     },
 };
 
+/**
+ * ICE Server Providers Configuration
+ *
+ * Popular TURN/STUN providers with their configuration patterns.
+ * Use these as reference for configuring your production environment.
+ */
+export const ICE_PROVIDERS = {
+    // Self-hosted coturn (recommended for production)
+    coturn: {
+        name: 'Self-hosted coturn',
+        config: (host, username, credential) => ([
+            { urls: `stun:${host}:3478` },
+            { urls: `turn:${host}:3478`, username, credential },
+            { urls: `turn:${host}:3478?transport=tcp`, username, credential },
+            { urls: `turns:${host}:5349`, username, credential }, // TLS
+        ]),
+        docs: 'https://github.com/coturn/coturn',
+    },
+
+    // Metered.ca (free tier available)
+    metered: {
+        name: 'Metered TURN',
+        config: (apiKey) => ([
+            { urls: 'stun:stun.relay.metered.ca:80' },
+            {
+                urls: 'turn:a.relay.metered.ca:80',
+                username: apiKey,
+                credential: apiKey,
+            },
+            {
+                urls: 'turn:a.relay.metered.ca:443',
+                username: apiKey,
+                credential: apiKey,
+            },
+            {
+                urls: 'turn:a.relay.metered.ca:443?transport=tcp',
+                username: apiKey,
+                credential: apiKey,
+            },
+        ]),
+        pricing: 'Free: 500MB/month, Paid: from $0.40/GB',
+        docs: 'https://www.metered.ca/stun-turn',
+    },
+
+    // Twilio (pay-as-you-go)
+    twilio: {
+        name: 'Twilio Network Traversal',
+        // Note: Twilio requires fetching ephemeral credentials via API
+        config: (username, credential) => ([
+            { urls: 'stun:global.stun.twilio.com:3478' },
+            {
+                urls: 'turn:global.turn.twilio.com:3478?transport=udp',
+                username,
+                credential,
+            },
+            {
+                urls: 'turn:global.turn.twilio.com:3478?transport=tcp',
+                username,
+                credential,
+            },
+            {
+                urls: 'turn:global.turn.twilio.com:443?transport=tcp',
+                username,
+                credential,
+            },
+        ]),
+        pricing: '$0.40/GB',
+        docs: 'https://www.twilio.com/docs/stun-turn',
+    },
+
+    // Xirsys (global coverage)
+    xirsys: {
+        name: 'Xirsys',
+        config: (username, credential, domain) => ([
+            { urls: `stun:${domain}:3478` },
+            { urls: `turn:${domain}:80?transport=udp`, username, credential },
+            { urls: `turn:${domain}:3478?transport=udp`, username, credential },
+            { urls: `turn:${domain}:80?transport=tcp`, username, credential },
+            { urls: `turn:${domain}:3478?transport=tcp`, username, credential },
+        ]),
+        pricing: 'Free: 500MB/month, Paid: from $24.99/month',
+        docs: 'https://xirsys.com/',
+    },
+};
+
 /**
  * WebRTC Peer Connection Manager
  *
@@ -104,6 +293,9 @@ export class WebRTCPeerConnection extends EventEmitter {
             latency: [],
             connectionTime: null,
         };
+        // WebRTC classes (set during initialize for Node.js compatibility)
+        this._RTCSessionDescription = null;
+        this._RTCIceCandidate = null;
     }
 
     /**
@@ -111,13 +303,18 @@ export class WebRTCPeerConnection extends EventEmitter {
      */
     async initialize() {
         // Use wrtc for Node.js or native WebRTC in browser
-        const RTCPeerConnection = globalThis.RTCPeerConnection ||
-            (await this.loadNodeWebRTC());
+        const webrtcClasses = await this.loadWebRTCClasses();
 
-        if (!RTCPeerConnection) {
+        if (!webrtcClasses) {
             throw new Error('WebRTC not available');
         }
 
+        const { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } = webrtcClasses;
+
+        // Store classes for later use in handleOffer/handleAnswer/addIceCandidate
+        this._RTCSessionDescription = RTCSessionDescription;
+        this._RTCIceCandidate = RTCIceCandidate;
+
         this.pc = new RTCPeerConnection({
             iceServers: WEBRTC_CONFIG.iceServers,
         });
@@ -132,15 +329,31 @@ export class WebRTCPeerConnection extends EventEmitter {
     }
 
     /**
-     * Load wrtc for Node.js environment
+     * Load WebRTC classes (from browser globals or wrtc package)
      */
-    async loadNodeWebRTC() {
+    async loadWebRTCClasses() {
+        // Check for browser globals first
+        if (globalThis.RTCPeerConnection) {
+            return {
+                RTCPeerConnection: globalThis.RTCPeerConnection,
+                RTCSessionDescription: globalThis.RTCSessionDescription,
+                RTCIceCandidate: globalThis.RTCIceCandidate,
+            };
+        }
+
+        // Try to load wrtc for Node.js
         try {
-            const wrtc = await import('wrtc');
-            return wrtc.RTCPeerConnection;
+            const wrtcModule = await import('wrtc');
+            // wrtc exports everything under default in ESM
+            const wrtc = wrtcModule.default || wrtcModule;
+            return {
+                RTCPeerConnection: wrtc.RTCPeerConnection,
+                RTCSessionDescription: wrtc.RTCSessionDescription,
+                RTCIceCandidate: wrtc.RTCIceCandidate,
+            };
         } catch (err) {
-            // wrtc not available, will use simulation
-            console.warn('WebRTC not available in Node.js, using simulation');
+            // wrtc not available
+            console.warn('WebRTC not available in Node.js:', err.message);
             return null;
         }
     }
@@ -234,6 +447,10 @@ export class WebRTCPeerConnection extends EventEmitter {
      * Handle incoming offer and create answer
      */
     async handleOffer(offer) {
+        // Create RTCSessionDescription using stored class reference
+        const RTCSessionDescription = this._RTCSessionDescription || globalThis.RTCSessionDescription;
+        const RTCIceCandidate = this._RTCIceCandidate || globalThis.RTCIceCandidate;
+
         await this.pc.setRemoteDescription(new RTCSessionDescription(offer));
 
         // Process any pending ICE candidates
@@ -251,6 +468,10 @@ export class WebRTCPeerConnection extends EventEmitter {
      * Handle incoming answer
      */
     async handleAnswer(answer) {
+        // Create RTCSessionDescription using stored class reference
+        const RTCSessionDescription = this._RTCSessionDescription || globalThis.RTCSessionDescription;
+        const RTCIceCandidate = this._RTCIceCandidate || globalThis.RTCIceCandidate;
+
         await this.pc.setRemoteDescription(new RTCSessionDescription(answer));
 
         // Process any pending ICE candidates
@@ -264,6 +485,8 @@ export class WebRTCPeerConnection extends EventEmitter {
      * Add ICE candidate
      */
     async addIceCandidate(candidate) {
+        const RTCIceCandidate = this._RTCIceCandidate || globalThis.RTCIceCandidate;
+
         if (this.pc.remoteDescription) {
             await this.pc.addIceCandidate(new RTCIceCandidate(candidate));
         } else {
@@ -772,7 +995,8 @@ export class WebRTCPeerManager extends EventEmitter {
      * Setup event handlers for a peer connection
      */
     setupPeerHandlers(peerConnection) {
-        peerConnection.on('ice-candidate', ({ candidate }) => {
+        peerConnection.on('ice-candidate', async ({ candidate }) => {
+            // Forward ICE candidate via available signaling method
             if (this.signalingSocket?.readyState === 1) {
                 this.signalingSocket.send(JSON.stringify({
                     type: 'ice-candidate',
@@ -780,6 +1004,13 @@ export class WebRTCPeerManager extends EventEmitter {
                     from: this.localIdentity.piKey,
                     candidate,
                 }));
+            } else if (this.externalSignaling) {
+                // Use external signaling (Firebase, etc.)
+                try {
+                    await this.externalSignaling('ice-candidate', peerConnection.peerId, candidate);
+                } catch (err) {
+                    console.warn('Failed to send ICE candidate via external signaling:', err.message);
+                }
             }
         });
 
@@ -1011,10 +1242,432 @@ export class QDAGSynchronizer extends EventEmitter {
     }
 }
 
+/**
+ * ICE Connection Diagnostics
+ *
+ * Provides comprehensive diagnostics for ICE connectivity issues,
+ * helping identify NAT types, test STUN/TURN servers, and diagnose
+ * connection failures.
+ */
+export class ICEDiagnostics extends EventEmitter {
+    constructor(options = {}) {
+        super();
+        this.options = {
+            timeout: options.timeout || 10000,
+            iceServers: options.iceServers || WEBRTC_CONFIG.iceServers,
+            verbose: options.verbose || false,
+        };
+        this.results = {
+            startTime: null,
+            endTime: null,
+            natType: 'unknown',
+            stunResults: [],
+            turnResults: [],
+            candidateTypes: [],
+            errors: [],
+            recommendations: [],
+        };
+    }
+
+    /**
+     * Run full ICE diagnostics suite
+     */
+    async runDiagnostics() {
+        this.results.startTime = Date.now();
+        this.log('Starting ICE diagnostics...');
+
+        try {
+            // Test STUN servers
+            await this.testStunServers();
+
+            // Test TURN servers
+            await this.testTurnServers();
+
+            // Determine NAT type
+            this.determineNatType();
+
+            // Generate recommendations
+            this.generateRecommendations();
+
+        } catch (err) {
+            this.results.errors.push({
+                phase: 'diagnostics',
+                error: err.message,
+            });
+        }
+
+        this.results.endTime = Date.now();
+        this.results.duration = this.results.endTime - this.results.startTime;
+
+        return this.results;
+    }
+
+    /**
+     * Test STUN servers for reachability
+     */
+    async testStunServers() {
+        const stunServers = this.options.iceServers.filter(
+            server => server.urls && server.urls.startsWith('stun:')
+        );
+
+        this.log(`Testing ${stunServers.length} STUN servers...`);
+
+        for (const server of stunServers) {
+            const result = await this.testIceServer(server, 'stun');
+            this.results.stunResults.push(result);
+            this.emit('stun-result', result);
+        }
+    }
+
+    /**
+     * Test TURN servers for reachability and authentication
+     */
+    async testTurnServers() {
+        const turnServers = this.options.iceServers.filter(
+            server => server.urls && (
+                server.urls.startsWith('turn:') ||
+                server.urls.startsWith('turns:')
+            )
+        );
+
+        this.log(`Testing ${turnServers.length} TURN servers...`);
+
+        for (const server of turnServers) {
+            const result = await this.testIceServer(server, 'turn');
+            this.results.turnResults.push(result);
+            this.emit('turn-result', result);
+        }
+    }
+
+    /**
+     * Test a single ICE server
+     */
+    async testIceServer(server, type) {
+        const startTime = Date.now();
+        const result = {
+            url: server.urls,
+            type,
+            success: false,
+            latency: null,
+            candidateType: null,
+            error: null,
+        };
+
+        try {
+            // Get RTCPeerConnection
+            const RTCPeerConnection = globalThis.RTCPeerConnection ||
+                (await this.loadNodeWebRTC());
+
+            if (!RTCPeerConnection) {
+                result.error = 'WebRTC not available';
+                return result;
+            }
+
+            const pc = new RTCPeerConnection({
+                iceServers: [server],
+                iceTransportPolicy: type === 'turn' ? 'relay' : 'all',
+            });
+
+            const candidatePromise = new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    reject(new Error('ICE gathering timeout'));
+                }, this.options.timeout);
+
+                pc.onicecandidate = (event) => {
+                    if (event.candidate) {
+                        clearTimeout(timeout);
+                        resolve(event.candidate);
+                    }
+                };
+
+                pc.onicegatheringstatechange = () => {
+                    if (pc.iceGatheringState === 'complete') {
+                        clearTimeout(timeout);
+                        reject(new Error('No candidates gathered'));
+                    }
+                };
+            });
+
+            // Create data channel to trigger ICE gathering
+            pc.createDataChannel('test');
+
+            // Create offer
+            const offer = await pc.createOffer();
+            await pc.setLocalDescription(offer);
+
+            // Wait for candidate
+            const candidate = await candidatePromise;
+
+            result.success = true;
+            result.latency = Date.now() - startTime;
+            result.candidateType = candidate.type;
+            result.candidate = {
+                type: candidate.type,
+                protocol: candidate.protocol,
+                address: candidate.address,
+                port: candidate.port,
+            };
+
+            // Track candidate types
+            if (!this.results.candidateTypes.includes(candidate.type)) {
+                this.results.candidateTypes.push(candidate.type);
+            }
+
+            pc.close();
+
+        } catch (err) {
+            result.error = err.message;
+            result.latency = Date.now() - startTime;
+        }
+
+        this.log(`  ${type.toUpperCase()} ${server.urls}: ${result.success ? 'OK' : 'FAILED'} (${result.latency}ms)`);
+        return result;
+    }
+
+    /**
+     * Load wrtc for Node.js environment
+     */
+    async loadNodeWebRTC() {
+        try {
+            const wrtc = await import('wrtc');
+            return wrtc.RTCPeerConnection;
+        } catch (err) {
+            return null;
+        }
+    }
+
+    /**
+     * Determine NAT type based on gathered candidates
+     */
+    determineNatType() {
+        const hasHost = this.results.candidateTypes.includes('host');
+        const hasSrflx = this.results.candidateTypes.includes('srflx');
+        const hasRelay = this.results.candidateTypes.includes('relay');
+
+        if (hasHost && hasSrflx) {
+            // Can get server reflexive = not symmetric NAT
+            const stunSuccess = this.results.stunResults.filter(r => r.success).length;
+            if (stunSuccess >= 2) {
+                this.results.natType = 'full-cone';
+            } else {
+                this.results.natType = 'restricted-cone';
+            }
+        } else if (hasHost && !hasSrflx && hasRelay) {
+            // Can only get relay = symmetric NAT
+            this.results.natType = 'symmetric';
+        } else if (hasHost && !hasSrflx && !hasRelay) {
+            // No external connectivity
+            this.results.natType = 'blocked';
+        } else if (!hasHost) {
+            // No host candidates = unusual configuration
+            this.results.natType = 'unknown';
+        }
+
+        this.log(`NAT Type detected: ${this.results.natType}`);
+    }
+
+    /**
+     * Generate recommendations based on diagnostics
+     */
+    generateRecommendations() {
+        const recs = [];
+
+        // Check STUN connectivity
+        const stunSuccess = this.results.stunResults.filter(r => r.success).length;
+        const stunTotal = this.results.stunResults.length;
+
+        if (stunSuccess === 0) {
+            recs.push({
+                severity: 'error',
+                message: 'No STUN servers reachable',
+                action: 'Check firewall rules for UDP port 3478',
+            });
+        } else if (stunSuccess < stunTotal / 2) {
+            recs.push({
+                severity: 'warning',
+                message: `Only ${stunSuccess}/${stunTotal} STUN servers reachable`,
+                action: 'Some STUN servers may be blocked or unreliable',
+            });
+        }
+
+        // Check TURN connectivity
+        const turnSuccess = this.results.turnResults.filter(r => r.success).length;
+        const turnTotal = this.results.turnResults.length;
+
+        if (this.results.natType === 'symmetric' && turnSuccess === 0) {
+            recs.push({
+                severity: 'error',
+                message: 'Symmetric NAT detected but no TURN servers available',
+                action: 'Configure a TURN server for reliable connectivity',
+            });
+        } else if (turnSuccess === 0 && turnTotal > 0) {
+            recs.push({
+                severity: 'warning',
+                message: 'No TURN servers reachable',
+                action: 'Check TURN credentials and firewall rules',
+            });
+        }
+
+        // NAT-specific recommendations
+        if (this.results.natType === 'symmetric') {
+            recs.push({
+                severity: 'info',
+                message: 'Symmetric NAT detected',
+                action: 'TURN server is required for reliable P2P connections',
+            });
+        }
+
+        if (this.results.natType === 'blocked') {
+            recs.push({
+                severity: 'error',
+                message: 'Network appears to block WebRTC',
+                action: 'Configure TURN over TCP/443 or use a WebSocket fallback',
+            });
+        }
+
+        // Performance recommendations
+        const avgLatency = this.calculateAverageLatency();
+        if (avgLatency > 200) {
+            recs.push({
+                severity: 'warning',
+                message: `High ICE latency (${avgLatency}ms average)`,
+                action: 'Consider using geographically closer STUN/TURN servers',
+            });
+        }
+
+        this.results.recommendations = recs;
+    }
+
+    /**
+     * Calculate average latency across all tests
+     */
+    calculateAverageLatency() {
+        const allResults = [
+            ...this.results.stunResults,
+            ...this.results.turnResults,
+        ].filter(r => r.success && r.latency);
+
+        if (allResults.length === 0) return 0;
+
+        const total = allResults.reduce((sum, r) => sum + r.latency, 0);
+        return Math.round(total / allResults.length);
+    }
+
+    /**
+     * Get a summary report
+     */
+    getSummary() {
+        const stunOk = this.results.stunResults.filter(r => r.success).length;
+        const turnOk = this.results.turnResults.filter(r => r.success).length;
+
+        return {
+            status: this.getOverallStatus(),
+            natType: this.results.natType,
+            stunServers: `${stunOk}/${this.results.stunResults.length} reachable`,
+            turnServers: `${turnOk}/${this.results.turnResults.length} reachable`,
+            avgLatency: `${this.calculateAverageLatency()}ms`,
+            candidateTypes: this.results.candidateTypes,
+            recommendations: this.results.recommendations.length,
+            duration: `${this.results.duration}ms`,
+        };
+    }
+
+    /**
+     * Determine overall connectivity status
+     */
+    getOverallStatus() {
+        const stunOk = this.results.stunResults.some(r => r.success);
+        const turnOk = this.results.turnResults.some(r => r.success);
+        const hasErrors = this.results.recommendations.some(r => r.severity === 'error');
+
+        if (hasErrors) return 'error';
+        if (stunOk && turnOk) return 'good';
+        if (stunOk || turnOk) return 'degraded';
+        return 'failed';
+    }
+
+    /**
+     * Format results as readable string
+     */
+    formatReport() {
+        const summary = this.getSummary();
+        const lines = [
+            '================================================================',
+            '            ICE CONNECTION DIAGNOSTICS REPORT                   ',
+            '================================================================',
+            `  Status:         ${summary.status.toUpperCase()}`,
+            `  NAT Type:       ${summary.natType}`,
+            `  STUN Servers:   ${summary.stunServers}`,
+            `  TURN Servers:   ${summary.turnServers}`,
+            `  Avg Latency:    ${summary.avgLatency}`,
+            `  Candidates:     ${summary.candidateTypes.join(', ') || 'none'}`,
+            '----------------------------------------------------------------',
+        ];
+
+        if (this.results.recommendations.length > 0) {
+            lines.push('  RECOMMENDATIONS:');
+            for (const rec of this.results.recommendations) {
+                const icon = rec.severity === 'error' ? '[!]' :
+                            rec.severity === 'warning' ? '[W]' : '[i]';
+                lines.push(`  ${icon} ${rec.message}`);
+                lines.push(`      -> ${rec.action}`);
+            }
+        }
+
+        lines.push('================================================================');
+
+        return lines.join('\n');
+    }
+
+    log(message) {
+        if (this.options.verbose) {
+            console.log(`[ICE] ${message}`);
+        }
+        this.emit('log', message);
+    }
+}
+
+/**
+ * Quick ICE connectivity test
+ *
+ * Usage:
+ *   import { testIceConnectivity } from './webrtc.js';
+ *   const result = await testIceConnectivity();
+ *   console.log(result.formatReport());
+ */
+export async function testIceConnectivity(options = {}) {
+    const diagnostics = new ICEDiagnostics({
+        verbose: true,
+        ...options,
+    });
+    await diagnostics.runDiagnostics();
+    return diagnostics;
+}
+
+/**
+ * Create custom ICE configuration for specific provider
+ *
+ * Usage:
+ *   import { createIceConfig, ICE_PROVIDERS } from './webrtc.js';
+ *   const config = createIceConfig('coturn', 'turn.example.com', 'user', 'pass');
+ */
+export function createIceConfig(provider, ...args) {
+    if (!ICE_PROVIDERS[provider]) {
+        throw new Error(`Unknown ICE provider: ${provider}. Available: ${Object.keys(ICE_PROVIDERS).join(', ')}`);
+    }
+    return {
+        iceServers: ICE_PROVIDERS[provider].config(...args),
+    };
+}
+
 // Export default configuration for testing
 export default {
     WebRTCPeerConnection,
     WebRTCPeerManager,
     QDAGSynchronizer,
+    ICEDiagnostics,
     WEBRTC_CONFIG,
+    ICE_PROVIDERS,
+    testIceConnectivity,
+    createIceConfig,
 };