
# クライアント

WebSocket クライアントは `@WebSocketClient` を付けた抽象クラスで、受信メッセージを `Stream` として返すメソッド (`@OnMessage`) と、メッセージを送るメソッド (`@SendMessage`) を持ちます。ジェネレーターがそれを実装し、コンテナがそれを Bean にします。接続は最初に必要になったときに開き、クライアントのすべてのストリームと送信で共有され、誰かが購読している間は失われても再接続します。

## 使う理由

ライブのデータを表示するアプリは、ソケットを開き、各フレームをデコードし、ネットワークが切れたら再び開かなければなりません。それも、再起動中のサーバーに殺到しないよう、間隔を伸ばしながらです。インターフェースとして宣言すれば、ソケットは型付きのストリームと型付きの送信になり、そのすべてが代わりに行われます。

## 例

```dart
@WebSocketClient('prices', url: r'${prices.url}', protocols: ['prices.v2'])
abstract interface class PriceSocket {
  @OnMessage()
  Stream<PriceUpdate> updates();         // JSON のテキストメッセージ

  @OnMessage()
  Stream<Uint8List> snapshots();         // バイナリメッセージ

  @SendMessage()
  Future<void> subscribe(Subscription subscription);

  Future<void> connect();                // 任意: 今すぐ開く
  Future<void> close();                  // 任意: 早めに閉じる (コード 1000)
}

@Service()
class Ticker {
  Ticker(this.socket);

  final PriceSocket socket;
  StreamSubscription<PriceUpdate>? _subscription;

  Future<void> watch(String isbn) async {
    _subscription = socket.updates().listen(show);   // 接続を開く
    await socket.subscribe(Subscription(isbn: isbn));
  }

  Future<void> stop() async {
    await _subscription?.cancel();                   // 最後の購読者: もう再接続しない
    await socket.close();
  }
}
```

## @WebSocketClient

| 属性 | 意味 |
|---|---|
| `name` (位置引数) | クライアントの名前: そのプロパティは `spring.websocket.client.config.<name>.*` で、ハンドシェイクのインターセプターはそれを `clientName` として見る。 |
| `url` | `ws://` または `wss://` で始まるアドレス。`${...}` のプレースホルダーも可。なければ `url` プロパティ。 |
| `protocols` | ハンドシェイクで提示するサブプロトコル (`Sec-WebSocket-Protocol`)。 |

## メソッド

| メソッド | 働き |
|---|---|
| `@OnMessage() Stream<T> name()` | 受信メッセージ。`String` はテキストメッセージをそのまま、`Uint8List` はバイナリメッセージを、その他の型はテキストメッセージを JSON として読んだものを返す。別の種類のメッセージはスキップされる。読めないメッセージはエラーイベント (`MessageConversionException`) として届き、ストリームは続く。呼び出すたびに新しいストリームを返し、すべてのストリームがすべてのメッセージを受け取る。 |
| `@SendMessage() Future<void> name(T message)` | メッセージを送る: `String` はテキストとして、`Uint8List` (または `List<int>` のパラメーター) はバイナリとして、その他は JSON のテキストとして。接続が開く間は待つ。メッセージがキューに入った時点で完了し、出ていった時点ではない。 |
| `Future<void> connect()` | 任意。最初の使用時ではなく、今すぐ接続を開く。 |
| `Future<void> close()` | 任意。ログアウト時や画面がなくなるときに、接続を早めに閉じる (コード 1000)。ストリームは終わる。クライアントを再び使うと新しい接続が開く。シャットダウン時には不要。 |

その他のメソッドは理由とともにアプリケーションを起動時に止めます。URL がない場合や、`ws://` か `wss://` で始まらない場合も同様です。`@SendMessage` メソッドが JSON として書けない値は、`Future` が返される前に、呼び出し自体から `MessageConversionException` を投げます。

## 接続

- **クライアントごとに一つ。** クライアントのすべてのストリームと送信が一つの接続を共有します。
- **必要に応じて。** `@OnMessage` のストリームの最初の購読者、最初に送られたメッセージ、または `connect()` で開きます。
- **誰かが購読している間は再接続。** 失われた接続 (コードなし、1001、1005、1006、1011 から 1014 で閉じたもの、またはクライアントが 4500 で切ったもの) や失敗した試行は、待機の後に再び開かれます。最初の待機は `reconnect.delay` で、その後の待機は `reconnect.multiplier` を掛けて `reconnect.max-delay` まで伸び、`reconnect.jitter` の幅で前後します。その間も購読者は購読したままです。
- **停止中の送信。** 送信 (または `connect()`) は次の試行だけを待ち、その試行が失敗すれば失敗するため、遅延と `connect-timeout` を足した時間より長く待つことはありません。購読者がいれば、そうした失敗の後も再接続は続きます。いなければ、それ以上は試みません。
- **あきらめる。** リトライは、接続が安定していると分かるまで数え続けられます。メッセージを届けるか、`reconnect.max-delay` の間開いたままであることです。そのため、受け入れてすぐに閉じるサーバーでも `reconnect.max-retries` に達します。あきらめた後、ストリームは最後のエラーで終わります。次の購読者は、すべてのリトライを持って再び始めます。最後の購読者がキャンセルすると、それ以上の試行は行われません。
- **サーバーによるクローズ。** 通常のクローズ (1000) はストリームを終わらせます。その他のコード (1008 ポリシー違反...) は `WebSocketException` でストリームを終わらせます。
- **シャットダウン。** アプリケーションが停止すると接続は閉じられます。`closeAsync()` はそれらが閉じるまで待ちます。

接続は `WebSocketConnectionManager` が管理し、開いた接続は `spring_web_dart` の `WebSocketSession` です。

## Spring (Java) との対応

```java
WebSocketClient client = new StandardWebSocketClient();
client.execute(new TextWebSocketHandler() {
  @Override
  protected void handleTextMessage(WebSocketSession session, TextMessage message) { ... }
}, "wss://chat.neon.books/ws");
```

Spring には宣言的な WebSocket クライアントがありません。`@WebSocketClient`、(クライアントでの) `@OnMessage`、`@SendMessage` はこのプロジェクト独自のものです。Spring の `WebSocketConnectionManager` は再接続しませんが、こちらはします。STOMP にはまだ対応していません。

## 関連項目

- [クライアントの設定](client-configuration.md)
- [テスト](testing.md)
- [spring_web_dart](../spring-web-dart/index.md)
