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

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

## 使う理由

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

## 例

```dart
// エコーハンドラーは /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 のプール](../spring-boot-starter-web/server/isolates.md) があると、各 isolate は、自分が受け入れたセッションを保持する自分のレジストリを持ちます。`broadcast` はそれらに届き、他の isolate のセッションには届きません。[サーバーのエンドポイント](server-endpoints.md#isolate-のプールがある場合) を参照してください。

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

## 関連項目

- [サーバーのエンドポイント](server-endpoints.md)
- [Web スターターの CORS](../spring-boot-starter-web/cors.md)
- [ハンドラーマッピング](../spring-boot-starter-web/server/handler-mappings.md)
