golang's net/rpc package and supports both async-std and tokio.This crate aims at providing an easy-to-use RPC that is similar to golang's
net/rpc.
The usage is similar to that of golang's net/rpc with functions sharing similar
names and functionalities. Certain function names are changed to be more "rusty".
Because rust doesn't have reflection, attribute macros are used to make certain
method "exported".
The most recent breaking changes will be reflected here.
async_tungstenite, and thus HTTP connections
of versions <0.5.0 are **NOT** compatible with versions >=0.5.0.toy_rpc::error::Error changed from struct-like variants to simply enum variantslog for logging (eg. env_logger).The feature flags can be put into two categories.
Choice of serialization/deserialzation
serde_bincode: the default codec will use bincode
for serialization/deserializationserde_json: the default codec will use serde_json
for json serialization/deserializationserde_cbor: the default codec will use serde_cbor
for serialization/deserializationserde_rmp: the default codec will use rmp-serde
for serialization/deserializationChoice of runtime
async_std_runtime: supports usage with async-stdtokio_runtime: supports usage with tokiohttp_tide: enables tide integration on the server side. This also enables async_std_runtimehttp_actix_web: enables actix-web integration on the server side. This also enables tokio_runtimehttp_warp: enables integration with warp on the server side. This also enables tokio_runtimeOther trivial feature flags are listed below, and they are likely of no actual usage for you.
docsstd: serde/std. There is no actual usage right now.toml
[features]
default = [
"serde_bincode",
"async_std_runtime"
]
The following documentation is adapted based on golang's documentation.
This crate provides access to the methods marked with #[export_impl]
and #[export_method] of an object across a network connection. A server
registers an object, making it visible as a service with a name provided by the user.
After the registration, the "exported" methods will be accessible remotely.
A server may register multiple objects as multiple services, and multiple
objects of the same type or different types could be registered on the same
Server object.
To export a method, use #[export_method] attribute in an impl block marked with
#[export_impl] attribute. This crate currently only support using #[export_impl] attribute
on one impl block per type.
```rust struct ExampleService { }
impl ExampleService {
#[exportmethod]
async fn exportedmethod(&self, args: ()) -> Result
async fn not_exported_method(&self, args: ()) -> Result<String, String> {
Ok("This method is NOT exported".to_string())
}
} ```
The methods to export must meet the following criteria on the server side
#[export_impl]#[export_method] attributethe method takes one argument other than &self and returns a Result<T, E>
serde::DeserializeOk type T of the result must implement trait serde::SerializeErr type E of the result must implement trait ToStringthe method is essentially in the form
```rust struct ServiceState { }
impl ServiceState {
#[exportmethod]
async fn methodname(&self, args: Req) -> Result
Req and Res are marshaled/unmarshaled (serialized/deserialized) by serde.
Realistically the Req and Res type must also be marshaled/unmarshaled on
the client side, and thus Req and Res must both implement both
serde::Serialize and serde::Deserialize.
The method's argument reprements the argument provided by the client caller,
and the Ok type of result represents success parameters to be returned to
the client caller. The Err type of result is passed back to the client as
a String.
The server may handle requests on a single connection by calling serve_conn,
and it may handle multiple connections by creating a async_std::net::TcpListener
and call accept. Integration with HTTP currently only supports tide by calling
into_endpoint.
A client wishing to use the service establishes a async_std::net::TcpStream connection
and then creates Client over the connection. The convenience function dial performs
this step for raw TCP socket connection, and dial_http performs this for an HTTP
connection. A Client with HTTP connection or socket connection has three methods, call, async_call,
and spawn_task, to specify the service and method to call and the argument.
Please note that call_http, async_call_http and spawn_task_http are becoming deprecated
as the same API now can be called for both a socket client and an HTTP client.
call method is synchronous and waits for the remote call
to complete and then returns the result in a blocking manner.async_call is the async versions of call and call_http,
respectively. Because they are async functions, they must be called with .await to
be executed.spawn_task method spawns an async task and returns a JoinHandle.
The result can be obtained using the JoinHandle. Please note that
async_std::task::JoinHandle and tokio::task::JoinHandle behave slightly different.
Executing .await on async_std::task::JoinHandle returns Result<Res, toy_rpc::error::Error>.
However, executing .await on tokio::task::JoinHandle returns
`ResultUnless an explicity codec is set up (with serve_codec method, HTTP is NOT supported yet),
the default codec specified by one of the following features tags (serde_bincode, serde_json
serde_cbor, serde_rmp) will be used to transport data.
async-std and tokioStarting from version 0.5.0-beta.2, you can use toy-rpc with either runtime by choosing
the corresponding feature flag (async_std_runtime, tokio_runtime).
Similar to choosing the runtimes, toy-rpc supports integration with actix-web, tide,
and warp by choosing the corresponding feature flag (http_tide, http_actix_web
http_warp). Starting from version 0.5.0-beta.0 the integration is implemented using
WebSocket as the transport protocol, and the DEFAULT_RPC_SERVER=_rpc_ is appended to the path you
supply to the HTTP framework. The client side support is not based on async_tungstenite
and removed usage of surf. Thus versions >=0.5.0-beta.0 are NOT compatible
with versions <0.5.0-beta.0. The examples below are also updated to reflect
the changes.
A few simple examples are shown below. More examples can be found in the examples
directory in the repo. All examples here will assume the follwing
RPC service definition below.
The examples here will also need some other dependencies
```toml [dependencies]
toy-rpc = { version = "0.5.0" }
async-std = { version = "1.9.0", features = ["attributes"] } tokio = { version = "1.2.0", features = ["rt", "rt-multi-thread", "macros", "net", "sync"] } tide = "0.16.0" actix-web = "3.3.2" warp = "0.3.0"
async-trait = "0.1.42" env_logger = "0.8.2" log = "0.4.14" serde = { version = "1.0.123", features = ["derive"] }
```
```rust pub mod rpc { use serde::{Serialize, Deserialize}; use toyrpc::macros::exportimpl;
// use tokio::sync::Mutex; // uncomment this for the examples that use tokio runtim
// use async_std::sync::Mutex; // uncomment this for the examples that use async-std runtime
pub struct ExampleService {
pub counter: Mutex<i32>
}
#[derive(Debug, Serialize, Deserialize)]
pub struct ExampleRequest {
pub a: u32,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct ExampleResponse {
a: u32,
}
#[async_trait::async_trait]
trait Rpc {
async fn echo(&self, req: ExampleRequest) -> Result<ExampleResponse, String>;
}
#[async_trait::async_trait]
#[export_impl]
impl Rpc for ExampleService {
#[export_method]
async fn echo(&self, req: ExampleRequest) -> Result<ExampleResponse, String> {
let mut counter = self.counter.lock().await;
*counter += 1;
let res = ExampleResponse{ a: req.a };
Ok(res)
}
}
} ```
async-stdThis example will assume the RPC service defined above,
and you may need to uncomment the line use async_std::sync::Mutex; in the RPC service definition
for this example.
The default feature flags will work with the example below.
server.rs
```rust use asyncstd::net::TcpListener; use asyncstd::sync::{Arc, Mutex}; use asyncstd::task; use toyrpc::macros::service; use toy_rpc::Server;
use crate::rpc; // assume the rpc module can be found here
async fn main() { env_logger::init();
let addr = "127.0.0.1:8080";
let example_service = Arc::new(
rpc::ExampleService {
counter: Mutex::new(0),
}
);
// notice that the second argument in `service!()` macro is a path
let server = Server::builder()
.register("example", service!(example_service, rpc::ExampleService))
.build();
let listener = TcpListener::bind(addr).await.unwrap();
println!("Starting listener at {}", &addr);
let handle = task::spawn(async move {
server.accept(listener).await.unwrap();
});
handle.await;
} ```
client.rs
```rust use toyrpc::Client; use toyrpc::error::Error;
use crate::rpc; // assume the rpc module can be found here
async fn main() { let addr = "127.0.0.1:8080"; let client = Client::dial(addr).await.unwrap();
let args = rpc::ExampleRequest{a: 1};
let reply: Result<rpc::ExampleResponse, Error> = client.call("example.echo", &args);
println!("{:?}", reply);
client.close().await;
} ```
tokioThis example will assume the RPC service defined above
and you may need to uncomment the line use tokio::sync::Mutex; in the RPC service definition
for this example.
The default feature flags will NOT work for this example, and you need to change the feature flags.
rust
[dependencies]
toy_rpc = { version = "0.5.0", default-features = false, features = ["serde_bincode", "tokio_runtime"] }
server.rs
```rust use std::sync::Arc; use tokio::net::TcpListener; use tokio::sync::Mutex; use tokio::task; use toyrpc::macros::service; use toyrpc::Server;
use crate::rpc; // assume the rpc module can be found here
async fn main() { env_logger::init();
let addr = "127.0.0.1:8080";
let example_service = Arc::new(
rpc::ExampleService {
counter: Mutex::new(0),
}
);
// notice that the second argument in `service!()` macro is a path
let server = Server::builder()
.register("example", service!(example_service, rpc::ExampleService))
.build();
let listener = TcpListener::bind(addr).await.unwrap();
println!("Starting listener at {}", &addr);
let handle = task::spawn(async move {
server.accept(listener).await.unwrap();
});
// tokio JoinHandle returns an extra result
handle.await.unwrap();
} ```
client.rs
```rust use toyrpc::Client; use toyrpc::error::Error;
use crate::rpc; // assume the rpc module can be found here
async fn main() { let addr = "127.0.0.1:8080"; let client = Client::dial(addr).await.unwrap();
let args = rpc::ExampleRequest{a: 1};
let reply: Result<rpc::ExampleResponse, Error> = client.call("example.echo", &args);
println!("{:?}", reply);
client.close().await;
} ```
tideThis example will assume the RPC service defined above
and you may need to uncomment the line use async_std::sync::Mutex; in the RPC service definition
for this example.
An example client to use with HTTP can be found in a separate example here. The default feature flags will NOT work with this example, and you need to change the feature flags.
toml
toy_rpc = { version = "0.5.0", default-features = false, features = ["serde_bincode", "http_tide"] }
server.rs
```rust use asyncstd::sync::{Arc, Mutex}; use toyrpc::macros::service; use toy_rpc::Server;
use crate::rpc; // assume the rpc module can be found here
async fn main() -> tide::Result<()> { env_logger::init();
let addr = "127.0.0.1:8080";
let example_service = Arc::new(
rpc::ExampleService {
counter: Mutex::new(0),
}
);
let server = Server::builder()
.register("example", service!(example_service, rpc::ExampleService))
.build();
let mut app = tide::new();
app.at("/rpc/").nest(server.handle_http());
// with `http_tide`, the line above can also be replaced with the line below
//app.at("/rpc/").nest(server.into_endpoint());
app.listen(addr).await?;
Ok(())
}
```
actix-webThis example will assume the RPC service defined above
and you may need to uncomment the line use tokio::sync::Mutex; in the RPC service definition
for this example.
An example client to use with HTTP can be found in a another example here. The default feature flags will NOT work with this example, and you need to change the feature flags.
toml
toy_rpc = { version = "0.5.0", default-features = false, features = ["serde_bincode", "http_actix_web"] }
server.rs
```rust use std::sync::Arc; use tokio::sync::Mutex; use actixweb::{App, HttpServer, web}; use toyrpc::macros::service; use toy_rpc::Server;
use crate::rpc; // assume the rpc module can be found here
async fn main() -> std::io::Result<()> { env_logger::init();
let addr = "127.0.0.1:8080";
let example_service = Arc::new(
rpc::ExampleService {
counter: Mutex::new(0),
}
);
let server = Server::builder()
.register("example", service!(example_service, rpc::ExampleService))
.build();
let app_data = web::Data::new(server);
HttpServer::new(
move || {
App::new()
.service(
web::scope("/rpc/")
.app_data(app_data.clone())
.configure(Server::handle_http())
// with `http_actix_web`, the line above can also be replaced with the line below
//.configure(Server::scope_config)
)
}
)
.bind(addr)?
.run()
.await
}
```
warpThis example will assume the RPC service defined above
and you may need to uncomment the line use tokio::sync::Mutex; in the RPC service definition
for this example.
An example client to use with HTTP can be found in a another example here. The default feature flags will NOT work with this example, and you need to change the feature flags.
toml
toy_rpc = { version = "0.5.0", default-features = false, features = ["serde_bincode", "http_warp"] }
server.rs
```rust use warp::Filter; use std::sync::Arc; use tokio::sync::Mutex; use toyrpc::macros::service; use toyrpc::Server;
use crate::rpc; // assume the rpc module can be found here
async fn main() { envlogger::init(); let exampleservice = Arc::new( rpc::ExampleService { counter: Mutex::new(0), } );
let server = Server::builder()
.register("example", service!(example_service, rpc::ExampleService))
.build();
let routes = warp::path("rpc")
.and(server.handle_http());
// RPC will be served at "ws://127.0.0.1:8080/rpc/_rpc_"
warp::serve(routes).run(([127, 0, 0, 1], 8080)).await;
}
```
This example will assume the RPC service defined above. The default feature flags will work with this example. However, you may also use client with any runtime or http feature flag.
All HTTP examples assumes that the RPC server is found at "127.0.0.1/rpc/" endpoint.
```rust use toyrpc::Client; use toyrpc::error::Error;
use crate::rpc; // assume the rpc module can be found here
// choose the runtime attribute accordingly //#[tokio::main]
async fn main() { // note that the url scheme is "ws" let addr = "ws://127.0.0.1:8080/rpc/"; let client = Client::dial_http(addr).await.unwrap();
let args = rpc::ExampleRequest{a: 1};
let reply: Result<rpc::ExampleResponse, Error> = client.call("example.echo", &args);
println!("{:?}", reply);
client.close().await;
} ```
Breaking changes
async_tungstenite, and thus HTTP connections
of versions <0.5.0 are not compatible with versions >=0.5.0.toy_rpc::error::Error changed from struct-like variants to simple enum variantsNon-breaking changes
Stream and Sink impl from the custom binary transport protocol FrameSink implementation for the custom binary transport protocol FrameCodecRead, CodecWrite, ServerCodec, ClientCodec to no longer
return number of bytes writtencall, async_call and spawn_task for socket client
and HTTP client. The call_http, async_call_http, and spawn_task_http
methods are kept for compatibility.spawn_task() and spawn_task_http() with Arc<Mutex<_>> until
lifetime with async task is figured out. As a result, Client no longer needs to be declared mut.actix-web feature flag to support integration with actix-webserde_rmp features flagserde_cbor feature flagbincode feature flag to serde_bincodeThe following items are in no particulars order.
License: MIT/Apache-2.0