ハンドラー、オリジン、ブロードキャスト

@WebSocketEndpoint のほかに、Spring のより低レベルなスタイルも使えます。WebSocketConfigurer の Bean がパスに登録する WebSocketHandler のオブジェクトを、HandshakeInterceptor とともに使うものです。ブラウザーからのすべてのハンドシェイクは、エンドポイントの許可されたオリジンに対してチェックされます。WebSocketSessionRegistry は開いているセッションを保持し、それらすべてに一度に送れるようにします。

使う理由

Spring から移植したコードはハンドラーをそのまま保てますし、一つのハンドラーで複数のパスを処理できます。オリジンのチェックは、他のサイトのページがユーザーの Cookie を使って接続を開くのを防ぎます。ルームや全員へのブロードキャストは、Bean にする価値があるほどよくあることです。

例

// エコーハンドラーは /ws/echo で、ショップのページにだけ応答する。
@Configuration()
class WsConfig implements WebSocketConfigurer {
  @override
  void registerWebSocketHandlers(WebSocketHandlerRegistry registry) => registry
      .addHandler(EchoHandler(), ['/ws/echo'])
      .setAllowedOrigins(['https://shop.example'])
      .setSupportedProtocols(['echo.v1'])
      .addInterceptors([TokenInterceptor()]);
}

final class EchoHandler extends TextWebSocketHandler {
  @override
  void handleTextMessage(ServerWebSocketSession session, String text) =>
      session.sendMessage('echo: $text (${session.attributes['token']})');
}

// トークンを持つクライアントだけが接続する。ハンドラーは session.attributes['token'] でそれを見つける。
final class TokenInterceptor with HandshakeInterceptor {
  @override
  bool beforeHandshake(request, response, attributes) {
    final token = request.queryParameters['token']?.firstOrNull;
    if (token == null) return false;                  // 403
    attributes['token'] = token;                      // session.attributes になる
    return true;
  }
}

// /ws/news のすべてのクライアントがお知らせを受け取る。
@Service()
class Announcer {
  Announcer(this.sessions);

  final WebSocketSessionRegistry sessions;

  void announce(Object news) => sessions.broadcast('/ws/news', news);  // JSON として
}

型

型 Spring 内容
WebSocketHandler WebSocketHandler afterConnectionEstablished、handleMessage (String または Uint8List)、handleTransportError、afterConnectionClosed。
AbstractWebSocketHandler、TextWebSocketHandler 同じ テキストとバイナリのメッセージを別々のメソッドで。バイナリメッセージは TextWebSocketHandler の接続を閉じる (1003)。
WebSocketConfigurer、WebSocketHandlerRegistry 同じ addHandler(handler, paths)、続いて setAllowedOrigins、setAllowedOriginPatterns、setSupportedProtocols、addInterceptors。
HandshakeInterceptor 同じ beforeHandshake(request, response, attributes): false は拒否する (自分で応答していなければ 403)。afterHandshake(request, error)。
ServerWebSocketSession サーバー側の WebSocketSession id、handshakeHeaders、attributes、principal、pathVariables、isOpen、sendMessage、sendJson、close。
WebSocketSessionRegistry なし 開いているセッション: sessions([pattern])、broadcast(pattern, message) (null: すべてのエンドポイント)。
WebSocketHandlerMapping WebSocketHandlerMapping ハンドシェイクをマッピングする。Web スターターのディスパッチャーは、コントローラーの後にこれに問い合わせる。

セッションの受信メッセージは handleMessage に渡されます。一度しか購読できないその messages ストリームは、サーバー自身が読みます。

Spring との違い

オリジン

Spring の OriginHandshakeInterceptor と同じく、サーバー自身のオリジン (同じスキーム、ホスト、ポート。ポートがなければスキームのデフォルト) から接続するブラウザーは受け入れられ、別のオリジンからのものはエンドポイントのルールが許可する場合だけ受け入れられます。それ以外は 403 を受け取ります。ルールは Web スターターの CORS のものです。

Spring との違い (ブラウザーが送るものについてはありません): 1024 文字を超える Origin は、ルールにかかわらず 403 を受け取ります。サーバー自身のオリジンは、ホストの大文字小文字にかかわらず認識されます。URL でない Origin は 403 を受け取ります (Spring は 500 で失敗します)。

判断するのはエンドポイントのオリジンだけです。Web スターターの addCorsMappings のルールと @CrossOrigin はコントローラーのためのもので、ハンドシェイクには適用されません。エンドポイントのパスのルールを持つ corsConfigurationSource という名前の CorsConfigurationSource の Bean だけは、Spring Security がチェックするのと同じく、セキュリティスターターのフィルターによってチェックもされます。

ブロードキャスト

WebSocketSessionRegistry は、開いているセッションをエンドポイントのパスごとに保持します。パスはエンドポイントに書いたとおりです (/ws/rooms/neon ではなく /ws/rooms/{room})。セッションはハンドシェイクが成功すると加わり、閉じると外れます。

サーバーの isolate のプール があると、各 isolate は、自分が受け入れたセッションを保持する自分のレジストリを持ちます。broadcast はそれらに届き、他の isolate のセッションには届きません。サーバーのエンドポイント を参照してください。

Spring に対応するものはありません。Spring のアプリケーションはそうしたリストを自分で保持します。

関連項目