https://github.com/fizyr/fizyr-rpc
Native Rust implementation of the Fizyr RPC protocol
https://github.com/fizyr/fizyr-rpc
hacktoberfest rpc rust shared-memory
Last synced: about 1 month ago
JSON representation
Native Rust implementation of the Fizyr RPC protocol
- Host: GitHub
- URL: https://github.com/fizyr/fizyr-rpc
- Owner: fizyr
- License: apache-2.0
- Created: 2020-09-08T17:08:28.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-12-11T09:41:22.000Z (over 1 year ago)
- Last Synced: 2025-04-09T17:47:22.094Z (about 1 month ago)
- Topics: hacktoberfest, rpc, rust, shared-memory
- Language: Rust
- Homepage:
- Size: 416 KB
- Stars: 9
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
[](https://docs.rs/fizyr-rpc/)
[](https://github.com/fizyr/fizyr-rpc-rs/actions?query=workflow%3Atests+branch%3Amain)
# 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`][transport::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
```rust
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);
```
[`Peer`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/struct.Peer.html
[`Peer::connect()`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/struct.Peer.html#method.connect
[`Peer::run()`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/struct.Peer.html#method.run
[`PeerHandle`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/struct.PeerHandle.html
[`PeerReadHandle`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/struct.PeerReadHandle.html
[`PeerWriteHandle`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/struct.PeerWriteHandle.html
[`Server`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/struct.Server.html
[transport::Transport]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/transport/trait.Transport.html
[`TcpTransport`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/type.TcpTransport.html
[`UnixStreamTransport`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/type.UnixStreamTransport.html
[`UnixSeqpacketTransport`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/type.UnixSeqpacketTransport.html
[`StreamBody`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/struct.StreamBody.html
[`UnixBody`]: https://docs.rs/fizyr-rpc/latest/fizyr_rpc/struct.UnixBody.html