From d27f341bdebe29df927b6d2b6f1a26fd657a0efe Mon Sep 17 00:00:00 2001 From: Tim Kuehn Date: Wed, 19 Aug 2020 18:32:56 -0700 Subject: [PATCH] Prepare release of v0.22.0 --- README.md | 34 +++++++++++++++++++++------------- RELEASES.md | 30 ++++++++++++++++++++++++++++-- example-service/Cargo.toml | 2 +- tarpc/Cargo.toml | 2 +- tarpc/examples/pubsub.rs | 2 +- tarpc/src/lib.rs | 5 +---- 6 files changed, 53 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index fbc12a9..58371b3 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ # tarpc + + *Disclaimer*: This is not an official Google product. tarpc is an RPC framework for rust with a focus on ease of use. Defining a @@ -22,7 +24,7 @@ writing a server is taken care of for you. [Documentation](https://docs.rs/crate/tarpc/) -### What is an RPC framework? +## 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 @@ -40,7 +42,7 @@ process, and no context switching between different languages. Some other features of tarpc: - Pluggable transport: any type impling `Stream + Sink` can be used as a transport to connect the client and server. -- `Send` optional: if the transport doesn't require it, neither does tarpc! +- `Send + 'static` optional: if the transport doesn't require it, neither does tarpc! - Cascading cancellation: dropping a request will send a cancellation message to the server. The server will cease any unfinished work on the request, subsequently cancelling any of its own requests, repeating for the entire chain of transitive dependencies. @@ -53,18 +55,18 @@ Some other features of tarpc: responses `Serialize + Deserialize`. It's entirely optional, though: in-memory transports can be used, as well, so the price of serialization doesn't have to be paid when it's not needed. -### Usage +## Usage Add to your `Cargo.toml` dependencies: ```toml -tarpc = { version = "0.21.0", features = ["full"] } +tarpc = "0.22.0" ``` The `tarpc::service` attribute expands to a collection of items that form an rpc service. These generated types make it easy and ergonomic to write servers with less boilerplate. Simply implement the generated service trait, and you're off to the races! -### Example +## Example For this example, in addition to tarpc, also add two other dependencies to your `Cargo.toml`: @@ -81,6 +83,7 @@ For a more real-world example, see [example-service](example-service). First, let's set up the dependencies and service definition. ```rust + use futures::{ future::{self, Ready}, prelude::*, @@ -109,19 +112,22 @@ implement it for our Server struct. #[derive(Clone)] struct HelloServer; -#[tarpc::server] impl World for HelloServer { - async fn hello(self, _: context::Context, name: String) -> String { - format!("Hello, {}!", name) + // Each defined rpc generates two items in the trait, a fn that serves the RPC, and + // an associated type representing the future output by the fn. + + type HelloFut = Ready; + + fn hello(self, _: context::Context, name: String) -> Self::HelloFut { + future::ready(format!("Hello, {}!", name)) } } ``` Lastly let's write our `main` that will start the server. While this example uses an -[in-process -channel](https://docs.rs/tarpc/0.18.0/tarpc/transport/channel/struct.UnboundedChannel.html), -tarpc also ships bincode and JSON -tokio-net based TCP transports that are generic over all serializable types. +[in-process channel](rpc::transport::channel), tarpc also ships a generic [`serde_transport`] +behind the `serde-transport` feature, with additional [TCP](serde_transport::tcp) functionality +available behind the `tcp` feature. ```rust #[tokio::main] @@ -151,9 +157,11 @@ async fn main() -> io::Result<()> { } ``` -### Service Documentation +## Service Documentation Use `cargo doc` as you normally would to see the documentation created for all items expanded by a `service!` invocation. + + License: MIT diff --git a/RELEASES.md b/RELEASES.md index eb5a9fa..c3af79e 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -1,3 +1,29 @@ +## 0.22.0 (2020-08-02) + +This release adds some flexibility and consistency to `serde_transport`, with one new feature and +one small breaking change. + +### New Features + +`serde_transport::tcp` now exposes framing configuration on `connect()` and `listen()`. This is +useful if, for instance, you want to send requests or responses that are larger than the maximum +payload allowed by default: + +```rust +let mut transport = tarpc::serde_transport::tcp::connect(server_addr, Json::default); +transport.config_mut().max_frame_length(4294967296); +let mut client = MyClient::new(client::Config::default(), transport.await?).spawn()?; +``` + +### Breaking Changes + +The codec argument to `serde_transport::tcp::connect` changed from a Codec to impl Fn() -> Codec, +to be consistent with `serde_transport::tcp::listen`. While only one Codec is needed, more than one +person has been tripped up by the inconsistency between `connect` and `listen`. Unfortunately, the +compiler errors are not much help in this case, so it was decided to simply do the more intuitive +thing so that the compiler doesn't need to step in in the first place. + + ## 0.21.1 (2020-08-02) ### New Features @@ -62,7 +88,7 @@ nameable futures and will just be boxing the return type anyway. This macro does ### Bug Fixes - https://github.com/google/tarpc/issues/304 - + A race condition in code that limits number of connections per client caused occasional panics. - https://github.com/google/tarpc/pull/295 @@ -82,7 +108,7 @@ nameable futures and will just be boxing the return type anyway. This macro does ## 0.13.0 (2018-10-16) -### Breaking Changes +### Breaking Changes Version 0.13 marks a significant departure from previous versions of tarpc. The API has changed significantly. The tokio-proto crate has been torn out and diff --git a/example-service/Cargo.toml b/example-service/Cargo.toml index 0f8318c..2163324 100644 --- a/example-service/Cargo.toml +++ b/example-service/Cargo.toml @@ -16,7 +16,7 @@ description = "An example server built on tarpc." clap = "2.0" futures = "0.3" serde = { version = "1.0" } -tarpc = { version = "0.21", path = "../tarpc", features = ["full"] } +tarpc = { version = "0.22", path = "../tarpc", features = ["full"] } tokio = { version = "0.2", features = ["full"] } tokio-serde = { version = "0.6", features = ["json"] } tokio-util = { version = "0.3", features = ["codec"] } diff --git a/tarpc/Cargo.toml b/tarpc/Cargo.toml index 9571a8a..8c51827 100644 --- a/tarpc/Cargo.toml +++ b/tarpc/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "tarpc" -version = "0.21.1" +version = "0.22.0" authors = ["Adam Wright ", "Tim Kuehn "] edition = "2018" license = "MIT" diff --git a/tarpc/examples/pubsub.rs b/tarpc/examples/pubsub.rs index 7c124d8..f98a237 100644 --- a/tarpc/examples/pubsub.rs +++ b/tarpc/examples/pubsub.rs @@ -18,7 +18,7 @@ /// messages to all clients subscribed to the topic of that message. /// /// Subscriber Publisher PubSub Server -/// T1 | | | +/// T1 | | | /// T2 |-----Connect------------------------------------------------------>| /// T3 | | | /// T2 |<-------------------------------------------------------Topics-----| diff --git a/tarpc/src/lib.rs b/tarpc/src/lib.rs index bea2d52..a12a671 100644 --- a/tarpc/src/lib.rs +++ b/tarpc/src/lib.rs @@ -4,9 +4,6 @@ // license that can be found in the LICENSE file or at // https://opensource.org/licenses/MIT. -//! [![Latest Version](https://img.shields.io/crates/v/tarpc.svg)](https://crates.io/crates/tarpc) -//! [![Join the chat at https://gitter.im/tarpc/Lobby](https://badges.gitter.im/tarpc/Lobby.svg)](https://gitter.im/tarpc/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -//! //! *Disclaimer*: This is not an official Google product. //! //! tarpc is an RPC framework for rust with a focus on ease of use. Defining a @@ -50,7 +47,7 @@ //! Add to your `Cargo.toml` dependencies: //! //! ```toml -//! tarpc = "0.21.0" +//! tarpc = "0.22.0" //! ``` //! //! The `tarpc::service` attribute expands to a collection of items that form an rpc service.