5.2 KiB
Host injection into ASF's prerendered pages (asf-host-injection)
- Slug: asf-host-injection
- Type: Feature, proposal; not approved, build not started
- Status: 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: generaliseIndexHtmlInjector, hook inPrerenderedSiteMiddleware),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
- Bryan approves the plan; the ASF golden files (input JSON + expected HTML, with a README and commit) are delivered after that.
- Can .NET 10 run on the hosting package (hosting bundle or self-contained)? Decided by Bryan with the hosting provider.
- 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. - 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.