サーバーのエンドポイント
依存関係に spring_boot_starter_web があれば、@WebSocketEndpoint の Bean は、Web サーバーのポートのあるパスへの WebSocket の接続を受け付けます。そのメソッドは、接続が開いたとき (@OnOpen)、メッセージごと (@OnMessage)、閉じたとき (@OnClose)、エラー時 (@OnError) に呼ばれます。名前は Jakarta の @ServerEndpoint に従います。
使う理由
チャット、ライブのダッシュボード、ゲームのサーバーは、接続を受け付け、メッセージを順に読み、返信し、ルームの全員に送り出す必要があります。エンドポイントの Bean はこれを、他の Bean と同じくコンストラクター注入を使い、いくつかのアノテーション付きメソッドで表します。ハンドシェイクは普通の HTTP リクエストなので、Web スターターのフィルターを通り、セキュリティフィルターはエンドポイントが受け取る前にそれを認証します。
例
// パスごとに一つのルームを持つチャット: /ws/rooms/neon、/ws/rooms/dart...
@WebSocketEndpoint('/ws/rooms/{room}', allowedOrigins: ['https://chat.example'])
@Log()
class ChatEndpoint {
ChatEndpoint(this.sessions);
final WebSocketSessionRegistry sessions;
// エンドポイントはすべての接続で共有される: 接続ごとの状態は session.attributes に置く。
@OnOpen()
void open(ServerWebSocketSession session, @PathVariable() String room, Principal? user) {
session.attributes['room'] = room;
session.attributes['user'] = user?.name ?? 'guest';
}
@OnMessage()
Ack message(@PathVariable() String room, ChatMessage message) {
sessions.broadcast('/ws/rooms/{room}', message); // エンドポイントの開いているすべてのセッションに
return Ack(room: room, received: message.text); // 返信。JSON として送り返される
}
@OnClose()
void close(ServerWebSocketSession session, CloseStatus status) =>
log.info('${session.id} left: ${status.code}');
@OnError()
void error(ServerWebSocketSession session, Object error) =>
session.sendMessage('error: $error');
}
@Introspected()
class Ack {
const Ack({required this.room, required this.received});
final String room;
final String received;
}
@WebSocketEndpoint
| 属性 | 意味 |
|---|---|
path (位置引数) |
コントローラーと同じパスパターン ({room}、{*rest})。 |
allowedOrigins |
ブラウザーが接続してよいオリジン全体 (ハンドラー、オリジン、ブロードキャスト を参照)。 |
allowedOriginPatterns |
オリジンパターン (https://*.chat.example、http://localhost:[*])。 |
protocols |
エンドポイントが話すサブプロトコル。クライアントが提示するもののうち、リストにある最初のものが選ばれる。そのどれも提示しないクライアントも、プロトコルなしで接続する。 |
name |
Bean の名前。 |
メソッドのパラメーター
メソッドは必要なものを任意の順で受け取ります。
| パラメーター | 値 |
|---|---|
ServerWebSocketSession (または WebSocketSession) |
接続。 |
@PathVariable() String room |
パスの {room} (別の名前には @PathVariable('id'))。int、double、bool、列挙型... は ConversionService で変換される。変換できない値はハンドシェイクに 400 で応答する。 |
Principal? |
ハンドシェイクのユーザー (匿名なら null)。 |
@OnMessage でのメッセージ |
String (テキスト)、Uint8List (バイナリ)、またはその他の型 (ObjectMapper を通して JSON として読まれる)。 |
@OnClose での CloseStatus |
接続が閉じた理由。 |
@OnError でのエラー |
メソッドが投げたもの、または接続のエラー。 |
動作
- 返信。
@OnMessageが返したものは、Futureを待った後に送り返されます。Stringはテキストとして、バイトはバイナリとして、その他は JSON として。voidとnullは何も送りません。 - 順序とバックプレッシャー。 一つの接続のメッセージは、順に一つずつ処理されます。一つを処理している間は接続を読まないため、ハンドラーの処理より速く送るクライアントは、サーバーのメモリを埋めるのではなく、ネットワークによって抑えられます。
- 受信のサイズ。
server.websocket.max-text-message-sizeやmax-binary-message-size(Tomcat と同じくデフォルトは 8 KB) より大きいメッセージは、接続を 1009 で閉じます。 - 遅い読み手。 ゆっくり読むクライアントに送ったものは、
server.websocket.send-buffer-size-limit(512 KB) とsend-time-limit(10 秒) までメモリで待ちます。どちらかを超えると接続は切られ、@OnCloseは 4500 (CloseStatus.sessionNotReliable) を受け取ります。その間にクライアントが去ると、セッションは 1006 (CloseStatus.noCloseFrame) で閉じられます。session.close(status)の後は、@OnCloseはそのステータスを受け取ります。いずれの場合も、セッションはWebSocketSessionRegistryから外れます。 - エラー。 例外は
@OnErrorメソッドに渡され、接続は開いたままです。@OnErrorメソッドがなければ、ログに出され、接続は 1011 (サーバーエラー) で閉じられます。これは@OnOpenにも当てはまります。接続について失敗したその他のことはspring.websocket.serverにログ出力され、接続を 1011 で閉じます。プロセスを終わらせることは決してありません。 - クライアントを追い返す。
@OnOpenはセッションを自分で閉じられます。そのとき@OnCloseはステータスを一度だけ受け取ります。クライアントがクローズを見る前に送ったメッセージは、まだ@OnMessageに届くことがあります。そこでsession.isOpenを確認してください。 - ハンドシェイクでないもの。 ハンドシェイクでないそのパスへのリクエストはプレーンテキストの 400 を、繰り返されたり不正だったりする
Sec-WebSocket-Keyは 400 の problem を、別のSec-WebSocket-Versionは 426 を受け取ります。 - セッション ID は、Spring と同じくランダムな UUID (
session.id) です。
サーバー側のある場所
スターターのサーバー側は、独立したモジュール springBootStarterWebsocketServerAutoConfiguration です。webSocketSessionRegistry Bean と、ハンドシェイクをルーティングする webSocketHandlerMapping です。これは native だけです。dart:io が存在するビルド (Dart VM、AOT 実行ファイル、スマートフォンやデスクトップの Flutter アプリ) に含まれ、ブラウザービルドには含まれません。ブラウザービルドはどのみちサーバーを動かせません。アプリケーションはそのために何もしません。ジェネレーターが両方のモジュールを列挙します。コンテキストを手で組み立てるテストは、両方を指定します (テスト を参照)。
isolate のプールがある場合
server.isolates.count が 1 より大きいと、Web サーバーの プール のすべての isolate が、自分のエンドポイントと自分の WebSocketSessionRegistry を持ちます。接続は、開いている間ずっと、そのハンドシェイクを受け取った isolate に属します。
broadcastは、送信する isolate に接続しているクライアントに届きます。他の isolate のクライアントには届きません。メンバーが四つの isolate に分散しているチャットルームでは、メッセージを見るのはそのおよそ 4 分の 1 です。sessions()は、自分の isolate のセッションを列挙します。- エンドポイントがフィールドに持つ状態 (誰がルームにいるか) も isolate ごとです。
- プールを離れる isolate は、自分のセッションを閉じます。クライアントは再び接続し、別の isolate に届きます。
プールは、最初に isolate を追加するときにログに出す警告の中で、このレジストリを示します (Each isolate keeps its own WebSocket sessions in memory, ...)。すべてのクライアントに届けるには、各 isolate がそのメッセージを知らなければなりません。すべての isolate が聞いているもの (メッセージブローカー、データベースの通知) にメッセージを発行し、それぞれに自分のセッションへブロードキャストさせてください。
起動時のチェック
一つのパスに 2 つのハンドラー、パスにない @PathVariable や、String から変換できるもののない型の @PathVariable、上記のどの種類でもないパラメーター、同じアノテーションを持つ複数のメソッド、あるいは @OnOpen、@OnMessage、@OnClose のどれも持たないエンドポイントは、問題の一覧とともにアプリケーションを止めます。
セキュリティ
ハンドシェイクは Web のフィルターを通る HTTP の GET です。spring_boot_starter_security がある場合は、ルール (requestMatchers('/ws/**').authenticated()) でパスを保護すれば、エンドポイントはユーザーを Principal として受け取ります。ブラウザーはハンドシェイクでヘッダーを送れないため、セッションの Cookie か、クエリのトークンを送ります。
Spring (Java) との対応
@ServerEndpoint("/ws/rooms/{room}")
public class ChatEndpoint {
@OnMessage
public void message(@PathParam("room") String room, String text, Session session) { ... }
}
Spring には独自のアノテーション付きエンドポイントがありません。WebSocketHandler を登録するか、ServerEndpointExporter を通して Jakarta の @ServerEndpoint クラスを登録します。ここではエンドポイントはコンストラクター注入を使うシングルトンの Bean で (Jakarta は接続ごとに一つ生成します)、@PathVariable が @PathParam の代わりになります。@EnableWebSocket は不要です。