allow custom ID generators in Clients, and support String ids (#2077)

This is to support using this package to write a dart analyzer LSP client, which requires String ids.

Also closes #738

This is technically breaking because there was some code which tries to coerce string ids back into integers, but this should never have happened. Any server stringifying integer IDs is not spec compliant.

Let me know if we want to release this as non-breaking instead of breaking, I think it would be fine personally, but don't feel strongly either way.

Author: jakemac53

pkgs/json_rpc_2/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 4.0.0
+
+* Add custom ID generator option to clients, which allows for `String` ids.
+* **Breaking**: When `String` ids are present in a response, we no longer
+  automatically try to parse them as integers. This behavior was never a part
+  of the spec, and is not compatible with allowing custom ID generators.
+
 ## 3.0.3
 
 * Require Dart 3.4

pkgs/json_rpc_2/lib/src/client.dart

@@ -18,16 +18,18 @@ import 'utils.dart';
 class Client {
   final StreamChannel<dynamic> _channel;
 
-  /// The next request id.
-  var _id = 0;
+  /// A function to generate the next request id.
+  Object Function() _idGenerator;
 
   /// The current batch of requests to be sent together.
   ///
   /// Each element is a JSON RPC spec compliant message.
   List<Map<String, dynamic>>? _batch;
 
   /// The map of request ids to pending requests.
-  final _pendingRequests = <int, _Request>{};
+  ///
+  /// Keys must be of type `int` or `String`.
+  final _pendingRequests = <Object, _Request>{};
 
   final _done = Completer<void>();
 
@@ -49,9 +51,14 @@ class Client {
   ///
   /// Note that the client won't begin listening to [channel] until
   /// [Client.listen] is called.
-  Client(StreamChannel<String> channel)
+  ///
+  /// If [idGenerator] is passed, it will be called to generate an ID for each
+  /// request. Defaults to an auto-incrementing `int`. The value returned must
+  /// be either an `int` or `String`.
+  Client(StreamChannel<String> channel, {Object Function()? idGenerator})
       : this.withoutJson(
-            jsonDocument.bind(channel).transformStream(ignoreFormatExceptions));
+            jsonDocument.bind(channel).transformStream(ignoreFormatExceptions),
+            idGenerator: idGenerator);
 
   /// Creates a [Client] that communicates using decoded messages over
   /// [_channel].
@@ -61,7 +68,12 @@ class Client {
   ///
   /// Note that the client won't begin listening to [_channel] until
   /// [Client.listen] is called.
-  Client.withoutJson(this._channel) {
+  ///
+  /// If [_idGenerator] is passed, it will be called to generate an ID for each
+  /// request. Defaults to an auto-incrementing `int`. The value returned must
+  /// be either an `int` or `String`.
+  Client.withoutJson(this._channel, {Object Function()? idGenerator})
+      : _idGenerator = idGenerator ?? _createIncrementingIdGenerator() {
     done.whenComplete(() {
       for (var request in _pendingRequests.values) {
         request.completer.completeError(StateError(
@@ -115,7 +127,7 @@ class Client {
   /// Throws a [StateError] if the client is closed while the request is in
   /// flight, or if the client is closed when this method is called.
   Future<Object?> sendRequest(String method, [Object? parameters]) {
-    var id = _id++;
+    var id = _idGenerator();
     _send(method, parameters, id);
 
     var completer = Completer<Object?>.sync();
@@ -142,7 +154,7 @@ class Client {
   ///
   /// Sends a request to invoke [method] with [parameters]. If [id] is given,
   /// the request uses that id.
-  void _send(String method, Object? parameters, [int? id]) {
+  void _send(String method, Object? parameters, [Object? id]) {
     if (parameters is Iterable) parameters = parameters.toList();
     if (parameters is! Map && parameters is! List && parameters != null) {
       throw ArgumentError('Only maps and lists may be used as JSON-RPC '
@@ -201,7 +213,6 @@ class Client {
     if (!_isResponseValid(response_)) return;
     final response = response_ as Map;
     var id = response['id'];
-    id = (id is String) ? int.parse(id) : id;
     var request = _pendingRequests.remove(id)!;
     if (response.containsKey('result')) {
       request.completer.complete(response['result']);
@@ -218,7 +229,6 @@ class Client {
     if (response is! Map) return false;
     if (response['jsonrpc'] != '2.0') return false;
     var id = response['id'];
-    id = (id is String) ? int.parse(id) : id;
     if (!_pendingRequests.containsKey(id)) return false;
     if (response.containsKey('result')) return true;
 
@@ -244,3 +254,11 @@ class _Request {
 
   _Request(this.method, this.completer, this.chain);
 }
+
+/// The default ID generator, uses an auto incrementing integer.
+///
+/// Each call returns a new function which starts back a `0`.
+int Function() _createIncrementingIdGenerator() {
+  var nextId = 0;
+  return () => nextId++;
+}

pkgs/json_rpc_2/lib/src/peer.dart

@@ -59,12 +59,20 @@ class Peer implements Client, Server {
   /// some requests which are not conformant with the JSON-RPC 2.0
   /// specification. In particular, requests missing the `jsonrpc` parameter
   /// will be accepted.
-  Peer(StreamChannel<String> channel,
-      {ErrorCallback? onUnhandledError, bool strictProtocolChecks = true})
-      : this.withoutJson(
+  ///
+  /// If [idGenerator] is passed, it will be called to generate an ID for each
+  /// request. Defaults to an auto-incrementing `int`.  The value returned must
+  /// be either an `int` or `String`.
+  Peer(
+    StreamChannel<String> channel, {
+    ErrorCallback? onUnhandledError,
+    bool strictProtocolChecks = true,
+    Object Function()? idGenerator,
+  }) : this.withoutJson(
             jsonDocument.bind(channel).transform(respondToFormatExceptions),
             onUnhandledError: onUnhandledError,
-            strictProtocolChecks: strictProtocolChecks);
+            strictProtocolChecks: strictProtocolChecks,
+            idGenerator: idGenerator);
 
   /// Creates a [Peer] that communicates using decoded messages over [_channel].
   ///
@@ -81,14 +89,24 @@ class Peer implements Client, Server {
   /// some requests which are not conformant with the JSON-RPC 2.0
   /// specification. In particular, requests missing the `jsonrpc` parameter
   /// will be accepted.
+  ///
+  /// If [idGenerator] is passed, it will be called to generate an ID for each
+  /// request. Defaults to an auto-incrementing `int`. The value returned must
+  /// be either an `int` or `String`.
   Peer.withoutJson(this._channel,
-      {ErrorCallback? onUnhandledError, bool strictProtocolChecks = true}) {
+      {ErrorCallback? onUnhandledError,
+      bool strictProtocolChecks = true,
+      Object Function()? idGenerator}) {
     _server = Server.withoutJson(
         StreamChannel(_serverIncomingForwarder.stream, _channel.sink),
         onUnhandledError: onUnhandledError,
         strictProtocolChecks: strictProtocolChecks);
     _client = Client.withoutJson(
-        StreamChannel(_clientIncomingForwarder.stream, _channel.sink));
+        StreamChannel(
+          _clientIncomingForwarder.stream,
+          _channel.sink,
+        ),
+        idGenerator: idGenerator);
   }
 
   // Client methods.

pkgs/json_rpc_2/pubspec.yaml

@@ -1,5 +1,5 @@
 name: json_rpc_2
-version: 3.0.3
+version: 4.0.0
 description: >-
   Utilities to write a client or server using the JSON-RPC 2.0 spec.
 repository: https://github.com/dart-lang/tools/tree/main/pkgs/json_rpc_2