IRPC

A streaming rpc system for iroh

Goals

See the module docs.

Docs

Properly building docs for this crate is quite complex. For all the gory details, see DOCS.md.

lib.rs:

A minimal RPC library for use with iroh.

Goals

The main goal of this library is to provide an rpc framework that is so lightweight that it can be also used for async boundaries within a single process without any overhead, instead of the usual practice of a mpsc channel with a giant message enum where each enum case contains mpsc or oneshot backchannels.

The second goal is to lightly abstract over remote and local communication, so that a system can be interacted with cross process or even across networks.

Non-goals

• Cross language interop. This is for talking from rust to rust
• Any kind of versioning. You have to do this yourself
• Making remote message passing look like local async function calls
• Being runtime agnostic. This is for tokio

Interaction patterns

For each request, there can be a response and update channel. Each channel can be either oneshot, carry multiple messages, or be disabled. This enables the typical interaction patterns known from libraries like grpc:

• rpc: 1 request, 1 response
• server streaming: 1 request, multiple responses
• client streaming: multiple requests, 1 response
• bidi streaming: multiple requests, multiple responses

as well as more complex patterns. It is however not possible to have multiple differently typed tx channels for a single message type.

Transports

We don't abstract over the send and receive stream. These must always be quinn streams, specifically streams from the [iroh quinn fork].

This restricts the possible rpc transports to quinn (QUIC with dial by socket address) and iroh (QUIC with dial by node id).

An upside of this is that the quinn streams can be tuned for each rpc request, e.g. by setting the stream priority or by directy using more advanced part of the quinn SendStream and RecvStream APIs such as out of order receiving.

Serialization

Serialization is currently done using [postcard]. Messages are always length prefixed with postcard varints, even in the case of oneshot channels.

Serialization only happens for cross process rpc communication.

However, the requirement for message enums to be serializable is present even when disabling the rpc feature. Due to the fact that the channels live outside the message, this is not a big restriction.

Features

• rpc: Enable the rpc features. Enabled by default. By disabling this feature, all rpc related dependencies are removed. The remaining dependencies are just serde, tokio and tokio-util.
• message_spans: Enable tracing spans for messages. Enabled by default. This is useful even without rpc, to not lose tracing context when message passing. This is frequently done manually. This obviously requires a dependency on tracing.
• quinn_endpoint_setup: Easy way to create quinn endpoints. This is useful both for testing and for rpc on localhost. Enabled by default.

History

This crate evolved out of the quic-rpc crate, which is a generic RPC framework for any transport with cheap streams such as QUIC. Compared to quic-rpc, this crate does not abstract over the stream type and is focused on iroh and our iroh quinn fork. Module for cross-process RPC using quinn.