Skip to content

Make StaticHost responses edge-cacheable and configurable - #2220

Closed
David Pine (IEvangelist) wants to merge 10 commits into
mainfrom
dapine/edge-cacheable-origin-headers
Closed

David Pine (IEvangelist) wants to merge 10 commits into
mainfrom
dapine/edge-cacheable-origin-headers

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Summary

Stacked on #2178 (base: sebros/optimistic-babbage-j11aeu); review that first. Pairs with an ADO PR to the deploy branch that turns on Azure Front Door caching for fingerprinted content only: /_astro/* and ?v= URLs. Nothing else is cached at the edge, so deploys need no purge.

Why: on a test Front Door Premium in front of this stack, enabling caching cut the brotli TTFB from about 400 ms to 129 ms, gave gzip-only clients edge-gzipped bodies (today they get uncompressed ones, e.g. 14 MB instead of 841 KB), and answered If-None-Match from the edge. A Rules Engine OverrideAlways did not cache HTML sent as Cache-Control: no-cache (still CONFIG_NOCACHE after 17 min). So HTML edge caching needs the origin to change Cache-Control.

Changes

  1. Configurable caching (SiteFileCacheOptions, section SiteFiles:CacheControl). These replace the constants in SiteFileMiddleware. They're validated on start and can be changed with App Service settings plus a restart, e.g. SiteFiles__CacheControl__Default.

    Key Default
    Default (HTML, .md, .txt, .xml, JSON, …) no-cache (unchanged)
    Media (image/video/font) max-age=3600, must-revalidate (unchanged)
    Immutable max-age=31536000, public, immutable (unchanged)
    ImmutablePathPrefixes /_astro. Semicolon-separated, because binding a list appends to its default instead of replacing it.
    VersionQueryParameter v. Empty turns it off.

    Default stays no-cache because these files keep their URL when their content changes. Front Door never caches a no-cache response, even on a route or rule that enables caching.

  2. ?v= versioned URLs get the immutable value. The frontend adds ?v=<hash> in Load API reference sidebar trees once per package or module #2213 and Serve English in place of untranslated locale routes #2214; Front Door will cache those routes by query string.

  3. no-store on every redirect. A new NoStoreRedirectMiddleware runs first in the pipeline and sets it on all 301/302/303/307/308 responses: HTTPS upgrade, canonical-path redirects, and /install.ps1 / /install.sh. It also overrides a redirect that sets its own caching. 304 is unaffected. StaticHost has no trailing-slash redirect today (UseDefaultFiles rewrites and doesn't redirect). /healthz, /api/live/* and the 404 page already send no-store; they're unchanged.

  4. Range requests never get the brotli copy. Any Range request is served from the uncompressed file, with Vary: Accept-Encoding still sent. Front Door answers 503 when range lengths for one URL differ across encodings, and a seek into brotli bytes is useless. This also removes the If-Range date special case.

  5. Build-time brotli at quality 11. compress-site.cs now uses CompressionLevel.SmallestSize on ProcessorCount threads and logs elapsed time. Serve the site with a per-request file middleware instead of MapStaticAssets #2178's reuse of unchanged copies is kept. The output directory is renamed site-br-q11/ so quality-4 copies in obj are not reused.

    • Size, measured on 400 real pages: HTML goes from 18.5% to 16.4% of raw; _astro JS+CSS from 24.9% to 22.8%.
    • Cost: about 87 ms per page vs 4 ms, roughly 42 CPU-minutes for about 29k pages. That's about 10–11 minutes wall-clock on a 4-vCPU runner for a cold publish; incremental publishes only recompress changed files.

Edge caching scope: HTML isn't cached at the edge, so Markdown negotiation (Accept: text/markdown) can't share a cache entry with HTML.

Third-party links and affiliations

None

Validation

  • After the no-cache default change: dotnet test tests\StaticHost.Tests --filter "FullyQualifiedName!~StaticHost.Tests.Live" — passed (172 passed, 0 failed).
  • dotnet test tests\StaticHost.Tests — passed (432 passed, 0 failed). New and updated tests cover:
    • Cache-Control per file type: HTML, .md, .txt, .xml, JSON, media, /_astro, and a /_astroid non-match.
    • ?v= giving immutable; empty v and other parameters do not.
    • Options binding, including prefixes replacing the default, and a renamed version parameter.
    • Invalid configuration failing at startup.
    • no-store on canonical, endpoint (install-style 302, 301, a self-cached 308) and HTTPS redirects; 304 keeping its caching.
    • Range requests with Accept-Encoding: br never getting brotli (single, multi and unsatisfiable ranges, with and without If-Range).
  • dotnet run --file src\statichost\compress-site.cs on 40 sample pages, run twice — passed: the first run compressed 40 on 16 threads; the second reused all 40.
  • bun run build / full publish was not run locally (it's slow and resource-heavy); CI builds the site.

…cAssets

MapStaticAssets needs a manifest of every file of the web root. With the
site's ~70,500 files (8.4 GB), building it dominates every StaticHost
build and publish, and each instance loads it at startup into one route
per file.

StaticHost now turns static web assets off and serves the web root with
SiteFileMiddleware:

- It looks the file up per request, prefers the brotli copy next to it
  when the client accepts br, and answers single byte ranges.
- It computes the ETag (base64 SHA-256, the same value MapStaticAssets
  sent) the first time a file is served and caches it in memory.
- It keeps the existing caching: immutable for /_astro/, the SDK's
  one-hour default for images, video and fonts, no-cache otherwise.
- It steps aside when an endpoint matched, so API, health and download
  endpoints keep precedence.

Site.targets publishes the frontend's output to wwwroot, as the static
web assets pipeline did: it asks frontend.esproj for JavaScriptOutputGroup
(which runs its BuildCommand) and writes a brotli copy (Optimal, the level
used before) of each text file, reusing copies newer than their source.
It replaces Caching.targets.

The Frontend Build job no longer copies dist into wwwroot and rebuilds
StaticHost to regenerate the manifest.

Measured on a 4-core VM against the real production build of the site,
current setup vs this change:

- dotnet publish (Astro build excluded): 213 s -> 55 s (22 s when the
  brotli copies are reused)
- CI-style build with dist in wwwroot: 86 s -> 9 s
- Endpoints manifest: 142 MB -> none
- First response after start: 13-18 s -> 2.3-5.8 s (the rest is
  startup both share)
- Memory after warm load: 2.1-2.2 GB -> 280 MB RSS
- Each of the 33k pages once: 1,450 -> 3,900 req/s, p99 56 -> 9 ms
- Warm load: 5,700-5,850 -> 10,100-10,800 req/s, p99 21 -> 9 ms

Comparing both servers on every page and file, with and without br
(207,786 responses), Content-Type, Cache-Control, ETag, Vary and
Content-Length match. The differences: Last-Modified on brotli responses
is now the file's own, 4 tiny files no longer get a brotli copy that is
not smaller, and StaticHost's own wwwroot (.gitignore, the dev-only
Scalar theme) is no longer published.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01871HTuV3jb825jyAUQ3L7d
- Write the brotli copies with src/statichost/compress-site.cs, a file-based
  app that Site.targets runs, instead of an inline MSBuild task that loaded
  BrotliStream by reflection (which fails under .NET Framework MSBuild).
- Reuse a brotli copy only while it carries its source's exact timestamp. A
  source replaced by new content with an older timestamp (a cache restore or
  an archive extraction) kept the copy of the old content.
- Answer If-Match and If-Unmodified-Since with 412, as MapStaticAssets did.
- Apply a date in If-Range only to uncompressed responses: Last-Modified is
  the original file's, so it does not identify the bytes of its brotli copy.
- Key cached ETags by the file's path in the web root, not its physical path
  or bare name, and parse the ETag once per request.
- Compute ETags with XxHash128 instead of SHA-256: an ETag only has to tell
  versions of a file apart, which needs no cryptographic hash. It still
  hashes the content, so unchanged files keep their ETag across deployments.
- Say why the brotli copy is looked up even for clients that do not accept
  brotli (the Vary header both versions need), and why cached ETags are
  keyed by ordinal path.
Request paths that differ only by empty or dot segments (/a/b.json,
/a//b.json, /a/./b.json) name one file, and the file provider resolves them
to the same physical path. Keyed by request path, each spelling added an
entry and hashed the file again, so a client could grow the cache without
bound and force a full read of any file on every request. Keyed by physical
path, the cache holds at most one entry per file of the web root.

Concurrent first requests for a file may still both hash it; that happens
once per file per instance, and serving the file reads it anyway.
The static asset endpoints allowed only GET and HEAD, so routing matched a
file's path and answered 405 for other methods. The middleware stepped aside
for them instead, and a POST to a file fell through to the 404 page. It now
answers 405 with Allow: GET, HEAD; a path with no file still gets 404.
- Bind Cache-Control values from SiteFiles:CacheControl (Default, Media, Immutable,
  ImmutablePathPrefixes, VersionQueryParameter) with validation on start.
- Default for non-fingerprinted files becomes public, max-age=0, must-revalidate,
  s-maxage=3600 so Front Door can cache HTML while browsers revalidate.
- Serve ?v= versioned URLs with the immutable Cache-Control.
- Send Cache-Control: no-store with every redirect (HTTPS, canonical path, install scripts).
- Never serve the brotli copy to a Range request.
- Write build-time brotli copies at quality 11 on every core.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…s them

Front Door caches only fingerprinted content (/_astro and ?v= URLs) and
deployments no longer purge the edge, so a file whose URL doesn't change
with its content must not be cached there.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Ignore Range on HEAD (RFC 9110, 14.2): HEAD gets the whole file's headers.
- Choose brotli or identity by Accept-Encoding quality values; identity when
  neither is acceptable.
- Hash the file again for requests with If-Match, If-None-Match or If-Range,
  so a file replaced with the same length and time cannot get a stale 304.
- Reuse a brotli copy only when its source's SHA-256 matches, not its time.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…' into dapine/edge-cacheable-origin-headers

# Conflicts:
#	src/statichost/StaticHost/SiteFiles/SiteFileMiddleware.cs
Base automatically changed from sebros/optimistic-babbage-j11aeu to main November 20, 2026 18:39
@IEvangelist

Copy link
Copy Markdown
Member Author

Closing in favor of #2227. Front Door now caches only fingerprinted content (/_astro/* and ?v= URLs) with no purge on deploy, so HTML stays no-cache and the configurable cache options, no-store redirects and Range changes aren't needed. The one piece still needed, ?v= JSON served as immutable, is in #2227.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants