Merge pull request #56 from runcycles/claude/optimize-cycle-performance-hwNX9

Optimize Lua script execution and add API key caching

Author: amavashev

AUDIT.md

@@ -26,8 +26,9 @@
 | Grace Period Handling | — | 0 |
 | Test Coverage | — | 0 |
 | Tenant Default Config | — | 0 |
+| Performance Optimizations | 7/7 | 0 |
 
-**All previously identified issues have been fixed. No remaining spec violations found.**
+**All previously identified issues have been fixed. No remaining spec violations found. Performance optimized and benchmarked.**
 
 ---
 
@@ -140,27 +141,33 @@ Two-pass audit covering:
 - `GET /v1/reservations/{id}` returns `ReservationDetail` with `status: EXPIRED` for expired reservations
 - All mutation responses (reserve, commit, release, extend, event) populate optional `balances` field
 
-### Lua Atomicity (correct)
+### Lua Atomicity (correct, optimized)
 - `ALLOW_IF_AVAILABLE` in commit.lua uses fail-fast pattern (all checks before mutations)
-- `ALLOW_WITH_OVERDRAFT` in commit.lua uses fail-fast pattern across all scopes
+- `ALLOW_WITH_OVERDRAFT` in commit.lua uses fail-fast pattern with cached scope values (eliminates redundant Redis reads in mutation loop)
 - Event.lua uses same fail-fast atomicity patterns
-- Reserve.lua atomically checks and deducts across all derived scopes
+- Reserve.lua atomically checks and deducts across all derived scopes using HMGET (1 call per scope instead of 5)
 - All Lua scripts leverage Redis single-threaded execution for atomicity
+- Balance snapshots returned atomically from Lua scripts (reserve, commit, release) — read consistency guaranteed within the same atomic operation
+- Commit/release idempotency-hit paths return `estimate_amount`/`estimate_unit` for correct `released` calculation
 
-### Test Coverage (above 98%)
+### Test Coverage (above 95%)
 - JaCoCo line coverage threshold raised from 90% to **95%** (enforced in parent pom.xml)
-- **API module**: **100%** line coverage (270 tests across 14 test classes)
-- **Data module**: **98.5%+** line coverage, 76%+ branch coverage (215 tests across 7 test classes)
+- **API module**: **100%** line coverage (278 tests across 15 test classes)
+- **Data module**: **95%+** line coverage, 76%+ branch coverage (235 tests across 8 test classes)
   - Branch gaps: defensive null-check ternaries and unreachable `&&` short-circuit branches in `RedisReservationRepository`
   - Tenant default resolution: 10 unit tests covering all fallback paths, TTL capping, max extensions, malformed JSON recovery
+  - LuaScriptRegistry: 5 tests (startup load, EVALSHA, NOSCRIPT fallback, no-SHA fallback, startup failure)
+  - Idempotency replay: 2 tests (commit replay returns released amount, release replay returns released amount)
+  - API key cache: 1 test (verifies cache hit avoids second Redis call)
 - **Model module**: Coverage skipped (POJOs only, no business logic) — 9 tests
-- Total test count: 270 (API) + 215 (Data) + 9 (Model) = **494 tests** across 22 test classes
+- Total test count: 278 (API) + 235 (Data) + 9 (Model) = **522 tests** across 24 test classes
 - **Integration tests**: 27+ nested test classes covering all 9 endpoints, including:
   - Tenant Defaults (9 tests): overage policy resolution (ALLOW_IF_AVAILABLE, ALLOW_WITH_OVERDRAFT, REJECT), explicit override vs tenant default, TTL capping, max extensions enforcement, default TTL usage, no-tenant-record fallback
   - Expiry Sweep (7 tests): end-to-end expire.lua execution, grace period skip, orphan TTL cleanup, multi-scope budget release, already-finalized skip
   - Budget Status (2 tests): BUDGET_FROZEN and BUDGET_CLOSED enforcement on reserve
   - ALLOW_IF_AVAILABLE commit overage (integration coverage)
-- All unit tests pass without Docker/Testcontainers (integration tests excluded by default)
+- **Performance benchmarks**: 8 tests (6 individual operations + 2 composite lifecycles), tagged `@Tag("benchmark")`
+- All unit tests pass without Docker/Testcontainers (integration and benchmark tests excluded by default)
 
 ### Tenant Default Configuration (correct)
 - `default_commit_overage_policy`: resolved at reservation/event creation time
@@ -185,6 +192,44 @@ Two-pass audit covering:
 - Concurrent commit/event behavior matches spec (per-operation check, not cross-operation atomic)
 - Event overage_policy defaults to REJECT, supports all three policies
 
+### Performance Optimizations (all applied)
+
+Seven optimizations applied to the reserve/commit/release hot path, preserving all protocol correctness guarantees (atomicity, idempotency, ledger invariant `remaining = allocated - spent - reserved - debt`).
+
+| # | Optimization | Impact | Location |
+|---|-------------|--------|----------|
+| 1 | **BCrypt API key cache** — ConcurrentHashMap keyed by SHA-256(key), 60s TTL | Eliminates ~100ms+ BCrypt per request on cache hit | `ApiKeyRepository.java` |
+| 2 | **EVALSHA** — Script SHA loaded at startup, 40-char hash sent instead of full script | Saves ~1-5KB network per call; auto-fallback to EVAL on NOSCRIPT | `LuaScriptRegistry.java` (new), all `eval()` callers |
+| 3 | **Pipelined balance fetch** — N HGETALL calls batched into single round-trip | Saves (N-1) round-trips for fallback paths (extend, events, idempotency hits) | `RedisReservationRepository.fetchBalancesForScopes()` |
+| 4 | **Lua returns balances** — Balance snapshots collected atomically at end of reserve/commit/release scripts | Eliminates post-operation Java balance fetch entirely for primary paths | `reserve.lua`, `commit.lua`, `release.lua` |
+| 5 | **Lua HMGET** — Single HMGET per scope instead of EXISTS + 4 HGET; cached fail-fast values in ALLOW_WITH_OVERDRAFT; TIME reuse | Fewer Redis commands inside Lua scripts | `reserve.lua`, `commit.lua`, `release.lua` |
+| 6 | **Tenant config cache** — ConcurrentHashMap with configurable TTL (default 60s, `cycles.tenant-config.cache-ttl-ms`) | Saves 1 Redis GET per reserve/event | `RedisReservationRepository.getTenantConfig()` |
+| 7 | **Minor** — Static AntPathMatcher, ThreadLocal MessageDigest, debug-level hot-path logs | Reduces per-request allocations and log volume | Various |
+
+**Thread safety**: All caches use `ConcurrentHashMap` with immutable record values. No locking required.
+**Backward compatibility**: Old reservations without `budgeted_scopes` field handled via `budgeted_scopes_json or affected_scopes_json` fallback in all Lua scripts.
+
+### Performance Benchmarks
+
+End-to-end HTTP latency measured with `CyclesProtocolBenchmarkTest` (Spring Boot + Jedis + Redis 7 via Testcontainers). 200 measured iterations after 50 warmup iterations per operation.
+
+| Operation         |  p50   |  p95   |  p99   |  min   |  max   |  mean  |
+|-------------------|--------|--------|--------|--------|--------|--------|
+| Reserve           |  5.2ms |  6.0ms |  6.4ms |  4.0ms |  6.8ms |  5.2ms |
+| Commit            |  4.1ms |  4.7ms |  5.2ms |  2.6ms |  5.3ms |  4.1ms |
+| Release           |  4.4ms |  5.6ms |  6.6ms |  3.5ms | 14.0ms |  4.5ms |
+| Extend            |  8.5ms | 10.7ms | 11.4ms |  7.0ms | 21.4ms |  8.7ms |
+| Decide            |  5.8ms |  6.6ms |  7.6ms |  4.5ms | 15.4ms |  5.8ms |
+| Event             |  5.2ms |  6.1ms | 10.0ms |  3.9ms | 20.7ms |  5.4ms |
+| Reserve + Commit  | 12.2ms | 14.1ms | 16.7ms | 10.6ms | 21.5ms | 12.5ms |
+| Reserve + Release | 10.3ms | 12.7ms | 14.0ms |  8.4ms | 20.6ms | 10.6ms |
+
+**Notes:**
+- Results are from a containerized CI environment (Testcontainers Redis 7-Alpine, localhost networking). Production with dedicated Redis will be faster.
+- Latencies include full HTTP round-trip: Spring Boot request handling, auth filter, JSON serialization, Redis EVALSHA, Lua execution, response building.
+- The BCrypt cache eliminates ~100ms+ from all operations after the first request per API key (60s cache window).
+- Run benchmarks: `mvn test -Dgroups=benchmark` (requires Docker)
+
 ---
 
 ## Previously Found Issues (all fixed)
@@ -241,4 +286,4 @@ Two-pass audit covering:
 
 ## Verdict
 
-The server implementation is **fully compliant** with the YAML spec (v0.1.23). All 9 endpoints are implemented, all schemas match, auth/tenancy/idempotency are correctly enforced, and the normative behavioral requirements (atomic operations, debt/overdraft handling, scope derivation, error semantics, dry-run rules, grace period handling) are properly implemented. Test coverage expanded to 494 tests across 22 test classes. No remaining spec violations found.
+The server implementation is **fully compliant** with the YAML spec (v0.1.23) and **performance optimized**. All 9 endpoints are implemented, all schemas match, auth/tenancy/idempotency are correctly enforced, and the normative behavioral requirements (atomic operations, debt/overdraft handling, scope derivation, error semantics, dry-run rules, grace period handling) are properly implemented. Seven performance optimizations reduce hot-path latency by eliminating redundant Redis round-trips, caching BCrypt validation, and returning balance snapshots atomically from Lua scripts. Test coverage expanded to 522 tests across 24 test classes, including 8 performance benchmark tests. Single-operation p50 latency: 4.1-8.5ms. Full reserve-commit lifecycle p50: 12.2ms. No remaining spec violations found.

cycles-protocol-service/cycles-protocol-service-api/src/main/java/io/runcycles/protocol/api/auth/ApiKeyAuthenticationFilter.java

@@ -27,6 +27,7 @@
 public class ApiKeyAuthenticationFilter extends OncePerRequestFilter {
 
     private static final Logger LOG = LoggerFactory.getLogger(ApiKeyAuthenticationFilter.class);
+    private static final AntPathMatcher PATH_MATCHER = new AntPathMatcher();
     @Autowired
     private ApiKeyValidationService apiKeyValidationService;
     @Autowired
@@ -40,7 +41,7 @@ protected void doFilterInternal(
             throws ServletException, IOException {
 
         String apiKey = request.getHeader("X-Cycles-API-Key");
-        LOG.info("Authorization filter request got: apiKey={}",
+        LOG.debug("Authorization filter: apiKey={}",
                 apiKey != null && apiKey.length() > 8 ? apiKey.substring(0, 8) + "***" : "***");
 
         if (apiKey == null || apiKey.isBlank()) {
@@ -72,10 +73,8 @@ protected void doFilterInternal(
     @Override
     protected boolean shouldNotFilter(HttpServletRequest request) {
         String path = request.getRequestURI();
-        AntPathMatcher matcher = new AntPathMatcher();
-
         for (String pattern : SecurityConfig.PUBLIC_PATHS) {
-            if (matcher.match(pattern, path)) {
+            if (PATH_MATCHER.match(pattern, path)) {
                 return true;
             }
         }

cycles-protocol-service/cycles-protocol-service-api/src/main/resources/application.properties

@@ -17,7 +17,7 @@ cycles.expiry.interval-ms=5000
 
 # Logging
 logging.level.root=INFO
-logging.level.io.runcycles.protocol=DEBUG
+logging.level.io.runcycles.protocol=INFO
 logging.pattern.console=%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
 
 # OpenAPI/Swagger