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.

[DavidHLP]

Thank you @Shubh2-0 for putting together the JMH benchmark module skeleton!

The draft PR has been reviewed, repaired, and integrated into main (via commits c26e0dc and 91285dd):

1. API Compatibility Fixes: Aligned SyncLockProperties.setTimeout, 4-arg BloomFilterConfig constructor, and DefaultTtlPolicy.calculateFinalTtl to match latest core APIs, plus configured Lombok annotation processor paths in root POM.
2. Completed Remaining Acceptance Criteria for [help wanted] Minimal JMH module (3 benchmarks) + PERFORMANCE.md SLO #3: Implemented ChainPassThroughBenchmark (chain vs Spring-native caching baseline) and HandlerAdditiveCostBenchmark (marginal cost across 1 to 5 handlers).
3. Live Measurements: Executed live benchmarks on OpenJDK 21, generated jmh-results.json, and updated PERFORMANCE.md with actual throughput and latency results.

Closing this draft PR as the work is now fully merged and extended in main. Thanks again for your contribution!