クライアントの設定

各クライアントは 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 のものを置き換える。

メッセージサイズの制限

キー デフォルト 意味
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

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

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 を宣言してください。

Spring (Java) との対応

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

関連項目