GetStream · xsahil03x · Aug 20, 2026 · Aug 20, 2026 · Aug 20, 2026 · Aug 20, 2026
@@ -4,8 +4,14 @@
 
 - Removed the `userId` parameter from `UserToken.anonymous`, anonymous tokens always use `User.anonymousUserId`
 - Removed the `TokenManager.tokenProvider` setter, use `setTokenProvider` instead
+- `StreamWebSocketClient` now takes an `optionsBuilder` instead of `options`, and calls it for every connection attempt
+- Renamed `StreamWebSocketClient.onConnectionEstablished` to `onAuthenticate`, which is what it is called for and when
+- `StreamWebSocketClient.onAuthenticate` is now a `WebSocketAuthenticator`: it is handed a `WsSender` and returns a `Result`, so a failure to authenticate can be observed
 - `TokenManager.userId` is now nullable, and is `null` until an identity is configured
 - `User` now requires a user of type `UserType.anonymous` to carry `User.anonymousUserId` as its id. The constructor is `const`, so a mismatch in a const context fails to compile rather than throwing in debug mode
+- `StreamApiError.isTokenExpiredError` now means the token expired (code 40) rather than any invalid-token code. The rest — not yet valid, used before issued, wrong signature — are `isInvalidTokenError`, along with a wrong API key, since another token does not fix any of them
+- `StreamApiError.isClientError` compares the HTTP `statusCode` against 400..499 rather than the Stream error `code`, which never falls in that range and so never matched
+- `Result.getOrElse`, `getOrDefault`, `recover` and `recoverCatching` no longer take a type parameter of their own and return the result's own type. They previously cast the value to the callback's type, which failed on a successful result — most visibly for a callback that only throws. Kotlin's equivalents widen through a `<R, T : R>` bound that Dart cannot express; to widen here, name the wider type on the result (`Result<num> widened = intResult`), which works because `Result` is covariant, or use `fold`
 
 ### ✨ Features
 
@@ -15,13 +21,28 @@
 - Added `User.anonymousUserId`, the id every anonymous user has
 - Added `TokenManager.unconfigured`, for a client that exists before its user does
 - Added `TokenManager.reset`, which drops the configured identity and its cached token
+- Added `DisconnectionSource.connectTimeout`, reported when a connection attempt is abandoned before the connection is established; it is eligible for automatic reconnection, since a handshake that did not complete in time is the same failure as a connection that stops answering health checks
+- Added `DisconnectionSource.authenticationFailed`, reported with its cause when a connection opens but cannot be authenticated
+- `StreamWebSocketClient` now honours `WebSocketOptions.connectTimeout`, which is no longer nullable and defaults to `WebSocketOptions.defaultConnectTimeout`. This is a behaviour change as well as an API one: a connection previously waited indefinitely for its first health check, and is now abandoned — and reconnected — after 30 seconds, matching the wait the Swift SDK allows for the same handshake
+- Added `WsSender`, the send capability handed to a `WebSocketAuthenticator`
+- Added `WebSocketConnectionState.isExpiredTokenDisconnection`, so a caller that can replace the token knows when to. Automatic reconnection deliberately refuses this case: whoever retries it would present the token the server just refused, and only the caller can obtain another
+- Added `ConnectUserDetailsRequest.fromUser`, which builds the details a client may send from a `User`
+- Added `StreamWebSocketClient.dispose`, which closes the connection along with `events` and `connectionState`; the client is `Disposable`, so `isDisposed` reports whether it has been called
 - Added `teams` field to `User` class
 
 ### 🐛 Bug Fixes
 
 - Fixed `TokenManager.getToken()` contacting the `TokenProvider` on every call instead of returning the cached token
 - Fixed `DynamicTokenProvider` accepting a token issued for a different user than the one requested
 - Fixed `TokenManager` caching a token that finished loading after `expireToken` or `setTokenProvider` had invalidated it
+- Fixed `StreamWebSocketClient.disconnect` completing before the socket was closed, so a `connect` straight afterwards raced the closure and saw the connection go down again
+- Fixed a failure to close the socket leaving `StreamWebSocketClient` reporting itself as disconnecting for good, since the engine reports such a failure rather than notifying its listener
+- Fixed a `WebSocketAuthenticator` that throws, rather than returning a failure, escaping as an unhandled error and leaving the connection authenticating until it timed out — losing the cause, which the timeout does not carry. The natural authenticator throws, since loading a token does
+- Fixed `StreamWebSocketClient.disconnect` replacing the source of a closure already under way, which could turn a reconnectable `ServerInitiated` error into a permanent `ConnectTimeout`
+- Fixed `isAutomaticReconnectionEnabled` neither refusing a deliberate server close nor refusing client errors: it compared the API error's code against the close code 1000, and against a 400..499 range that Stream codes never occupy, so both rules were dead. It now mirrors the iOS SDK — close code 1000, invalid tokens and 4xx all refuse, an expired token does not
+- A connection the server closed because the request was rate limited is now eligible for automatic reconnection. The backend closes it with the rate-limit window's reset in the response headers and a one-minute window, so the condition clears on its own — unlike every other 4xx it can close a socket with, which carry no reset
+- Fixed `ConnectionRecoveryHandler` retrying a first connection attempt, which failed the caller of `connect` and reconnected behind them at the same time — and made the caller's own retry fail with "connection already in progress". It now recovers only connections that have existed since the caller last asked for one, so a deliberate `disconnect` hands connecting back and the next `connect` is the caller's attempt again
+- Fixed a health check arriving while disconnecting reporting the connection as established again, which replaced the disconnection source and could turn a deliberate disconnect into an automatic reconnect
 
 ### 🔄 Changed
 

@@ -69,16 +69,32 @@ class StreamApiError extends Equatable {
   ];
 }
 
-final _tokenInvalidErrorCodes = _range(40, 42);
-final _clientErrorCodes = _range(400, 499);
+// The token this was issued for has expired; another one is accepted.
+const _expiredTokenCode = 40;
+
+// The token cannot be accepted for a reason another token does not fix: not
+// valid yet, used before it was issued, or signed with the wrong secret.
+final _invalidTokenCodes = _range(41, 43);
+
+// The API key itself is wrong, which no token repairs either.
+const _accessKeyErrorCode = 2;
+
+final _clientErrorStatusCodes = _range(400, 499);
 
 /// Extension methods for [StreamApiError] to provide convenient error type checks.
 extension StreamApiErrorExtension on StreamApiError {
-  /// Whether this error indicates an expired or invalid token.
-  bool get isTokenExpiredError => _tokenInvalidErrorCodes.contains(code);
+  /// Whether the token has expired.
+  ///
+  /// Distinct from [isInvalidTokenError]: an expired token is replaced by asking
+  /// the provider for another, where an invalid one is a configuration problem
+  /// that a fresh token presents again.
+  bool get isTokenExpiredError => code == _expiredTokenCode;
+
+  /// Whether the token, or the key it was signed with, cannot be accepted.
+  bool get isInvalidTokenError => _invalidTokenCodes.contains(code) || code == _accessKeyErrorCode;
 
   /// Whether this error is a client-side error (4xx status codes).
-  bool get isClientError => _clientErrorCodes.contains(code);
+  bool get isClientError => _clientErrorStatusCodes.contains(statusCode);
 
   /// Whether this error indicates rate limiting (429 status code).
   bool get isRateLimitError => statusCode == 429;

@@ -1,5 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 
+import 'user.dart';
+
 part 'connect_user_details_request.g.dart';
 
 @JsonSerializable(createFactory: false)
@@ -13,6 +15,24 @@ class ConnectUserDetailsRequest {
     this.custom,
   });
 
+  /// Creates the details a client may send when connecting as [user].
+  ///
+  /// A user's role and teams are left out: the server assigns both and does not
+  /// accept them from a client.
+  ///
+  /// Pass [includeDetails] as `false` to send the id alone.
+  factory ConnectUserDetailsRequest.fromUser(
+    User user, {
+    bool includeDetails = true,
+  }) {
+    return ConnectUserDetailsRequest(
+      id: user.id,
+      name: includeDetails ? user.originalName : null,
+      image: includeDetails ? user.image : null,
+      custom: includeDetails ? user.custom : null,
+    );
+  }
+
   final String id;
   final String? image;
   final bool? invisible;

@@ -58,8 +58,8 @@ extension PatternMatching<T> on Result<T> {
   /// Returns the encapsulated value if this instance represents [Success] or `null`
   /// if it is [Failure].
   ///
-  /// This function is a shorthand for `getOrElse(() => null)` or
-  /// `fold(onSuccess: (it) => it, onFailure: (_) => null)`.
+  /// This function is a shorthand for
+  /// `fold(onSuccess: (it) => it, onFailure: (_, _) => null)`.
   T? getOrNull() {
     return switch (this) {
       Success<T>(:final data) => data,
@@ -90,7 +90,7 @@ extension PatternMatching<T> on Result<T> {
   /// Returns the encapsulated value if this instance represents [Success] or throws the encapsulated error
   /// if it is [Failure].
   ///
-  /// This function is a shorthand for `getOrElse((error) => throw error)`.
+  /// This function is a shorthand for `getOrElse((error, _) => throw error)`.
   T getOrThrow() {
     return switch (this) {
       Success<T>(:final data) => data,
@@ -107,20 +107,27 @@ extension PatternMatching<T> on Result<T> {
   /// Note, that this function rethrows any error thrown by [onFailure] function.
   ///
   /// This function is a shorthand for `fold(onSuccess: (it) => it, onFailure: onFailure)`.
-  R getOrElse<R>(R Function(Object error, StackTrace? stackTrace) onFailure) {
+  ///
+  /// [onFailure] returns this result's own type. To fall back to a supertype,
+  /// widen the result first — `Result<num> widened = intResult` — or use [fold],
+  /// which takes its return type from both branches.
+  T getOrElse(T Function(Object error, StackTrace? stackTrace) onFailure) {
     return switch (this) {
-      Success<T>(:final data) => data as R,
+      Success<T>(:final data) => data,
       Failure(:final error, :final stackTrace) => onFailure(error, stackTrace),
     };
   }
 
   /// Returns the encapsulated value if this instance represents [Success] or the
   /// [defaultValue] if it is [Failure].
   ///
-  /// This function is a shorthand for `getOrElse((_) => defaultValue)`.
-  R getOrDefault<R>(R defaultValue) {
+  /// This function is a shorthand for `getOrElse((_, _) => defaultValue)`.
+  ///
+  /// [defaultValue] is of this result's own type; widen the result to fall back
+  /// to a supertype.
+  T getOrDefault(T defaultValue) {
     return switch (this) {
-      Success<T>(:final data) => data as R,
+      Success<T>(:final data) => data,
       Failure() => defaultValue,
     };
   }
@@ -180,11 +187,14 @@ extension PatternMatching<T> on Result<T> {
   ///
   /// Note, that this function rethrows any error thrown by [transform] function.
   /// See [recoverCatching] for an alternative that encapsulates errors.
-  Result<R> recover<R>(
-    R Function(Object error, StackTrace? stackTrace) transform,
+  ///
+  /// [transform] returns this result's own type, so widening is done on the way
+  /// in rather than on the way out: widen the result first, then recover.
+  Result<T> recover(
+    T Function(Object error, StackTrace? stackTrace) transform,
   ) {
     return switch (this) {
-      Success<T>(:final data) => Result.success(data as R),
+      Success<T>() => this,
       Failure(:final error, :final stackTrace) => Result.success(
         transform(error, stackTrace),
       ),
@@ -196,11 +206,14 @@ extension PatternMatching<T> on Result<T> {
   ///
   /// This function catches any error thrown by [transform] function and encapsulates it as a failure.
   /// See [recover] for an alternative that rethrows errors.
-  Result<R> recoverCatching<R>(
-    R Function(Object error, StackTrace? stackTrace) transform,
+  ///
+  /// [transform] returns this result's own type, so widening is done on the way
+  /// in rather than on the way out: widen the result first, then recover.
+  Result<T> recoverCatching(
+    T Function(Object error, StackTrace? stackTrace) transform,
   ) {
     return switch (this) {
-      Success<T>(:final data) => Result.success(data as R),
+      Success<T>() => this,
       Failure(:final error, :final stackTrace) => runSafelySync(
         () => transform(error, stackTrace),
       ),

@@ -195,8 +195,6 @@ class WebSocketEngineException extends Equatable implements Exception {
     return null;
   }
 
-  static const stopErrorCode = 1000;
-
   @override
   List<Object?> get props => [reason, code, error];
 }
@@ -22,7 +22,7 @@ class WebSocketOptions {
   /// Creates a new instance of [WebSocketOptions].
   const WebSocketOptions({
     required this.url,
-    this.connectTimeout,
+    this.connectTimeout = defaultConnectTimeout,
     this.protocols,
     this.queryParameters,
   });
@@ -35,9 +35,17 @@ class WebSocketOptions {
 
   /// Maximum time allowed for establishing the WebSocket connection.
   ///
-  /// When specified, the connection attempt will timeout if not completed
-  /// within this duration. If `null`, uses the platform default timeout.
-  final Duration? connectTimeout;
+  /// Covers the whole attempt, not just opening the socket: a connection that
+  /// opens but is never established is abandoned once this elapses.
+  ///
+  /// Defaults to [defaultConnectTimeout].
+  final Duration connectTimeout;
+
+  /// The [connectTimeout] used when none is given.
+  ///
+  /// Matches the wait the Swift SDK allows for the same handshake; the Android
+  /// one is stricter at ten seconds.
+  static const defaultConnectTimeout = Duration(seconds: 30);
 
   /// WebSocket sub-protocols to negotiate during the handshake.
   ///

@@ -18,6 +18,10 @@ import 'retry_strategy.dart';
 /// when reconnection should occur, implementing exponential backoff with jitter for optimal
 /// retry behavior.
 ///
+/// It recovers connections that existed: until [StreamWebSocketClient.connect] has established
+/// one, connecting belongs to whoever called it and was handed the failure. A first attempt that
+/// fails is therefore not retried here, including when the network returns.
+///
 /// ## Built-in Policies
 ///
 /// The handler automatically includes several reconnection policies:
@@ -79,6 +83,11 @@ class ConnectionRecoveryHandler extends Disposable {
 
   late final _subscriptions = CompositeSubscription();
 
+  // Whether a connection has been established since the caller last asked for
+  // one: it is what separates a drop this handler recovers from an attempt whose
+  // outcome the caller is waiting on.
+  var _hasConnected = false;
+
   /// Attempts reconnection if policies allow it.
   ///
   /// Evaluates all configured policies and initiates reconnection when conditions are met.
@@ -117,7 +126,15 @@ class ConnectionRecoveryHandler extends Disposable {
     _reconnectionTimer = null;
   }
 
-  bool _canBeReconnected() => _policies.every((it) => it.canBeReconnected());
+  bool _canBeReconnected() {
+    // Until a connection has existed, connecting belongs to whoever called
+    // `connect` and was handed the failure. Retrying here as well would work
+    // behind a caller already told the attempt failed — and would race the
+    // retry that caller makes in response.
+    if (!_hasConnected) return false;
+
+    return _policies.every((it) => it.canBeReconnected());
+  }
 
   bool _canBeDisconnected() {
     return switch (_client.connectionState.value) {
@@ -147,13 +164,29 @@ class ConnectionRecoveryHandler extends Disposable {
   void _onConnectionStateChanged(WebSocketConnectionState state) {
     return switch (state) {
       Connecting() => _cancelReconnection(),
-      Connected() => _reconnectStrategy.resetConsecutiveFailures(),
-      Disconnected() => _scheduleReconnectionIfNeeded(),
+      Connected() => _onConnectionEstablished(),
+      Disconnected(:final source) => _onConnectionLost(source),
       // These states do not require any action.
       Initialized() || Authenticating() || Disconnecting() => () {},
     };
   }
 
+  // A connection exists, so keeping it is this handler's job from here, and the
+  // failures the backoff had accumulated are behind us.
+  void _onConnectionEstablished() {
+    _hasConnected = true;
+    return _reconnectStrategy.resetConsecutiveFailures();
+  }
+
+  // A disconnect the caller asked for hands connecting back to them, so the next
+  // `connect` is a fresh attempt they await rather than a drop to recover. A
+  // system-initiated one is the opposite: backgrounding and network loss are what
+  // this handler exists to come back from.
+  void _onConnectionLost(DisconnectionSource source) {
+    if (source is UserInitiated) _hasConnected = false;
+    return _scheduleReconnectionIfNeeded();
+  }
+
   @override
   Future<void> dispose() async {
     _cancelReconnection();