Recipe: caching

kandra-runtime declares Caffeine as compileOnly — it's on Kandra's own compile classpath (so KandraCache can call it directly in source) but not transitively pulled into your app's runtime classpath. If you annotate an entity @CacheResult and never add com.github.ben-manes.caffeine:caffeine to your own dependencies, Kandra doesn't fail — KandraCache falls back to a no-op cache, and logs a WARN: "@CacheResult is configured but Caffeine is not on the classpath — caching disabled. Add 'com.github.ben-manes.caffeine:caffeine' to your dependencies." Every findById call still works correctly — it just always misses, silently paying full ScyllaDB round-trip cost on a code path you believed was cached, unless you're watching the startup logs for that specific warning.

This wasn't always a clean fallback. KandraCache.resolveMethod originally resolved getIfPresent/put/invalidate against the cache instance's own concrete runtime class (target.javaClass.getMethod(...)) — but Caffeine's actual cache implementations are package-private; only the public Cache interface is public. The Method object it found was technically public but its declaring class wasn't, so every invoke() threw IllegalAccessException the instant a real Caffeine dependency was on the classpath — the exact scenario @CacheResult exists for. Fixed by resolving the method against Caffeine's public Cache interface instead of the concrete class, so the access check passes without needing setAccessible(true). If you're not on a version with this fix, every write to a cached entity crashes as soon as Caffeine is actually present — worth confirming you're past ISS-023 before trusting this feature in production.

This is the load-bearing gotcha for this whole page — read it even if you skip everything else here.

findById's real cache key is derived from its actual idValues arguments: a bare single value when the entity's full primary key is exactly one column, otherwise an ordered List of every value passed in (partition key and clustering key, in full — required since ISS-025). But every write method's invalidation call used a different helper, partitionKeyOf(entity), which collected only schema.partitionKeys and always returned a bare single value, regardless of whether the entity had clustering keys at all.

For any entity with a clustering key — a time-series table, anything with a composite primary key — those two shapes never matched. findById(userId, bucketedAt)'s real cache key was the List [userId, bucketedAt]; update()'s invalidation call produced the bare userId. The invalidation call didn't error, didn't warn — it just invalidated a cache key that was never the one findById was actually using, so the real, stale entry sat in the cache untouched. update() appeared to succeed. findById kept serving the pre-update row until the TTL expired on its own — silently, with no exception anywhere in the call chain to catch.

This bug did not exist before ISS-025 shipped: when findById(id) (partition-key-only, one argument) was still the "normal," if silently-wrong-row, way to call it on a clustering-keyed entity, its cache key was also a bare single value — matching partitionKeyOf's shape by coincidence. Tightening findById's key contract to require the full key (the ISS-025 fix) changed the cache key's real shape too, but the invalidation helper was a separate piece of code that nobody updated to match — a scope gap in that fix, not an independent new mistake.

Fixed by replacing partitionKeyOf with cacheKeyOf, which reuses the same keyValuesOf helper append/remove/put already relied on, and applies findById's exact shape convention: bare single value for a one-column key, ordered List otherwise. Verified live against a real cluster: save a clustering-keyed @CacheResult entity, findById (full key) to populate the cache, update() a field, findById (same full key) again — now returns the fresh row, not the stale cached one.