p-hatan / mirrormirror.p-hatan.ir

Viewing version 0.8.0. Open the latest package page.

centrifuge

0.8.0

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

Download archive

Readme

Build Status Coverage Status

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, saprykin.h@gmail.com

Changelog

[0.8.0]

Version 0.8.0 is the next iteration of centrifuge-dart development. It pushes client closer to other clients in the ecosystem. It also contains several backwards incompatible changes.

  • Return Futures from Client.connect, Client.disconnect, Subscription.subscribe, Subscription.unsubscribe methods - addresses #31.
  • On initial connect fire DisconnectEvent on connection error - this makes behavior of centrifuge-dart similar to all other our clients - addresses #56.
  • Add client error stream to consume ErrorEvent - each transport failure will emit error to this stream - addresses #56.
  • Refactor subscription statuses - add subscribing and error statuses. This change is mostly internal should not affect working with Subscriptions.
  • Do not call UnsubscribeEvent if subscription is not successfully subscribed (i.e. in subscribed state). This makes behavior of centrifuge-dart similar to all other our clients.
  • Update disconnect reasons due to failed connection and calling Client.Disconnect method - make it more similar to all other connector libraries in ecosystem.
  • Add default transport timeout (10 sec) – on connect and subscribe timeouts client will auto reconnect, calls like publish, history, rpc can now throw TimeoutException. Also - properly pass timeout to the transport (was not before!). Again – this makes client behave similarly to all other connectors.
  • Add presence and presenceStats methods for Subscription and on client top level (for server-side subscriptions).
  • Support streamPosition in SubscribeSuccessEvent.
  • Support streamPosition in ServerSubscribeEvent.
  • Support data in ServerSubscribeEvent.
  • Implement send method to send async messages to a server.
  • Fix deletion during iteration over map when working with server-side subscriptions.
  • Better event String representations.
  • Improvements and fixes in examples.

[0.7.1]

  • Add support for data in SubscribeSuccessEvent. This is a custom data which can be sent by a server towards client connection in subscribe result. Note that due to the bug in Centrifugo server this feature only works in Centrifugo >= v3.0.3.

[0.7.0]

Update to work with Centrifuge >= v0.18.0 and Centrifugo v3.

Breaking change in server behavior. Client History API behavior changed in Centrifuge >= v0.18.0 and Centrifugo >= v3.0.0. When using history call it won't return all publications in a stream by default. See Centrifuge v0.18.0 release notes or Centrifugo v3 migration guide for more information and workaround on server-side.

  • Protocol definitions updated to the latest version
  • History method now accepts optional limit, since and reverse arguments and returns HistoryResult
  • RPC call now requires method name as first argument (you can pass empty string to mimic previous behavior)
  • Publish now returns PublishResult
  • When working with Centrifugo v3 or Centrifuge >= v0.18.0 it's now possible to avoid using ?format=protobuf in connection URL. Client will negotiate Protobuf protocol with a server using WebSocket subprotocol mechanism (in request headers).

[0.6.0]

Null safety migration

  • library dependencies updated to null safe versions
  • library code updated to support null safety in places where required

See issue #47 and pull request #48 for details.

[0.5.1]

  • Skip handling for events from server-side subscriptions resulted in null pointer dereference

[0.5.0]

  • Update protobuf dependency to ^1.0.1, thanks @Holofox

[0.4.1]

  • Implement removeSubscription method, thanks @tiamo

[0.4.0]

  • Breaking changes connected property removed

[0.3.0]

  • Breaking changes Changed API to avoid returning futures where they do not make sense – in connect and subscribe methods.
  • Client now uses Websocket Ping/Pong frames to find broken connection
  • Support for private channel subscription using onPrivateSub configuration callback function
  • Fix several null pointer dereferences in edge cases, throw ClientDisconnectedError when there is an attempt to send protocol request over non-connected client.
  • Fix examples where subscribe could happen before stream handlers set

[0.2.0]

  • Breaking changes Replaced subscribe method with getSubscription in Client.
  • Added reconnection.
  • Added history method to Subscription. Thanks vanelizarov.
  • Added rpc method.

[0.1.0]

  • Added authorization with JWT
  • Added subscription to private channel with JWT

[0.0.1]

  • Initial release

Installing

export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'centrifuge:0.8.0'
pubspec.yaml
name: centrifuge
version: 0.8.0

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

homepage: http://github.com/centrifugal/centrifuge-dart

environment:
 sdk: '>=2.12.0 <3.0.0'

dependencies:
 meta: ^1.3.0
 protobuf: ^2.0.0
 fixnum: ^1.0.0

dev_dependencies:
  test: ^1.17.4
  mockito: ^5.0.7
  build_runner: ^2.0.3

Version history

VersionPublishedArchiveSHA-256
0.0.1Cached · Upstream SHA-256 matchedDownloaddb3faacd…bd6395
0.1.0Cached · Upstream SHA-256 matchedDownload09f7e4de…6b0b62
0.2.0Cached · Upstream SHA-256 matchedDownload23bb4439…ea7ae6
0.3.0Cached · Upstream SHA-256 matchedDownload3b377680…8aab61
0.4.0Cached · Upstream SHA-256 matchedDownload08e6f397…213fbc
0.4.1Cached · Upstream SHA-256 matchedDownload6bb61dec…98094b
0.5.0Cached · Upstream SHA-256 matchedDownloadfd063805…d18ae1
0.5.1Cached · Upstream SHA-256 matchedDownload60d5f869…941458
0.6.0Cached · Upstream SHA-256 matchedDownloadd219ec9a…037c10
0.7.0Cached · Upstream SHA-256 matchedDownload6548eff6…235e80
0.7.1Cached · Upstream SHA-256 matchedDownload56407e60…13ad2c
0.8.0Cached · Upstream SHA-256 matchedDownload5ac2b57e…b7620a
0.9.0Cached · Upstream SHA-256 matchedDownload1f281a39…016252
0.9.1Cached · Upstream SHA-256 matchedDownload0b9abe02…7ab142
0.9.2Cached · Upstream SHA-256 matchedDownloadc261d991…360df3
0.9.3Cached · Upstream SHA-256 matchedDownload4cd31b8b…bd7d34
0.9.4Cached · Upstream SHA-256 matchedDownloadfda87da9…272ec3
0.10.0Cached · Upstream SHA-256 matchedDownloada278ecc0…d447b3
0.11.0Cached · Upstream SHA-256 matchedDownload26bc8e36…65c5ec
0.12.0Cached · Upstream SHA-256 matchedDownload8a836da8…ea9aef
0.13.0Cached · Upstream SHA-256 matchedDownload8cea9670…6c71c8
0.14.0Cached · Upstream SHA-256 matchedDownloadc35b75c7…4e4d47
0.14.1Cached · Upstream SHA-256 matchedDownload15b9aabc…7e2516
0.15.0Cached · Upstream SHA-256 matchedDownloadbc4e20bc…a8eb01
0.15.1Cached · Upstream SHA-256 matchedDownloadbcd1e205…ccdf09
0.16.0Cached · Upstream SHA-256 matchedDownloadb8b3d3c6…522a6d
0.17.0Cached · Upstream SHA-256 matchedDownload96050368…f97c73
0.18.0Cached · Upstream SHA-256 matchedDownloadfa943928…f530ba
0.19.0Cached · Upstream SHA-256 matchedDownload672d21fa…77253d
0.19.1Cached · Upstream SHA-256 matchedDownload27808466…6446ea
0.20.0Cached · Upstream SHA-256 matchedDownloadfae4f687…b2bc6a
0.20.1Cached · Upstream SHA-256 matchedDownload5f172511…1e177d
0.21.0Cached · Upstream SHA-256 matchedDownload7449dc56…2b7969

Dependencies

fixnum "^1.0.0"

meta "^1.3.0"

protobuf "^2.0.0"