WebSocket トランスポート

WebSocket は開いたままの接続で、両側がいつでもメッセージを送れます。チャット、リアルタイムの更新、ゲームなどです。WebSocketTransport.connect(url) は接続を開き、WebSocketSession を返します。その受信メッセージは Stream です。その上に載る宣言的なクライアント、つまり @WebSocketClient を付けたインターフェースは spring_boot_starter_websocket から来ます。

使う理由

dart:io とブラウザーには、制限もエラーも異なる別々の WebSocket クラスがあります。Spring の送信の制限とクローズステータスを持つ、両者を覆う一つのインターフェースがあれば、同じコードがサーバーでも、Flutter アプリでも、Web でも動き、テストではネットワークを置き換えられます。

例

final sockets = platformWebSocketTransport();
final session = await sockets.connect(
  Uri.parse('wss://chat.neon.books/ws'),
  headers: HttpHeaders({'Authorization': 'Bearer $token'}), // Web では使えない
  timeout: const Duration(seconds: 5),
);
session.messages.listen(log.info);
session.sendMessage('{"text":"hi"}');
await session.close(); // CloseStatus.normal。理由を伝えるには:
// await session.close(CloseStatus.policyViolation.withReason('no token'));

トランスポート

トランスポート プラットフォーム インポート
platformWebSocketTransport(maxTextMessageSize:, maxBinaryMessageSize:) 下の 2 つのどちらかを選ぶ package:spring_web_dart/spring_web_dart.dart
IoWebSocketTransport VM、Android・iOS・デスクトップの Flutter (dart:io の WebSocket) package:spring_web_dart/io.dart
BrowserWebSocketTransport Web、Flutter Web (dart:js_interop を通した WebSocket) package:spring_web_dart/browser.dart
MockWebSocketTransport テスト package:spring_web_dart/testing.dart、または spring_boot_starter_test

WebSocketSession

メンバー 意味
messages 受信メッセージ: テキストフレームなら String、バイナリなら Uint8List。
sendMessage(message) String (テキスト) または List<int> (バイナリ)。待たない。
acceptedProtocol サーバーが選んだサブプロトコル。
isOpen セッションが開いているかどうか。
close([status]) 閉じる。デフォルトは CloseStatus.normal。
closeStatus どのように閉じたか。
flush() IoWebSocketSession のみ: 送ったものが出ていくまで待つ。

CloseStatus には定数 (normal、goingAway、policyViolation、noCloseFrame 1006、sessionNotReliable 4500...)、withReason(text)、equalsCode(other) があります。

送信とバックプレッシャー

sendMessage は待ちません。メッセージはネットワークが受け取るまでメモリで待ちます。dart:io (IoWebSocketSession。クライアントと Web スターターのサーバーの両方) では、Spring の ConcurrentWebSocketSessionDecorator と同じく、512 KB を超えるものが待っているか、送ったものが 10 秒以内に出ていかないと、セッションはあきらめます。接続は切られ、closeStatus は 4500 です。そのため、ネットワークが受け取るより速く送るループは 4500 で終わります。ネットワークのペースで進むには、各メッセージの後に flush() を await してください。

// 大きなエクスポートを、サーバーが読む速さで送る。
final session = await IoWebSocketTransport().connect(url) as IoWebSocketSession;
for (final chunk in export) {
  session.sendMessage(chunk);
  await session.flush(); // 接続が終わると WebSocketException で失敗する
}

その他の制限は IoWebSocketTransport(sendBufferSizeLimit:, sendTimeLimit:) で設定します。

受信

ハンドシェイク

Spring (Java) との対応

WebSocketSession session = new StandardWebSocketClient()
    .execute(handler, "wss://chat.neon.books/ws").get();

WebSocketSession は受信メッセージを Stream として渡します。Spring では WebSocketHandler が呼ばれます。sendMessage は TextMessage や BinaryMessage ではなく String やバイトを受け取り、ブロックしません (Spring のものはブロックします)。flush() を使ってください。closeStatus はセッションがどのように閉じたかを示します。Spring ではこれを afterConnectionClosed に渡します。

関連項目