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/golang/groupcache 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 all four use cases

• 31+ active contributors
• Distributed ownership (top contributor 29% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{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 golang/groupcache repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/golang/groupcache.

What it runs against: a local clone of golang/groupcache — 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 golang/groupcache | 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 | Last commit ≤ 556 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "golang/groupcache(\\.git)?\\b" \\
  && ok "origin remote is golang/groupcache" \\
  || miss "origin remote is not golang/groupcache (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"

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

groupcache is a distributed in-memory caching library for Go that eliminates the need for separate memcached servers by embedding cache logic directly into your application. It automatically shards data across peer nodes using consistent hashing, coordinates cache fills via singleflight to prevent thundering herds, and automatically hot-spots super-popular keys across multiple peers to prevent bottlenecking. Flat package structure: core cache logic in groupcache.go, LRU eviction in lru/lru.go, peer discovery in peers.go and http.go, consistent hashing in consistenthash/consistenthash.go, duplicate request suppression in singleflight/singleflight.go, and protobuf RPC contracts in groupcachepb/groupcache.proto. No monorepo; single library with subpackages.

Go backend engineers building distributed systems who need cache coordination without operational overhead of running memcached clusters. Used internally at Google (dl.google.com, Blogger, Google Code, Google Fiber) and by teams wanting to replace memcached pools with library-based caching.

Production-ready and mature: used in Google's production systems since at least 2013, has comprehensive test coverage (groupcache_test.go, http_test.go, lru/lru_test.go, etc.), uses Travis CI (.travis.yml), and maintains Go 1.20+ compatibility. However, repository shows minimal recent activity suggesting stable maintenance mode rather than active development.

Very low risk: only two dependencies (github.com/golang/protobuf v1.5.4, google.golang.org/protobuf v1.33.0), both actively maintained by Google. Single logical maintainer model (bradfitz@ per README) but code is battle-tested in Google production for 10+ years. No known breaking changes expected—immutability design prevents versioning issues.

Repository appears in stable/maintenance mode. No active issues or PRs visible in provided data. Last notable activity likely aligned with Go 1.20 module definition (go.mod exists). No breaking changes or major feature development indicated.

git clone https://github.com/golang/groupcache && cd groupcache && go mod download && go test ./...

Daily commands: Not a runnable service—this is a library. Import in your Go code: import "github.com/golang/groupcache". Run tests with go test ./... and go test ./lru ./consistenthash ./singleflight.

• groupcache.go: Core Group struct and Get() method—entry point for all cache operations
• lru/lru.go: LRU eviction policy implementation used for hot item storage
• consistenthash/consistenthash.go: Consistent hashing ring that determines which peer owns each key
• singleflight/singleflight.go: Deduplication mechanism preventing thundering herd during cache misses
• http.go: HTTP server and client for peer-to-peer RPC communication
• groupcachepb/groupcache.proto: Protocol Buffer definition for GetRequest/GetResponse RPC messages
• peers.go: PeerPicker interface defining how peers are discovered and selected
• byteview.go: Immutable ByteView container preventing accidental value mutations

New Get() behavior → groupcache.go. Cache eviction logic → lru/lru.go. Peer selection → peers.go or consistenthash/consistenthash.go. RPC protocol → groupcachepb/groupcache.proto (requires protoc recompile). HTTP transport → http.go. Singleflight internals → singleflight/singleflight.go.

Non-obvious requirement: cache keys must be stable and deterministic across all peer nodes (no randomized hashing). Protobuf messages require protoc compiler for .proto regeneration (groupcachepb/groupcache.pb.go is generated, not hand-edited). Singleflight deduplication is per-process—if multiple Go processes each run groupcache independently, each will load the same key redundantly (expected design, not a bug). No TTL or explicit eviction—values are immutable and only removed by LRU pressure.

• Consistent Hashing — groupcache uses consistent hashing (consistenthash/consistenthash.go) to deterministically map keys to peer nodes; this allows cache rebalancing when peers join/leave without rehashing all keys
• Singleflight / Request Deduplication — groupcache's singleflight pattern (singleflight/singleflight.go) ensures that when multiple goroutines request the same missing key, only one load happens and all callers wait for that single result—preventing thundering herd
• LRU (Least Recently Used) Eviction — groupcache's lru/lru.go implements LRU cache eviction to keep hot items (especially auto-mirrored super-hot keys) in memory while bounded by max cache size
• Peer-to-Peer Cache Coordination — Unlike memcached (separate servers), groupcache peers are the application itself (http.go provides both cache server and client); each node knows about others and RPC-fetches from peer owners
• Immutable ByteView — byteview.go wraps []byte in an immutable container preventing callers from accidentally modifying cached values, enforcing cache safety in concurrent environments
• Protocol Buffers for RPC — groupcachepb/groupcache.proto defines GetRequest/GetResponse messages; Protobuf provides compact, versioned serialization for peer communication vs. JSON overhead
• Hot Item Mirroring — groupcache automatically replicates super-hot keys across multiple peers (tracked in lru/ logic) to prevent single-peer bottlenecks that plague memcached; mentioned in README but implementation is subtle

• bradfitz/gomemcache — Client library for actual memcached; groupcache is designed as a memcached-replacement so understanding gomemcache's API helps clarify design trade-offs
• golang/go — groupcache depends on Go standard library (net/http, encoding/binary); relevant for understanding platform constraints and idioms
• grpc/grpc-go — Alternative RPC framework for distributed cache scenarios; groupcache uses plain HTTP+Protobuf instead of gRPC for simplicity
• golang/protobuf — Direct dependency (v1.5.4) used for serializing cache GetRequest/GetResponse messages across peers
• bluele/gcache — Modern single-node Go caching library with TTL and eviction policies; if you need distributed caching, groupcache; if just local, gcache is simpler

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 context.Context support throughout groupcache API

The current groupcache API (groupcache.go, peers.go, http.go) lacks context.Context support, which is critical for modern Go applications. This prevents proper timeout handling, cancellation, and request-scoped values. Adding context support would align with Go best practices (especially important since go.mod specifies Go 1.20+) and enable users to implement proper lifecycle management in their distributed cache operations.

• [ ] Update Get() and GetBytes() method signatures in groupcache.go to accept context.Context
• [ ] Update Getter interface in groupcache.go to pass context through the fill function
• [ ] Update http.go RegisterPeerPicker() and peer HTTP handlers to propagate context through requests
• [ ] Update singleflight/singleflight.go Do() method to accept and use context for cancellation
• [ ] Add comprehensive context-based tests in groupcache_test.go covering timeout and cancellation scenarios
• [ ] Update http_test.go to validate context propagation in HTTP peer communication

Add metrics/observability hooks to core cache operations

groupcache.go currently has no built-in instrumentation. Adding optional callback hooks for cache hits/misses, fill operations, and peer communication would enable users to export metrics to Prometheus, DataDog, etc. without forking or monkey-patching. This is a high-value addition for production deployments where observability is critical.

• [ ] Add StatsHandler interface to groupcache.go with methods: OnCacheHit(key string), OnCacheMiss(key string), OnFillStart(key string), OnFillComplete(key string, duration time.Duration, err error)
• [ ] Add SetStatsHandler() method to Group struct in groupcache.go
• [ ] Integrate stats callbacks in Group.Get() method to emit events at appropriate points
• [ ] Integrate stats callbacks in http.go for peer fetch operations
• [ ] Add example implementation in README.md or new examples directory showing Prometheus exporter integration
• [ ] Add comprehensive tests in groupcache_test.go verifying stats callbacks are fired correctly

Add explicit peer healthcheck mechanism with fallback strategy

The current peers.go and http.go don't have any health checking mechanism. In distributed setups, dead or slow peers cause cascading failures. Adding configurable health checks with exponential backoff and fallback logic would significantly improve reliability in production environments where network partitions are common.

• [ ] Add HealthChecker interface to peers.go with Check(ctx context.Context, peer ProtoGetter) error method
• [ ] Add healthcheck configuration fields to http.go's HTTPPool struct (CheckInterval, CheckTimeout, MaxRetries)
• [ ] Implement periodic health checks in http.go that mark unhealthy peers and temporarily exclude them from peer selection
• [ ] Update consistenthash/consistenthash.go or http.go to skip unhealthy peers during Get() operations
• [ ] Add exponential backoff retry logic before permanently marking a peer as unhealthy
• [ ] Add comprehensive tests in http_test.go covering health check scenarios (network failures, slow responses, recovery)

• Add context.Context support to groupcache.Group.Get() and singleflight.Group.Do()—both currently lack timeout/cancellation, which is a gap vs. modern Go libraries. Start by adding ctx parameter to groupcache.go:Get() signature.
• Expand http_test.go coverage for error cases—no tests for transport failures, malformed responses, or HTTP 500 errors on peer calls. Add tests verifying fallback-to-local-load behavior when peer RPC fails.
• Document the singleflight/singleflight.go deduplication semantics in README with a concrete example showing 3 concurrent requests hitting the same missing key—currently users must read code to understand thundering herd prevention.

The golang/groupcache codebase demonstrates reasonable security practices but has some concerns. The primary issue is the use of a deprecated protobuf library (v1.5.4) instead of the maintained google.golang.org/protobuf. Additionally, as a distributed caching library designed for inter-peer communication, the absence of visible TLS/mTLS and authentication mechanisms is a notable gap. The library lacks explicit security headers in HTTP implementations and may benefit from additional input validation in the consistent hash and LRU components. No hardcoded secrets or SQL injection risks were identified. Overall, the codebase is relatively secure but requires attention to dependency updates and communication security mechanisms.

• Medium · Outdated Protobuf Dependency — go.mod - github.com/golang/protobuf v1.5.4. The codebase uses github.com/golang/protobuf v1.5.4, which is deprecated. Google has migrated to google.golang.org/protobuf v1.33.0. The legacy package may not receive security updates and has known compatibility issues. Fix: Migrate from github.com/golang/protobuf to google.golang.org/protobuf v1.33.0 or later. Update all protobuf imports from 'github.com/golang/protobuf' to 'google.golang.org/protobuf'.
• Low · Missing Security Headers in HTTP Handler — http.go. The http.go file implements HTTP endpoints for distributed cache communication. Without visibility of the implementation, there is a potential risk that security headers (X-Frame-Options, X-Content-Type-Options, etc.) may not be properly configured, especially if the cache is exposed to untrusted networks. Fix: Ensure HTTP handlers in http.go include appropriate security headers. Implement Content Security Policy headers and validate input from HTTP requests. Consider adding rate limiting and authentication mechanisms for inter-peer communication.
• Low · No Explicit Secrets Management — peers.go, http.go. While no hardcoded secrets are apparent in file names, groupcache is designed for distributed peer-to-peer communication. There is no visible mechanism for securing inter-peer communication (e.g., TLS/mTLS, authentication tokens). Fix: Implement TLS/mTLS for inter-peer communication. Add authentication mechanisms (e.g., mutual TLS certificates or HMAC-based authentication) to verify peer identity and prevent unauthorized cache access.
• Low · Potential Integer Overflow in LRU Cache — lru/lru.go. Cache implementations commonly have integer overflow vulnerabilities when handling size calculations or counters. The lru package may be susceptible if it doesn't properly validate size parameters. Fix: Review lru.go for proper bounds checking on size parameters. Ensure integer overflow protection in cache size calculations and counter increments. Use safe integer arithmetic libraries if available.
• Low · Missing Input Validation in Consistent Hash — consistenthash/consistenthash.go. The consistent hash implementation (consistenthash/consistenthash.go) may not properly validate peer addresses or key inputs, potentially allowing malformed data to cause panics or unexpected behavior. Fix: Add input validation for peer addresses (e.g., verify IP address format). Validate key length and content. Implement bounds checking for hash ring operations.

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.