centrifuge 0.8.0

Dart client to communicate with Centrifuge and Centrifugo from Flutter and VM over dart:io WebSocket

This repo contains a Dart connector library to communicate with Centrifugo server or a server based on Centrifuge library for Go language. This client uses WebSocket transport with binary Protobuf protocol format for Centrifuge protocol message encoding. See feature matrix below to find out which protocol features are supported here at the moment.

Example

• example\flutter_app simple chat application
• example\chat_app one more chat example
• example\console simple console application
• example\console_server_subs demonstrates working with server-side subscriptions

Usage

Create a client instance:

import 'package:centrifuge/centrifuge.dart' as centrifuge;

final client = centrifuge.createClient("ws://localhost:8000/connection/websocket?format=protobuf");

Note that using ?format=protobuf is required for Centrifugo < v3 and can be skipped for later versions.

Centrifuge-dart uses binary Protobuf protocol internally but nothing stops you from sending JSON-encoded data over it. Our examples demonstrate this.

Connect to a server:

await client.connect();

To handle connect and disconnect events you can listen to connectStream and disconnectStream:

client.connectStream.listen(onEvent);
client.disconnectStream.listen(onEvent);
await client.connect();

Connect and disconnect events can happen many times throughout client lifetime.

Subscribe to a channel:

final subscription = client.getSubscription(channel);

subscription.publishStream.listen(onEvent);
subscription.joinStream.listen(onEvent);  
subscription.leaveStream.listen(onEvent);
subscription.subscribeSuccessStream.listen(onEvent);
subscription.subscribeErrorStream.listen(onEvent);
subscription.unsubscribeStream.listen(onEvent);

await subscription.subscribe();

Publish to a channel:

final data = utf8.encode(jsonEncode({'input': message}));
await subscription.publish(data);

When using server-side subscriptions you don't need to create Subscription instances, just set appropriate event handlers on Client instance:

client.connectStream.listen(onEvent);
client.disconnectStream.listen(onEvent);
client.subscribeStream.listen(onEvent);
client.publishStream.listen(onEvent);
await client.connect();

Usage in background

When mobile application goes to background there are many OS-specific limitations for established persistent connections. Thus in most cases you need to disconnect from a server when app moves to background and connect again when app goes to foreground.

Feature matrix

• connect to server using JSON protocol format
• connect to server using Protobuf protocol format
• connect with token (JWT)
• connect with custom header
• automatic reconnect in case of errors, network problems etc
• exponential backoff for reconnect
• connect and disconnect events
• handle disconnect reason
• subscribe on channel and handle asynchronous Publications
• handle Join and Leave messages
• handle Unsubscribe notifications
• reconnect on subscribe timeout
• publish method of Subscription
• unsubscribe method of Subscription
• presence method of Subscription
• presence stats method of Subscription
• history method of Subscription
• top-level publish method
• top-level presence method
• top-level presence stats method
• top-level history method
• send asynchronous messages to server
• handle asynchronous messages from server
• send RPC commands
• subscribe to private channels with token (JWT)
• connection JWT refresh
• private channel subscription token (JWT) refresh
• handle connection expired error
• handle subscription expired error
• ping/pong to find broken connection
• message recovery mechanism for client-side subscriptions
• server-side subscriptions
• message recovery mechanism for server-side subscriptions
• history stream pagination
• subscribe from the known StreamPosition

Instructions for maintainers/contributors

How to update protobuf definitions

1. Install protoc compiler
2. Install protoc_plugin https://pub.dev/packages/protoc_plugin (dart pub global activate protoc_plugin)
3. cd lib/src/proto and run protoc --dart_out=. -I . client.proto
4. cd to root and run dartfmt -w lib/ test/ (install dartfmt with dart pub global activate dart_style)

How to release

1. Update changelog
2. Bump version in pubspec.yaml, push, create new tag
3. pub publish

Author

German Saprykin, [e-mail]