fix(templates): correct response caching of origin-dependent and faulted responses bitfoundation#12733 (bitfoundation#12734)

Author: yasmoradi

src/Templates/Boilerplate/Bit.Boilerplate/.docs/14- Response Caching System.md

@@ -150,18 +150,29 @@ Output cache still works correctly for multi-language scenarios.
 public async ValueTask CacheRequestAsync(OutputCacheContext context, CancellationToken cancellation)
 {
     var responseCacheAtt = context.HttpContext.GetResponseCacheAttribute();
-    
+
     if (responseCacheAtt is null) return;
 
-    // Default: SharedMaxAge = MaxAge if not specified
-    if (responseCacheAtt.SharedMaxAge == -1)
-    {
-        responseCacheAtt.SharedMaxAge = responseCacheAtt.MaxAge;
-    }
+    context.AllowLocking = true;
+    context.EnableOutputCaching = true;
+
+    // What the output cache keys on, besides the request path:
+    context.CacheVaryByRules.QueryKeys = "*";
+    context.CacheVaryByRules.VaryByHost = true;
+    context.CacheVaryByRules.HeaderNames = new[] { HeaderNames.Origin, "X-Origin" };
+    context.CacheVaryByRules.VaryByValues.Add("Culture", CultureInfo.CurrentUICulture.Name);
+
+    // Multi-tenant: an authenticated request resolves its tenant from the user's claim rather than from the
+    // host, and tenant scoped entities are filtered by it, so two tenants on one host must not share an entry.
+    if (context.HttpContext.User.GetTenantId() is Guid currentTenantId)
+        context.CacheVaryByRules.VaryByValues.Add("Tenant", currentTenantId.ToString());
 
-    var clientCacheTtl = responseCacheAtt.MaxAge;      // In-memory + Browser
-    var edgeCacheTtl = responseCacheAtt.SharedMaxAge;  // CDN Edge
-    var outputCacheTtl = responseCacheAtt.SharedMaxAge; // ASP.NET Core Output Cache
+    // SharedMaxAge falls back to MaxAge when it isn't set
+    var sharedMaxAge = responseCacheAtt.SharedMaxAge == -1 ? responseCacheAtt.MaxAge : responseCacheAtt.SharedMaxAge;
+
+    var clientCacheTtl = responseCacheAtt.MaxAge;  // In-memory + Browser
+    var edgeCacheTtl = sharedMaxAge;               // CDN Edge
+    var outputCacheTtl = sharedMaxAge;             // ASP.NET Core Output Cache
 
     // Disable CDN edge if configured
     if (settings.ResponseCaching?.EnableCdnEdgeCaching is false)
@@ -182,14 +193,49 @@ public async ValueTask CacheRequestAsync(OutputCacheContext context, Cancellatio
         outputCacheTtl = -1;
     }
 
+    // The entry is tagged with the request path only, without the query string: purging is done by bare path
+    // ("/product/5"), while QueryKeys = "*" gives every query string variant its own entry. Tagging those with
+    // their full PathAndQuery would leave "/product/5?utm_source=x" unpurgeable for the rest of its lifetime.
+    context.Tags.Add(new Uri(context.HttpContext.Request.GetUri().GetUrlWithoutCulture()).AbsolutePath.ToLowerInvariant());
+
     // ... set cache headers and output cache policy
 }
 ```
 
+**Responses that are never stored:** a response is kept out of every cache unless it is a `200 OK` that hands out no
+cookies (the culture cookie is exempt, since the cache varies by culture anyway). That keeps a 404 for a product created
+a minute later from surviving on the edge for days, and keeps one caller's cookies from being replayed to everybody else.
+This is enforced twice - by an `OnStarting` callback that downgrades `Cache-Control` to `no-store, private` for browsers
+and CDNs, and by clearing `AllowCacheStorage` in `ServeResponseAsync` for the output cache.
+
+**Telling shared caches what to vary on:**
+
+The output cache keys on `Origin` and `X-Origin`, so the response advertises them too:
+
+```
+Vary: Origin, X-Origin
+```
+
+- `Origin` - the CORS middleware runs before the output cache middleware and echoes the caller's origin into
+  `Access-Control-Allow-Origin`. Without the vary, the first caller's value would be replayed to every other origin and
+  their browsers would reject it.
+- `X-Origin` - the header a Blazor Hybrid / standalone WASM client sends to tell the backend which web app url it is
+  running under (See `HttpRequestExtensions.GetWebAppUrl`), which can end up embedded in the response.
+
+> **A CDN may ignore `Vary`.** Cloudflare does not consider it in caching decisions unless the header is
+> `Accept-Encoding`, or a **Cache Rules → Vary** setting naming `origin` / `x-origin` has been configured on the zone.
+> Without that rule the edge keeps a single variant per URL and hands it to callers of every origin. Configure it before
+> turning `EnableCdnEdgeCaching` on.
+
 **Important Security Note:**
 
 The `UserAgnostic` property is critical for security. If a response contains user-specific data (e.g., user's name, roles, or tenant information), it **must not** be cached in shared caches (CDN edge or output cache). Setting `UserAgnostic = true` is only safe when the response is identical for all users.
 
+> **Multi-tenant + CDN edge:** the `Tenant` discriminator above is part of the **ASP.NET Core output cache key only** -
+> `VaryByValues` never becomes a response header, so a CDN cannot see it. The output cache therefore keeps tenants apart
+> correctly, but an edge cache keyed on host + path does not. Until the tenant is part of the URL or the host, treat
+> `UserAgnostic = true` together with `EnableCdnEdgeCaching` as unsafe for any response whose body is tenant-filtered.
+
 ---
 
 ### 3. ResponseCacheService
@@ -215,10 +261,10 @@ public partial class ResponseCacheService
     /// </summary>
     public async Task PurgeCache(params string[] relativePaths)
     {
-        // Purge from ASP.NET Core output cache
+        // Purge from ASP.NET Core output cache. Lowercased to match the tag the policy writes.
         foreach (var relativePath in relativePaths)
         {
-            await outputCacheStore.EvictByTagAsync(relativePath, default);
+            await outputCacheStore.EvictByTagAsync(relativePath.ToLowerInvariant(), default);
         }
 
         // Purge from Cloudflare CDN
@@ -231,9 +277,9 @@ public partial class ResponseCacheService
     public async Task PurgeProductCache(int shortId)
     {
         await PurgeCache(
-            "/",                                  // Home page (may list products)
-            $"/product/{shortId}",                // Product detail page
-            $"/api/ProductView/Get/{shortId}"     // Product API endpoint
+            "/",                                     // Home page (may list products)
+            $"/product/{shortId}",                   // Product detail page
+            $"/api/v1/ProductView/Get/{shortId}"     // Product API endpoint
         );
     }
 }
@@ -282,7 +328,7 @@ public string? GetPrimaryMediumImageUrl(Uri absoluteServerAddress)
     return HasPrimaryImage is false
         ? null
         : new Uri(absoluteServerAddress, 
-            $"/api/Attachment/GetAttachment/{Id}/{AttachmentKind.ProductPrimaryImageMedium}?v={Version}")
+            $"/api/v1/Attachment/GetAttachment/{Id}/{AttachmentKind.ProductPrimaryImageMedium}?v={Version}")
             .ToString();
 }
 ```
@@ -477,10 +523,44 @@ This prevents accidentally serving User A's data to User B through shared caches
       "https://sales.bitplatform.com",
       "https://sales.bitplatform.uk"
     ]
+  },
+  // Shared/appsettings.json - shared by the server AND every client (WASM, MAUI, Windows)
+  "MemoryCache": {
+    "SizeLimit": 268435456  // 256 MB, in bytes
   }
 }
 ```
 
+Both `ResponseCaching` flags default to `false`. Turn `EnableCdnEdgeCaching` on only after reading the `Vary` and
+multi-tenant notes above.
+
+---
+
+## The L1 Memory Budget
+
+Layers 1 and 4 (Client In-Memory Cache and Output Cache) both live in the app's single `IMemoryCache`, which is bounded
+by `MemoryCache:SizeLimit` in `Shared/appsettings.json` and implemented by `AppMemoryCache`.
+
+**The unit is bytes, not entries.** That matters, because the three kinds of entry are charged differently:
+
+| Entry | Charged | Set by |
+|---|---|---|
+| Output cache response body | its exact length | `FusionOutputCacheStore` (`AddFusionOutputCache`) |
+| Client in-memory cached response | its exact length | `CacheDelegatingHandler` |
+| Everything else (FusionCache data entries, 3rd party libraries) | `AppMemoryCache.EstimatedEntrySizeInBytes` (4 KB) | `WithDefaultEntryOptions` / `AppMemoryCache.CreateEntry` |
+
+The flat 4 KB estimate is deliberately generous: charging an entry too much only means fewer of them fit, while charging
+too little lets the cache outgrow the limit it exists to enforce. At 256 MB the budget holds roughly 65k estimated
+entries, minus whatever the cached response bodies take.
+
+**Why not count entries instead?** Because the output cache stores whole response bodies here. A single pre-rendered
+page or attachment would otherwise cost the same one unit as a small dictionary, letting one big response quietly
+consume a budget sized for tens of thousands of small ones - or, worse, be silently rejected once the limit was reached,
+turning output caching into a no-op with no error anywhere.
+
+If you raise `SizeLimit`, remember the same value ships to the clients: it also bounds the Blazor Hybrid / WASM app's
+in-process cache on a phone, not just the server's.
+
 ---
 
 ## FusionCache Library
@@ -527,13 +607,36 @@ This shows the TTL (in seconds) for each cache layer. Use browser DevTools Netwo
 
 ```
 Cache-Control: public, max-age=300, s-maxage=3600
+Vary: Origin, X-Origin
 App-Cache-Response: Output:3600,Edge:3600,Client:300
 ```
 
 Interpretation:
 - `max-age=300`: Browser and in-memory cache for 5 minutes
 - `s-maxage=3600`: CDN edge and output cache for 1 hour
 - `public`: Can be cached in shared caches (CDN)
+- `Vary`: the request headers a shared cache must include in its key
+- `Output:-1` (or `Edge:-1` / `Client:-1`) means that layer was disabled for this request - by configuration, by the
+  caller being authenticated on a non-`UserAgnostic` endpoint, or by the request being a pre-rendered Blazor page
+
+A response that turns out not to be cacheable (anything other than `200 OK`, or one that sets a cookie) is downgraded to
+`Cache-Control: no-store, private` on its way out, regardless of what `App-Cache-Response` announced earlier in the
+request.
+
+---
+
+### Automated Test
+
+`src/Tests/Features/Caching/ProductResponseCacheTests.cs` exercises the whole loop end to end with
+`EnableOutputCaching` and `PrerenderEnabled` both on: it fills the output cache from two directions (the tenant-user
+calling the `UserAgnostic` product API, and an anonymous visitor loading the pre-rendered product page), has the
+tenant-admin edit the product through `ProductController.Update` and asserts both readers see the change immediately,
+then deletes the row straight from the database and asserts both readers keep being served the deleted product - the
+proof that the responses are coming from the cache and not the database.
+
+Note it needs `ProductController` (Admin module) and `ProductViewController` (Sales module) at the same time, and
+`module` is a single-choice template parameter, so it is excluded from generated projects and only runs against the
+template's own source tree.
 
 ---
 

src/Templates/Boilerplate/Bit.Boilerplate/.template.config/template.json

@@ -449,7 +449,11 @@
                         "**/.git/**",
                         "**/*.nuspec",
                         "src/Server/**/Data/Migrations/**",
-                        "src/**/App_Data/**"
+                        "src/**/App_Data/**",
+                        // Needs ProductController (Admin module) and ProductViewController + the product page (Sales
+                        // module) at once, and "module" is a single choice, so it can only ever run against the
+                        // template's own source tree.
+                        "src/Tests/Features/Caching/ProductResponseCacheTests.cs"
                     ]
                 },
                 {
@@ -547,7 +551,8 @@
                         "src/Tests/Features/Identity/PhoneNumberNormalizationUITests.cs",
                         "src/Tests/Features/Identity/WebAuthnPasswordlessUITests.cs",
                         "src/Tests/Features/OpenApi/OpenApiScalarIntegrationTests.cs",
-                        "src/Tests/Features/ForceUpdate/ForceUpdateUITests.cs"
+                        "src/Tests/Features/ForceUpdate/ForceUpdateUITests.cs",
+                        "src/Tests/Features/Caching/ProductResponseCacheTests.cs"
                     ]
                 },
                 {
@@ -707,4 +712,4 @@
             ]
         }
     ]
-}
+}

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Components/Routes.razor

@@ -6,7 +6,7 @@
             <AppRouter AppAssembly="@GetType().Assembly"
                        AdditionalAssemblies="@(AssemblyLoadContext.Default.Assemblies.Where(asm => asm.GetName().Name?.Contains("Boilerplate.Client") is true))">
                 @*#if (brouter == true)*@
-                <ChildContent>
+                <Routes>
                     @*#if (module == "Admin")*@
                     @* Keep-alive: pages that host a BitDataGrid whose add/edit lives on a separate page
                        (e.g. ProductsPage -> AddOrEditProductPage) keep their grid state - current page,
@@ -16,7 +16,7 @@
                     <Broute KeepAlive Path="@PageUrls.Products" Component="@typeof(Boilerplate.Client.Core.Components.Pages.Products.ProductsPage)" />
                     <Broute KeepAlive Path="@("{culture?}" + PageUrls.Products)" Component="@typeof(Boilerplate.Client.Core.Components.Pages.Products.ProductsPage)" />
                     @*#endif*@
-                </ChildContent>
+                </Routes>
                 @*#endif*@
                 <Found Context="routeData">
                     <AppRouteDataPublisher RouteData="@routeData" />

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Infrastructure/Services/HttpMessageHandlers/CacheDelegatingHandler.cs

@@ -54,7 +54,7 @@ protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage
                     LogScopeData = logScopeData.ToDictionary()
                 }, options: new()
                 {
-                    Size = 1,
+                    Size = responseContent.Length,
                     AbsoluteExpirationRelativeToNow = maxAge
                 });
             }

src/Templates/Boilerplate/Bit.Boilerplate/src/Server/Boilerplate.Server.Api/Features/Identity/IdentityController.ExternalSignIn.cs

@@ -9,8 +9,12 @@ public partial class IdentityController
     [AutoInject] private ApiServerExceptionHandler serverExceptionHandler = default!;
     [AutoInject] private IAuthenticationSchemeProvider authenticationSchemeProvider = default!;
 
+    /// <summary>
+    /// Deliberately not cached: the returned URL embeds the caller's origin, which GetWebAppUrl resolves from the X-Origin
+    /// header. That header is part of neither the output cache's vary rules nor a CDN's cache key, so a cached response would
+    /// hand one origin's sign-in URL to a caller coming from another, sending the resulting sign-in link to the wrong origin.
+    /// </summary>
     [HttpGet]
-    [AppResponseCache(SharedMaxAge = 3600 * 24 * 7, MaxAge = 60 * 5)]
     public async Task<string> GetExternalSignInUri(string provider, string? returnUrl = null, int? localHttpPort = null, CancellationToken cancellationToken = default)
     {
         var uri = Url.Action(nameof(ExternalSignIn), new { provider, returnUrl, localHttpPort, origin = Request.GetWebAppUrl() })!;