
# WebSocket

依存関係に `spring_boot_starter_websocket` も加えると、Web サーバーはそのポートで WebSocket 接続も受け付けます。`server.websocket.*` プロパティは、セッションが読むメッセージのサイズと、送信待ちとして保持できる量を制限します。

## 使う理由

WebSocket は開いたままで、双方向にメッセージを運びます。チャット、リアルタイムの価格、ゲーム、通知などです。HTTP API と同じサーバー、同じポート、同じフィルター (ハンドシェイクの前段のセキュリティ) が必要です。

開いた接続はリスクでもあります。クライアントが一つの巨大なメッセージを送ったり、サーバーが送り続けている間に読むのをやめたりして、サーバーのメモリを使い果たさせるかもしれません。上限は、そうしたセッションを早めに閉じます。

## 例

```yaml
# pubspec.yaml
dependencies:
  spring_boot_starter_web: ^0.9.0
  spring_boot_starter_websocket: ^0.9.0
```

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'package:spring_boot_starter_websocket/spring_boot_starter_websocket.dart';

// ws://localhost:8080/ws/rooms/neon
@WebSocketEndpoint('/ws/rooms/{room}')
class ChatEndpoint {
  ChatEndpoint(this.sessions);
  final WebSocketSessionRegistry sessions;

  @OnMessage()
  Ack message(@PathVariable() String room, ChatMessage message) {
    sessions.broadcast('/ws/rooms/{room}', message); // 開いているすべてのセッションへ
    return Ack(room: room, received: message.text);  // JSON での返信
  }
}

@Introspected()
class ChatMessage {
  const ChatMessage({required this.text});
  final String text;
}

@Introspected()
class Ack {
  const Ack({required this.room, required this.received});
  final String room;
  final String received;
}
```

```yaml
# lib/resources/application.yml
server:
  websocket:
    max-text-message-size: 64KB
    max-binary-message-size: 1MB
    send-buffer-size-limit: 1MB
    send-time-limit: 20s
```

```properties
server.websocket.max-text-message-size=64KB
server.websocket.max-binary-message-size=1MB
server.websocket.send-buffer-size-limit=1MB
server.websocket.send-time-limit=20s
```

`@WebSocketEndpoint`、`WebSocketHandler`、`WebSocketConfigurer`、ハンドシェイクインターセプター、オリジン、ブロードキャストは WebSocket スターターに属します。その README で説明されています: [spring_boot_starter_websocket, Server endpoints](https://github.com/farum-azula/spring_core_dart/blob/main/spring_boot_starter_websocket/README.md)。このページは、Web スターターが加えるもの、つまり接続のサーバー側を扱います。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `server.websocket.max-text-message-size` | `DataSize` | `8KB` | セッションが読む最大のテキストメッセージ (UTF-8 のバイト数)。`-1`: 上限なし。 |
| `server.websocket.max-binary-message-size` | `DataSize` | `8KB` | セッションが読む最大のバイナリメッセージ。`-1`: 上限なし。 |
| `server.websocket.send-buffer-size-limit` | `DataSize` | `512KB` | セッションが送信待ちとして保持できる最大量。`-1`: 上限なし。 |
| `server.websocket.send-time-limit` | `Duration` | `10s` | 送ったものが出ていくまでにかかってよい最長の時間。`-1`: 上限なし。 |

### `server.websocket.max-text-message-size`

- **型:** `DataSize` (`8KB`、`64KB`、`1MB`。単なる数値はバイト)。**デフォルト:** `8KB` (Spring での Tomcat のデフォルト)。**`-1`:** 上限なし。
- **動作:** UTF-8 のバイト数で数えてこれより大きいテキストメッセージは読まれません。セッションは `1009` (message too big) で閉じられます。サイズはメッセージを組み立てる前に、メッセージのすべてのフレームにわたって数えられるので、多数の小さなフレームに分けたメッセージでも通り抜けられません。
- **ログ:** `debug` レベルで、`spring.web.server` に: `WebSocket session at /ws/rooms/neon closed with 1009: a message was larger than the limit`。
- **変更する理由:** メッセージが 8 KB より大きい場合 (JSON ドキュメント、貼り付けたテキスト)。
- **例:** `server.websocket.max-text-message-size=64KB`。
- **注意:** Tomcat は文字数を数えますが、ここではバイト数を数えます。アクセント記号や絵文字を含む 8,000 文字のテキストは 8 KB を超えることがあります。

### `server.websocket.max-binary-message-size`

- **型:** `DataSize`。**デフォルト:** `8KB`。**`-1`:** 上限なし。
- **動作:** バイナリメッセージに対する同じ上限 (バイト数)。それより大きいとセッションは `1009` で閉じられます。
- **変更する理由:** クライアントが画像、音声のチャンク、ファイルを送る場合。
- **例:** `server.websocket.max-binary-message-size=1MB`。

### `server.websocket.send-buffer-size-limit`

- **型:** `DataSize`。**デフォルト:** `512KB`。**`-1`:** 上限なし。
- **動作:** セッションが送るものは、クライアントが受け取るまでメモリで待ちます。これより多くが待っていると、セッションは諦めます。接続は切断され (クローズフレームも通らないため)、セッションのクローズステータスは理由付きの `4500` (`CloseStatus.sessionNotReliable`) になります。ハンドラーの `afterConnectionClosed` (または `@OnClose`) がそれを受け取ります。
- **pong も数えます。** クライアントの ping に応える pong もメッセージと一緒に待つので、ping を送って何も読まないクライアントも上限に達します。
- **読み込みは続きます。** メッセージが待っている間も、セッションはクライアントからの読み込みを続けます。サーバーが大量に送っている間に大量に送るクライアントも、足止めされません。
- **ログ:** `spring.web.server` への警告: `WebSocket session at /ws/rooms/neon dropped: <reason>`。
- **変更する理由:** ネットワークが一度に受け取れない 512 KB を超えるまとまり (大きな状態のスナップショット) を送る場合は引き上げる。遅いクライアントが多い場合にメモリを守るには引き下げる。
- **例:** `server.websocket.send-buffer-size-limit=2MB`。

### `server.websocket.send-time-limit`

- **型:** `Duration` (`10s`、`500ms`。単なる数値はミリ秒)。**デフォルト:** `10s`。**`-1`:** 上限なし。
- **動作:** セッションが送ったものがこの時間内に出ていかないと、同じように接続が切断されます。クローズステータスは `4500` です。
- **変更する理由:** 遅いモバイルネットワークのクライアントのためには引き上げる。詰まったクライアントを早く切るには引き下げる。
- **例:** `server.websocket.send-time-limit=20s`。

### クライアントのペースで送る

上限に達せずに大量に送るには、各メッセージが出ていくのを待ってから次を送ります。Web スターターのサーバーのセッションは `IoWebSocketSession` です (`@WebSocketEndpoint` では、`DefaultServerWebSocketSession` の `delegate`)。その `flush()` は、メモリで待っているものがなくなると完了します。

```dart
import 'package:spring_boot_starter_websocket/spring_boot_starter_websocket.dart';
import 'package:spring_web_dart/io.dart' show IoWebSocketSession;

Future<void> sendAll(ServerWebSocketSession session, Stream<String> lines) async {
  final raw = session is DefaultServerWebSocketSession ? session.delegate : session;
  await for (final line in lines) {
    session.sendMessage(line);
    if (raw is IoWebSocketSession) {
      await raw.flush(); // クライアントが読む速さで送る
    }
  }
}
```

`IoWebSocketSession` は `package:spring_web_dart/io.dart` から来ます。インポートするには、依存関係に `spring_web_dart` を追加してください。

`flush()` は、先に接続が閉じられたり切断されたりすると `WebSocketException` で失敗します。

## ハンドシェイク

ハンドシェイクは、`Connection: Upgrade` と `Upgrade: websocket` を持つ通常の HTTP の `GET` です。そのため:

- **フィルターを通ります。** セキュリティのフィルターチェーンは他のリクエストと同じように認証し、フォワードヘッダーが適用され、セッションフィルターが実行されます。
- **サーバーがチェックします** (RFC 6455)。

| 問題 | 応答 |
|---|---|
| `Sec-WebSocket-Key` がない、二つある、または base64 で 16 バイトでない | `400` |
| `Sec-WebSocket-Version` が二回送られた | `400` |
| `13` 以外のバージョン、またはなし | `Sec-WebSocket-Version: 13` 付きの `426 Upgrade Required` |

- **`101 Switching Protocols` で応答されます。** `Content-Length` や `Transfer-Encoding` は付きません。
- **`server.request-timeout` で計測されません。**
- **`server.ssl.client-auth=need` では**、クライアント証明書のないハンドシェイクは、他のリクエストと同じく 403 を受け取ります。
- **セッションの URI** のスキームは `ws`、TLS なら `wss` です。

## クローズコード

| コード | いつ |
|---|---|
| `1001` (going away) | サーバーの停止時。どちらのシャットダウンモードでも、開いているすべてのセッションが理由 `Server stopping` で閉じられる |
| `1006` (`CloseStatus.noCloseFrame`) | メッセージが待っている間にクライアントが去った (リセット)。エラーが理由になる。TLS 上でも同様 |
| `1009` (too big) | `max-text-message-size` または `max-binary-message-size` を超えるメッセージ |
| `4500` (`CloseStatus.sessionNotReliable`) | `send-buffer-size-limit` または `send-time-limit` を超えた |
| 独自のもの | サーバーから `session.close(status)` した後、ハンドラーはそのステータスを受け取る |

## ルール

- **圧縮なし。** 拡張はネゴシエーションされないので、permessage-deflate は使われません。`server.compression.*` は適用されません。
- **一つのポート。** WebSocket と HTTP は `server.port` (と TLS) を共有します。
- **シャットダウン。** 開いているセッションはシャットダウンの開始時に閉じられます。グレースフルな停止はそれらを待ちません。[シャットダウン](shutdown.md) を参照してください。
- **順序。** WebSocket スターターのハンドラーマッピングは、コントローラーの後 (順序 1) に問い合わせられます。[ハンドラーマッピング](handler-mappings.md) を参照してください。
- **テスト。** `MockMvc.webSocket` はメモリ内でエンドポイントを開きます。[テスト](../testing.md) を参照してください。

## Spring (Java) との対応

```java
@Bean
ServletServerContainerFactoryBean createWebSocketContainer() {
  var container = new ServletServerContainerFactoryBean();
  container.setMaxTextMessageBufferSize(64 * 1024);
  container.setMaxBinaryMessageBufferSize(1024 * 1024);
  return container;
}

// そしてセッションごとに:
new ConcurrentWebSocketSessionDecorator(session, 20_000, 1024 * 1024);
```

重要な違い:

- 上限はプロパティ (`server.websocket.*`、このスターター独自のキー) です。Spring はそれらをコードで、コンテナーとセッションのデコレーターに設定します。
- テキストの上限は UTF-8 のバイト数を数えます。Tomcat は文字数を数えます。
- すべてのセッションが送信の上限を持ちます。Spring の `ConcurrentWebSocketSessionDecorator` は、それを STOMP のセッションと、あなたがラップしたセッションにだけ適用します。Tomcat 上の通常のハンドラーは、代わりに送信スレッドをブロックします (Tomcat のブロッキング送信タイムアウト 20 秒まで)。同じように待つには `flush()` を await してください。
- permessage-deflate は提供されません。Tomcat はそれをネゴシエーションします。

## 関連項目

- [組み込みサーバー](index.md)
- [シャットダウン](shutdown.md)
- [タイムアウト](timeouts.md)
- [ハンドラーマッピング](handler-mappings.md)
- [フィルター](../filters.md)
- [テスト](../testing.md)
- [すべてのプロパティ](../properties.md)
- [データサイズ](../../spring-core-dart/conversion/data-size.md)
