tonic_rest/lib.rs
1#![allow(clippy::doc_markdown)] // README uses "OpenAPI" proper noun throughout
2#![doc = include_str!("../README.md")]
3//!
4//! ---
5//!
6//! ## API Reference
7//!
8//! # Types
9//!
10//! - [`RestError`] — Converts [`tonic::Status`] to HTTP JSON error responses
11//! - [`build_tonic_request`] — Bridges Axum requests to [`tonic::Request`]
12//! - [`sse_error_event`] — Formats gRPC errors as SSE events
13//! - [`grpc_to_http_status`] — Maps gRPC status codes to HTTP status codes
14//! - [`grpc_code_name`] — Returns canonical `SCREAMING_SNAKE_CASE` name for a gRPC code
15//!
16//! # Usage
17//!
18//! ```toml
19//! [dependencies]
20//! tonic-rest = "0.1"
21//!
22//! [build-dependencies]
23//! tonic-rest-build = "0.1"
24//! ```
25//!
26//! # Companion Crate
27//!
28//! | Crate | Purpose | Cargo section |
29//! |---------------------|--------------------|----------------------------|
30//! | `tonic-rest` (this) | Runtime types | `[dependencies]` |
31//! | `tonic-rest-build` | Build-time codegen | `[build-dependencies]` |
32
33#![forbid(unsafe_code)]
34#![deny(missing_docs)]
35
36mod runtime;
37
38pub use runtime::*;
39
40/// Concatenate [`FORWARDED_HEADERS`] with extra headers at compile time.
41///
42/// Used by generated code from `tonic-rest-build` to ensure the default
43/// forwarded header list stays in sync with the runtime constant.
44///
45/// ```ignore
46/// const ALL: &[&str] = tonic_rest::concat_forwarded_headers!("x-custom");
47/// ```
48#[macro_export]
49macro_rules! concat_forwarded_headers {
50 ($($extra:expr),* $(,)?) => {
51 &[
52 // Canonical defaults from FORWARDED_HEADERS
53 "authorization",
54 "user-agent",
55 "x-forwarded-for",
56 "x-real-ip",
57 // Extra headers
58 $($extra,)*
59 ]
60 };
61}
62
63/// Serde adapters for prost well-known types and proto3 enums.
64///
65/// Provides adapters for both optional and required fields:
66/// - `timestamp` / `opt_timestamp` — `Timestamp` ↔ RFC 3339
67/// - `duration` / `opt_duration` — `Duration` ↔ `"300s"`
68/// - `field_mask` / `opt_field_mask` — `FieldMask` ↔ `"name,email"`
69///
70/// Also provides the [`define_enum_serde`] macro for proto enum `#[serde(with)]` modules.
71#[cfg(feature = "serde")]
72pub mod serde;