GetStream · xsahil03x · Aug 19, 2026 · Aug 19, 2026 · Aug 19, 2026 · Aug 19, 2026
@@ -528,8 +528,12 @@ explaining the purpose of the item. Subsequent paragraphs elaborate. Avoid multi
 sentence first paragraphs — the first paragraph gets extracted for tables of
 contents.
 
-When referencing a parameter, use backticks. When referencing a parameter that also
-corresponds to a property, use square brackets instead.
+When referencing a parameter, use square brackets, as
+[Effective Dart](https://dart.dev/effective-dart/documentation#do-use-square-brackets-in-doc-comments-to-refer-to-in-scope-identifiers)
+does — `dart doc` resolves them and links to the declaration.
+
+Reserve backticks for names that are *not* in scope where the comment sits: a private
+constructor argument named from a class-level doc, or a type from another package.
 
 Avoid using "above" or "below" to reference other dartdoc sections. Dartdoc pages
 are often viewed in isolation.

@@ -2,10 +2,18 @@
 
 ### 💥 BREAKING CHANGES
 
+- Raised the minimum Dart SDK to `^3.12.0`
 - Removed the `userId` parameter from `UserToken.anonymous`, anonymous tokens always use `User.anonymousUserId`
 - Removed the `TokenManager.tokenProvider` setter, use `setTokenProvider` instead
 - `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. A mismatch fails to compile in a const context, and throws in debug mode otherwise
+- `StreamWebSocketClient` now takes an `optionsBuilder` instead of `options`, called once per connection attempt
+- Renamed `StreamWebSocketClient.onConnectionEstablished` to `onAuthenticate`, now a `WebSocketAuthenticator`. It is handed a `WsRequestSender` and the error the server closed the previous attempt with, and throws to say the credentials did not go out
+- Removed `WebSocketEngineException.stopErrorCode`, use `CloseCode.normalClosure`
+- `AuthInterceptor` extends `Interceptor` rather than `QueuedInterceptor`, so requests are no longer serialised against one another
+- `WebSocketConnectionState.isAutomaticReconnectionEnabled` is now `true` for an expired token, and remains `false` for token errors a fresh token cannot fix
+- `StreamApiError.isTokenExpiredError` now means code 40 only; the other token codes and a wrong API key are `isInvalidTokenError`. `isClientError` compares the HTTP `statusCode` against 400..499, rather than the Stream error `code`, which never falls in that range
+- `Result.getOrElse`, `getOrDefault`, `recover` and `recoverCatching` return the result's own type and no longer take a type parameter. To widen, widen the result (`Result<num> widened = intResult`) or use `fold`
 
 ### ✨ Features
 
@@ -16,19 +24,31 @@
 - Added `User.anonymousUserId`, the id every anonymous user has
 - Added `TokenManager.unconfigured`, for a client that exists before its user does, and `TokenManager.reset`, which drops the configured identity and its cached token
 - Added `teams` field to `User` class
+- Added `DioException.apiError`, the Stream API error a response carried, or `null` for anything else
+- Added `DisconnectionSource.connectTimeout` and `authenticationFailed`, and `isReconnectable`, whether a connection closed for that reason is worth opening again
+- 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 now `Disposable`, and `connect` throws a `StateError` afterwards
+- `StreamWebSocketClient` now honours `WebSocketOptions.connectTimeout`, no longer nullable and 30 seconds by default, so an attempt that never becomes usable is abandoned
 
 ### 🐛 Bug Fixes
 
 - Fixed three faults in `TokenManager`'s token cache: `getToken` contacted the provider on every call instead of returning the cached token, handed out a token that had already expired rather than replacing it, and cached one that finished loading after `expireToken` or `setTokenProvider` had invalidated it. A static provider is left alone, having nothing fresher to give
 - Fixed `DynamicTokenProvider` accepting a token issued for a different user than the one requested
+- Fixed several faults in the token-expired retry: it was skipped when the response carried no JSON content type, never completed at all when the replacement was refused too, re-sent a multipart body whose streams the refused attempt had consumed, and expired a token another request had already replaced
+- `StreamWebSocketClient` no longer prints to the console
+- Fixed a connection that could be left open, or left disconnecting for good: `connect` leaked the socket of a failed handshake, `disconnect` completed before the socket had closed, and a close that failed or found no socket reported no closure at all
+- Fixed reconnection eligibility: the deliberate-close and client-error checks never matched, and a rate limit was treated as permanent when it clears on its own
+- Fixed `ConnectionRecoveryHandler` retrying a first connection attempt, which reconnected behind the caller of `connect`; only established connections are recovered now
+- Fixed a health check arriving while disconnecting reporting the connection as established again, turning a deliberate disconnect into a reconnect
 
 ### 🔄 Changed
 
-- Raised the minimum Dart SDK to `^3.12.0`
+- `ConnectUserDetailsRequest` leaves its unset fields out of the JSON it serialises, rather than sending them as nulls
 - Anonymous requests now always send `user_id=!anon`, rather than whatever id the `TokenManager` was configured with
 - `DynamicTokenProvider` checks the token type before its user id, so a token of the wrong type is reported as such instead of as a mismatched user
 - `TokenManager.getToken` fails when `reset` runs while the token is loading, and rejects a token whose `user_id` is not the user it was loading for; a `setTokenProvider` during a load still serves the caller that started it
-- `AuthInterceptor` no longer attempts a token refresh when the manager has no identity, so the original token-expired error is surfaced rather than a failure to load a token
+- `AuthInterceptor` no longer refreshes a token when the manager has no identity, so the original error is surfaced, and no longer retries a request signed for a user it has since been pointed away from, which would have performed one user's request as another
+- `StreamWebSocketEngine.open` fails when a connection is already open, rather than closing it to make room
 
 ## 0.4.0
 

@@ -0,0 +1,3 @@
+tags:
+  # Tests that drive a fully wired `StreamWebSocketClient` against a fake server.
+  ws-client:
@@ -3,7 +3,7 @@ import 'package:dio/dio.dart';
 import '../stream_core_dio_error.dart';
 
 class ApiErrorInterceptor extends Interceptor {
-  /// Initializes a new instance of [ApiErrorInterceptor].
+  /// Creates a new [ApiErrorInterceptor].
   const ApiErrorInterceptor();
 
   @override

@@ -1,7 +1,7 @@
 import 'package:dio/dio.dart';
 
 class ApiKeyInterceptor extends Interceptor {
-  /// Initialize a new API key interceptor
+  /// Creates a new [ApiKeyInterceptor].
   const ApiKeyInterceptor(this.apiKey);
 
   /// The API key to be added to the request headers

@@ -4,17 +4,21 @@ import '../../errors.dart';
 import '../../user.dart';
 import '../stream_core_dio_error.dart';
 
-/// Authentication interceptor that refreshes the token if
-/// an auth error is received
-class AuthInterceptor extends QueuedInterceptor {
-  /// Initialize a new auth interceptor
+/// Interceptor that signs every request with the caller's token.
+///
+/// A request the server refuses for an expired token is retried once, carrying a replacement.
+class AuthInterceptor extends Interceptor {
+  /// Creates a new [AuthInterceptor].
   AuthInterceptor(this._dio, this._tokenManager);
 
   final Dio _dio;
-
-  /// The token manager used in the client
   final TokenManager _tokenManager;
 
+  // Not a `QueuedInterceptor`: it frees a slot only once a handler completes, so the retry sent from
+  // `onError` would wait behind the request holding it. `TokenManager` serialises the token loads.
+
+  static const _retriedKey = 'stream_core.auth_token_retried';
+
   @override
   Future<void> onRequest(
     RequestOptions options,
@@ -38,7 +42,7 @@ class AuthInterceptor extends QueuedInterceptor {
       final dioError = StreamDioException(
         exception: error,
         requestOptions: options,
-        stackTrace: StackTrace.current,
+        stackTrace: stackTrace,
       );
 
       return handler.reject(dioError, true);
@@ -50,30 +54,36 @@ class AuthInterceptor extends QueuedInterceptor {
     DioException err,
     ErrorInterceptorHandler handler,
   ) async {
-    final data = err.response?.data;
-    if (data == null || data is! Map<String, dynamic>) {
-      return handler.next(err);
-    }
+    final error = err.apiError;
+    if (error == null || !error.isTokenExpiredError) return handler.next(err);
 
-    final error = StreamApiError.fromJson(data);
-    if (error.isTokenExpiredError) {
-      // Don't try to refresh the token when there is no user to load one for,
-      // or when the provider would return the same token again.
-      final canRefresh = _tokenManager.userId != null && !_tokenManager.usesStaticProvider;
-      if (!canRefresh) return handler.next(err);
-      // Otherwise, mark the current token as expired.
-      _tokenManager.expireToken();
+    final options = err.requestOptions;
 
-      try {
-        final options = err.requestOptions;
-        // ignore: inference_failure_on_function_invocation
-        final response = await _dio.fetch(options);
-        return handler.resolve(response);
-      } on DioException catch (exception) {
-        return handler.next(exception);
-      }
+    // A retry after a user switch would perform this request as the new user.
+    final signedFor = options.queryParameters['user_id'];
+    final canRefresh = signedFor == _tokenManager.userId && !_tokenManager.usesStaticProvider;
+    if (!canRefresh) return handler.next(err);
+
+    if (options.extra[_retriedKey] == true) return handler.next(err);
+
+    // Another request may have replaced it already, and expiring that would discard a valid token.
+    if (options.headers['Authorization'] == _tokenManager.peekToken()?.rawValue) {
+      _tokenManager.expireToken();
     }
 
-    return handler.next(err);
+    // The multipart body is cloned because the refused attempt already consumed its streams.
+    final data = options.data;
+    final retry = options.copyWith(
+      extra: {...options.extra, _retriedKey: true},
+      data: data is FormData ? data.clone() : data,
+    );
+
+    try {
+      // ignore: inference_failure_on_function_invocation
+      final response = await _dio.fetch(retry);
+      return handler.resolve(response);
+    } on DioException catch (exception) {
+      return handler.reject(exception);
+    }
   }
 }
@@ -2,9 +2,9 @@ import 'package:dio/dio.dart';
 
 typedef ConnectionIdGetter = String? Function();
 
-/// Interceptor that injects the connection id in the request params
+/// Interceptor that injects the connection id into the request params.
 class ConnectionIdInterceptor extends Interceptor {
-  /// Initialize a new [ConnectionIdInterceptor].
+  /// Creates a new [ConnectionIdInterceptor].
   const ConnectionIdInterceptor(this._connectionId);
 
   /// The getter for the connection id.

@@ -4,7 +4,7 @@ import '../system_environment_manager.dart';
 
 /// Interceptor that sets additional headers for all requests.
 class HeadersInterceptor extends Interceptor {
-  /// Initialize a new [HeadersInterceptor].
+  /// Creates a new [HeadersInterceptor].
   const HeadersInterceptor(this._systemEnvironmentManager);
 
   final SystemEnvironmentManager _systemEnvironmentManager;

@@ -23,7 +23,7 @@ void _defaultLogPrint(InterceptStep step, Object object) => print(object);
 
 /// Interceptor dedicated to logging
 class LoggingInterceptor extends Interceptor {
-  /// Initialize a new logging interceptor
+  /// Creates a new [LoggingInterceptor].
   LoggingInterceptor({
     this.request = true,
     this.requestHeader = false,

@@ -2,9 +2,9 @@ import 'dart:convert';
 
 import '../../stream_core.dart';
 
-/// Error class specific to StreamChat and Dio
+/// A [DioException] carrying the Stream [ClientException] that caused it.
 class StreamDioException extends DioException {
-  /// Initialize a stream chat dio error
+  /// Creates a [StreamDioException] for [exception].
   StreamDioException({
     required this.exception,
     required super.requestOptions,
@@ -21,16 +21,25 @@ class StreamDioException extends DioException {
 }
 
 extension StreamDioExceptionExtension on DioException {
-  HttpClientException toClientException() {
-    final apiErrorResult = runSafelySync(
-      () => switch (response?.data) {
-        final Map<String, Object?> data => StreamApiError.fromJson(data),
-        final String data => StreamApiError.fromJson(jsonDecode(data) as Map<String, Object?>),
-        _ => null,
-      },
-    );
+  /// The Stream API error this exception's response carried, or `null` when it carried something else.
+  ///
+  /// A Stream error is recognised whether the server sent it as JSON or as plain text. A body that is
+  /// not one — a proxy or gateway answering with an error of its own — reads as `null` rather than
+  /// throwing.
+  StreamApiError? get apiError => runSafelySync(() {
+    final data = response?.data;
+    final json = data is String ? jsonDecode(data) : data;
+    if (json is! Map<String, Object?>) return null;
 
-    final apiError = apiErrorResult.getOrNull();
+    return StreamApiError.fromJson(json);
+  }).getOrNull();
+
+  /// This exception as an [HttpClientException].
+  ///
+  /// Takes its message, status code and cause from [apiError] when the response carried one, and
+  /// from what the transport reported otherwise. A request the caller cancelled is marked as such.
+  HttpClientException toClientException() {
+    final apiError = this.apiError;
 
     return HttpClientException(
       message: apiError?.message ?? response?.statusMessage ?? message ?? '',

@@ -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 (error code 40).
+  ///
+  /// Distinct from [isInvalidTokenError]: an expired token is fixed by loading another one, whereas
+  /// an invalid token is a configuration problem that a fresh token reproduces.
+  bool get isTokenExpiredError => code == _expiredTokenCode;
+
+  /// Whether the token, or the API key it was signed with, cannot be accepted
+  /// (error codes 41 to 43, and 2).
+  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,8 +1,11 @@
 import 'package:json_annotation/json_annotation.dart';
 
+import '../utils/standard.dart';
+import 'user.dart';
+
 part 'connect_user_details_request.g.dart';
 
-@JsonSerializable(createFactory: false)
+@JsonSerializable(createFactory: false, includeIfNull: false)
 class ConnectUserDetailsRequest {
   const ConnectUserDetailsRequest({
     required this.id,
@@ -13,6 +16,27 @@ class ConnectUserDetailsRequest {
     this.custom,
   });
 
+  /// Creates the details to send when connecting as [user].
+  ///
+  /// Pass [includeDetails] as `false` to send the id alone.
+  ///
+  /// The name comes from [User.originalName] rather than [User.name], so a user who was never given
+  /// one does not have their id sent as their name. [User.role] and [User.teams] are left out
+  /// deliberately: the server assigns both and ignores whatever a client claims for them.
+  factory ConnectUserDetailsRequest.fromUser(
+    User user, {
+    bool includeDetails = true,
+  }) {
+    final details = user.takeIf((_) => includeDetails);
+
+    return ConnectUserDetailsRequest(
+      id: user.id,
+      name: details?.originalName,
+      image: details?.image,
+      custom: details?.custom,
+    );
+  }
+
   final String id;
   final String? image;
   final bool? invisible;