Cache Strategies — Cache-Aside, Stampede Protection, and Invalidation

Request arrives
  │
  ▼
Cache hit? → YES → return cached value
  │
  NO
  │
  ▼
Load from database
  │
  ▼
Write to cache with TTL
  │
  ▼
Return value

// Application/Patients/Queries/GetPatient/GetPatientQueryHandler.cs
public async Task<Result<PatientResponse>> Handle(
    GetPatientQuery query, CancellationToken ct)
{
    var cacheKey = $"patient:{query.PatientId.Value}";

    // HybridCache implements Cache-Aside in one call
    var cached = await _cache.GetOrCreateAsync(
        key:     cacheKey,
        factory: async token =>
        {
            var patient = await _patients.GetByIdAsync(query.PatientId, token);
            return patient is null ? null : MapToResponse(patient);
        },
        options: new HybridCacheEntryOptions
        {
            Expiration           = TimeSpan.FromMinutes(10),
            LocalCacheExpiration = TimeSpan.FromSeconds(30),
        },
        tags: [$"patient-{query.PatientId.Value}"],
        ct);

    return cached is null
        ? Result.Failure<PatientResponse>(PatientErrors.NotFound)
        : Result.Success(cached);
}

// After creating a patient, populate the cache immediately
public async Task<Result<PatientId>> Handle(
    CreatePatientCommand command, CancellationToken ct)
{
    // ... create patient, save to DB ...
    await _unitOfWork.SaveChangesAsync(ct);

    // Write-through: populate cache so first read is a cache hit
    var response = MapToResponse(newPatient);
    await _cache.SetAsync(
        key:   $"patient:{newPatient.Id.Value}",
        value: response,
        options: new HybridCacheEntryOptions
        {
            Expiration = TimeSpan.FromMinutes(10),
        },
        tags: [$"patient-{newPatient.Id.Value}"],
        ct);

    return Result.Success(newPatient.Id);
}

// Three invalidation strategies:

// 1. Time-based expiry (simplest, acceptable staleness)
//    Good for: reference data (drug formulary, ICD-10 codes)
//    Bad for: frequently-written clinical data
options.Expiration = TimeSpan.FromMinutes(10);

// 2. Explicit key removal (point invalidation)
//    Good for: simple single-entity invalidation
await _cache.RemoveAsync($"patient:{patientId.Value}", ct);

// 3. Tag-based invalidation (recommended)
//    Good for: cascading invalidation (patient tag covers all patient-related queries)
await _cache.RemoveByTagAsync($"patient-{patientId.Value}", ct);

// Tag naming convention (examples for a clinical system):
"patient-{id}"              → patient profile, prescriptions, drug orders
"patient-list"              → paginated list queries
"formulary"                 → drug formulary (global reference data)
"formulary-{code}"          → specific drug entry
"drug-interactions-{code}"  → interaction data for one drug

// When to invalidate which tags:
// Patient name update:       RemoveByTagAsync($"patient-{id}")
// Prescription added:        RemoveByTagAsync($"patient-{id}")
// Patient deactivated:       RemoveByTagAsync($"patient-{id}"), RemoveByTagAsync("patient-list")
// New patient registered:    RemoveByTagAsync("patient-list")
// Formulary updated:         RemoveByTagAsync("formulary")

// Without protection — the thundering herd problem:
// A popular cache key (drug formulary, read 500 times/second) expires at T=0.
// All 500 concurrent requests see a cache miss and call the database simultaneously.
// Database spike: potentially timeouts, degraded performance, cascade failures.

// With HybridCache's built-in stampede protection:
// All 500 requests call GetOrCreateAsync simultaneously.
// Only 1 request executes the factory.
// 499 requests wait (via SemaphoreSlim) and receive the result from the 1 factory call.
// The database receives exactly 1 query.

// This requires no extra code — it is built into GetOrCreateAsync.

// A drug interaction check queries multiple data sources — expensive to compute
public sealed class GetDrugInteractionsQueryHandler
{
    private readonly IDrugInteractionService _interactions;
    private readonly HybridCache _cache;

    public async Task<Result<DrugInteractionReport>> Handle(
        GetDrugInteractionsQuery query, CancellationToken ct)
    {
        // Sort medication codes so {A,B} and {B,A} hit the same cache key
        var sortedCodes = query.MedicationCodes
            .OrderBy(c => c)
            .ToList();

        var cacheKey = $"interactions:{string.Join(",", sortedCodes)}";

        var report = await _cache.GetOrCreateAsync(
            key: cacheKey,
            factory: async token =>
            {
                // This calls an external drug interaction database API — takes 300ms
                return await _interactions.CheckAsync(sortedCodes, token);
            },
            options: new HybridCacheEntryOptions
            {
                Expiration = TimeSpan.FromHours(24),   // interaction data rarely changes
                LocalCacheExpiration = TimeSpan.FromMinutes(5),
            },
            tags: sortedCodes.Select(c => $"formulary-{c}").ToList(),
            ct);

        return Result.Success(report);
    }
}

// ✗ Do NOT cache real-time clinical data
// INR readings, current vitals, live lab results — stale data is dangerous
// If a patient's INR was 1.8 at 8am but is now 4.9 at 10am, the doctor must see 4.9

// ✗ Do NOT cache mutation results
// After creating a patient, do NOT cache the creation result (only read responses)
// Cache the read response after the fact (write-through if you want it pre-populated)

// ✗ Do NOT cache sensitive data with long TTLs
// Refresh token state, session data, authorization decisions should not live in cache
// for extended periods — a revoked token cached for 10 minutes is a security hole

// ✓ DO cache:
// Drug formulary entries (changes daily at most)
// ICD-10 code lookups (changes annually)
// Patient profile (changes rarely, read very frequently)
// Expensive aggregation reports (department-level statistics)