クライアントの設定
各クライアントは spring.websocket.client.config.<name>.* の下で設定します。<name> はクライアントの名前です。クライアントが設定しないものは spring.websocket.client.config.default.* にフォールバックします。すべてのクライアントに共通する 2 つのキーが、受信メッセージのサイズを制限します。トークンは WebSocketHandshakeInterceptor の Bean を通してハンドシェイクに入れます。
使う理由
不安定なネットワーク上のモバイルアプリには、素早い最初の再接続と長い最大の間隔が必要です。サーバー間のフィードには、固定のリトライと上限が必要です。サーバーは再接続のたびに新しいトークンを求めます。プロパティとインターセプターは、クライアントのインターフェースに手を触れずにこれらをまかないます。
例
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
// チャットサーバーは、(再) 接続のたびにユーザーの現在のトークンを求める。
@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 |
バイナリメッセージについて同じ。 |
# 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と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 を参照)。
トランスポート
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 に従います。