A simple WebSocket client for Dart which includes automatic reconnection logic
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();
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);
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);
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);
BinaryExponentialBackoff
This backoff strategy will make the WebSocket client wait an exponentially
increasing amount of time until a maxiumum 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);
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;
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
closemethod 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');
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.message.listen((message) {
// Handle the incoming message.
});
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');