If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/grpc-ecosystem/go-grpc-middleware shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 6w ago
• 52+ active contributors
• Distributed ownership (top contributor 15% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live grpc-ecosystem/go-grpc-middleware repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/grpc-ecosystem/go-grpc-middleware.

What it runs against: a local clone of grpc-ecosystem/go-grpc-middleware — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in grpc-ecosystem/go-grpc-middleware | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 74 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of grpc-ecosystem/go-grpc-middleware. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/grpc-ecosystem/go-grpc-middleware.git
#   cd go-grpc-middleware
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of grpc-ecosystem/go-grpc-middleware and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "grpc-ecosystem/go-grpc-middleware(\\.git)?\\b" \\
  && ok "origin remote is grpc-ecosystem/go-grpc-middleware" \\
  || miss "origin remote is not grpc-ecosystem/go-grpc-middleware (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 74 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~44d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/grpc-ecosystem/go-grpc-middleware"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

go-grpc-middleware is a production-grade library providing ready-to-use gRPC interceptors for Go that implement cross-cutting concerns like authentication, logging, retries, rate limiting, and metrics collection. It enables developers to chain multiple interceptors on gRPC servers and clients to handle observability (tracing, metrics, logs) and common patterns (auth, recovery, validation) consistently across microservices without boilerplate. Monorepo structure: interceptors/ directory contains feature packages (auth, logging, recovery, retry, etc.), each with implementation (*.go), tests (*_test.go), and examples (*_test.go). examples/ contains full server/client demos showing real interceptor chaining. Tooling managed via .bingo/ for reproducible builds across contributors.

Go developers building gRPC microservices who need to add authentication, distributed tracing, structured logging, and metrics instrumentation without writing interceptor logic from scratch. Used by teams deploying multiple services that need consistent observability and security middleware across their RPC layer.

Actively maintained and production-ready. The repo has official gRPC ecosystem backing (grpc-ecosystem org), GitHub Actions CI/CD pipeline (.github/workflows/go.yaml), comprehensive test coverage (*_test.go files throughout), and uses bingo for reproducible tooling. v2 release is stable with regular updates.

Low risk for stable use cases. The project is well-established with gRPC ecosystem governance. Main considerations: v2 breaking changes from v1 require migration, and some advanced interceptors may require knowledge of gRPC internals. Dependency surface is small (primarily gRPC, grpc/protobuf, and optional observability libraries), reducing supply chain risk.

Active maintenance with focus on gRPC compatibility and observability features. The example server (examples/server/main.go) demonstrates integration with OpenTelemetry and Prometheus. Recent work involves ensuring interceptor chains work correctly with modern gRPC features and tracing standards.

git clone https://github.com/grpc-ecosystem/go-grpc-middleware.git
cd go-grpc-middleware
make help  # See available build targets
cd examples
go mod tidy && go run ./server/main.go  # Start example gRPC server in one terminal
go run ./client/main.go  # Run client in another

Daily commands: See Makefile targets: make build (compile), make test (run tests), make lint (golangci-lint), make examples (build example binaries). Use .bingo/Variables.mk for reproducible tool versions. Example server runs as: cd examples && go run ./server/main.go.

• interceptors/auth/auth.go: Reference implementation showing how to write both unary and stream server/client interceptors with proper context and error handling.
• examples/server/main.go: Demonstrates real-world interceptor chaining with metrics, logging, auth, recovery, and OpenTelemetry integration.
• Makefile: Defines build, test, lint, and code generation targets; essential for understanding the development workflow.
• .bingo/bingo.mod: Manages reproducible versions of linters, code generators, and build tools used by all contributors.
• go.mod: Declares minimal dependencies (gRPC, protobuf) and allows users to see exactly what this library requires.
• interceptors/logging/logging.go: Shows how to integrate structured logging with request/response lifecycle and context extraction patterns.

To add a new interceptor: create interceptors/newfeature/newfeature.go with UnaryServerInterceptor and StreamServerInterceptor functions following patterns in interceptors/auth/auth.go. Add tests as newfeature_test.go. Document in doc.go. For changes to existing interceptors, modify files in their package directory (e.g., interceptors/logging/ for logging changes).

1. gRPC interceptor signatures differ between unary/stream and server/client—always check the pattern you need in an existing interceptor. 2) Context cancellation must be respected; interceptors receive context from gRPC framework and must not drop deadlines. 3) Proto generation requires .proto files and the bingo-managed protoc-gen-go and protoc-gen-go-grpc tools—don't use system-wide versions. 4) The examples depend on external services (Jaeger for tracing) when run in full observability mode; check examples/README.md for setup.

• gRPC Interceptors (Unary vs Stream) — Foundational to this entire library—you must understand when to use UnaryServerInterceptor (single RPC) vs StreamServerInterceptor (bidirectional streams), and how signature differs between server and client.
• Interceptor Chaining — This repo's primary capability is composing multiple interceptors (auth, logging, metrics) into a single chain via ChainUnaryInterceptor—order matters and early interceptors wrap later ones.
• Context Propagation & Metadata — gRPC passes request metadata (headers, auth tokens) and trace context through Go's context.Context; interceptors must read/modify it correctly to implement auth and observability.
• Token Bucket Rate Limiting — The retry package uses token bucket algorithm internally to implement rate limiting on retried requests; understanding this pattern helps debug throttling behavior.
• Exemplar-Based Tracing (Metrics ↔ Traces Correlation) — Advanced observability feature shown in examples where Prometheus metrics include trace IDs as exemplars, enabling direct jumps from metric alerts to distributed traces.
• Selector Pattern (Conditional Interceptor Application) — Allows you to apply interceptors only to certain RPC methods (e.g., skip auth on /health checks)—key for production flexibility without forking interceptor logic.
• Panic Recovery in RPC Handlers — The recovery interceptor catches panics in RPC handler goroutines and converts them to gRPC errors, preventing server crashes—critical for production stability.

• grpc/grpc-go — The core gRPC Go library that this middleware builds upon; defines the interceptor interfaces and base server/client abstractions.
• grpc-ecosystem/grpc-opentelemetry-go — Companion observability project providing gRPC support for OpenTelemetry tracing; often chained with middleware from this repo.
• grpc-ecosystem/go-grpc-prometheus — Dedicated metrics interceptor for Prometheus that works alongside this middleware for production monitoring.
• open-telemetry/opentelemetry-go — Parent observability framework that this repo's tracing examples integrate with for distributed tracing.
• grpc/grpc-gateway — Sibling gRPC ecosystem project for exposing gRPC services via HTTP/REST; middleware from this repo can wrap gRPC-gateway backends.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for interceptor chaining across auth, logging, and retry middleware

The repo currently has unit tests for individual interceptors (auth_test.go, client_test.go) but lacks integration tests demonstrating real-world scenarios where multiple middleware are chained together. This is critical because interceptor composition is the core value proposition of this library. New contributors can add tests that verify auth → logging → retry chains work correctly with gRPC unary and streaming calls.

• [ ] Create new file: interceptors/integration_test.go or interceptors/chain_integration_test.go
• [ ] Add test cases for unary interceptor chains: auth.UnaryServerInterceptor() → logging → retry
• [ ] Add test cases for streaming interceptor chains with the same middleware composition
• [ ] Reference existing examples in examples/server/main.go and examples/client/main.go to ensure compatibility
• [ ] Verify tests pass with 'make test' and update Makefile if needed

Add missing CI workflow for protobuf compatibility and code generation validation

The repo has buf.yaml and buf.lock files indicating proto file management, and .bingo/ contains protoc-gen-go and protoc-gen-go-grpc tools, but .github/workflows/go.yaml doesn't show explicit proto code generation validation. A new workflow should validate that proto definitions match generated Go code and prevent breaking changes to the gRPC API surface.

• [ ] Create new file: .github/workflows/proto.yaml
• [ ] Add steps to run 'buf lint' on all proto files
• [ ] Add steps to regenerate Go code from protos using protoc and verify no diff from committed code
• [ ] Ensure buf.lock is validated to prevent accidental dependency drift
• [ ] Add job status badge to README.md similar to existing 'go' badge

Expand logging middleware examples with structured logging output validation tests

The repo has examples/logging/examples/ with kit, log, logr, and logrus implementations, but no tests validating the actual log output format and field presence. New contributors should add example_test.go files that verify each logging implementation produces correct structured logs (JSON format, field names, values) when intercepting gRPC calls, ensuring consistency across logger backends.

• [ ] Review existing: interceptors/logging/examples/logrus/example_test.go as reference
• [ ] Add tests to: interceptors/logging/examples/kit/example_test.go to validate kit logger output
• [ ] Add tests to: interceptors/logging/examples/log/example_test.go to validate stdlib log output
• [ ] Add tests to: interceptors/logging/examples/logr/example_test.go to validate logr output
• [ ] Verify each test captures log output and asserts presence of fields like method, duration, status_code, error

• Add comprehensive godoc examples to interceptors that lack them (e.g., retry package). Start by examining interceptors/auth/examples_test.go pattern and copying it to packages missing example_test.go files.
• Expand test coverage for stream interceptors in packages like interceptors/retry/—check *_test.go files and look for functions with no stream-variant tests.
• Add middleware-specific integration tests that chain 3+ interceptors together (auth + logging + metrics) in examples/ to catch real-world interaction bugs.

The go-grpc-middleware repository demonstrates a reasonable security posture as a middleware library. The codebase appears to be well-structured with dedicated security components (auth, validation). However, there are minor concerns: potential exposure of environment files, absence of a security policy document, and incomplete visibility of dependency versions. The project is a middleware library with no direct external-facing infrastructure concerns (no Docker, exposed ports, or obvious data handling). Primary recommendations include establishing a security policy, ensuring all dependencies are regularly audited, and verifying that authentication and validation implementations follow cryptographic best practices.

• Low · Potential Plaintext Credentials in Environment Files — .bingo/variables.env. The file structure includes '.bingo/variables.env' which may contain sensitive configuration or credentials. Environment files should never be committed to version control. Fix: Ensure .env files are added to .gitignore. Use secure secret management systems (e.g., environment variables, secret vaults) instead of committing credentials to the repository.
• Low · Missing Security Policy Documentation — Repository root. No visible SECURITY.md or security policy document found in the repository root. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file documenting the security policy, supported versions, and responsible disclosure process. Add security contact information.
• Low · Incomplete Dependency Information — go.mod, go.sum. The provided go.mod/go.sum files are not fully visible in the analysis. Cannot fully verify if all dependencies are from trusted sources and free from known vulnerabilities. Fix: Regularly run 'go list -json -m all' and use tools like 'nancy' or 'go vulnerability check' to identify vulnerable dependencies. Keep dependencies updated to their latest secure versions.
• Low · Limited Visibility into Authentication Implementation — interceptors/auth/. While the repository includes authentication middleware (interceptors/auth/), the actual implementation details weren't provided for full security review of auth mechanisms. Fix: Ensure all authentication mechanisms follow industry best practices: validate tokens cryptographically, implement proper scope checking, use TLS for all communications, and avoid hardcoding any credentials.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.