Options (#4)

- **BREAKING CHANGE**: Change options to separate, platform-specific object
- You can now pass a headers and other options to the IO websocket client
- Backoff full jitter strategy for reconnection attempts
- Add more metrics
- Public Fake WebSocket client for testing

Author: PlugFox

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.0.0-pre.1
+
+- **BREAKING CHANGE**: Change options to separate, platform-specific object
+- You can now pass a headers and other options to the IO websocket client
+- Backoff full jitter strategy for reconnection attempts
+- Add more metrics
+- Public Fake WebSocket client for testing
+
 ## 0.1.2
 
 - Update README.md

example/ws_example.dart

@@ -10,7 +10,7 @@ void main([List<String>? args]) {
       defaultValue: 'wss://echo.plugfox.dev:443/connect');
 
   // Setup a WebSocket client with auto reconnect
-  final client = WebSocketClient(reconnectTimeout: const Duration(seconds: 5))
+  final client = WebSocketClient()
     // Observing the incoming messages from the server
     ..stream.listen((message) => print('< $message'))
     // Observing the state changes (connecting, open, disconnecting, closed)

lib/interface.dart

@@ -1,8 +1,10 @@
-library dev.plugfox.ws.interface;
+library interface;
 
 export 'package:ws/src/client/message_stream.dart';
 export 'package:ws/src/client/metrics.dart';
 export 'package:ws/src/client/state.dart';
 export 'package:ws/src/client/status_codes.dart';
 export 'package:ws/src/client/web_socket_ready_state.dart';
+export 'package:ws/src/client/ws_client_fake.dart' show WebSocketClientFake;
 export 'package:ws/src/client/ws_client_interface.dart';
+export 'package:ws/src/client/ws_options.dart';

lib/src/client/message_stream.dart

@@ -11,6 +11,8 @@ final Converter<List<int>, Map<String, Object?>> _$jsonBytesDecoder =
         const JsonDecoder().cast<String, Map<String, Object?>>());
 
 /// Stream of message events handled by this WebSocket.
+/// {@category Client}
+/// {@category Entity}
 final class WebSocketMessagesStream
     extends StreamView< /* String || List<int> */ Object> {
   /// Stream of message events handled by this WebSocket.

lib/src/client/metrics.dart

@@ -10,7 +10,7 @@ final class WebSocketMetrics {
   const WebSocketMetrics({
     required this.timestamp,
     required this.readyState,
-    required this.reconnectTimeout,
+    required this.nextReconnectionAttempt,
     required this.transferredSize,
     required this.receivedSize,
     required this.transferredCount,
@@ -19,8 +19,9 @@ final class WebSocketMetrics {
     required this.lastSuccessfulConnectionTime,
     required this.disconnects,
     required this.lastDisconnectTime,
-    required this.expectedReconnectTime,
     required this.lastDisconnect,
+    required this.isReconnectionActive,
+    required this.currentReconnectAttempts,
     required this.lastUrl,
   });
 
@@ -51,11 +52,6 @@ final class WebSocketMetrics {
         WebSocketReadyState.fromCode,
         () => WebSocketReadyState.closed,
       ),
-      reconnectTimeout: extract<int, Duration>(
-        'reconnectTimeout',
-        (v) => Duration(milliseconds: v),
-        () => Duration.zero,
-      ),
       transferredSize: extract<String, BigInt>(
         'transferredSize',
         BigInt.parse,
@@ -120,8 +116,18 @@ final class WebSocketMetrics {
         (v) => v,
         () => null,
       ),
-      expectedReconnectTime: extract<int, DateTime?>(
-        'expectedReconnectTime',
+      isReconnectionActive: extract<bool, bool>(
+        'isReconnectionActive',
+        (v) => v,
+        () => false,
+      ),
+      currentReconnectAttempts: extract<int, int>(
+        'currentReconnectAttempts',
+        (v) => v,
+        () => 0,
+      ),
+      nextReconnectionAttempt: extract<int, DateTime?>(
+        'nextReconnectionAttempt',
         DateTime.fromMillisecondsSinceEpoch,
         () => null,
       ),
@@ -132,7 +138,6 @@ final class WebSocketMetrics {
   Map<String, Object?> toJson() => <String, Object?>{
         'timestamp': timestamp.millisecondsSinceEpoch,
         'readyState': readyState.code,
-        'reconnectTimeout': reconnectTimeout.inMilliseconds,
         'transferredSize': transferredSize.toString(),
         'receivedSize': receivedSize.toString(),
         'transferredCount': transferredCount.toString(),
@@ -143,9 +148,12 @@ final class WebSocketMetrics {
             lastSuccessfulConnectionTime?.millisecondsSinceEpoch,
         'disconnects': disconnects,
         'lastDisconnectTime': lastDisconnectTime?.millisecondsSinceEpoch,
-        'expectedReconnectTime': expectedReconnectTime?.millisecondsSinceEpoch,
+        'nextReconnectionAttempt':
+            nextReconnectionAttempt?.millisecondsSinceEpoch,
         'lastDisconnectCode': lastDisconnect.code,
         'lastDisconnectReason': lastDisconnect.reason,
+        'isReconnectionActive': isReconnectionActive,
+        'currentReconnectAttempts': currentReconnectAttempts,
         'lastUrl': lastUrl,
       };
 
@@ -155,9 +163,6 @@ final class WebSocketMetrics {
   /// The current state of the connection.
   final WebSocketReadyState readyState;
 
-  /// Timeout between reconnection attempts.
-  final Duration reconnectTimeout;
-
   /// The total number of bytes sent.
   final BigInt transferredSize;
 
@@ -183,18 +188,23 @@ final class WebSocketMetrics {
   final DateTime? lastDisconnectTime;
 
   /// The time of the next expected reconnect.
-  final DateTime? expectedReconnectTime;
+  final DateTime? nextReconnectionAttempt;
 
   /// The last disconnect reason.
   final ({int? code, String? reason}) lastDisconnect;
 
+  /// Is the client currently planning to reconnect?
+  final bool isReconnectionActive;
+
+  /// The current number of reconnection attempts.
+  final int currentReconnectAttempts;
+
   /// The last URL used to connect.
   final String? lastUrl;
 
   @override
   int get hashCode => Object.hashAll([
         readyState,
-        reconnectTimeout,
         transferredSize,
         receivedSize,
         transferredCount,
@@ -203,8 +213,10 @@ final class WebSocketMetrics {
         lastSuccessfulConnectionTime,
         disconnects,
         lastDisconnectTime,
-        expectedReconnectTime,
+        nextReconnectionAttempt,
         lastDisconnect,
+        isReconnectionActive,
+        currentReconnectAttempts,
         lastUrl,
       ]);
 
@@ -219,19 +231,20 @@ final class WebSocketMetrics {
                 '${ago ? 'ago' : 'from now'}'
             : 'never';
     return '- readyState: ${readyState.name}\n'
-        '- reconnectTimeout: ${reconnectTimeout.inSeconds} seconds\n'
         '- transferredSize: $transferredSize\n'
         '- receivedSize: $receivedSize\n'
         '- transferredCount: $transferredCount\n'
         '- receivedCount: $receivedCount\n'
+        '- isReconnectionActive: $isReconnectionActive\n'
+        '- currentReconnectAttempts: $currentReconnectAttempts\n'
         '- reconnects: ${reconnects.successful} / ${reconnects.total}\n'
         '- lastSuccessfulConnectionTime: '
         '${dateTimeRepresentation(lastSuccessfulConnectionTime, ago: true)}\n'
         '- disconnects: $disconnects\n'
         '- lastDisconnectTime: '
         '${dateTimeRepresentation(lastDisconnectTime, ago: true)}\n'
-        '- expectedReconnectTime: '
-        '${dateTimeRepresentation(expectedReconnectTime)}\n'
+        '- nextReconnectionAttempt: '
+        '${dateTimeRepresentation(nextReconnectionAttempt)}\n'
         '- lastDisconnect: '
         '${lastDisconnect.code ?? 'unknown'} '
         '(${lastDisconnect.reason ?? 'unknown'})\n'

lib/src/client/state.dart

@@ -2,24 +2,11 @@ import 'package:meta/meta.dart';
 import 'package:ws/src/client/status_codes.dart';
 import 'package:ws/src/client/web_socket_ready_state.dart';
 
-/// Whether the stream controller is permanently closed.
-///
-/// The controller becomes closed by calling the [close] method.
-///
-/// If the controller is closed,
-/// the "done" event might not have been delivered yet,
-/// but it has been scheduled, and it is too late to add more events.
-//bool get isClosed;
-
-/// A future which is completed when the stream controller is done.
-//Future<void> get done;
-
 /// {@template web_socket_client_state}
 /// WebSocket client state.
-///
+/// {@endtemplate}
 /// {@category Client}
 /// {@category Entity}
-/// {@endtemplate}
 @immutable
 sealed class WebSocketClientState {
   /// {@macro web_socket_client_state}

lib/src/client/status_codes.dart

@@ -24,6 +24,7 @@ import 'package:meta/meta.dart';
 /// and thus can't be registered.  Such codes can be used by prior
 /// agreements between WebSocket applications.  The interpretation of
 /// these codes is undefined by this protocol.
+/// {@category Client}
 /// {@category Entity}
 enum WebSocketStatusCodes implements Comparable<WebSocketStatusCodes> {
   /// Successful operation / regular socket shutdown.

lib/src/client/web_socket_ready_state.dart

@@ -1,5 +1,6 @@
 /// The [IWebSocketPlatformTransport.readyState] property
 /// returns the current state of the WebSocket connection.
+/// {@category Client}
 /// {@category Entity}
 enum WebSocketReadyState {
   /// Socket has been created. The connection is not yet open.

lib/src/client/websocket_exception.dart

@@ -2,6 +2,7 @@
 /// This is a custom exception class for WebSocket.
 /// Do not confuse it with a native exception WebSocketException from dart:io
 /// {@endtemplate}
+/// {@category Client}
 /// {@category Entity}
 sealed class WSException implements Exception {
   /// {@macro websocket_exception}
@@ -17,6 +18,7 @@ sealed class WSException implements Exception {
 /// {@template not_connected_exception}
 /// Exception thrown when a WebSocket is not connected.
 /// {@endtemplate}
+/// {@category Client}
 /// {@category Entity}
 final class WSNotConnected extends WSException {
   /// {@macro not_connected_exception}
@@ -26,6 +28,7 @@ final class WSNotConnected extends WSException {
 /// {@template unknown_exception}
 /// Unknown WebSocket exception.
 /// {@endtemplate}
+/// {@category Client}
 /// {@category Entity}
 final class WSUnknownException extends WSException {
   /// {@macro unknown_exception}
@@ -36,6 +39,7 @@ final class WSUnknownException extends WSException {
 /// {@template socket_exception}
 /// Exception thrown when a socket operation fails.
 /// {@endtemplate}
+/// {@category Client}
 /// {@category Entity}
 final class WSSocketException extends WSException {
   /// {@macro socket_exception}
@@ -45,6 +49,7 @@ final class WSSocketException extends WSException {
 /// {@template http_exception}
 /// Exception thrown when a socket operation fails.
 /// {@endtemplate}
+/// {@category Client}
 /// {@category Entity}
 final class WSHttpException extends WSException {
   /// {@macro http_exception}
@@ -54,6 +59,7 @@ final class WSHttpException extends WSException {
 /// {@template unsupported_exception}
 /// The operation was not allowed by the object.
 /// {@endtemplate}
+/// {@category Client}
 /// {@category Entity}
 final class WSUnsupportedException extends WSException {
   /// {@macro unsupported_exception}
@@ -63,6 +69,7 @@ final class WSUnsupportedException extends WSException {
 /// {@template client_closed}
 /// The operation was not allowed by the object.
 /// {@endtemplate}
+/// {@category Client}
 /// {@category Entity}
 final class WSClientClosed extends WSException implements StateError {
   /// {@macro client_closed}

lib/src/client/ws_client.dart

@@ -1,15 +1,19 @@
 import 'dart:async';
 
+import 'package:ws/src/client/message_stream.dart';
+import 'package:ws/src/client/metrics.dart';
+import 'package:ws/src/client/state.dart';
+import 'package:ws/src/client/websocket_exception.dart';
 import 'package:ws/src/client/ws_client_fake.dart'
     // ignore: uri_does_not_exist
     if (dart.library.html) 'package:ws/src/client/ws_client_js.dart'
     // ignore: uri_does_not_exist
-    if (dart.library.io) 'package:ws/src/client/ws_client_io.dart';
+    if (dart.library.io) 'package:ws/src/client/ws_client_vm.dart';
 import 'package:ws/src/client/ws_client_interface.dart';
+import 'package:ws/src/client/ws_options.dart';
 import 'package:ws/src/manager/connection_manager.dart';
 import 'package:ws/src/manager/metrics_manager.dart';
 import 'package:ws/src/util/event_queue.dart';
-import 'package:ws/ws.dart';
 
 /// {@template ws_client}
 /// WebSocket client.
@@ -19,11 +23,9 @@ import 'package:ws/ws.dart';
 /// {@category Client}
 final class WebSocketClient implements IWebSocketClient {
   /// {@macro ws_client}
-  WebSocketClient(
-      {Duration reconnectTimeout = const Duration(seconds: 5),
-      Iterable<String>? protocols})
-      : reconnectTimeout = reconnectTimeout.abs(),
-        _client = $platformWebSocketClient(reconnectTimeout.abs(), protocols) {
+  WebSocketClient([WebSocketOptions? options])
+      : _client = $platformWebSocketClient(options),
+        _options = options {
     WebSocketMetricsManager.instance.startObserving(this);
   }
 
@@ -32,32 +34,30 @@ final class WebSocketClient implements IWebSocketClient {
   /// with reconnecting and concurrency protection.
   /// {@macro ws_client}
   WebSocketClient.fromClient(IWebSocketClient client,
-      {Duration reconnectTimeout = const Duration(seconds: 5)})
-      : reconnectTimeout = reconnectTimeout.abs(),
-        _client = client {
+      [WebSocketOptions? options])
+      : _client = client,
+        _options = options {
     WebSocketMetricsManager.instance.startObserving(this);
   }
 
   /// {@macro ws_client}
-  factory WebSocketClient.connect(String url,
-          {Duration reconnectTimeout = const Duration(seconds: 5),
-          Iterable<String>? protocols}) =>
-      WebSocketClient(reconnectTimeout: reconnectTimeout, protocols: protocols)
-        ..connect(url).ignore();
+  factory WebSocketClient.connect(String url, [WebSocketOptions? options]) =>
+      WebSocketClient(options)..connect(url).ignore();
 
   final IWebSocketClient _client;
   final WebSocketEventQueue _eventQueue = WebSocketEventQueue();
 
+  /// Current options.
+  /// {@nodoc}
+  final WebSocketOptions? _options;
+
   @override
   bool get isClosed => _isClosed;
   bool _isClosed = false;
 
-  @override
-  final Duration reconnectTimeout;
-
   /// Get the metrics for this client.
   WebSocketMetrics get metrics =>
-      WebSocketMetricsManager.instance.buildMetric(this);
+      WebSocketMetricsManager.instance.buildMetricFor(this);
 
   @override
   WebSocketMessagesStream get stream => _client.stream;
@@ -79,7 +79,11 @@ final class WebSocketClient implements IWebSocketClient {
   Future<void> connect(String url) {
     if (_isClosed) return Future<void>.error(const WSClientClosed());
     return _eventQueue.push('connect', () {
-      WebSocketConnectionManager.instance.startMonitoringConnection(this, url);
+      WebSocketConnectionManager.instance.startMonitoringConnection(
+        this,
+        url,
+        _options?.connectionRetryInterval,
+      );
       return _client.connect(url);
     });
   }

lib/src/client/ws_client_base.dart

@@ -10,9 +10,7 @@ import 'package:ws/src/util/logger.dart';
 @internal
 abstract base class WebSocketClientBase implements IWebSocketClient {
   /// {@nodoc}
-  WebSocketClientBase(
-      {this.reconnectTimeout = const Duration(seconds: 5),
-      Iterable<String>? protocols})
+  WebSocketClientBase({Iterable<String>? protocols})
       : _dataController = StreamController<Object>.broadcast(),
         _stateController = StreamController<WebSocketClientState>.broadcast(),
         _state = WebSocketClientState.initial(),
@@ -28,9 +26,6 @@ abstract base class WebSocketClientBase implements IWebSocketClient {
   @protected
   final List<String>? protocols;
 
-  @override
-  final Duration reconnectTimeout;
-
   /// Output stream of data from native WebSocket client.
   /// {@nodoc}
   @protected