サーバーのエンドポイント

依存関係に 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 でのエラー メソッドが投げたもの、または接続のエラー。

動作

サーバー側のある場所

スターターのサーバー側は、独立したモジュール springBootStarterWebsocketServerAutoConfiguration です。webSocketSessionRegistry Bean と、ハンドシェイクをルーティングする webSocketHandlerMapping です。これは native だけです。dart:io が存在するビルド (Dart VM、AOT 実行ファイル、スマートフォンやデスクトップの Flutter アプリ) に含まれ、ブラウザービルドには含まれません。ブラウザービルドはどのみちサーバーを動かせません。アプリケーションはそのために何もしません。ジェネレーターが両方のモジュールを列挙します。コンテキストを手で組み立てるテストは、両方を指定します (テスト を参照)。

isolate のプールがある場合

server.isolates.count が 1 より大きいと、Web サーバーの プール のすべての isolate が、自分のエンドポイントと自分の WebSocketSessionRegistry を持ちます。接続は、開いている間ずっと、そのハンドシェイクを受け取った 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 は不要です。

関連項目