feat(bench): add resicache-bench JMH module — SyncLock, BloomFilter, TtlJitter benchmarks + PERFORMANCE.md

[Shubh2-0]

Closes #3

Hey @DavidHLP — sorry for the delay, here's the draft PR with the full JMH module skeleton as discussed.

What's in this PR

New module:

esicache-bench/

A stand-alone Maven module (doesn't inherit spring-boot-starter-parent so JMH's annotation processor and shade plugin work cleanly). Produces an executable fat-jar via maven-shade-plugin.

resicache-bench/ ├── pom.xml └── src/main/java/io/github/davidhlp/bench/ ├── SyncLockBenchmark.java ← cache-breakdown / thundering-herd ├── BloomFilterBenchmark.java ← cache-penetration / Bloom gate └── TtlJitterBenchmark.java ← cache-avalanche / TTL jitter spread

PERFORMANCE.md (repo root)

Documents baseline throughput numbers, SLO thresholds and full run instructions.

---

Benchmark details

SyncLockBenchmark — cache-breakdown protection

Measures SyncSupport leader-follower single-flight in 3 scenarios:

oSync — baseline: all threads race directly to the loader (thundering herd)

• syncLocalOnly_8threads — 8 threads, JVM-local ConcurrentHashMap CAS gate
• syncContended_32threads — 32 threads vs single key (worst-case stampede)

SLO: syncLocalOnly overhead ≤ 2×
oSync per operation

BloomFilterBenchmark — cache-penetration protection

Measures LocalBloomIFilter in 3 scenarios:

• �loomMightContain_hit — true-positive (key in filter, DB proceeds)
• �loomMightContain_miss — definitive-negative (key never inserted, DB skipped)
• �loomPut — insertion cost on first DB load

Parameterised: expectedInsertions, alsePositiveProbability
SLO: �loomMightContain_hit ≥ 5 M ops/s single-thread

TtlJitterBenchmark — cache-avalanche protection

Measures DefaultTtlPolicy TTL jitter computation:

• tlJitter_compute — jittered TTL per cache put (single-thread)
• tlBaseline — raw Duration.toMillis() reference
• tlJitter_concurrent_uniformity — 8 threads, validates no ThreadLocalRandom contention

Parameterised: jitterRatio (0.1, 0.2)
SLO: tlJitter_compute ≥ 10 M ops/s

---

Running

`�ash

install core

mvn -f pom.xml install -DskipTests

build fat-jar

mvn -f resicache-bench/pom.xml package -DskipTests

run all benchmarks (~3-5 min)

java -jar resicache-bench/target/resicache-bench.jar -rf json -rff results.json

run specific suite

java -jar resicache-bench/target/resicache-bench.jar SyncLockBenchmark
`

---

Happy to make any adjustments to the SLO thresholds, JMH config (@WarmUp, @fork, @threads) or add more benchmark scenarios before marking this ready for review.

[DavidHLP]

Thanks for opening the draft and for putting together the JMH module skeleton. Before this is marked ready for review, please align the benchmark suite with the acceptance criteria in #3:

• add a ResiCache chain pass-through vs Spring-native @Cacheable comparison;
• add a benchmark that isolates the additive cost of each handler;
• retain the SyncLock concurrency benchmark.

The Bloom Filter and TTL Jitter benchmarks are useful optional coverage, but they do not substitute for the first two required scenarios.

Please also provide the raw JMH JSON output (or an equivalent reproducible artifact) supporting the numbers in PERFORMANCE.md, including the environment and exact run command. Until then, the reported throughput and SLO conclusions cannot be independently verified.

I have left the PR as a draft and added the performance and changes requested labels.