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

pkg/json_rpc_2/README.md

Index: pkg/json_rpc_2/README.md
diff --git a/pkg/json_rpc_2/README.md b/pkg/json_rpc_2/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..3d09d0f394a5878d9f914345cb0f8862a69750ea
--- /dev/null
+++ b/pkg/json_rpc_2/README.md
@@ -0,0 +1,98 @@
+A library that implements the [JSON-RPC 2.0 spec][spec].
+
+[spec]: http://www.jsonrpc.org/specification
+
+## Server
+
+A JSON-RPC 2.0 server exposes a set of methods that can be called by clients.
+These methods can be registered using `Server.registerMethod`:
+
+```dart
+import "package:json_rpc_2/json_rpc_2.dart" as json_rpc;
+
+var server = new json_rpc.Server();
+
+// Any string may be used as a method name. JSON-RPC 2.0 methods are
+// case-sensitive.
+var i = 0;
+server.registerMethod("count", () {
+  // Just return the value to be sent as a response to the client. This can be
+  // anything JSON-serializable, or a Future that completes to something
+  // JSON-serializable.
+  return i++;
+});
+
+// Methods can take parameters. They're presented as a [Parameters] object which
+// makes it easy to validate that the expected parameters exist.
+server.registerMethod("echo", (params) {
+  // If the request doesn't have a "message" parameter, this will automatically
+  // send a response notifying the client that the request was invalid.
+  return params.getNamed("message");
+});
+
+// [Parameters] has methods for verifying argument types.
+server.registerMethod("subtract", (params) {
+  // If "minuend" or "subtrahend" aren't numbers, this will reject the request.
+  return params.getNum("minuend") - params.getNum("subtrahend");
+});
+
+// [Parameters] also supports optional arguments.
+server.registerMethod("sort", (params) {
+  var list = params.getList("list");
+  list.sort();
+  if (params.getBool("descending", orElse: () => false)) {
+    return params.list.reversed;
+  } else {
+    return params.list;
+  }
+});
+
+// A method can send an error response by throwing a `json_rpc.RpcException`.
+// Any positive number may be used as an application-defined error code.
+const DIVIDE_BY_ZERO = 1;
+server.registerMethod("divide", (params) {
+  var divisor = params.getNum("divisor");
+  if (divisor == 0) {
+    throw new json_rpc.RpcException(DIVIDE_BY_ZERO, "Cannot divide by zero.");
+  }
+
+  return params.getNum("dividend") / divisor;
+});
+```
+
+Once you've registered your methods, you can handle requests with
+`Server.parseRequest`:

[Bob Nystrom, 2014/03/20 18:25:58]

How about "handleRequest" since this is the common case?

[nweiz, 2014/03/20 22:55:41]

I like [parseRequest] -- it's shorter and conveys the difference between
[handleRequest] and [parseRequest] well. I'm also not sure which is going to be
the more common case. I put the web socket example first because isolates are
more of a pain to set up, but it's possible that isolate communication will be
more widely-used.

+
+```dart
+import 'dart:io';
+
+WebSocket.connect('ws://localhost:4321').then((socket) {
+  socket.listen((message) {
+    server.parseRequest(message).then((response) {
+      if (response != null) socket.add(response);
+    });
+  });
+});
+```
+
+If you're communicating with objects that haven't been serialized to a string,
+you can also call `Server.handleRequest` directly:

[Bob Nystrom, 2014/03/20 18:25:58]

And then maybe make this "handleMessage" or "handleParsedRequest"?

[nweiz, 2014/03/20 22:55:41]

See above.

+
+```dart
+import 'dart:isolate';
+
+var receive = new ReceivePort();
+Isolate.spawnUri('path/to/client.dart', [], receive.sendPort).then((_) {
+  receive.listen((message) {
+    server.handleRequest(message['request']).then((response) {
+      if (response != null) message['respond'].send(response);
+    });
+  });
+})
+```
+
+## Client
+
+Currently this package does not contain an implementation of a JSON-RPC 2.0
+client.
+