IoWebSocketSession class final

A WebSocketSession over an open dart:io WebSocket, on either side of the connection.

IoWebSocketTransport returns one for a client connection, and the web starter's server returns one from ServerHttpRequest.upgradeToWebSocket for an accepted connection; both make it with IoWebSocketSession.fromUpgradedSocket. Create one yourself only to wrap a WebSocket you opened with dart:io directly.

closeStatus gives the code the other side sent; if this side closed first and no answer has arrived yet, or the connection ended without one, it gives the status passed to close. A connection that breaks (reset by the other side, a write that fails) ends messages, and closeStatus is then CloseStatus.noCloseFrame (1006) with the error as the reason (Connection reset by peer), as Tomcat reports it, whether a read or a write met the error first: when the input ends first (as it often does over TLS) while something is still being written, messages ends once the write has ended too, or a second later. A message larger than the session's limits (8 KB by default) is not read: the session closes with 1009 (see IoWebSocketSession.fromUpgradedSocket).

sendMessage does not wait: the message waits in memory until the network takes it; flush waits for that. When the other side reads nothing, that memory would grow without end, so a session made by IoWebSocketSession.fromUpgradedSocket gives up on it, as Spring's ConcurrentWebSocketSessionDecorator does: when more than sendBufferSizeLimit bytes wait (512 KB by default), or what was sent has not all left within sendTimeLimit (10 seconds by default), the connection is dropped without a closing handshake (a close frame could not get through either), closeStatus becomes CloseStatus.sessionNotReliable (4500, with the reason), and messages ends. The connection is still read while something waits, so two sides that both send more than the network holds do not wait for each other; the pongs that answer pings wait with the messages, so a peer that sends pings and reads nothing reaches the limit too.

Implemented types

Constructors

IoWebSocketSession(WebSocket socket, Uri uri)
A session over the open socket, whose address is uri. It does not bound what waits to be sent (dart:io keeps it all), nor the size of the messages it receives, and it has dart:io's fault with a ping or pong between the fragments of a message: the fragments before it are lost, and the pong carries them (see IoWebSocketSession.fromUpgradedSocket).
IoWebSocketSession.fromUpgradedSocket(Socket socket, Uri uri, {required bool serverSide, String? protocol, int sendBufferSizeLimit = defaultSendBufferSizeLimit, Duration? sendTimeLimit = defaultSendTimeLimit, int maxTextMessageSize = defaultMaxMessageSize, int maxBinaryMessageSize = defaultMaxMessageSize})
A session over socket, a connection on which the WebSocket handshake has just been done (HttpResponse.detachSocket on a server, HttpClientResponse.detachSocket on a client); uri is its address. The handshake answer may still be on its way in socket (written with add): what the session sends follows it.
factory

Properties

acceptedProtocol → String?
The subprotocol the two sides agreed on in the handshake, or null when none was asked for or accepted.
no setteroverride
closeStatus → CloseStatus?
How the connection was closed, by either side: the code and reason of the close frame. null while it is open.
no setteroverride
done → Future<void>
Completes when the connection has closed, whichever side closed it, or was dropped.
no setter
hashCode → int
The hash code for this object.
no setterinherited
isOpen → bool
Whether messages can still be sent: false once either side has started to close the connection.
no setteroverride
messages → Stream<Object>
The incoming messages. The session listens to the dart:io socket from the start, paused until this stream is listened to: the network is not read before, and dart:io's close never drains the socket itself (it does so for a socket nobody listens to, and a later listen then fails). So a session closed before anyone listened still gives a stream that ends, once the close is done; the messages that arrive after that close while nobody listens are dropped (nobody could answer them any more).
no setteroverride
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
uri → Uri
The URL of the connection: the one a client connected to, or the ws: form of the request URL on a server.
final

Methods

close([CloseStatus status = CloseStatus.normal]) → Future<void>
Closes the connection, sending status (CloseStatus.normal by default) to the other side. The future completes when the connection is closed.
override
flush() → Future<void>
Completes once everything sent so far has left this process: handed to the network, nothing of it waiting in memory any more. So a loop that awaits it after each sendMessage sends as fast as the other side reads, and never reaches the session's sendBufferSizeLimit.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
sendMessage(Object message) → void
Sends message as a text frame when it is a String, or as a binary frame when it is a List<int>. Throws a WebSocketException when the session is no longer open, and an ArgumentError for any other type. It does not wait for the frame to leave: the message waits in memory until the network takes it. On dart:io a session whose other side takes nothing gives up past its limits (512 KB waiting, or 10 seconds) and drops the connection, and IoWebSocketSession.flush waits until what was sent has left; see IoWebSocketSession.
override
toString() → String
A string representation of this object.
inherited

Operators

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

Constants

defaultMaxMessageSize → const int
The largest message a session receives, text or binary: 8 KB, Tomcat's default maxTextMessageBufferSize and maxBinaryMessageBufferSize, on its server and its client.
defaultSendBufferSizeLimit → const int
The most bytes a session keeps waiting to be sent before it drops the connection: 512 KB, Spring's default sendBufferSizeLimit (WebSocketTransportRegistration).
defaultSendTimeLimit → const Duration
How long what a session sent may take to leave before it drops the connection: 10 seconds, Spring's default sendTimeLimit.