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/grpc-go 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 2d ago
• 20 active contributors
• Distributed ownership (top contributor 20% 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/grpc-go repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/grpc/grpc-go.

What it runs against: a local clone of grpc/grpc-go — 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/grpc-go | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of grpc/grpc-go. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/grpc/grpc-go.git
#   cd grpc-go
#
# 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/grpc-go and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "grpc/grpc-go(\\.git)?\\b" \\
  && ok "origin remote is grpc/grpc-go" \\
  || miss "origin remote is not grpc/grpc-go (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "grpc.go" \\
  && ok "grpc.go" \\
  || miss "missing critical file: grpc.go"
test -f "balancer/balancer.go" \\
  && ok "balancer/balancer.go" \\
  || miss "missing critical file: balancer/balancer.go"
test -f "internal/transport/http2_server.go" \\
  && ok "internal/transport/http2_server.go" \\
  || miss "missing critical file: internal/transport/http2_server.go"
test -f "codes/codes.go" \\
  && ok "codes/codes.go" \\
  || miss "missing critical file: codes/codes.go"
test -f "internal/resolver/resolver.go" \\
  && ok "internal/resolver/resolver.go" \\
  || miss "missing critical file: internal/resolver/resolver.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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/grpc-go"
  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).

grpc-go is the official Go implementation of gRPC, a high-performance RPC framework built on HTTP/2 that enables efficient, language-agnostic service-to-service communication. It provides server and client libraries, protocol buffer code generation (protoc-gen-go-grpc), and advanced features like load balancing, interceptors, keepalive, and authorization. The project powers production gRPC deployments across organizations needing low-latency, multiplexed RPC over HTTP/2. Monorepo structure: root-level packages (grpc, admin, attributes, authz, balancer, connectivity, credentials, encoding, health, interop, metadata, resolver, stats, tap, test) contain core gRPC functionality; cmd/protoc-gen-go-grpc/ holds the protoc plugin; Documentation/ has architecture guides; examples/ provides runnable demos; .github/workflows orchestrates CI, coverage, and releases. Admin and authz are separate concerns with their own test suites.

Go backend engineers and platform teams building microservices, gRPC API servers, and service meshes who need native Go gRPC bindings; also protocol buffer users who need Go code generation for gRPC services via protoc-gen-go-grpc.

Highly mature and production-ready. The repo shows extensive CI/CD coverage (.github/workflows for testing, coverage, codeql, release automation), comprehensive test suites in every subdirectory, active development (recent commits visible from release workflows), and multi-year stability as the canonical Go gRPC implementation backed by Google. This is battle-tested infrastructure code.

Low risk for core functionality, but watch for: large dependency tree (protobuf, genproto, golang.org/x/net/sys/text as indirect deps), Go version constraint requiring latest two major releases (currently 1.25.0), and potential breaking changes tracked across versions (see Documentation/versioning.md). Dependency updates are managed via .github/workflows/deps.yml, suggesting active maintenance burden.

Active maintenance across multiple areas: release pipeline (release.yml), dependency updates (deps.yml), PR validation and testing (pr-validation.yml, testing.yml), security scanning (codeql-analysis.yml), and stale issue management (stale.yml). Recent focus on authorization (authz/ with audit logging support in authz/audit/), admin APIs (admin/test/), and code quality (codecov.yml integration).

git clone https://github.com/grpc/grpc-go.git
cd grpc-go
go mod download
go test ./...

For development, ensure Go 1.23+ is installed (two latest major releases). Optionally set GRPC_GO_LOG_VERBOSITY_LEVEL and GRPC_GO_LOG_SEVERITY_LEVEL environment variables for debugging.

Daily commands: Run the gRPC test suite: make test (via Makefile). Run examples: cd examples && go run ... for specific example. For protoc code generation: protoc --go_out=. --go-grpc_out=. example.proto (requires protoc and protoc-gen-go-grpc binary installed via go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest).

• grpc.go — Main entry point and core gRPC server/client API—defines Server, ClientConn, and Dial interfaces that all contributors must understand
• balancer/balancer.go — Load balancer abstraction layer—foundational for understanding connection management and endpoint selection strategies
• internal/transport/http2_server.go — HTTP/2 transport implementation for servers—critical for understanding frame handling and streaming semantics
• codes/codes.go — gRPC status codes and error handling—every RPC response flows through this, essential for error contract compliance
• internal/resolver/resolver.go — Service discovery and endpoint resolution—core to how gRPC locates and routes to backend services
• metadata/metadata.go — Request/response metadata handling—critical for headers, trailers, and context propagation across RPC boundaries

Add a new Load Balancer Strategy

1. Create a new directory in balancer/ matching your strategy name (e.g., balancer/customlb/) (balancer/customlb/customlb.go)
2. Implement the balancer.Balancer interface with UpdateClientConnState and Close methods (balancer/customlb/customlb.go)
3. Implement a Picker that satisfies balancer.Picker, returning SubConns for each Pick call (balancer/customlb/customlb.go)
4. Register your balancer via balancer.Register() in init() to make it discoverable by name (balancer/customlb/customlb.go)
5. Add end-to-end tests in *_ext_test.go verifying balancer selection and failover behavior (balancer/customlb/customlb_ext_test.go)

Add a new Server Interceptor (Middleware)

1. Define a UnaryServerInterceptor or StreamServerInterceptor function matching the interface signature (myinterceptor/interceptor.go)
2. Call handler() or call the stream handler within your interceptor to execute the RPC (myinterceptor/interceptor.go)
3. Register interceptor with NewServer() via UnaryInterceptor() or StreamInterceptor() ServerOptions (your_server_setup.go)
4. Test the interceptor with a test server using credentials and a test client calling it (myinterceptor/interceptor_test.go)

Add a new Resolver (Service Discovery Integration)

1. Create resolver directory (e.g., resolver/custom/) and implement resolver.Resolver interface (resolver/custom/custom.go)
2. Implement ResolveNow() to fetch endpoints and UpdateState() to notify ClientConn of changes (resolver/custom/custom.go)
3. Implement a builder.Builder with Scheme() and Build() methods to construct your resolver (resolver/custom/custom.go)
4. Register builder via resolver.Register() in init(), then Dial with target://scheme/endpoint (resolver/custom/custom.go)

Add Authorization Policy Enforcement

1. Define your RBAC policy in a YAML/JSON file following the CEL-based policy format (your_policy.yaml)
2. Create an authz.Evaluator using NewStaticAuthzPolicies or a policy engine that parses your policy (authz/custom_policy.go)
3. Register the evaluator with NewServerWithAuthz() or inject via interceptor in server options (your_server_setup.go)
4. Optionally add audit logging by implementing authz/audit/AuditLogger interface (authz/custom_audit.go)

• HTTP/2 — Provides multiplexed bidirectional streaming, header compression (HPACK), and efficient connection reuse—foundational to gRPC's low-latency RPC design
• Protocol Buffers — Efficient serialization format; gRPC code generation (protoc-gen-go-grpc) automates stub creation and ensures type safety
• Load Balancer & Resolver Abstraction — Decouples service discovery, endpoint selection, and health checking—enables pluggable strategies (round-robin, ring-hash, custom) without core changes
• Context (Go stdlib) — Carries deadlines, cancellation, and metadata across RPC call chains—essential for timeout propagation and interceptor chaining

• HTTP/2 over custom binary protocol

  • Why: Standards compliance, proxy/firewall compatibility, and leverage of existing HTTP infrastructure
  • Consequence: Slightly higher overhead than hand-rolled binary; benefits in operability outweigh performance cost for most use cases

• Pluggable balancer architecture

  • Why: Allows diverse routing strategies without modifying core; users can implement custom business logic
  • Consequence: API complexity and potential for misconfiguration if custom balancers not properly tested

• Server-side interceptor chains (not filtering layer)

  • Why: Full RPC method visibility enables fine-grained control (logging, auth, metrics) while remaining composable
  • Consequence: Interceptor order matters; multiple interceptors can degrade performance if not optimized

• Metadata as separate concept (not in message)

  • Why: Allows protocol-level headers/trailers independent of payload; supports HTTP semantics
  • Consequence: Users must explicitly manage context propagation; accidental loss of metadata if context not threaded properly

• HTTP/1.1 support (HTTP/2 only)
• Built-in request retrying at transport level (left to interceptors and custom balancer logic)
• Automatic message compression negotiation (compression must be explicitly enabled per codec)
• Client-side authentication plugins (users implement via credentials and interceptors)
• Distributed tracing (OpenTelemetry integration is external)
• Real-time message streaming over REST (gRPC is binary-first; REST

Environment variables: GRPC_GO_LOG_VERBOSITY_LEVEL and GRPC_GO_LOG_SEVERITY_LEVEL control logging; must be set before import to take effect. Go version constraint: code requires two latest major Go releases (1.24+); older versions will fail mysteriously. Port conflicts: tests use hardcoded ports; running tests in parallel on same machine may cause flakes. Protoc plugin path: protoc-gen-go-grpc must be in PATH or referenced by --plugin flag; missing it causes silent failures. Internal packages: google.golang.org/grpc/internal/* are unstable and may change between minor versions; do not depend on them in external code.

• HTTP/2 Multiplexing — gRPC's core advantage over HTTP/1.1; multiple concurrent RPC streams share a single TCP connection, reducing latency and resource usage. Understanding flow control and stream prioritization is essential for tuning performance.
• Protocol Buffers (protobuf) — gRPC's serialization format; .proto files define service interfaces and message types, then protoc-gen-go-grpc generates boilerplate. You must understand proto3 syntax and code generation to use grpc-go effectively.
• Unary vs Streaming RPC — grpc-go supports four RPC modes (unary, server-streaming, client-streaming, bidirectional-streaming). Each has different error handling, backpressure, and cancellation semantics documented in Documentation/
• Interceptors (Middleware) — grpc-go's extension mechanism for cross-cutting concerns (auth, logging, metrics, observability). Unary interceptors run once per RPC; stream interceptors wrap the stream. Central to building observable, secure services.
• gRPC Metadata — HTTP/2 headers (key-value pairs) sent with RPC calls for authentication tokens, trace IDs, and custom headers. Handled separately from message body; see Documentation/grpc-metadata.md for grpc-go specifics.
• Service Discovery & Load Balancing — grpc-go's resolver and balancer packages handle dynamic endpoint discovery (Consul, Kubernetes, etc.) and load balancing strategies (round-robin, ring-hash). Essential for production resilience.
• Keepalive & Connection Management — HTTP/2 connections are persistent; grpc-go requires explicit keepalive configuration (PING frames) to detect dead connections and avoid firewall timeouts. See Documentation/keepalive.md for tuning.
• Context-based Cancellation — All gRPC calls take a context.Context for deadline/timeout and cancellation propagation. Go's context semantics are baked into grpc-go's concurrency model.

• grpc/grpc — Reference C++ implementation of gRPC; go-grpc aims for feature parity and protocol compatibility
• grpc/grpc-java — Sibling Java implementation; useful for understanding gRPC design decisions and cross-language interop requirements
• grpc/grpc-web — Browser-friendly gRPC bindings; grpc-go servers often serve both grpc-go clients and grpc-web JavaScript clients
• protocolbuffers/protobuf-go — Underlying Protocol Buffers Go runtime; grpc-go depends heavily on google.golang.org/protobuf types and marshaling
• golang/go — Go language runtime and standard library; grpc-go requires latest two major versions and uses golang.org/x/* packages for net, crypto, text

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 end-to-end tests for gRPC authorization audit logging

The authz package has audit logging infrastructure (authz/audit/audit_logger.go, authz/audit/stdout/stdout_logger.go) but the existing test (authz/audit/audit_logging_test.go) appears minimal. There's no integration test verifying that authorization decisions are correctly logged through the audit system in real gRPC scenarios. This is critical for security-sensitive deployments that need audit trails.

• [ ] Create authz/audit/audit_logging_integration_test.go with end-to-end scenarios
• [ ] Test audit log output for allowed vs denied RPC calls with different RBAC policies
• [ ] Verify audit logs capture client identity, method names, and decision outcomes
• [ ] Add test cases for stdout logger and custom logger implementations
• [ ] Ensure tests integrate with grpc_authz_end2end_test.go patterns

Add missing connection state evaluator tests for edge cases

The balancer/conn_state_evaluator.go file has corresponding tests, but examining endpoint sharding (balancer/endpointsharding/) shows complex connection state logic. The conn_state_evaluator_test.go may not cover all edge cases around state transitions during graceful shutdowns, connection pool exhaustion, and rapid state flaps that could cause instability in production load balancing.

• [ ] Review balancer/conn_state_evaluator_test.go for missing scenarios
• [ ] Add test cases for rapid READY→TRANSIENT_FAILURE→READY cycles
• [ ] Add tests for state evaluation with multiple endpoints in different states
• [ ] Test connection state evaluation during server shutdown sequences
• [ ] Add benchmark tests to ensure evaluator performance under load

Add gRPC keepalive configuration validation and testing

Documentation/keepalive.md exists but there's no dedicated keepalive validation package. The backoff.go and backoff/backoff.go files handle timing, but there's no centralized validator to catch misconfigured keepalive parameters (e.g., MaxConnectionIdle > MaxConnectionAge, invalid timeout values). This would prevent silent failures and configuration-related outages.

• [ ] Create keepalive/validator.go to validate KeepaliveParams structs
• [ ] Implement validation for: MaxConnectionIdle, MaxConnectionAge, MaxConnectionAgeGrace, Time, Timeout relationships
• [ ] Add keepalive/validator_test.go with comprehensive test cases for valid/invalid configurations
• [ ] Integrate validator into server and dial options (reference internal/transport/http2_server.go patterns)
• [ ] Add validation examples to Documentation/keepalive.md with updated code samples

• Add missing test coverage for specific transport error handling paths in internal/transport/ (visible from codecov.yml setup); grep for TODO comments in transport code and write end-to-end tests exercising connection failures.
• Expand Documentation/compression.md with concrete examples showing gzip/deflate codec registration and benchmarks comparing overhead; currently lacks sample code for custom codec implementations.
• Add audit logging integration tests in authz/audit/ for the stdout logger (stdout/stdout_logger.go has basic implementation but admin/test/admin_test.go pattern shows test patterns missing for audit scenarios); test log output format and filtering.

The gRPC-Go codebase appears to be a mature, well-maintained project with generally good security practices. However, there are concerns about the dependency configuration in the go.mod file, particularly the invalid Go version specification (1.25.0) and a suspicious future-dated dependency (genproto v0.0.0-20260226221140). These require immediate investigation and correction. Additionally, transitive dependencies should be reviewed and updated regularly. The security policy documentation could be more comprehensive. No hardcoded secrets, SQL injection risks, or obvious misconfigurations were detected in the provided file structure.

• Medium · Outdated Go Version Requirement — cmd/protoc-gen-go-grpc/go.mod. The go.mod file specifies 'go 1.25.0' which appears to be a future or invalid version number. Current Go releases are in the 1.x series (e.g., 1.21, 1.22). This may indicate a configuration error or typo that could lead to unexpected behavior or security issues during builds. Fix: Verify and correct the Go version to match one of the two latest major releases as documented in the README. Use a valid version like 'go 1.21' or 'go 1.22'.
• Medium · Dependency Version Pinning with Future Dates — cmd/protoc-gen-go-grpc/go.mod. The go.mod file contains a dependency 'google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-...' with a timestamp (20260226) that appears to be in the future (year 2026). This is highly suspicious and may indicate a compromised dependency or configuration error. Fix: Investigate this dependency version immediately. Verify the integrity of dependencies using 'go mod verify' and consider using a more recent, stable version with a realistic timestamp.
• Low · Potential Outdated Transitive Dependencies — cmd/protoc-gen-go-grpc/go.mod. The transitive dependencies (golang.org/x/net v0.51.0, golang.org/x/sys v0.42.0, golang.org/x/text v0.34.0) may be outdated relative to the target Go versions. While these are standard library extensions, older versions may contain known vulnerabilities. Fix: Run 'go get -u' to update to the latest compatible versions of dependencies, and review the SECURITY.md file for known CVEs. Regularly update dependencies as part of the maintenance cycle.
• Low · Missing Security Policy Details — SECURITY.md. The SECURITY.md file is minimal and only references an external CVE process document. It lacks specific guidance on security disclosure timelines, vulnerability report handling procedures, or security update communication channels. Fix: Expand the SECURITY.md file with detailed security policies including: disclosure timeline, responsible disclosure contact information, supported versions for security updates, and links to security advisories.

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.