[−][src]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 must first create a Peer
object.
The Peer
object is responsible for reading and writing messages with the peer,
but you can't use it for sending or receiving messages directly.
Instead, you must ensure that the Peer::run()
future is being polled.
The easiest way to do that is by calling Peer::spawn(...)
,
which will run the future in a background task and returns a PeerHandle
.
Server
The Server
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 Server
struct.
There are different transports for different socket types.
Different transports may also use different types as message body.
For example, the [TcpTransport
][TcpTransport] and [UnixStreamTransport
][UnixStreamTransport]
use messages with a [StreamBody
][StreamBody].
This [StreamBody
][StreamBody] body type contains raw bytes.
The [UnixSeqpacketTransport
][UnixSeqpacketTransport] has messages with a [UnixBody
][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
][TcpTransport]unix-stream
: for the [UnixStreamTransport
][UnixStreamTransport]unix-seqpacket
: for the [UnixSeqpacketTransport
][UnixSeqpacketTransport]
Modules
error | Error types. |
service_id | Well-known service IDs. |
Structs
Message | A complete RPC message, including header and body. |
MessageHeader | A message header. |
Peer | Peer read/write loop. |
PeerHandle | Handle to a peer. |
PeerReadHandle | Handle to receive messages from a peer. |
PeerWriteHandle | Handle to send messages to a peer. |
ReceivedRequest | A handle for a received request. |
RequestTracker | Tracker that manages open requests. |
SentRequest | A handle for a sent request. |
Server | Server that spawns peers for all accepted connections. |
Enums
Incoming | An incoming request or stream message. |
MessageType | The type of a message. |
Outgoing | An outgoing request or stream message. |
Constants
HEADER_LEN | The encoded length of a message header (excluding the frame size). |
MAX_PAYLOAD_LEN | The maximum length of a message body. |
Traits
Body | Trait for types that can be used as message body. |
IntoTransport | Trait to allow generic creation of transports from a socket. |
ServerListener | Helper trait for |
Transport | Trait for types that represent a bi-direction message transport. |
TransportReadHalf | Trait for the read half of a transport type. |
TransportWriteHalf | Trait for transport types that you can write message to. |