feat: Distributed cache interceptor for queries (ICacheableQuery<TResponse>)

[Copilot]

Adds transparent IDistributedCache caching for queries via a pipeline interceptor, eliminating per-handler cache boilerplate. Caching is opt-in per query type via ICacheableQuery<TResponse>.

New contracts (NetEvolve.Pulse.Extensibility)

• ICacheableQuery<TResponse> — extends IQuery<TResponse> with CacheKey and Expiry properties.
• CacheExpirationMode — enum to distinguish between Absolute (default) and Sliding expiration.
• QueryCachingOptions — options class with:
  • JsonSerializerOptions — for custom cache serialization (defaults to JsonSerializerOptions.Default)
  • ExpirationMode — absolute vs. sliding expiry (defaults to Absolute)
  • DefaultExpiry — fallback TimeSpan? applied when ICacheableQuery<TResponse>.Expiry returns null (defaults to null, meaning no explicit expiration)

New interceptor (NetEvolve.Pulse)

• DistributedCacheQueryInterceptor<TQuery, TResponse> — registered as IRequestInterceptor<,> (scoped). Behavior:
  • Non-ICacheableQuery queries pass through unchanged.
  • Cache hit → deserializes and returns; handler is skipped.
  • Cache miss → invokes handler, serializes response via System.Text.Json, stores with optional expiry.
  • IDistributedCache not registered → falls through silently.
  • Serialization uses the JsonSerializerOptions from QueryCachingOptions.
  • Effective expiry is resolved as ICacheableQuery<TResponse>.Expiry ?? QueryCachingOptions.DefaultExpiry; applied as absolute or sliding based on ExpirationMode.

Registration

• AddQueryCaching(Action<QueryCachingOptions>? configure = null) added to IMediatorConfigurator and implemented in MediatorConfigurator. Options are registered via the standard Options pattern.

services.AddDistributedMemoryCache();
services.AddPulse(c => c.AddQueryCaching(options =>
{
    options.ExpirationMode = CacheExpirationMode.Sliding;
    options.DefaultExpiry = TimeSpan.FromMinutes(10); // fallback when query Expiry is null
    options.JsonSerializerOptions = new JsonSerializerOptions
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    };
}));

public record GetProductQuery(Guid Id) : ICacheableQuery<ProductDto>
{
    public string? CorrelationId { get; set; }
    public string CacheKey => $"product:{Id}";
    public TimeSpan? Expiry => TimeSpan.FromMinutes(5); // overrides DefaultExpiry when set
}

Test coverage

• Unit tests: cache hit, cache miss, expiry, null expiry, no-cache fallthrough, non-cacheable pass-through, expired entry refresh, sliding expiration mode, custom JsonSerializerOptions, DefaultExpiry applied when query expiry is null, query expiry overrides DefaultExpiry.
• Integration tests: end-to-end with MemoryDistributedCache verifying second-invocation cache hit, non-cacheable query bypass, no-cache fallthrough, sliding expiration, custom JSON options, and DefaultExpiry fallback.

Breaking change (interface)

Existing IMediatorConfigurator stub implementations in tests (Polly, SqlServer, EntityFramework) updated to satisfy the updated AddQueryCaching(Action<QueryCachingOptions>? configure = null) signature.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[samtrion]

@copilot Please update the README files for each project and the solution readme

[Copilot]

@copilot Please update the README files for each project and the solution readme

Done in commit 16dcb19. Updated the three READMEs directly affected by the new feature:

• Root README.md — added distributed query caching to the solution features list
• src/NetEvolve.Pulse/README.md — added distributed query caching to the features list and a new "Distributed Query Caching" configuration section with a behavior table
• src/NetEvolve.Pulse.Extensibility/README.md — added ICacheableQuery<TResponse> to the features list and a new "Cacheable Queries" usage section with a full code example

The provider packages (Polly, EntityFramework, SqlServer, Dapr) were left unchanged as query caching is unrelated to their functionality.

[samtrion]

@copilot Please solve open comments

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.48%. Comparing base (19680ce) to head (294fa7c).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #152      +/-   ##
==========================================
+ Coverage   86.12%   86.48%   +0.36%     
==========================================
  Files          42       44       +2     
  Lines        1312     1347      +35     
  Branches      123      130       +7     
==========================================
+ Hits         1130     1165      +35     
  Misses        145      145              
  Partials       37       37              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

@copilot Please solve open comments

Addressed in commit 6f7e513:

• Added CacheExpirationMode enum (Absolute / Sliding) in NetEvolve.Pulse.Extensibility
• Added QueryCachingOptions class in NetEvolve.Pulse.Extensibility with JsonSerializerOptions (for custom serialization) and ExpirationMode (to choose between absolute and sliding expiration)
• Updated AddQueryCaching(Action<QueryCachingOptions>? configure = null) on IMediatorConfigurator to accept optional configuration
• Updated DistributedCacheQueryInterceptor to inject IOptions<QueryCachingOptions> and use the configured options for both serialization and expiry mode
• Extended unit and integration tests to cover both new options

[aikido-pr-checks]

Implemented IMediatorConfigurator.AddQueryCaching(Action?) — adding this required interface method breaks existing implementers. Add a default interface implementation or keep the interface unchanged.

Details

✨ AI Reasoning
​The concrete MediatorConfigurator type now includes a new public AddQueryCaching method to match the updated interface. While adding the implementation itself is fine, the underlying interface addition forces all external implementers of IMediatorConfigurator to add the same method, breaking source compatibility.

🔧 How do I fix it?
Support both old and new parameter names during transition periods. Add new optional parameters with defaults. Keep existing response fields while adding new ones. Focus on backwards compatibility.

_{Reply @AikidoSec feedback: [FEEDBACK] to get better review comments in the future.
Reply @AikidoSec ignore: [REASON] to ignore this issue.
More info}