refactor(call): generic peer_message side channel for in-call app-to-app state (WT-713)

Replace the media_state-specific request/event with a generic peer_message
envelope carrying an opaque {type, data} pair. media_state (camera state,
data {video}) becomes the first carried type; the client routes inbound
peer_message by type and ignores unknown ones, so future in-call signals reuse
the same channel without protocol changes. "message" over "signal" to avoid
collision with the SIP/WS signaling plane - this is an app-to-app message.

Author: SERDUN

lib/features/call/bloc/call_bloc.dart

@@ -81,6 +81,9 @@ typedef OutgoingFromNumberResolver = String? Function(String? callerProvidedFrom
 
 const _getUserMediaPushKitTimeout = Duration(seconds: 8);
 
+/// `peer_message` type carrying the remote camera state (`data: {video: bool}`).
+const _mediaStatePeerMessageType = 'media_state';
+
 class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver implements CallkeepDelegate {
   final CallLogsRepository callLogsRepository;
   final void Function(String callId, String callerName) _onMissedCall;
@@ -1138,7 +1141,13 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
     final transaction = WebtritSignalingClient.generateTransactionId();
     _signalingModule
         .execute(
-          MediaStateRequest(transaction: transaction, line: call.line, callId: call.callId, media: {'video': video}),
+          PeerMessageRequest(
+            transaction: transaction,
+            line: call.line,
+            callId: call.callId,
+            type: _mediaStatePeerMessageType,
+            data: {'video': video},
+          ),
         )
         ?.catchError((Object e) => _logger.info('_sendMediaState: $e'));
   }
@@ -4113,8 +4122,12 @@ class CallBloc extends Bloc<CallEvent, CallState> with WidgetsBindingObserver im
       add(_CallSignalingEvent.updating(line: event.line, callId: event.callId));
     } else if (event is UpdatedEvent) {
       add(_CallSignalingEvent.updated(line: event.line, callId: event.callId));
-    } else if (event is MediaStateEvent) {
-      add(_CallSignalingEvent.mediaState(line: event.line, callId: event.callId, media: event.media));
+    } else if (event is PeerMessageEvent) {
+      if (event.type == _mediaStatePeerMessageType) {
+        add(_CallSignalingEvent.mediaState(line: event.line, callId: event.callId, media: event.data));
+      } else {
+        _logger.info('[SIG] PeerMessageEvent: ignoring unknown type "${event.type}"');
+      }
     } else if (event is TransferEvent) {
       add(
         _CallSignalingEvent.transfer(

packages/webtrit_signaling/lib/src/events/call/call_events.dart

@@ -7,9 +7,9 @@ export 'hangingup_event.dart';
 export 'hangup_event.dart';
 export 'holding_event.dart';
 export 'incoming_call_event.dart';
-export 'media_state_event.dart';
 export 'missed_call_event.dart';
 export 'notify_event.dart';
+export 'peer_message_event.dart';
 export 'proceeding_event.dart';
 export 'progress_event.dart';
 export 'resuming_event.dart';

packages/webtrit_signaling/lib/src/events/call/media_state_event.dart

@@ -0,0 +1,48 @@
+import '../abstract_events.dart';
+
+/// Peer-relayed counterpart of [PeerMessageRequest]. Carries the opaque
+/// [type] + [data] envelope from the remote party plus the [sender] number;
+/// the client interprets [type] (e.g. `media_state`) and ignores unknown ones.
+class PeerMessageEvent extends CallEvent {
+  const PeerMessageEvent({
+    super.transaction,
+    required super.line,
+    required super.callId,
+    required this.type,
+    required this.data,
+    this.sender,
+  });
+
+  final String type;
+  final Map<String, dynamic> data;
+  final String? sender;
+
+  @override
+  List<Object?> get props => [...super.props, type, data, sender];
+
+  static const typeValue = 'peer_message';
+
+  @override
+  Map<String, dynamic> toJson() => {
+    ...callBaseJson(typeValue),
+    'type': type,
+    'data': data,
+    if (sender != null) 'sender': sender,
+  };
+
+  factory PeerMessageEvent.fromJson(Map<String, dynamic> json) {
+    final eventTypeValue = json[Event.typeKey];
+    if (eventTypeValue != typeValue) {
+      throw ArgumentError.value(eventTypeValue, Event.typeKey, 'Not equal $typeValue');
+    }
+
+    return PeerMessageEvent(
+      transaction: json['transaction'],
+      line: json['line'],
+      callId: json['call_id'],
+      type: json['type'],
+      data: json['data'],
+      sender: json['sender'],
+    );
+  }
+}

packages/webtrit_signaling/lib/src/events/call/peer_message_event.dart

@@ -39,9 +39,9 @@ abstract class CallEvent extends LineEvent {
     HangupEvent.typeValue: HangupEvent.fromJson,
     HoldingEvent.typeValue: HoldingEvent.fromJson,
     IncomingCallEvent.typeValue: IncomingCallEvent.fromJson,
-    MediaStateEvent.typeValue: MediaStateEvent.fromJson,
     MissedCallEvent.typeValue: MissedCallEvent.fromJson,
     NotifyEvent.typeValue: NotifyEvent.fromJson,
+    PeerMessageEvent.typeValue: PeerMessageEvent.fromJson,
     ProceedingEvent.typeValue: ProceedingEvent.fromJson,
     ProgressEvent.typeValue: ProgressEvent.fromJson,
     ResumingEvent.typeValue: ResumingEvent.fromJson,

packages/webtrit_signaling/lib/src/events/call_event.dart

@@ -2,8 +2,8 @@ export 'accept_request.dart';
 export 'decline_request.dart';
 export 'hangup_request.dart';
 export 'hold_request.dart';
-export 'media_state_request.dart';
 export 'outgoing_call_request.dart';
+export 'peer_message_request.dart';
 export 'transfer_request.dart';
 export 'unhold_request.dart';
 export 'update_request.dart';

packages/webtrit_signaling/lib/src/requests/call/call_requests.dart

@@ -0,0 +1,50 @@
+import '../abstract_requests.dart';
+
+/// Generic in-call app-to-app side channel. The server is a dumb relay: it
+/// forwards the opaque [type] + [data] envelope to the peer's sessions without
+/// inspecting it. `media_state` (camera state) is the first carried [type];
+/// further types (call quality, peer mute, ...) reuse the same request.
+class PeerMessageRequest extends CallRequest {
+  const PeerMessageRequest({
+    required super.transaction,
+    required super.line,
+    required super.callId,
+    required this.type,
+    required this.data,
+  });
+
+  final String type;
+  final Map<String, dynamic> data;
+
+  @override
+  List<Object?> get props => [...super.props, type, data];
+
+  static const typeValue = 'peer_message';
+
+  factory PeerMessageRequest.fromJson(Map<String, dynamic> json) {
+    final requestTypeValue = json[Request.typeKey];
+    if (requestTypeValue != typeValue) {
+      throw ArgumentError.value(requestTypeValue, Request.typeKey, 'Not equal $typeValue');
+    }
+
+    return PeerMessageRequest(
+      transaction: json['transaction'],
+      line: json['line'],
+      callId: json['call_id'],
+      type: json['type'],
+      data: json['data'],
+    );
+  }
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      Request.typeKey: typeValue,
+      'transaction': transaction,
+      'line': line,
+      'call_id': callId,
+      'type': type,
+      'data': data,
+    };
+  }
+}

packages/webtrit_signaling/lib/src/requests/call/media_state_request.dart

@@ -29,8 +29,8 @@ abstract class CallRequest extends LineRequest {
     DeclineRequest.typeValue: DeclineRequest.fromJson,
     HangupRequest.typeValue: HangupRequest.fromJson,
     HoldRequest.typeValue: HoldRequest.fromJson,
-    MediaStateRequest.typeValue: MediaStateRequest.fromJson,
     OutgoingCallRequest.typeValue: OutgoingCallRequest.fromJson,
+    PeerMessageRequest.typeValue: PeerMessageRequest.fromJson,
     TransferRequest.typeValue: TransferRequest.fromJson,
     UnholdRequest.typeValue: UnholdRequest.fromJson,
     UpdateRequest.typeValue: UpdateRequest.fromJson,

packages/webtrit_signaling/lib/src/requests/call/peer_message_request.dart

@@ -6,58 +6,62 @@ import 'package:webtrit_signaling/src/events/call/call_events.dart';
 import 'package:webtrit_signaling/src/events/call_event.dart';
 
 void main() {
-  void testFromJson(String description, Map<String, dynamic> actual, MediaStateEvent expected) {
+  void testFromJson(String description, Map<String, dynamic> actual, PeerMessageEvent expected) {
     test(description, () {
-      expect(MediaStateEvent.fromJson(actual), equals(expected));
+      expect(PeerMessageEvent.fromJson(actual), equals(expected));
       expect(CallEvent.fromJson(actual), equals(expected));
     });
   }
 
   testFromJson(
-    'MediaStateEvent: video off with sender',
+    'PeerMessageEvent: media_state video off with sender',
     json.decode(r'''
     {
       "transaction": "transaction 1",
       "line": 0,
       "call_id": "qwerty",
-      "event": "media_state",
-      "media": {"video": false},
+      "event": "peer_message",
+      "type": "media_state",
+      "data": {"video": false},
       "sender": "555001"
     }
     ''')
         as Map<String, dynamic>,
-    const MediaStateEvent(
+    const PeerMessageEvent(
       transaction: 'transaction 1',
       line: 0,
       callId: 'qwerty',
-      media: {'video': false},
+      type: 'media_state',
+      data: {'video': false},
       sender: '555001',
     ),
   );
 
   testFromJson(
-    'MediaStateEvent: video on without sender and transaction',
+    'PeerMessageEvent: media_state video on without sender and transaction',
     json.decode(r'''
     {
       "line": 1,
       "call_id": "qwerty",
-      "event": "media_state",
-      "media": {"video": true}
+      "event": "peer_message",
+      "type": "media_state",
+      "data": {"video": true}
     }
     ''')
         as Map<String, dynamic>,
-    const MediaStateEvent(line: 1, callId: 'qwerty', media: {'video': true}),
+    const PeerMessageEvent(line: 1, callId: 'qwerty', type: 'media_state', data: {'video': true}),
   );
 
-  test('MediaStateEvent: toJson round trip', () {
-    const event = MediaStateEvent(
+  test('PeerMessageEvent: toJson round trip', () {
+    const event = PeerMessageEvent(
       transaction: 'transaction 1',
       line: 0,
       callId: 'qwerty',
-      media: {'video': false},
+      type: 'media_state',
+      data: {'video': false},
       sender: '555001',
     );
 
-    expect(MediaStateEvent.fromJson(event.toJson()), equals(event));
+    expect(PeerMessageEvent.fromJson(event.toJson()), equals(event));
   });
 }