45 lines
5.2 KiB
Markdown
45 lines
5.2 KiB
Markdown
# 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`: 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.
|