WebSocket

With spring_boot_starter_websocket in the dependencies too, the web server also accepts WebSocket connections on its port. The server.websocket.* properties limit the size of the messages a session reads and how much it may keep waiting to be sent.

Why

A WebSocket stays open and carries messages both ways: a chat, live prices, a game, notifications. It needs the same server as the HTTP API, the same port, and the same filters (security in front of the handshake).

An open connection is also a risk. A client could send one huge message, or stop reading while the server keeps sending, until the server runs out of memory. The limits close such sessions early.

Example

# 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); // to every open session
    return Ack(room: room, received: message.text);  // the reply, as 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, handshake interceptors, origins and broadcasting belong to the WebSocket starter. Its README describes them: spring_boot_starter_websocket, Server endpoints. This page covers what the web starter adds: the server side of the connection.

Properties

Key Type Default Meaning
server.websocket.max-text-message-size DataSize 8KB The largest text message a session reads, in UTF-8 bytes. -1: no limit.
server.websocket.max-binary-message-size DataSize 8KB The largest binary message a session reads. -1: no limit.
server.websocket.send-buffer-size-limit DataSize 512KB The most a session may keep waiting to be sent. -1: no limit.
server.websocket.send-time-limit Duration 10s The longest what was sent may take to leave. -1: no limit.

server.websocket.max-text-message-size

server.websocket.max-binary-message-size

server.websocket.send-buffer-size-limit

server.websocket.send-time-limit

Sending at the client's pace

To send a lot without reaching the limits, wait until each message has left before the next one. The session of the web starter's server is an IoWebSocketSession (in a @WebSocketEndpoint, the delegate of the DefaultServerWebSocketSession). Its flush() completes when nothing waits in memory any more:

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(); // sent as fast as the client reads
    }
  }
}

IoWebSocketSession comes from package:spring_web_dart/io.dart: add spring_web_dart to your dependencies to import it.

flush() fails with a WebSocketException when the connection closes or is dropped first.

The handshake

The handshake is an ordinary HTTP GET with Connection: Upgrade and Upgrade: websocket. So:

Problem Answer
no Sec-WebSocket-Key, two of them, or not 16 bytes in base64 400
Sec-WebSocket-Version sent twice 400
a version other than 13, or none 426 Upgrade Required with Sec-WebSocket-Version: 13

Close codes

Code When
1001 (going away) the server stops: every open session is closed with the reason Server stopping, in both shutdown modes
1006 (CloseStatus.noCloseFrame) the client went away (a reset) while messages waited; the error is the reason. Also over TLS
1009 (too big) a message over max-text-message-size or max-binary-message-size
4500 (CloseStatus.sessionNotReliable) past send-buffer-size-limit or send-time-limit
your own after session.close(status) from the server, the handler gets that status

Rules

In Spring (Java)

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

// and, per session:
new ConcurrentWebSocketSessionDecorator(session, 20_000, 1024 * 1024);

Differences that matter:

See also