Index: pkg/json_rpc_2/lib/src/server.dart |
diff --git a/pkg/json_rpc_2/lib/src/server.dart b/pkg/json_rpc_2/lib/src/server.dart |
new file mode 100644 |
index 0000000000000000000000000000000000000000..d05c54f9ee85a82ae89d3c79174820727787987c |
--- /dev/null |
+++ b/pkg/json_rpc_2/lib/src/server.dart |
@@ -0,0 +1,220 @@ |
+// 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(); |
+ } |
+} |