OLD | NEW |
(Empty) | |
| 1 A library that implements the [JSON-RPC 2.0 spec][spec]. |
| 2 |
| 3 [spec]: http://www.jsonrpc.org/specification |
| 4 |
| 5 ## Server |
| 6 |
| 7 A JSON-RPC 2.0 server exposes a set of methods that can be called by clients. |
| 8 These methods can be registered using `Server.registerMethod`: |
| 9 |
| 10 ```dart |
| 11 import "package:json_rpc_2/json_rpc_2.dart" as json_rpc; |
| 12 |
| 13 var server = new json_rpc.Server(); |
| 14 |
| 15 // Any string may be used as a method name. JSON-RPC 2.0 methods are |
| 16 // case-sensitive. |
| 17 var i = 0; |
| 18 server.registerMethod("count", () { |
| 19 // Just return the value to be sent as a response to the client. This can be |
| 20 // anything JSON-serializable, or a Future that completes to something |
| 21 // JSON-serializable. |
| 22 return i++; |
| 23 }); |
| 24 |
| 25 // Methods can take parameters. They're presented as a [Parameters] object which |
| 26 // makes it easy to validate that the expected parameters exist. |
| 27 server.registerMethod("echo", (params) { |
| 28 // If the request doesn't have a "message" parameter, this will automatically |
| 29 // send a response notifying the client that the request was invalid. |
| 30 return params.getNamed("message"); |
| 31 }); |
| 32 |
| 33 // [Parameters] has methods for verifying argument types. |
| 34 server.registerMethod("subtract", (params) { |
| 35 // If "minuend" or "subtrahend" aren't numbers, this will reject the request. |
| 36 return params.getNum("minuend") - params.getNum("subtrahend"); |
| 37 }); |
| 38 |
| 39 // [Parameters] also supports optional arguments. |
| 40 server.registerMethod("sort", (params) { |
| 41 var list = params.getList("list"); |
| 42 list.sort(); |
| 43 if (params.getBool("descending", orElse: () => false)) { |
| 44 return params.list.reversed; |
| 45 } else { |
| 46 return params.list; |
| 47 } |
| 48 }); |
| 49 |
| 50 // A method can send an error response by throwing a `json_rpc.RpcException`. |
| 51 // Any positive number may be used as an application-defined error code. |
| 52 const DIVIDE_BY_ZERO = 1; |
| 53 server.registerMethod("divide", (params) { |
| 54 var divisor = params.getNum("divisor"); |
| 55 if (divisor == 0) { |
| 56 throw new json_rpc.RpcException(DIVIDE_BY_ZERO, "Cannot divide by zero."); |
| 57 } |
| 58 |
| 59 return params.getNum("dividend") / divisor; |
| 60 }); |
| 61 ``` |
| 62 |
| 63 Once you've registered your methods, you can handle requests with |
| 64 `Server.parseRequest`: |
| 65 |
| 66 ```dart |
| 67 import 'dart:io'; |
| 68 |
| 69 WebSocket.connect('ws://localhost:4321').then((socket) { |
| 70 socket.listen((message) { |
| 71 server.parseRequest(message).then((response) { |
| 72 if (response != null) socket.add(response); |
| 73 }); |
| 74 }); |
| 75 }); |
| 76 ``` |
| 77 |
| 78 If you're communicating with objects that haven't been serialized to a string, |
| 79 you can also call `Server.handleRequest` directly: |
| 80 |
| 81 ```dart |
| 82 import 'dart:isolate'; |
| 83 |
| 84 var receive = new ReceivePort(); |
| 85 Isolate.spawnUri('path/to/client.dart', [], receive.sendPort).then((_) { |
| 86 receive.listen((message) { |
| 87 server.handleRequest(message['request']).then((response) { |
| 88 if (response != null) message['respond'].send(response); |
| 89 }); |
| 90 }); |
| 91 }) |
| 92 ``` |
| 93 |
| 94 ## Client |
| 95 |
| 96 Currently this package does not contain an implementation of a JSON-RPC 2.0 |
| 97 client. |
| 98 |
OLD | NEW |