4 releases
0.3.0 | Jun 25, 2024 |
---|---|
0.2.4 | Jun 24, 2024 |
0.2.3 | Jun 24, 2024 |
0.2.0 | Jun 24, 2024 |
#266 in Procedural macros
98 downloads per month
42KB
577 lines
Eagle
Stability
Eagle is still in early development. Performance is not ideal, the interface is likely to change and the documentation is not final. Basic functionality is fully implemented and works as expected.
What is Eagle?
Eagle is a library which allows you to easily build an RPC protocol.
It uses a macro to generate the required communication code and makes adding new functions easy and quick. Eagle is designed to work specifically with tokio
and uses serde
for formatting data.
Please note that since eagle
is a pure proc-macro library, you must manually add compatible versions of tokio
, serde
, ron
and optionally log
to your dependencies.
Using Eagle
The way that eagle
is designed to be used is inside a shared dependency between your "server" and your "client". Both of these should be in a workspace. Create a shared
crate which both components should depend on, this crate should have eagle
as a dependency. By default eagle
uses TCP for communication, but you may disable default features and enable the unix
feature on eagle
to use unix sockets instead.
Inside this crate, you can define your protocol as an enum:
use eagle::Protocol;
use serde::{Serialize, Deserialize};
#[derive(Clone, Serialize, Deserialize)]
pub struct ExampleStruct {
a: i32,
b: i32
}
#[derive(Protocol)]
pub enum Example {
Addition((i32, i32), i32),
StructuredDataAlsoWorks(ExampleStruct, ()),
SetState(i32, i32),
GetState((), i32)
}
Each variant describes one of the functions that the client can call, the first field on a variant represents the arguments that the client can send and the second field represents the return value. In the example above, the addition
function would take in two [i32
]s and return another [i32
]. Any data passed this way must implement Clone
as well as serde::Serialize
and serde::Deserialize
.
The Protocol
macro will create a number of exports in your shared crate. You will be able to import them by name in your client and server.
Once your protocol is defined, you can implement it on your server. To do so, you must first implement a handler for your
protocol. A handler must implement Clone
as well as the ServerHandler
trait for your protocol. For the above example:
struct ExampleHandler {
state: i32
}
impl ExampleServerHandler for ExampleHandler {
async fn addition(&mut self, a: i32, b: i32) -> i32 {
a + b
}
async fn get_state(&mut self) -> i32 {
self.state
}
async fn set_state(&mut self, state: i32) -> i32 {
self.state = state;
self.state
}
}
Your handler can now be used by the server. You can easily bind your server to a socket with:
use shared::ExampleServer;
let handler = ExampleHandler { state: 0 };
let server_task = ExampleServer::bind(handler, "127.0.0.1:1234").await;
// Or, if you're using the 'unix' feature...
let server_task = ExampleServer::bind(handler, "/tmp/sock").await;
Note that bind is an asynchronous function which should never return, you must put it in a separate task. Once bound, the server will await for connections and start responding to queries.
On the client, all you need to do is to use your protocol's Client
to connect and you can start making requests.
use shared::ExampleClient;
let client = ExampleClient::connect("127.0.0.1:1234").await.unwrap();
assert_eq!(client.addition(5, 2), 7);
License
Eagle is licensed under the AGPL (GNU Affero General Public License). To learn more, read LICENSE.md
Dependencies
~260–700KB
~17K SLoC