Prepare release of v0.26.0

README.md

@@ -42,6 +42,7 @@ process, and no context switching between different languages.
 Some other features of tarpc:
 - Pluggable transport: any type impling `Stream<Item = Request> + Sink<Response>` can be
   used as a transport to connect the client and server.
+- `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.
@@ -50,9 +51,9 @@ Some other features of tarpc:
   requests sent by the server that use the request context will propagate the request deadline.
   For example, if a server is handling a request with a 10s deadline, does 2s of work, then
   sends a request to another server, that server will see an 8s deadline.
-- Distributed tracing: tarpc is instrumented with [tracing](https://github.com/tokio-rs/tracing)
-  primitives extended with [OpenTelemetry](https://opentelemetry.io/) traces. Using a compatible
-  tracing subscriber like
+- Distributed tracing: tarpc is instrumented with
+  [tracing](https://github.com/tokio-rs/tracing) primitives extended with
+  [OpenTelemetry](https://opentelemetry.io/) traces. Using a compatible tracing subscriber like
   [Jaeger](https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry-jaeger),
   each RPC can be traced through the client, server, amd other dependencies downstream of the
   server. Even for applications not connected to a distributed tracing collector, the
@@ -66,7 +67,7 @@ Some other features of tarpc:
 Add to your `Cargo.toml` dependencies:
 
 ```toml
-tarpc = "0.25"
+tarpc = "0.26"
 ```
 
 The `tarpc::service` attribute expands to a collection of items that form an rpc service.
@@ -80,7 +81,7 @@ your `Cargo.toml`:
 
 ```toml
 futures = "1.0"
-tarpc = { version = "0.25", features = ["tokio1"] }
+tarpc = { version = "0.26", features = ["tokio1"] }
 tokio = { version = "1.0", features = ["macros"] }
 ```
 
@@ -147,7 +148,7 @@ async fn main() -> io::Result<()> {
 
     // WorldClient is generated by the #[tarpc::service] attribute. It has a constructor `new`
     // that takes a config and any Transport as input.
-    let mut client = WorldClient::new(client::Config::default(), client_transport).spawn()?;
+    let mut client = WorldClient::new(client::Config::default(), client_transport).spawn();
 
     // The client has an RPC method for each RPC defined in the annotated trait. It takes the same
     // args as defined, with the addition of a Context, which is always the first arg. The Context

RELEASES.md

@@ -1,3 +1,78 @@
+## 0.26.0 (2021-04-14)
+
+### New Features
+
+#### Tracing
+
+tarpc is now instrumented with tracing primitives extended with
+OpenTelemetry traces. Using a compatible tracing-opentelemetry
+subscriber like Jaeger, each RPC can be traced through the client,
+server, amd other dependencies downstream of the server. Even for
+applications not connected to a distributed tracing collector, the
+instrumentation can also be ingested by regular loggers like env_logger.
+
+### Breaking Changes
+
+#### Logging
+
+Logged events are now structured using tracing. For applications using a
+logger and not a tracing subscriber, these logs may look different or
+contain information in a less consumable manner. The easiest solution is
+to add a tracing subscriber that logs to stdout, such as
+tracing_subscriber::fmt.
+
+####  Context
+
+- Context no longer has parent_span, which was actually never needed,
+  because the context sent in an RPC is inherently the parent context.
+  For purposes of distributed tracing, the client side of the RPC has all
+  necessary information to link the span to its parent; the server side
+  need do nothing more than export the (trace ID, span ID) tuple.
+- Context has a new field, SamplingDecision, which has two variants,
+  Sampled and Unsampled. This field can be used by downstream systems to
+  determine whether a trace needs to be exported. If the parent span is
+  sampled, the expectation is that all child spans be exported, as well;
+  to do otherwise could result in lossy traces being exported. Note that
+  if an Openetelemetry tracing subscriber is not installed, the fallback
+  context will still be used, but the Context's sampling decision will
+  always be inherited by the parent Context's sampling decision.
+- Context::scope has been removed. Context propagation is now done via
+  tracing's task-local spans. Spans can be propagated across tasks via
+  Span::in_scope. When a service receives a request, it attaches an
+  Opentelemetry context to the local Span created before request handling,
+  and this context contains the request deadline. This span-local deadline
+  is retrieved by Context::current, but it cannot be modified so that
+  future Context::current calls contain a different deadline. However, the
+  deadline in the context passed into an RPC call will override it, so
+  users can retrieve the current context and then modify the deadline
+  field, as has been historically possible.
+- Context propgation precedence changes: when an RPC is initiated, the
+  current Span's Opentelemetry context takes precedence over the trace
+  context passed into the RPC method. If there is no current Span, then
+  the trace context argument is used as it has been historically. Note
+  that Opentelemetry context propagation requires an Opentelemetry
+  tracing subscriber to be installed.
+
+#### Server
+
+- The server::Channel trait now has an additional required associated
+  type and method which returns the underlying transport. This makes it
+  more ergonomic for users to retrieve transport-specific information,
+  like IP Address. BaseChannel implements Channel::transport by returning
+  the underlying transport, and channel decorators like Throttler just
+  delegate to the Channel::transport method of the wrapped channel.
+
+#### Client
+
+- NewClient::spawn no longer returns a result, as spawn can't fail.
+
+### References
+
+[1] https://github.com/tokio-rs/tracing
+[2] https://opentelemetry.io
+[3] https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry-jaeger
+[4] https://github.com/env-logger-rs/env_logger
+
 ## 0.25.0 (2021-03-10)
 
 ### Breaking Changes
@@ -170,7 +245,7 @@ nameable futures and will just be boxing the return type anyway. This macro does
 
 ### Breaking Changes
 
-- Enums had _non_exhaustive fields replaced with the #[non_exhaustive] attribute.
+- Enums had `_non_exhaustive` fields replaced with the #[non_exhaustive] attribute.
 
 ### Bug Fixes
 

example-service/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tarpc-example-service"
-version = "0.9.0"
+version = "0.10.0"
 authors = ["Tim Kuehn <tikue@google.com>"]
 edition = "2018"
 license = "MIT"
@@ -21,7 +21,7 @@ opentelemetry = { version = "0.13", features = ["rt-tokio"] }
 opentelemetry-jaeger = { version = "0.12", features = ["tokio"] }
 rand = "0.8"
 serde = { version = "1.0" }
-tarpc = { path = "../tarpc", features = ["full"] }
+tarpc = { version = "0.26", path = "../tarpc", features = ["full"] }
 tokio = { version = "1", features = ["macros", "net", "rt-multi-thread"] }
 tokio-serde = { version = "0.8", features = ["json"] }
 tracing = { version = "0.1" }

plugins/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tarpc-plugins"
-version = "0.10.0"
+version = "0.11.0"
 authors = ["Adam Wright <adam.austin.wright@gmail.com>", "Tim Kuehn <timothy.j.kuehn@gmail.com>"]
 edition = "2018"
 license = "MIT"

tarpc/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tarpc"
-version = "0.25.1"
+version = "0.26.0"
 authors = ["Adam Wright <adam.austin.wright@gmail.com>", "Tim Kuehn <timothy.j.kuehn@gmail.com>"]
 edition = "2018"
 license = "MIT"
@@ -34,7 +34,7 @@ pin-project = "1.0"
 rand = "0.8"
 serde = { optional = true, version = "1.0", features = ["derive"] }
 static_assertions = "1.1.0"
-tarpc-plugins = { path = "../plugins", version = "0.10" }
+tarpc-plugins = { path = "../plugins", version = "0.11" }
 thiserror = "1.0"
 tokio = { version = "1", features = ["time"] }
 tokio-util = { version = "0.6.3", features = ["time"] }

tarpc/src/lib.rs

@@ -38,6 +38,14 @@
 //!   requests sent by the server that use the request context will propagate the request deadline.
 //!   For example, if a server is handling a request with a 10s deadline, does 2s of work, then
 //!   sends a request to another server, that server will see an 8s deadline.
+//! - Distributed tracing: tarpc is instrumented with
+//!   [tracing](https://github.com/tokio-rs/tracing) primitives extended with
+//!   [OpenTelemetry](https://opentelemetry.io/) traces. Using a compatible tracing subscriber like
+//!   [Jaeger](https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry-jaeger),
+//!   each RPC can be traced through the client, server, amd other dependencies downstream of the
+//!   server. Even for applications not connected to a distributed tracing collector, the
+//!   instrumentation can also be ingested by regular loggers like
+//!   [env_logger](https://github.com/env-logger-rs/env_logger/).
 //! - Serde serialization: enabling the `serde1` Cargo feature will make service requests and
 //!   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.
@@ -46,7 +54,7 @@
 //! Add to your `Cargo.toml` dependencies:
 //!
 //! ```toml
-//! tarpc = "0.25"
+//! tarpc = "0.26"
 //! ```
 //!
 //! The `tarpc::service` attribute expands to a collection of items that form an rpc service.
@@ -60,7 +68,7 @@
 //!
 //! ```toml
 //! futures = "1.0"
-//! tarpc = { version = "0.25", features = ["tokio1"] }
+//! tarpc = { version = "0.26", features = ["tokio1"] }
 //! tokio = { version = "1.0", features = ["macros"] }
 //! ```
 //!