WebSocket
依存関係に spring_boot_starter_websocket も加えると、Web サーバーはそのポートで WebSocket 接続も受け付けます。server.websocket.* プロパティは、セッションが読むメッセージのサイズと、送信待ちとして保持できる量を制限します。
使う理由
WebSocket は開いたままで、双方向にメッセージを運びます。チャット、リアルタイムの価格、ゲーム、通知などです。HTTP API と同じサーバー、同じポート、同じフィルター (ハンドシェイクの前段のセキュリティ) が必要です。
開いた接続はリスクでもあります。クライアントが一つの巨大なメッセージを送ったり、サーバーが送り続けている間に読むのをやめたりして、サーバーのメモリを使い果たさせるかもしれません。上限は、そうしたセッションを早めに閉じます。
例
# pubspec.yaml
dependencies:
spring_boot_starter_web: ^0.9.0
spring_boot_starter_websocket: ^0.9.0
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'package:spring_boot_starter_websocket/spring_boot_starter_websocket.dart';
// ws://localhost:8080/ws/rooms/neon
@WebSocketEndpoint('/ws/rooms/{room}')
class ChatEndpoint {
ChatEndpoint(this.sessions);
final WebSocketSessionRegistry sessions;
@OnMessage()
Ack message(@PathVariable() String room, ChatMessage message) {
sessions.broadcast('/ws/rooms/{room}', message); // 開いているすべてのセッションへ
return Ack(room: room, received: message.text); // JSON での返信
}
}
@Introspected()
class ChatMessage {
const ChatMessage({required this.text});
final String text;
}
@Introspected()
class Ack {
const Ack({required this.room, required this.received});
final String room;
final String received;
}
# lib/resources/application.yml
server:
websocket:
max-text-message-size: 64KB
max-binary-message-size: 1MB
send-buffer-size-limit: 1MB
send-time-limit: 20s
server.websocket.max-text-message-size=64KB
server.websocket.max-binary-message-size=1MB
server.websocket.send-buffer-size-limit=1MB
server.websocket.send-time-limit=20s
@WebSocketEndpoint、WebSocketHandler、WebSocketConfigurer、ハンドシェイクインターセプター、オリジン、ブロードキャストは WebSocket スターターに属します。その README で説明されています: spring_boot_starter_websocket, Server endpoints。このページは、Web スターターが加えるもの、つまり接続のサーバー側を扱います。
プロパティ
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
server.websocket.max-text-message-size |
DataSize |
8KB |
セッションが読む最大のテキストメッセージ (UTF-8 のバイト数)。-1: 上限なし。 |
server.websocket.max-binary-message-size |
DataSize |
8KB |
セッションが読む最大のバイナリメッセージ。-1: 上限なし。 |
server.websocket.send-buffer-size-limit |
DataSize |
512KB |
セッションが送信待ちとして保持できる最大量。-1: 上限なし。 |
server.websocket.send-time-limit |
Duration |
10s |
送ったものが出ていくまでにかかってよい最長の時間。-1: 上限なし。 |
server.websocket.max-text-message-size
- 型:
DataSize(8KB、64KB、1MB。単なる数値はバイト)。デフォルト:8KB(Spring での Tomcat のデフォルト)。-1: 上限なし。 - 動作: UTF-8 のバイト数で数えてこれより大きいテキストメッセージは読まれません。セッションは
1009(message too big) で閉じられます。サイズはメッセージを組み立てる前に、メッセージのすべてのフレームにわたって数えられるので、多数の小さなフレームに分けたメッセージでも通り抜けられません。 - ログ:
debugレベルで、spring.web.serverに:WebSocket session at /ws/rooms/neon closed with 1009: a message was larger than the limit。 - 変更する理由: メッセージが 8 KB より大きい場合 (JSON ドキュメント、貼り付けたテキスト)。
- 例:
server.websocket.max-text-message-size=64KB。 - 注意: Tomcat は文字数を数えますが、ここではバイト数を数えます。アクセント記号や絵文字を含む 8,000 文字のテキストは 8 KB を超えることがあります。
server.websocket.max-binary-message-size
- 型:
DataSize。デフォルト:8KB。-1: 上限なし。 - 動作: バイナリメッセージに対する同じ上限 (バイト数)。それより大きいとセッションは
1009で閉じられます。 - 変更する理由: クライアントが画像、音声のチャンク、ファイルを送る場合。
- 例:
server.websocket.max-binary-message-size=1MB。
server.websocket.send-buffer-size-limit
- 型:
DataSize。デフォルト:512KB。-1: 上限なし。 - 動作: セッションが送るものは、クライアントが受け取るまでメモリで待ちます。これより多くが待っていると、セッションは諦めます。接続は切断され (クローズフレームも通らないため)、セッションのクローズステータスは理由付きの
4500(CloseStatus.sessionNotReliable) になります。ハンドラーのafterConnectionClosed(または@OnClose) がそれを受け取ります。 - pong も数えます。 クライアントの ping に応える pong もメッセージと一緒に待つので、ping を送って何も読まないクライアントも上限に達します。
- 読み込みは続きます。 メッセージが待っている間も、セッションはクライアントからの読み込みを続けます。サーバーが大量に送っている間に大量に送るクライアントも、足止めされません。
- ログ:
spring.web.serverへの警告:WebSocket session at /ws/rooms/neon dropped: <reason>。 - 変更する理由: ネットワークが一度に受け取れない 512 KB を超えるまとまり (大きな状態のスナップショット) を送る場合は引き上げる。遅いクライアントが多い場合にメモリを守るには引き下げる。
- 例:
server.websocket.send-buffer-size-limit=2MB。
server.websocket.send-time-limit
- 型:
Duration(10s、500ms。単なる数値はミリ秒)。デフォルト:10s。-1: 上限なし。 - 動作: セッションが送ったものがこの時間内に出ていかないと、同じように接続が切断されます。クローズステータスは
4500です。 - 変更する理由: 遅いモバイルネットワークのクライアントのためには引き上げる。詰まったクライアントを早く切るには引き下げる。
- 例:
server.websocket.send-time-limit=20s。
クライアントのペースで送る
上限に達せずに大量に送るには、各メッセージが出ていくのを待ってから次を送ります。Web スターターのサーバーのセッションは IoWebSocketSession です (@WebSocketEndpoint では、DefaultServerWebSocketSession の delegate)。その flush() は、メモリで待っているものがなくなると完了します。
import 'package:spring_boot_starter_websocket/spring_boot_starter_websocket.dart';
import 'package:spring_web_dart/io.dart' show IoWebSocketSession;
Future<void> sendAll(ServerWebSocketSession session, Stream<String> lines) async {
final raw = session is DefaultServerWebSocketSession ? session.delegate : session;
await for (final line in lines) {
session.sendMessage(line);
if (raw is IoWebSocketSession) {
await raw.flush(); // クライアントが読む速さで送る
}
}
}
IoWebSocketSession は package:spring_web_dart/io.dart から来ます。インポートするには、依存関係に spring_web_dart を追加してください。
flush() は、先に接続が閉じられたり切断されたりすると WebSocketException で失敗します。
ハンドシェイク
ハンドシェイクは、Connection: Upgrade と Upgrade: websocket を持つ通常の HTTP の GET です。そのため:
- フィルターを通ります。 セキュリティのフィルターチェーンは他のリクエストと同じように認証し、フォワードヘッダーが適用され、セッションフィルターが実行されます。
- サーバーがチェックします (RFC 6455)。
| 問題 | 応答 |
|---|---|
Sec-WebSocket-Key がない、二つある、または base64 で 16 バイトでない |
400 |
Sec-WebSocket-Version が二回送られた |
400 |
13 以外のバージョン、またはなし |
Sec-WebSocket-Version: 13 付きの 426 Upgrade Required |
101 Switching Protocolsで応答されます。Content-LengthやTransfer-Encodingは付きません。server.request-timeoutで計測されません。server.ssl.client-auth=needでは、クライアント証明書のないハンドシェイクは、他のリクエストと同じく 403 を受け取ります。- セッションの URI のスキームは
ws、TLS ならwssです。
クローズコード
| コード | いつ |
|---|---|
1001 (going away) |
サーバーの停止時。どちらのシャットダウンモードでも、開いているすべてのセッションが理由 Server stopping で閉じられる |
1006 (CloseStatus.noCloseFrame) |
メッセージが待っている間にクライアントが去った (リセット)。エラーが理由になる。TLS 上でも同様 |
1009 (too big) |
max-text-message-size または max-binary-message-size を超えるメッセージ |
4500 (CloseStatus.sessionNotReliable) |
send-buffer-size-limit または send-time-limit を超えた |
| 独自のもの | サーバーから session.close(status) した後、ハンドラーはそのステータスを受け取る |
ルール
- 圧縮なし。 拡張はネゴシエーションされないので、permessage-deflate は使われません。
server.compression.*は適用されません。 - 一つのポート。 WebSocket と HTTP は
server.port(と TLS) を共有します。 - シャットダウン。 開いているセッションはシャットダウンの開始時に閉じられます。グレースフルな停止はそれらを待ちません。シャットダウン を参照してください。
- 順序。 WebSocket スターターのハンドラーマッピングは、コントローラーの後 (順序 1) に問い合わせられます。ハンドラーマッピング を参照してください。
- テスト。
MockMvc.webSocketはメモリ内でエンドポイントを開きます。テスト を参照してください。
Spring (Java) との対応
@Bean
ServletServerContainerFactoryBean createWebSocketContainer() {
var container = new ServletServerContainerFactoryBean();
container.setMaxTextMessageBufferSize(64 * 1024);
container.setMaxBinaryMessageBufferSize(1024 * 1024);
return container;
}
// そしてセッションごとに:
new ConcurrentWebSocketSessionDecorator(session, 20_000, 1024 * 1024);
重要な違い:
- 上限はプロパティ (
server.websocket.*、このスターター独自のキー) です。Spring はそれらをコードで、コンテナーとセッションのデコレーターに設定します。 - テキストの上限は UTF-8 のバイト数を数えます。Tomcat は文字数を数えます。
- すべてのセッションが送信の上限を持ちます。Spring の
ConcurrentWebSocketSessionDecoratorは、それを STOMP のセッションと、あなたがラップしたセッションにだけ適用します。Tomcat 上の通常のハンドラーは、代わりに送信スレッドをブロックします (Tomcat のブロッキング送信タイムアウト 20 秒まで)。同じように待つにはflush()を await してください。 - permessage-deflate は提供されません。Tomcat はそれをネゴシエーションします。