fix(caching): reset StoredAt on 304 revalidation so Age restarts (v2.2.1)

[FranRuiz98]

Summary

When a stale entry was revalidated and the origin answered 304 Not Modified, the entry's freshness TTL was refreshed but StoredAt kept its original value, so the Age response header kept growing past the revalidation. Observed live with the samples against Kestrel + Redis: /catalog with max-age=10, stale-if-error=60 showed Age: 65 at the moment of a successful 304 revalidation, then Age: 68, 70… on subsequent fresh cache hits instead of restarting near 0.

Per RFC 9111 §4.2.3 the age calculation restarts from the validation response, and §4.3.4 requires the stored response to be updated with the 304's header fields.

Changes

• New shared RefreshFromNotModified helper in CachingMiddleware replaces the three duplicated 304-refresh blocks (foreground RevalidateAsync, background stale-while-revalidate, and HandleHeadAsync). On a 304 it now:
  • resets StoredAt to the revalidation time, so Age restarts from 0 (§4.2.3);
  • merges the 304's header fields (Date, Cache-Control, ETag, …) into the stored headers (§4.3.4);
  • recomputes ExpiresAt / stale windows / MustRevalidate exactly as before.
• Secondary fix that falls out of it: MemoryCacheStore computes its eviction TTL as ExpiresAt − StoredAt, so refreshed entries previously got an inflated eviction window (new ExpiresAt − old StoredAt). DistributedCacheStore keys off absolute ExpiresAt and is unaffected; the reset StoredAt round-trips through its JSON serialization (covered by a test).
• Version bump 2.2.0 → 2.2.1 (pure behavior fix, no API change — say the word if you'd rather ship it as 2.3.0) + README changelog entry.

Tests

New NotModifiedAgeResetTests (6 tests) covering: Age = 0 on the revalidated response, subsequent hits counting age from the revalidation time, §4.3.4 header updates, background (stale-while-revalidate) revalidation, HEAD-triggered revalidation, and the DistributedCacheStore path. All six genuinely fail against the pre-fix code (verified by stashing the middleware change: 6/6 failed).

Freshness logic runs on the injected TimeProvider, so these use FakeTimeProvider — per the v2.1.0 lesson, only physical store-eviction timing needs the real clock, which isn't what's under test here. The distributed test seeds the fake clock with real now so MemoryDistributedCache's real-clock absolute expiration doesn't evict the entry.

Verification

• dotnet build Stampede.Http.slnx --no-incremental: 0 warnings, 0 errors
• dotnet test: 349/349 passed (343 existing + 6 new)

🤖 Generated with Claude Code