web_socket_client

Description:

web socket client

WebSocket Client #




A simple WebSocket client for Dart which includes automatic reconnection
logic.
Quick Start 🚀 #
// Create a WebSocket client.
final socket = WebSocket(Uri.parse('ws://localhost:8080'));

// Listen to messages from the server.
socket.messages.listen((message) {
// Handle incoming messages.
});

// Send a message to the server.
socket.send('ping');

// Close the connection.
socket.close();
copied to clipboard
Establishing a Connection 🔌 #
The WebSocket client will attempt to establish a connection immediately upon
initialization. By default, a timeout will occur if establishing a connection
exceeds 60 seconds but a custom timeout duration can be provided:
final uri = Uri.parse('ws://localhost:8080');

// Trigger a timeout if establishing a connection exceeds 10s.
final timeout = Duration(seconds: 10);
final socket = WebSocket(uri, timeout: timeout);
copied to clipboard
Reconnecting 🔄 #
If the WebSocket client is not able to establish a connection, it will
automatically attempt to reconnect using the provided Backoff strategy. By
default, a BinaryExponentialBackoff is used but a custom backoff can be
provided.
There are three built-in backoff strategies but a custom backoff strategy can be
written by implementing the Backoff interface.
ConstantBackoff
This backoff strategy will make the WebSocket client wait a constant amount of
time between reconnection attempts.
// Wait a constant 1s between reconnection attempts.
// [1, 1, 1, ...]
const backoff = ConstantBackoff(Duration(seconds: 1));
final socket = WebSocket(uri, backoff: backoff);
copied to clipboard
LinearBackoff
This backoff strategy will make the WebSocket client wait a linearly
increasing amount of time until an optional maximum duration is reached.
// Initially wait 0s and increase the wait time by 1s until a maximum of 5s is reached.
// [0, 1, 2, 3, 4, 5, 5, 5, ...]
const backoff = LinearBackoff(
initial: Duration(seconds: 0),
increment: Duration(seconds: 1),
maximum: Duration(seconds: 5),
);
final socket = WebSocket(uri, backoff: backoff);
copied to clipboard
BinaryExponentialBackoff
This backoff strategy will make the WebSocket client wait an exponentially
increasing amount of time until a maximum step is reached.
// Initially wait 1s and double the wait time until a maximum step of of 3 is reached.
// [1, 2, 4, 4, 4, ...]
const backoff = BinaryExponentialBackoff(
initial: Duration(seconds: 1),
maximumStep: 3
);
final socket = WebSocket(uri, backoff: backoff);
copied to clipboard
Monitoring the Connection ⚡️ #
The WebSocket client exposes a connection object which can be used to query
the connection state at any given time as well as listen to real-time changes in
the connection state.
final uri = Uri.parse('ws://localhost:8080');
final socket = WebSocket(uri);

// Listen to changes in the connection state.
socket.connection.listen((state) {
// Handle changes in the connection state.
});

// Query the current connection state.
final connectionState = socket.connection.state;
copied to clipboard
The connection state can be one of the following:

connecting: the connection has not yet been established.
connected: the connection is established and communication is possible.
reconnecting: the connection was lost and is in the process of being
re-established.
reconnected: the connection was lost and has been re-established.
disconnecting: the connection is going through the closing handshake or
the close method has been invoked.
disconnected: the WebSocket connection has been closed or could not be
established.

* The disconnected connection state contains nullable fields for the close
code, close reason, error, and stack trace.
Sending Messages 📤 #
Once a WebSocket connection has been established, messages can be sent to the
server via send:
final socket = WebSocket(Uri.parse('ws://localhost:8080'));

// Wait until a connection has been established.
await socket.connection.firstWhere((state) => state is Connected);

// Send a message to the server.
socket.send('ping');
copied to clipboard
Receiving Messages 📥 #
Listen for incoming messages from the server via the messages stream:
final socket = WebSocket(Uri.parse('ws://localhost:8080'));

// Listen for incoming messages.
socket.messages.listen((message) {
// Handle the incoming message.
});
copied to clipboard
Protobuf 💬 #
If you're using web_socket_client on the web with Protobuf, you might
want to use binaryType when initializing the WebSocket class.
binaryType is only applicable on the web and is not used on desktop or mobile platforms.
final socket = WebSocket(Uri.parse('ws://localhost:8080'), binaryType: 'arraybuffer');
copied to clipboard
See https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType for more info.
Closing the Connection 🚫 #
Once a WebSocket connection is established, it will automatically attempt to
reconnect if the connection is disrupted. Calling close() will update the
connection state to disconnecting, perform the closing handshake, and set the
state to disconnected. At this point, the WebSocket client will not attempt
to reconnect and a new WebSocket client instance will need to be created in
order to establish a new connection.
final socket = WebSocket(Uri.parse('ws://localhost:8080'));

// Later, close the connection with an optional code and reason.
socket.close(1000, 'CLOSE_NORMAL');
copied to clipboard