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

依存関係に `spring_boot_starter_web` があれば、`@WebSocketEndpoint` の Bean は、Web サーバーのポートのあるパスへの WebSocket の接続を受け付けます。そのメソッドは、接続が開いたとき (`@OnOpen`)、メッセージごと (`@OnMessage`)、閉じたとき (`@OnClose`)、エラー時 (`@OnError`) に呼ばれます。名前は Jakarta の `@ServerEndpoint` に従います。

## 使う理由

チャット、ライブのダッシュボード、ゲームのサーバーは、接続を受け付け、メッセージを順に読み、返信し、ルームの全員に送り出す必要があります。エンドポイントの Bean はこれを、他の Bean と同じくコンストラクター注入を使い、いくつかのアノテーション付きメソッドで表します。ハンドシェイクは普通の HTTP リクエストなので、Web スターターのフィルターを通り、セキュリティフィルターはエンドポイントが受け取る前にそれを認証します。

## 例

```dart
// パスごとに一つのルームを持つチャット: /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` | ブラウザーが接続してよいオリジン全体 ([ハンドラー、オリジン、ブロードキャスト](handlers.md) を参照)。 |
| `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 アプリ) に含まれ、ブラウザービルドには含まれません。ブラウザービルドはどのみちサーバーを動かせません。アプリケーションはそのために何もしません。ジェネレーターが両方のモジュールを列挙します。コンテキストを手で組み立てるテストは、両方を指定します ([テスト](testing.md#サーバーのエンドポイント) を参照)。

### isolate のプールがある場合

`server.isolates.count` が 1 より大きいと、Web サーバーの [プール](../spring-boot-starter-web/server/isolates.md) のすべての 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) との対応

```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` は不要です。

## 関連項目

- [ハンドラー、オリジン、ブロードキャスト](handlers.md)
- [Web スターターの WebSocket](../spring-boot-starter-web/server/websocket.md)
- [isolate のプール](../spring-boot-starter-web/server/isolates.md)
- [テスト](testing.md)
