Merge pull request #248 from shiguredo/feature/datachannel-signaling-type-close

DataChannel Signaling の type: close のデータ構造を定義

Author: zztkm

CHANGES.md

@@ -33,6 +33,12 @@
   - @zztkm
 - [ADD] サイマルキャストの映像のエンコーディングパラメーター `scaleResolutionDownTo` を追加する
   - @zztkm
+- [ADD] Sora から DataChannel シグナリングを切断する際に "type": "close" メッセージを受信する機能を追加する
+  - DataChannel シグナリングが有効、かつ ignore_disconnect_websocket が true、かつ Sora の設定で data_channel_signaling_close_message が有効な場合に受信することが可能
+  - "type": "close" に対応するため、 `Signaling` のケースに `close` を追加した
+    - `close` の associated value の型である `SignalingClose` 構造体を追加した
+  - `SoraError` に DataChannel シグナリングで "type": "close" を受信して接続が解除されたことを表すケースである `dataChannelClosed` を追加した
+  - @zztkm
 - [FIX] Sora から切断された場合の切断処理を修正し適切なエラーを ``MediaChannelHandlers.onDisconnect`` で受け取ることができるようにする
   - Sora iOS SDK 2025.1.1 までは Sora から Close Frame を受け取ったり、ネットワークエラーが起きたりしても、WebSocket メッセージ受信失敗に起因する ``SoraError.webSocketError`` しか受信できなかったが、以下の内容を受信できるようになった
     - Sora から Close Frame を受け取った場合のステータスコードと理由

Sora/MediaChannel.swift

@@ -416,7 +416,7 @@ public final class MediaChannel {
       handlers.onDisconnectLegacy?(error)
 
       // クロージャを用いて、エラーの内容に応じた SoraCloseEvent を生成
-      // error が nil の場合はクライアントからの正常終了として .ok にする
+      // error が nil の場合はクライアントからの正常終了 or DataChannel のみのシグナリング利用時の正常終了として .ok にする
       // error が SoraError の場合はケースに応じて .ok と .error を切り替える
       // error が SoraError の場合はクライアントが disconnect に渡した error のため、そのまま .error とする
       let disconnectEvent: SoraCloseEvent = {
@@ -428,6 +428,8 @@ public final class MediaChannel {
           case .webSocketClosed(let code, let reason):
             // 基本的に reason が nil なるケースはないはずだが、nil の場合は空文字列とする
             return SoraCloseEvent.ok(code: code.intValue(), reason: reason ?? "")
+          case .dataChannelClosed(let code, let reason):
+            return SoraCloseEvent.ok(code: code, reason: reason)
           default:
             return SoraCloseEvent.error(error)
           }

Sora/PeerChannel.swift

@@ -146,6 +146,9 @@ class PeerChannel: NSObject, RTCPeerConnectionDelegate {
 
   private var connectedAtLeastOnce: Bool = false
 
+  /// DataChannel シグナリングで type: close メッセージを受信したときにメッセージ内容を保存するための変数
+  private var dataChannelSignalingClose: (code: Int, reason: String)?
+
   // type: redirect のために SDP を保存しておく
   // 値が設定されている場合2回目の type: connect メッセージ送信とみなし、 redirect 中であると判断する
   private var sdp: String?
@@ -982,14 +985,17 @@ class PeerChannel: NSObject, RTCPeerConnectionDelegate {
 
   func handleSignalingOverDataChannel(_ signaling: Signaling) {
     Logger.debug(
-      type: .mediaStream,
+      type: .peerChannel,
       message: "handle signaling over DataChannel => \(signaling.typeName())")
     switch signaling {
     case .reOffer(let reOffer):
       createAndSendReAnswerOverDataChannel(forReOffer: reOffer.sdp)
     case .push, .notify:
       // 処理は不要
       break
+    case .close(let close):
+      // dataChannelSignalingClose に格納した値は basicDisconnect で利用される
+      dataChannelSignalingClose = (code: close.code, reason: close.reason)
     default:
       Logger.error(
         type: .peerChannel, message: "unexpected signaling type => \(signaling.typeName())")
@@ -1044,6 +1050,19 @@ class PeerChannel: NSObject, RTCPeerConnectionDelegate {
 
     nativeChannel?.close()
 
+    var error = error
+    // DataChannel が正常にクローズされ (reason == .dataChannelClosed)、
+    // かつ事前に Sora から "close" メッセージを受信していた場合 (dataChannelSignalingClose != nil)、
+    // error を SoraError.dataChannelClosed にする
+    if let dataChannelSignalingClose = dataChannelSignalingClose,
+      case .dataChannelClosed = reason
+    {
+      error = SoraError.dataChannelClosed(
+        statusCode: dataChannelSignalingClose.code, reason: dataChannelSignalingClose.reason
+      )
+    }
+
+    // TODO(zztkm): signalingChannel.ignoreDisconnectWebSocket が true の場合はこの処理は不要かもしれない
     signalingChannel.disconnect(error: error, reason: reason)
 
     Logger.debug(type: .peerChannel, message: "call onDisconnect")
@@ -1055,6 +1074,9 @@ class PeerChannel: NSObject, RTCPeerConnectionDelegate {
       onConnect = nil
     }
 
+    // disconnect したあとは基本的に PeerChannel を使い回さないはずだが、一応 nil にしておく
+    dataChannelSignalingClose = nil
+
     Logger.debug(type: .peerChannel, message: "did disconnect")
   }
 

Sora/Signaling.swift

@@ -132,6 +132,10 @@ public enum Signaling {
   /// "redirect" シグナリング
   case redirect(SignalingRedirect)
 
+  /// type: "close" は DataChannel シグナリング利用時に
+  /// `ignore_disconnect_websocket`: true かつ、`data_channel_signaling_close_message`: true の場合に受信する
+  case close(SignalingClose)
+
   /// :nodoc:
   public static func decode(_ data: Data) -> Result<Signaling, Error> {
     do {
@@ -175,6 +179,8 @@ public enum Signaling {
       return "switched"
     case .redirect:
       return "redirect"
+    case .close:
+      return "close"
     }
   }
 }
@@ -515,6 +521,15 @@ public struct SignalingRedirect {
   public var location: String
 }
 
+/// type: "close" シグナリングメッセージを表す
+/// Sora から受信するメッセージなのでエンコーダーは実装していない
+public struct SignalingClose {
+  /// ステータスコード
+  public var code: Int
+  /// 切断理由
+  public var reason: String
+}
+
 /// "notify" シグナリングメッセージを表します。
 public struct SignalingNotify {
   // MARK: イベント情報
@@ -692,6 +707,8 @@ extension Signaling: Codable {
       self = try .switched(SignalingSwitched(from: decoder))
     case "redirect":
       self = try .redirect(SignalingRedirect(from: decoder))
+    case "close":
+      self = try .close(SignalingClose(from: decoder))
     default:
       throw SoraError.unknownSignalingMessageType(type: type)
     }
@@ -1355,3 +1372,17 @@ extension SignalingRedirect: Decodable {
     location = try container.decode(String.self, forKey: .location)
   }
 }
+
+/// :nodoc:
+extension SignalingClose: Decodable {
+  enum CodingKeys: String, CodingKey {
+    case code
+    case reason
+  }
+
+  public init(from decoder: Decoder) throws {
+    let container = try decoder.container(keyedBy: CodingKeys.self)
+    code = try container.decode(Int.self, forKey: .code)
+    reason = try container.decode(String.self, forKey: .reason)
+  }
+}

Sora/SoraError.swift

@@ -38,6 +38,11 @@ public enum SoraError: Error {
 
   /// メッセージング機能のエラー
   case messagingError(reason: String)
+
+  /// DataChannel 経由のシグナリングで type: close を受信し、接続が解除されたことを示します。
+  /// - statusCode: ステータスコード
+  /// - reason: 切断理由
+  case dataChannelClosed(statusCode: Int, reason: String)
 }
 
 /// :nodoc:
@@ -73,6 +78,8 @@ extension SoraError: LocalizedError {
       return "Camera error: \(reason)"
     case .messagingError(let reason):
       return "Messaging error: \(reason)"
+    case .dataChannelClosed(let statusCode, let reason):
+      return "DataChannel is closed (\(statusCode) \(reason))"
     }
   }
 }