tarpc_lib/
lib.rs

1// Copyright 2018 Google LLC
2//
3// Use of this source code is governed by an MIT-style
4// license that can be found in the LICENSE file or at
5// https://opensource.org/licenses/MIT.
6
7#![feature(weak_counts, non_exhaustive, trait_alias)]
8#![deny(missing_docs, missing_debug_implementations)]
9
10//! An RPC framework providing client and server.
11//!
12//! Features:
13//! * RPC deadlines, both client- and server-side.
14//! * Cascading cancellation (works with multiple hops).
15//! * Configurable limits
16//!    * In-flight requests, both client and server-side.
17//!        * Server-side limit is per-connection.
18//!        * When the server reaches the in-flight request maximum, it returns a throttled error
19//!          to the client.
20//!        * When the client reaches the in-flight request max, messages are buffered up to a
21//!          configurable maximum, beyond which the requests are back-pressured.
22//!    * Server connections.
23//!        * Total and per-IP limits.
24//!        * When an incoming connection is accepted, if already at maximum, the connection is
25//!          dropped.
26//! * Transport agnostic.
27
28pub mod client;
29pub mod context;
30pub mod server;
31pub mod transport;
32pub(crate) mod util;
33
34pub use crate::{client::Client, server::Server, transport::Transport};
35
36use futures::task::Poll;
37use std::{io, time::SystemTime};
38
39/// A message from a client to a server.
40#[derive(Debug)]
41#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
42#[non_exhaustive]
43pub enum ClientMessage<T> {
44    /// A request initiated by a user. The server responds to a request by invoking a
45    /// service-provided request handler.  The handler completes with a [`response`](Response), which
46    /// the server sends back to the client.
47    Request(Request<T>),
48    /// A command to cancel an in-flight request, automatically sent by the client when a response
49    /// future is dropped.
50    ///
51    /// When received, the server will immediately cancel the main task (top-level future) of the
52    /// request handler for the associated request. Any tasks spawned by the request handler will
53    /// not be canceled, because the framework layer does not
54    /// know about them.
55    Cancel {
56        /// The trace context associates the message with a specific chain of causally-related actions,
57        /// possibly orchestrated across many distributed systems.
58        #[cfg_attr(feature = "serde", serde(default))]
59        trace_context: trace::Context,
60        /// The ID of the request to cancel.
61        request_id: u64,
62    },
63}
64
65/// A request from a client to a server.
66#[derive(Clone, Copy, Debug)]
67#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
68#[non_exhaustive]
69pub struct Request<T> {
70    /// Trace context, deadline, and other cross-cutting concerns.
71    pub context: context::Context,
72    /// Uniquely identifies the request across all requests sent over a single channel.
73    pub id: u64,
74    /// The request body.
75    pub message: T,
76}
77
78/// A response from a server to a client.
79#[derive(Clone, Debug, PartialEq, Eq, Hash)]
80#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
81#[non_exhaustive]
82pub struct Response<T> {
83    /// The ID of the request being responded to.
84    pub request_id: u64,
85    /// The response body, or an error if the request failed.
86    pub message: Result<T, ServerError>,
87}
88
89/// An error response from a server to a client.
90#[derive(Clone, Debug, PartialEq, Eq, Hash)]
91#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
92#[non_exhaustive]
93pub struct ServerError {
94    #[cfg_attr(
95        feature = "serde1",
96        serde(serialize_with = "util::serde::serialize_io_error_kind_as_u32")
97    )]
98    #[cfg_attr(
99        feature = "serde1",
100        serde(deserialize_with = "util::serde::deserialize_io_error_kind_from_u32")
101    )]
102    /// The type of error that occurred to fail the request.
103    pub kind: io::ErrorKind,
104    /// A message describing more detail about the error that occurred.
105    pub detail: Option<String>,
106}
107
108impl From<ServerError> for io::Error {
109    fn from(e: ServerError) -> io::Error {
110        io::Error::new(e.kind, e.detail.unwrap_or_default())
111    }
112}
113
114impl<T> Request<T> {
115    /// Returns the deadline for this request.
116    pub fn deadline(&self) -> &SystemTime {
117        &self.context.deadline
118    }
119}
120
121pub(crate) type PollIo<T> = Poll<Option<io::Result<T>>>;
tarpc_lib/lib.rs

tarpc_lib/
lib.rs
