Crate toy_rpc[−][src]
A async RPC crate that mimics the 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 come with reflection built-in, attribute macros are used to make certain
methods as if they were “exported”.
Content
Breaking Changes
The most recent breaking changes will be reflected here. Change logs can be found in Change Log.
0.6.0
Breaking Changes
- In short, this update makes the crate resemble closer to the usage of
go
’snet/rpc
package - Service registration is simplified to
Server::builder().register(foo_service).build()
. The examples will be updated accordingly. Thusservice!()
macro will be deprecatedregister
function now takes only one argument, which is the instance of the service- on the client side, the service name will just be the name of the struct. for example,
to call a RPC method on
struct Foo { }
service, the client simply uses.async_call("Foo.<method>").await
where<method>
should be replaced with the RPC method - you can still register multiple services on the same server. However, only one object of the same type can be registered on the same server. Multiple servers are needed to have multiple objects of the same type.
- Re-defined the custom
Error
type
Non-breaking changes
- Fixed bug where client does not interpret error message correctly
- Fixed bug with
accept_websocket
crashes with incorrect protocol
Crate Feature Flags
The feature flags can be put into two categories.
Choice of serialization/deserialzation
serde_bincode
: the default codec will usebincode
for serialization/deserializationserde_json
: the default codec will useserde_json
forjson
serialization/deserializationserde_cbor
: the default codec will useserde_cbor
for serialization/deserializationserde_rmp
: the default codec will usermp-serde
for serialization/deserialization
Choice of runtime
async_std_runtime
: supports usage withasync-std
tokio_runtime
: supports usage withtokio
http_tide
: enablestide
integration on the server side. This also enablesasync_std_runtime
http_actix_web
: enablesactix-web
integration on the server side. This also enablestokio_runtime
http_warp
: enables integration withwarp
on the server side. This also enablestokio_runtime
Other trivial feature flags are listed below, and they are likely of no actual usage for you.
docs
std
:serde/std
. There is no actual usage right now.
Default Features
[features]
default = [
"serde_bincode",
"async_std_runtime"
]
Documentation
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 the name of the type of the object.
After the registration, the “exported” methods will be accessible remotely.
A server may register multiple objects (services) of different types but
may not register multiple objects of the same type.
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. Please note that the service name and method name is case
sensitive (ie. the “exported” service and method in the example below can be remotely
accessed via "ExampleService.exported_method"
).
use toy_rpc::macros::export_impl; struct ExampleService { } #[export_impl] impl ExampleService { #[export_method] async fn exported_method(&self, args: ()) -> Result<String, String> { Ok("This is an exported method".to_string()) } 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
-
the method resides in an impl block marked with
#[export_impl]
-
the method is marked with
#[export_method]
attribute -
the method takes one argument other than
&self
and returns aResult<T, E>
- the argument must implement trait
serde::Deserialize
- the
Ok
typeT
of the result must implement traitserde::Serialize
- the
Err
typeE
of the result must implement traitToString
- the argument must implement trait
-
the method is essentially in the form
struct Service { } #[export_impl] impl Service { #[export_method] async fn method_name(&self, args: Req) -> Result<Res, ErrorMsg> where Req: serde::Deserialize, Res: serde::Serialize, ErrorMsg: ToString, { unimplemented!() } }
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 represents 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 TcpListener
and call accept
. HTTP integration is accomplished with WebSocket and currently
supports actix-web
, warp
, and tide
.
A client wishing to use the service establishes a 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
the service and method name is case sensitive, and following Rust’s naming convention,
the service name should be in CamelCase, for example, if a service is defined as pub struct FooBar {}
,
the client needs to use async_call("FooBar.echo").await
to make the remote call.
call
method is synchronous and waits for the remote call to complete and then returns the result in a blocking manner.async_call
is theasync
versions ofcall
andcall_http
, respectively. Because they areasync
functions, they must be called with.await
to be executed.spawn_task
method spawns anasync
task and returns aJoinHandle
. The result can be obtained using theJoinHandle
. Please note thatasync_std::task::JoinHandle
andtokio::task::JoinHandle
behave slightly differently. Executing.await
onasync_std::task::JoinHandle
returnsResult<Res, toy_rpc::error::Error>
. However, executing.await
ontokio::task::JoinHandle
returns `Result<Result<Res, toy_rpc::Error>, tokio::task::JoinError>.- A client stub trait is generated automatically which allows usage such as
client.foo_bar().echo("data").await
wherefoo_bar()
represents a call to theFooBar{}
service whileecho()
represents the RPC method for theFooBar{}
service. More details can be found below
Unless 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 marshal/unmarshal data.
async-std
and tokio
Starting 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
).
HTTP integrations
Similar to choosing the runtimes, toy-rpc
supports integration with actix-web
, tide
,
and warp
by choosing the corresponding feature flag (http_actix_web
, http_tide
,
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 now based on async_tungstenite
.
Please note that toy-rpc
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.
Client Stub
The #[export_impl]
macro now also generates client stubs that internally uses async_call
.
For example, if the Example {}
service is registered on the server with the echo(&self, arg: u32)
method.
If you want to call the echo()
RPC method on the Example {}
service, you
can conveniently use client.example().echo(3).await.unwrap()
. The generated stub follows the
snake case, for example
- if a service is defined as pub struct Foo {}
, the generated stub will be foo()
- if a service is defined as pub struct FooBar {}
, the generated stub will be foo_bar()
- if a service is defined asx pub struct FooBarService {}
, the generated stub will be foo_bar_service()
pub mod rpc { use toy_rpc::macros::export_impl; use serde::{Serialize, Deserialze}; pub struct Example { } #[export_impl] impl Example { pub async fn echo(&self, arg: u32) -> Result<u32, String> { Ok(arg) } } } // import everything from the `rpc` mod to include the generated client stub use rpc::*; #[async_std::main] async fn main() { let addr = "127.0.0.1:23333"; let client = Client::dial(addr).await.unwrap(); // The generated client stub will provide a function `example()` // for convenience. // The line below is equivalent to `let reply = client.async_call("Example.echo", 3).await.unwrap();` let reply = client.example().echo(3).await.unwrap(); println!("Reply: {}", reply); }
Examples
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
[dependencies]
# you may need to change feature flags for different examples
toy-rpc = { version = "0.6.0" }
# optional depending on the choice of runtime or http framework for different examples
async-std = { version = "1.9.0", features = ["attributes"] }
tokio = { version = "1.4.0", features = ["rt", "rt-multi-thread", "macros", "net", "sync"] }
tide = "0.16.0"
actix-web = "3.3.2"
warp = "0.3.0"
# other dependencies needed for the examples here
async-trait = "0.1.42"
env_logger = "0.8.2"
log = "0.4.14"
serde = { version = "1.0.123", features = ["derive"] }
Example Service Definition
pub mod rpc { use serde::{Serialize, Deserialize}; use toy_rpc::macros::export_impl; use async_trait::async_trait; // uncomment the line below for the examples that use tokio runtime // use tokio::sync::Mutex; // uncomment the line below for the examples that use async-std runtime // use async_std::sync::Mutex; 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] trait Rpc { async fn echo(&self, req: ExampleRequest) -> Result<ExampleResponse, String>; } #[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) } } }
RPC over TCP with async-std
This 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
use async_std::net::TcpListener; use async_std::sync::{Arc, Mutex}; use async_std::task; use toy_rpc::macros::service; use toy_rpc::Server; use crate::rpc; // assume the rpc module can be found here #[async_std::main] 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`service!()` macro is no longer needed let server = Server::builder() .register(example_service) .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
use toy_rpc::Client; use toy_rpc::error::Error; // import everything from the `rpc` mod to include generated client stub use crate::rpc::*; // assume the rpc module can be found here #[async_std::main] async fn main() { let addr = "127.0.0.1:8080"; let client = Client::dial(addr).await.unwrap(); let args = ExampleRequest{a: 1}; // Use synchronous call let reply: Result<rpc::ExampleResponse, Error> = client.call("Example.echo", &args); println!("{:?}", reply); // or use the generated client stub for `ExampleService` let reply = client.example_service().echo(&args).await; println!("{:?}", reply); client.close().await; }
RPC over TCP with tokio
This 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.
[dependencies] toy_rpc = { version = "0.6.0", default-features = false, features = ["serde_bincode", "tokio_runtime"] }
server.rs
use std::sync::Arc; use tokio::net::TcpListener; use tokio::sync::Mutex; use tokio::task; use toy_rpc::macros::service; use toy_rpc::Server; use crate::rpc; // assume the rpc module can be found here #[tokio::main] 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) .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
use toy_rpc::Client; use toy_rpc::error::Error; // import everything from the `rpc` mod to include generated client stub use crate::rpc::*; // assume the rpc module can be found here #[tokio::main] async fn main() { let addr = "127.0.0.1:8080"; let client = Client::dial(addr).await.unwrap(); let args = rpc::ExampleRequest{a: 1}; // Use synchronous call let reply: Result<rpc::ExampleResponse, Error> = client.call("Example.echo", &args); println!("{:?}", reply); // or use the generated client stub for `ExampleService` let reply = client.example_service().echo(&args).await; println!("{:?}", reply); client.close().await; client.close().await; }
HTTP integration with tide
This 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.
toy_rpc = { version = "0.6.0", default-features = false, features = ["serde_bincode", "http_tide"] }
server.rs
use async_std::sync::{Arc, Mutex}; use toy_rpc::macros::service; use toy_rpc::Server; use crate::rpc; // assume the rpc module can be found here #[async_std::main] 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) .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(()) }
HTTP integration with actix-web
This 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.
toy_rpc = { version = "0.6.0", default-features = false, features = ["serde_bincode", "http_actix_web"] }
server.rs
use std::sync::Arc; use tokio::sync::Mutex; use actix_web::{App, HttpServer, web}; use toy_rpc::macros::service; use toy_rpc::Server; use crate::rpc; // assume the rpc module can be found here #[actix_web::main] 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) .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 }
HTTP integration with warp
This 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.
toy_rpc = { version = "0.6.0", default-features = false, features = ["serde_bincode", "http_warp"] }
server.rs
use warp::Filter; use std::sync::Arc; use tokio::sync::Mutex; use toy_rpc::macros::service; use toy_rpc::Server; use crate::rpc; // assume the rpc module can be found here #[tokio::main] async fn main() { env_logger::init(); let example_service = Arc::new( rpc::ExampleService { counter: Mutex::new(0), } ); let server = Server::builder() .register(example_service) .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; }
RPC client for HTTP
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.
use toy_rpc::Client; use toy_rpc::error::Error; use crate::rpc; // assume the rpc module can be found here // choose the runtime attribute accordingly //#[tokio::main] #[async_std::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}; // Use synchronous call let reply: Result<rpc::ExampleResponse, Error> = client.call("Example.echo", &args); println!("{:?}", reply); // or use the generated client stub for `ExampleService` let reply = client.example_service().echo(&args).await; println!("{:?}", reply); client.close().await; }
Change Log
0.6.0
Breaking Changes
- In short, this update makes the crate resemble closer to the usage of
go
’snet/rpc
package - Service registration is simplified to
Server::builder().register(foo_service).build()
. The examples will be updated accordingly. Thusservice!()
macro will be deprecatedregister
function now takes only one argument, which is the instance of the service- on the client side, the service name will just be the name of the struct. for example,
to call a RPC method on
struct Foo { }
service, the client simply uses.async_call("Foo.<method>").await
where<method>
should be replaced with the RPC method - you can still register multiple services on the same server. However, only one object of the same type can be registered on the same server. Multiple servers are needed to have multiple objects of the same type.
- Re-defined the custom
Error
type
Non-breaking changes
- Fixed bug where client does not interpret error message correctly
- Fixed bug with
accept_websocket
crashes with incorrect protocol
0.5.4
- Handlers are now stored as a
fn
pointer as opposed to a trait object.
0.5.3
- The
#[export_impl]
macro now generates client stub functions by generating a new trait fortoy_rpc::Client
.
0.5.0
Breaking changes
- HTTP integration is now accomplished using WebSocket with
async_tungstenite
, and thus HTTP connections of versions <0.5.0 are not compatible with versions >=0.5.0. - The custom binary transport protocol now includes a magic byte at the beginning, making versions <0.5.0 NOT compatible with versions >= 0.5.0;
toy_rpc::error::Error
changed from struct-like variants to simple enum variants- Changes to feature flags
- “logging” feature flag is removed
- “surf” feature flag is removed
- “tide” is changed to “http_tide”
- “actix-web” is changed to “http_actix_web”
- added “http_warp” feature flag
- added “async_std_runtime”
- added “tokio_runtime”
Non-breaking changes
- Removed
Stream
andSink
impl from the custom binary transport protocolFrame
0.4.5
- Added
Sink
implementation for the custom binary transport protocolFrame
0.4.4
- Modified traits
CodecRead
,CodecWrite
,ServerCodec
,ClientCodec
to no longer return number of bytes written - The number of bytes written for header and body will be logged separately
0.4.3
- Removed previously unused NoneError
- Unified
call
,async_call
andspawn_task
for socket client and HTTP client. Thecall_http
,async_call_http
, andspawn_task_http
methods are kept for compatibility.
0.4.2
- Temporary fix of
spawn_task()
andspawn_task_http()
withArc<Mutex<_>>
until lifetime with async task is figured out. As a result,Client
no longer needs to be declaredmut
.
0.4.1
- Updated documentation
0.4.0
- Added
actix-web
feature flag to support integration withactix-web
0.3.1
- Added
serde_rmp
features flag - Updated and corrected examples in the documentation
0.3.0
- Added
serde_cbor
feature flag - Changed
bincode
feature flag toserde_bincode
Future Plan
The following items are in no particular order.
- improve error handling (sort of done)
- improve documentation
- improve logging message
- support other I/O connection
- more tests
Re-exports
pub use server::Server; |
pub use server::ServerBuilder; |
pub use crate::client::async_std::Client; |
pub use error::Error; |
pub use serde; |
pub use erased_serde; |
pub use lazy_static; |
Modules
client | There are two |
codec |
|
error | Custom errors |
macros | Re-export of proc_macros defined in |
message | Custom definition of rpc request and response headers |
server | RPC server. There is only one |
service | Service builder and registration |
transport | Custom binary transport and WebSocket integration |
util |