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/alibaba/jetcache 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

• Last commit 4mo ago
• 12 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago
• ⚠ Concentrated ownership — top contributor handles 73% of recent commits

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

What it runs against: a local clone of alibaba/jetcache — 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 alibaba/jetcache | 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 ≤ 136 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "alibaba/jetcache(\\.git)?\\b" \\
  && ok "origin remote is alibaba/jetcache" \\
  || miss "origin remote is not alibaba/jetcache (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 "jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/Cached.java" \\
  && ok "jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/Cached.java" \\
  || miss "missing critical file: jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/Cached.java"
test -f "jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/CacheHandler.java" \\
  && ok "jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/CacheHandler.java" \\
  || miss "missing critical file: jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/CacheHandler.java"
test -f "jetcache-anno/src/main/java/com/alicp/jetcache/anno/aop/JetCacheInterceptor.java" \\
  && ok "jetcache-anno/src/main/java/com/alicp/jetcache/anno/aop/JetCacheInterceptor.java" \\
  || miss "missing critical file: jetcache-anno/src/main/java/com/alicp/jetcache/anno/aop/JetCacheInterceptor.java"
test -f "jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/ExpressionEvaluator.java" \\
  && ok "jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/ExpressionEvaluator.java" \\
  || miss "missing critical file: jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/ExpressionEvaluator.java"
test -f "jetcache-anno/src/main/java/com/alicp/jetcache/anno/config/CommonConfiguration.java" \\
  && ok "jetcache-anno/src/main/java/com/alicp/jetcache/anno/config/CommonConfiguration.java" \\
  || miss "missing critical file: jetcache-anno/src/main/java/com/alicp/jetcache/anno/config/CommonConfiguration.java"

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

JetCache is a unified Java caching abstraction layer that provides a uniform API across multiple backend implementations (Redis, Tair, Caffeine, LinkedHashMap). It enables declarative method-level caching via annotations (@Cached, @CacheUpdate, @CacheInvalidate) with native TTL support, two-level (local + remote) caching, distributed cache refresh, and automatic statistics collection—solving the problem of cache implementation fragmentation in enterprise Java applications. Multi-module Maven monorepo: jetcache-anno-api provides the annotation contract (CacheConsts, CacheInvalidate, etc.); core implementation modules (likely jetcache-core, jetcache-spring) follow. Parallel docs structure (docs/CN/ and docs/EN/) with detailed guides for each Redis client variant (RedisWithJedis.md, RedisWithLettuce.md, RedisWithRedisson.md). Docker Compose setup (docker-compose.yml) indicates test infrastructure.

Java backend engineers building microservices or monolithic applications that need flexible caching strategies without being locked into a single cache provider; Spring/Spring Boot developers who want more powerful declarative caching than Spring Cache provides (especially those needing TTL, two-level caching, and distributed refresh).

Production-ready and actively maintained. The project is at version 2.7.9-SNAPSHOT with established CI/CD (maven.yml workflow), comprehensive bilingual documentation (docs/CN and docs/EN), and clear changelog (changelog.txt). However, it is a Alibaba-sponsored project with moderate community visibility compared to Spring Cache; maintenance appears solid but not as high-velocity as mainstream Spring projects.

Standard open source risks apply.

Based on file structure, active work includes: multi-client Redis support (separate docs for Jedis, Lettuce, Redisson), Spring Boot integration, and recent features like distributed cache invalidation (2.7+) and async access (2.2+). The snapshot version and presence of .travis.yml + maven.yml suggests continuous integration is live. Specific recent focus appears to be on value convertor options (fastjson, jackson, kryo, kryo5) and key convertor flexibility.

git clone https://github.com/alibaba/jetcache.git
cd jetcache
mvn clean install
# For Spring Boot example, check docs/EN/GettingStarted.md

Daily commands: No standalone runnable artifact; this is a library. To use: add dependency to your Spring Boot project (e.g., com.alicp.jetcache:jetcache-spring-boot-starter), configure in application.yml/properties, annotate methods with @Cached. For local testing: mvn test. For Docker-based Redis testing: docker-compose up (presupposes docker-compose.yml configures Redis).

• jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/Cached.java — Core annotation for method-level caching; every contributor must understand the primary caching contract.
• jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/CacheHandler.java — Central handler implementing cache operations (@Cached, @CacheInvalidate, @CacheUpdate); defines the execution model.
• jetcache-anno/src/main/java/com/alicp/jetcache/anno/aop/JetCacheInterceptor.java — AOP interceptor that wraps method calls with cache logic; the bridge between Spring AOP and cache annotations.
• jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/ExpressionEvaluator.java — Evaluates SpEL expressions in cache keys and conditions; critical for dynamic key generation.
• jetcache-anno/src/main/java/com/alicp/jetcache/anno/config/CommonConfiguration.java — Configures cache instances and Spring bean setup; entry point for @EnableCache annotation processing.
• jetcache-anno/src/main/java/com/alicp/jetcache/anno/field/CreateCacheAnnotationBeanPostProcessor.java — Post-processor that injects @CreateCache fields; handles programmatic cache instance creation.
• jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/CacheType.java — Enum defining supported cache types (LOCAL, REMOTE); foundational to the multi-backend abstraction.

Add a new cache annotation

1. Define annotation interface in jetcache-anno-api (jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/)
2. Create corresponding config class (e.g., CachedAnnoConfig) to hold parsed metadata (jetcache-anno/src/main/java/com/alicp/jetcache/anno/support/)
3. Add parsing logic to CacheAnnotationParser.parse() method (jetcache-anno/src/main/java/com/alicp/jetcache/anno/config/CacheAnnotationParser.java)
4. Implement handler method in CacheHandler for the new annotation logic (jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/CacheHandler.java)
5. Update CachePointcut to match the new annotation (jetcache-anno/src/main/java/com/alicp/jetcache/anno/aop/CachePointcut.java)

Add support for a new serialization format

1. Add new enum value to SerialPolicy if introducing a new strategy type (jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/SerialPolicy.java)
2. Create encoder/decoder implementation or extend DefaultEncoderParser (jetcache-anno/src/main/java/com/alicp/jetcache/anno/support/DefaultEncoderParser.java)
3. Register the encoder in the parser's strategy map (jetcache-anno/src/main/java/com/alicp/jetcache/anno/support/DefaultEncoderParser.java)

Add dynamic cache key generation via SpEL

1. Define SpEL expression in @Cached.key parameter (jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/Cached.java)
2. ExpressionEvaluator is automatically invoked by CacheConfigUtil to evaluate keys at runtime (jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/ExpressionEvaluator.java)
3. Context variables (target, method, args) are exposed via CacheInvokeContext (jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/CacheInvokeContext.java)

Customize cache naming strategy

1. Extend CacheNameGenerator or provide a custom implementation (jetcache-anno/src/main/java/com/alicp/jetcache/anno/support/CacheNameGenerator.java)
2. Register custom generator in CommonConfiguration or application context (jetcache-anno/src/main/java/com/alicp/jetcache/anno/config/CommonConfiguration.java)

• Spring AOP (Proxy-based) — Provides non-intrusive method interception without modifying target classes; integrates seamlessly with Spring beans.
• undefined — undefined

1. SpEL context in @Cached/@CacheUpdate/@CacheInvalidate: the key attribute uses Spring Expression Language; mismatched parameter names silently fail. 2. Serialization compatibility: switching between fastjson/jackson for keys or kryo/kryo5 for values requires cache invalidation; old serialized entries become unreadable. 3. Two-level caching invalidation: the local cache layer (e.g., Caffeine) may not immediately invalidate when remote cache is updated; requires distributed lock or manual refresh. 4. Spring version constraints: 2.7+ requires Spring Framework 5.2.4+ and Boot 2.2.5+; using older versions silently skips annotation processing. 5. Redis driver version hell: Lettuce and Redisson have incompatible configuration; pick one early.

• Two-level caching (L1/L2 cache) — JetCache's core differentiator: local in-process caches (Caffeine) reduce latency, remote caches (Redis) provide persistence and cross-JVM consistency; understanding when to use BOTH vs REMOTE-only is critical for performance tuning
• Spring Expression Language (SpEL) — All JetCache annotations use SpEL for dynamic cache key generation (e.g., key='#userId', key='#user.profile.id'); misunderstanding SpEL contexts causes silent cache misses
• Aspect-Oriented Programming (AOP) — JetCache's @Cached, @CacheUpdate, @CacheInvalidate annotations are implemented via Spring AOP interceptors; understanding proxy creation and method interception is essential for debugging caching failures
• Cache invalidation strategies (TTL vs explicit vs distributed) — JetCache supports passive expiration (TTL/expire parameter), explicit invalidation (@CacheInvalidate), and distributed invalidation (2.7+); choosing the wrong strategy causes stale data or over-invalidation
• Distributed locks (for cache refresh) — When multiple JVMs refresh the same cache key simultaneously, JetCache 2.2+ uses distributed locks (via Redis) to prevent cache stampede and redundant expensive operations
• Serialization and convertor strategy pattern — JetCache decouples key serialization (fastjson vs jackson) from value serialization (java vs kryo vs kryo5); swapping convertors mid-deployment breaks old cache entries, requiring careful rollout planning
• Cache statistics collection via interceptors — JetCache automatically tracks hit/miss rates, access counts, and operation latencies at both method and cache instance level; this data is crucial for identifying hot spots and tuning cache parameters (TTL, size, concurrency)

• spring-projects/spring-framework — Spring Cache is the closest alternative in the same ecosystem; JetCache is positioned as a superset with more powerful annotations and two-level caching
• ben-manes/caffeine — JetCache uses Caffeine as one of its built-in local cache implementations; understanding Caffeine's eviction policies and stats collection is essential for tuning two-level caches
• lettuce-io/lettuce-core — Redis driver recommended for async access in JetCache 2.2+; one of three supported Redis clients alongside Jedis and Redisson
• redis/jedis — Legacy but widely-used Redis driver; JetCache supports it for backward compatibility with older Spring Boot projects
• redisson/redisson — Advanced Redis driver with distributed locks and multi-threaded support; JetCache leverages it for distributed cache refresh (2.2+) and invalidation (2.7+)

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 unit tests for CachePenetrationProtect annotation in jetcache-anno

The jetcache-anno module has CachePenetrationProtect.java defined in the API, but there's no visible test coverage in the file structure for this critical feature that prevents cache penetration attacks in distributed environments. This is a core JetCache feature that deserves dedicated test coverage including edge cases like concurrent requests, timeout scenarios, and fallback behavior.

• [ ] Create jetcache-anno/src/test/java/com/alicp/jetcache/anno/CachePenetrationProtectTest.java
• [ ] Add tests for concurrent cache miss scenarios with protection enabled
• [ ] Add tests for timeout behavior and exception handling during protection
• [ ] Add integration tests with both local and remote cache backends
• [ ] Verify tests run in the Maven CI pipeline (.github/workflows/maven.yml)

Add missing English documentation for AdvancedCacheAPI and DevNote features in docs/EN

The docs/CN folder contains AdvancedCacheAPI.md and DevNote.md, but docs/EN is missing AdvancedCacheAPI.md and DevNote.md entirely. These appear to be important developer resources that English-speaking contributors cannot currently access, creating a documentation parity gap.

• [ ] Translate docs/CN/AdvancedCacheAPI.md to docs/EN/AdvancedCacheAPI.md
• [ ] Translate docs/CN/DevNote.md to docs/EN/DevNote.md (if it exists)
• [ ] Update docs/EN/Readme.md to link to these new documentation files
• [ ] Review translations for technical accuracy regarding cache API specifics
• [ ] Add cross-references in the main README.md to both language versions

Add integration tests for multi-level caching with Lettuce and Redisson backends in jetcache-anno

JetCache's key differentiator is two-level caching support (local + remote). While docs/EN contains RedisWithJedis.md, RedisWithLettuce.md, and RedisWithRedisson.md, there's no visible test coverage for multi-level cache scenarios with different Redis client backends. This is a critical feature that needs verification across implementation variants.

• [ ] Create jetcache-anno/src/test/java/com/alicp/jetcache/anno/MultiLevelCacheIntegrationTest.java
• [ ] Add tests for L1 (local) + L2 (Redis via Lettuce) caching with TTL synchronization
• [ ] Add tests for L1 + L2 caching with Redisson backend
• [ ] Add tests for cache invalidation propagation across both levels
• [ ] Add tests for refresh behavior in two-level cache scenarios
• [ ] Ensure docker-compose.yml services are properly initialized for test execution

• Add missing test coverage for CacheInvalidate with SpEL key expressions: jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/CacheInvalidate.java lacks explicit unit tests for complex SpEL scenarios (nested property access, method calls in key). Create test class CacheInvalidateSpELTest to cover edge cases like @CacheInvalidate(key='#user.profile.id').
• Document Lettuce vs Redisson driver differences in docs/EN/RedisWithLettuce.md and docs/EN/RedisWithRedisson.md: Both docs exist but lack side-by-side comparison of configuration quirks, connection pooling defaults, and async API support. Add a 'Comparison' section showing real config examples for the same use case in both drivers.
• Add integration test for kryo5 value serialization with two-level caching: docs/CN/Config.md mentions kryo5 convertor but no test verifies that Caffeine (local) + Redis (remote) work correctly with kryo5 serialization. Create test case that updates local cache, serializes to Redis with kryo5, then deserializes back without data loss.

JetCache codebase has moderate security concerns primarily in infrastructure and deployment configuration. The main issues involve exposed Redis ports without authentication, incomplete Sentinel configuration, and potential secrets in version-controlled .env files. The Java code itself shows awareness of cache-specific security (penetration protection, refresh mechanisms) but lacks explicit documentation on secure usage

• High · Exposed Redis Ports in Docker Compose — docker-compose.yml (lines: master, slave1, slave2, sentinel1 services). The docker-compose.yml uses 'network_mode: host' for Redis services, which exposes Redis ports (6379, 6380, 6381, 26379) directly to the host network without any authentication or firewall configuration. This allows unauthorized access to the Redis instances. Fix: 1. Remove 'network_mode: host' and use Docker's bridge network instead. 2. Implement Redis authentication with requirepass. 3. Use port binding restrictions (127.0.0.1:6379:6379) instead of exposing to all interfaces. 4. Add firewall rules to restrict Redis port access.
• Medium · Missing .env File Validation — .env. The presence of a .env file in the repository root suggests potential storage of environment variables or secrets. If committed to version control, this could expose sensitive information like API keys, database credentials, or Redis passwords. Fix: 1. Ensure .env is added to .gitignore immediately. 2. Use .env.example with placeholder values instead. 3. Implement secrets management (e.g., HashiCorp Vault, AWS Secrets Manager). 4. Scan git history for accidental commits: 'git log --all --full-history -- .env'.
• Medium · Incomplete Sentinel Configuration in Docker Compose — docker-compose.yml (sentinel1 service command). The sentinel configuration in docker-compose.yml uses incomplete bash commands (line cut off with 'sed -i' and missing configuration parameters). This could lead to misconfigured Sentinel failover behavior and potential security gaps in the Redis cluster setup. Fix: 1. Complete the sentinel configuration with all required parameters. 2. Add sentinel-dir and logfile configuration. 3. Validate Sentinel configuration syntax separately. 4. Consider using a separate sentinel.conf file mounted as a volume instead of inline bash configuration.
• Medium · Unspecified Redis Version in Docker Compose — docker-compose.yml (image: 'redis:${IMG_VER}'). The docker-compose.yml references '${IMG_VER}' environment variable for the Redis image version, which may not be defined or could default to 'latest'. Using 'latest' tag can introduce unknown security vulnerabilities from newer versions without proper testing. Fix: 1. Always use specific Redis version tags (e.g., 'redis:6.2.14-alpine'). 2. Define IMG_VER in .env.example with a specific version. 3. Regularly audit and update to patched versions. 4. Test version upgrades in non-production environments first.
• Low · AOP-Based Interceptor Implementation — jetcache-anno/src/main/java/com/alicp/jetcache/anno/aop/JetCacheInterceptor.java. The codebase uses Spring AOP interceptors (JetCacheInterceptor.java) for cache annotation processing. If improperly configured, AOP proxies could expose internal cache data or bypass security checks for unauthenticated method calls. Fix: 1. Ensure proper Spring Security integration with cache interceptors. 2. Validate that sensitive methods are properly secured before caching. 3. Implement cache key generation that prevents collision attacks. 4. Add authorization checks before cache operations.
• Low · Potential Cache Penetration Without Explicit Protection — jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/CachePenetrationProtect.java. While CachePenetrationProtect annotation exists, the default behavior and mandatory usage are unclear. Cache penetration attacks could occur if not properly configured on all critical cache methods. Fix: 1. Document cache penetration protection as mandatory for sensitive operations. 2. Implement default protection mechanisms. 3. Use code reviews to ensure CachePenetrationProtect is applied to high-value cached methods. 4. Add static analysis rules to flag uncprotected cache 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.