refactor: introduce typed RTC exceptions and acquireModificationLock mutex

- Add pc_exceptions.dart with PCWrongSignalingState hierarchy and RtcJsepErrorParser
- Remove duplicate SDPConfigurationError from user_media_builder.dart
- Replace on String catch substring checks in RenegotiationHandler with typed exceptions
- Add acquireModificationLock to PeerConnectionManager for serialising concurrent modifications
- Add missing _CallActionRenegotiate event class to call_event.dart

Author: SERDUN

lib/features/call/bloc/call_bloc.dart

@@ -1,5 +1,6 @@
 import 'dart:async';
 import 'dart:io';
+import 'dart:math';
 
 import 'package:flutter/widgets.dart' hide Notification;
 
@@ -153,6 +154,7 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
     on<_PeerConnectionEvent>(_onPeerConnectionEvent, transformer: sequential());
     on<CallScreenEvent>(_onCallScreenEvent, transformer: sequential());
     on<CallConfigEvent>(_onConfigEvent, transformer: sequential());
+    on<_CallActionRenegotiate>(_onCallActionRenegotiate, transformer: droppable());
 
     navigator.mediaDevices.ondevicechange = (event) {
       add(const _NavigatorMediaDevicesChange());
@@ -1119,6 +1121,8 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
       proximityEnabled: state.shouldListenToProximity,
     );
 
+    final releaseLock = await _peerConnectionManager.acquireModificationLock(activeCall.callId);
+
     try {
       final jsep = event.jsep;
       if (jsep != null) {
@@ -1141,6 +1145,7 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
                 '__onCallSignalingEventUpdating: glare detected via pre-check (signalingState=$signalingState), rolling back local offer',
               );
               await peerConnection.setLocalDescription(RTCSessionDescription('', 'rollback'));
+              _dispatchRenegotiation(event.callId);
             }
 
             try {
@@ -1154,6 +1159,7 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
                   '__onCallSignalingEventUpdating: glare detected via catch ($e), rolling back local offer and retrying',
                 );
                 await peerConnection.setLocalDescription(RTCSessionDescription('', 'rollback'));
+                _dispatchRenegotiation(event.callId);
                 await peerConnection.setRemoteDescription(remoteDescription);
               } else {
                 rethrow;
@@ -1164,7 +1170,9 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
 
             // According to RFC 8829 5.6 (https://datatracker.ietf.org/doc/html/rfc8829#section-5.6),
             // localDescription should be set before sending the answer to transition into stable state.
-            await peerConnection.setLocalDescription(localDescription);
+            await peerConnection
+                .setLocalDescription(localDescription)
+                .catchError((error) => throw RtcJsepErrorParser.parse(error));
 
             await _signalingClient?.execute(
               UpdateRequest(
@@ -1178,10 +1186,13 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
         });
       }
     } catch (e, s) {
+      _logger.warning('__onCallSignalingEventUpdating - error:', e, s);
       callErrorReporter.handle(e, s, '__onCallSignalingEventUpdating && jsep error:');
 
       _peerConnectionManager.completeError(event.callId, e);
       add(_ResetStateEvent.completeCall(event.callId));
+    } finally {
+      releaseLock();
     }
   }
 
@@ -1482,6 +1493,8 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
     if (currentVideoTrack != null) {
       currentVideoTrack.enabled = event.enabled;
       emit(state.copyWithMappedActiveCall(event.callId, (call) => call.copyWith(video: event.enabled)));
+      // Helps recover from video-stuck states when user taps to toggle video
+      _dispatchRenegotiation(event.callId);
       return;
     }
 
@@ -2003,7 +2016,9 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
 
       // According to RFC 8829 5.6 (https://datatracker.ietf.org/doc/html/rfc8829#section-5.6),
       // localDescription should be set before sending the answer to transition into stable state.
-      await peerConnection.setLocalDescription(localDescription).catchError((e) => throw SDPConfigurationError(e));
+      await peerConnection
+          .setLocalDescription(localDescription)
+          .catchError((error) => throw RtcJsepErrorParser.parse(error));
 
       await _signalingClient?.execute(
         AcceptRequest(
@@ -2906,6 +2921,78 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
     await _signalingClient?.execute(updateRequest);
   }
 
+  /// Proactive renegotiation handler for recovery scenarios (glare rollback, video toggle, etc.).
+  ///
+  /// Uses [acquireModificationLock] to serialize with [__onCallSignalingEventUpdating],
+  /// and [droppable] transformer to discard redundant retries queued during an active cycle.
+  Future<void> _onCallActionRenegotiate(_CallActionRenegotiate event, Emitter<CallState> emit) async {
+    final callId = event.callId;
+    final activeCall = state.activeCalls.firstWhereOrNull((call) => call.callId == callId);
+    if (activeCall == null) return;
+
+    final lineId = activeCall.line;
+
+    final peerConnection = await _peerConnectionManager.retrieve(callId);
+    if (peerConnection == null) return;
+
+    final releaseLock = await _peerConnectionManager.acquireModificationLock(callId);
+
+    final pcSignalingState = await peerConnection.getSignalingState();
+    _logger.warning(() => '_onCallActionRenegotiate signalingState: $pcSignalingState');
+    final connectionState = await peerConnection.getConnectionState();
+    _logger.warning(() => '_onCallActionRenegotiate connectionState: $connectionState');
+
+    if (connectionState == RTCPeerConnectionState.RTCPeerConnectionStateNew) {
+      _logger.warning('_onCallActionRenegotiate skipped due to new connection state');
+      releaseLock();
+      return;
+    }
+
+    if (pcSignalingState != RTCSignalingState.RTCSignalingStateStable) {
+      _logger.warning('_onCallActionRenegotiate skipped due to non-stable signaling state');
+      releaseLock();
+      return;
+    }
+
+    try {
+      final localDescription = await peerConnection.createOffer({});
+      sdpMunger?.apply(localDescription);
+      // According to RFC 8829 5.6 (https://datatracker.ietf.org/doc/html/rfc8829#section-5.6),
+      // localDescription should be set before sending the offer to transition into have-local-offer state.
+      await peerConnection
+          .setLocalDescription(localDescription)
+          .catchError((error) => throw RtcJsepErrorParser.parse(error));
+
+      final updateRequest = UpdateRequest(
+        transaction: WebtritSignalingClient.generateTransactionId(),
+        line: lineId,
+        callId: callId,
+        jsep: localDescription.toMap(),
+      );
+      await _signalingClient?.execute(updateRequest);
+    } catch (e, s) {
+      _logger.warning('_onCallActionRenegotiate error', e, s);
+      callErrorReporter.handle(e, s, '_onCallActionRenegotiate error:');
+    } finally {
+      releaseLock();
+    }
+  }
+
+  /// Schedules a renegotiation with a random delay to reduce glare probability.
+  ///
+  /// Inspired by the 491 Request Pending handling described in RFC 5407.
+  void _dispatchRenegotiation(String callId, {Duration? delayOverride}) async {
+    final randomDelay = delayOverride ?? Duration(milliseconds: Random().nextInt(6000).clamp(1000, 5000));
+    _logger.warning(() => '_dispatchRenegotiation for callId: $callId with random delay: $randomDelay');
+    Future.delayed(randomDelay).then((_) {
+      if (isClosed) return;
+      final activeCall = state.activeCalls.firstWhereOrNull((call) => call.callId == callId);
+      if (activeCall == null) return;
+
+      add(_CallActionRenegotiate(callId));
+    });
+  }
+
   void _addToRecents(ActiveCall activeCall) {
     final number = activeCall.handle.value;
     final username = activeCall.displayName;

lib/features/call/bloc/call_event.dart

@@ -1056,3 +1056,12 @@ class _CallConfigEventUpdated extends CallConfigEvent {
   @override
   List<Object?> get props => [monitorCheckInterval];
 }
+
+class _CallActionRenegotiate extends CallEvent {
+  const _CallActionRenegotiate(this.callId);
+
+  final String callId;
+
+  @override
+  List<Object?> get props => [callId];
+}

lib/features/call/utils/call_error_reporter.dart

@@ -7,6 +7,7 @@ import 'package:webtrit_signaling/webtrit_signaling.dart';
 import 'package:webtrit_phone/app/notifications/models/notification.dart';
 
 import '../models/notification.dart';
+import 'pc_exceptions.dart';
 import 'user_media_builder.dart';
 
 final _logger = Logger('CallBloc:SignalingErrorReporter');

lib/features/call/utils/pc_exceptions.dart

@@ -0,0 +1,32 @@
+abstract class PCWrongSignalingState implements Exception {
+  final String message;
+  const PCWrongSignalingState(this.message);
+}
+
+class RtcSetRemoteDescriptionWhileHaveLocalOffer extends PCWrongSignalingState {
+  const RtcSetRemoteDescriptionWhileHaveLocalOffer(super.message);
+}
+
+class RtcCreateAnswerWhileWrongState extends PCWrongSignalingState {
+  const RtcCreateAnswerWhileWrongState(super.message);
+}
+
+class SDPConfigurationError implements Exception {
+  final String message;
+  const SDPConfigurationError(this.message);
+  @override
+  String toString() => 'SDPConfigurationError: $message';
+}
+
+class RtcJsepErrorParser {
+  static Exception parse(Object error) {
+    final msg = error.toString();
+    if (msg.contains('have-local-offer') || msg.contains('setRemoteDescription')) {
+      return RtcSetRemoteDescriptionWhileHaveLocalOffer(msg);
+    }
+    if (msg.contains('createAnswer') || msg.contains('wrong state')) {
+      return RtcCreateAnswerWhileWrongState(msg);
+    }
+    return SDPConfigurationError(msg);
+  }
+}

lib/features/call/utils/peer_connection_manager.dart

@@ -81,6 +81,9 @@ final class PeerConnectionManager {
   /// Stores the [_ConnectionState] for each active call, keyed by [CallId].
   final _states = <CallId, _ConnectionState>{};
 
+  /// Serialises concurrent modifications to a single call's peer connection.
+  final Map<String, Completer<void>> _modificationLocks = {};
+
   /// Tracks active disposal futures.
   ///
   /// Acts as a "Disposal Barrier": [createPeerConnection] checks this map
@@ -103,6 +106,22 @@ final class PeerConnectionManager {
     }
   }
 
+  /// Acquires an exclusive modification lock for [callId].
+  ///
+  /// Returns a release function. Caller must call it in a `finally` block to
+  /// unblock any concurrent waiters.
+  Future<void Function()> acquireModificationLock(String callId) async {
+    while (_modificationLocks.containsKey(callId)) {
+      await _modificationLocks[callId]!.future;
+    }
+    final completer = Completer<void>();
+    _modificationLocks[callId] = completer;
+    return () {
+      _modificationLocks.remove(callId);
+      if (!completer.isCompleted) completer.complete();
+    };
+  }
+
   /// Reserves a slot for a call. Must be called before [retrieve].
   void add(CallId callId) {
     if (_states.containsKey(callId)) {

lib/features/call/utils/renegotiation_handler.dart

@@ -4,6 +4,7 @@ import 'package:flutter_webrtc/flutter_webrtc.dart';
 import 'package:logging/logging.dart';
 import 'package:webtrit_signaling/webtrit_signaling.dart';
 import 'call_error_reporter.dart';
+import 'pc_exceptions.dart';
 import 'sdp_munger.dart';
 
 final _logger = Logger('RenegotiationHandler');
@@ -112,30 +113,29 @@ class RenegotiationHandler {
 
       // According to RFC 8829 5.6 (https://datatracker.ietf.org/doc/html/rfc8829#section-5.6),
       // localDescription should be set before sending the offer to transition into have-local-offer state.
-      await peerConnection.setLocalDescription(localDescription);
-
-      await execute(callId, lineId, localDescription);
+      try {
+        await peerConnection.setLocalDescription(localDescription);
+        await execute(callId, lineId, localDescription);
+      } on String catch (e) {
+        throw RtcJsepErrorParser.parse(e);
+      }
     } on WebtritSignalingErrorException catch (e) {
       _logger.warning(
         () => 'onRenegotiationNeeded: UpdateRequest rejected by server (callId=$callId, lineId=$lineId): $e',
       );
       callErrorReporter.handle(e, null, 'RenegotiationHandler.handle error (callId=$callId, lineId=$lineId)');
-    } on String catch (e) {
+    } on PCWrongSignalingState catch (e) {
       // flutter_webrtc surfaces native errors as plain strings. A "wrong state" failure
       // on setLocalDescription means a concurrent setRemoteDescription (e.g. from an
       // incoming updating_call) moved the PC out of stable between the TOCTOU guard and
       // the setLocalDescription call. This is a transient race — libwebrtc keeps the
       // [[NegotiationNeeded]] flag set and will re-fire onRenegotiationNeeded once the
       // PC returns to stable. No user notification is needed.
-      if (e.contains('wrong state') || e.contains('have-remote-offer') || e.contains('have-local-offer')) {
-        _logger.warning(
-          () =>
-              'onRenegotiationNeeded: setLocalDescription failed in wrong state ($e) '
-              '— libwebrtc will re-fire onRenegotiationNeeded when stable',
-        );
-      } else {
-        callErrorReporter.handle(e, null, 'RenegotiationHandler.handle error (callId=$callId, lineId=$lineId)');
-      }
+      _logger.warning(
+        () =>
+            'RenegotiationHandler: signaling state error — ${e.message} '
+            '— libwebrtc will re-fire onRenegotiationNeeded when stable',
+      );
     } catch (e, s) {
       callErrorReporter.handle(e, s, 'RenegotiationHandler.handle error (callId=$callId, lineId=$lineId)');
     } finally {

lib/features/call/utils/user_media_builder.dart

@@ -67,12 +67,3 @@ class UserMediaError implements Exception {
   @override
   String toString() => 'UserMediaError: $message';
 }
-
-class SDPConfigurationError implements Exception {
-  final String message;
-
-  SDPConfigurationError(this.message);
-
-  @override
-  String toString() => 'SDPConfigurationError: $message';
-}

lib/features/call/utils/utils.dart

@@ -6,6 +6,7 @@ export 'contact_resolver.dart';
 export 'ice_filter.dart';
 export 'logging_rtp_traffic_monitor_delegate.dart';
 export 'peer_connection_factory.dart';
+export 'pc_exceptions.dart';
 export 'peer_connection_manager.dart';
 export 'renegotiation_handler.dart';
 export 'peer_connection_policy_applier.dart';