go-grpc-middleware

A collection of reusable gRPC interceptors for Go covering auth, logging, retries, validation, and recovery.

Library
Go
vv1.4.0
6,760 stars
Apache License 2.0

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
70 /100 Good
Development Activity 64
Maintenance 36
Community 80
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
79 /100 Good
Architecture 88
Code Quality 85
Innovation 62
Learning Curve 80

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.

Used by 19 apps in this directory

Go
82%
AGPL 3.0

PeerDB

Data Engineering · Databases

3,315

Postgres-native ETL that streams change data capture in real time to Snowflake, BigQuery, ClickHouse, S3, and Kafka — up to 10x faster than general-purpose pipelines, managed through a familiar Postgres SQL interface.

View details
89
Repo Health
76
Technical
66
Dependency
Built with
Go 82%
TypeScript 11%
Updated 1 weeks ago
Go
90%
AGPL 3.0

Pyroscope

Developer Tools · Devops · Monitoring

11,711

An open-source, horizontally scalable continuous profiling platform that pinpoints CPU, memory, and I/O bottlenecks down to the exact line of code, built by Grafana Labs alongside Loki, Tempo, and Mimir.

View details
92
Repo Health
89
Technical
65
Dependency
Built with
Go 90%
Updated 1 weeks ago
Go
40%
Apache 2.0

Rill

Analytics · Data Engineering

2,985

The fastest BI tool for humans and agents — define metrics, models, and dashboards as code and query them instantly on ClickHouse or DuckDB.

View details
88
Repo Health
88
Technical
65
Dependency
Built with
Go 40%
TypeScript 38%
Svelte 20%
Updated 1 weeks ago
Go
99%
Apache 2.0

SpiceDB

Authentication · Databases · Security

7,202

An open source, Google Zanzibar-inspired authorization database that models permissions as relationships and evaluates fine-grained access checks at massive scale with single-digit millisecond latency.

View details
90
Repo Health
89
Technical
67
Dependency
Built with
Go 99%
Updated 1 weeks ago
Go
99%
Apache 2.0

SpiceDB

Authentication · Databases · Security

7,202

An open source, Google Zanzibar-inspired authorization database that models permissions as relationships and evaluates fine-grained access checks at massive scale with single-digit millisecond latency.

View details
90
Repo Health
89
Technical
67
Dependency
Built with
Go 99%
Updated 1 weeks ago
Go
75%
AGPL 3.0

Teleport

Authentication · Security

21,074

Zero-trust infrastructure access platform that replaces credentials and VPNs with short-lived certificates, SSO, and identity-aware proxies for SSH, Kubernetes, databases, RDP, and AI agents.

View details
94
Repo Health
81
Technical
68
Dependency
Built with
Go 75%
TypeScript 16%
Updated 1 weeks ago
Go
75%
AGPL 3.0

Teleport

Authentication · Security

21,074

Zero-trust infrastructure access platform that replaces credentials and VPNs with short-lived certificates, SSO, and identity-aware proxies for SSH, Kubernetes, databases, RDP, and AI agents.

View details
94
Repo Health
81
Technical
68
Dependency
Built with
Go 75%
TypeScript 16%
Updated 1 weeks ago
Go
95%
Apache 2.0

TiDB

AI Development · Databases

40,715

AI-Native Distributed SQL Database for Agentic Workloads

View details
97
Repo Health
66
Technical
68
Dependency
Built with
Go 95%
Updated 1 weeks ago
Go
97%
BSD 3

Weaviate

Databases · Search

16,940

Open-source vector database combining semantic search, hybrid queries, RAG, and image search in a single cloud-native system built for production scale.

View details
91
Repo Health
85
Technical
68
Dependency
Built with
Go 97%
Updated 1 weeks ago

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers