feat: Implement hybrid caching with Redis and Aspire orchestration, including localization-aware extensions and a new caching guide.

Author: aalmada

README.md

@@ -134,6 +134,7 @@ BookStore/
 - **[API Conventions](docs/api-conventions-guide.md)** - Time handling and JSON serialization standards
 - **[ETag Support](docs/etag-guide.md)** - Optimistic concurrency and caching
 - **[Correlation & Causation IDs](docs/correlation-causation-guide.md)** - Distributed tracing
+- **[Caching Guide](docs/caching-guide.md)** - Hybrid caching with Redis and localization support
 - **[Real-time Notifications](docs/signalr-guide.md)** - SignalR integration and optimistic updates
 - **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute to this project
 

docs/caching-guide.md

@@ -0,0 +1,87 @@
+# Caching Guide
+
+This guide explains how to configure and use caching in the BookStore API, specifically focusing on the hybrid caching strategy integrated with .NET Aspire and localization.
+
+## Overview
+
+The BookStore API uses **Hybrid Caching** (`HybridCache`), enriched by **.NET Aspire** for seamless distributed cache orchestration.
+
+**Components:**
+- **L1 Cache (In-Memory)**: Local, fast access.
+- **L2 Cache (Distributed)**: Redis, orchestrated by Aspire.
+- **Stampede Protection**: Built-in to coalescing requests.
+- **Localization Awareness**: Automatically scopes cache keys to the user's culture.
+
+## Configuration
+
+### Aspire Orchestration
+
+The caching infrastructure is automatically wired up by .NET Aspire.
+
+1.  **AppHost**: Declares the Redis resource.
+    ```csharp
+    var cache = builder.AddRedis("cache");
+    builder.AddProject<Projects.BookStore_ApiService>("apiservice")
+           .WithReference(cache);
+    ```
+
+2.  **Service Defaults**: Redis configuration is injected via service discovery. The API service adds the distributed cache:
+    ```csharp
+    builder.Services.AddRedisDistributedCache("cache");
+    builder.Services.AddHybridCache();
+    ```
+
+## Localized Caching
+
+**Challenge**: Content (e.g., book descriptions) changes based on the user's language (`Accept-Language`). If you cache "book-123" without considering culture, a Portuguese user might receive English content cached by a previous request.
+
+**Solution**: Use the `GetOrCreateLocalizedAsync` extension method.
+
+### Usage Pattern
+
+Instead of `GetOrCreateAsync`, use `GetOrCreateLocalizedAsync`. This method automatically appends the current UI culture (e.g., `|en-US`, `|pt-BR`) to the cache key.
+
+```csharp
+public class BookService(HybridCache cache)
+{
+    public async Task<Book?> GetBookAsync(string id, CancellationToken token = default)
+    {
+        // Key becomes "book-{id}|{culture}" automatically
+        return await cache.GetOrCreateLocalizedAsync(
+            key: $"book-{id}",
+            factory: async cancel => await RetrieveBookFromDatabaseAsync(id, cancel),
+            token: token
+        );
+    }
+}
+```
+
+### Invalidation
+
+When invalidating localized content, ensure you remove the localized entry or use tags.
+
+**Remove specific localized entry**:
+```csharp
+// Removes "book-{id}|{current_culture}"
+await cache.RemoveLocalizedAsync($"book-{id}");
+```
+
+**Remove by Tag (Recommended)**:
+Tags are culture-agnostic. Tagging all variations of a book allows you to clear all languages at once.
+
+```csharp
+await cache.GetOrCreateLocalizedAsync(
+    $"book-{id}",
+    factory,
+    tags: [$"book:{id}"] 
+);
+
+// Clears English, Portuguese, Spanish, etc. for this book
+await cache.RemoveByTagAsync($"book:{id}");
+```
+
+## Best Practices
+
+1.  **Use Tags for Entities**: Always tag cache entries with the entity ID (e.g., `book:123`). This makes invalidation much easier than tracking every culture-variant key.
+2.  **Use Localized Methods**: Prefer `GetOrCreateLocalizedAsync` for any content that *might* be localized, even if it isn't yet.
+3.  **Environment Awareness**: Aspire handles the connection strings. In development, it spins up a Redis container. In production, it points to your managed Redis instance.

docs/toc.yml

@@ -22,6 +22,8 @@
       href: logging-guide.md
     - name: ETag
       href: etag-guide.md
+    - name: Caching
+      href: caching-guide.md
     - name: Correlation & Causation
       href: correlation-causation-guide.md
     - name: API Conventions

src/ApiService/BookStore.ApiService/BookStore.ApiService.csproj

@@ -23,10 +23,12 @@
   <ItemGroup>
     <PackageReference Include="Asp.Versioning.Http" Version="8.1.1" />
     <PackageReference Include="Aspire.Azure.Storage.Blobs" Version="13.1.0" />
+    <PackageReference Include="Aspire.StackExchange.Redis.DistributedCaching" Version="13.1.0" />
     <PackageReference Include="AspNetCore.HealthChecks.NpgSql" Version="9.0.0" />
     <PackageReference Include="Marten" Version="8.17.0" />
     <PackageReference Include="Marten.AspNetCore" Version="8.17.0" />
     <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.1" />
+    <PackageReference Include="Microsoft.Extensions.Caching.Hybrid" Version="9.0.0-preview.9.24556.5" />
     <PackageReference Include="Microsoft.OpenApi" Version="2.0.0" />
     <PackageReference Include="Npgsql.OpenTelemetry" Version="10.0.1" />
     <PackageReference Include="Scalar.AspNetCore" Version="2.11.10" />

src/ApiService/BookStore.ApiService/Infrastructure/Extensions/ApplicationServicesExtensions.cs

@@ -46,6 +46,10 @@ public static IServiceCollection AddApplicationServices(
         _ = services.AddResponseCaching();
         _ = services.AddOutputCache();
 
+#pragma warning disable EXTEXP0018 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+        _ = services.AddHybridCache();
+#pragma warning restore EXTEXP0018 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+
         return services;
     }
 

src/ApiService/BookStore.ApiService/Infrastructure/Extensions/HybridCacheExtensions.cs

@@ -0,0 +1,59 @@
+using System.Globalization;
+using Microsoft.Extensions.Caching.Hybrid;
+
+namespace BookStore.ApiService.Infrastructure.Extensions;
+
+/// <summary>
+/// Extension methods for HybridCache to support localization-aware caching
+/// </summary>
+public static class HybridCacheExtensions
+{
+    /// <summary>
+    /// Gets or creates a cache entry using a key that is automatically scoped to the current UI culture.
+    /// </summary>
+    /// <typeparam name="TItem">The type of the item in the cache.</typeparam>
+    /// <param name="cache">The hybrid cache instance.</param>
+    /// <param name="key">The base cache key.</param>
+    /// <param name="factory">The factory to create the item if it does not exist.</param>
+    /// <param name="options">Optional entry options.</param>
+    /// <param name="tags">Optional tags for the entry.</param>
+    /// <param name="token">Cancellation token.</param>
+    /// <returns>The cached or newly created item.</returns>
+    public static ValueTask<TItem> GetOrCreateLocalizedAsync<TItem>(
+        this HybridCache cache,
+        string key,
+        Func<CancellationToken, ValueTask<TItem>> factory,
+        HybridCacheEntryOptions? options = null,
+        IEnumerable<string>? tags = null,
+        CancellationToken token = default)
+    {
+        var localizedKey = GetLocalizedKey(key);
+        return cache.GetOrCreateAsync(localizedKey, factory, options, tags, token);
+    }
+
+    /// <summary>
+    /// Removes a cache entry using a key that is automatically scoped to the current UI culture.
+    /// </summary>
+    /// <param name="cache">The hybrid cache instance.</param>
+    /// <param name="key">The base cache key.</param>
+    /// <param name="token">Cancellation token.</param>
+    public static ValueTask RemoveLocalizedAsync(
+        this HybridCache cache,
+        string key,
+        CancellationToken token = default)
+    {
+        var localizedKey = GetLocalizedKey(key);
+        return cache.RemoveAsync(localizedKey, token);
+    }
+
+    /// <summary>
+    /// Helper to append current culture to the key.
+    /// Format: "key|culture" (e.g., "book-123|en-US")
+    /// </summary>
+    private static string GetLocalizedKey(string key)
+    {
+        var culture = CultureInfo.CurrentUICulture.Name;
+        // Use a pipe delimiter - distinct from colon usually used for hierarchy
+        return $"{key}|{culture}";
+    }
+}

src/ApiService/BookStore.ApiService/Program.cs

@@ -15,6 +15,9 @@
 // Add Azure Blob Storage client (Azurite locally, Azure in production)
 builder.AddAzureBlobServiceClient("blobs");
 
+// Add Redis distributed cache
+builder.AddRedisDistributedCache("cache");
+
 // Configure services
 builder.Services.AddJsonConfiguration(builder.Environment);
 builder.Services.AddApplicationServices(builder.Configuration);

src/BookStore.AppHost/AppHost.cs

@@ -13,9 +13,12 @@
 
 var blobs = storage.AddBlobs("blobs");
 
+var cache = builder.AddRedis("cache");
+
 var apiService = builder.AddProject<Projects.BookStore_ApiService>("apiservice")
     .WithReference(bookStoreDb)
     .WithReference(blobs) // Add blob storage reference
+    .WithReference(cache)
     .WithHttpHealthCheck("/health")
     .WithExternalHttpEndpoints()
     .WithUrlForEndpoint("http", url =>

src/BookStore.AppHost/BookStore.AppHost.csproj

@@ -8,6 +8,7 @@
   <ItemGroup>
     <PackageReference Include="Aspire.Hosting.Azure.Storage" Version="13.1.0" />
     <PackageReference Include="Aspire.Hosting.PostgreSQL" Version="13.1.0" />
+    <PackageReference Include="Aspire.Hosting.Redis" Version="13.1.0" />
   </ItemGroup>
 
   <ItemGroup>