Create a package that implements a JSON-RPC 2.0 server.

pkg/json_rpc_2/lib/src/server.dart

+// Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library json_rpc_2.server;
+
+import 'dart:async';
+import 'dart:collection';
+import 'dart:convert';
+
+import 'package:stack_trace/stack_trace.dart';
+
+import '../error_code.dart' as error_code;
+import 'exception.dart';
+import 'parameters.dart';
+import 'utils.dart';
+
+/// A JSON-RPC 2.0 server.
+///
+/// A server exposes methods that are called by requests, to which it provides
+/// responses. Methods can be registered using [registerMethod] and
+/// [registerFallback]. Requests can be handled using [handleRequest] and
+/// [parseRequest].
+///
+/// Note that since requests can arrive asynchronously and methods can run
+/// asynchronously, it's possible for multiple methods to be invoked at the same
+/// time, or even for a single method to be invoked multiple times at once.
+class Server {
+  /// The methods registered for this server.
+  final _methods = new Map<String, Function>();
+
+  /// The fallback methods for this server.
+  ///
+  /// These are tried in order until one of them doesn't throw a
+  /// [RpcException.methodNotFound] exception.
+  final _fallbacks = new Queue<Function>();
+
+  Server();
+
+  /// Registers a method named [name] on this server.
+  ///
+  /// [callback] can take either zero or one arguments. If it takes zero, any
+  /// requests for that method that include parameters will be rejected. If it
+  /// takes one, it will be passed a [Parameters] object.
+  ///
+  /// [callback] can return either a JSON-serializable object or a Future that
+  /// completes to a JSON-serializable object. Any errors in [callback] will be
+  /// reported to the client as JSON-RPC 2.0 errors.
+  void registerMethod(String name, Function callback) {
+    if (_methods.containsKey(name)) {
+      throw new ArgumentError('There\'s already a method named "$name".');
+    }
+
+    _methods[name] = callback;
+  }
+
+  /// Registers a fallback method on this server.
+  ///
+  /// A server may have any number of fallback methods. When a request comes in
+  /// that doesn't match any named methods, each fallback is tried in order. A
+  /// fallback can pass on handling a request by throwing a
+  /// [RpcException.methodNotFound] exception.
+  ///
+  /// [callback] can return either a JSON-serializable object or a Future that
+  /// completes to a JSON-serializable object. Any errors in [callback] will be
+  /// reported to the client as JSON-RPC 2.0 errors. [callback] may send custom
+  /// errors by throwing an [RpcException].
+  void registerFallback(callback(Parameters parameters)) {
+    _fallbacks.add(callback);
+  }
+
+  /// Handle a request that's already been parsed from JSON.
+  ///
+  /// [request] is expected to be a JSON-serializable object representing a
+  /// request sent by a client. This calls the appropriate method or methods for
+  /// handling that request and returns a JSON-serializable response, or `null`
+  /// if no response should be sent. [callback] may send custom
+  /// errors by throwing an [RpcException].
+  Future handleRequest(request) {
+    return syncFuture(() {
+      if (request is! List) return _handleSingleRequest(request);
+      if (request.isEmpty) {
+        return new RpcException(error_code.INVALID_REQUEST, 'A batch must '
+            'contain at least one request.').serialize(request);
+      }
+
+      return Future.wait(request.map(_handleSingleRequest)).then((results) {
+        var nonNull = results.where((result) => result != null);
+        return nonNull.isEmpty ? null : nonNull.toList();
+      });
+    });
+  }
+
+  /// Parses and handles a JSON serialized request.
+  ///
+  /// This calls the appropriate method or methods for handling that request and
+  /// returns a JSON string, or `null` if no response should be sent.
+  Future<String> parseRequest(String request) {
+    return syncFuture(() {
+      var decodedRequest;
+      try {
+        decodedRequest = JSON.decode(request);
+      } on FormatException catch (error) {
+        return new RpcException(error_code.PARSE_ERROR, 'Invalid JSON: '
+            '${error.message}').serialize(request);
+      }
+
+      return handleRequest(decodedRequest);
+    }).then((response) {
+      if (response == null) return null;
+      return JSON.encode(response);
+    });
+  }
+
+  /// Handles an individual parsed request.
+  Future _handleSingleRequest(request) {
+    return syncFuture(() {
+      _validateRequest(request);
+
+      var name = request['method'];
+      var method = _methods[name];
+      if (method == null) method = _tryFallbacks;
+
+      if (method is ZeroArgumentFunction) {
+        if (!request.containsKey('params')) return method();
+        throw new RpcException.invalidParams('No parameters are allowed for '
+            'method "$name".');
+      }
+
+      return method(new Parameters(name, request['params']));
+    }).then((result) {
+      // A request without an id is a notification, which should not be sent a
+      // response, even if one is generated on the server.
+      if (!request.containsKey('id')) return null;
+
+      return {
+        'jsonrpc': '2.0',
+        'result': result,
+        'id': request['id']
+      };
+    }).catchError((error, stackTrace) {
+      if (error is! RpcException) {
+        error = new RpcException(
+            error_code.SERVER_ERROR, getErrorMessage(error), data: {
+          'full': error.toString(),
+          'stack': new Chain.forTrace(stackTrace).toString()
+        });
+      }
+
+      if (error.code != error_code.INVALID_REQUEST &&
+          !request.containsKey('id')) {
+        return null;
+      } else {
+        return error.serialize(request);
+      }
+    });
+  }
+
+  /// Validates that [request] matches the JSON-RPC spec.
+  void _validateRequest(request) {
+    if (request is! Map) {
+      throw new RpcException(error_code.INVALID_REQUEST, 'Request must be '
+          'an Array or an Object.');
+    }
+
+    if (!request.containsKey('jsonrpc')) {
+      throw new RpcException(error_code.INVALID_REQUEST, 'Request must '
+          'contain a "jsonrpc" key.');
+    }
+
+    if (request['jsonrpc'] != '2.0') {
+      throw new RpcException(error_code.INVALID_REQUEST, 'Invalid JSON-RPC '
+          'version ${JSON.encode(request['jsonrpc'])}, expected "2.0".');
+    }
+
+    if (!request.containsKey('method')) {
+      throw new RpcException(error_code.INVALID_REQUEST, 'Request must '
+          'contain a "method" key.');
+    }
+
+    var method = request['method'];
+    if (request['method'] is! String) {
+      throw new RpcException(error_code.INVALID_REQUEST, 'Request method must '
+          'be a string, but was ${JSON.encode(method)}.');
+    }
+
+    var params = request['params'];
+    if (request.containsKey('params') && params is! List && params is! Map) {
+      throw new RpcException(error_code.INVALID_REQUEST, 'Request params must '
+          'be an Array or an Object, but was ${JSON.encode(params)}.');
+    }
+
+    var id = request['id'];
+    if (id != null && id is! String && id is! num) {
+      throw new RpcException(error_code.INVALID_REQUEST, 'Request id must be a '
+          'string, number, or null, but was ${JSON.encode(id)}.');
+    }
+  }
+
+  /// Try all the fallback methods in order.
+  Future _tryFallbacks(Parameters params) {
+    var iterator = _fallbacks.toList().iterator;
+
+    _tryNext() {
+      if (!iterator.moveNext()) {
+        return new Future.error(
+            new RpcException.methodNotFound(params.method),
+            new Chain.current());
+      }
+
+      return syncFuture(() => iterator.current(params)).catchError((error) {
+        if (error is! RpcException) throw error;
+        if (error.code != error_code.METHOD_NOT_FOUND) throw error;
+        return _tryNext();
+      });
+    }
+
+    return _tryNext();
+  }
+}