Remove deprecated tokio-proto and replace with homegrown rpc framework (#199)

# New Crates - crate rpc contains the core client/server request-response framework, as well as a transport trait. - crate bincode-transport implements a transport that works almost exactly as tarpc works today (not to say it's wire-compatible). - crate trace has some foundational types for tracing. This isn't really fleshed out yet, but it's useful for in-process log tracing, at least. All crates are now at the top level. e.g. tarpc-plugins is now tarpc/plugins rather than tarpc/src/plugins. tarpc itself is now a *very* small code surface, as most functionality has been moved into the other more granular crates. # New Features - deadlines: all requests specify a deadline, and a server will stop processing a response when past its deadline. - client cancellation propagation: when a client drops a request, the client sends a message to the server informing it to cancel its response. This means cancellations can propagate across multiple server hops. - trace context stuff as mentioned above - more server configuration for total connection limits, per-connection request limits, etc. # Removals - no more shutdown handle. I left it out for now because of time and not being sure what the right solution is. - all async now, no blocking stub or server interface. This helps with maintainability, and async/await makes async code much more usable. The service trait is thusly renamed Service, and the client is renamed Client. - no built-in transport. Tarpc is now transport agnostic (see bincode-transport for transitioning existing uses). - going along with the previous bullet, no preferred transport means no TLS support at this time. We could make a tls transport or make bincode-transport compatible with TLS. - a lot of examples were removed because I couldn't keep up with maintaining all of them. Hopefully the ones I kept are still illustrative. - no more plugins! # Open Questions 1. Should client.send() return `Future<Response>` or `Future<Future<Response>>`? The former appears more ergonomic but it doesn’t allow concurrent requests with a single client handle. The latter is less ergonomic but yields back control of the client once it’s successfully sent out the request. Should we offer fns for both? 2. Should rpc service! Fns take &mut self or &self or self? The service needs to impl Clone anyway, technically we only need to clone it once per connection, and then leave it up to the user to decide if they want to clone it per RPC. In practice, everyone doing nontrivial stuff will need to clone it per RPC, I think. 3. Do the request/response structs look ok? 4. Is supporting server shutdown/lameduck important? Fixes #178 #155 #124 #104 #83 #38
2026-01-22 11:05:22 +01:00 · 2018-10-16 11:26:27 -07:00
parent 5e4b97e589
commit 905e5be8bb
73 changed files with 4690 additions and 5143 deletions
--- a/rpc/src/lib.rs
+++ b/rpc/src/lib.rs
@@ -0,0 +1,214 @@
+// Copyright 2018 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.
+
+#![feature(
+    const_fn,
+    non_exhaustive,
+    integer_atomics,
+    try_trait,
+    nll,
+    futures_api,
+    pin,
+    arbitrary_self_types,
+    await_macro,
+    async_await,
+    generators,
+    optin_builtin_traits,
+    generator_trait,
+    gen_future,
+    decl_macro,
+)]
+#![deny(missing_docs, missing_debug_implementations)]
+
+//! An RPC framework providing client and server.
+//!
+//! Features:
+//! * RPC deadlines, both client- and server-side.
+//! * Cascading cancellation (works with multiple hops).
+//! * Configurable limits
+//!    * In-flight requests, both client and server-side.
+//!        * Server-side limit is per-connection.
+//!        * When the server reaches the in-flight request maximum, it returns a throttled error
+//!          to the client.
+//!        * When the client reaches the in-flight request max, messages are buffered up to a
+//!          configurable maximum, beyond which the requests are back-pressured.
+//!    * Server connections.
+//!        * Total and per-IP limits.
+//!        * When an incoming connection is accepted, if already at maximum, the connection is
+//!          dropped.
+//! * Transport agnostic.
+
+pub mod client;
+pub mod context;
+pub mod server;
+pub mod transport;
+pub(crate) mod util;
+
+pub use crate::{client::Client, server::Server, transport::Transport};
+
+use futures::{Future, task::{Spawn, SpawnExt, SpawnError}};
+use std::{cell::RefCell, io, sync::Once, time::SystemTime};
+
+/// A message from a client to a server.
+#[derive(Debug)]
+#[cfg_attr(
+    feature = "serde",
+    derive(serde::Serialize, serde::Deserialize)
+)]
+#[non_exhaustive]
+pub struct ClientMessage<T> {
+    /// The trace context associates the message with a specific chain of causally-related actions,
+    /// possibly orchestrated across many distributed systems.
+    pub trace_context: trace::Context,
+    /// The message payload.
+    pub message: ClientMessageKind<T>,
+}
+
+/// Different messages that can be sent from a client to a server.
+#[derive(Debug)]
+#[cfg_attr(
+    feature = "serde",
+    derive(serde::Serialize, serde::Deserialize)
+)]
+#[non_exhaustive]
+pub enum ClientMessageKind<T> {
+    /// A request initiated by a user. The server responds to a request by invoking a
+    /// service-provided request handler.  The handler completes with a [`response`](Response), which
+    /// the server sends back to the client.
+    Request(Request<T>),
+    /// A command to cancel an in-flight request, automatically sent by the client when a response
+    /// future is dropped.
+    ///
+    /// When received, the server will immediately cancel the main task (top-level future) of the
+    /// request handler for the associated request. Any tasks spawned by the request handler will
+    /// not be canceled, because the framework layer does not
+    /// know about them.
+    Cancel {
+        /// The ID of the request to cancel.
+        request_id: u64,
+    },
+}
+
+/// A request from a client to a server.
+#[derive(Debug)]
+#[cfg_attr(
+    feature = "serde",
+    derive(serde::Serialize, serde::Deserialize)
+)]
+#[non_exhaustive]
+pub struct Request<T> {
+    /// Uniquely identifies the request across all requests sent over a single channel.
+    pub id: u64,
+    /// The request body.
+    pub message: T,
+    /// When the client expects the request to be complete by. The server will cancel the request
+    /// if it is not complete by this time.
+    #[cfg_attr(
+        feature = "serde",
+        serde(serialize_with = "util::serde::serialize_epoch_secs")
+    )]
+    #[cfg_attr(
+        feature = "serde",
+        serde(deserialize_with = "util::serde::deserialize_epoch_secs")
+    )]
+    pub deadline: SystemTime,
+}
+
+/// A response from a server to a client.
+#[derive(Debug, PartialEq, Eq)]
+#[cfg_attr(
+    feature = "serde",
+    derive(serde::Serialize, serde::Deserialize)
+)]
+#[non_exhaustive]
+pub struct Response<T> {
+    /// The ID of the request being responded to.
+    pub request_id: u64,
+    /// The response body, or an error if the request failed.
+    pub message: Result<T, ServerError>,
+}
+
+/// An error response from a server to a client.
+#[derive(Debug, PartialEq, Eq)]
+#[cfg_attr(
+    feature = "serde",
+    derive(serde::Serialize, serde::Deserialize)
+)]
+#[non_exhaustive]
+pub struct ServerError {
+    #[cfg_attr(
+        feature = "serde",
+        serde(serialize_with = "util::serde::serialize_io_error_kind_as_u32")
+    )]
+    #[cfg_attr(
+        feature = "serde",
+        serde(deserialize_with = "util::serde::deserialize_io_error_kind_from_u32")
+    )]
+    /// The type of error that occurred to fail the request.
+    pub kind: io::ErrorKind,
+    /// A message describing more detail about the error that occurred.
+    pub detail: Option<String>,
+}
+
+impl From<ServerError> for io::Error {
+    fn from(e: ServerError) -> io::Error {
+        io::Error::new(e.kind, e.detail.unwrap_or_default())
+    }
+}
+
+impl<T> Request<T> {
+    /// Returns the deadline for this request.
+    pub fn deadline(&self) -> &SystemTime {
+        &self.deadline
+    }
+}
+
+static INIT: Once = Once::new();
+static mut SEED_SPAWN: Option<Box<dyn CloneSpawn>> = None;
+thread_local! {
+    static SPAWN: RefCell<Box<dyn CloneSpawn>> = {
+        unsafe {
+            // INIT must always be called before accessing SPAWN.
+            // Otherwise, accessing SPAWN can trigger undefined behavior due to race conditions.
+            INIT.call_once(|| {});
+            RefCell::new(SEED_SPAWN.clone().expect("init() must be called."))
+        }
+    };
+}
+
+/// Initializes the RPC library with a mechanism to spawn futures on the user's runtime.
+/// Client stubs and servers both use the initialized spawn.
+///
+/// Init only has an effect the first time it is called. If called previously, successive calls to
+/// init are noops.
+pub fn init(spawn: impl Spawn + Clone + 'static) {
+    unsafe {
+        INIT.call_once(|| {
+            SEED_SPAWN = Some(Box::new(spawn));
+        });
+    }
+}
+
+pub(crate) fn spawn(future: impl Future<Output = ()> + Send + 'static) -> Result<(), SpawnError> {
+    SPAWN.with(|spawn| {
+        spawn.borrow_mut().spawn(future)
+    })
+}
+
+trait CloneSpawn: Spawn {
+    fn box_clone(&self) -> Box<dyn CloneSpawn>;
+}
+
+impl Clone for Box<dyn CloneSpawn> {
+    fn clone(&self) -> Self {
+        self.box_clone()
+    }
+}
+
+impl<S: Spawn + Clone + 'static> CloneSpawn for S {
+    fn box_clone(&self) -> Box<dyn CloneSpawn> {
+        Box::new(self.clone())
+    }
+}