NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev
pub.dev, #1368 most downloaded on pub.dev
Dart client to communicate with Centrifuge and Centrifugo from Flutter and VM over WebSockets
Latest stable
0.21.0
Last release 1 months ago
20 Oct 2026
Ships fairly regularly
a new release about every 3 months
Nearly every release is documented
notes for 33 of 33 stable releases
Nothing withdrawn
no release was ever pulled
8 years old
33 releases · first in 2018
Drag across the ruler to compare, or tap a release to open it.
A stability release. Connection, subscription and token handling were reviewed against a validation harness and against centrifuge-js. The harness cov
A stability release. Connection, subscription and token handling were reviewed against a validation harness and against centrifuge-js. The harness covers seeded chaos against a fake server, a real Centrifugo behind fault-injecting proxies, and browsers under dart2js and dart2wasm. Most fixes cover races between reconnects, event listeners calling back into the client, teardown, token refresh, and browser behaviour. Every fix comes with a regression test.
connect() validates the endpoint. It throws the new ConfigurationError, without changing the client state, when the endpoint can't be opened as a websocket on the platform. Such endpoints used to be retried forever as transport errors, calling getToken and getData on every attempt.
getToken stops the client. The client emits a ConfigurationError error event and disconnects as unauthorized, as centrifuge-js does, instead of reconnecting with the expired token forever. Call setToken() with a new token, then connect(). With getToken configured, the next attempt still calls getToken, even after setToken(). PRs: #129, #154.badProtocol and reason "exception during message handling: ...", without reconnecting, as centrifuge-js does. The exception is still reported as uncaught. Before, the rest of that websocket message was lost, including replies to pending calls, and the client went on. The same now applies to a publication recovered in a subscribe reply that fails to decode, e.g. a delta without base data: before, the error went unnoticed and the rest of the recovered publications were dropped. PRs: #131, #177.badProtocol and reason "exception in event handler: ...", without reconnecting, as centrifuge-js does; call connect() to start again. The exception is still reported as uncaught in the listener's zone. Listeners after the failing one don't get that event, and the SDK's own processing completes as if the listener had returned. A publication whose listener threw doesn't count as delivered, so after connect() a recoverable subscription receives it again. Before, the exception was reported and otherwise ignored, and the client went on. Catch errors in your listeners. PR: #177.ClientConfig.timeout (10s by default). It's aborted on timeout, and on disconnect() or close() while in progress. Before, a server that accepted the connection but never answered the upgrade left the client connecting forever, and every attempt against it leaked its socket: two file descriptors per attempt, measured at 824 open descriptors after 400 attempts, until the process hit its limit and could no longer connect at all.
unsubscribed is emitted when unsubscribe() is called, before the server replies, instead of after the reply. The Unsubscribe command is sent before the event, so a subscribe() from its listener follows it. PRs: #128, #133.removeSubscription() unregisters the subscription at once.
subscriptions() returns an unmodifiable copy instead of the client's live registry. Code can remove subscriptions while iterating over it. PR: #150.ready() returns a failed future instead of throwing synchronously when the client is disconnected or closed, or the subscription is unsubscribed. await ready() inside try catches the error as before; ready().catchError(...) now gets it too. PR: #163.connect() or subscribe() doesn't fail. A second call while connecting or subscribing still waits for the attempt in progress. Like the first call, it now completes without an error if that attempt ends in a disconnect or unsubscribe, instead of leaving an uncaught error when not awaited. PR: #164.StateError: Cannot fire new event. PR: #127.timeout means no timeout also for calls waiting for the client or a subscription to become ready; they used to fail at once. PR: #156.getToken is kept, and the client reconnects or resubscribes with it. The server rejects it if it's no longer valid. PRs: #129, #152.disconnect(), setToken() and connect() during a pending attempt no longer connect with the old token.connect() after disconnect() is no longer dropped while the old attempt runs.disconnect() closes the pending attempt's transport.getData is awaited no longer loses its reconnect.disconnect() or connect() from connecting, connected, disconnected, subscribing and error listeners leaves consistent state and one connection attempt, with no duplicate events, no ConcurrentModificationError and no leftover ping or refresh timers.connect() from a disconnected listener after getToken threw UnauthorizedException no longer leaves the client connecting forever. PR: #124.disconnect() fails with ClientDisconnectedError instead of a null-check TypeError.ready() no longer leave waiters behind.unsubscribe(), disconnect() or removeSubscription(). This covers:
unsubscribe() can no longer mark the subscription subscribed, or leave a server-side subscription the client doesn't track.unsubscribe() during a subscribe in flight sends an Unsubscribe and it fails, the client reconnects, as after a failed Unsubscribe of a subscribed subscription and as in centrifuge-js. Before, the server could keep the subscription and push its publications until the connection ended. A failure arriving after that connection ended no longer reconnects the next one.Publication.epoch. PR: #170.unsubscribe() and subscribe() from a publication listener no longer recover that publication again. PR: #142.getToken that throws TimeoutException is handled like other getToken errors instead of reconnecting the whole client. PR: #143.removeSubscription() and subscribe:
ready() no longer resolves after a subscribed listener tore the subscription down. PR: #148.getToken resolves after a reconnect or resubscribe no longer starts a second refresh chain for the life of the connection or subscription. PR: #129.getToken during a refresh means unauthorized, as documented and as in centrifuge-js. It disconnects the client, or unsubscribes the subscription, instead of sending a refresh without a token. PR: #122.getToken no longer fails into an endless retry loop when the server reports an expiry. PR: #120.connect() or subscribe() from its listener gets a new token. PR: #137.toString(): UnauthorizedException.toString() includes its message, and MessageEvent.toString() is well-formed. PRs: #118, #119.Two Centrifugo bugs found during this validation are fixed in Centrifugo v6.9.6 (centrifugal/centrifuge#629 and #627):
since at the top of the stream, gets the next publication as a delta without base data. With this release the client then disconnects with badProtocol; earlier versions dropped every publication on the channel.test/web_endpoint_test.dart runs in a browser: dart test -p chrome test/web_endpoint_test.dart, optionally with --compiler dart2wasm. CI runs it in Chrome under both compilers.package:lints with strict casts and raw types, and covers the tests too. The code is formatted with dart format, and CI checks it. The unused mockito and build_runner dev dependencies and the old tool/test.sh are removed. example/chat_app is removed too: it depended on the discontinued dash_chat package and no longer built. The public API and the minimum Dart SDK (3.7) are unchanged.Some PRs in this release fix issues introduced by earlier PRs of the same release: #135, #136, #144, #149, #157 and parts of the PRs above. They are not listed separately, since v0.20.1 was not affected.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Fix WebSocket transport selection on dart2wasm builds by @VangThao1905 in https://github.com/centrifugal/centrifuge-dart/pull/115
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.20.0...v0.20.1
Transport resolving to the dart:io (IOWebSocketChannel) implementation instead of the browser one (HtmlWebSocketChannel) when compiled with dart2wasm. The conditional import in transport.dart used to check dart.library.html, which is not declared under the wasm compile target — Flutter Web's wasm target has no dart:html and relies on dart:js_interop instead — so the WebSocket transport silently fell back to the VM implementation and never connected in the browser. Switched the check to dart.library.js_interop, which is declared for both dart2js and dart2wasm web builds while remaining unavailable on native (VM) targets, so native platforms keep using dart:io as before.Support getState callback by @FZambia in https://github.com/centrifugal/centrifuge-dart/pull/110
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.19.1...v0.20.0
SubscriptionConfig.getState callback support (requires Centrifugo >= 6.8.0), mirroring the same option in centrifuge-js. The callback lets the application load its state from its own source of truth and return the corresponding stream position — the SDK then subscribes with recovery from that position, so no publications are lost between the state read and the subscribe. The callback is invoked on initial subscribe (when there is no saved position) and again when the server reports an unrecoverable position (error 112 — the SDK requests this behavior via the reject_unrecovered subscribe flag). It is NOT called on reconnects where server-side recovery succeeds. Errors thrown from the callback emit a subscription error event with the new SubscriptionGetStateError type and are retried with backoff.channel_compaction flag, and when the server supports and allows it (Centrifugo PRO allow_channel_compaction namespace option) publication/join/leave pushes carry a short numeric channel ID instead of the string channel name — the SDK routes such pushes via an internal ID registry. Servers without compaction support simply ignore the flag, so behavior is unchanged there.Filter helpers and pass it via SubscriptionConfig.tagsFilter, or change it at runtime with Subscription.setTagsFilter(). A tags filter cannot be combined with delta compression. #112wasRecovering=true, recovered=false — letting the app reload via its existing recovery-failure path rather than looking like a brand-new first subscribe. A non-recoverable subscription simply resubscribes. #113Fix connection and subscription stability bugs by @FZambia in https://github.com/centrifugal/centrifuge-dart/pull/109
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.19.0...v0.19.1
Client.send() to use SendRequest instead of the deprecated Message type so async messages reach the server again.subscribing (codes 2500/3007 and other temporary codes) now trigger an immediate resubscribe instead of waiting for a reconnect that may never come.unsubscribe() or disconnect() arrives while getToken is awaiting.Client.close() and Subscription.close() no longer emit error/unsubscribed events after the resource is closed; pending ready() futures on a closed subscription are completed with SubscriptionUnsubscribedError and any timers are cancelled.ClientDisconnectedError thrown by an in-flight ConnectRequest no longer cancels the reconnect timer that the transport's onDone already scheduled (previously left the client stuck in connecting).onError callback instead of crashing the socket listener.getData callback are caught: an error event is emitted and the transport is closed (instead of an unhandled async exception)._refreshToken no longer issues a RefreshRequest if the client is not connected anymore by the time the token callback resolves.getToken is no longer invoked when the user did not configure one (previous check could call a null callback in edge cases).backoffDelay returns minDelay when the computed range collapses to zero, avoiding RangeError from Random.nextInt(0).Add Client.close() — disconnects and releases all client resources (closes every event stream and removes every subscription). The client is unusable
Client.close() — disconnects and releases all client resources (closes every event stream and removes every subscription). The client is unusable after close(); subsequent public method calls throw ClientClosedError. Use Client.disconnect() for a temporary disconnect that keeps the client usable. #106await client.disconnect() now actually waits for transport teardown before resolving.3014 (connection state invalidated) and unsubscribe code 2502 (subscription state invalidated) now correctly clear the relevant token and recovery state, forcing a fresh getToken on reconnect.1009 (message size limit) is now terminal (no auto-reconnect), matching the behavior in centrifuge-js.SubscribeRequest is in flight now sends a cleanup Unsubscribe to the server, preventing a "ghost" server-side subscription that keeps pushing publications to the local sub.unsubscribe()/disconnect during a subscribe round-trip can no longer flip the subscription state back to Subscribed.ClientDisconnectedError thrown type.ClientConfig.tlsSkipVerify through to the WebSocket transport on VM/Flutter (dart:io) platforms — was a silent no-op before. Useful for wss:// development against a self-signed cert. Web platforms ignore the flag, since the browser owns TLS validation. #107getToken retries, and several race-condition tests, all running against the docker-compose Centrifugo.Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.18.0...v0.19.0
Allow protobuf v6, drop Protobuf v3/v4, min SDK 3.7 by @FZambia in https://github.com/centrifugal/centrifuge-dart/pull/104
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.17.0...v0.18.0
Allow Protobuf v5 dependency by @FZambia in https://github.com/centrifugal/centrifuge-dart/pull/102
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.16.0...v0.17.0
Allow usage of protobuf v4, drop protobuf v2 by @FZambia in https://github.com/centrifugal/centrifuge-dart/pull/100
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.15.1...v0.16.0
Support Fossil delta compression by @FZambia in https://github.com/centrifugal/centrifuge-dart/pull/97
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.15.0...v0.15.1
This release changes headers in ClientConfig from Map to Map . This is a breaking change, but it must not cause huge troubles beyond a simple refactor…
web_socket_channel, min Dart SDK is now 3.3 #91setHeaders method to update headers #92.This release changes headers in ClientConfig from Map<String, dynamic> to Map<String, String>. This is a breaking change, but it must not cause huge troubles beyond a simple refactoring.
Usages of dart.html were removed in this release. Also some internal optimizations were done to allocate less when constructing Protobuf command data.
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.14.1...v0.15.0
Add renew connection data callback by @Holofox in https://github.com/centrifugal/centrifuge-dart/pull/88
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.14.0...v0.14.1
connInfo and chanInfo for join/leave events by @hetao29 #84
connInfo and chanInfo for join/leave events by @hetao29 #84Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.13.0...v0.14.0
Relax Protobuf dependency requirements to be >=2.0.0 <4.0.0 instead of ^3.0.0
>=2.0.0 <4.0.0 instead of ^3.0.0Fix websocket usage in web env (fixes The method 'sendByteBuffer' isn't defined for the type 'WebSocket' error), add simple web example #85
The method 'sendByteBuffer' isn't defined for the type 'WebSocket' error), add simple web example #85Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.11.0...v0.12.0
Update protobuf dependency from ^2.0.0 to ^3.0.0
^2.0.0 to ^3.0.0'>=2.19.0 <4.0.0'Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.10.0...v0.11.0
Breaking change! This release changes the semantics of working with connection tokens described in Centrifugo v5 release post.
Breaking change! This release changes the semantics of working with connection tokens described in Centrifugo v5 release post.
Previously, returning an empty token string from getToken callback resulted in client disconnection with unauthorized reason.
Now returning an empty string from getToken is a valid scenario which won't result into disconnect on the client side. It's still possible to disconnect client by throwing a special UnauthorizedException from getToken function.
And we are putting back setToken method to the SDK – so it's now possible to reset the token to be empty upon user logout.
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.9.4...v0.10.0
Improving reconnect behaviour upon bad network conditions (like connect timeout), #79
feat: add web support by @robert-virkus in https://github.com/centrifugal/centrifuge-dart/pull/73
Full Changelog: https://github.com/centrifugal/centrifuge-dart/compare/v0.9.2...v0.9.3
Fix null check for close reason, fixes #66
Fix setting initial connection token #63
UnsubscribedEventThis release adopts a new iteration of Centrifugal protocol and a new iteration of API. Client now behaves according to the client SDK API specificati
Breaking changes
This release adopts a new iteration of Centrifugal protocol and a new iteration of API. Client now behaves according to the client SDK API specification. The work has been done according to Centrifugo v4 roadmap.
Check out Centrifugo v4 release post that covers the reasoning behind changes.
All the current core features of Centrifugal client protocol are now supported here.
New release only works with Centrifugo >= v4.0.0 and Centrifuge >= 0.25.0. See Centrifugo v4 migration guide for details about the changes in the ecosystem.
Note, that Centrifugo v4 supports clients working over the previous protocol iteration, so you can update Centrifugo to v4 without any changes on the client side (but you need to turn on use_client_protocol_v1_by_default option in the configuration of Centrifugo, see Centrifugo v4 migration guide for details).
It pushes client closer to other clients in the ecosystem. It also contains several backwards incompatible changes.
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.
Client.connect, Client.disconnect, Subscription.subscribe, Subscription.unsubscribe methods - addresses #31.DisconnectEvent on connection error - this makes behavior of centrifuge-dart similar to all other our clients - addresses #56.ErrorEvent - each transport failure will emit error to this stream - addresses #56.subscribing and error statuses. This change is mostly internal should not affect working with Subscriptions.UnsubscribeEvent if subscription is not successfully subscribed (i.e. in subscribed state). This makes behavior of centrifuge-dart similar to all other our clients.Client.Disconnect method - make it more similar to all other connector libraries in ecosystem.TimeoutException. Also - properly pass timeout to the transport (was not before!). Again – this makes client behave similarly to all other connectors.presence and presenceStats methods for Subscription and on client top level (for server-side subscriptions).streamPosition in SubscribeSuccessEvent.streamPosition in ServerSubscribeEvent.data in ServerSubscribeEvent.send method to send async messages to a server.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
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.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…
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.
limit, since and reverse arguments and returns HistoryResultPublishResult?format=protobuf in connection URL. Client will negotiate Protobuf protocol with a server using WebSocket subprotocol mechanism (in request headers).library dependencies updated to null safe versions
Skip handling for events from server-side subscriptions resulted in null pointer dereference
Update protobuf dependency to ^1.0.1, thanks @Holofox
^1.0.1, thanks @HolofoxImplement removeSubscription method, thanks @tiamo
removeSubscription method, thanks @tiamoBreaking changes connected property removed
connected property removedBreaking changes Changed API to avoid returning futures where they do not make sense – in connect and subscribe methods.
connect and subscribe methods.onPrivateSub configuration callback functionClientDisconnectedError when there is an attempt to send protocol request over non-connected client.Breaking changes Replaced subscribe method with getSubscription in Client.
Added subscription to private channel with JWT
* Initial release
One column per quarter.