Merge pull request #277 from shiguredo/feature/get-stats

統計情報取得 getStats メソッド追加

Author: t-miya

CHANGES.md

@@ -13,6 +13,11 @@
 
 - [UPDATE] libwebrtc m140.7339.2.2 に上げる
   - @miosakuma
+- [UPDATE] Statistics, StatisticsEntry をドキュメント対象として公開する
+  - `getStats` メソッドの返り値である `Statistics` のドキュメントを生成するため
+  - @t-miya
+- [ADD] MediaChannel に libwebrtc の統計情報を取得する `getStats` メソッドを追加する
+  - @t-miya
 
 ## 2025.2.0
 

Sora/MediaChannel.swift

@@ -442,6 +442,58 @@ public final class MediaChannel {
     }
   }
 
+  /// libwebrtc の統計情報を取得します。
+  /// 非同期取得中に切断された場合でも安全になるよう、コールバック内で
+  /// self の生存確認、state == .connected の再確認、peerChannel.nativeChannel が同一インスタンスかどうか、をチェックしています。
+  ///
+  /// - parameter handler: 統計情報取得後に呼ばれるクロージャー
+  public func getStats(handler: @escaping (Result<Statistics, Error>) -> Void) {
+    guard state == .connected else {
+      let message = "MediaChannel is not connected (state: \(state))"
+      Logger.debug(type: .mediaChannel, message: message)
+      handler(.failure(SoraError.peerChannelError(reason: message)))
+      return
+    }
+
+    guard let peerConnection = peerChannel.nativeChannel else {
+      let message =
+        "RTCPeerConnection is unavailable (state: \(state), nativeChannel: nil)"
+      Logger.debug(type: .mediaChannel, message: message)
+      handler(.failure(SoraError.peerChannelError(reason: message)))
+      return
+    }
+
+    // peerConnection.statistics クロージャはlibwebrtc 側のスレッドから遅れて呼ばれ、内部で MediaChannel をキャプチャします。
+    // ここで self を強参照すると、MediaChannel が切断・解放されたあとでもクロージャが解放されず、deinit が遅れたり循環参照が発生する恐れがあります。
+    // そのため [weak self] でキャプチャし、呼び出し時点で MediaChannel がまだ有効かどうかをチェックしています。
+    // self が解放済みなら MediaChannel is unavailable エラーを返すことで安全に処理を抜けます。
+    peerConnection.statistics { [weak self] report in
+      guard let self else {
+        handler(.failure(SoraError.peerChannelError(reason: "MediaChannel is unavailable")))
+        return
+      }
+
+      guard self.state == .connected else {
+        let message = "MediaChannel is not connected (state: \(self.state))"
+        Logger.debug(type: .mediaChannel, message: message)
+        handler(.failure(SoraError.peerChannelError(reason: message)))
+        return
+      }
+
+      guard let currentPeerConnection = self.peerChannel.nativeChannel,
+        currentPeerConnection === peerConnection
+      else {
+        let message =
+          "RTCPeerConnection is unavailable (state: \(self.state), nativeChannel changed)"
+        Logger.debug(type: .mediaChannel, message: message)
+        handler(.failure(SoraError.peerChannelError(reason: message)))
+        return
+      }
+
+      handler(.success(Statistics(contentsOf: report)))
+    }
+  }
+
   /// DataChannel を利用してメッセージを送信します
   public func sendMessage(label: String, data: Data) -> Error? {
     guard peerChannel.switchedToDataChannel else {

Sora/Statistics.swift

@@ -1,9 +1,12 @@
 import Foundation
 import WebRTC
 
-/// :nodoc:
+/// WebRTC の統計情報を SDK から扱いやすい形にしたコンテナーです。
 public class Statistics {
+  /// 収集時刻 (μs)
   public var timestamp: CFTimeInterval
+
+  /// 統計エントリーの一覧
   public var entries: [StatisticsEntry] = []
 
   init(contentsOf report: RTCStatisticsReport) {
@@ -14,6 +17,7 @@ public class Statistics {
     }
   }
 
+  /// JSON へシリアライズしやすい形式を返します。
   public var jsonObject: Any {
     let json = NSMutableArray()
     for entry in entries {
@@ -28,11 +32,18 @@ public class Statistics {
   }
 }
 
-/// :nodoc:
+/// 単一の WebRTC 統計エントリーを表します。
 public class StatisticsEntry {
+  /// エントリー ID
   public var id: String
+
+  /// 統計種別
   public var type: String
+
+  /// 測定時刻 (μs)
   public var timestamp: CFTimeInterval
+
+  /// 生の統計値
   public var values: [String: NSObject]
 
   init(contentsOf statistics: RTCStatistics) {