Crate fizyr_rpc

Rust implementation of the Fizyr RPC procotol.

The Fizyr RPC protocol is a request/response protocol, with bi-directional feedback as long as a request is open. Additionally, you can send individual stream messages that do not initiate a request.

Overview

Peer and PeerHandle

As a user of the library, you will mostly be using the PeerHandle object. The PeerHandle is used to interact with a remote peer. It is used to send and receive requests and stream messages. It can also be split in a PeerReadHandle and a PeerWriteHandle, to allow moving the handles into different tasks. The write handle can also be cloned and used in multiple tasks.

To obtain a PeerHandle, you can call Peer::connect(). This will connect to a remote listener and spawn a background task to read and write messages over the connection. If you need full control over tasks, you can instead create a Peer object and call Peer::run() manually.

Listener

The Listener struct is used to accept incoming connections and gives you a PeerHandle for each incoming connection. You can then use the handle to process incoming messages and to send messages to the peer. Usually, you will want to spawn a task for each accepted connection that handles the communication.

Transports

Each peer internally uses a Transport. The transport is responsible for reading and writing raw messages. By abstracting away the message transport, the library can expose a single generic Peer and Listener struct.

There are different transports for different socket types. Different transports may also use different types as message body. For example, the TcpTransport and UnixStreamTransport use messages with a StreamBody. This StreamBody body type contains raw bytes.

The UnixSeqpacketTransport has messages with a UnixBody, which allows you to embed file descriptors with each message.

Features

The library uses features to avoid unnecessarily large dependency trees. Each feature corresponds to a different transport type. None of the features are enabled by default. Currently, the library has these features:

• tcp: for the TcpTransport
• unix-stream: for the UnixStreamTransport
• unix-seqpacket: for the UnixSeqpacketTransport

Example

use fizyr_rpc::{TcpPeer, StreamConfig};

let (peer, info) = TcpPeer::connect("localhost:1337", StreamConfig::default()).await?;
eprintln!("Connected to: {}", info.remote_address());
let mut request = peer.send_request(1, &b"Hello World!"[..]).await?;

while let Some(update) = request.recv_update().await {
    let body = std::str::from_utf8(&update.body)?;
    eprintln!("Received update: {}", body);
}

let response = request.recv_response().await?;
let body = std::str::from_utf8(&response.body)?;
eprintln!("Received response: {}", body);

Modules

format

Traits for converting between RPC messages and Rust values.

interface_example

Example module for the interface! macro.

introspection

Support types and traits for runtime interface instrospection.

service_id

Well-known service IDs.

transport

Transport traits and concrete implementations.

util

Utility traits.

Macros

interface

Define an RPC interface.

Structs

Error

Opaque error for all RPC operations.

Listener

Listener that spawns peers for all accepted connections.

Message

A complete RPC message, including header and body.

MessageHeader

A message header.

Peer

Peer read/write loop.

PeerCloseHandle

Handle to close the connection with a peer.

PeerHandle

Handle to a peer.

PeerReadHandle

Handle to receive messages from a peer.

PeerWriteHandle

Handle to send messages to a peer.

ReceivedRequestHandle

A handle for a received request.

ReceivedRequestWriteHandle

A write handle for a received request.

SentRequestHandle

A handle for a sent request.

SentRequestWriteHandle

A write handle for a sent request.

StreamBody

The body of a stream message.

StreamConfig

Configuration for a byte-stream transport.

UnixBody

Body for the unix tranport.

UnixConfig

Configuration for Unix datagram transports.

Enums

MessageType

The type of a message.

ParseUpdateError

The received update is unknown or invalid.

ReceivedMessage

An incoming request or stream message.

RecvMessageError

Error that can occur when receiving a message from a peer using a generated interface.

Constants

HEADER_LEN

The encoded length of a message header.

MAX_PAYLOAD_LEN

The maximum length of a message body.

Traits

Body

Trait for types that can be used as message body.

ListeningSocket

Helper trait for Listener.

Type Aliases

TcpListener

Listener for TCP sockets.

TcpPeer

Peer using the TCP transport.

TcpTransport

Message transport for TCP.

UnixSeqpacketListener

Listener for Unix seqpacket sockets.

UnixSeqpacketPeer

Peer using the Unix seqpacket transport.

UnixSeqpacketTransport

Message transport for Unix seqpacket sockets.

UnixStreamListener

Listener for Unix stream sockets.

UnixStreamPeer

Peer using the Unix stream transport.

UnixStreamTransport

Message transport for Unix stream sockets.