wse_client 3.1.0
wse_client: ^3.1.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.1.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.
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.
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).
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