Crate toy_rpc[−][src]
Expand description
An async RPC crate that mimics the golang
’s net/rpc
package and supports both async-std
and tokio
.
This project is still being actively developed. I have kind of run out of ideas for features, so feel free to let me know if there is a feature that you want.
toy-rpc
aims to be an easy-to-use async RPC tool that is inspired by golang’s net/rpc
’s API.
It supports both async_std
and tokio
runtimes over either TCP or TLS. Integration with
common HTTP server frameworks such as actix_web
, warp
and tide
are provided.
The overall usage and API should feel similar to that of the golang’s net/rpc
package. Some of the names are changed
to make them sound more “rusty”. Because rust does not come with runtime reflection, attribute macros #[export_impl]
and #[export_trait]
/ #[export_trait_impl]
, and attribute #[export_method]
are used to mark functions “exported” in golang’s
net/rpc
perspective.
More detailed usage can be found in the book and documentation.
- Book
- Quickstart
- Documentation
- Change Log
- GitHub repository
- crate.io
- Minimum supported Rust version: 1.53 or later
This crate uses #![forbid(unsafe_code)]
to ensure no usage of unsafe
in the crate.
Feature flags
The feature flags can be put into three categories.
Choice of runtime and HTTP framework integration
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
andws_async_std
http_actix_web
: enablesactix-web
integration on the server side. This also enablestokio_runtime
andws_tokio
http_warp
: enables integration withwarp
on the server side. This also enablestokio_runtime
andws_tokio
http_axum
: enables integration withaxum
on the server side. This also enablestokio_runtime
andws_tokio
Choice of RPC server or client (both can be enabled at the same time)
server
: enables RPC serverclient
: enables RPC client
Choice of serialization/deserialzation (only one should be enabled at a time)
serde_bincode
: (default) 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
WebSocket support (HTTP integration is implementd with WebSocket)
ws_tokio
: enables WebSocket and HTTP integrations withtokio
. This must be enabled for client to usedial_http(addr)
ordial_websocket(addr)
.ws_async_std
: enables WebSocket and HTTP integrations withasync-std
. This must be enabled for client to usedial_http(addr)
ordial_websocket(addr)
.
TLS support
tls
: enables TLS support
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.
By default, only serde_bincode
feature is enabled.
You must enable at least one runtime feature flag and the server
and/or client
to have something usable.
Default features
default = ["serde_bincode"]
Integration
HTTP integration is provided for actix-web
, tide
, and warp
. More details can be found
in the Book/Integrations and in
examples.
Quickstart Example
A quickstart example with tokio
runtime is provided in the Book/Quickstart.
Re-exports
pub use client::Client;
pub use server::builder::ServerBuilder;
pub use server::Server;
pub use error::Error;
pub use erased_serde;
pub use serde;
Modules
client
RPC Client impementation
SplittibleCodec
is defined in this module, and they are implemented
for the DefaultCodec
Default codec implementations are feature gated behind the following features
serde_bincode
, serde_json
, serde_cbor
, serde_rmp
.
Custom errors
Re-export of proc_macros defined in toy_rpc_macros
ErrorMessage from server to client
Message protocol between server and client
PubSub support
server
RPC server. There is only one Server
defined, but some methods have
different implementations depending on the runtime feature flag
Service builder and registration
Custom binary transport and WebSocket integration
Utility traits and functions.
Constants
http_actix_web
or http_warp
or http_tide
or http_axum
or client
The default path added to the HTTP url
Type Definitions
Type alias for std::result::Result<T, toy_rpc::error::Error>