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:) で設定します。
受信
- サーバーからの 8 KB (テキストまたはバイナリ。Tomcat のデフォルト) を超えるメッセージは、
dart:ioでは読まれません。セッションは 1009 (メッセージが大きすぎる) で閉じられます。テキストの制限は UTF-8 のバイト数で数えます。IoWebSocketTransport(maxTextMessageSize:, maxBinaryMessageSize:)またはplatformWebSocketTransport(maxTextMessageSize: ...)で引き上げます (-1: 上限なし)。ブラウザーには制限がありません。 - メッセージが送信を待っている間も接続は読まれ続けるため、どちらも大量に送る 2 つの側が互いを待つことはありません。
- 切れた接続は、
closeStatus1006 とエラーを理由として、messagesを終わらせます。 - メッセージのフラグメントの間の ping にはすぐに応答し、メッセージは丸ごと届きます。
- 誰も購読する前に閉じたセッションでも、クローズが終わると終わる
messagesが得られます。
ハンドシェイク
- ブラウザーはハンドシェイクで独自のヘッダーを送らないため、
headersが空でないとBrowserWebSocketTransportは失敗します。Web では、トークンをクエリパラメーターかプロトコルとして渡してください。 - RFC 6455 の求めるとおり、クライアントが提示していないサブプロトコルや何らかの拡張 (何も提示しないため、メッセージは圧縮されません) をサーバーが選ぶと、ハンドシェイクは失敗します。
- ブラウザーと同じく、リダイレクトはたどられません。
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 に渡します。