Skip to content

C
capnproto
Commit a984a0fb authored by Kenton Varda's avatar Kenton Varda
Browse files
Options

Document RPC.

parent 3c7efbb4
Hide whitespace changes
Inline Side-by-side
Showing with 668 additions and 48 deletions
doc/_includes/header.html
View file @ a984a0fb
......@@ -39,7 +39,8 @@
<li><a href="{{ site.baseurl }}encoding.html">Encoding</a></li>
<li><a href="{{ site.baseurl }}rpc.html">RPC Protocol</a></li>
<li><a href="{{ site.baseurl }}capnp-tool.html">The <code>capnp</code> Tool</a></li>
<li><a href="{{ site.baseurl }}cxx.html">C++ Runtime</a></li>
<li><a href="{{ site.baseurl }}cxx.html">C++ Serialization</a></li>
<li><a href="{{ site.baseurl }}cxxrpc.html">C++ RPC</a></li>
<li><a href="{{ site.baseurl }}otherlang.html">Other Languages</a></li>
<li><a href="{{ site.baseurl }}roadmap.html">Road Map</a></li>
</ul>
......
doc/_plugins/capnp_lexer.py
View file @ a984a0fb
......@@ -15,7 +15,7 @@ class CapnpLexer(RegexLexer):
(r'=', Literal, 'expression'),
(r':', Name.Class, 'type'),
(r'\$', Name.Attribute, 'annotation'),
(r'(struct|enum|interface|union|import|using|const|annotation|in|of|on|as|with|from|fixed)\b',
(r'(struct|enum|interface|union|import|using|const|annotation|extends|in|of|on|as|with|from|fixed)\b',
Token.Keyword),
(r'[a-zA-Z0-9_.]+', Token.Name),
(r'[^#@=:$a-zA-Z0-9_]+', Text),
......
doc/cxx.md
View file @ a984a0fb
......@@ -3,10 +3,11 @@ layout: page
title: C++ Runtime
---
# C++ Runtime
# C++ Serialization
The Cap'n Proto C++ runtime implementation provides an easy-to-use interface for manipulating
messages backed by fast pointer arithmetic.
messages backed by fast pointer arithmetic. This page discusses the serialization layer of
the runtime; see [C++ RPC](cxxrpc.html) for information about the RPC layer.
## Example Usage
......@@ -173,7 +174,13 @@ To generate C++ code from your `.capnp` [interface definition](language.html), r
This will create `myproto.capnp.h` and `myproto.capnp.c++` in the same directory as `myproto.capnp`.
To use this code in your app, you must link against both `libcapnp` and `libkj`.
To use this code in your app, you must link against both `libcapnp` and `libkj`. If you use
`pkg-config`, Cap'n Proto provides the `capnp` module to simplify discovery of compiler and linker
flags.
If you use [RPC](cxxrpc.html) (i.e., your schema defines [interfaces](language.html#interfaces)),
then you will additionally nead to link against `libcapnp-rpc` and `libkj-async`, or use the
`capnp-rpc` `pkg-config` module.
### Setting a Namespace
......@@ -362,7 +369,7 @@ implicitly convertible in this way. Unfortunately, this trick doesn't work on G
### Interfaces
Interfaces (RPC) are not yet implemented at this time.
[Interfaces (RPC) have their own page.](cxxrpc.html)
### Constants
......
doc/cxxrpc.md 0 → 100644
View file @ a984a0fb
---
layout: page
title: C++ Runtime
---
# C++ RPC
The Cap'n Proto C++ RPC layer sits on top of the [serialization layer](cxx.html) and implements
the [RPC protocol](rpc.html).
## Current Status
As of version 0.4, Cap'n Proto's C++ RPC implementation is a [Level 1](rpc.html#protocol_features)
implementation. Persistent capabilities, three-way introductions, and distributed equality are
not yet implemented.
## Sample Code
The [Calculator example](https://github.com/kentonv/capnproto/tree/master/c++/samples) implements
a fully-functional Cap'n Proto client and server.
## KJ Concurrency Framework
RPC naturally requires a notion of concurrency. Unfortunately,
[all concurrency models suck](https://plus.google.com/u/0/+KentonVarda/posts/D95XKtB5DhK).
Cap'n Proto's RPC is based on the [KJ library](cxx.html#kj_library)'s event-driven concurrency
framework. The core of the KJ asynchronous framework (events, promises, callbacks) is defined in
`kj/async.h`, with I/O interfaces (streams, sockets, networks) defined in `kj/async-io.h`.
### Event Loop Concurrency
KJ's concurrency model is based on event loops. While multiple threads are allowed, each thread
must have its own event loop. KJ discourages fine-grained interaction between threads as
synchronization is expensive and error-prone. Instead, threads are encouraged to communicate
through Cap'n Proto RPC.
KJ's event loop model bears a lot of similarity to the Javascript concurrency model. Experienced
Javascript hackers -- especially node.js hackers -- will feel right at home.
_As of version 0.4, the only supported way to communicate between threads is over pipes or
socketpairs. This will be improved in future versions._
### Promises
Function calls that do I/O must do so asynchronously, and must return a "promise" for the
result. Promises -- also known as "futures" in some systems -- are placeholders for the results
of operations that have not yet completed. When the operation completes, we say that the promise
"resolves" to a value, or is "fulfilled". A promise can also be "rejected", which means an
exception occurred.
{% highlight c++ %}
kj::Promise<kj::String> fetchHttp(kj::StringPtr url);
// Asynchronously fetches an HTTP document and returns
// the content as a string.
kj::Promise<void> sendEmail(kj::StringPtr address,
kj::StringPtr title, kj::StringPtr body);
// Sends an e-mail to the given address with the given title
// and body.
{% endhighlight %}
As you will see, KJ promises are very similar to the evolving Javascript promise standard, and
much of the [wisdom around it](https://www.google.com/search?q=javascript+promises) can be directly
applied to KJ promises.
### Callbacks
If you want to do something with the result of a promise, you must first wait for it to complete.
This is normally done by registering a callback to execute on completion. Luckily, C++11 just
introduced lambdas which makes this far more pleasant than it would have been a few years ago!
{% highlight c++ %}
kj::Promise<kj::String> contentPromise =
fetchHttp("http://example.com");
kj::Promise<int> lineCountPromise =
promise.then([](kj::String& content) {
return countChars(content, '\n');
});
{% endhighlight %}
The callback passed to `then()` takes the promised result as its parameter and returns a new value.
`then()` itself returns a new promise for that value which the callback will eventually return.
If the callback itself returns a promise, then `then()` actually returns a promise for the
resolution of the latter promise -- that is, `Promise<Promise<T>>` is automatically reduced to
`Promise<T>`.
Note that `then()` consumes the original promise: you can only call `then()` once. This is true
of all of the methods of `Promise`. The only way to consume a promise in multiple places is to
first "fork" it with the `fork()` method, which we don't get into here. Relatedly, promises
are linear types, which means they have move constructors but not copy constructors.
### Error Propagation
`then()` takes an optional second parameter for handling errors. Think of this like a `catch`
block.
{% highlight c++ %}
kj::Promise<int> lineCountPromise =
promise.then([](kj::String& content) {
return countChars(content, '\n');
}, [](kj::Exception&& exception) {
// Error! Pretend the document was empty.
return 0;
});
{% endhighlight %}
Note that the KJ framework coerces all exceptions to `kj::Exception` -- the exception's description
(as returned by `what()`) will be retained, but any type-specific information is lost. Under KJ
exception philosophy, exceptions always represent an error that should not occur under normal
operation, and the only purpose of exceptions is to make software fault-tolerant. In particular,
the only reasonable ways to handle an exception are to try again, tell a human, and/or propagate
to the caller. To that end, `kj::Exception` contains information useful for reporting purposes
and to help decide if trying again is reasonable, but typed exception hierarchies are not useful
and not supported.
It is recommended that Cap'n Proto code use the assertion macros in `kj/debug.h` to throw
exceptions rather than use the C++ `throw` keyword. These macros make it easy to add useful
debug information to an exception and generally play nicely with the KJ framework. In fact, you
can even use these macros -- and propagate exceptions through promises -- if you compile your code
with exceptions disabled. See the headers for more information.
### Waiting
It is illegal for code running in an event callback to wait, since this would stall the event loop.
However, if you are the one responsible for starting the event loop in the first place, then KJ
makes it easy to say "run the event loop until this promise resolves, then return the result".
{% highlight c++ %}
kj::EventLoop loop;
kj::WaitScope waitScope(loop);
kj::Promise<kj::String> contentPromise =
fetchHttp("http://example.com");
kj::String content = contentPromise.wait(waitScope);
int lineCount = countChars(content, '\n');
{% endhighlight %}
Using `wait()` is common in high-level client-side code. On the other hand, it is almost never
used in servers.
### Cancellation
If you discard a `Promise` without calling any of its methods, the operation it was waiting for
is canceled, because the `Promise` itself owns that operation. This means than any pending
callbacks simply won't be executed. If you need explicit notification when a promise is canceled,
you can use its `attach()` method to attach an object with a destructor -- the destructor will be
called when the promise either completes or is canceled.
### Other Features
KJ promise a number of primitive operations that can be performed on promises. The complete API
is documented directly in the `kj/async.h` header. Additionally, see the `kj/async-io.h` header
for APIs for performing basic network I/O -- although Cap'n Proto RPC users typically won't need
to use these APIs directly.
## Generated Code
Imagine the following interface:
{% highlight capnp %}
interface Directory {
create @0 (name :Text) -> (file :File);
open @1 (name :Text) -> (file :File);
remove @2 (name :Text);
}
{% endhighlight %}
`capnp compile` will generate code that looks like this (edited for readability):
{% highlight c++ %}
struct Directory {
Directory() = delete;
class Client;
class Server;
struct CreateParams;
struct CreateResults;
struct OpenParams;
struct OpenResults;
struct RemoveParams;
struct RemoveResults;
// Each of these is equivalent to what would be generated for
// a Cap'n Proto struct with one field for each parameter /
// result.
};
class Directory::Client
: public virtual capnp::Capability::Client {
public:
Client(std::nullptr_t);
Client(kj::Own<Directory::Server> server);
Client(kj::Promise<Client> promise);
Client(kj::Exception exception);
capnp::Request<CreateParams, CreateResults> createRequest();
capnp::Request<OpenParams, OpenResults> openRequest();
capnp::Request<RemoveParams, RemoveResults> removeRequest();
};
class Directory::Server
: public virtual capnp::Capability::Server {
protected:
typedef capnp::CallContext<CreateParams, CreateResults> CreateContext;
typedef capnp::CallContext<OpenParams, OpenResults> OpenContext;
typedef capnp::CallContext<RemoveParams, RemoveResults> RemoveContext;
// Convenience typedefs.
virtual kj::Promise<void> create(CreateContext context);
virtual kj::Promise<void> open(OpenContext context);
virtual kj::Promise<void> remove(RemoveContext context);
// Methods for you to implement.
};
{% endhighlight %}
### Clients
The generated `Client` type represents a reference to a remote `Server`. `Client`s are
pass-by-value types that use reference counting under the hood. (Warning: For performance
reasons, the reference counting used by `Client`s is not thread-safe, so you must not copy a
`Client` to another thread, unless you do it by means of an inter-thread RPC.)
A `Client` can be implicitly constructed from any of:
* A `kj::Own<Server>`, which takes ownership of the server object and creates a client that
calls it. (You can get a `kj::Own<T>` to a newly-allocated heap object using
`kj::heap<T>(constructorParams)`; see `kj/memory.h`.)
* A `kj::Promise<Client>`, which creates a client whose methods first wait for the promise to
resolve, then forward the call to the resulting client.
* A `kj::Exception`, which creates a client whose methods always throw that exception.
* `nullptr`, which creates a client whose methods always throw. This is meant to be used to
initialize variables that will be initialized to a real value later on.
For each interface method `foo()`, the `Client` has a method `fooRequest()` which creates a new
request to call `foo()`. The returned `capnp::Request` object has methods equivalent to a
`Builder` for the parameter struct (`FooParams`), with the addition of a method `send()`.
`send()` sends the RPC and returns a `capnp::RemotePromise<FooResults>`.
This `RemotePromise` is equivalent to `kj::Promise<capnp::Response<FooResults>>`, but also has
methods that allow pipelining. Namely:
* For each interface-typed result, it has a getter method which returns a `Client` of that type.
Calling this client will send a pipelined call to the server.
* For each struct-typed result, it has a getter method which returns an object containing pipeline
getters for that struct's fields.
In other words, the `RemotePromise` effectively implements a subset of the eventual results'
`Reader` interface -- one that only allows access to interfaces and sub-structs.
The `RemotePromise` eventually resolves to `capnp::Response<FooResults>`, which behaves like a
`Reader` for the result struct except that it also owns the result message.
{% highlight c++ %}
Directory::Client dir = ...;
// Create a new request for the `open()` method.
auto request = dir.openRequest();
request.setName("foo");
// Send the request.
auto promise = request.send();
// Make a pipelined request.
auto promise2 = promise.getFile().getSizeRequest().send();
// Wait for the full results.
auto promise3 = promise2.then(
[](capnp::Response<File::GetSizeResults>&& response) {
cout << "File size is: " << response.getSize() << endl;
});
{% endhighlight %}
### Servers
The generated `Server` type is an abstract interface which may be subclassed to implement a
capability. Each method takes a `context` argument and returns a `kj::Promise<void>` which
resolves when the call is finished. The parameter and result structures are accessed through the
context -- `context.getParams()` returns a `Reader` for the parameters, and `context.getResults()`
returns a `Builder` for the results. The context also has methods for controlling RPC logistics,
such as cancellation -- see `capnp::CallContext` in `capnp/capability.h` for details.
Accessing the results through the context (rather than by returning them) is unintuitive, but
necessary because the underlying RPC transport needs to have control over where the results are
allocated. For example, a zero-copy shared memory transport would need to allocate the results in
the shared memory segment. Hence, the method implementation cannot just create its own
`MessageBuilder`.
{% highlight c++ %}
class DirectoryImpl final: public Directory::Server {
public:
kj::Promise<void> open(OpenContext context) override {
auto iter = files.find(context.getRequest().getName());
// Throw an exception if not found.
KJ_REQUIRE(iter != files.end(), "File not found.");
context.getResults().setFile(iter->second);
return kj::READY_NOW;
}
// Any method which we don't implement will simply throw
// an exception by default.
private:
std::map<kj::StringPtr, File::Client> files;
};
{% endhighlight %}
## Initializing RPC
Cap'n Proto makes it easy to start up an RPC client or server using the "EZ RPC" classes,
defined in `capnp/ez-rpc.h`. These classes get you up and running quickly, but they hide a lot
of details that power users will likely want to manipulate. Check out the comments in `ez-rpc.h`
to understand exactly what you get and what you miss. For the purpose of this overview, we'll
show you how to use EZ RPC to get started.
### Starting a client
A client should typically look like this:
{% highlight c++ %}
#include <capnp/ez-rpc.h>
#include "my-interface.capnp.h"
int main(int argc, const char* argv[]) {
// We expect one argument specifying the server address.
if (argc != 2) {
std::cerr << "usage: " << argv[0] << " HOST[:PORT]" << std::endl;
return 1;
}
// Set up the EzRpcClient, connecting to the server on port
// 5923 unless a different port was specified by the user.
capnp::EzRpcClient client(argv[1], 5923);
auto& waitScope = client.getWaitScope();
// Request the service named "foo" from the server.
MyInterface::Client cap =
client.importCap<MyInterface>("foo");
// Make a call to the capability.
auto request = cap.fooRequest();
request.setParam(123);
auto promise = request.send();
// Wait for the result. This is the only line that blocks.
auto response = promise.wait(waitScope);
// All done.
std::cout << response.getResult() << std::endl;
return 0;
}
{% endhighlight %}
Note that for the connect address, Cap'n Proto supports DNS host names as well as IPv4 and IPv6
addresses. Additionally, a Unix domain socket can be specified as `unix:` followed by a path name.
For a more complete example, see the
[calculator client sample](https://github.com/kentonv/capnproto/tree/master/c++/samples/calculator-client.c++).
### Starting a server
A server might look something like this:
{% highlight c++ %}
#include <capnp/ez-rpc.h>
#include "my-interface-impl.h"
int main(int argc, const char* argv[]) {
// We expect one argument specifying the address to which
// to bind and accept connections.
if (argc != 2) {
std::cerr << "usage: " << argv[0] << " ADDRESS[:PORT]"
<< std::endl;
return 1;
}
// Set up the EzRpcServer, binding to port 5923 unless a
// different port was specified by the user.
capnp::EzRpcServer server(argv[1], 5923);
// Export a capability under the name "foo". Note that the
// second parameter here can be any "Client" object or anything
// that can implicitly cast to a "Client" object. You can even
// re-export a capability imported from another server.
server.exportCap("foo", kj::heap<MyInterfaceImpl>());
// Run forever, accepting connections and handling requests.
kj::NEVER_DONE.wait(waitScope);
}
{% endhighlight %}
Note that for the bind address, Cap'n Proto supports DNS host names as well as IPv4 and IPv6
addresses. The special address `*` can be used to bind to the same port on all local IPv4 and
IPv6 interfaces. Additionally, a Unix domain socket can be specified as `unix:` followed by a
path name.
For a more complete example, see the
[calculator server sample](https://github.com/kentonv/capnproto/tree/master/c++/samples/calculator-server.c++).
doc/index.md
View file @ a984a0fb
......@@ -67,6 +67,11 @@ Glad you asked!
order of magnitude or more. In fact, usually it's no more than some inline accessor methods!
* **Tiny runtime library:** Due to the simplicity of the Cap'n Proto format, the runtime library
can be much smaller.
* **Time-traveling RPC:** Cap'n Proto features an RPC system implements [time travel](rpc.html)
such that call results are returned to the client before the request even arrives at the server!
<a href="rpc.html"><img src='images/time-travel.png' style='max-width:639px'></a>
**_Why do you pick on Protocol Buffers so much?_**
......
doc/language.md
View file @ a984a0fb
......@@ -13,8 +13,7 @@ manipulate that message type in your desired language.
For example:
{% highlight capnp %}
# unique file ID, generated by `capnp id`
@0xdbb9ad1f14bf0b36;
@0xdbb9ad1f14bf0b36; # unique file ID, generated by `capnp id`
struct Person {
name @0 :Text;
......@@ -304,38 +303,46 @@ be considered numeric.
### Interfaces
An interface has a collection of methods, each of which takes some parameters and returns a
result. Like struct fields, methods are numbered.
An interface has a collection of methods, each of which takes some parameters and return some
results. Like struct fields, methods are numbered. Interfaces support inheritance, including
multiple inheritance.
{% highlight capnp %}
interface Directory {
list @0 () :List(FileInfo);
create @1 (name :Text) :FileInfo;
open @2 (name :Text) :FileInfo;
delete @3 (name :Text) :Void;
link @4 (name :Text, file :File) :Void;
interface Node {
isDirectory @0 () -> (result :Bool);
}
struct FileInfo {
name @0 :Text;
size @1 :UInt64;
file @2 :File; # A pointer to a File.
interface Directory extends(Node) {
list @0 () -> (list: List(Entry));
struct Entry {
name @0 :Text;
node @1 :Node;
}
create @1 (name :Text) -> (file :File);
mkdir @2 (name :Text) -> (directory :Directory)
open @3 (name :Text) -> (node :Node);
delete @4 (name :Text);
link @5 (name :Text, node :Node);
}
interface File {
read @0 (startAt :UInt64 = 0, amount :UInt64 = 0xffffffffffffffff) :Data;
interface File extends(Node) {
size @0 () -> (size: UInt64);
read @1 (startAt :UInt64 = 0, amount :UInt64 = 0xffffffffffffffff)
-> (data: Data);
# Default params = read entire file.
write @1 (startAt :UInt64, data :Data) :Void;
truncate @2 (size :UInt64) :Void;
write @2 (startAt :UInt64, data :Data);
truncate @3 (size :UInt64);
}
{% endhighlight %}
Notice something interesting here: `FileInfo` is a struct, but it contains a `File`, which is an
interface. Structs (and primitive types) are passed over RPC by value, but interfaces are passed by
reference. So when `Directory.open` is called remotely, the content of a `FileInfo` (including
values for `name` and `size`) is transmitted back, but for the `file` field, only the address of
some remote `File` object is sent.
Notice something interesting here: `Node`, `Directory`, and `File` are interfaces, but several
methods take these types as parameters or return them as results. `Directory.Entry` is a struct,
but it contains a `Node`, which is an interface. Structs (and primitive types) are passed over RPC
by value, but interfaces are passed by reference. So when `Directory.list` is called remotely, the
content of a `List(Entry)` (including the text of each `name`) is transmitted back, but for the
`node` field, only a reference to some remote `Node` object is sent.
When an address of an object is transmitted, the RPC system automatically manages making sure that
the recipient gets permission to call the addressed object -- because if the recipient wasn't
......
doc/rpc.md
View file @ a984a0fb
......@@ -5,22 +5,218 @@ title: RPC Protocol
# RPC Protocol
The Cap'n Proto RPC protocol is not yet defined. See the language spec's
[section on interfaces](language.html#interfaces) for a hint of what it will do.
Here are some misc planned / hoped-for features:
* **Shared memory IPC:** When instructed to communicate over a Unix domain socket, Cap'n Proto may
automatically negotiate to use shared memory, by creating a temporary file and then sending a
file descriptor across the socket. Once messages are being allocated in shared memory, RPCs
can be initiated by merely signaling a [futex](http://man7.org/linux/man-pages/man2/futex.2.html)
(on Linux, at least), which ought to be ridiculously fast.
* **Promise Pipelining:** When an RPC will return a reference to a new remote object, the client
will be able to initiate calls to the returned object before the initial RPC has actually
completed. Essentially, the client says to the server: "Call method `foo` of the object to be
returned by RPC id N." Obviously, if the original RPC fails, the dependent call also fails.
Otherwise, the server can start executing the dependent call as soon as the original call
completes, without the need for a network round-trip. In the object-capability programming
language <a href="http://en.wikipedia.org/wiki/E_(programming_language)">E</a> this is known as
[promise pipelining](http://en.wikipedia.org/wiki/Futures_and_promises#Promise_pipelining).
## Introduction
### Time Travel! _(Promise Pipelining)_
<img src='images/time-travel.png' style='max-width:639px'>
Cap'n Proto RPC employs TIME TRAVEL! The results of an RPC call are returned to the client
instantly, before the server even receives the request to start working on it!
There is, of course, a catch: The results can only be used as part of a new request sent to the
same server. If you want to use the results for anything else, you must wait.
This is useful, however: Say that, as in the picture, you want to call `foo()`, then call `bar()`
on its result, i.e. `bar(foo())`. Or -- as is very common in object-oriented programming -- you
want to call a method on the result of another call, i.e. `foo().bar()`. With any traditional RPC
system, this will require two network round trips. With Cap'n Proto, it takes only one. In fact,
you can chain any number of such calls together -- with diamond dependencies and everything -- and
Cap'n Proto will collapse them all into one call.
By now you can probably imagine how it works: if you execute `bar(foo())`, the client sends two
messages to the server, one saying "Please execute foo()", and a second saying "Please execute
bar() on the result of the first call". These messages can be sent together -- there's no need
to wait for the first call to actually return.
To make programming to this model easy, in your code, each call returns a "promise". Promises
work much like Javascript promises or promises/futures in other languages: the promise is returned
immediately, but you must later call `wait()` or register a completion callback to handle.
However, Cap'n Proto promises support an additional feature:
[pipelining](http://en.wikipedia.org/wiki/Futures_and_promises#Promise_pipelining). The promise
actually has methods corresponding to whatever methods the final result would have, except that
these methods may only be used for the purpose of calling back to the server. Moreover, a
pipelined promise can be used in the parameters to another call without waiting.
**_But isn't that just syntax sugar?_**
OK, fair enough. In a traditional RPC system, we might solve our problem by introducing a new
method `foobar()` which combines `foo()` and `bar()`. Now we've eliminated the round trip, without
inventing a new protocol.
The problem is, this kind of arbitrary combining of orthogonal features quickly turns nice, elegant
object-oriented protocols into ad-hoc procedural messes.
For example, consider the following interface:
{% highlight capnp %}
# A happy, object-oriented interface!
struct Node {
union {
file :File;
directory :Directory;
}
}
interface Directory {
list @0 () -> (list: List(Entry));
struct Entry {
name @0 :Text;
file @1 :Node;
}
create @1 (name :Text) -> (node :Node);
open @2 (name :Text) -> (node :Node);
delete @3 (name :Text);
link @4 (name :Text, node :Node);
}
interface File {
size @0 () -> (size: UInt64);
read @1 (startAt :UInt64, amount :UInt64) -> (data: Data);
write @2 (startAt :UInt64, data :Data);
truncate @3 (size :UInt64);
}
{% endhighlight %}
This a very clean interface for interacting with a file system. But say you are using this
interface over a satellite link with 1000ms latency. Now you have a problem: simply reading the
file `foo` in directory `bar` takes four round trips!
{% highlight python %}
# pseudocode
foo = root.open("foo").node.directory; # 1
bar = foo.open("bar").node.file; # 2
size = bar.size(); # 3
data = bar.read(0, size); # 4
{% endhighlight %}
In such a high-latency scenario, making your interface elegant is simply not worth 4x the latency.
So now you're going to change it. You'll probably do something like:
* Introduce a notion of path strings, so that you can specify "foo/bar" rather than make two
separate calls.
* Merge the `File` and `Directory` interfaces into a single `Filesystem` interface, where every
call takes a path as an argument.
{% highlight capnp %}
# A sad, singleton-y interface.
interface Filesystem {
list @0 (path :Text) -> (list :List(Text));
create @1 (path :Text, data :Data);
delete @2 (path :Text);
link @3 (path :Text, target :Text);
fileSize @4 (path :Text) -> (size: UInt64);
read @5 (path :Text, startAt :UInt64, amount :UInt64)
-> (data: Data);
readAll @6 (path :Text) -> (data: Data);
write @7 (path :Text, startAt :UInt64, data :Data);
truncate @8 (path :Text, size :UInt64);
}
{% endhighlight %}
We've now solved our latency problem... but at what cost?
* We now have to implement path string manipulation, which is always a headache.
* If someone wants to perform multiple operations on a file or directory, we now either have to
re-allocate resources for every call or we have to implement some sort of cache, which tends to
be complicated and error-prone.
* We can no longer give someone a specific `File` or a `Directory` -- we have to give them a
`Filesystem` and a path.
* But what if they are buggy and have hard-coded some path other than the one we specified?
* Or what if we don't trust them, and we really want them to access only one particular `File` or
`Directory` and not have permission to anything else. Now we have to implement authentication
and authorization systems! Arrgghh!
Essentially, in our quest to avoid latency, we've resorted to using a singleton-ish design, and
[singletons are evil](http://www.object-oriented-security.org/lets-argue/singletons).
**Promise Pipelining solves all of this!**
With pipelining, our 4-step example can be automatically reduced to a single round trip with no
need to change our interface at all. We keep our simple, elegant, singleton-free interface, we
don't have to implement path strings, caching, authentication, or authorization, and yet everything
performs as well as we can possibly hope for.
### Distributed Objects
As you've noticed by now, Cap'n Proto RPC is a distributed object protocol. Interface references --
or, as we more commonly call them, capabilities -- are a first-class type. You can pass a
capability as a parameter or embed it in a struct or list. This is a huge difference from many
modern RPC-over-HTTP protocols that only let you address global URLs, or other RPC systems like
Protocol Buffers and Thrift that only let you address singleton objects exported at startup. The
ability to dynamically introduce new objects and pass around references to them allows you to use
the same design patterns over the network that you use locally in object-oriented programming
languages. Many kinds of interactions become vastly easier to express given the richer vocabulary.
**_Didn't CORBA prove this doesn't work?_**
No!
CORBA failed for many reasons, with the usual problems of design-by-committee being a big one.
However, CORBA also had a critical technical flaw: it did not implement promise pipelining. As
shown above, promise pipelining is absolutely critical to making object-oriented interfaces work
in the presence of latency. It is often said that object- and RPC-oriented protocols don't work
because they try to pretend that a network call is equivalent to a local call. In reality, this
is not actually a problem with object protocols in general, but specifically CORBA and
similarly-naive protocols that lack promise pipelining. Promise pipelining is the missing link.
### Security
Cap'n Proto interafce references are
[capabilities](http://en.wikipedia.org/wiki/Capability-based_security). That is, they both
designate an object to call and confer permission to call it. When a new object is created, only
the creator is initially able to call it. When the object is passed over a network connection,
the receiver gains permission to make calls -- but no one else does. In fact, it is impossible
for others to access the capability without consent of either the host or the receiver because
the host only assigns it an ID specific to the connection over which it was sent.
Capability-based design patterns -- which largely boil down to object-oriented design patterns --
work great with Cap'n Proto. Such patterns tend to be much more agile than traditional ACL-based
security, making it easy to keep security tight and avoid confused-deputy attacks while minimizing
pain for legitimate users. That said, you can of course implement ACLs or any other pattern on top
of capabilities.
## Protocol Features
Cap'n Proto's RPC protocol has the following notable features. Since the protocol is complicated,
the feature set has been divided into numbered "levels", so that implementations may declare which
features they have covered by advertising a level number.
* **Level 1:** Object references and promise pipelining, as described above.
* **Level 2:** Persistent capabilities. You may request to "save" a capability, receiving a
persistent token which can be used to "restore" it in the future (on a new connection). Not
all capabilities can be saved; the host app must implement support for it. Building this into
the protocol makes it possible for a Cap'n-Proto-based data store to transparently save
structures containing capabilities without knowledge of the particular capability types or the
application built on them, as well as potentially enabling more powerful analysis and
visualization of stored data.
* **Level 3:** Three-way interactions. A network of Cap'n Proto vats (nodes) can pass object
references to each other and automatically form direct connections as needed. For instance, if
Alice (on machine A) sends Bob (on machine B) a reference to Carol (on machine C), then machine B
will form a new connection to machine C so that Bob can call Carol directly without proxying
through machine A.
* **Level 4:** Reference equality / joining. If you receive a set of capabilities from different
parties which should all point to the same underlying objects, you can verify securely that they
in fact do. This is subtle, but enables many security patterns that rely on one party being able
two verify that two or more other parties agree on something (imagine a digital escrow agent).
See [E's page on equality](http://erights.org/elib/equality/index.html).
## Specification
The Cap'n Proto RPC protocol is defined in terms of Cap'n Proto serialization schemas. The
documentation is inline. See
[rpc.capnp](https://github.com/kentonv/capnproto/blob/master/c++/src/capnp/rpc.capnp).
Cap'n Proto's RPC protocol is based heavily on
[CapTP](http://www.erights.org/elib/distrib/captp/index.html), the distributed capability protocol
used by the [E programming language](http://www.erights.org/index.html). Lots of useful material
for understanding capabilities can be found at those links.
The protocol is complex, but the functionality it supports is conceptually simple. Just as TCP
is a complex protocol that implements the simple concept of a byte stream, Cap'n Proto RPC is a
complex protocol that implements the simple concept of objects with callable methods.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment