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/allegro/bigcache 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 2w ago
• 46+ active contributors
• Distributed ownership (top contributor 19% of recent commits)
• Apache-2.0 licensed
• CI configured
• ⚠ No test directory detected

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

What it runs against: a local clone of allegro/bigcache — 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 allegro/bigcache | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 43 days ago | Catches sudden abandonment since generation |

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

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

# 4. Critical files exist
test -f "bigcache.go" \\
  && ok "bigcache.go" \\
  || miss "missing critical file: bigcache.go"
test -f "shard.go" \\
  && ok "shard.go" \\
  || miss "missing critical file: shard.go"
test -f "queue/bytes_queue.go" \\
  && ok "queue/bytes_queue.go" \\
  || miss "missing critical file: queue/bytes_queue.go"
test -f "hash.go" \\
  && ok "hash.go" \\
  || miss "missing critical file: hash.go"
test -f "config.go" \\
  && ok "config.go" \\
  || miss "missing critical file: config.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 43 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~13d)"
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/allegro/bigcache"
  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).

BigCache is a high-performance, concurrent in-memory cache written in Go designed to hold gigabytes of data without triggering Go's garbage collector overhead. It avoids GC pressure by storing entries as byte slices on the heap and using sharded hash tables with automatic eviction based on entry age or memory limits. The cache offers microsecond-level Get/Set operations even with millions of entries through lock-free read paths and efficient memory management. Flat monolithic structure with core cache logic in bigcache.go and supporting modules for sub-concerns: queue/bytes_queue.go handles the ring buffer for expired entry cleanup, shard.go implements per-shard locking, encoding.go provides serialization helpers, and server/ contains an optional HTTP wrapper. Tests are co-located (bigcache_test.go, bigcache_bench_test.go). The entry point is bigcache.New() returning a *BigCache struct managing Shards []Shard internally.

Go backend engineers building high-throughput services (APIs, microservices, session stores) who need to cache gigabytes of data without GC pauses degrading p99 latencies. DevOps teams running Kubernetes workloads where predictable latency trumps exact hit rates. Any developer trading memory for speed in latency-sensitive Go applications.

Production-ready. The repository shows mature patterns: comprehensive test coverage (assert_test.go, bigcache_test.go, benchmarks in bigcache_bench_test.go), CI/CD pipeline (.github/workflows/build.yml, release-management.yml), active release management (release-drafter.yml), and Go 1.16+ support requirement. The codebase is stable but actively maintained with recent refactors visible in the file list (iterator.go, encoding.go suggesting iterative improvements).

Low operational risk but medium adoption risk. Dependencies are minimal (go.mod shows only core Go stdlib), reducing supply-chain risk. The main risk is architectural: BigCache requires careful sizing (MaxEntriesInWindow, MaxEntrySize, HardMaxCacheSize must be tuned) and forces manual serialization (entries are []byte, no built-in JSON marshaling). Single maintainer patterns may exist—verify contributor diversity in CODEOWNERS.

Recent additions suggest active maintenance around observability and flexibility: encoding.go and encoding_test.go indicate custom serialization support is being emphasized, iterator.go and iterator_test.go add range-over-cache capability (likely for bulk operations), and the server/ package hints at REST API bindings for cache introspection. The release-management.yml workflow suggests regular version bumps.

Clone and test:

git clone https://github.com/allegro/bigcache.git
cd bigcache
go test ./...
go test -bench=. ./...

No external dependencies or services required; runs on any Go 1.16+ system.

Daily commands: No build step needed for library use. To run benchmarks:

go test -bench=. -benchmem ./...

To start the optional cache server:

cd server && go run server.go

To run all tests with coverage:

go test -cover ./...

• bigcache.go — Main BigCache API and entry point; defines core Get/Set/Delete operations and cache initialization logic
• shard.go — Sharding mechanism that distributes cache entries across multiple locks for concurrency; critical for performance
• queue/bytes_queue.go — Ring buffer implementation managing heap allocation and garbage collection avoidance; foundational to BigCache's efficiency
• hash.go — Hash function selection and routing logic that determines which shard handles each cache key
• config.go — Configuration struct and defaults; defines cache behavior including eviction policy, shard count, and max entry size
• encoding.go — Entry serialization/deserialization with timestamp and hash encoding; required for all Get/Set operations
• server/server.go — HTTP wrapper providing REST API access to BigCache; demonstrates integration patterns

• BigCache (bigcache.go) (Go concurrency primitives, sync.RWMutex) — Top-level cache instance; routes Get/Set/Delete to appropriate shard; manages lifecycle and stats
  • Failure mode: Panic if shards not initialized; returns

Add a custom eviction policy

1. Define eviction logic in shard.go's evictEntry() method or create a new eviction strategy interface (shard.go)
2. Update config.go to add EvictionPolicy field to Config struct (config.go)
3. Modify bigcache.go to pass the policy to each shard at initialization (bigcache.go)
4. Add tests in bigcache_test.go to verify eviction behavior (bigcache_test.go)

Expose cache metrics via a new HTTP endpoint

1. Add a new handler function in server/stats_handler.go or create server/custom_handler.go (server/stats_handler.go)
2. Register the route in server/server.go's http.HandleFunc() call (server/server.go)
3. Call cache.Stats() (from bigcache.go) to retrieve metrics and return as JSON (server/server.go)
4. Test the endpoint in server/server_test.go (server/server_test.go)

Implement a custom hash function

1. Create a new hash implementation (e.g., xxhash) or modify fnv.go (fnv.go)
2. Update hash.go's hashKey() function to use the new hash algorithm (hash.go)
3. Add benchmarks in fnv_bench_test.go to compare performance (fnv_bench_test.go)
4. Test in fnv_test.go to ensure consistency (fnv_test.go)

Add support for cache entry TTL (time-to-live)

1. Extend Config struct in config.go with DefaultTTL field (config.go)
2. Modify encoding.go to include TTL in encoded entry header (encoding.go)
3. Update shard.go to check TTL expiration in get() method before returning (shard.go)
4. Test TTL logic in bigcache_test.go and verify clock.go time mocking works (bigcache_test.go)

• Go with unsafe memory pointers (bytes.go) — Minimizes allocation and GC pressure by reusing memory regions; critical for efficient gigabyte-scale caches
• Sharding with per-shard mutexes (shard.go) — Reduces lock contention by distributing entries across multiple shards; enables true concurrency without global locks
• Ring buffer / circular queue (queue/bytes_queue.go) — Avoids repeated allocations; reuses same memory for evicted entries, enabling constant-space garbage collection
• FNV-1a hashing (fnv.go) — Fast, simple, and collision-resistant enough for shard distribution without cryptographic overhead
• HTTP server wrapper (server/) — Optional REST API layer allowing distributed cache access patterns without embedding the cache binary

• Entries stored as raw byte slices; no built-in serialization

  • Why: Allows the library to avoid serialization overhead and GC; users control when/how objects are marshaled
  • Consequence: Developers must handle encoding/decoding themselves (JSON, Protocol Buffers, etc.)

• Simple FIFO eviction with ring buffer

  • Why: Predictable memory usage and O(1) eviction; avoids complex data structures that would fragment memory
  • Consequence: No LRU or time-based eviction by default; entries age-out in insertion order

• Per-shard locking instead of lock-free algorithms

  • Why: Simpler implementation; adequate performance for most workloads; avoids atomic operation overhead for all keys
  • Consequence: Hotspot keys on a single shard could create bottlenecks under extreme contention

• No distributed cache; single-process only

  • Why: Keeps implementation simple and fast; avoids network/consensus overhead
  • Consequence: Not suitable for multi-node clusters; each instance is independent

• Does not provide distributed or replicated caching across multiple machines
• Does not handle automatic serialization/deserialization of arbitrary Go types
• Does not support advanced eviction policies like LRU or LFU without custom implementation
• Does not provide built-in persistence or recovery from disk
• Does not guarantee transactional semantics or ACID properties

Critical tuning parameters: Shards must be a power of 2 (checked in config.go but fails silently if violated). MaxEntriesInWindow is rps*lifeWindow and must be estimated correctly or cache will reallocate; underestimate causes extra allocations (verbose logs help). Serialization burden: All entries are []byte, so JSON marshaling happens outside the cache; no automatic compression. CleanWindow resolution: Set to < 1 second is ineffective (comment in config.go); expired entries may linger briefly. Hard limit behavior: HardMaxCacheSize=0 means unlimited; reaching the limit causes oldest entries to be silently overwritten (check OnRemoveWithReason callback). AppEngine: bytes_appengine.go has platform-specific memory handling; verify behavior on non-standard runtimes. Iterator thread safety: iterator.go traversal is not atomic with concurrent writes; snapshots may miss/duplicate entries.

• Sharding (concurrent partitioning) — BigCache divides the hash table into Shards (power-of-2 count) so multiple goroutines can write concurrently without global lock contention; critical for throughput scaling
• Ring buffer / Circular buffer — queue/bytes_queue.go uses a fixed-size ring to store entries in order, enabling O(1) eviction of oldest entries without array shifts; key to BigCache's speed
• GC-free memory allocation (unsafe pointers) — bytes.go and bytes_appengine.go use unsafe.Pointer to allocate memory outside the Go heap, avoiding garbage collector pauses on cache entries; the core innovation of BigCache
• FNV-1a hash function — fnv.go implements FNV-1a for fast, non-cryptographic hashing of keys to shards; chosen for speed and distribution quality, not security
• Time-based eviction (TTL) with LRU fallback — Entries expire after LifeWindow; when cache hits HardMaxCacheSize, oldest entries (by insertion time) are evicted; config.go and shard.go implement this dual strategy
• Read-write locks (RWMutex) with lock-free reads — shard.go uses RWMutex to allow many concurrent readers but exclusive writers; the sync.Map alternative is considered but mutable maps require write locks here
• Serialized value storage (no type safety) — Entries stored as []byte forces manual encoding/decoding at boundaries (encoding.go); trades type safety for memory efficiency and flexibility, a key design trade-off

• hashicorp/golang-lru — Standard Go LRU cache; simpler API but slower for gigabyte-scale workloads due to GC overhead; good for comparison on small datasets
• ristretto-cache/ristretto — Modern LRU alternative with W-TinyLFU eviction policy and built-in TTL; handles GC better than stdlib but less battle-tested for extreme scale than BigCache
• coocood/freecache — Another Go in-memory cache focused on GC-free operation; similar sharding approach but older codebase; BigCache is the more actively maintained equivalent
• patrickmn/go-cache — Lightweight TTL cache with simpler API; adequate for small caches (MB-scale) but lacks sharding and will GC heavily at GB scale
• allegro/bigcache-server — If it exists as separate repo: standalone daemon wrapping BigCache server/ package into a Kubernetes-ready service

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 benchmarks for concurrent shard operations in bigcache_bench_test.go

The repo has bigcache_bench_test.go and fnv_bench_test.go, but lacks benchmarks specifically targeting concurrent shard access patterns, eviction performance under high load, and memory allocation patterns. This is critical for a cache library where performance claims are central to the value proposition. New contributors can add benchmarks for: concurrent reads/writes on individual shards, eviction performance with varying entry sizes, and collision handling in the hash function.

• [ ] Review existing benchmarks in bigcache_bench_test.go and fnv_bench_test.go
• [ ] Study shard.go to understand locking and eviction mechanisms
• [ ] Add BenchmarkShardConcurrentReadWrite with various goroutine counts (10, 100, 1000)
• [ ] Add BenchmarkEvictionUnderLoad to measure GC impact during high-volume evictions
• [ ] Add BenchmarkHashDistribution to verify fnv hash uniformity across shard distribution
• [ ] Ensure benchmarks are runnable with go test -bench=. ./... and document results

Implement missing iterator tests in iterator_test.go for edge cases and error conditions

iterator.go exists but iterator_test.go likely lacks comprehensive coverage for edge cases like: iterating over empty caches, concurrent modification during iteration, behavior when cache is cleared mid-iteration, and proper resource cleanup. These are critical for a cache library where users need predictable iterator behavior.

• [ ] Review iterator.go implementation to identify untested code paths
• [ ] Add test cases for iterating over empty BigCache instance
• [ ] Add test case for concurrent Set/Delete operations during iteration with expected behavior documentation
• [ ] Add test case for cache.Reset() called during active iteration
• [ ] Add test cases for iterator.NextEntry() returning error conditions
• [ ] Add test to verify OnRemove callback behavior during iteration
• [ ] Run coverage tools to target uncovered branches in iterator.go

Add integration tests for server package in server/server_test.go covering HTTP edge cases and middleware chain

The server subpackage has server.go, cache_handlers.go, middleware.go, and stats_handler.go but server_test.go and middleware_test.go likely have limited coverage for realistic HTTP scenarios. Contributors can add integration tests for: HTTP error responses (malformed requests, missing keys), concurrent client requests, middleware execution order, and stats accuracy under load. This is valuable since the server exposes BigCache over HTTP.

• [ ] Review server.go, cache_handlers.go, and middleware.go to map all HTTP endpoints
• [ ] Add test for GET request with non-existent key returning proper 404 status
• [ ] Add test for POST/PUT with oversized payloads (exceeding MaxEntrySize)
• [ ] Add test for concurrent requests to verify race conditions don't exist
• [ ] Add test for middleware execution order and proper header injection
• [ ] Add integration test for stats endpoint accuracy after Set/Get/Delete operations
• [ ] Add test for proper error responses with meaningful HTTP status codes

• Add duration-aware cache stats: config.go and stats.go exist but don't track eviction reasons granularly (OnRemoveWithReason callback exists but is barely documented). Add tests in stats_test.go (missing file) demonstrating count of evictions by reason (TTL expiry vs. hard limit vs. manual delete).
• Implement cache warming helper: examples_test.go exists but lacks a concrete example of pre-populating cache from a backing store (common pattern). Add a function like PreloadFromFile(filename string) with corresponding test showing set operations don't block concurrent reads.
• Add Prometheus metrics exporter: server/ has HTTP handlers but no metrics export (no /metrics endpoint). Create server/metrics.go exporting cache hit rate, eviction rate, shard utilization to Prometheus; add unit test in server/metrics_test.go.

BigCache demonstrates reasonable security practices with appropriate use of GitHub workflows and configuration management. The primary concern is the outdated Go 1.16 requirement, which should be upgraded to a currently supported version. The codebase appears to be an in-memory cache library without obvious injection vulnerabilities, SQL queries, or hardcoded secrets based on the file structure. No third-party dependency vulnerabilities are apparent from the provided go.mod. Recommendations include updating the Go version requirement and adding a SECURITY.md file for vulnerability disclosure guidance.

• Medium · Outdated Go Version Requirement — go.mod (go 1.16). The module specifies Go 1.16 as the minimum version, which was released in February 2021 and is no longer receiving security updates. Go 1.16 reached end-of-life in December 2022. Running on outdated Go versions exposes the application to known security vulnerabilities in the Go runtime and standard library. Fix: Update the minimum Go version to at least 1.21 or the latest stable release. Update all dependencies to versions compatible with the newer Go version.
• Low · Missing SECURITY.md Policy — Repository root. No SECURITY.md file is present in the repository root. This file is important for documenting the project's security policy and providing clear instructions for responsible vulnerability disclosure. Fix: Create a SECURITY.md file that outlines the vulnerability disclosure process and security contact information.
• Low · Incomplete README Security Context — README.md. The README.md file appears to be truncated in the provided context (ends mid-import statement). While not a direct vulnerability, incomplete documentation can lead to misconfiguration by users. Fix: Ensure README.md is complete and includes security best practices for using BigCache, particularly around serialization/deserialization of sensitive data.

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.