Cocache

CoCache Development Guide

CoCache is a Java/Kotlin two-level distributed coherent cache framework:

• L2 client-side cache: local Map, Guava, or Caffeine cache.
• L1 distributed cache: Redis-backed shared cache.
• Coherence: CacheEvictedEventBus publishes evictions so peer instances invalidate local entries.

Start Here

Choose the smallest reference that fits the request:

Repository Rules

When editing this repository, follow AGENTS.md:

• Use me.ahoo.test.asserts.assert and .assert() in Kotlin tests; do not use AssertJ assertThat().
• Extend the TCK specs in cocache-test for cache implementations.
• Ask before changing cocache-api public interfaces or adding dependencies.
• Run the relevant Gradle checks before finishing; prefer ./gradlew check for broad changes.

Core Model

Define one cache interface per cache domain. The interface extends Cache<K, V>, is annotated with @CoCache, and is registered through @EnableCoCache. CoCache creates a proxy at runtime.

@CoCache(keyPrefix = "user:", ttl = 120)
@GuavaCache(maximumSize = 1_000_000, expireAfterAccess = 120, expireUnit = TimeUnit.SECONDS)
interface UserCache : Cache<String, User>

@SpringBootApplication
@EnableCoCache(caches = [UserCache::class])
class App

Use caches through Kotlin operators: cache[key], cache[key] = value, cache.evict(key), and cache.getCache(key) when CacheValue metadata is required.

Extension Points

CoCache auto-configures defaults, but each component can be overridden:

• Per cache, define named beans such as UserCache.CacheSource, UserCache.ClientSideCache, UserCache.KeyConverter, or UserCache.JoinKeyExtractor.
• Globally, define beans by type; auto-configured beans use @ConditionalOnMissingBean.
• For data loading, implement CacheSource<K, V>.loadCacheValue(key) and return DefaultCacheValue.forever(value), DefaultCacheValue.ttlAt(value, ttl), or bounded DefaultCacheValue.missingGuard(ttl, amplitude) values. Returning null for a missing key is also valid — CoCache auto-caches a missing guard with the cache's TTL (cache-penetration protection).

Testing Pattern

CoCache provides abstract specs in cocache-test for compatibility coverage:

• CacheSpec<K,V> for base cache behavior.
• ClientSideCacheSpec<V> for L2 caches.
• DistributedCacheSpec<V> for L1 caches.
• DefaultCoherentCacheSpec<K,V> for two-level coherent cache behavior and cache breakdown protection.
• MultipleInstanceSyncSpec<K,V> and CacheEvictedEventBusSpec for cross-instance coherence and event buses.

Use the repo's createCacheEntry(): Pair<K, V> contract:

class MyDistributedCacheTest : DistributedCacheSpec<String>() {
    override fun createCache(): DistributedCache<String> {
        return MyDistributedCache()
    }

    override fun createCacheEntry(): Pair<String, String> {
        return UUID.randomUUID().toString() to "test_value"
    }
}

Key Classes

Build Commands

./gradlew build -x test
./gradlew test
./gradlew :cocache-core:test
./gradlew :cocache-core:test --tests "me.ahoo.cache.proxy.ProxyCacheTest"
./gradlew :cocache-spring-redis:check
./gradlew :cocache-spring-boot-starter:check
./gradlew check