ringline_grpc/lib.rs
1//! Sans-IO gRPC client framing layer.
2//!
3//! This crate provides a pure sans-IO gRPC client framing layer built on top
4//! of `ringline-h2`. It has no protobuf dependency -- the caller provides raw
5//! `&[u8]` message bodies and handles serialization externally.
6//!
7//! # Architecture
8//!
9//! ```text
10//! TCP + TLS bytes
11//! |
12//! +----v-----------+
13//! | ringline-h2 | HTTP/2 framing + HPACK
14//! +----+-----------+
15//! |
16//! +----v-----------+
17//! | ringline-grpc | gRPC message framing + status codes
18//! | GrpcConnection | GrpcEvent: Response, Message, Status, etc.
19//! +----------------+
20//! ```
21//!
22//! # Example
23//!
24//! ```rust,ignore
25//! use ringline_grpc::{GrpcConnection, GrpcEvent, Settings};
26//!
27//! let mut grpc = GrpcConnection::new(Settings::client_default());
28//!
29//! // Send the connection preface to the transport.
30//! let preface = grpc.take_pending_send();
31//! transport_send(&preface);
32//!
33//! // Send a unary request (codec-agnostic: caller provides raw bytes).
34//! let stream_id = grpc.send_unary("my.Service", "MyMethod", &request_bytes, &[])?;
35//! transport_send(&grpc.take_pending_send());
36//!
37//! // Feed received bytes and drain events.
38//! grpc.recv(&received_data)?;
39//! while let Some(event) = grpc.poll_event() {
40//! match event {
41//! GrpcEvent::Message { stream_id, data } => { /* decoded message */ }
42//! GrpcEvent::Status { stream_id, status, message, .. } => { /* done */ }
43//! _ => {}
44//! }
45//! }
46//! ```
47
48pub(crate) mod compress;
49pub mod connection;
50pub mod error;
51pub mod message;
52
53pub use connection::{GrpcConnection, GrpcEvent};
54pub use error::{GrpcError, GrpcStatus};
55pub use ringline_h2::{HeaderField, Settings};