ハンドラー、オリジン、ブロードキャスト
@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 との違い
- ハンドラーのメソッドが投げたエラーは
handleTransportErrorに渡され、ハンドラーが閉じない限り接続は開いたままです。Spring は 1011 で閉じます。AbstractWebSocketHandler.handleTransportErrorは何もしないため、ログに出したり閉じたりするにはオーバーライドしてください。 setAllowedOrigins、setAllowedOriginPatterns、setSupportedProtocolsは、それ以前に設定した値に追加します。Spring のものは置き換えます。HandshakeInterceptorが適用されるのは configurer のハンドラーだけで、@WebSocketEndpointには適用されません。Web のフィルターは両方をカバーします。@EnableWebSocketは不要です。
オリジン
Spring の OriginHandshakeInterceptor と同じく、サーバー自身のオリジン (同じスキーム、ホスト、ポート。ポートがなければスキームのデフォルト) から接続するブラウザーは受け入れられ、別のオリジンからのものはエンドポイントのルールが許可する場合だけ受け入れられます。それ以外は 403 を受け取ります。ルールは Web スターターの CORS のものです。
allowedOrigins/setAllowedOriginsはオリジン全体で、大文字小文字を区別せずに比較されます ('https://chat.example')。'*'は任意のオリジンを許可します。allowedOriginPatterns/setAllowedOriginPatternsは大文字小文字を区別して比較されます。*は任意のテキストに一致し ('https://*.chat.example'はhttps://eu.chat.exampleに一致し、https://chat.exampleには一致しません。'*.chat.example'は任意のスキームに一致します)、末尾のポートリストは列挙したポート ('http://localhost:[3000,3001]')、または[*]で任意のポートかポートなしに一致します。- 値にはカンマで区切って複数を列挙でき、末尾の
/は無視されます。 Originを送らないクライアント (アプリ、サーバー) は受け入れられます。それらはフィルターかHandshakeInterceptorで認証してください。
Spring との違い (ブラウザーが送るものについてはありません): 1024 文字を超える Origin は、ルールにかかわらず 403 を受け取ります。サーバー自身のオリジンは、ホストの大文字小文字にかかわらず認識されます。URL でない Origin は 403 を受け取ります (Spring は 500 で失敗します)。
判断するのはエンドポイントのオリジンだけです。Web スターターの addCorsMappings のルールと @CrossOrigin はコントローラーのためのもので、ハンドシェイクには適用されません。エンドポイントのパスのルールを持つ corsConfigurationSource という名前の CorsConfigurationSource の Bean だけは、Spring Security がチェックするのと同じく、セキュリティスターターのフィルターによってチェックもされます。
ブロードキャスト
WebSocketSessionRegistry は、開いているセッションをエンドポイントのパスごとに保持します。パスはエンドポイントに書いたとおりです (/ws/rooms/neon ではなく /ws/rooms/{room})。セッションはハンドシェイクが成功すると加わり、閉じると外れます。
broadcast(pattern, message)はStringをテキストとして、バイトをバイナリとして、その他を JSON として送り、その間に閉じたセッションはスキップします。パターンとしてnullを渡すと、すべてのエンドポイントに送ります。sessions([pattern])は開いているセッションを列挙します。たとえば一つのルームに送るには、session.pathVariables['room']やsession.attributesでフィルターします。
サーバーの isolate のプール があると、各 isolate は、自分が受け入れたセッションを保持する自分のレジストリを持ちます。broadcast はそれらに届き、他の isolate のセッションには届きません。サーバーのエンドポイント を参照してください。
Spring に対応するものはありません。Spring のアプリケーションはそうしたリストを自分で保持します。