Expand description
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 theTcpTransport
unix-stream
: for theUnixStreamTransport
unix-seqpacket
: for theUnixSeqpacketTransport
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
- Traits for converting between RPC messages and Rust values.
- Example module for the
interface!
macro. - Support types and traits for runtime interface instrospection.
- Well-known service IDs.
- Transport traits and concrete implementations.
- Utility traits.
Macros
- Define an RPC interface.
Structs
- Opaque error for all RPC operations.
- Listener that spawns peers for all accepted connections.
- A complete RPC message, including header and body.
- A message header.
- Peer read/write loop.
- Handle to close the connection with a peer.
- Handle to a peer.
- Handle to receive messages from a peer.
- Handle to send messages to a peer.
- A handle for a received request.
- A write handle for a received request.
- A handle for a sent request.
- A write handle for a sent request.
- The body of a stream message.
- Configuration for a byte-stream transport.
- Body for the unix tranport.
- Configuration for Unix datagram transports.
Enums
- The type of a message.
- The received update is unknown or invalid.
- An incoming request or stream message.
- Error that can occur when receiving a message from a peer using a generated interface.
Constants
- The encoded length of a message header.
- The maximum length of a message body.
Traits
- Trait for types that can be used as message body.
- Helper trait for
Listener
.
Type Aliases
- Listener for TCP sockets.
- Peer using the TCP transport.
- Message transport for TCP.
- Listener for Unix seqpacket sockets.
- Peer using the Unix seqpacket transport.
- Message transport for Unix seqpacket sockets.
- Listener for Unix stream sockets.
- Peer using the Unix stream transport.
- Message transport for Unix stream sockets.