[BlazorWebView] Add opt-in static content caching

src/BlazorWebView/src/Maui/Android/WebKitWebViewClient.cs

@@ -1,4 +1,6 @@
-using System;
+using System;
+using System.Collections.Generic;
+using System.IO;
 using System.Runtime.Versioning;
 using Android.Content;
 using Android.Runtime;
@@ -21,6 +23,9 @@ internal class WebKitWebViewClient : WebViewClient
 		private static readonly Uri AppOriginUri = new(AppOrigin);
 
 		private readonly BlazorWebViewHandler? _webViewHandler;
+		// Android does not store WebResourceResponse instances returned from ShouldInterceptRequest in Chromium's
+		// HTTP cache. Keep explicitly cacheable static responses in a bounded per-WebView cache instead.
+		private readonly StaticContentResponseCache _staticContentResponseCache = new();
 
 		public WebKitWebViewClient(BlazorWebViewHandler webViewHandler)
 		{
@@ -100,7 +105,7 @@ private bool ShouldOverrideUrlLoadingCore(IWebResourceRequest? request)
 				}
 
 				// 2. Check if the request is for a Blazor resource
-				response = GetResponse(requestUri, _webViewHandler?.Logger);
+				response = GetResponse(request, requestUri, _webViewHandler?.Logger);
 				if (response is not null)
 				{
 					return response;
@@ -113,9 +118,33 @@ private bool ShouldOverrideUrlLoadingCore(IWebResourceRequest? request)
 			return base.ShouldInterceptRequest(view, request);
 		}
 
-		private WebResourceResponse? GetResponse(string requestUri, ILogger? logger)
+		private WebResourceResponse? GetResponse(IWebResourceRequest request, string requestUri, ILogger? logger)
 		{
+			if (!Uri.TryCreate(requestUri, UriKind.Absolute, out var uri) || !AppOriginUri.IsBaseOf(uri))
+			{
+				return null;
+			}
+
+			StaticContentCacheRequestBehavior? cacheRequestBehavior = null;
+			if (_staticContentResponseCache.TryGet(requestUri, out var cachedResponse))
+			{
+				cacheRequestBehavior = StaticContentResponseCachePolicy.GetRequestBehavior(request.Method, request.RequestHeaders);
+				if (cacheRequestBehavior == StaticContentCacheRequestBehavior.Default)
+				{
+					var cachedRequestUri = QueryStringHelper.RemovePossibleQueryString(requestUri);
+					logger?.HandlingWebRequest(cachedRequestUri);
+					logger?.ResponseContentBeingSent(cachedRequestUri, cachedResponse.StatusCode);
+					return CreateWebResourceResponse(cachedResponse);
+				}
+
+				if (cacheRequestBehavior == StaticContentCacheRequestBehavior.Refresh)
+				{
+					_staticContentResponseCache.Remove(requestUri);
+				}
+			}
+
 			var allowFallbackOnHostPage = AppOriginUri.IsBaseOfPage(requestUri);
+			var originalRequestUri = requestUri;
 			requestUri = QueryStringHelper.RemovePossibleQueryString(requestUri);
 
 			logger?.HandlingWebRequest(requestUri);
@@ -127,8 +156,43 @@ private bool ShouldOverrideUrlLoadingCore(IWebResourceRequest? request)
 			{
 				var contentType = headers["Content-Type"];
 
+				// By default local caching is disabled so that user scripts are always re-executed. Applications can
+				// opt specific resources into caching via BlazorWebView.StaticContentCacheControlProvider.
+				// The original (unstripped) URI is passed so the provider can act on query strings (e.g. img.png?v=2).
+				// See https://github.com/dotnet/maui/issues/8279
+				var cacheControlOverride = StaticContentCacheControl.ResolveOverride(_webViewHandler?.VirtualView, originalRequestUri, contentType, logger);
+				if (cacheControlOverride is not null)
+				{
+					headers["Cache-Control"] = cacheControlOverride;
+				}
+
 				logger?.ResponseContentBeingSent(requestUri, statusCode);
 
+				if (statusCode == 200 &&
+					headers.TryGetValue("Cache-Control", out var cacheControl) &&
+					StaticContentResponseCachePolicy.TryGetCacheLifetime(cacheControl, out var cacheLifetime))
+				{
+					cacheRequestBehavior ??= StaticContentResponseCachePolicy.GetRequestBehavior(request.Method, request.RequestHeaders);
+					if (cacheRequestBehavior != StaticContentCacheRequestBehavior.Disabled)
+					{
+						if (StaticContentResponseBuffer.TryBuffer(content, originalRequestUri, logger, out var cachedContent, out var responseContent))
+						{
+							var responseToCache = new StaticContentResponse(
+								originalRequestUri,
+								contentType,
+								statusCode,
+								statusMessage,
+								headers,
+								cachedContent,
+								StaticContentResponseCachePolicy.GetExpiration(cacheLifetime));
+
+							_staticContentResponseCache.Set(responseToCache);
+						}
+
+						return new WebResourceResponse(contentType, "UTF-8", statusCode, statusMessage, headers, responseContent);
+					}
+				}
+
 				return new WebResourceResponse(contentType, "UTF-8", statusCode, statusMessage, headers, content);
 			}
 			else
@@ -139,6 +203,15 @@ private bool ShouldOverrideUrlLoadingCore(IWebResourceRequest? request)
 			return null;
 		}
 
+		private static WebResourceResponse CreateWebResourceResponse(StaticContentResponse response)
+			=> new(
+				response.ContentType,
+				"UTF-8",
+				response.StatusCode,
+				response.StatusMessage,
+				new Dictionary<string, string>(response.Headers, StringComparer.OrdinalIgnoreCase),
+				new MemoryStream(response.Content, writable: false));
+
 		public override void OnPageFinished(AWebView? view, string? url)
 		{
 			base.OnPageFinished(view, url);
@@ -234,11 +307,12 @@ private void RunBlazorStartupScripts(AWebView view)
 
 		protected override void Dispose(bool disposing)
 		{
-			base.Dispose(disposing);
 			if (disposing)
 			{
-				//_webViewManager = null;
+				_staticContentResponseCache.Clear();
 			}
+
+			base.Dispose(disposing);
 		}
 
 		private class JavaScriptValueCallback : Java.Lang.Object, IValueCallback

src/BlazorWebView/src/Maui/BlazorWebView.cs

@@ -1,6 +1,6 @@
 using System;
-using System.Threading.Tasks;
 using System.Runtime.Versioning;
+using System.Threading.Tasks;
 using Microsoft.AspNetCore.Components.Web;
 using Microsoft.Extensions.FileProviders;
 using Microsoft.Maui;
@@ -67,6 +67,24 @@ public string StartPath
 		/// <inheritdoc cref="IBlazorWebView.RootComponents" />
 		public RootComponentsCollection RootComponents { get; }
 
+		/// <summary>
+		/// Gets or sets a callback that determines the <c>Cache-Control</c> header value used for static content
+		/// (such as images, fonts, or stylesheets) served from the app's content root.
+		/// <para>
+		/// By default no callback is set and all served content uses <c>no-cache, max-age=0, must-revalidate,
+		/// no-store</c>, which disables WebView caching. Provide a callback to opt specific resources into caching,
+		/// which can avoid repeated file reads and reduce image reload flicker when navigating between pages.
+		/// Return <see langword="null"/> or an empty string from the callback to keep the default behavior for a
+		/// given request. Cache entries remain subject to platform limits, expiration, and eviction.
+		/// </para>
+		/// <para>
+		/// The callback is invoked from the platform's request handling, which may run on a background thread, so it
+		/// must not access UI state directly. If the callback throws, the exception is logged and the request falls
+		/// back to the default header.
+		/// </para>
+		/// </summary>
+		public Func<BlazorWebViewStaticContentRequest, string?>? StaticContentCacheControlProvider { get; set; }
+
 		/// <summary>
 		/// Allows customizing how links are opened.
 		/// By default, opens internal links in the webview and external links in an external app.

src/BlazorWebView/src/Maui/BlazorWebViewStaticContentRequest.cs

@@ -0,0 +1,36 @@
+using System;
+
+namespace Microsoft.AspNetCore.Components.WebView.Maui
+{
+	/// <summary>
+	/// Describes a request for static content served by a <see cref="BlazorWebView"/>. An instance is passed to the
+	/// callback set on <see cref="BlazorWebView.StaticContentCacheControlProvider"/> so the application can decide
+	/// which <c>Cache-Control</c> header value to send for the resource.
+	/// </summary>
+	public sealed class BlazorWebViewStaticContentRequest
+	{
+		/// <summary>
+		/// Initializes a new instance of the <see cref="BlazorWebViewStaticContentRequest"/> class.
+		/// </summary>
+		/// <param name="uri">The absolute URI of the requested static content.</param>
+		/// <param name="contentType">The resolved MIME content type of the requested static content.</param>
+		public BlazorWebViewStaticContentRequest(Uri uri, string contentType)
+		{
+			ArgumentNullException.ThrowIfNull(uri);
+			ArgumentNullException.ThrowIfNull(contentType);
+
+			Uri = uri;
+			ContentType = contentType;
+		}
+
+		/// <summary>
+		/// Gets the absolute URI of the requested static content.
+		/// </summary>
+		public Uri Uri { get; }
+
+		/// <summary>
+		/// Gets the resolved MIME content type of the requested static content, for example <c>image/png</c>.
+		/// </summary>
+		public string ContentType { get; }
+	}
+}

src/BlazorWebView/src/Maui/IBlazorWebView.cs

@@ -29,6 +29,16 @@ public string StartPath
 		/// </summary>
 		RootComponentsCollection RootComponents { get; }
 
+		/// <summary>
+		/// Gets a callback that returns the <c>Cache-Control</c> header value to use for a static content request
+		/// served by the <see cref="BlazorWebView"/>, or <see langword="null"/> to use the default (which disables
+		/// caching). Returning <see langword="null"/> or an empty string from the callback for a given request also
+		/// falls back to the default for that request. The callback may be invoked on a background thread, so it
+		/// must not access UI state directly. If the callback throws, the exception is logged and the request falls
+		/// back to the default header. Cache entries remain subject to platform limits, expiration, and eviction.
+		/// </summary>
+		Func<BlazorWebViewStaticContentRequest, string?>? StaticContentCacheControlProvider => null;
+
 		/// <summary>
 		/// Gets the <see cref="JSComponentConfigurationStore"/>.
 		/// </summary>

src/BlazorWebView/src/Maui/PublicAPI/net-android/PublicAPI.Unshipped.txt

@@ -1,2 +1,9 @@
 #nullable enable
 override Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewHandler.ConnectHandler(Android.Webkit.WebView! platformView) -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.set -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.BlazorWebViewStaticContentRequest(System.Uri! uri, string! contentType) -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.ContentType.get -> string!
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.Uri.get -> System.Uri!
+Microsoft.AspNetCore.Components.WebView.Maui.IBlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?

src/BlazorWebView/src/Maui/PublicAPI/net-ios/PublicAPI.Unshipped.txt

@@ -1 +1,8 @@
 #nullable enable
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.set -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.BlazorWebViewStaticContentRequest(System.Uri! uri, string! contentType) -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.ContentType.get -> string!
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.Uri.get -> System.Uri!
+Microsoft.AspNetCore.Components.WebView.Maui.IBlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?

src/BlazorWebView/src/Maui/PublicAPI/net-maccatalyst/PublicAPI.Unshipped.txt

@@ -1 +1,8 @@
 #nullable enable
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.set -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.BlazorWebViewStaticContentRequest(System.Uri! uri, string! contentType) -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.ContentType.get -> string!
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.Uri.get -> System.Uri!
+Microsoft.AspNetCore.Components.WebView.Maui.IBlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?

src/BlazorWebView/src/Maui/PublicAPI/net-tizen/PublicAPI.Unshipped.txt

@@ -1 +1,8 @@
 #nullable enable
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.set -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.BlazorWebViewStaticContentRequest(System.Uri! uri, string! contentType) -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.ContentType.get -> string!
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.Uri.get -> System.Uri!
+Microsoft.AspNetCore.Components.WebView.Maui.IBlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?

src/BlazorWebView/src/Maui/PublicAPI/net-windows/PublicAPI.Unshipped.txt

@@ -1 +1,8 @@
 #nullable enable
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.set -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.BlazorWebViewStaticContentRequest(System.Uri! uri, string! contentType) -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.ContentType.get -> string!
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.Uri.get -> System.Uri!
+Microsoft.AspNetCore.Components.WebView.Maui.IBlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?

src/BlazorWebView/src/Maui/PublicAPI/net/PublicAPI.Unshipped.txt

@@ -1 +1,8 @@
 #nullable enable
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView.StaticContentCacheControlProvider.set -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.BlazorWebViewStaticContentRequest(System.Uri! uri, string! contentType) -> void
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.ContentType.get -> string!
+Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest.Uri.get -> System.Uri!
+Microsoft.AspNetCore.Components.WebView.Maui.IBlazorWebView.StaticContentCacheControlProvider.get -> System.Func<Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebViewStaticContentRequest!, string?>?

src/BlazorWebView/src/Maui/StaticContentCacheControl.cs

@@ -0,0 +1,61 @@
+using System;
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.AspNetCore.Components.WebView.Maui
+{
+	internal static class StaticContentCacheControl
+	{
+		// Historical default that disables all WebView caching of served content so that user scripts are always
+		// re-executed. It is applied unless the application opts a resource into caching via
+		// BlazorWebView.StaticContentCacheControlProvider. See https://github.com/dotnet/maui/issues/8279
+		internal const string Default = "no-cache, max-age=0, must-revalidate, no-store";
+
+		// Returns the application-provided Cache-Control override for the request, or null to use the default.
+		internal static string? ResolveOverride(IBlazorWebView? blazorWebView, string requestUri, string contentType, ILogger? logger)
+		{
+			var provider = blazorWebView?.StaticContentCacheControlProvider;
+			if (provider is null)
+			{
+				return null;
+			}
+
+			// The request handlers run on background threads, so guard against a malformed URI rather than letting
+			// an unexpected UriFormatException surface as a crash. If parsing fails we keep the default header.
+			if (!Uri.TryCreate(requestUri, UriKind.Absolute, out var uri))
+			{
+				return null;
+			}
+
+			string? cacheControl;
+			try
+			{
+				cacheControl = provider(new BlazorWebViewStaticContentRequest(uri, contentType));
+			}
+			catch (Exception ex)
+			{
+				// The provider is arbitrary application code invoked from the native request-handling path. On Windows
+				// it runs inside an async void handler, where an escaped exception would also skip deferral.Complete()
+				// and hang the request. A faulty provider must not take down static asset serving, so keep the default.
+				logger?.StaticContentCacheControlProviderFailed(requestUri, ex);
+				return null;
+			}
+
+			// An empty or whitespace-only string is deliberately treated like null (keep the default): such a
+			// Cache-Control value is non-standard and engine-dependent, and is more likely an accidental result of
+			// string manipulation than an intentional opt-in. Explicit directives are the supported way to enable caching.
+			if (string.IsNullOrWhiteSpace(cacheControl))
+			{
+				return null;
+			}
+
+			// Values containing CR/LF are also rejected: some platforms concatenate the value into a raw response
+			// header block, so a stray newline would produce a malformed response or allow header injection.
+			if (cacheControl.Contains('\r', StringComparison.Ordinal) || cacheControl.Contains('\n', StringComparison.Ordinal))
+			{
+				return null;
+			}
+
+			return cacheControl;
+		}
+	}
+}