@marianmeres/webrtc 1.1.0 → 1.2.0

package/API.md

@@ -759,6 +759,9 @@ interface WebRtcManagerConfig {
   /** Initial reconnection delay in ms (doubles each attempt). Default: 1000 */
   reconnectDelay?: number;
 
+  /** Timeout in ms for full reconnection to reach connected state. Default: 30000 */
+  fullReconnectTimeout?: number;
+
   /** Callback to control whether reconnection should proceed */
   shouldReconnect?: (context: {
     attempt: number;
@@ -942,19 +945,24 @@ When `autoReconnect: true`:
 2. **Attempts 3+:** Full reconnection (new peer connection)
 3. **Backoff:** `reconnectDelay * 2^(attempt-1)` milliseconds
 
-For "full" strategy reconnections, listen for the `reconnecting` event and re-perform signaling:
+#### Full Reconnection and Signaling
+
+**Important:** For "full" strategy reconnections, the manager creates a new peer connection but **cannot automatically complete the signaling handshake**. You must listen for the `reconnecting` event and re-perform signaling when `strategy === 'full'`:
 
 ```typescript
-manager.on('reconnecting', ({ attempt, strategy }) => {
+manager.on('reconnecting', async ({ attempt, strategy }) => {
   if (strategy === 'full') {
     // Re-do offer/answer exchange
     const offer = await manager.createOffer();
     await manager.setLocalDescription(offer);
     sendToRemote(offer);
   }
+  // For 'ice-restart', the manager handles it automatically
 });
 ```
 
+If the connection doesn't reach `CONNECTED` state within `fullReconnectTimeout` (default: 30 seconds), it's treated as a failed attempt and the next reconnection attempt begins. When all attempts are exhausted, `EVENT_RECONNECT_FAILED` is emitted.
+
 ### Conditional Reconnection
 
 Use the `shouldReconnect` callback to suppress reconnection when the peer disconnected intentionally:

package/README.md

@@ -51,6 +51,7 @@ const manager = new WebRtcManager(factory, config);
 - `autoReconnect`: Enable automatic reconnection (default: false)
 - `maxReconnectAttempts`: Max reconnection attempts (default: 5)
 - `reconnectDelay`: Initial reconnection delay in ms (default: 1000)
+- `fullReconnectTimeout`: Timeout in ms for full reconnection to succeed (default: 30000)
 - `shouldReconnect`: Callback to control whether reconnection should proceed (see below)
 - `debug`: Enable debug logging (default: false)
 - `logger`: Custom logger instance implementing `Logger` interface (default: console)
@@ -161,6 +162,39 @@ The callback receives:
 - `maxAttempts`: Configured maximum attempts
 - `strategy`: `"ice-restart"` (attempts 1-2) or `"full"` (attempts 3+)
 
+### Reconnection Strategies
+
+The manager uses two reconnection strategies with exponential backoff:
+
+1. **ICE Restart** (attempts 1-2): Lightweight reconnection that keeps the existing peer connection and restarts ICE negotiation. Works when the network path changed but the remote peer is still available.
+
+2. **Full Reconnection** (attempts 3+): Creates a completely new peer connection. This is necessary when ICE restart fails, but **requires consumer action** to complete the signaling handshake.
+
+#### Handling Full Reconnection
+
+When a full reconnection is triggered, the manager will:
+1. Clean up the old peer connection
+2. Create a new peer connection
+3. Emit `EVENT_RECONNECTING` with `strategy: 'full'`
+
+**Important:** The manager cannot automatically complete the signaling handshake for full reconnections. You must listen for the `reconnecting` event and re-establish signaling when the strategy is `'full'`:
+
+```typescript
+manager.on(WebRtcManager.EVENT_RECONNECTING, async ({ attempt, strategy }) => {
+  console.log(`Reconnecting (attempt ${attempt}, strategy: ${strategy})`);
+
+  if (strategy === 'full') {
+    // Re-do the signaling handshake
+    const offer = await manager.createOffer();
+    await manager.setLocalDescription(offer);
+    signalingChannel.send({ type: 'offer', offer });
+  }
+  // For 'ice-restart', the manager handles it automatically
+});
+```
+
+If the full reconnection doesn't reach `CONNECTED` state within `fullReconnectTimeout` (default: 30 seconds), it's treated as a failed attempt and the next reconnection attempt begins (or `EVENT_RECONNECT_FAILED` is emitted if max attempts reached).
+
 ## Examples
 
 ### Basic Usage (Vanilla JavaScript)

package/dist/types.d.ts

@@ -26,6 +26,8 @@ export interface WebRtcManagerConfig {
     maxReconnectAttempts?: number;
     /** Initial reconnection delay in ms. Doubles with each attempt. Defaults to 1000. */
     reconnectDelay?: number;
+    /** Timeout in ms for full reconnection strategy to reach connected state. Defaults to 30000. */
+    fullReconnectTimeout?: number;
     /**
      * Callback to determine whether reconnection should be attempted.
      * Called before each reconnection attempt when autoReconnect is enabled.

package/dist/webrtc-manager.js

@@ -89,6 +89,7 @@ export class WebRtcManager {
     #dataChannels = new Map();
     #reconnectAttempts = 0;
     #reconnectTimer = null;
+    #fullReconnectTimeoutTimer = null;
     #deviceChangeHandler = null;
     /**
      * Creates a new WebRtcManager instance.
@@ -705,8 +706,12 @@ export class WebRtcManager {
             const state = this.#pc.connectionState;
             this.#debug("Connection state changed:", state);
             if (state === "connected") {
-                // Connection successful - reset reconnect attempts
+                // Connection successful - reset reconnect attempts and clear any pending timeout
                 this.#reconnectAttempts = 0;
+                if (this.#fullReconnectTimeoutTimer !== null) {
+                    clearTimeout(this.#fullReconnectTimeoutTimer);
+                    this.#fullReconnectTimeoutTimer = null;
+                }
                 this.#dispatch(WebRtcFsmEvent.CONNECTED);
             }
             else if (state === "failed") {
@@ -747,6 +752,11 @@ export class WebRtcManager {
             clearTimeout(this.#reconnectTimer);
             this.#reconnectTimer = null;
         }
+        // Clear any pending full reconnection timeout
+        if (this.#fullReconnectTimeoutTimer !== null) {
+            clearTimeout(this.#fullReconnectTimeoutTimer);
+            this.#fullReconnectTimeoutTimer = null;
+        }
         // Remove device change listener
         if (this.#deviceChangeHandler) {
             navigator.mediaDevices.removeEventListener("devicechange", this.#deviceChangeHandler);
@@ -853,8 +863,21 @@ export class WebRtcManager {
                 // perform the signaling handshake (create offer/answer exchange) to
                 // complete the reconnection.
                 try {
+                    // Clean up old connection and reset to IDLE so connect() creates a new PC
+                    this.#cleanup();
+                    this.#dispatch(WebRtcFsmEvent.RESET);
                     await this.connect();
-                    // If successful, onconnectionstatechange will reset attempts
+                    // Start timeout for full reconnection - if connection doesn't succeed
+                    // within the timeout, treat it as a failure
+                    const timeout = this.#config.fullReconnectTimeout ?? 30000;
+                    this.#fullReconnectTimeoutTimer = setTimeout(() => {
+                        this.#fullReconnectTimeoutTimer = null;
+                        // Only trigger failure if still not connected
+                        if (this.state !== WebRtcState.CONNECTED) {
+                            this.#debug("Full reconnection timeout reached, connection not established");
+                            this.#handleConnectionFailure();
+                        }
+                    }, timeout);
                 }
                 catch (e) {
                     this.#logger.error("[WebRtcManager] Reconnection failed:", e);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/webrtc",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",