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.