Expand description
§Eagle - A simple library for RPC in Rust
Eagle is a library for building RPC protocols in Rust. It uses a macro to transform your protocol definition into the necessary code to allow communication between a server and a client.
Eagle uses tokio
as its async runtime and
ron
for serialization.
§Usage
eagle
is designed to be used to create your own protocol crate. We
recommend creating a new cargo workspace for your project with a shared
crate which will contain your protocol definition and individual crates
for the server and client.
In your shared crate, you can define your protocol using the Protocol
derive macro. This will generate the necessary code for the server and
client to communicate.
use eagle::Protocol;
#[derive(Protocol)]
pub enum Example {
Add((i32, i32), i32),
Length(String, usize),
/* ... */
}
The Protocol
derive macro will generate all the necessary code, including
your handler trait, your server struct, and your client struct.
On your server, you will need to implement the handler trait. This trait describes the functions that the client can request from the server.
#[derive(Clone)]
pub struct Handler;
impl ExampleServerHandler for Handler {
async fn add(&mut self, a: i32, b: i32) -> i32 {
a + b
}
async fn length(&mut self, s: String) -> usize {
s.len()
}
/* ... */
}
To start the server, you simply need to use the generated server struct and pass it your handler.
let handler = Handler;
let address = "127.0.0.1:12345"; // Or, if using the 'unix' feature, "/tmp/eagle.sock"
let server = ExampleServer::bind(handler, address).await;
server.close().await;
Once bound, the server will begin listening for incoming connections and
queries. You must remember to use the close
method to shut down the server.
On the client side, you can simply use the generated client struct to connect to the server and begin sending queries.
let address = "127.0.0.1:12345"; // Or, if using the 'unix' feature, "/tmp/eagle.sock"
let client = ExampleClient::connect(address).await.unwrap();
assert_eq!(client.add(2, 5).await.unwrap(), 7);
The client can be closed by calling the close
method on the client struct.
This will abort the connection.
Derive Macros§
- Protocol
- Generate all the necessary RPC code for a protocol from an enum describing it.