gateway_runtime/
lib.rs

1//! # Gateway Runtime
2//!
3//! ## Overview
4//! The `gateway-runtime` crate provides the essential runtime components for the `grpc-gateway-rust` ecosystem.
5//! It acts as the bridge between HTTP/JSON requests and gRPC services, handling routing, transcoding,
6//! authentication, and middleware orchestration.
7//!
8//! ## Core Components
9//!
10//! *   **[Gateway]**: The primary builder and entry point. It orchestrates the middleware stack and constructs
11//!     the final `tower::Service` responsible for handling requests.
12//! *   **[Router]**: Manages the registration and matching of gRPC service methods to HTTP paths.
13//! *   **[Codec]**: Handles the transcoding between HTTP body formats (JSON) and Protocol Buffers.
14//! *   **[errors::GatewayError]**: The canonical error type for the gateway, mapping gRPC status codes to HTTP responses.
15//!
16//! ## Middleware Architecture
17//! The gateway uses `tower::Service` layers to compose functionality. The execution order for an incoming request is:
18//! 1.  **Tracing/Metrics**: Telemetry recording.
19//! 2.  **Error Handling**: Catches internal or upstream errors and formats them (e.g., as JSON).
20//! 3.  **Response Modification**: Late-stage modification of HTTP responses.
21//! 4.  **Header Processing**: Filtering and renaming of incoming/outgoing headers.
22//! 5.  **Metadata Extraction**: Converting headers or context into gRPC metadata.
23//! 6.  **Routing & Auth**: Matching the path and verifying authentication requirements.
24//! 7.  **Dispatch**: Invoking the generated service handler.
25//!
26//! ## Feature Flags
27//! *   `std` (default): Enables standard library features (e.g., `std::error::Error` for `GatewayError`).
28//!     Disable this for `no_std` environments (requires `alloc`).
29//!
30//! ## Integration
31//! This crate is typically used by code generated by `protoc-gen-grpc-gateway-rust`, but can also be used
32//! manually to build custom gateways.
33
34#![doc(html_root_url = "https://docs.rs/grpc-gateway-rust/0.1.1")]
35
36// Re-export the alloc crate for use within derived code.
37#[doc(hidden)]
38pub extern crate alloc;
39
40pub mod codec;
41pub mod defaults;
42pub mod errors;
43pub mod forward;
44pub mod gateway;
45pub mod handlers;
46pub mod layers;
47pub mod metadata;
48#[doc(hidden)]
49pub mod pattern;
50pub mod router;
51pub mod shutdown;
52pub mod utilities;
53
54// Public dependencies re-exported for convenience in generated code.
55pub use bytes;
56pub use http;
57pub use http_body;
58pub use http_body_util;
59pub use tonic;
60pub use tower;
61
62use alloc::vec::Vec;
63
64// Primary public API
65pub use codec::Codec;
66pub use errors::GatewayError;
67pub use gateway::{Gateway, UnescapingMode};
68pub use router::Router;
69
70/// A boxed body that implements `http_body::Body`.
71///
72/// Used as the standard response body type for the gateway to ensure type erasure and compatibility.
73pub type BoxBody = http_body_util::combinators::UnsyncBoxBody<bytes::Bytes, GatewayError>;
74
75/// A generic HTTP request body for the gateway.
76///
77/// The gateway currently buffers the request body into `Vec<u8>` to support
78/// multiple reads during transcoding or inspection.
79pub type GatewayRequest = http::Request<Vec<u8>>;
80
81/// A generic HTTP response body for the gateway.
82pub type GatewayResponse = http::Response<BoxBody>;
83
84/// A generic Result type for gateway operations.
85pub type GatewayResult = Result<GatewayResponse, GatewayError>;
86
87/// A boxed cloneable service for handling gateway requests.
88///
89/// This is the type returned by `Gateway::into_service()` and expected by generated code registries.
90pub type BoxedGatewayService =
91    tower::util::BoxCloneService<http::Request<Vec<u8>>, http::Response<BoxBody>, GatewayError>;
gateway_runtime/lib.rs

gateway_runtime/
lib.rs
