cpp-async-rpc: Library for Asynchronicity, Serialization and Remoting

This is cpp-async-rpc, a C++17 library supporting template meta-programming,
asynchronous network programming, binary serialization and RPC.

Disclaimer: This is not a Google supported product.

What does cpp-async-rpc look like?

RPC server and client

Here a single small binary includes an interface definition, the server and the
client.

#include <iostream>
#include <string>
#include "arpc/client.h"
#include "arpc/interface.h"
#include "arpc/server.h"

/// This is the definition of the Greeter interface.
ARPC_INTERFACE(Greeter, (/* doesn't extend other interfaces */),
               (  // Return a salutation..
                   ((std::string), say_hello_to,
                    (((const std::string&), name)))));

/// This is the server-side implementation of the Greeter interface.
struct GreeterImpl : Greeter {
  std::string say_hello_to(const std::string& name) override {
    return "Hello " + name + "!";
  }
};

int main(int argc, char* argv[]) {
  // Create a server-side implementation object.
  arpc::server_object<GreeterImpl> greeter;

  // Set up the server on TCP port 9999 and register the object in it with under
  // the "greeter" name.
  arpc::server server({/* default options */}, arpc::endpoint().port(9999));
  server.register_object("greeter", greeter);

  // Start serving RPCs.
  server.start();

  // Create a client connection to the server.
  arpc::client_connection client(arpc::endpoint().name("localhost").port(9999));

  // Get a proxy for the "greeter" remote object.
  auto greeter_proxy = client.get_proxy<Greeter>("greeter");

  // Call the remote method and print the results.
  std::cout << greeter_proxy.say_hello_to("world") << std::endl;

  return 0;
}

Yeah, we use the C preprocessor as our IDL compiler, which makes the syntax
awkward, but on the other hand your interface definition remains a valid (even
if ugly) C++ header file.

Serialization of custom structures

cpp-async-rpc is able to serialize and deserialize most standard library classes
out of the box. It also handles custom classes that implement standard
interfaces, like the begin()/end() contract for containers. But it wouldn't
be so useful if you couldn't teach it how to serialize your own data structures
(for instance for their use as RPC arguments). Doing so is easy:

#include <iostream>
#include <string>
#include <vector>
#include "arpc/binary_codecs.h"
#include "arpc/iostream_adapters.h"
#include "arpc/serializable.h"

// To be serializable, MyClass must inherit arpc::serializable<MyClass> or
// arpc::dynamic<MyClass> if run-time polymorphism is required.
struct MyClass : arpc::serializable<MyClass> {
  int x;
  double y;
  std::vector<std::string> z;

  // Enumerate the fields that must be serialized.
  ARPC_FIELDS(x, y, z);
};

int main(int argc, char* argv[]) {
  // Create an instance of my data structure.
  MyClass data{{/* base class init */}, 4, 5.5, {"first", "second", "third"}};

  // Create a binary encoder outputting to stdout.
  arpc::ostream_output_stream oos(std::cout);
  arpc::little_endian_binary_encoder encoder(oos);

  // Write the binary data. Try piping the output of this program to xxd.
  encoder(data);

  return 0;
}

Asynchronous networking

This example sends an HTTP get request and prints out the response in an
asynchronous manner. It uses a local context to set a timeout of 10 seconds
for the whole set of calls.

#include <chrono>
#include <exception>
#include <iostream>
#include <string>
#include "arpc/awaitable.h"
#include "arpc/context.h"
#include "arpc/errors.h"
#include "arpc/select.h"
#include "arpc/socket.h"

int main(int argc, char* argv[]) {
  try {
    arpc::context ctx;
    ctx.set_timeout(std::chrono::seconds(10));

    auto s =
        arpc::dial(arpc::endpoint().name("www.kernel.org").service("http"));

    std::string request = "GET / HTTP/1.0\r\nHost: www.kernel.org\r\n\r\n";
    char buf[256];

    while (true) {
      auto [sent, received] = arpc::select(
          request.size() ? s.async_write(request.data(), request.size())
                         : arpc::never().then([]() { return std::size_t{0}; }),
          s.async_read(buf, sizeof(buf)));

      if (sent) {
        std::cout << "S(" << *sent << ")" << std::endl;
        // Remove the bytes we already sent.
        request.erase(0, *sent);
      }

      if (received) {
        std::cout << "R(" << *received << ")" << std::endl
                  << std::string(buf, buf + *received) << std::endl;
      }
    }

    return 0;
  } catch (const arpc::errors::base_error& e) {
    std::cerr << "Exception of type " << e.portable_error_class_name()
              << " with message: " << e.what() << std::endl;
    return 1;
  } catch (...) {
    std::cerr << "Some other exception." << std::endl;
    return 1;
  }
}

Why cpp-async-rpc?

This library evolved from plans to communicate two distinct microcontrollers
over a serial line.

It eventually became a generic serialization framework (because none of the
existing ones would be easy to adapt to the target embedded environments), and
from there on the jump to an RPC framework with support with cancellation and
asynchronous networking was easier.

As cpp-async-rpc built on template metaprogramming to reduce the amount of code
the user would need to write, the library eventually moved from targeting C++11
to target C++17, which simplified a number of things and made some syntax way
more natural.

At of today, the library supports POSIX environments (it's developed on Linux),
but the plan is to eventually make it work for Espressif's
ESP-IDF environment, so that RPC
servers can be implemented in the
ESP32 hardware
platform.

What's in cpp-async-rpc?

Preprocessor-based code generation (sequences, iteration and conditionals).
This is used so that cpp-async-rpc doesn't require an IDL compiler to define
its serializable structures or RPC interfaces. Thanks to the preprocessor,
these are just defined in C++ native headers (albeit with some syntax
contortions).
Meta-programming toolkit: support for compile-time sequences with associated
compile-time or run-time values. The library supports compile-time iteration
on lists of types or values, and compile-time and constexpr mapping
(transform()) and aggregation (accumulate()) of data sequences.
A serialization framework that supports portable binary serialization of most
of the standard types in modern C++, including primitive types, strings,
sequences and associative containers. cpp-async-rpc can also serialize smart
pointers (including run-time polymorphic types and possibly cyclic object
graphs).
Asynchronous primitives for operating on files, sockets and timers, coupled
with synchronization primitives (mutexes, semaphores, flags, queues, futures)
that also support asynchronicity and event composition. A select() function
allows to compose events so that the first one to trigger is notified. The
synchronization primitives are drop-in replacements for the standard library
ones, but they are built on POSIX pipes so that they can be used in
select() or poll().
A subclass of std::thread with support for stackable execution contexts.
The context primitive can hold data or deadlines that are propagated across
RPC call boundaries. If a context is cancelled, any I/O operation or
asynchronous wait related to it will throw an exception immediately.
Networking support for resolving domain names and ports, and establishing
both client and server connections.
Preprocessor-based generation of RPC-oriented "C++ interfaces" (classes with
just pure virtual methods), including asynchronous variants and the
associated RPC proxy implementations.
RPC client and server support for remoting over RPC.

What's still missing?

Discovering and fixing all the bugs.
A usable port to the ESP32 (which will likely involve some
VFS
component to support vestigial pipes as select-able locks.
Non-token test coverage.
Documentation.

Inspiration

Cereal: A C++11 library for
serialization. This was the original source of inspiration for cpp-async-rpc.
Boost MPL, Fusion and Hana libraries. These
provided inspiration on how to process sequences of types or data at compile
time (for example for iterating on struct fields).
The Go language. The cancellable contexts, the channel
multiplexing and the clean networking libraries in Go have inspired some of
the work in cpp-async-rpc.
JavaScript Promises
as the chosen way to encapsulate behaviour to be run once asynchronous
conditions are met.

Dependencies

A C++17 compliant compiler.
The Meson Build system.
Catch2 for the unit testing framework.
fu2::function2 as a handy replacement
for std::function that can support move-only lambdas too.

google/cpp-async-rpc