タイムアウト機能¶

概要¶

Sora Flutter SDK は WebRTC 接続のライフサイクル各段階でタイムアウト機能を提供します。これにより、無限待機を防ぎ、より堅牢なアプリケーションを構築できます。

タイムアウトを設定するには SoraConnectionConfig の timeoutOptions に SoraTimeoutOptions を指定します。 timeoutOptions は省略できますが、指定する値は SoraTimeoutOptions です。

設定可能なタイムアウト¶

対象外のタイムアウト¶

次のタイムアウトは SoraTimeoutOptions では変更できません。

• rpc(): SoraRpcOptions.timeout (ミリ秒) で呼び出しごとに指定します。未指定の場合はタイムアウトしません。詳細は RPC 機能 をご確認ください
• replaceVideoTrack(): 映像トラックの差し替え処理に 10 秒の固定タイムアウトが適用されます
• getStats(): 統計情報の取得に 5 秒の固定タイムアウトが適用されます。詳細は 統計情報 をご確認ください

使用方法¶

final config = SoraConnectionConfig(
  signalingUrls: ['wss://example.com/signaling'],
  channelId: 'channel-id',
  role: SoraRole.sendrecv,
);

final config = SoraConnectionConfig(
  signalingUrls: ['wss://example.com/signaling'],
  channelId: 'channel-id',
  role: SoraRole.sendrecv,
  timeoutOptions: SoraTimeoutOptions(
    connectionTimeout: Duration(seconds: 60),
    disconnectWaitTimeout: Duration(seconds: 15),
    signalingCandidateTimeout: Duration(seconds: 10),
  ),
);

エラーハンドリング¶

接続処理または切断処理を失敗させるタイムアウトが発生した場合は、 connect() / disconnect() が例外を投げたうえで、 conn.events の SoraConnectionErrorEvent でも通知されます。

• connectionTimeout 超過: connect() が TimeoutException を投げます
• disconnectWaitTimeout 超過: disconnect() が TimeoutException を投げます
• 最後の候補 URL またはリダイレクト先での signalingCandidateTimeout 超過: connect() が StateError を投げます

例外と SoraConnectionErrorEvent は同じタイムアウトに対して両方通知されます。接続処理の失敗の分岐は connect() / disconnect() の例外で行い、 SoraConnectionErrorEvent は接続状態の表示やログ出力に利用するのが基本です。

最後以外の候補 URL が signalingCandidateTimeout を超えても、後続の候補 URL への接続に成功した場合は例外を投げず、 SoraConnectionErrorEvent も通知しません。

リダイレクト先の signalingCandidateTimeout 超過では、別の候補 URL への切り替えは行われません。 connect() の完了前であれば connect() が StateError を投げ、接続完了後であれば SoraConnectionErrorEvent の通知だけが行われます。

タイムアウトの対象外のエラーもあります。次のエラーは例外と SoraConnectionErrorEvent のどちらか一方でのみ通知されます。

• rpc() のタイムアウト: TimeoutException が rpc() の呼び出し元へ返るのみです。 SoraConnectionErrorEvent は通知されません
• 接続確立後に発生するエラー (例: websocket_error / camera_open_error): connect() の例外ではなく SoraConnectionErrorEvent でのみ通知されます

SoraTimeoutEvent は WebSocket の reason が TIMEOUT の場合に通知されます。ただし、切断処理中や PeerConnection の接続確立後は通知されません。タイムアウトの検知は SoraConnectionErrorEvent と connect() / disconnect() の例外で行うのが基本です。

final conn = await Sora.createConnection(config);

conn.events.listen((event) {
  if (event case SoraConnectionErrorEvent(:final code, :final message)) {
    switch (code) {
      case SoraErrorCode.connectionTimeout:
        print('接続タイムアウト: ${message ?? ''}');
      case SoraErrorCode.disconnectTimeout:
        print('切断タイムアウト: ${message ?? ''}');
      case SoraErrorCode.signalingCandidateTimeout:
        print('シグナリング接続タイムアウト: ${message ?? ''}');
    }
  }
});

リトライロジック¶

タイムアウトが発生した場合のリトライ処理例です。複数の候補 URL は SDK が自動で試行するため、この例は全候補 URL の接続に失敗した後の接続全体の再試行だけを扱います。

conn.events は connect() より前に購読してください。全候補 URL の signalingCandidateTimeout では、 connect() が StateError を投げるため、 SoraConnectionErrorEvent.code を確認して再試行対象を判定します。その他の StateError は再試行しません。

import 'dart:async';

import 'package:sora_sdk/sora_sdk.dart';

Future<SoraConnection> connectWithRetry(
  SoraConnectionConfig config,
  int maxRetries,
) async {
  int retries = 0;
  while (true) {
    final conn = await Sora.createConnection(config);
    var candidateTimeout = false;
    var connected = false;
    final subscription = conn.events.listen((event) {
      if (event is SoraConnectionErrorEvent &&
          event.code == SoraErrorCode.signalingCandidateTimeout) {
        candidateTimeout = true;
      }
    });

    try {
      await conn.connect();
      connected = true;
      return conn;
    } on TimeoutException catch (error, stackTrace) {
      if (retries >= maxRetries) {
        Error.throwWithStackTrace(error, stackTrace);
      }
      retries++;
      print('接続タイムアウト (リトライ $retries/$maxRetries)');
    } on StateError catch (error, stackTrace) {
      // StreamController は非同期でイベントを配信するため、
      // connect() の例外を受け取った後にイベントを処理する時間を確保します。
      await Future<void>.delayed(Duration.zero);
      if (!candidateTimeout) {
        Error.throwWithStackTrace(error, stackTrace);
      }
      if (retries >= maxRetries) {
        Error.throwWithStackTrace(error, stackTrace);
      }
      retries++;
      print('シグナリング候補タイムアウト (リトライ $retries/$maxRetries)');
    } finally {
      await subscription.cancel();
      if (!connected) {
        await conn.dispose();
      }
    }
    await Future<void>.delayed(const Duration(seconds: 2));
  }
}

推奨タイムアウト値¶

タイムアウト値は環境やネットワーク状況に応じて調整してください。