wse_client 3.2.0
wse_client: ^3.2.0 copied to clipboard
The WSE client for Dart and Flutter, on the Rust client through flutter_rust_bridge.
wse_client #
The WSE client for Dart and Flutter. It keeps a connection to a WSE server,
reconnects when the connection is lost, recovers the messages it missed, and
hands the server's messages to the app in order. It is the Rust client
(wse-client on crates.io) through flutter_rust_bridge.
Platforms: Android (API 24+), iOS 15+, macOS 10.15+, Linux and Windows. Flutter 3.38 or newer. These are the library's minimums; the app's Flutter may ask for more (Flutter 3.50 makes macOS apps for macOS 12 and newer).
Install #
dependencies:
wse_client: ^3.2.0
The package's build hook takes the prebuilt Rust library of the app's target from the package's GitHub release and uses it only when its SHA-256 is the one the release listed, so the app needs no Rust toolchain. Prebuilt libraries exist for Android (arm64-v8a, armeabi-v7a, x86_64), iOS (devices, and simulators on Apple silicon and Intel), macOS (Apple silicon and Intel), Linux (x64, arm64) and Windows (x64, arm64).
To build the library from source instead (a Rust toolchain through rustup,
plus Xcode for Apple targets or the Android NDK for Android), add to the
app's pubspec.yaml:
hooks:
user_defines:
wse_client:
build: source
An iOS app sets its minimum iOS version to 15.0. An Android app has the
INTERNET permission in its main manifest, and a macOS app the
com.apple.security.network.client entitlement.
Use #
import 'package:wse_client/wse_client.dart';
Future<void> main() async {
await WseClient.init();
final client = await WseClient.connect(
wseConfig('wss://example.com/wse', token: token, topics: ['prices']),
);
await client.send('order', '{"id": 1}');
client.trySendLive('open_valve', '{"id": 7}'); // on this connection or not at all
await for (final item in client.events()) {
switch (item.kind) {
case WseItemKind.message:
print('${item.topic} ${item.name}: ${item.json}');
case WseItemKind.gap:
print('lost messages on ${item.topic}: reload it');
default:
break;
}
}
}
events() is the client's stream: messages, connections and disconnections,
subscriptions, gaps it could not recover, server errors, and the end when the
client closes. One listener reads it at a time; a listener that stops in
between loses nothing, the next one gets the rest. close() sends what is
queued and closes; a closed client's calls throw a WseError of kind
closed.
The outbox #
Every message sent, except a live or signed one, waits in the outbox until
the server answers for it, goes again after a reconnect, and reaches the
server's application once where the server can tell (one it cannot, the node
that took it gone, comes marked possible_repeat). The delivered item names the messages the
server took (ids); notDelivered names those it will not take and why
(reason): the server refused it (busy, rate_limited, missing,
not_ready), it was not written within its time (expired), it was the
last user's (user_changed), the app cleared the outbox (cleared), or
the client closed with it in memory (closed).
final id = await client.sendWith('order', '{"item":"tea"}', id: 'order-17');
// ... later, on sign-out:
client.clear();
sendWith also names a request's correlationId, which the reply names
back (the message item's correlationId), and its priority (10 critical,
8 high, 5 normal, 3 low, 1 background), for the server's app;
requires: ['orders'] waits until those topics are continuous, as
sendRequiring does, under the app's own id; live: true sends on the
connection that is ready now, or not at all. A message item carries its
sender's priority and timestamp too.
The outbox is in memory by default. With offline: wseOffline(path: file)
(a file in the app's own storage) it outlives the app. At most
maxMessages (100,000) and maxBytes (16 MiB) wait, the ones not answered
yet included: past either send waits for room and trySend throws
full. One not written within maxAge (an hour), or the ttl it was sent
with, is dropped. client.kept says how many wait. A file that cannot be
opened or written is a storageFailed item (name: what failed,
reason: why), and the outbox goes on in memory. wseOffline(disabled: true) has no outbox: a send with no connection fails, as before 3.2.
WseClient.connect completes once the server took the connection, and
fails when the first attempt does. For an app that may start without a
network, WseClient.start completes at once: the connection is made in the
background, a failed first attempt made again as any later one, and what is
sent meanwhile waits in the outbox.
Topic states and recover-or-resync #
client.topicStates says of each topic whether the server took it and
whether its messages run without a break. Where every fact counts, a
recover-or-resync delivery holds a topic that is not continuous -- from a
cold start, after every reconnect, after a break -- until the app brought
its state up to date:
final client = await WseClient.connect(
wseConfig(url, topics: ['orders'], delivery: wseDelivery('board', checkpoint: saved)),
);
await for (final item in client.events()) {
switch (item.kind) {
case WseItemKind.resync:
await loadState(item.topics, item.committed);
client.resynced(item.round!); // what was held comes next
case WseItemKind.message:
apply(item); // safe to apply twice
client.commit(item);
save(client.checkpoint());
default:
break;
}
}
The checkpoint is bound to the realm, the user, the consumer and the schema;
one of anything else is refused with a checkpointRejected item. Recovery
starts from it, so a message that came but was not applied comes again.
await client.sendRequiring('cancel', json, ['orders']) sends once each of
the topics is continuous on the connection, checked right before it goes
(after a reconnect it waits for the resync); sends that require nothing go
past it, and once the server takes a connection for another user it goes
nowhere.
Certificates #
A wss:// server's certificate is checked by the system's verifier (the
default, WseTrust.platform): the roots the device trusts. On Android the
package's Android part sets it up as the app starts. WseTrust.roots([ca])
trusts only a private CA's certificate (PEM or DER), WseTrust.mozilla the
Mozilla roots built into the library:
final ca = await rootBundle.load('assets/plant-ca.pem');
final client = await WseClient.connect(
wseConfig(url, trust: WseTrust.roots([ca.buffer.asUint8List()])),
);
ws:// sends everything in the clear and needs insecure: true (for
development).
A lost connection is made again: the first attempt after reconnectDelay
(a second), each next one reconnectFactor (1.5) times later, up to
reconnectMaxDelay (30 s), spread by ±10% unless reconnectJitter: false;
after reconnectMaxAttempts in a row (never by default) the client gives up
and closes. reconnect: false never tries.
Background and network #
WseAppLifecycle(client) pauses the client five seconds after the app went
to the background and resumes it when the app comes back. On a desktop a
minimized window keeps running and keeps receiving: there it pauses the
client only with pauseMinimized: true, and a window that only lost focus
never pauses it.
WseNetworkMonitor(client) pauses it while the device has no network and
makes the connection again when the network moves to other interfaces (Wi-Fi
to mobile, say); the app feeds it what it sees, with connectivity_plus for
one:
final lifecycle = WseAppLifecycle(client);
final network = WseNetworkMonitor(client);
Connectivity().onConnectivityChanged.listen(
(results) => network.update(
usable: !results.contains(ConnectivityResult.none),
interfaces: [for (final result in results) result.name],
),
);
Both pause for reasons of their own: client.pause('manual') stays until
the app calls client.resume('manual'). A paused client keeps its topics and
positions; once no reason is left it connects again and recovers what it
missed. Dispose of both with the client.
In flutter test the package loads the library its build hook made for the
host, so tests that use the client run on the developer's machine too.
Desktop apps #
On Windows, macOS and Linux the package works as it does on a phone, and the
release build takes the same prebuilt library: the app runs from any folder
and needs no Rust toolchain. The example runs on all three
(flutter run -d macos, windows or linux). A macOS app runs in the App
Sandbox, which lets it open connections only with this entitlement in
macos/Runner/DebugProfile.entitlements and
macos/Runner/Release.entitlements:
<key>com.apple.security.network.client</key>
<true/>
A Linux app builds with GTK 3, as every Flutter app on Linux. A minimized
window keeps receiving (WseAppLifecycle, above).
License #
MIT