tarpc: Tim & Adam's RPC lib
Disclaimer: This is not an official Google product.
tarpc is an RPC framework for rust with a focus on ease of use. Defining a service can be done in just a few lines of code, and most of the boilerplate of writing a server is taken care of for you.
What is an RPC framework?
"RPC" stands for "Remote Procedure Call," a function call where the work of producing the return value is being done somewhere else. When an rpc function is invoked, behind the scenes the function contacts some other process somewhere and asks them to evaluate the function instead. The original function then returns the value produced by the other process.
tarpc differentiates itself from other RPC frameworks by defining the schema in code, rather than in a separate language such as .proto. This means there's no separate compilation process, and no cognitive context switching between different languages. Additionally, it works with the community-backed library serde: any serde-serializable type can be used as arguments to tarpc fns.
NB: this example is for master. Are you looking for other versions?
Add to your
= "0.9.0" = "0.2.0"
tarpc has two APIs:
sync for blocking code and
future for asynchronous
code. Here's how to use the sync api.
extern crate tarpc; use mpsc; use thread; use ; use ClientExt; use ; service! ;
service! macro expands to a collection of items that form an
rpc service. In the above example, the macro is called within the
hello_service module. This module will contain
FutureClient types, and
AsyncService traits. There is
ServiceExt trait that provides starter
fns for services, with an
umbrella impl for all services. These generated types make it easy and
ergonomic to write servers without dealing with sockets or serialization
directly. Simply implement one of the generated traits, and you're off to the
races! See the
tarpc_examples package for more examples.
Here's the same service, implemented using futures.
extern crate futures; extern crate tarpc; extern crate tokio_core; use Future; use ; use ClientExt; use ; use reactor; service! ;
Example: Futures + TLS
By default, tarpc internally uses a
TcpStream for communication between your clients and
servers. However, TCP by itself has no encryption. As a result, your communication will be sent in
the clear. If you want your RPC communications to be encrypted, you can choose to use TLS. TLS
operates as an encryption layer on top of TCP. When using TLS, your communication will occur over a
TlsStream<TcpStream>. You can add the ability to make TLS clients and servers by adding
tls feature flag enabled.
When using TLS, some additional information is required. You will need to make
client::tls::Context requires a
TlsConnector types are defined in the native-tls. tarpc re-exports
external TLS-related types in its
native_tls module (
Both TLS streams and TCP streams are supported in the same binary when the
tls feature is enabled.
However, if you are working with both stream types, ensure that you use the TLS clients with TLS
servers and TCP clients with TCP servers.
extern crate futures; extern crate tarpc; extern crate tokio_core; use Future; use ; use ClientExt; use tls; use ; use reactor; use ; service! ;
Sync vs Futures
service! invocation generates code for both synchronous and future-based applications.
It's up to the user whether they want to implement the sync API or the futures API. The sync API has
the simplest programming model, at the cost of some overhead - each RPC is handled in its own
thread. The futures API is based on tokio and can run on any tokio-compatible executor. This mean a
service that implements the futures API for a tarpc service can run on a single thread, avoiding
context switches and the memory overhead of having a thread per RPC.
All generated tarpc RPC methods return either
tarpc::Result<T, E> or something like
Future<T, E>. The error type defaults to
tarpc::util::Never (a wrapper for
! which implements
std::error::Error) if no error type is explicitly specified in the
service! macro invocation. An
error type can be specified like so:
use Message; service!
tarpc::util::Message is just a wrapper around string that implements
for service implementations that don't require complex error handling. The pipe is used as syntax
for specifying the error type in a way that's agnostic of whether the service implementation is
synchronous or future-based. Note that in the simpler examples in the readme, no pipe is used, and
the macro automatically chooses
tarpc::util::Never as the error type.
The above declaration would produce the following synchronous service trait:
and the following future-based trait:
cargo doc as you normally would to see the documentation created for all
items expanded by a
- Concurrent requests from a single client.
- Compatible with tokio services.
- Run any number of clients and services on a single event loop.
- Any type that
Deserializecan be used in rpc signatures.
- Attributes can be specified on rpc methods. These will be included on both the services' trait methods as well as on the clients' stub methods.
Gaps/Potential Improvements (not necessarily actively being worked on)
- Configurable server rate limiting.
- Automatic client retries with exponential backoff when server is busy.
- Load balancing
- Service discovery
- Automatically reconnect on the client side when the connection cuts out.
- Support generic serialization protocols.
To contribute to tarpc, please see CONTRIBUTING.
tarpc is distributed under the terms of the MIT license.
See LICENSE for details.