Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 9 additions & 18 deletions .github/workflows/frontend-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,9 @@ jobs:
node-version: ${{ inputs.node_version }}

# The E2E shards serve the site with StaticHost, as production does,
# from the build output this job uploads (statichost-bin). Its restore
# and compile need no site, so they run alongside the Astro build.
# from the build output this job uploads (statichost-bin). StaticHost
# reads the site from its web root per request, so its build needs no
# site and runs alongside the Astro build.
- uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
with:
global-json-file: global.json
Expand Down Expand Up @@ -138,16 +139,6 @@ jobs:
bun run build:production
fi

# StaticHost serves its wwwroot, which holds a copy of dist (hard links)
# as in production. MapStaticAssets lists every file of the web root:
# this incremental build redoes only that, while the site archive is packed
# and uploaded.
- name: Start the StaticHost build
run: |
cp -alf dist/. ../statichost/StaticHost/wwwroot/
"$SETUP" wait statichost-compile
"$SETUP" start statichost-build dotnet build -c Release --no-restore ../statichost/StaticHost

- name: Save Astro build state
if: ${{ success() && (github.event_name == 'push' || steps.astro_cache.outputs.cache-matched-key == '') }}
uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
Expand Down Expand Up @@ -226,7 +217,7 @@ jobs:

- name: Wait for the StaticHost build
run: |
"$SETUP" wait statichost-build
"$SETUP" wait statichost-compile
"$SETUP" report

- name: Upload the StaticHost build
Expand Down Expand Up @@ -457,17 +448,17 @@ jobs:
"$SETUP" start playwright-deps bun run playwright install-deps chromium
"$SETUP" start playwright-browsers bun run playwright install chromium

# The Frontend Build job built StaticHost against this run's dist.
# StaticHost reads the web root's files per request, so it starts
# before the site is there, and boots during its download.
# The Frontend Build job built StaticHost. It reads the web root's files
# per request, so it starts before the site is there, and boots during
# its download.
- name: Download the StaticHost build
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: statichost-bin
path: src/statichost/StaticHost/bin/Release/net10.0

# Any answer, a 404 included, means StaticHost built its routing table,
# which the first request does.
# Any answer, a 404 included, means StaticHost is up and has built its
# routing table, which the first request does.
- name: Start StaticHost
run: |
mkdir -p ../statichost/StaticHost/wwwroot
Expand Down
6 changes: 3 additions & 3 deletions src/frontend/playwright.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,9 @@ export default defineConfig({
webServer: isCI
? {
// CI serves the built site with StaticHost, as production does (Markdown negotiation, canonical
// redirects, the 404 page, headers). The Frontend Build job builds it against the site's files
// (wwwroot holds a copy of dist), so the tests start its assembly directly: `dotnet run --no-build`
// still evaluates the project, which takes seconds. The E2E jobs start it before dist arrives
// redirects, the 404 page, headers) from its wwwroot, where the E2E jobs unpack dist. The Frontend
// Build job builds it, so the tests start its assembly directly: `dotnet run --no-build` still
// evaluates the project, which takes seconds. The E2E jobs start it before dist arrives
// (.github/scripts/start-web-server.mjs), hence reuseExistingServer.
command: `dotnet bin/Release/net10.0/StaticHost.dll --urls ${e2eBaseUrl}`,
cwd: fileURLToPath(new URL('../statichost/StaticHost/', import.meta.url)),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,8 @@ namespace StaticHost.AgentReadiness;
/// HTML page (via <c>starlight-page-actions</c>). E.g. <c>/get-started/quickstart/</c>
/// has companion <c>/get-started/quickstart.md</c>. This middleware short-circuits
/// the pipeline by streaming that file directly when markdown is preferred —
/// it does NOT rewrite <c>Request.Path</c> because rewriting after
/// <c>UseRouting()</c> would not re-trigger endpoint selection in
/// <c>MapStaticAssets()</c>.
/// it does NOT rewrite <c>Request.Path</c>, because the negotiated response needs
/// its own caching headers (below), which the site file middleware would replace.
/// </para>
/// <para>
/// Therefore the middleware MUST run before <c>UseDefaultFiles</c> and
Expand Down Expand Up @@ -44,7 +43,7 @@ public MarkdownNegotiationMiddleware(
{
_next = next;
_logger = logger;
// Use the same provider MapStaticAssets reads from so wwwroot is the source of truth.
// Use the same provider SiteFileMiddleware reads from so wwwroot is the source of truth.
_fileProvider = env.WebRootFileProvider;
}

Expand Down
37 changes: 0 additions & 37 deletions src/statichost/StaticHost/Caching.targets

This file was deleted.

1 change: 1 addition & 0 deletions src/statichost/StaticHost/GlobalUsings.cs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
global using StaticHost.AgentReadiness;
global using StaticHost.Live;
global using StaticHost.Routing;
global using StaticHost.SiteFiles;
global using StaticHost.Telemetry;

global using OpenTelemetry;
Expand Down
13 changes: 9 additions & 4 deletions src/statichost/StaticHost/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
options.BackgroundServiceExceptionBehavior = BackgroundServiceExceptionBehavior.Ignore);

builder.AddLiveStatus();
builder.Services.AddSiteFiles();

builder.Services.AddHsts(options =>
{
Expand All @@ -34,6 +35,9 @@
// Restore the Front Door client IP before telemetry or any middleware reads it.
app.UseForwardedClientIp();

// Before anything that redirects: Front Door must never cache a redirect.
app.UseNoStoreRedirects();

// Only enable HSTS in production
if (!app.Environment.IsDevelopment())
{
Expand All @@ -47,8 +51,7 @@

// Agent-readiness middlewares MUST run before UseDefaultFiles + UseRouting:
// * UseDefaultFiles rewrites /foo/ -> /foo/index.html, breaking .md-companion mapping.
// * MapStaticAssets registers endpoints during UseRouting, so a path rewrite
// after UseRouting wouldn't re-trigger endpoint selection.
// * A path rewrite after UseRouting wouldn't re-trigger endpoint selection.
// MarkdownNegotiationMiddleware short-circuits to serve the .md body directly;
// LinkHeaderMiddleware attaches a Link header on HTML 2xx responses via OnStarting.
app.UseAgentReadiness();
Expand Down Expand Up @@ -96,6 +99,10 @@
await next();
});

// The site's files. Requests that matched an endpoint below (health, downloads, live status)
// pass through to it; a file that does not exist falls through to the 404 page above.
app.UseSiteFiles();

app.MapGet("/healthz", (HttpContext context) =>
{
// A health probe must always reach the origin, never a cached copy.
Expand Down Expand Up @@ -143,6 +150,4 @@
return Results.Redirect("https://aka.ms/aspire/get/install.sh");
});

app.MapStaticAssets();

await app.RunAsync();
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,16 @@ public static IApplicationBuilder UseCanonicalPathRedirects(this IApplicationBui
app.UseMiddleware<CanonicalPathRedirectMiddleware>();
return app;
}

/// <summary>
/// Sends <c>Cache-Control: no-store</c> with every redirect, so no cache keeps one.
/// Call first, before any middleware or endpoint that can redirect.
/// </summary>
public static IApplicationBuilder UseNoStoreRedirects(this IApplicationBuilder app)
{
ArgumentNullException.ThrowIfNull(app);

app.UseMiddleware<NoStoreRedirectMiddleware>();
return app;
}
}
37 changes: 37 additions & 0 deletions src/statichost/StaticHost/Routing/NoStoreRedirectMiddleware.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
namespace StaticHost.Routing;

/// <summary>
/// Marks every redirect the host sends <c>Cache-Control: no-store</c>.
/// </summary>
/// <remarks>
/// A redirect without <c>Cache-Control</c> is heuristically cacheable, and a permanent one is
/// cacheable by default (RFC 9111, 4.2.2). Azure Front Door would keep such a redirect for days,
/// so a canonical path, an HTTPS upgrade or an install script target that changes would go on
/// redirecting from the edge. Run it first, so it sees the redirects of every later middleware
/// and endpoint. 304 Not Modified is not a redirect and keeps the file's caching.
/// </remarks>
internal sealed class NoStoreRedirectMiddleware(RequestDelegate next)
{
public Task InvokeAsync(HttpContext context)
{
context.Response.OnStarting(static state =>
{
var response = (HttpResponse)state;
if (IsRedirect(response.StatusCode))
{
response.Headers.CacheControl = "no-store";
}

return Task.CompletedTask;
}, context.Response);

return next(context);
}

internal static bool IsRedirect(int statusCode) => statusCode
is StatusCodes.Status301MovedPermanently
or StatusCodes.Status302Found
or StatusCodes.Status303SeeOther
or StatusCodes.Status307TemporaryRedirect
or StatusCodes.Status308PermanentRedirect;
}
57 changes: 57 additions & 0 deletions src/statichost/StaticHost/Site.targets
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
<Project>
<!--
Publishes the site (src/frontend/dist) to wwwroot with a brotli copy of each text file.

StaticHost serves the web root with SiteFileMiddleware, not MapStaticAssets, so the project
turns static web assets off (StaticWebAssetsEnabled). That pipeline hashed every file, wrote a
manifest of every URL, and made each instance load it at startup, which costs a lot with
about 70,000 files. What it did that the site needs is here: run the frontend build, copy its
output, and compress it once at publish. Caching and ETags are decided per request.

Asking frontend.esproj for JavaScriptOutputGroup runs its BuildCommand and returns dist's
files, as the static web assets pipeline did. The brotli copies are written by a file-based
app (../compress-site.cs), which reuses the copies of files that did not change.
-->
<PropertyGroup>
<!-- The text types the SDK compressed (Microsoft.NET.Sdk.StaticWebAssets.Compression.targets). -->
<SiteCompressedExtensions>.html;.htm;.md;.markdown;.txt;.xml;.json;.webmanifest;.js;.mjs;.jsx;.css;.map;.svg;.ico;.bmp;.otf;.wasm;.csv;.tsv;.ics;.xsl;.xslt</SiteCompressedExtensions>
<SiteCompressApp>$(MSBuildThisFileDirectory)../compress-site.cs</SiteCompressApp>
<!-- The dotnet that runs this build, so the app uses the same SDK; plain dotnet under msbuild.exe. -->
<SiteDotnet>$(DOTNET_HOST_PATH)</SiteDotnet>
<SiteDotnet Condition="'$(SiteDotnet)' == ''">dotnet</SiteDotnet>
</PropertyGroup>

<Target Name="AddSiteToPublish" AfterTargets="ComputeResolvedFilesToPublishList">
<PropertyGroup>
<!-- Set here: IntermediateOutputPath is not defined yet when this file's properties are. -->
<_SiteIntermediateDirectory>$(MSBuildProjectDirectory)/$(IntermediateOutputPath)</_SiteIntermediateDirectory>
<!-- Named after the brotli quality of compress-site.cs, so copies of another quality are not reused. -->
<_SiteCompressedDirectory>$(_SiteIntermediateDirectory)site-br-q11/</_SiteCompressedDirectory>
<_SiteFileList>$(_SiteIntermediateDirectory)site-files.txt</_SiteFileList>
<_SiteBrotliList>$(_SiteIntermediateDirectory)site-br.txt</_SiteBrotliList>
</PropertyGroup>

<MSBuild Projects="@(ProjectReference->WithMetadataValue('Filename', 'frontend'))" Targets="JavaScriptOutputGroup">
<Output TaskParameter="TargetOutputs" ItemName="_SiteFile" />
</MSBuild>

<!-- The app reads each file's full path and its path in the site, separated by a tab. -->
<WriteLinesToFile File="$(_SiteFileList)" Lines="@(_SiteFile->'%(FullPath)%09%(TemplateSubPath)%(Filename)%(Extension)')" Overwrite="true" WriteOnlyWhenDifferent="true" />
<Exec Command="&quot;$(SiteDotnet)&quot; run --file &quot;$(SiteCompressApp)&quot; -- &quot;$(_SiteFileList)&quot; &quot;$(_SiteCompressedDirectory)&quot; &quot;$(SiteCompressedExtensions)&quot; &quot;$(_SiteBrotliList)&quot;"
StandardOutputImportance="high" />
<ReadLinesFromFile File="$(_SiteBrotliList)">
<Output TaskParameter="Lines" ItemName="_SiteBrotliFile" />
</ReadLinesFromFile>

<ItemGroup>
<ResolvedFileToPublish Include="@(_SiteFile)"
RelativePath="wwwroot/%(_SiteFile.TemplateSubPath)%(_SiteFile.Filename)%(_SiteFile.Extension)"
CopyToPublishDirectory="PreserveNewest"
ExcludeFromSingleFile="true" />
<ResolvedFileToPublish Include="@(_SiteBrotliFile->'$(_SiteCompressedDirectory)%(Identity)')"
RelativePath="wwwroot/%(_SiteBrotliFile.Identity)"
CopyToPublishDirectory="PreserveNewest"
ExcludeFromSingleFile="true" />
</ItemGroup>
</Target>
</Project>
59 changes: 59 additions & 0 deletions src/statichost/StaticHost/SiteFiles/SiteFileCacheOptions.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
namespace StaticHost.SiteFiles;

/// <summary>
/// The <c>Cache-Control</c> values <see cref="SiteFileMiddleware"/> sends, bound from the
/// <c>SiteFiles:CacheControl</c> configuration section so they can be tuned with App Service
/// settings (for example <c>SiteFiles__CacheControl__Default</c>) and a restart, without a deploy.
/// </summary>
/// <remarks>
/// <para>
/// Azure Front Door caches only fingerprinted content, and deployments don't purge it. A file
/// that isn't fingerprinted keeps its URL when its content changes, so it defaults to
/// <c>no-cache</c>: browsers revalidate it on every use, and Front Door never caches a response
/// the origin marks <c>no-cache</c>, even on a route or rule that enables caching.
/// </para>
/// </remarks>
internal sealed class SiteFileCacheOptions
{
public const string SectionName = "SiteFiles:CacheControl";

// A file that isn't fingerprinted can change without a new URL, so nothing may reuse it unchecked.
internal const string DefaultValue = "no-cache";

// The SDK's default for images, video and fonts, as MapStaticAssets sent.
internal const string MediaValue = "max-age=3600, must-revalidate";

// https://starlight.astro.build/environmental-impact/#caching
internal const string ImmutableValue = "max-age=31536000, public, immutable";

/// <summary>The value for files that are neither media nor immutable: HTML, markdown, JSON, XML, text.</summary>
public string Default { get; set; } = DefaultValue;

/// <summary>The value for images, video and fonts outside the immutable paths.</summary>
public string Media { get; set; } = MediaValue;

/// <summary>The value for fingerprinted files, and for files requested with the version query parameter.</summary>
public string Immutable { get; set; } = ImmutableValue;

/// <summary>
/// Paths whose files are fingerprinted, so they can be cached forever, separated by semicolons.
/// Astro hashes the names of the files it emits under <c>/_astro/</c>. A string rather than a
/// list, because configuration adds to a list's default instead of replacing it.
/// </summary>
public string ImmutablePathPrefixes { get; set; } = "/_astro";

/// <summary>
/// The query parameter that marks a URL as versioned (<c>sidebar.json?v=&lt;hash&gt;</c>), so its
/// response can be cached forever: a new version gets a new URL. Empty turns it off.
/// </summary>
public string VersionQueryParameter { get; set; } = "v";

internal string[] GetImmutablePathPrefixes() =>
ImmutablePathPrefixes.Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);

internal static bool IsValid(SiteFileCacheOptions options) =>
!string.IsNullOrWhiteSpace(options.Default)
&& !string.IsNullOrWhiteSpace(options.Media)
&& !string.IsNullOrWhiteSpace(options.Immutable)
&& options.GetImmutablePathPrefixes().All(static prefix => prefix is ['/', _, ..] && !prefix.EndsWith('/'));
}
Loading