
# クライアントの設定

各クライアントは `spring.websocket.client.config.<name>.*` の下で設定します。`<name>` はクライアントの名前です。クライアントが設定しないものは `spring.websocket.client.config.default.*` にフォールバックします。すべてのクライアントに共通する 2 つのキーが、受信メッセージのサイズを制限します。トークンは `WebSocketHandshakeInterceptor` の Bean を通してハンドシェイクに入れます。

## 使う理由

不安定なネットワーク上のモバイルアプリには、素早い最初の再接続と長い最大の間隔が必要です。サーバー間のフィードには、固定のリトライと上限が必要です。サーバーは再接続のたびに新しいトークンを求めます。プロパティとインターセプターは、クライアントのインターフェースに手を触れずにこれらをまかないます。

## 例

```properties
spring.websocket.client.config.default.connect-timeout=5s
spring.websocket.client.config.chat.url=wss://chat.neon.books/ws
spring.websocket.client.config.chat.reconnect.delay=500ms
spring.websocket.client.config.chat.reconnect.jitter=100ms
spring.websocket.client.config.chat.reconnect.max-retries=10
spring.websocket.client.config.feed.default-request-headers.X-Api-Key=${FEED_KEY}
spring.websocket.client.max-text-message-size=1MB
```

```dart
// チャットサーバーは、(再) 接続のたびにユーザーの現在のトークンを求める。
@Component()
class ChatAuth implements WebSocketHandshakeInterceptor {
  ChatAuth(this.tokens);

  final TokenStore tokens;

  @override
  Future<void> apply(WebSocketHandshake handshake) async {
    if (handshake.clientName == 'chat') {                  // 他のクライアントには触れない
      handshake.queryParameter('token', await tokens.current());
      // VM とモバイルのみ: handshake.headers.set('Authorization', 'Bearer ...');
    }
  }
}
```

## クライアントのキー

各キーは `spring.websocket.client.config.<name>.<key>` (または `default`) です。

| キー | デフォルト | 意味 |
|---|---|---|
| `url` | なし | `@WebSocketClient` が `url` を持たないときのアドレス。`${...}` のプレースホルダーも可。 |
| `connect-timeout` | `10s` | ハンドシェイクにかけてよい最長時間。 |
| `reconnect.enabled` | `true` | 誰かが購読している間、失われた接続を再び開く。`false` では、失われた接続がメッセージのストリームを終わらせる。 |
| `reconnect.delay` | `1s` | 最初の試行の前の待機。 |
| `reconnect.multiplier` | `2` | その後の各待機に掛ける値。固定の遅延には `1`。それより小さくはできない。 |
| `reconnect.max-delay` | `30s` | 最長の待機。正の値。 |
| `reconnect.jitter` | なし | 各待機に加減するランダムな部分。待機と同じく乗数に応じて伸び、待機は `delay` を下回ることも `max-delay` を上回ることもない。 |
| `reconnect.max-retries` | 上限なし | あきらめるまでに連続して試みる回数。 |
| `default-request-headers.<Name>` | なし | 各ハンドシェイクで送るヘッダー (ブラウザーではできない)。カンマ区切りのリストか YAML のリストで複数の値。クライアントのヘッダーは、大文字小文字にかかわらず同じ名前の `default` のものを置き換える。 |

- `reconnect.*` の名前は Spring Framework 7 の `RetryPolicy` のもので、値はそのビルダーと同じようにチェックされます。`delay` と `jitter` は負でなく、`multiplier` は 1 以上、`max-delay` は正、`max-retries` は負でないことです。`max-delay` より大きい `delay` は `max-delay` だけ待ちます。それ以外はプロパティを示して起動を失敗させます (数値でない `multiplier` や `max-retries` は単なる `FormatException` で失敗します)。
- 待機は Spring の `ExponentialBackOff` と同じく計算されます。デフォルトは `RetryPolicy` のもの (固定の 1 秒の遅延、3 回のリトライ) ではなく、再接続に向いたもの (倍々に伸びる遅延、上限なし) です。
- `reconnect.enabled` は大文字小文字を問わず `true` / `false`、`on` / `off`、`yes` / `no`、`1` / `0` を受け取ります。それ以外の値は起動を失敗させます。
- コードでは、ポリシーは `WebSocketReconnectPolicy` である `WebSocketClientConfig.reconnect` です。

## メッセージサイズの制限

| キー | デフォルト | 意味 |
|---|---|---|
| `spring.websocket.client.max-text-message-size` | `8KB` | クライアントが読む最大のテキストメッセージ (UTF-8 のバイト数)。これより大きいと接続を 1009 (メッセージが大きすぎる) で閉じ、`WebSocketException` でストリームを終わらせる。上限なしは `-1`。 |
| `spring.websocket.client.max-binary-message-size` | `8KB` | バイナリメッセージについて同じ。 |

8 KB は Spring での Tomcat のデフォルトです。Tomcat はテキストを文字数で数えます。ブラウザーには制限がありません。

この二つは、アプリケーションのすべてのクライアントに効きます。一つのクライアントには独自の制限を与えられるので、大きなメッセージを送るサーバーのために、他のクライアントの制限まで上げる必要はありません。

| `spring.websocket.client.config.<name>.` の下のキー | デフォルト | 意味 |
|---|---|---|
| `max-text-message-size` | クライアントの `default` のエントリー、次に `spring.websocket.client.max-text-message-size` | このクライアントが読む最大のテキストメッセージ。 |
| `max-binary-message-size` | クライアントの `default` のエントリー、次に `spring.websocket.client.max-binary-message-size` | バイナリメッセージについて同じ。 |

```properties
# The feed sends JSON of up to 1 MB; every other client stays at 8 KB.
spring.websocket.client.config.feed.max-text-message-size=1MB
```

- [`@PhoenixChannel`](phoenix.md) と `PhoenixSocket` も、クライアント名でこれらを受け取ります。
- クライアントの制限は、接続のたびに `WebSocketTransport` に渡されます (`connect(url, maxTextMessageSize:, maxBinaryMessageSize:)`)。そのため、独自のトランスポートの Bean でも効きます。
- コードでは `WebSocketClientConfig.maxTextMessageSize` と `maxBinaryMessageSize` です。`null` は、トランスポート自身の制限のままにします。

## ハンドシェイクのインターセプター

`WebSocketHandshakeInterceptor` の Bean は、すべての接続と再接続のハンドシェイクを、送られる前に変更します。そのため、その間に期限切れになったトークンは新しいものに置き換えられます。

| `WebSocketHandshake` のメンバー | 意味 |
|---|---|
| `clientName` | 一部のクライアントにだけ作用するための、クライアントの名前。 |
| `queryParameter(name, value)` | URL にクエリパラメーターを追加する。 |
| `headers` | ハンドシェイクのヘッダー (ブラウザーでは使えない)。 |
| `protocols` | 提示するサブプロトコル。 |

例外を投げたインターセプターは、その接続の試行を失敗させます。

**Flutter Web とブラウザー**は、WebSocket のハンドシェイクでヘッダーを送れません。そこでのヘッダーは `WebSocketException` で失敗します。トークンは代わりに URL (`queryParameter`) かサブプロトコルに入れてください。クライアントのログの行と例外のメッセージは、すべてのクエリの値とユーザー情報を `***` として示します (`ws://chat.test/ws?token=***`)。元のエラーは例外の `cause` に残ります。

DPoP を含む OAuth 2.0 のトークンには、`spring_boot_starter_oauth2_client` の `OAuth2AccessTokenHeaders` がヘッダーを書きます ([spring_boot_starter_oauth2_client](../spring-boot-starter-oauth2-client/index.md) を参照)。

## トランスポート

`webSocketTransport` の Bean が接続を開きます。デフォルトは `platformWebSocketTransport()` です。VM と Flutter のモバイル・デスクトップでは `IoWebSocketTransport` (`dart:io`)、Web では `BrowserWebSocketTransport` です。それを置き換えるには、テストがモックでするように、独自の `WebSocketTransport` の Bean を宣言してください。

- `dart:io` では、クライアントが送ったものは、サーバーが受け取らない間メモリで待ちます。Spring の `ConcurrentWebSocketSessionDecorator` と同じく、512 KB を超えるものが待っているか、送ったものが 10 秒以内に出ていかないと、接続は切られ (4500)、クライアントは再接続します。別の制限には `IoWebSocketTransport(sendBufferSizeLimit: ..., sendTimeLimit: ...)` の Bean を宣言してください。
- 拡張は提示しません (permessage-deflate はなし)。クライアントが提示していないサブプロトコルや何らかの拡張を選ぶハンドシェイクの応答は、接続を失敗させます (RFC 6455)。
- ブラウザーと同じく、リダイレクトはたどられません。

## Spring (Java) との対応

Spring は制限をコードで、クライアントの `WebSocketContainer` に設定し (`setDefaultMaxTextMessageBufferSize`)、クライアントのプロパティを持ちません。`spring.websocket.client.*` と `WebSocketHandshakeInterceptor` はこのプロジェクト独自のものです。`reconnect.*` の名前は Spring 7 の `RetryPolicy` に従います。

## 関連項目

- [クライアント](clients.md)
- [Phoenix Channels クライアント](phoenix.md)
- [すべてのプロパティ](properties.md)
- [データサイズ](../spring-core-dart/conversion/data-size.md)
