ESP-032 — Distributed Cache Support (Redis)

Objective

Expose an optional caching infrastructure for SQL strings generated by FluentSQL. The goal is to allow the results of complex serialization to be stored and retrieved from a distributed cache (Redis), avoiding the cost of rebuilding the string from the AST in repetitive executions with the same state.

Scope

• Definition of the IFluentSQLCacheProvider interface in the Core.
• Implementation of TFluentSQLRedisCacheProvider in a new expansion unit/driver.
• Hashing mechanism of the AST or query components to generate unique cache keys.
• Integration in TFluentSQL (or builder) to check the cache before calling the serializer.
• Support for configurable TTL (Time-to-Live).
• Documented "Cache Miss" and "Cache Hit" cases.

Out of Scope

• Implementation of the Redis client (should use existing libraries like DelphiRedisClient).
• Local disk persistence.
• Complex cache invalidation based on DB events.
• Caching dynamic parameters (only the SQL string structure).

Business Rules

1. The cache must never return invalid or outdated SQL relative to the current builder state.
2. Redis connection failure should not prevent SQL generation (automatic fallback to local serialization).
3. The cache key must be deterministic relative to the dialect and query structure.

Technical Impact

• New files: Source/Core/FluentSQL.Cache.Interfaces.pas, Source/Drivers/FluentSQL.Cache.Redis.pas.
• Changes in FluentSQL.pas to support .WithCache(provider).
• Optional dependency on a Redis client.

Acceptance Criteria

• Cache interface defined and decoupled.
• Redis provider implemented and functional with mock or real server.
• Unit tests validating hit/miss/fallback.
• Documentation of the extension usage by engine (Redis).