README.md
1ARPC - An RPC framework that supports file descriptor passing
2=============================================================
3
4## Introduction
5
6ARPC is an RPC framework that is heavily inspired by Google's Protobuf
7and GRPC and aims to be compatible with its core C++ API.
8
9Similar to GRPC/Protobuf, ARPC ships with a script called `aprotoc` that
10can convert `.proto` files to C++ header files containing message and
11service bindings. Where ARPC differs from GRPC/Protobuf is that it
12provides support for attaching file descriptors to messages and sending
13them to other processes on the system. It accomplishes this by making
14use of [file descriptor passing](https://keithp.com/blogs/fd-passing/),
15a feature that is available when making use of `AF_UNIX` sockets.
16
17ARPC can be very useful for adding [privilege separation](https://en.wikipedia.org/wiki/Privilege_separation)
18to your software. For example, a mail server could run with almost no
19privileges, but still be able to deliver mail to user's mailboxes by
20making use of an auxiliary process that hands out file descriptors to
21mail spools stored on disk.
22
23ARPC does not support any authentication and authorization, for the
24reason that it is mainly intended to be used across UNIX sockets. It
25also does not provide any support for concurrency and GRPC's
26asynchronous API. Concurrency can be introduced by opening multiple
27channels across separate UNIX sockets.
28
29ARPC has been built on top of a serialization library called
30[Argdata](https://github.com/NuxiNL/argdata), which in its turn has been
31developed as hierarchical configuration file format for
32[the CloudABI sandboxing framework](https://nuxi.nl/cloudabi/).
33
34## Building ARPC
35
36ARPC can be built natively using:
37
38 mkdir build
39 cd build
40 cmake -DCMAKE_BUILD_TYPE=Release ..
41 make
42
43It can be compiled for CloudABI for i686 as follows:
44
45 mkdir build
46 cd build
47 cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-i686-cloudabi.cmake ..
48 make
49
50To install in a specific location, give `-DCMAKE_INSTALL_PREFIX` to CMake.
51'make install' will then install the headers, library and `aprotoc` there.
52
53## Using ARPC
54
55ARPC should be easy to use if you already have some experience using
56GRPC. Be sure to check out
57[the GRPC C++ tutorial](http://www.grpc.io/docs/tutorials/basic/c.html)
58to become familiar with the basics. Differences between GRPC and ARPC
59worth mentioning:
60
61- All of ARPC's definitions are stored in a single header file,
62 `<arpc++/arpc++.h>` and are part of namespace `arpc`.
63- In addition to the commonly used Protobuf datatypes (e.g., `int32`,
64 `string`, `bool`), ARPC's `aprotoc` allows you to declare fields of
65 type `fd`, which adds a field to the message of type
66 `std::shared_ptr<FileDescriptor>`.
67- ARPC servers and channels do not create UNIX sockets themselves. File
68 descriptors of connected `AF_UNIX`, `SOCK_STREAM` sockets must be
69 provided to `arpc::CreateChannel()` and `arpc::ServerBuilder`.
70- [The unit tests](src/server_test.cc) also contain some examples of how
71 to use ARPC.
72