Crate tarpc

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.

Example usage:

#![feature(plugin, use_extern_macros)]
#![plugin(tarpc_plugins)]

#[macro_use]
extern crate tarpc;
extern crate tokio_core;

use tarpc::sync::{client, server};
use tarpc::sync::client::ClientExt;
use tarpc::util::Never;
use tokio_core::reactor;
use std::sync::mpsc;
use std::thread;

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 (tx, rx) = mpsc::channel();
    thread::spawn(move || {
        let mut handle = HelloServer.listen("localhost:10000",
            server::Options::default()).unwrap();
        tx.send(handle.addr()).unwrap();
        handle.run();
    });
    let addr = rx.recv().unwrap();
    let client = SyncClient::connect(addr, client::Options::default()).unwrap();
    println!("{}", client.hello("Mom".to_string()).unwrap());
}

Example usage with TLS:

#![feature(plugin, use_extern_macros)]
#![plugin(tarpc_plugins)]

#[macro_use]
extern crate tarpc;

use tarpc::sync::{client, server};
use tarpc::sync::client::ClientExt;
use tarpc::tls;
use tarpc::util::Never;
use tarpc::native_tls::{TlsAcceptor, Pkcs12};

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 get_acceptor() -> TlsAcceptor {
     let buf = include_bytes!("test/identity.p12");
     let pkcs12 = Pkcs12::from_der(buf, "password").unwrap();
     TlsAcceptor::builder(pkcs12).unwrap().build().unwrap()
}

fn main() {
    let addr = "localhost:10000";
    let acceptor = get_acceptor();
    let _server = HelloServer.listen(addr, server::Options::default().tls(acceptor));
    let client = SyncClient::connect(addr,
                                     client::Options::default()
                                         .tls(tls::client::Context::new("foobar.com").unwrap()))
                                         .unwrap();
    println!("{}", client.hello("Mom".to_string()).unwrap());
}

Modules

future	Futures-based version of the tarpc API.
sync	Synchronous version of the tarpc API
util	Provides some utility error types, as well as a trait for spawning futures on the default event loop.

Macros

service

The main macro that creates RPC services.

Enums

Error

All errors that can occur during the use of tarpc.