be5f55c5f6
* Extend snake_to_camel plugin to replace {} in the doc string with the origin snake-cased ident.
Also, track tokio-rs master.
This is really ad-hoc, undiscoverable, and unintuitive, but there's no way to programmatically create doc strings
in regular code, and I want to produce better doc strings for the associated types.
Given `fn foo_bar`:
Before: `/// The type of future returned by the function of the same name.`
After: ``/// The type of future returned by `{}`.``
=> `/// The type of future returned by foo_bar.`
* Fix some docs
* Use a helper fn on pipeline::Frame instead of handrolled match.
* Don't hide docs for ClientFuture.
It's exposed in the Connect impl of FutureService -- the tradeoff for not generating *another* item -- and hiding it breaks doc links.
* Formatting
* Rename snake_to_camel plugin => tarpc-plugins
* Update README
* Mangle a lot of names in macro expansion.
To lower the chance of any issues, prefix idents in service expansion with __tarpc_service.
In future_enum, prefix with __future_enum. The pattern is basically __macro_name_ident.
Any imported enum variant will conflict with a let binding or a function arg, so we basically
can't use any generic idents at all. Example:
enum Req { request(..) }
use self::Req::request;
fn make_request(request: Request) { ... }
^^^^^^^ conflict here
Additionally, suffix generated associated types with Fut to avoid conflicts with camelcased rpcs.
Why someone would do that, I don't know, but we shouldn't allow that wart.
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.
RPC frameworks are a fundamental building block of most microservices-oriented architectures. Two well-known ones are gRPC and Cap'n Proto.
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.
Usage
NB: this example is for master. Are you looking for other versions?
Add to your Cargo.toml dependencies:
tarpc = { git = "https://github.com/google/tarpc" }
tarpc-plugins = { git = "https://github.com/google/tarpc" }
Example
// required by `FutureClient` (not used in this example)
#![feature(conservative_impl_trait, plugin)]
#![plugin(tarpc_plugins)]
extern crate futures;
#[macro_use]
extern crate tarpc;
use tarpc::util::Never;
use tarpc::sync::Connect;
service! {
rpc hello(name: String) -> String;
}
#[derive(Clone)]
struct HelloServer;
impl SyncService for HelloServer {
fn hello(&self, name: String) -> Result<String, Never> {
Ok(format!("Hello, {}!", name))
}
}
fn main() {
let addr = "localhost:10000";
let _server = HelloServer.listen(addr).unwrap();
let client = SyncClient::connect(addr).unwrap();
println!("{}", client.hello(&"Mom".to_string()).unwrap());
}
The 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 SyncClient, AsyncClient,
and FutureClient types, and SyncService and AsyncService traits. There is
also a 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.
Documentation
Use cargo doc as you normally would to see the documentation created for all
items expanded by a service! invocation.
Additional Features
- Configurable server rate limiting.
- Automatic client retries with exponential backoff when server is busy.
- Concurrent requests from a single client.
- Backed by an mio
EventLoop, protecting services (includingSyncServices) from slowloris attacks. - Run any number of clients on a single client event loop.
- Run any number of services on a single service event loop.
- Configure clients and services to run on a custom event loop, defaulting to the global event loop.
- Any type that
implsserde'sSerializeandDeserializecan 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)
- Load balancing
- Service discovery
- Automatically reconnect on the client side when the connection cuts out.
- Support generic serialization protocols.
Contributing
To contribute to tarpc, please see CONTRIBUTING.
License
tarpc is distributed under the terms of the MIT license.
See LICENSE for details.