Files
SluijsensandClaude Sonnet 5.5 571aaf9cd2 ASF-injectie 5/5: end-to-end test op de master-host, ASF Website:AuthoredBaseUrl, rooktest-uitbreiding, docs
- ASF appsettings: Website:AuthoredBaseUrl=https://andreaslop.nl, PublicBaseUrl leeg (env).
- Api.Tests/AsfInjectionPipelineTests: pagina met markers, echte database; een CMS-wijziging is direct zichtbaar (ETag wijzigt), data-blok == publieke API, 304, sitemap-adres.
- smoke-site.sh: onverwerkte CMS-markers op / falen; data-blok moet siteUrl van deze host hebben.
- docs: asf-host-injection 'as built'.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-15 16:16:27 +01:00

7.4 KiB

Host injection into ASF's prerendered pages (asf-host-injection)

  • Slug: asf-host-injection
  • Type: Feature, proposal; not approved, build not started
  • Status: Built on feature/contact-forms-module (commits 7d66944, a136615, ef4fb9d, 4baadf3 and the one after it; tests green locally), not yet deployed: needs the website build with the markers and Website__PublicBaseUrl=https://test.andreaslop.nl in the ASF-test env file. Before: plan agreed with the ASF session (their counterpart: AndreaSlopFotografie-packages/aidlc-docs/features/asf-cms-host-injection/plan.md, section "Host contract"). Bryan accepted the approach (neutral list first, styled cards after hydration; the host writes the list HTML) on 2026-11-15 but said not to start building yet: he first reads the plan and finds out whether .NET 10 can run on the hosting package (hosting bundle or self-contained).
  • Affected components (planned): SlpModularCms.Core (Hosting/Website: generalise IndexHtmlInjector, hook in PrerenderedSiteMiddleware), SlpModularCms.Modules.Offerings (marker providers), scripts/smoke-site.sh, docs
  • Documented: 2026-11-15
  • Documentation Language: English
  • Conversation Language: Dutch (user language)

Why

Bryan's hosting package has one entry per website: the CMS host is that entry and serves the website, the prerendered pages and /admin. So ASF in production also runs entirely through Kestrel (IIS passes every request on, serves no static files and caches no HTML). Packages, banners and (later) gallery data can therefore be written into the prerendered HTML by the host: visible to crawlers within about a minute of a CMS change, without a nightly build. A rebuild webhook stays an option only for build-processed gallery images.

Host contract (agreed with ASF)

All markers are found in one pass; a page without markers and without the authored address is still served as a plain static file. Fail-open everywhere: missing marker = nothing; invalid data or a provider failure = the baked page is served.

Marker Host behaviour
<!--CMS:OFFERINGS-HTML-->…<!--/CMS:OFFERINGS-HTML--> Replace the content between the markers by a simple crawlable list from the live offerings (C# template following ASF's "Neutral HTML spec" and their golden files; everything HTML-encoded). The markers stay.
<!--CMS:BANNER-TOP-HTML-->…<!--/…-->, <!--CMS:BANNER-BOTTOM-HTML-->…<!--/…--> Same, from the live banner of that position as <aside><strong/><span/><a/>; empty (204) empties the region, so an ended banner disappears at once.
<!--CMS:DATA--> directly followed by the baked <script type="application/json" id="cms-data"> Replace the pair by the live block {"siteUrl":…,"offerings":[…],"banners":{"top":…|null,"bottom":…|null}}, the same shapes as the public GETs, < > & and U+2028/9 as \uXXXX. siteUrl = Website:PublicBaseUrl, otherwise Website:AuthoredBaseUrl, without a trailing slash.
<!--CMS:OFFER-JSON-LD slug="x"--> directly before <script type="application/ld+json"> Parse that block and set offers.price (whole euros) from the live offering; no live offering or no price derivable (free text) = remove offers. A provider failure leaves the baked block. Invalid JSON is left alone.
<span data-cms-price="slug">€ 185</span> Replace the text by € + U+00A0 + whole euros; unknown slug or no price = unchanged.

One artifact for test and production

Website:AuthoredBaseUrl (https://andreaslop.nl, the address ASF's build writes) is replaced by Website:PublicBaseUrl in html, sitemap.xml and robots.txt when the host has a PublicBaseUrl that differs (test: Website__PublicBaseUrl=https://test.andreaslop.nl in the host's env file). Where the host answers robots.txt itself (a NoIndex test host) that goes first.

Serving and caching

Injected pages: Cache-Control: no-cache, strong ETag from the final body, 304 on If-None-Match, no Last-Modified; behind the 60-second cache with direct invalidation on every CMS change (offering, banner). The proxy must not cache HTML, must pass ETag/If-None-Match/304 and Vary, and must forward Host and X-Forwarded-*. Measured on test-ASF (2026-11-15): HTML and robots.txt already come from the host (host headers, no Age/X-Cache), gzip is applied on the way. /assets/ stays immutable.

Open before the build starts

  1. Bryan approves the plan; the ASF golden files (input JSON + expected HTML, with a README and commit) are delivered after that.
  2. Can .NET 10 run on the hosting package (hosting bundle or self-contained)? Decided by Bryan with the hosting provider.
  3. IIS production: one pass-through entry (ASP.NET Core Module, no static-file handler or HTML caching in IIS; in-process or out-of-process with ForwardedHeaders:KnownProxies), a Windows publish artifact and its own publish job. To be written down once the environment is known and tested against test-ASF.
  4. Hero and gallery: a separate plan (same-origin images with content-hash URLs, variants and dimensions, preload for LCP); the data model keeps room for it.

Risks

Markers stripped by a build (confirmed not the case for ASF's Vite/TanStack prerender); proxy or IIS caching of HTML; .NET 10 unavailable on the package; the per-base-URL cache keyed from the Host header when no PublicBaseUrl is configured (to be capped in this unit); several app instances (invalidation is per process; the 60-second TTL bounds the lag). Estimated effort: about 1.5 days for the host side, plus ASF's front-end rework.

As built (2026-11-15)

Piece Where
Marker edits (regions, data block, JSON-LD, inline values, script escaping) Core/Hosting/Website/HtmlMarkerEditor.cs
Injector for every html/xml/txt file of the prerendered host and for the SpaFallback index.html; caching (60 s, direct invalidation, capped at 256 entries), ETag/304, address replacement, per-part fail-open Core/Hosting/Website/HtmlMarkerInjector.cs; hook in PrerenderedSiteMiddleware (ServeFile); registered by AddCmsWebsite
Neutral list and banner HTML, price rules (whole euros, 1.250) Offerings/Services/CmsPageHtml.cs; golden files of the website repo (ASF commit 16027f5) in Offerings.Tests/Golden/host-injection, GoldenHtmlTests
Marker transform (regions, #cms-data with siteUrl, JSON-LD price, data-cms-price) Offerings/Services/OfferingsHtmlTransform.cs (IHtmlPageTransform)
Settings ASF appsettings.json: Website:AuthoredBaseUrl=https://andreaslop.nl, Website:PublicBaseUrl empty (env Website__PublicBaseUrl)
End-to-end test (real database, ASF settings, temporary web root) Api.Tests/AsfInjectionPipelineTests
Smoke test scripts/smoke-site.sh: unprocessed CMS:DATA / CMS:OFFER-JSON-LD markers on / fail; a data block must carry this host's siteUrl; ETag and no-cache on the injected home page

Behaviour choices: a successful empty answer empties a region (no live package, no active banner); a failing service leaves the baked content; a package without a derivable price removes offers from the JSON-LD (a failing service does not); a file without markers and without the authored address stays a plain static file; 404.html is not injected.

Deploy order matters: set Website__PublicBaseUrl=https://test.andreaslop.nl on ASF-test before the first website build with markers is deployed, otherwise the data block's siteUrl is the production address and the smoke test fails on purpose.