
# WebSocket トランスポート

WebSocket は開いたままの接続で、両側がいつでもメッセージを送れます。チャット、リアルタイムの更新、ゲームなどです。`WebSocketTransport.connect(url)` は接続を開き、`WebSocketSession` を返します。その受信メッセージは `Stream` です。その上に載る宣言的なクライアント、つまり `@WebSocketClient` を付けたインターフェースは `spring_boot_starter_websocket` から来ます。

## 使う理由

`dart:io` とブラウザーには、制限もエラーも異なる別々の WebSocket クラスがあります。Spring の送信の制限とクローズステータスを持つ、両者を覆う一つのインターフェースがあれば、同じコードがサーバーでも、Flutter アプリでも、Web でも動き、テストではネットワークを置き換えられます。

## 例

```dart
final sockets = platformWebSocketTransport();
final session = await sockets.connect(
  Uri.parse('wss://chat.neon.books/ws'),
  headers: HttpHeaders({'Authorization': 'Bearer $token'}), // Web では使えない
  timeout: const Duration(seconds: 5),
);
session.messages.listen(log.info);
session.sendMessage('{"text":"hi"}');
await session.close(); // CloseStatus.normal。理由を伝えるには:
// await session.close(CloseStatus.policyViolation.withReason('no token'));
```

## トランスポート

| トランスポート | プラットフォーム | インポート |
|---|---|---|
| `platformWebSocketTransport(maxTextMessageSize:, maxBinaryMessageSize:)` | 下の 2 つのどちらかを選ぶ | `package:spring_web_dart/spring_web_dart.dart` |
| `IoWebSocketTransport` | VM、Android・iOS・デスクトップの Flutter (`dart:io` の `WebSocket`) | `package:spring_web_dart/io.dart` |
| `BrowserWebSocketTransport` | Web、Flutter Web (`dart:js_interop` を通した `WebSocket`) | `package:spring_web_dart/browser.dart` |
| `MockWebSocketTransport` | テスト | `package:spring_web_dart/testing.dart`、または `spring_boot_starter_test` |

## WebSocketSession

| メンバー | 意味 |
|---|---|
| `messages` | 受信メッセージ: テキストフレームなら `String`、バイナリなら `Uint8List`。 |
| `sendMessage(message)` | `String` (テキスト) または `List<int>` (バイナリ)。待たない。 |
| `acceptedProtocol` | サーバーが選んだサブプロトコル。 |
| `isOpen` | セッションが開いているかどうか。 |
| `close([status])` | 閉じる。デフォルトは `CloseStatus.normal`。 |
| `closeStatus` | どのように閉じたか。 |
| `flush()` | `IoWebSocketSession` のみ: 送ったものが出ていくまで待つ。 |

`CloseStatus` には定数 (`normal`、`goingAway`、`policyViolation`、`noCloseFrame` 1006、`sessionNotReliable` 4500...)、`withReason(text)`、`equalsCode(other)` があります。

## 送信とバックプレッシャー

`sendMessage` は待ちません。メッセージはネットワークが受け取るまでメモリで待ちます。`dart:io` (`IoWebSocketSession`。クライアントと Web スターターのサーバーの両方) では、Spring の `ConcurrentWebSocketSessionDecorator` と同じく、512 KB を超えるものが待っているか、送ったものが 10 秒以内に出ていかないと、セッションはあきらめます。接続は切られ、`closeStatus` は 4500 です。そのため、ネットワークが受け取るより速く送るループは 4500 で終わります。ネットワークのペースで進むには、各メッセージの後に `flush()` を await してください。

```dart
// 大きなエクスポートを、サーバーが読む速さで送る。
final session = await IoWebSocketTransport().connect(url) as IoWebSocketSession;
for (final chunk in export) {
  session.sendMessage(chunk);
  await session.flush(); // 接続が終わると WebSocketException で失敗する
}
```

その他の制限は `IoWebSocketTransport(sendBufferSizeLimit:, sendTimeLimit:)` で設定します。

## 受信

- サーバーからの 8 KB (テキストまたはバイナリ。Tomcat のデフォルト) を超えるメッセージは、`dart:io` では読まれません。セッションは 1009 (メッセージが大きすぎる) で閉じられます。テキストの制限は UTF-8 のバイト数で数えます。`IoWebSocketTransport(maxTextMessageSize:, maxBinaryMessageSize:)` または `platformWebSocketTransport(maxTextMessageSize: ...)` で引き上げます (`-1`: 上限なし)。ブラウザーには制限がありません。
- メッセージが送信を待っている間も接続は読まれ続けるため、どちらも大量に送る 2 つの側が互いを待つことはありません。
- 切れた接続は、`closeStatus` 1006 とエラーを理由として、`messages` を終わらせます。
- メッセージのフラグメントの間の ping にはすぐに応答し、メッセージは丸ごと届きます。
- 誰も購読する前に閉じたセッションでも、クローズが終わると終わる `messages` が得られます。

## ハンドシェイク

- ブラウザーはハンドシェイクで独自のヘッダーを送らないため、`headers` が空でないと `BrowserWebSocketTransport` は失敗します。Web では、トークンをクエリパラメーターかプロトコルとして渡してください。
- RFC 6455 の求めるとおり、クライアントが提示していないサブプロトコルや何らかの拡張 (何も提示しないため、メッセージは圧縮されません) をサーバーが選ぶと、ハンドシェイクは失敗します。
- ブラウザーと同じく、リダイレクトはたどられません。

## Spring (Java) との対応

```java
WebSocketSession session = new StandardWebSocketClient()
    .execute(handler, "wss://chat.neon.books/ws").get();
```

`WebSocketSession` は受信メッセージを `Stream` として渡します。Spring では `WebSocketHandler` が呼ばれます。`sendMessage` は `TextMessage` や `BinaryMessage` ではなく `String` やバイトを受け取り、ブロックしません (Spring のものはブロックします)。`flush()` を使ってください。`closeStatus` はセッションがどのように閉じたかを示します。Spring ではこれを `afterConnectionClosed` に渡します。

## 関連項目

- [spring_boot_starter_websocket](../spring-boot-starter-websocket/index.md)
- [テスト](testing.md)
