Crate tonic_rest 

tonic-rest

Runtime types for REST + SSE endpoints generated from protobuf google.api.http annotations.

Part of the tonic-rest ecosystem — define your API once in proto files, get gRPC, REST, and OpenAPI 3.1.

This crate provides the shared types that generated Axum handlers reference at runtime. The companion crate tonic-rest-build generates the handler code at build time.

Key Features

• Google error model — gRPC errors map to structured JSON responses following the Google API error model
• SSE for server streaming — server-streaming RPCs are automatically exposed as Server-Sent Events endpoints
• Request bridging — build_tonic_request forwards headers, extensions (e.g. auth info), and metadata from Axum to Tonic
• Serde adapters — ready-made #[serde(with)] modules for Timestamp, Duration, FieldMask, and proto3 enums
• Zero runtime reflection — all handler code is generated at build time by companion tonic-rest-build

Types

• RestError — Converts tonic::Status to HTTP JSON error responses following the Google API error model
• build_tonic_request — Bridges Axum HTTP requests to tonic::Request, forwarding headers and extensions (e.g., auth info)
• sse_error_event — Formats gRPC errors as SSE events
• grpc_to_http_status / grpc_code_name — Maps all 17 gRPC codes to HTTP status codes and canonical names

Error Response Format

RestError produces JSON responses following the Google API error model:

{
  "error": {
    "code": 404,
    "message": "user not found",
    "status": "NOT_FOUND"
  }
}

SSE error events use the same wrapped format with event: error type:

event: error
data: {"error":{"code":401,"status":"UNAUTHENTICATED","message":"token expired"}}

Serde Adapters

Behind the serde feature (enabled by default), provides #[serde(with)] adapters for prost well-known types:

Adapter	Type	Wire format
timestamp / opt_timestamp	Timestamp / Option<Timestamp>	RFC 3339 ("2025-01-15T09:30:00Z")
duration / opt_duration	Duration / Option<Duration>	Seconds with suffix ("300s")
field_mask / opt_field_mask	FieldMask / Option<FieldMask>	Comma-separated camelCase ("displayName,email")

And the define_enum_serde! macro for proto3 enum fields (which are i32 in prost):

tonic_rest::define_enum_serde!(user_role, crate::UserRole);
// With prefix stripping:
tonic_rest::define_enum_serde!(health_status, crate::HealthStatus, "HEALTH_STATUS_");

Feature Flags

Feature	Default	Description
serde	on	WKT serde adapters + define_enum_serde! macro (adds prost-types, chrono, serde deps)

Quick Start

[dependencies]
tonic-rest = "0.1"

[build-dependencies]
tonic-rest-build = "0.1"

For a complete end-to-end example, see auth-service-rs.

Companion Crates

Crate	Purpose	Cargo section
tonic-rest-core	Shared descriptor types	internal
tonic-rest (this)	Runtime types	[dependencies]
tonic-rest-build	Build-time codegen	[build-dependencies]
tonic-rest-openapi	OpenAPI 3.1 generation	CLI / CI

Compatibility

tonic-rest	tonic	axum	prost-types	MSRV
0.1.x	0.14	0.8	0.14	1.85

License

MIT OR Apache-2.0

---

API Reference

Types

• RestError — Converts tonic::Status to HTTP JSON error responses
• build_tonic_request — Bridges Axum requests to tonic::Request
• sse_error_event — Formats gRPC errors as SSE events
• grpc_to_http_status — Maps gRPC status codes to HTTP status codes
• grpc_code_name — Returns canonical SCREAMING_SNAKE_CASE name for a gRPC code

Usage

[dependencies]
tonic-rest = "0.1"

[build-dependencies]
tonic-rest-build = "0.1"

Companion Crate

Crate	Purpose	Cargo section
tonic-rest (this)	Runtime types	[dependencies]
tonic-rest-build	Build-time codegen	[build-dependencies]

Modules

serde

Serde adapters for prost well-known types and proto3 enums.

Macros

concat_forwarded_headers

Concatenate FORWARDED_HEADERS with extra headers at compile time.

define_enum_serde

Generate #[serde(with)] modules for proto3 enum fields (i32 in prost).

Structs

RestError

REST error wrapper — converts tonic::Status to an HTTP error response.

Constants

CLOUDFLARE_HEADERS

Cloudflare-specific headers for client IP resolution.

FORWARDED_HEADERS

HTTP headers forwarded from Axum to tonic metadata for client context.

Functions

build_tonic_request

Build a tonic::Request from a body, HTTP headers, and an optional extension.

build_tonic_request_simple

Build a tonic::Request without an extension type.

build_tonic_request_with_headers

Build a tonic::Request with a custom set of forwarded headers.

cloudflare_header_names

Return CLOUDFLARE_HEADERS as typed HeaderName values.

forwarded_header_names

Return FORWARDED_HEADERS as typed HeaderName values.

grpc_code_name

Return the canonical SCREAMING_SNAKE_CASE name for a gRPC status code.

grpc_to_http_status

Map gRPC status codes to HTTP status codes.

sse_error_event

Build a structured SSE error event from a tonic::Status.