protoc-gen-httpgo

protoc-gen-httpgo is a powerful protoc plugin designed to generate native HTTP server and client code directly from your Protocol Buffers (proto) files. This tool serves as a lightweight, high-performance alternative to grpc-gateway, allowing direct HTTP serving from applications without the overhead typically associated with proxy layers.

Key Benefits

• Eliminate Proxy Overhead: Serve HTTP requests directly from the application, streamlining performance by removing the need for a transcoding layer.
• Dual-Stack Support: Utilize both HTTP and gRPC protocols concurrently without significant performance degradation.
• Protobuf-First Design: Create APIs using Protobuf while fully leveraging the capabilities of the HTTP ecosystem.

Performance Highlights

The plugin demonstrates significant performance gains compared to grpc-gateway:

• 30% Faster: Achieves higher speed by eliminating intermediary steps.
• 95% Reduction in Memory Overhead: Operates with minimal resource usage, enhancing efficiency across applications.

Feature Set

• Comprehensive Code Generation: Automatically generates both server and client codes, supporting various frameworks:
  • Integrates with gin (server only).
  • Works seamlessly with both fasthttp and net/http.
• Flexible Marshaling/Unmarshaling Options:
  • Default behavior utilizes the native encoding/json.
  • Optionally adopt protojson for enhanced protocol buffer support.
• Standardized Path Mapping: Leverages Google API's http rule definitions for path configurations, facilitating flexibility in endpoint management.
• Automatic URI Generation: Simplifies endpoint creation for developers.
• Support for Various Data Types: Handles a wide range of data types in path parameters efficiently.
• Middleware Compatibility: Easily integrates custom middleware to enhance functionality and manage application behavior.
• File Handling: Supports multipart forms for file uploads, allowing seamless document transfer.
• Zero Additional Dependencies: The generated code remains lean without unnecessary library requirements.

Get Started

To use this plugin, define RPC methods in your proto files. For example:

import "google/api/annotations.proto";

service TestService {
  rpc TestMethod (TestMessage) returns (TestMessage) {
    option (google.api.http) = {
      get: "/v1/test/{field1}"
    };
  }
}

message TestMessage {
  string field1 = 1;
  string field2 = 2;
}

To generate code from your proto definition, run:

protoc -I=. --httpgo_out=paths=source_relative:. example/proto/example.proto

Explore parameters for customization in code generation, focusing on options such as marshaller, only, and library for precise control over functionality.

Middleware Examples

Custom middleware can be incorporated to log requests, manage timeouts, or enforce headers. For example, middleware definitions can facilitate request logging:

func LoggerServerMiddleware(ctx context.Context, arg any, next func(ctx context.Context, arg any) (resp any, err error)) (resp any, err error) {
  log.Println("server request", arg)
  resp, err = next(ctx, arg)
  log.Println("server response", resp)
  return resp, err
}

Future Improvements

Future updates will include the implementation of additional web servers, dependency management tools, websocket support, and enhanced middleware examples to ensure applicability across various production environments.

To view example implementations and additional aspects of the library, please check the example directory. This plugin provides comprehensive tools to facilitate seamless HTTP server and client code generation from Protocol Buffers, enhancing both performance and developer productivity.