Implement JSON-RPC adapter to Cap'n Proto interfaces.

This implements JSON-RPC 2.0: https://www.jsonrpc.org/specification

c++/src/capnp/compat/json-rpc-test.c++

+// Copyright (c) 2018 Kenton Varda and contributors
+// Licensed under the MIT License:
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+#include "json-rpc.h"
+#include <kj/test.h>
+#include <capnp/test-util.h>
+
+namespace capnp {
+namespace _ {  // private
+namespace {
+
+KJ_TEST("json-rpc basics") {
+  auto io = kj::setupAsyncIo();
+  auto pipe = kj::newTwoWayPipe();
+
+  JsonRpc::ContentLengthTransport clientTransport(*pipe.ends[0]);
+  JsonRpc::ContentLengthTransport serverTransport(*pipe.ends[1]);
+
+  int callCount = 0;
+
+  JsonRpc client(clientTransport);
+  JsonRpc server(serverTransport, toDynamic(kj::heap<TestInterfaceImpl>(callCount)));
+
+  auto cap = client.getPeer<test::TestInterface>();
+  auto req = cap.fooRequest();
+  req.setI(123);
+  req.setJ(true);
+  auto resp = req.send().wait(io.waitScope);
+  KJ_EXPECT(resp.getX() == "foo");
+
+  KJ_EXPECT(callCount == 1);
+}
+
+KJ_TEST("json-rpc error") {
+  auto io = kj::setupAsyncIo();
+  auto pipe = kj::newTwoWayPipe();
+
+  JsonRpc::ContentLengthTransport clientTransport(*pipe.ends[0]);
+  JsonRpc::ContentLengthTransport serverTransport(*pipe.ends[1]);
+
+  int callCount = 0;
+
+  JsonRpc client(clientTransport);
+  JsonRpc server(serverTransport, toDynamic(kj::heap<TestInterfaceImpl>(callCount)));
+
+  auto cap = client.getPeer<test::TestInterface>();
+  KJ_EXPECT_THROW_MESSAGE("Method not implemented", cap.barRequest().send().wait(io.waitScope));
+}
+
+KJ_TEST("json-rpc multiple calls") {
+  auto io = kj::setupAsyncIo();
+  auto pipe = kj::newTwoWayPipe();
+
+  JsonRpc::ContentLengthTransport clientTransport(*pipe.ends[0]);
+  JsonRpc::ContentLengthTransport serverTransport(*pipe.ends[1]);
+
+  int callCount = 0;
+
+  JsonRpc client(clientTransport);
+  JsonRpc server(serverTransport, toDynamic(kj::heap<TestInterfaceImpl>(callCount)));
+
+  auto cap = client.getPeer<test::TestInterface>();
+  auto req1 = cap.fooRequest();
+  req1.setI(123);
+  req1.setJ(true);
+  auto promise1 = req1.send();
+
+  auto req2 = cap.bazRequest();
+  initTestMessage(req2.initS());
+  auto promise2 = req2.send();
+
+  auto resp1 = promise1.wait(io.waitScope);
+  KJ_EXPECT(resp1.getX() == "foo");
+
+  auto resp2 = promise2.wait(io.waitScope);
+
+  KJ_EXPECT(callCount == 2);
+}
+
+}  // namespace
+}  // namespace _ (private)
+}  // namespace capnp

c++/src/capnp/compat/json-rpc.capnp

+@0xd04299800d6725ba;
+
+$import "/capnp/c++.capnp".namespace("capnp::json");
+
+using Json = import "json.capnp";
+
+struct RpcMessage {
+  jsonrpc @0 :Text;
+  # Must always be "2.0".
+
+  id @1 :Json.Value;
+  # Correlates a request to a response. Technically must be a string or number. Our implementation
+  # will always use a number for calls it initiates, and will reflect IDs of any type for calls
+  # it receives.
+  #
+  # May be omitted when caller doesn't care about the response. The implementation will omit `id`
+  # and return immediately when calling methods with the annotation `@notification` (defined in
+  # `json.capnp`). The `@notification` annotation only matters for outgoing calls; for incoming
+  # calls, it's the client's decision whether it wants to receive the response.
+
+  method @2 :Text;
+  # Method name. Only expected when `params` is sent.
+
+  union {
+    none @3 :Void $Json.name("!missing params, result, or error");
+    # Dummy default value of union, to detect when none of the fields below were received.
+
+    params @4 :Json.Value;
+    # Initiates a call.
+
+    result @5 :Json.Value;
+    # Completes a call.
+
+    error @6 :Error;
+    # Completes a call throwing an exception.
+  }
+
+  struct Error {
+    code @0 :Int32;
+    message @1 :Text;
+    data @2 :Json.Value;
+  }
+}

c++/src/capnp/compat/json-rpc.h

+// Copyright (c) 2018 Kenton Varda and contributors
+// Licensed under the MIT License:
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+#pragma once
+
+#include "json.h"
+#include <kj/async-io.h>
+#include <capnp/capability.h>
+#include <kj/map.h>
+
+namespace kj { class HttpInputStream; }
+
+namespace capnp {
+
+class JsonRpc: private kj::TaskSet::ErrorHandler {
+  // An implementation of JSON-RPC 2.0: https://www.jsonrpc.org/specification
+  //
+  // This allows you to use Cap'n Proto interface declarations to implement JSON-RPC protocols.
+  // Of course, JSON-RPC does not support capabilities. So, the client and server each expose
+  // exactly one object to the other.
+
+public:
+  class Transport;
+  class ContentLengthTransport;
+
+  JsonRpc(Transport& transport, DynamicCapability::Client interface = {});
+  KJ_DISALLOW_COPY(JsonRpc);
+
+  DynamicCapability::Client getPeer(InterfaceSchema schema);
+
+  template <typename T>
+  typename T::Client getPeer() {
+    return getPeer(Schema::from<T>()).template castAs<T>();
+  }
+
+  kj::Promise<void> onError() { return errorPromise.addBranch(); }
+
+private:
+  JsonCodec codec;
+  Transport& transport;
+  DynamicCapability::Client interface;
+  kj::HashMap<kj::StringPtr, InterfaceSchema::Method> methodMap;
+  uint callCount = 0;
+  kj::Promise<void> writeQueue = kj::READY_NOW;
+  kj::ForkedPromise<void> errorPromise;
+  kj::Own<kj::PromiseFulfiller<void>> errorFulfiller;
+  kj::Promise<void> readTask;
+
+  struct AwaitedResponse {
+    CallContext<DynamicStruct, DynamicStruct> context;
+    kj::Own<kj::PromiseFulfiller<void>> fulfiller;
+  };
+  kj::HashMap<uint, AwaitedResponse> awaitedResponses;
+
+  kj::TaskSet tasks;
+
+  class CapabilityImpl;
+
+  kj::Promise<void> queueWrite(kj::String text);
+  void queueError(kj::Maybe<json::Value::Reader> id, int code, kj::StringPtr message);
+
+  kj::Promise<void> readLoop();
+
+  void taskFailed(kj::Exception&& exception) override;
+
+  JsonRpc(Transport& transport, DynamicCapability::Client interface,
+          kj::PromiseFulfillerPair<void> paf);
+};
+
+class JsonRpc::Transport {
+public:
+  virtual kj::Promise<void> send(kj::StringPtr text) = 0;
+  virtual kj::Promise<kj::String> receive() = 0;
+};
+
+class JsonRpc::ContentLengthTransport: public Transport {
+  // The transport used by Visual Studio Code: Each message is composed like an HTTP message
+  // without the first line. That is, a list of headers, followed by a blank line, followed by the
+  // content whose length is determined by the content-length header.
+public:
+  explicit ContentLengthTransport(kj::AsyncIoStream& stream);
+  ~ContentLengthTransport() noexcept(false);
+  KJ_DISALLOW_COPY(ContentLengthTransport);
+
+  kj::Promise<void> send(kj::StringPtr text) override;
+  kj::Promise<kj::String> receive() override;
+
+private:
+  kj::AsyncIoStream& stream;
+  kj::Own<kj::HttpInputStream> input;
+  kj::ArrayPtr<const byte> parts[2];
+};
+
+}  // namespace capnp

c++/src/capnp/compat/json.capnp

@@ -66,14 +66,14 @@ struct Value {
 #
 #     myField @0 :Text $Json.name("my_field");
 
-annotation name @0xfa5b1fd61c2e7c3d (field, enumerant, method, group, union): Text;
+annotation name @0xfa5b1fd61c2e7c3d (field, enumerant, method, group, union) :Text;
 # Define an alternative name to use when encoding the given item in JSON. This can be used, for
 # example, to use snake_case names where needed, even though Cap'n Proto uses strictly camelCase.
 #
 # (However, because JSON is derived from JavaScript, you *should* use camelCase names when
 # defining JSON-based APIs. But, when supporting a pre-existing API you may not have a choice.)
 
-annotation flatten @0x82d3e852af0336bf (field, group, union): FlattenOptions;
+annotation flatten @0x82d3e852af0336bf (field, group, union) :FlattenOptions;
 # Specifies that an aggregate field should be flattened into its parent.
 #
 # In order to flatten a member of a union, the union (or, for an anonymous union, the parent
@@ -87,7 +87,7 @@ struct FlattenOptions {
   # Optional: Adds the given prefix to flattened field names.
 }
 
-annotation discriminator @0xcfa794e8d19a0162 (struct, union): DiscriminatorOptions;
+annotation discriminator @0xcfa794e8d19a0162 (struct, union) :DiscriminatorOptions;
 # Specifies that a union's variant will be decided not by which fields are present, but instead
 # by a special discriminator field. The value of the discriminator field is a string naming which
 # variant is active. This allows the members of the union to have the $jsonFlatten annotation, or
@@ -105,8 +105,11 @@ struct DiscriminatorOptions {
   # It is an error to use `valueName` while also declaring some variants as $flatten.
 }
 
-annotation base64 @0xd7d879450a253e4b (field): Void;
+annotation base64 @0xd7d879450a253e4b (field) :Void;
 # Place on a field of type `Data` to indicate that its JSON representation is a Base64 string.
 
-annotation hex @0xf061e22f0ae5c7b5 (field): Void;
+annotation hex @0xf061e22f0ae5c7b5 (field) :Void;
 # Place on a field of type `Data` to indicate that its JSON representation is a hex string.
+
+annotation notification @0xa0a054dea32fd98c (method) :Void;
+# Indicates that this method is a JSON-RPC "notification", meaning it expects no response.

c++/src/capnp/compat/json.h

@@ -303,6 +303,12 @@ void JsonCodec::encode(T&& value, JsonValue::Builder output) const {
   encode(DynamicValue::Reader(ReaderFor<Base>(kj::fwd<T>(value))), Type::from<Base>(), output);
 }
 
+template <>
+inline void JsonCodec::encode<DynamicStruct::Reader>(
+      DynamicStruct::Reader&& value, JsonValue::Builder output) const {
+  encode(DynamicValue::Reader(value), value.getSchema(), output);
+}
+
 template <typename T>
 inline Orphan<T> JsonCodec::decode(JsonValue::Reader input, Orphanage orphanage) const {
   return decode(input, Type::from<T>(), orphanage).template releaseAs<T>();

c++/src/capnp/dynamic.h

@@ -584,6 +584,9 @@ public:
   kj::Promise<void> tailCall(Request<SubParams, DynamicStruct>&& tailRequest);
   void allowCancellation();
 
+  StructSchema getParamsType() const { return paramType; }
+  StructSchema getResultsType() const { return resultType; }
+
 private:
   CallContextHook* hook;
   StructSchema paramType;