StreamWebSocketClient class

A WebSocket client with connection management and event handling.

The primary interface for WebSocket connections in the Stream Core SDK that provides functionality for real-time communication with automatic reconnection, health monitoring, and sophisticated state management.

Each StreamWebSocketClient instance manages its own connection lifecycle and maintains state that can be observed for real-time updates. The client handles message encoding/decoding, connection recovery, and event distribution.

Example

final client = StreamWebSocketClient(
  optionsBuilder: () => const WebSocketOptions(url: 'wss://api.example.com'),
  // A WebSocketMessageCodec for the event and request types this SDK puts on the wire.
  messageCodec: const AppWsCodec(),
  onAuthenticate: (send, _) async {
    final token = await tokenManager.getToken();
    send(WsAuthMessageRequest(token: token.rawValue)).getOrThrow();
  },
);

await client.connect();

This client reports what it is doing under SC:WsClient, and the engine, health monitor and authentication handler it owns under SC:WsClient:Engine, :Health and :Auth. Nothing is written until an app installs a StreamLogHandler:

StreamLogger.handler = const StreamLogHandler.filtered(StreamLogFilter.minPriority(StreamLogPriority.debug), StreamLogHandler.console());

Give a second client its own tag to tell the two apart. Its collaborators are tagged from it, so one prefix still selects the whole family:

StreamWebSocketClient(tag: 'SC:Ws2', ...);
StreamLogger.filter = const StreamLogFilter.prefix({'SC:Ws2': StreamLogPriority.verbose});

Implemented types

Mixed-in types

Disposable

Constructors

StreamWebSocketClient({required WebSocketOptionsBuilder optionsBuilder, WebSocketProvider? wsProvider, WebSocketAuthenticator? onAuthenticate, PingRequestBuilder pingRequestBuilder = _defaultPingRequestBuilder, required WebSocketMessageCodec<WsEvent, WsRequest> messageCodec, Iterable<EventResolver<WsEvent>>? eventResolvers, String tag = 'SC:WsClient'}): Creates a new instance of StreamWebSocketClient.

Properties

connectionState → ConnectionStateEmitter: The current connection state of the WebSocket.
no setter
events → EventEmitter<WsEvent>: The event emitter for WebSocket events.
no setter
hashCode → int: The hash code for this object.
no setterinherited
isDisposed → bool: Returns true if this object has been disposed.
no setterinherited
optionsBuilder → WebSocketOptionsBuilder: The function used to build the connection options for each attempt.
final
pingRequestBuilder → PingRequestBuilder: The function used to build ping requests for health checks.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

connect() → Future<void>: Establishes a WebSocket connection.
disconnect({CloseCode closeCode = CloseCode.normalClosure, DisconnectionSource source = const UserInitiated()}) → Future<void>: Closes the WebSocket connection.
dispose() → Future<void>: Releases every resource held by this client.
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
onClose([int? closeCode, String? closeReason]) → void: Called when the WebSocket connection is closed.
override
onError(Object error, [StackTrace? stackTrace]) → void: Called when an error occurs on the WebSocket connection.
override
onMessage(WsEvent event) → void: Called when a message is received from the WebSocket.
override
onOpen() → void: Called when the WebSocket connection is successfully opened.
override
onPingRequested() → void: Called when it's time to send a ping request for health checking.
override
onUnhealthy() → void: Called when the WebSocket connection is determined to be unhealthy.
override
send(WsRequest request) → Result<void>: Sends a message through the WebSocket connection.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited