Feature/bump (#9)

* Squashed commit of the following:

commit 42abfb5
Author: Plague Fox <[email protected]>
Date:   Sat Feb 24 02:16:35 2024 +0400

    Update lints

* Add first message after connection/reconnection

* Add interceptors

* Fix after connect

* Test interceptors

* 1.0.0

* Reformat

* Remove nodoc

* Add missing comments

* Add information about options to readme

Author: PlugFox

.vscode/settings.json

@@ -4,7 +4,7 @@
     "editor.suggest.snippetsPreventQuickSuggestions": false,
     "editor.suggestSelection": "first",
     "editor.tabCompletion": "onlySnippets",
-    "editor.wordBasedSuggestions": false,
+    "editor.wordBasedSuggestions": "off",
     "editor.rulers": [80],
     "editor.defaultFormatter": "Dart-Code.dart-code",
     "editor.formatOnPaste": true,

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.0.0
+
+- Stable release
+- Add interceptors for incoming and outgoing messages
+- Add possibility to send messages right after connection
+
 ## 1.0.0-pre.6
 
 - **BREAKING CHANGE**: Change options to separate, platform-specific object

Makefile

@@ -25,7 +25,7 @@ server-down:
 # dart run coverage:test_with_coverage -fb -o coverage -- --concurrency=6 --platform chrome,vm --coverage=./coverage --reporter=expanded test/ws_test.dart
 coverage: get
 	@dart test --concurrency=6 --platform chrome,vm --coverage=coverage test/
-	@dart run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info --packages=.packages --report-on=lib
+	@dart run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info --report-on=lib
 #	@mv coverage/lcov.info coverage/lcov.base.info
 #	@lcov -r coverage/lcov.base.info -o coverage/lcov.base.info "lib/**.freezed.dart" "lib/**.g.dart"
 #	@mv coverage/lcov.base.info coverage/lcov.info

README.md

@@ -35,6 +35,41 @@ dependencies:
 - `add(Object data)`: Sends data on the WebSocket connection. The data can be either a String or a List of integers holding bytes.
 - `close([int? code = 1000, String? reason = 'NORMAL_CLOSURE'])`: Permanently stops the WebSocket connection and frees all resources. After calling this method, the WebSocket client is no longer usable.
 
+## Options
+
+The `WebSocketOptions` class provides a configurable set of options for setting up a WebSocket connection on both VM (Virtual Machine) and JS (JavaScript) platforms. This class supports a variety of settings including connection retry strategies, subprotocols, timeouts, message interceptors, and platform-specific configurations.
+
+To use `WebSocketOptions`, instantiate it directly with the desired configuration for your platform. Use the `.vm()` factory for VM platform settings and `.js()` factory for JS platform settings. The `.selector()` factory can be used to construct options depending on the current platform, allowing for flexible configuration across different environments.
+
+### Common Options
+
+Common configuration options applicable across VM and JS platforms:
+
+| Option                    | Description                                                                                                                                                                                                                                                     |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `connectionRetryInterval` | Specifies the [Backoff full jitter strategy](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) for reconnecting. Allows tweaks for the reconnect backoff algorithm (min delay, max delay). If not specified, reconnecting is disabled. |
+| `protocols`               | Specifies the subprotocols the client is willing to speak.                                                                                                                                                                                                      |
+| `timeout`                 | Specifies the maximum time to wait for the connection to be established. Defaults to 30 seconds if not specified.                                                                                                                                               |
+| `afterConnect`            | Specifies the callback function to be called after the connection is established, but before the client is allowed to send user messages.                                                                                                                       |
+| `interceptors`            | Specifies the interceptors for WebSocket messages.                                                                                                                                                                                                              |
+
+### VM Platform Options
+
+Specific to VM (Mobile, Desktop, Server, Console) platform. Not to be used on the web platform.
+
+- Includes all common options.
+- `headers`: Specifies additional HTTP headers for setting up the connection. Certain headers are controlled by the WebSocket connection process and will be ignored if passed.
+- `compression`: If provided, configures the WebSocket to negotiate with the specified `CompressionOptions`.
+- `customClient`: Allows specifying a custom `HttpClient`.
+- `userAgent`: Allows specifying a custom `UserAgent`.
+
+### JS Platform Options
+
+Specific to JS (Browser) platform. Not to be used on the VM platform.
+
+- Includes all common options.
+- `useBlobForBinary`: Specifies if `Uint8List` should be sent as `Blob` or as typed data. Defaults to sending as typed data.
+
 ## Example
 
 ![](example.png)
@@ -69,11 +104,14 @@ The `ws` package provides a cross-platform WebSocket client that supports JSON.
 - ✅ Fake client for testing
 - ✅ Custom exceptions
 - ✅ 90% test coverage
-- ❌ First message after connection/reconnection
-- ❌ Automatic ping/pong for keep-alive & connection health check
+- ✅ First message after connection/reconnection
+- ✅ Interceptors (middlewares)
+
+<!--
 - ❌ Reusing client between isolates
-- ❌ Interceptors (middlewares)
+- ❌ Automatic ping/pong for keep-alive & connection health check
 - ❌ RPC support
+-->
 
 ## More resources
 
@@ -111,3 +149,7 @@ We appreciate any form of support, whether it's a financial donation or just a s
 ## Tags
 
 web, socket, ws, wss, WebSocket, cross, platform
+
+```
+
+```

analysis_options.yaml

@@ -77,10 +77,9 @@ linter:
     close_sinks: true
     control_flow_in_finally: true
     empty_statements: true
-    iterable_contains_unrelated_type: true
+    collection_methods_unrelated_type: true
     join_return_with_assignment: true
     leading_newlines_in_multiline_strings: true
-    list_remove_unrelated_type: true
     literal_only_boolean_expressions: true
     missing_whitespace_between_adjacent_strings: true
     no_adjacent_strings_in_list: true

lib/src/client/message_stream.dart

@@ -1,11 +1,9 @@
 import 'dart:async';
 import 'dart:convert';
 
-/// {@nodoc}
 final Converter<String, Map<String, Object?>> _$jsonTextDecoder =
     const JsonDecoder().cast<String, Map<String, Object?>>();
 
-/// {@nodoc}
 final Converter<List<int>, Map<String, Object?>> _$jsonBytesDecoder =
     const Utf8Decoder().fuse<Map<String, Object?>>(
         const JsonDecoder().cast<String, Map<String, Object?>>());

lib/src/client/ws_client.dart

@@ -53,7 +53,6 @@ final class WebSocketClient implements IWebSocketClient {
       WebSocketConnectionManager(this);
 
   /// Current options.
-  /// {@nodoc}
   final WebSocketOptions _options;
 
   @override
@@ -124,6 +123,12 @@ final class WebSocketClient implements IWebSocketClient {
           stackTrace,
         );
       }
+      try {
+        // Send first messages after connection is established:
+        await _options.afterConnect?.call(_client);
+      } on Object {
+        _client.disconnect(1006, 'AFTER_CONNECT_ERROR');
+      }
     });
   }
 

lib/src/client/ws_client_base.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: avoid_types_on_closure_parameters, omit_local_variable_types
+
 import 'dart:async';
 import 'dart:collection';
 
@@ -7,31 +9,41 @@ import 'package:ws/src/client/state.dart';
 import 'package:ws/src/client/state_stream.dart';
 import 'package:ws/src/client/web_socket_ready_state.dart';
 import 'package:ws/src/client/ws_client_interface.dart';
+import 'package:ws/src/client/ws_interceptor.dart';
 import 'package:ws/src/util/constants.dart';
 import 'package:ws/src/util/logger.dart';
 
-/// {@nodoc}
 @internal
 abstract base class WebSocketClientBase implements IWebSocketClient {
-  /// {@nodoc}
-  WebSocketClientBase({Iterable<String>? protocols})
-      : _dataController = StreamController<Object>.broadcast(),
+  WebSocketClientBase({
+    Iterable<String>? protocols,
+    Iterable<WSInterceptor>? interceptors,
+  })  : _dataController = StreamController<Object>.broadcast(),
         _stateController = StreamController<WebSocketClientState>.broadcast(),
         _state = WebSocketClientState.initial(),
         protocols = protocols != null
-            ? UnmodifiableListView(protocols.toList(growable: false))
-            : null;
+            ? UnmodifiableListView<String>(protocols.toList(growable: false))
+            : null {
+    final chain =
+        interceptors?.toList(growable: false) ?? const <WSInterceptor>[];
+    _buildSendChain(chain);
+    _buildReceiveChain(chain);
+  }
 
   @override
   bool get isClosed => _isClosed; // coverage:ignore-line
   bool _isClosed = false;
 
-  /// {@nodoc}
   @protected
   final List<String>? protocols;
 
+  /// On message sent callback interceptors chain.
+  late final void Function(Object data) _onSentChain;
+
+  /// On message received callback interceptors chain.
+  late final void Function(Object data) _onReceivedDataChain;
+
   /// Output stream of data from native WebSocket client.
-  /// {@nodoc}
   @protected
   final StreamController<Object> _dataController;
 
@@ -40,15 +52,13 @@ abstract base class WebSocketClientBase implements IWebSocketClient {
       WebSocketMessagesStream(_dataController.stream);
 
   /// Current ready state of the WebSocket connection.
-  /// {@nodoc}
   abstract final WebSocketReadyState readyState;
 
   @override
   WebSocketClientState get state => _state;
   WebSocketClientState _state;
 
   /// Output stream of state changes.
-  /// {@nodoc}
   @protected
   final StreamController<WebSocketClientState> _stateController;
 
@@ -62,16 +72,14 @@ abstract base class WebSocketClientBase implements IWebSocketClient {
     setState((_) => WebSocketClientState.connecting(url: url));
   }
 
+  @protected
+  @visibleForOverriding
+  void push(Object data);
+
   @override
-  @mustCallSuper
-  FutureOr<void> add(Object data) async {
-    // coverage:ignore-start
-    if ($debugWS) {
-      var text = data.toString();
-      text = text.length > 100 ? '${text.substring(0, 97)}...' : text;
-      fine('> $text');
-    }
-    // coverage:ignore-end
+  @nonVirtual
+  FutureOr<void> add(Object data) {
+    _onSentChain(data);
   }
 
   @override
@@ -93,12 +101,10 @@ abstract base class WebSocketClientBase implements IWebSocketClient {
     try {
       await disconnect(code, reason);
     } on Object {/* ignore */} // coverage:ignore-line
-
     _dataController.close().ignore();
     _stateController.close().ignore();
   }
 
-  /// {@nodoc}
   @protected
   void setState(
       WebSocketClientState Function(WebSocketClientState state) change) {
@@ -108,42 +114,18 @@ abstract base class WebSocketClientBase implements IWebSocketClient {
     info('WebSocketClient state changed to $newState');
   }
 
-  /// {@nodoc}
   @protected
   void onConnected(String url) {
     setState((_) => WebSocketClientState.open(url: url));
   }
 
-  /// {@nodoc}
-  @protected
-  void onSent(Object data) {
-    // coverage:ignore-start
-    if ($debugWS) {
-      var text = data.toString();
-      text = text.length > 100 ? '${text.substring(0, 97)}...' : text;
-      fine('Sent: $text');
-    }
-    // coverage:ignore-end
-  }
-
   /// On data received callback.
-  /// {@nodoc}
   @protected
   void onReceivedData(Object? data) {
-    // coverage:ignore-start
-    if (data == null || _dataController.isClosed) return;
-    // coverage:ignore-end
-    _dataController.add(data);
-    // coverage:ignore-start
-    if ($debugWS) {
-      var text = data.toString();
-      text = text.length > 100 ? '${text.substring(0, 97)}...' : text;
-      fine('< $text');
-    }
-    // coverage:ignore-end
+    if (data == null) return;
+    _onReceivedDataChain(data);
   }
 
-  /// {@nodoc}
   @protected
   void onDisconnected(int? code, String? reason) {
     setState((_) => WebSocketClientState.closed(
@@ -153,7 +135,47 @@ abstract base class WebSocketClientBase implements IWebSocketClient {
   }
 
   /// Error callback.
-  /// {@nodoc}
   @protected
   void onError(Object error, StackTrace stackTrace) {}
+
+  /// Build push interceptors
+  void _buildSendChain(List<WSInterceptor> interceptors) {
+    void Function(Object) fn = (Object data) {
+      push(data);
+      // coverage:ignore-start
+      if ($debugWS) {
+        var text = data.toString();
+        text = text.length > 100 ? '${text.substring(0, 97)}...' : text;
+        fine('> $text');
+      }
+      // coverage:ignore-end
+    };
+    for (var i = interceptors.length - 1; i >= 0; i--) {
+      final interceptor = interceptors[i];
+      final next = fn;
+      fn = (data) => interceptor.onSend(data, next);
+    }
+    _onSentChain = fn;
+  }
+
+  /// Build receive interceptors
+  void _buildReceiveChain(List<WSInterceptor> interceptors) {
+    void Function(Object) fn = (Object data) {
+      if (_dataController.isClosed) return;
+      _dataController.add(data);
+      // coverage:ignore-start
+      if ($debugWS) {
+        var text = data.toString();
+        text = text.length > 100 ? '${text.substring(0, 97)}...' : text;
+        fine('< $text');
+      }
+      // coverage:ignore-end
+    };
+    for (var i = 0; i < interceptors.length; i++) {
+      final interceptor = interceptors[i];
+      final next = fn;
+      fn = (data) => interceptor.onMessage(data, next);
+    }
+    _onReceivedDataChain = fn;
+  }
 }

lib/src/client/ws_client_fake.dart

@@ -7,8 +7,8 @@ import 'package:ws/src/client/state_stream.dart';
 import 'package:ws/src/client/ws_client_interface.dart';
 import 'package:ws/src/client/ws_options.dart';
 
+/// Platform related callback to create a WebSocket client.
 // coverage:ignore-start
-/// {@nodoc}
 @internal
 IWebSocketClient $platformWebSocketClient(WebSocketOptions? options) =>
     WebSocketClientFake(protocols: options?.protocols);
@@ -29,7 +29,7 @@ final class WebSocketClientFake implements IWebSocketClient {
         _isClosed = false,
         _state = WebSocketClientState.initial();
 
-  /// {@nodoc}
+  /// List of protocols to be used in the WebSocket connection.
   @visibleForTesting
   final List<String>? protocols;