How elfpuck/grpc-http works
Project Type and Purpose
• This is an open‐source “developer tool” consisting of three protoc plugins (protoc-gen-go-http, protoc-gen-go-model, protoc-gen-swagger) plus a small Go runtime library (elfHttp) that wires up generated HTTP endpoints to a gRPC backend.
• Its purpose is to take .proto definitions and:
• generate Go model structs,
• generate HTTP gateway handlers,
• generate Swagger OpenAPI specs,
all in one protoc invocation.
File Structure
• Top level:
• elfHttp/ ← Go library providing HTTP server, routing, service registration
• protoc-gen-go-http/
• protoc-gen-go-model/
• protoc-gen-swagger/
• Each plugin folder contains a main.go (the plugin entry point) + tpl.go (the code templates).
• There’s a makefile and go.mod/go.sum for build and dependency management.
README Insights
• Installation: “go get” each plugin.
• Invocation: protoc --go_out=plugins=grpc --go-http_out=... --go-model_out=... --swagger_out=... foo.proto
• Usage snippet shows how the generated HTTP code calls into elfHttp.New(), registers services, and runs on an HTTP port.
• Swagger customization comes via protobuf annotations in swagger.proto.
Main Components and Their Relationships
A. Build‐Time Code Generation Flow
1. Input:
• .proto files (with optional swagger options)
2. Executor:
• protoc compiler
• Plugins invoked in order:
• protoc-gen-go (generates gRPC server & client stubs)
• protoc-gen-go-http
• protoc-gen-go-model
• protoc-gen-swagger
3. Plugins:
• Read the FileDescriptorSet from protoc stdin
• Apply Go template code (tpl.go)
• Emit .pb.go, _http.pb.go, _model.pb.go, swagger.json files
4. Output:
• Generated Go source code & swagger/spec files
B. Runtime HTTP ↔ gRPC Gateway Flow
1. elfHttp Library:
• elfHttp.New() creates a router + HTTP server
• e.Service("demo") returns a ServiceRegistrar
• Generated code calls RegisterXxxFromEndpoint(service, addr)
2. HTTP Server:
• Incoming HTTP requests → elfHttp routes → marshals to gRPC calls
3. gRPC Backend:
• gRPC server listens on its own port
• Business logic implemented in your service
4. Swagger UI / Spec:
• swagger.json served or embedded for client consumption
Architectural Patterns and Design Principles
• Plugin Architecture: each protoc‐gen‐XXX is a standalone executable conforming to protoc plugin protocol.
• Template‐Driven Codegen: separation of core logic (main.go) and templates (tpl.go).
• Layered Runtime: HTTP layer (elfHttp) → gRPC stub → business handlers.
• Single Responsibility: each plugin does one type of generation.
Elements
• Rectangles for processes (protoc, plugins, HTTP server, gRPC server)
• Rounded rectangles for libraries (elfHttp)