tonic-rest-build

Build-time REST codegen from protobuf google.api.http annotations for Tonic + Axum.

Reads a compiled proto FileDescriptorSet, extracts google.api.http annotations, and generates Axum route handler code that calls through Tonic service traits — keeping proto files as the single source of truth for both gRPC and REST APIs.

Quick Start

[dependencies]
tonic-rest = "0.1"

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

Zero-config build.rs — auto-discovers packages from the descriptor set:

use tonic_rest_build::{RestCodegenConfig, generate, dump_file_descriptor_set};

const PROTO_FILES: &[&str] = &["proto/service.proto"];
const PROTO_INCLUDES: &[&str] = &["proto"];

fn main() {
    let out_dir = std::env::var("OUT_DIR").unwrap();
    let descriptor_path = format!("{out_dir}/file_descriptor_set.bin");

    // Phase 1: Compile protos → descriptor set
    let descriptor_bytes = dump_file_descriptor_set(PROTO_FILES, PROTO_INCLUDES, &descriptor_path);

    // Phase 2: Compile protos → Rust (prost/tonic)
    let mut config = prost_build::Config::new();
    config.file_descriptor_set_path(&descriptor_path);
    config.compile_protos(PROTO_FILES, PROTO_INCLUDES).unwrap();

    // Phase 3: Generate REST routes
    let rest_config = RestCodegenConfig::new();
    let code = generate(&descriptor_bytes, &rest_config).unwrap();
    std::fs::write(format!("{out_dir}/rest_routes.rs"), code).unwrap();
}

Configuration

Explicit package mapping (e.g., when using pub use v1::*; re-exports):

let config = RestCodegenConfig::new()
    .package("auth.v1", "auth")
    .package("users.v1", "users")
    .wrapper_type("crate::core::Uuid")
    .extension_type("my_app::AuthInfo")
    .public_methods(&["Login", "SignUp"])
    .sse_keep_alive_secs(30);

RestCodegenConfig Options

Feature Flags

Serde Attribute Helper

Auto-discover proto fields and apply #[serde(with)] attributes:

use tonic_rest_build::configure_prost_serde;

configure_prost_serde(
    &mut config,
    &descriptor_bytes,
    PROTO_FILES,
    "crate::serde_wkt",
    &[(".google.protobuf.Timestamp", "opt_timestamp")],
    &[(".my.v1.UserRole", "user_role")],
);

Runtime Dependencies

The generated handler code references types from these crates — ensure they are in your [dependencies]:

Generated Code

For each service with HTTP annotations:

• {service}_rest_router(service: Arc<S>) -> Router — route registration
• Per-method handler functions with proper extractors
• PUBLIC_REST_PATHS: &[&str] — paths that bypass authentication middleware
• all_rest_routes(...) — combined router for all services

Handler Variants

Planned

• additional_bindings: Proto HttpRule.additional_bindings (multiple REST mappings per gRPC method) is not supported. Only the primary HTTP binding is processed.
• Partial body selectors: Only body: "*" (full body) and body: "" (no body) are supported. The body: "field_name" partial body binding from the gRPC-HTTP transcoding spec is not implemented.
• Repeated WKT fields: configure_prost_serde does not wire serde adapters for lists of well-known types (e.g. repeated google.protobuf.Timestamp). Single fields of these types work correctly.

For a complete end-to-end example with proto files, build.rs, REST handlers, and OpenAPI generation, see auth-service-rs.

Companion Crates

Compatibility