Prevent dotnet-watch script injection staleness (#27778)

The browser refresh mechansim used by dotnet-watch and VS modifies HTML content. The modified content includes
a script block that has a WebSocket url that changes for each new execution of dotnet watch run (not rebuilds, but watch itself).
HTML content can come from views or static html files on disk. For the latter, ASP.NET Core participates in browser caching by sending (and invalidating) etag headers.

One way to fix this problem is remove or modify the etag headers. The risk here is that might cause differences in behavior in development users may come to rely on that are unavailable in production. This change instead modifies the HTML content so the output is always consistent and consequently safe to cache. The dynamic content is served separately by the injected middleware.

This change fixes the issue of multiple instances of dotnet-watch. While this issue may crop up if you alternate between dotnet run and dotnet watch run but we haven't seen this being an issue as yet.

Fixes #27548

Summary
Running dotnet watch run multiple times in Blazor WASM apps (or any app that serves static html files) can produce console errors and prevent the browser refresh feature from working. Given that we've been telling our users to use dotnet watch run as their primary way to work outside of VS, it's likely more users would run in this.

Customer impact
A hard browser refresh (Ctrl + R) is needed to get the refresh behavior to work.

Regression
No. This has existed since the feature was introduced we did not get reports of it

Risk
Low. The fix is isolated to dotnet-watch and VS's browser refresh mechanism which is in preview. The change was tested locally, but if there's a regression or if the change interferes with user's workflow, users have the ability to disable this feature.

Author: pranavkm

src/Tools/dotnet-watch/BrowserRefresh/src/BrowserScriptMiddleware.cs

@@ -0,0 +1,51 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System;
+using System.Globalization;
+using System.IO;
+using System.Text;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Http;
+
+namespace Microsoft.AspNetCore.Watch.BrowserRefresh
+{
+    /// <summary>
+    /// Responds with the contennts of WebSocketScriptInjection.js with the stub WebSocket url replaced by the
+    /// one specified by the launching app.
+    /// </summary>
+    public sealed class BrowserScriptMiddleware
+    {
+        private readonly byte[] _scriptBytes;
+        private readonly string _contentLength;
+
+        public BrowserScriptMiddleware(RequestDelegate next)
+            : this(Environment.GetEnvironmentVariable("ASPNETCORE_AUTO_RELOAD_WS_ENDPOINT")!)
+        {
+        }
+
+        internal BrowserScriptMiddleware(string webSocketUrl)
+        {
+            _scriptBytes = GetWebSocketClientJavaScript(webSocketUrl);
+            _contentLength = _scriptBytes.Length.ToString(CultureInfo.InvariantCulture);
+        }
+
+        public async Task InvokeAsync(HttpContext context)
+        {
+            context.Response.Headers["Cache-Control"] = "no-store";
+            context.Response.Headers["Content-Length"] = _contentLength;
+            context.Response.Headers["Content-Type"] = "application/javascript; charset=utf-8";
+
+            await context.Response.Body.WriteAsync(_scriptBytes.AsMemory(), context.RequestAborted);
+        }
+
+        internal static byte[] GetWebSocketClientJavaScript(string hostString)
+        {
+            var jsFileName = "Microsoft.AspNetCore.Watch.BrowserRefresh.WebSocketScriptInjection.js";
+            using var reader = new StreamReader(typeof(WebSocketScriptInjection).Assembly.GetManifestResourceStream(jsFileName)!);
+            var script = reader.ReadToEnd().Replace("{{hostString}}", hostString);
+
+            return Encoding.UTF8.GetBytes(script);
+        }
+    }
+}

src/Tools/dotnet-watch/BrowserRefresh/src/HostingFilter.cs

@@ -2,6 +2,7 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
+using System.Globalization;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.DependencyInjection;
@@ -22,6 +23,7 @@ public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
         {
             return app =>
             {
+                app.Map(WebSocketScriptInjection.WebSocketScriptUrl, app1 => app1.UseMiddleware<BrowserScriptMiddleware>());
                 app.UseMiddleware<BrowserRefreshMiddleware>();
                 next(app);
             };

src/Tools/dotnet-watch/BrowserRefresh/src/ResponseStreamWrapper.cs

@@ -58,7 +58,7 @@ public override void Write(ReadOnlySpan<byte> buffer)
             OnWrite();
             if (IsHtmlResponse && !ScriptInjectionPerformed)
             {
-                ScriptInjectionPerformed = WebSocketScriptInjection.Instance.TryInjectLiveReloadScript(_baseStream, buffer);
+                ScriptInjectionPerformed = WebSocketScriptInjection.TryInjectLiveReloadScript(_baseStream, buffer);
             }
             else
             {
@@ -78,7 +78,7 @@ public override void Write(byte[] buffer, int offset, int count)
 
             if (IsHtmlResponse && !ScriptInjectionPerformed)
             {
-                ScriptInjectionPerformed = WebSocketScriptInjection.Instance.TryInjectLiveReloadScript(_baseStream, buffer.AsSpan(offset, count));
+                ScriptInjectionPerformed = WebSocketScriptInjection.TryInjectLiveReloadScript(_baseStream, buffer.AsSpan(offset, count));
             }
             else
             {
@@ -92,7 +92,7 @@ public override async Task WriteAsync(byte[] buffer, int offset, int count, Canc
 
             if (IsHtmlResponse && !ScriptInjectionPerformed)
             {
-                ScriptInjectionPerformed = await WebSocketScriptInjection.Instance.TryInjectLiveReloadScriptAsync(_baseStream, buffer.AsMemory(offset, count), cancellationToken);
+                ScriptInjectionPerformed = await WebSocketScriptInjection.TryInjectLiveReloadScriptAsync(_baseStream, buffer.AsMemory(offset, count), cancellationToken);
             }
             else
             {
@@ -106,7 +106,7 @@ public override async ValueTask WriteAsync(ReadOnlyMemory<byte> buffer, Cancella
 
             if (IsHtmlResponse && !ScriptInjectionPerformed)
             {
-                ScriptInjectionPerformed = await WebSocketScriptInjection.Instance.TryInjectLiveReloadScriptAsync(_baseStream, buffer, cancellationToken);
+                ScriptInjectionPerformed = await WebSocketScriptInjection.TryInjectLiveReloadScriptAsync(_baseStream, buffer, cancellationToken);
             }
             else
             {

src/Tools/dotnet-watch/BrowserRefresh/src/WebSocketScriptInjection.cs

@@ -13,22 +13,18 @@ namespace Microsoft.AspNetCore.Watch.BrowserRefresh
     /// Helper class that handles the HTML injection into
     /// a string or byte array.
     /// </summary>
-    public class WebSocketScriptInjection
+    public static class WebSocketScriptInjection
     {
         private const string BodyMarker = "</body>";
+        internal const string WebSocketScriptUrl = "/_framework/aspnetcore-browser-refresh.js";
 
-        private readonly byte[] _bodyBytes = Encoding.UTF8.GetBytes(BodyMarker);
-        private readonly byte[] _scriptInjectionBytes;
+        private static readonly byte[] _bodyBytes = Encoding.UTF8.GetBytes(BodyMarker);
 
-        public static WebSocketScriptInjection Instance { get; } = new WebSocketScriptInjection(
-            GetWebSocketClientJavaScript(Environment.GetEnvironmentVariable("ASPNETCORE_AUTO_RELOAD_WS_ENDPOINT")));
+        internal static string InjectedScript { get; } = $"<script src=\"{WebSocketScriptUrl}\"></script>";
 
-        public WebSocketScriptInjection(string clientScript)
-        {
-            _scriptInjectionBytes = Encoding.UTF8.GetBytes(clientScript);
-        }
+        private static readonly byte[] _injectedScriptBytes = Encoding.UTF8.GetBytes(InjectedScript);
 
-        public bool TryInjectLiveReloadScript(Stream baseStream, ReadOnlySpan<byte> buffer)
+        public static bool TryInjectLiveReloadScript(Stream baseStream, ReadOnlySpan<byte> buffer)
         {
             var index = buffer.LastIndexOf(_bodyBytes);
             if (index == -1)
@@ -44,14 +40,14 @@ public bool TryInjectLiveReloadScript(Stream baseStream, ReadOnlySpan<byte> buff
             }
 
             // Write the injected script
-            baseStream.Write(_scriptInjectionBytes);
+            baseStream.Write(_injectedScriptBytes);
 
             // Write the rest of the buffer/HTML doc
             baseStream.Write(buffer);
             return true;
         }
 
-        public async ValueTask<bool> TryInjectLiveReloadScriptAsync(Stream baseStream, ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken = default) 
+        public static async ValueTask<bool> TryInjectLiveReloadScriptAsync(Stream baseStream, ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken = default)
         {
             var index = buffer.Span.LastIndexOf(_bodyBytes);
             if (index == -1)
@@ -67,20 +63,12 @@ public async ValueTask<bool> TryInjectLiveReloadScriptAsync(Stream baseStream, R
             }
 
             // Write the injected script
-            await baseStream.WriteAsync(_scriptInjectionBytes, cancellationToken);
+            await baseStream.WriteAsync(_injectedScriptBytes, cancellationToken);
 
             // Write the rest of the buffer/HTML doc
             await baseStream.WriteAsync(buffer, cancellationToken);
             return true;
         }
 
-        internal static string GetWebSocketClientJavaScript(string? hostString)
-        {
-            var jsFileName = "Microsoft.AspNetCore.Watch.BrowserRefresh.WebSocketScriptInjection.js";
-            using var reader = new StreamReader(typeof(WebSocketScriptInjection).Assembly.GetManifestResourceStream(jsFileName)!);
-            var script = reader.ReadToEnd().Replace("{{hostString}}", hostString);
-
-            return $"<script>{script}</script>";
-        }
     }
 }

src/Tools/dotnet-watch/BrowserRefresh/test/BrowserScriptMiddlewareTest.cs

@@ -0,0 +1,66 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Http;
+using Xunit;
+
+namespace Microsoft.AspNetCore.Watch.BrowserRefresh
+{
+    public class BrowserScriptMiddlewareTest
+    {
+        [Fact]
+        public async Task InvokeAsync_ReturnsScript()
+        {
+            // Arrange
+            var context = new DefaultHttpContext();
+            var stream = new MemoryStream();
+            context.Response.Body = stream;
+            var middleware = new BrowserScriptMiddleware("some-host");
+
+            // Act
+            await middleware.InvokeAsync(context);
+
+            // Assert
+            stream.Position = 0;
+            var script = Encoding.UTF8.GetString(stream.ToArray());
+            Assert.Contains("// dotnet-watch browser reload script", script);
+            Assert.Contains("'some-host'", script);
+        }
+
+        [Fact]
+        public async Task InvokeAsync_ConfiguresHeaders()
+        {
+            // Arrange
+            var context = new DefaultHttpContext();
+            context.Response.Body = new MemoryStream();
+            var middleware = new BrowserScriptMiddleware("some-host");
+
+            // Act
+            await middleware.InvokeAsync(context);
+
+            // Assert
+            var response = context.Response;
+            Assert.Collection(
+                response.Headers.OrderBy(h => h.Key),
+                kvp =>
+                {
+                    Assert.Equal("Cache-Control", kvp.Key);
+                    Assert.Equal("no-store", kvp.Value);
+                },
+                kvp =>
+                {
+                    Assert.Equal("Content-Length", kvp.Key);
+                    Assert.NotEmpty(kvp.Value);
+                },
+                kvp =>
+                {
+                    Assert.Equal("Content-Type", kvp.Key);
+                    Assert.Equal("application/javascript; charset=utf-8", kvp.Value);
+                });
+        }
+    }
+}

src/Tools/dotnet-watch/BrowserRefresh/test/Microsoft.AspNetCore.Watch.BrowserRefresh.Tests.csproj

@@ -18,6 +18,7 @@
       We'll simply test against it as source.
     -->
     <Compile Include="..\src\BrowserRefreshMiddleware.cs" LinkBase="src" />
+    <Compile Include="..\src\BrowserScriptMiddleware.cs" LinkBase="src" />
     <Compile Include="..\src\ResponseStreamWrapper.cs" LinkBase="src" />
     <Compile Include="..\src\WebSocketScriptInjection.cs" LinkBase="src" />
     <EmbeddedResource Include="..\src\WebSocketScriptInjection.js" />

src/Tools/dotnet-watch/BrowserRefresh/test/ResponseStreamWrapperTest.cs

@@ -34,7 +34,7 @@ public async Task HtmlIsInjectedForStaticFiles()
             response.EnsureSuccessStatusCode();
 
             var content = await response.Content.ReadAsStringAsync();
-            Assert.Contains("dotnet-watch browser reload script", content);
+            Assert.Contains(WebSocketScriptInjection.InjectedScript, content);
         }
 
         [Fact]
@@ -50,7 +50,7 @@ public async Task HtmlIsInjectedForLargeStaticFiles()
 
             Assert.False(response.Content.Headers.TryGetValues("Content-Length", out _), "We shouldn't send a Content-Length header.");
             var content = await response.Content.ReadAsStringAsync();
-            Assert.Contains("dotnet-watch browser reload script", content);
+            Assert.Contains(WebSocketScriptInjection.InjectedScript, content);
         }
 
         [Fact]
@@ -73,7 +73,7 @@ public async Task HtmlIsInjectedForDynamicallyGeneratedMarkup()
 
             Assert.False(response.Content.Headers.TryGetValues("Content-Length", out _), "We shouldn't send a Content-Length header.");
             var content = await response.Content.ReadAsStringAsync();
-            Assert.Contains("dotnet-watch browser reload script", content);
+            Assert.Contains(WebSocketScriptInjection.InjectedScript, content);
         }
 
         [Fact]
@@ -98,7 +98,7 @@ public async Task HtmlIsInjectedForWriteAsyncMarkupWithContentLength()
 
             Assert.False(response.Content.Headers.TryGetValues("Content-Length", out _), "We shouldn't send a Content-Length header.");
             var content = await response.Content.ReadAsStringAsync();
-            Assert.Contains("dotnet-watch browser reload script", content);
+            Assert.Contains(WebSocketScriptInjection.InjectedScript, content);
         }
 
         [Fact]
@@ -131,7 +131,7 @@ public async Task HtmlIsInjectedForWriteAsyncMarkupWithMultipleWrites()
 
             Assert.False(response.Content.Headers.TryGetValues("Content-Length", out _), "We shouldn't send a Content-Length header.");
             var content = await response.Content.ReadAsStringAsync();
-            Assert.Contains("dotnet-watch browser reload script", content);
+            Assert.Contains(WebSocketScriptInjection.InjectedScript, content);
         }
 
         [Fact]
@@ -164,7 +164,7 @@ public async Task HtmlIsInjectedForPostResponses()
 
             Assert.False(response.Content.Headers.TryGetValues("Content-Length", out _), "We shouldn't send a Content-Length header.");
             var content = await response.Content.ReadAsStringAsync();
-            Assert.Contains("dotnet-watch browser reload script", content);
+            Assert.Contains(WebSocketScriptInjection.InjectedScript, content);
         }
 
         [Fact]