1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
// Copyright 2016 Google Inc. All Rights Reserved. // // Licensed under the MIT License, <LICENSE or http://opensource.org/licenses/MIT>. // This file may not be copied, modified, or distributed except according to those terms. //! 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](http://www.grpc.io) and //! [Cap'n Proto](https://capnproto.org/). //! //! 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)] //! #![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: //! //! ```no-run //! #![feature(plugin)] //! #![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()); //! } //! ``` #![deny(missing_docs, missing_debug_implementations)] #![feature(never_type)] #![cfg_attr(test, feature(plugin))] #![cfg_attr(test, plugin(tarpc_plugins))] extern crate byteorder; extern crate bytes; #[macro_use] extern crate cfg_if; #[macro_use] extern crate lazy_static; #[macro_use] extern crate log; extern crate net2; extern crate num_cpus; #[macro_use] extern crate serde_derive; extern crate thread_pool; extern crate tokio_io; #[doc(hidden)] pub extern crate bincode; #[doc(hidden)] #[macro_use] pub extern crate futures; #[doc(hidden)] pub extern crate serde; #[doc(hidden)] pub extern crate tokio_core; #[doc(hidden)] pub extern crate tokio_proto; #[doc(hidden)] pub extern crate tokio_service; pub use errors::Error; #[doc(hidden)] pub use errors::WireError; /// Provides some utility error types, as well as a trait for spawning futures on the default event /// loop. pub mod util; /// Provides the macro used for constructing rpc services and client stubs. #[macro_use] mod macros; /// Synchronous version of the tarpc API pub mod sync; /// Futures-based version of the tarpc API. pub mod future; /// TLS-specific functionality. #[cfg(feature = "tls")] pub mod tls; /// Provides implementations of `ClientProto` and `ServerProto` that implement the tarpc protocol. /// The tarpc protocol is a length-delimited, bincode-serialized payload. mod protocol; /// Provides a few different error types. mod errors; /// Provides an abstraction over TLS and TCP streams. mod stream_type; use std::sync::mpsc; use std::thread; use tokio_core::reactor; lazy_static! { /// The `Remote` for the default reactor core. static ref REMOTE: reactor::Remote = { spawn_core() }; } /// Spawns a `reactor::Core` running forever on a new thread. fn spawn_core() -> reactor::Remote { let (tx, rx) = mpsc::channel(); thread::spawn(move || { let mut core = reactor::Core::new().unwrap(); tx.send(core.handle().remote().clone()).unwrap(); // Run forever core.run(futures::empty::<(), !>()).unwrap(); }); rx.recv().unwrap() } cfg_if! { if #[cfg(feature = "tls")] { extern crate tokio_tls; extern crate native_tls as native_tls_inner; /// Re-exported TLS-related types from the `native_tls` crate. pub mod native_tls { pub use native_tls_inner::{Error, Pkcs12, TlsAcceptor, TlsConnector}; } } else {} }