Crate gateway_runtime 

Gateway Runtime

Overview

The gateway-runtime crate provides the essential runtime components for the grpc-gateway-rust ecosystem. It acts as the bridge between HTTP/JSON requests and gRPC services, handling routing, transcoding, authentication, and middleware orchestration.

Core Components

• Gateway: The primary builder and entry point. It orchestrates the middleware stack and constructs the final tower::Service responsible for handling requests.
• Router: Manages the registration and matching of gRPC service methods to HTTP paths.
• Codec: Handles the transcoding between HTTP body formats (JSON) and Protocol Buffers.
• errors::GatewayError: The canonical error type for the gateway, mapping gRPC status codes to HTTP responses.

Middleware Architecture

The gateway uses tower::Service layers to compose functionality. The execution order for an incoming request is:

1. Tracing/Metrics: Telemetry recording.
2. Error Handling: Catches internal or upstream errors and formats them (e.g., as JSON).
3. Response Modification: Late-stage modification of HTTP responses.
4. Header Processing: Filtering and renaming of incoming/outgoing headers.
5. Metadata Extraction: Converting headers or context into gRPC metadata.
6. Routing & Auth: Matching the path and verifying authentication requirements.
7. Dispatch: Invoking the generated service handler.

Feature Flags

• std (default): Enables standard library features (e.g., std::error::Error for GatewayError). Disable this for no_std environments (requires alloc).

Integration

This crate is typically used by code generated by protoc-gen-grpc-gateway-rust, but can also be used manually to build custom gateways.

Re-exports

pub use codec::Codec;

pub use errors::GatewayError;

pub use gateway::Gateway;

pub use gateway::UnescapingMode;

pub use router::Router;

pub use bytes;

pub use http;

pub use http_body;

pub use http_body_util;

pub use tonic;

pub use tower;

Modules

codec

Codec

defaults

Default Handlers

errors

Errors

forward

Forward

gateway

Gateway Builder and Service

handlers

Custom Handlers

layers

metadata

Metadata

router

Router

shutdown

Shutdown

utilities

Utilities

Type Aliases

BoxBody

A boxed body that implements http_body::Body.

BoxedGatewayService

A boxed cloneable service for handling gateway requests.

GatewayRequest

A generic HTTP request body for the gateway.

GatewayResponse

A generic HTTP response body for the gateway.

GatewayResult

A generic Result type for gateway operations.