# 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` が設定されています。 詳細は _sora_conf-ice_connection_state_disconnected_timeout をご確認ください。 ### ice_connection_state_failed_timeout この値は Sora が ICE コネクションステートを failed へと遷移する際にクライアントからの応答を待つ時間です。 デフォルトでは `10 s` が設定されています。 詳細は _sora_conf-ice_connection_state_failed_timeout をご確認ください。 ## ウェブフック コネクションの状態が `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` だった合計時間(ミリ秒)の合計が入ります ```javascript { // 色々省略してます "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 } } } ``` ## シーケンス図 > **重要** > > 図のタイムアウト値はデフォルト値を採用しています。 ### connected 正常な接続状態である connected を継続しているシーケンス図です。 ```mermaid 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 状態へ切り替わるシーケンス図です。 ```mermaid 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 状態へ切り替わるシーケンス図です。 ```mermaid 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 へと切り替わるシーケンス図です。 ```mermaid 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 まで状態が戻るシーケンス図です。 ```mermaid 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 ```