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

Middleware 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.