rama_ttrpc/
lib.rs

1//! ttRPC support for Rama.
2//!
3//! # ttRPC
4//!
5//! ttRPC ("gRPC for low-memory environments") is a lightweight RPC protocol used by
6//! container runtimes and their plugins — containerd shims, the kata-agent, and the
7//! containerd Node Resource Interface (NRI). Where gRPC rides on HTTP/2, ttRPC replaces
8//! the whole HTTP/2 stack with a simple length-prefixed framing directly on the byte
9//! stream, so it is a sibling to [`rama-grpc`], not part of it.
10//!
11//! Messages are encoded with [`prost`]; service stubs are generated at build time by
12//! [`rama-ttrpc-build`] (see [`include_proto!`]).
13//!
14//! ## Transport
15//!
16//! Like `rama-grpc`, this crate has **no transport layer**. A [`Client`] or
17//! [`ServerConnection`] is built from any already-connected stream (anything that is
18//! `AsyncRead + AsyncWrite`). Establish that stream with rama's `rama-tcp` / `rama-unix` /
19//! `rama-udp` capabilities (or an in-memory `tokio::io::duplex` pair), then hand it over:
20//!
21//! # Rama
22//!
23//! Crate used by the end-user `rama` crate and `rama` crate authors alike.
24//!
25//! Learn more about `rama`:
26//!
27//! - Github: <https://github.com/plabayo/rama>
28//! - Book: <https://ramaproxy.org/book/>
29//!
30//! [`rama-grpc`]: https://crates.io/crates/rama-grpc
31//! [`rama-ttrpc-build`]: https://crates.io/crates/rama-ttrpc-build
32//! [`prost`]: https://crates.io/crates/prost
33
34#![doc(
35    html_favicon_url = "https://raw.githubusercontent.com/plabayo/rama/main/docs/img/old_logo.png"
36)]
37#![doc(html_logo_url = "https://raw.githubusercontent.com/plabayo/rama/main/docs/img/old_logo.png")]
38#![cfg_attr(docsrs, feature(doc_cfg))]
39
40mod client;
41mod context;
42mod id_pool;
43mod io;
44mod macros;
45mod server;
46mod service;
47mod types;
48
49/// Result type used throughout `rama-ttrpc`, defaulting the error to [`Status`].
50pub type Result<T, E = Status> = std::result::Result<T, E>;
51
52pub use client::{Client, ClientExt, TtrpcConnector};
53pub use context::metadata::Metadata;
54pub use context::timeout::Timeout;
55pub use context::{Context, ServerContext, get_context, get_server};
56pub use server::{DEFAULT_MAX_CONCURRENT_STREAMS, ServerConnection, ServerController, TtrpcServer};
57pub use types::protos::status::StatusExt;
58pub use types::protos::{Code, Status};
59
60#[doc(hidden)]
61pub mod __codegen_prelude {
62    pub use crate::client::request_handlers::RequestHandler;
63    pub use crate::server::method_handlers::MethodHandler;
64    pub use crate::service::{
65        ClientStreamingMethod, DuplexStreamingMethod, ServerStreamingMethod, Service, UnaryMethod,
66    };
67}
68
69#[doc(hidden)]
70pub mod prelude {
71    pub use std::future::Future;
72
73    pub use rama_core::futures::stream::Stream;
74
75    pub use crate::Result;
76}
77
78pub mod stream {
79    //! Streaming helpers re-exported for generated service code.
80    pub use rama_core::futures::StreamExt;
81    pub use rama_core::futures::async_stream::{stream_fn, try_stream_fn};
82    pub use rama_core::futures::stream::{Stream, once};
83}
84
85/// ttRPC code generation (`rama-ttrpc-build`), re-exported so a `build.rs` can run codegen
86/// through the `rama-ttrpc` facade (mirrors `rama-grpc`'s `build` re-export).
87///
88/// Enable the `protobuf` feature to use it, e.g. `rama_ttrpc::build::compile_protos(...)`.
89#[cfg(feature = "protobuf")]
90#[cfg_attr(docsrs, doc(cfg(feature = "protobuf")))]
91#[doc(inline)]
92pub use ::rama_ttrpc_build as build;
93
94/// Protobuf support re-exported so generated ttRPC code does not require the consumer to
95/// depend on `prost` directly (mirrors `rama-grpc`'s `protobuf::prost`).
96///
97/// Gated on the `protobuf` feature: this re-export only exists to back generated code, and
98/// generating code requires that feature. (`prost` itself is always a dependency, since the
99/// ttRPC wire format is protobuf-framed — unlike `rama-grpc` where the gate also makes the
100/// `prost` dependency optional.)
101#[cfg(feature = "protobuf")]
102#[cfg_attr(docsrs, doc(cfg(feature = "protobuf")))]
103pub mod protobuf {
104    /// Re-export of [`prost`](https://docs.rs/prost) and
105    /// [`prost-types`](https://docs.rs/prost-types).
106    pub mod prost {
107        pub use ::prost::*;
108        pub use ::prost_types as types;
109    }
110}
rama_ttrpc/lib.rs

rama_ttrpc/
lib.rs
