WebSocket

依存関係に spring_boot_starter_websocket も加えると、Web サーバーはそのポートで WebSocket 接続も受け付けます。server.websocket.* プロパティは、セッションが読むメッセージのサイズと、送信待ちとして保持できる量を制限します。

使う理由

WebSocket は開いたままで、双方向にメッセージを運びます。チャット、リアルタイムの価格、ゲーム、通知などです。HTTP API と同じサーバー、同じポート、同じフィルター (ハンドシェイクの前段のセキュリティ) が必要です。

開いた接続はリスクでもあります。クライアントが一つの巨大なメッセージを送ったり、サーバーが送り続けている間に読むのをやめたりして、サーバーのメモリを使い果たさせるかもしれません。上限は、そうしたセッションを早めに閉じます。

例

# pubspec.yaml
dependencies:
  spring_boot_starter_web: ^0.9.0
  spring_boot_starter_websocket: ^0.9.0
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'package:spring_boot_starter_websocket/spring_boot_starter_websocket.dart';

// ws://localhost:8080/ws/rooms/neon
@WebSocketEndpoint('/ws/rooms/{room}')
class ChatEndpoint {
  ChatEndpoint(this.sessions);
  final WebSocketSessionRegistry sessions;

  @OnMessage()
  Ack message(@PathVariable() String room, ChatMessage message) {
    sessions.broadcast('/ws/rooms/{room}', message); // 開いているすべてのセッションへ
    return Ack(room: room, received: message.text);  // JSON での返信
  }
}

@Introspected()
class ChatMessage {
  const ChatMessage({required this.text});
  final String text;
}

@Introspected()
class Ack {
  const Ack({required this.room, required this.received});
  final String room;
  final String received;
}
# lib/resources/application.yml
server:
  websocket:
    max-text-message-size: 64KB
    max-binary-message-size: 1MB
    send-buffer-size-limit: 1MB
    send-time-limit: 20s
server.websocket.max-text-message-size=64KB
server.websocket.max-binary-message-size=1MB
server.websocket.send-buffer-size-limit=1MB
server.websocket.send-time-limit=20s

@WebSocketEndpoint、WebSocketHandler、WebSocketConfigurer、ハンドシェイクインターセプター、オリジン、ブロードキャストは WebSocket スターターに属します。その README で説明されています: spring_boot_starter_websocket, Server endpoints。このページは、Web スターターが加えるもの、つまり接続のサーバー側を扱います。

プロパティ

キー 型 デフォルト 意味
server.websocket.max-text-message-size DataSize 8KB セッションが読む最大のテキストメッセージ (UTF-8 のバイト数)。-1: 上限なし。
server.websocket.max-binary-message-size DataSize 8KB セッションが読む最大のバイナリメッセージ。-1: 上限なし。
server.websocket.send-buffer-size-limit DataSize 512KB セッションが送信待ちとして保持できる最大量。-1: 上限なし。
server.websocket.send-time-limit Duration 10s 送ったものが出ていくまでにかかってよい最長の時間。-1: 上限なし。

server.websocket.max-text-message-size

server.websocket.max-binary-message-size

server.websocket.send-buffer-size-limit

server.websocket.send-time-limit

クライアントのペースで送る

上限に達せずに大量に送るには、各メッセージが出ていくのを待ってから次を送ります。Web スターターのサーバーのセッションは IoWebSocketSession です (@WebSocketEndpoint では、DefaultServerWebSocketSession の delegate)。その flush() は、メモリで待っているものがなくなると完了します。

import 'package:spring_boot_starter_websocket/spring_boot_starter_websocket.dart';
import 'package:spring_web_dart/io.dart' show IoWebSocketSession;

Future<void> sendAll(ServerWebSocketSession session, Stream<String> lines) async {
  final raw = session is DefaultServerWebSocketSession ? session.delegate : session;
  await for (final line in lines) {
    session.sendMessage(line);
    if (raw is IoWebSocketSession) {
      await raw.flush(); // クライアントが読む速さで送る
    }
  }
}

IoWebSocketSession は package:spring_web_dart/io.dart から来ます。インポートするには、依存関係に spring_web_dart を追加してください。

flush() は、先に接続が閉じられたり切断されたりすると WebSocketException で失敗します。

ハンドシェイク

ハンドシェイクは、Connection: Upgrade と Upgrade: websocket を持つ通常の HTTP の GET です。そのため:

問題 応答
Sec-WebSocket-Key がない、二つある、または base64 で 16 バイトでない 400
Sec-WebSocket-Version が二回送られた 400
13 以外のバージョン、またはなし Sec-WebSocket-Version: 13 付きの 426 Upgrade Required

クローズコード

コード いつ
1001 (going away) サーバーの停止時。どちらのシャットダウンモードでも、開いているすべてのセッションが理由 Server stopping で閉じられる
1006 (CloseStatus.noCloseFrame) メッセージが待っている間にクライアントが去った (リセット)。エラーが理由になる。TLS 上でも同様
1009 (too big) max-text-message-size または max-binary-message-size を超えるメッセージ
4500 (CloseStatus.sessionNotReliable) send-buffer-size-limit または send-time-limit を超えた
独自のもの サーバーから session.close(status) した後、ハンドラーはそのステータスを受け取る

ルール

Spring (Java) との対応

@Bean
ServletServerContainerFactoryBean createWebSocketContainer() {
  var container = new ServletServerContainerFactoryBean();
  container.setMaxTextMessageBufferSize(64 * 1024);
  container.setMaxBinaryMessageBufferSize(1024 * 1024);
  return container;
}

// そしてセッションごとに:
new ConcurrentWebSocketSessionDecorator(session, 20_000, 1024 * 1024);

重要な違い:

関連項目