g2h: gRPC to HTTP Bridge Generator

Seamlessly expose your gRPC services as HTTP/JSON endpoints using Axum

g2h (gRPC-to-HTTP) automatically generates Axum HTTP handlers for your gRPC services, allowing them to be consumed by both gRPC clients and traditional web clients using HTTP/JSON.

Features

• 🔄 Automatic conversion between gRPC and HTTP/JSON
• 🛣️ Creates Axum routes that match gRPC service methods
• 🔌 Works with existing Tonic services with zero modification
• 🧠 Preserves metadata and headers between protocols
• 🚦 Proper error status conversion from gRPC to HTTP
• ✨ NEW: Automatic string enum support for HTTP endpoints

Quick Start

# Cargo.toml
[dependencies]
tonic = "0.13.0"
prost = "0.13.5"
axum = "0.8.3"
http = "1.3.1"
serde = { version = "1.0", features = ["derive"] }

[build-dependencies]
g2h = "0.1.0"
tonic-build = "0.13.0"
prost-build = "0.13.5"

// In your build.rs
use g2h::BridgeGenerator;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Simple approach with default settings
    BridgeGenerator::with_tonic_build()
        .build_prost_config()
        .compile_protos(&["proto/service.proto"], &["proto"])?;
    
    Ok(())
}

// In your main.rs - Create an Axum app with your gRPC service
let my_service = MyServiceImpl::default();
let http_router = my_service_handler(my_service);

let app = Router::new().nest("/api", http_router);

Now your service is accessible through both gRPC and HTTP:

POST /api/package.ServiceName/MethodName
Content-Type: application/json

{
  "field": "value"
}

Documentation

For complete usage examples and API documentation:

• Detailed Usage Guide
• Documentation
• Example Project

How It Works

g2h extends the standard gRPC code generation pipeline to create additional Axum router functions. These routers map HTTP POST requests to their corresponding gRPC methods, handling serialization/deserialization and status code conversion automatically.

String Enum Support

Enable automatic string enum deserialization for more user-friendly HTTP APIs:

// build.rs with string enum support
use g2h::BridgeGenerator;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    BridgeGenerator::with_tonic_build()
        .build_prost_config()
        .with_string_enums()  // Enable automatic enum string support
        .compile_protos(&["proto/service.proto"], &["proto"])?;
    
    Ok(())
}

Now your HTTP endpoints accept both string and integer enum values:

// ✅ Both formats work
{
  "status": "ACTIVE",        // String format (user-friendly)
  "priority": 1              // Integer format (still supported)
}

Key Benefits

• Drop-in replacement: Just add .with_string_enums() to your existing build chain
• No feature flags: Works out of the box
• No manual includes: Enum deserializers are automatically included
• Dynamic: Works with any protobuf package structure
• Chainable API: Follows the same pattern as standard prost_build configuration

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Built by Human, Documented by LLM.