Connection and errors
Connection status
Both clients expose a connectionStatus stream, and recover on their own:
/// A short description of [status], for a log or a status bar.
String describe(ConnectionStatus status) {
return switch (status) {
ConnectionStatus.connecting => 'Connecting…',
ConnectionStatus.connected => 'Online',
ConnectionStatus.reconnecting => 'Connection lost, retrying…',
ConnectionStatus.disconnected => 'Offline',
ConnectionStatus.error => 'Connection error',
// Terminal: the server refused this build. Ask the user to update.
ConnectionStatus.unsupported => 'Update required',
};
}
On unsupported, client.incompatibility says why the server refused this
build.
- Liveness. It is tracked with ping/pong. A missing pong within the ping timeout is treated as a dead (half-open) connection, and triggers a reconnect.
- Reconnection. The server–client client reconnects on a fixed interval, with a capped number of attempts. The relay client uses exponential backoff with jitter, and retries forever by default.
- A failed first connect enters the same reconnect loop.
disconnectanddisposestop it. - Backpressure. The server keeps a bounded send queue per connection, and drops a peer that cannot keep up. That peer re-syncs when it reconnects.
ConnectionStatus.unsupported is the one status the client never leaves: see
Refusals are permanent.
Faults: data that did not make it in
A status is about the connection. client.faults is about one piece of
data: a change or a state the client received on a working connection and
could not fold into the document. For example a blob it cannot read, or a
document already disposed.
client.faults.listen((fault) {
log('${fault.reason}: ${fault.error}');
});
// faults replays nothing, so a late listener reads this instead.
final missed = client.lastFault;
A fault is reported, never thrown. Applying runs inside the callback that reads
the socket, where a throw reaches no catch and no onError, and ends up as an
uncaught error in the zone.
Nothing is retried and the connection stays up, so an app that cares decides for itself whether to re-sync or to tell the user. A causal gap is not a fault: the client asks the server to serve the document again, which is the one failure a re-sync fixes.