go-grpc-middleware

go-grpc-middleware is the reference collection of gRPC interceptors for Go, offering ready-made server- and client-side middleware for the cross-cutting concerns every gRPC service eventually needs: authentication, structured logging, retries with backoff, rate limiting, request validation, timeouts, panic recovery, and method selection. Rather than writing interceptor boilerplate from scratch, teams import the pieces they need from interceptors/ and chain them with gRPC’s native ChainUnaryInterceptor/ChainStreamInterceptor.

The project is organized as a multi-module repository: the core v2 module keeps dependencies minimal, while heavier integrations like the Prometheus metrics provider live in their own versioned providers/ module so consumers don’t pull in dependencies they don’t use. Originally created in 2015 and now maintained under the grpc-ecosystem GitHub organization, it has become a de facto standard for Go microservices built on gRPC, with adapters for popular logging libraries (zap, logrus, slog, zerolog) provided as copyable examples rather than direct dependencies.

What You Get

• Auth interceptor - pluggable AuthFunc-based authentication for unary and streaming RPCs, with per-service override support.
• Logging interceptor - structured per-request logging with adapters demonstrated for zap, logrus, slog, and zerolog.
• Retry interceptor - client-side retry with configurable backoff strategies and gRPC status-code-aware retry policies.
• Validator interceptor - codegen-driven inbound message validation sourced from .proto file options via protovalidate.
• Recovery interceptor - converts panics inside handlers into proper gRPC errors instead of crashing the server.
• Selector interceptor - conditionally applies other interceptors based on service or method matching.
• Prometheus provider - a separately versioned module exposing client- and server-side gRPC metrics with exemplar support.

Common Use Cases

• Standardizing auth across microservices - a platform team applies one AuthFunc-based interceptor across dozens of internal gRPC services instead of reimplementing token checks in each.
• Correlated observability - engineers chain the logging interceptor with OpenTelemetry tracing so every log line carries a trace ID for cross-service debugging.
• Resilient client calls - a client wraps outbound calls with the retry interceptor to transparently handle transient UNAVAILABLE errors from downstream services.
• Crash-safe handlers - a production service adds the recovery interceptor as the last link in its chain so a single panicking handler doesn’t take down the whole process.
• Proto-driven validation - a team annotates .proto messages with validation constraints and lets the validator interceptor reject malformed requests before they reach business logic.

Under The Hood

Architecture The repository is a layered, multi-module Go codebase rather than a single package: the root module (import path ending /v2, defined in go.mod) holds the core middleware package plus per-concern interceptor packages under interceptors/ (auth, logging, retry, recovery, validator, ratelimit, selector, timeout, realip, protovalidate), each independent and importable on its own. Interceptors implement gRPC’s native grpc.UnaryServerInterceptor/StreamServerInterceptor (and client equivalents) function types directly, so they compose via gRPC’s built-in ChainUnaryInterceptor/ChainStreamInterceptor with no custom chaining machinery of its own (v1’s homegrown chaining was deliberately removed in v2). A shared Reporter/CallMeta abstraction in interceptors/reporter.go lets logging and metrics interceptors share common per-call bookkeeping logic. Heavier, more opinionated integrations (Prometheus metrics) are isolated into their own providers/ Go module with independent versioning, keeping the core module’s dependency footprint deliberately slim — a design choice that directly shapes how the project avoids dependency bloat as it grows.

Tech Stack The project targets modern Go (1.24, supporting the three latest major Go releases per its README) and depends on google.golang.org/grpc as its only mandatory runtime dependency for the core module, plus google.golang.org/protobuf and buf.build/go/protovalidate for the protovalidate-based validator interceptor. Testing relies on github.com/stretchr/testify. The providers/prometheus module additionally depends on the official Prometheus Go client. Build and release tooling is Makefile-driven with buf used for protobuf/CEL-based validation code generation, and dependency versions are pinned tightly in go.mod/go.sum with Dependabot keeping them current.

Code Quality The repository is extensively tested — 43 _test.go files across its interceptor packages, including dedicated examples_test.go files that double as executable documentation for each interceptor. CI (.github/workflows/go.yaml) runs both a dedicated lint/vet job (make lint) and a unit test matrix across oldstable/stable Go versions on both Ubuntu and macOS runners, giving reasonable confidence in cross-platform correctness. Error handling is idiomatic Go, using gRPC’s typed codes/status package throughout rather than generic errors, and public APIs favor small, composable interfaces (AuthFunc, Reporter, CallOption) over large configuration structs.

What Makes It Unique Unlike a single logging or auth library, go-grpc-middleware’s distinguishing choice is architectural: splitting itself into a lean core module plus independently versioned provider modules, so adopting Prometheus metrics doesn’t force every consumer’s core interceptor dependency tree to grow. Its v2 rewrite also deliberately declines to reinvent interceptor chaining now that gRPC-Go ships native chaining support, and it treats logger adapters (zap, slog, zerolog, logrus) as copyable example code rather than direct imports — avoiding the classic ‘depend on every logging library at once’ problem that afflicts many middleware collections.