ICE コネクションステート機能

概要

ICE コネクションステート機能は Sora に ICE コネクションによる状態管理を持たせた機能です。

前提

この機能はクライアント側が意識する必要はありません。

挙動

Sora は WebRTC が確立した後に TURN 上で ICE コネクションステートを更新し続けます。 ステートの更新には STUN Binding-Request と STUN Binding-Success を利用します。

  • Sora は 2.5 秒間隔で STUN Binding-Request をクライアントへ送ります

    • STUN Binding-Success が 2.5 秒以内に一度も返ってこない場合、状態を connected から checking へ遷移します

  • 状態が checking へ遷移した場合、 Sora は 1 秒間隔で STUN Binding-Request をクライアントへ送ります

    • STUN Binding-Success が 5 秒以内に一度も返ってこない場合、状態を checking から disconnected へ遷移します

    • この 5 秒は sora.conf にて ice_connection_state_disconnected_timeout で変更できます

  • 状態が disconnected に遷移した場合、 Sora は 50 ミリ秒間隔で STUN Binding-Request をクライアントへ送ります

    • STUN Binding-Success が 10 秒以内に一度も返ってこない場合、状態を disconnected から failed へ遷移します

    • この 10 秒は sora.conf にて ice_connection_state_failed_timeout で変更できます

    • このタイミングで sora.jsonl に warning として ICE-CONNECTION-STATE-DISCONNECTED が出力されます

  • 状態が failed に遷移した場合、Sora はクライアントの接続を切断します

    • このタイミングで sora.jsonl に error として ICE-CONNECTION-STATE-FAILED が出力されます

設定

ICE コネクションステート機能は無効にすることはできません。

ただし、切断や失敗までの判定時間を sora.conf にてデフォルト値から変更できます。

ice_connection_state_disconnected_timeout

この値は Sora が ICE コネクションステートを disconnected へと遷移する際にクライアントからの応答を待つ時間です。

デフォルトでは 5 s が設定されています。

詳細は ice_connection_state_disconnected_timeout をご確認ください。

ice_connection_state_failed_timeout

この値は Sora が ICE コネクションステートを failed へと遷移する際にクライアントからの応答を待つ時間です。

デフォルトでは 10 s が設定されています。

詳細は ice_connection_state_failed_timeout をご確認ください。

シグナリング通知

sora.conf の signaling_notify_ice_connection_state を true に設定すると、 シグナリング通知 ice_connection_state が自分を含むセッション参加者全員に送信されます。

以下の 4 つのタイミングで送信します。

  1. connected から checking になった時

  2. checking から connected になった時

  3. checking から disconnected になった時

  4. disconnected から checking になった時

また、新規参加者には connection.created の data に既存参加者の ice_connection_state が含まれます。

ice-connection-state.connected

自分が接続した時は connection.created のシグナリング通知の後に、 ice-connection-state.connected のシグナリング通知が送信されます。

{
  "connection_id": "JA0H99CB490C9EEV8AAVBNSBWG",
  "timestamp": "2024-10-15T01:04:50.039752Z",
  "type": "notify",
  "event_type": "ice-connection-state.connected",
  "previous_state": "checking"
}

{
  // 色々省略
  "connection_id": "ZE6QPYMF1N4473AN1AH5KY6T3C",
  "data": [
    {
      "connection_id": "JA0H99CB490C9EEV8AAVBNSBWG",
      "timestamp": "2024-10-15T01:04:50.036927Z",
      "bundle_id": "JA0H99CB490C9EEV8AAVBNSBWG",
      "client_id": "JA0H99CB490C9EEV8AAVBNSBWG",
      // 既存参加者の ice_connection_state が入ってくる
      "ice_connection_state": "connected"
    }
  ],
  "timestamp": "2024-10-15T01:05:17.317571Z",
  "type": "notify",
  "session_id": "HC3DTTQH1946DC9HYKAE2AAHS8",
  "role": "sendrecv",
  "event_type": "connection.created",
}

ウェブフック

コネクションの状態が checking と disconnected だった合計時間をイベントウェブフックで取得できます。

  • 取得可能なイベントウェブフック

    • connection.created

    • connection.updated

    • connection.destroyed

  • data.ice_connection_state.total_checking_duration_ms に checking だった合計時間(ミリ秒)の合計が入ります

  • data.ice_connection_state.total_disconnected_duration_ms に disconnected だった合計時間(ミリ秒)の合計が入ります

{
  // 色々省略してます
  "type": "connection.destroyed",
  "channel_id": "sora",
  "connection_id": "GS4Q8PQ5PS3EXC30T6PM2R7Y20",
  "timestamp": "2023-08-16T05:42:13.970729Z",
  "bundle_id": "GS4Q8PQ5PS3EXC30T6PM2R7Y20",
  "client_id": "GS4Q8PQ5PS3EXC30T6PM2R7Y20",
  "data": {
    "ice_connection_state": {
      "total_checking_duration_ms": 5002,
      "total_disconnected_duration_ms": 10002
    }
  }
}

テスト

ICE コネクションステートのテストをしたい場合は LockIceConnectionState API を利用してください。

ステート図

重要

図のタイムアウト値はデフォルト値を採用しています。

        stateDiagram
    New --> Checking
    Checking --> Connected: 応答あり
    Checking --> Disconnected: 5 秒間応答なし
    Disconnected --> Failed: 10 秒間応答なし
    Connected --> Checking: 2.5 秒応答なし
    Disconnected --> Checking: 応答あり
    Connected --> Closed: 正常終了

シーケンス図

重要

図のタイムアウト値はデフォルト値を採用しています。

connected

正常な接続状態である connected を継続しているシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>+C: STUN Binding-Request
    C-->>-S: STUN Binding-Success
    note left of S: 2.5 秒経過
    S->>+C: STUN Binding-Request
    C-->>-S: STUN Binding-Success
    note left of S: 2.5 秒経過
    S->>+C: STUN Binding-Request
    C-->>-S: STUN Binding-Success

connected -> checking

正常な接続状態である connected から一時的に反応が無く checking 状態へ切り替わるシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒経過したが反応がない
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1.0 秒経過
    S->>C: STUN Binding-Request
    note left of S: 1.0 秒経過
    S->>C: STUN Binding-Request

checking -> disconnected

一時的に反応が無い checking の状態が続いたため、 切断判断をするために短い間隔で疎通パケットを送信する disconnected 状態へ切り替わるシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒経過したが反応がない
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1.0 秒間隔で 5 秒間送り続けてるが反応がない
    note over S: ICE State disconnected
    S->>C: STUN Binding-Request
    note left of S: 50 ミリ秒
    S->>C: STUN Binding-Request

disconnected -> failed

切断判断をするため短い間隔で疎通パケットを送り続けたが、反応が無かったため failed へと切り替わるシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒経過したが反応がない
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1 秒間隔で 5 秒間送り続けてるが反応がない
    note over S: ICE State disconnected
    S->>C: STUN Binding-Request
    note left of S: 50 ミリ秒間隔で 10 秒間送り続けてるが反応がない
    note over S: ICE State failed
    note left of S: S はクライアントを切断したと見なし切断処理を行う

disconnected -> checking -> connected

一定時間、不通になっていたため状態が disconnected になっていましたが、 checking を経て connected まで状態が戻るシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒経過したが反応がない
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1 秒間隔で 5 秒間送り続けてるが反応がない
    note over S: ICE State disconnected
    S->>C: STUN Binding-Request
    note left of S: 50 ミリ秒間隔で 10 秒間送り続ける
    C-->>S: STUN Binding-Success
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1 秒間隔で 5 秒間送り続ける
    C-->>S: STUN Binding-Success
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒間隔で送り続ける
    C-->>S: STUN Binding-Success
© Copyright 2024, Shiguredo Inc Created using Sphinx 8.1.3