Crate eagle

Source
Expand description

§Eagle - A simple library for RPC in Rust

Eagle is still in early development. This documentation is subject to change and may not be entirely accurate.

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.