ASF-injectie 2/5: HtmlMarkerInjector (alle html/xml/txt van de prerendered host, adresvervanging, transforms, fail-open, begrensde cache) + tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 16:06:17 +01:00
co-authored by Claude Sonnet 5.5
parent 7d66944019
commit a13661517d
7 changed files with 549 additions and 137 deletions
@@ -150,27 +150,13 @@ public static class StaticContentExtensions
context.Response.ContentType = "text/html; charset=utf-8";
// Modules fill marker comments in index.html (e.g. the current offerings); cached, with an ETag.
var injector = context.RequestServices.GetService<IndexHtmlInjector>();
var injector = context.RequestServices.GetService<HtmlMarkerInjector>();
var page = injector is null
? null
: await injector.GetAsync(websiteIndex, context.Request, context.RequestAborted);
if (page is not null)
{
context.Response.Headers["Cache-Control"] = "no-cache";
context.Response.Headers["ETag"] = page.ETag;
if (context.Response.StatusCode == StatusCodes.Status200OK
&& context.Request.Headers.IfNoneMatch.Contains(page.ETag))
{
context.Response.StatusCode = StatusCodes.Status304NotModified;
return;
}
context.Response.ContentLength = page.Body.Length;
if (!HttpMethods.IsHead(context.Request.Method))
{
await context.Response.Body.WriteAsync(page.Body, context.RequestAborted);
}
await InjectedPageWriter.WriteAsync(context, page, "text/html; charset=utf-8");
return;
}
@@ -0,0 +1,252 @@
using System.Collections.Concurrent;
using System.Security.Cryptography;
using System.Text;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
namespace SlpModularCms.Core.Hosting.Website;
/// <summary>
/// A module's contribution to a website page through simple marker comments such as
/// <c>&lt;!--SLP:OFFERINGS-HTML--&gt;</c>. The key is the marker name without the comment delimiters
/// (<c>SLP:OFFERINGS-HTML</c>); the value is the HTML that replaces the whole comment (empty = remove it).
/// </summary>
public interface IIndexHtmlMarkerProvider
{
Task<IReadOnlyDictionary<string, string>> RenderAsync(string publicBaseUrl, CancellationToken cancellationToken);
}
/// <summary>Where a transform runs: the public address of the site it is writing for.</summary>
/// <param name="SiteUrl">
/// <c>Website:PublicBaseUrl</c> when configured, otherwise <c>Website:AuthoredBaseUrl</c>, otherwise the address of
/// the request. Never ends with a slash.
/// </param>
public sealed record HtmlTransformContext(string SiteUrl);
/// <summary>
/// A module's structured contribution to a page: it edits the HTML text itself (regions between markers, a data
/// block, JSON-LD, inline values; see <see cref="HtmlMarkerEditor"/>). Implementations are scoped, are asked first
/// whether the page concerns them, and must be fail-open: an exception means "leave the page as it was built".
/// </summary>
public interface IHtmlPageTransform
{
/// <summary>A cheap check of the raw page text: does this transform have anything to do here?</summary>
bool Wants(string html);
Task<string> ApplyAsync(string html, HtmlTransformContext context, CancellationToken cancellationToken);
}
/// <summary>Lets a module say that the content behind the markers changed (pages are rebuilt on the next request).</summary>
public interface IIndexHtmlCache
{
void Invalidate();
}
public sealed record InjectedPage(byte[] Body, string ETag);
/// <summary>
/// Turns a built website file (a page, <c>sitemap.xml</c>, <c>robots.txt</c>) into what is served: the production
/// address the site was built with becomes this instance's own address (<c>Website:AuthoredBaseUrl</c> to
/// <c>Website:PublicBaseUrl</c>), and, for html, the registered marker providers and page transforms fill in the
/// CMS content. Used by the SpaFallback host (index.html) and the prerendered host (every html file).
/// </summary>
/// <remarks>
/// A file that needs none of that is reported as "not injected" (null) and stays a plain static file with its
/// native headers. The rendered page is cached for <see cref="CacheTtl"/> per file and address and dropped at once on
/// <see cref="Invalidate"/> (a module calls it after a change) or when the file changes. Nothing here may take the
/// website down: a failing provider or transform is logged and skipped, so the baked content is served.
/// </remarks>
public sealed class HtmlMarkerInjector(
IServiceScopeFactory scopes,
IOptions<WebsiteOptions> options,
ILogger<HtmlMarkerInjector> logger,
TimeProvider? time = null) : IIndexHtmlCache
{
public static readonly TimeSpan CacheTtl = TimeSpan.FromSeconds(60);
private static readonly TimeSpan FailureTtl = TimeSpan.FromSeconds(5);
/// <summary>
/// Upper bound of cached pages. Without a configured <c>PublicBaseUrl</c> the address of the request is part of the
/// key, which a client can vary through the Host header; the cache is simply emptied when it grows past this.
/// </summary>
public const int MaxEntries = 256;
private readonly TimeProvider _time = time ?? TimeProvider.System;
private readonly ConcurrentDictionary<string, Entry> _cache = new();
private long _version;
private sealed record Entry(long Version, DateTime FileTime, DateTimeOffset Expires, InjectedPage? Page);
/// <summary>Number of cached results (for tests and diagnostics).</summary>
public int CachedEntryCount => _cache.Count;
public void Invalidate() => Interlocked.Increment(ref _version);
/// <summary>The file as it is served, or null when it needs no injection (serve the file as it is).</summary>
public async Task<InjectedPage?> GetAsync(string filePath, HttpRequest request, CancellationToken cancellationToken)
{
var configured = SpaSeoExtensions.BaseUrl(options.Value);
var authored = AuthoredOrigin(options.Value);
var requestBase = $"{request.Scheme}://{request.Host}";
var providerBase = configured ?? requestBase;
var siteUrl = (configured ?? authored ?? requestBase).TrimEnd('/');
var key = $"{filePath}|{providerBase}|{siteUrl}";
var fileTime = File.GetLastWriteTimeUtc(filePath);
var version = Interlocked.Read(ref _version);
var now = _time.GetUtcNow();
if (_cache.TryGetValue(key, out var cached)
&& cached.Version == version && cached.FileTime == fileTime && cached.Expires > now)
{
return cached.Page;
}
try
{
var (page, healthy) = await BuildAsync(filePath, configured, authored, providerBase, siteUrl, cancellationToken);
// A file that needs nothing stays that way until it changes; a built page lives for the TTL, and a page that
// was built without one of its parts (a failing provider) is retried soon.
var expires = page is null ? DateTimeOffset.MaxValue : now + (healthy ? CacheTtl : FailureTtl);
Store(key, new Entry(version, fileTime, expires, page));
return page;
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
// Never take the website down for its dynamic parts: keep the last good page if there is one, else serve the
// file as it was built.
logger.LogError(ex, "Preparing website file {File} failed; serving the previous or the plain file", Path.GetFileName(filePath));
Store(key, new Entry(version, fileTime, now + FailureTtl, cached?.Page));
return cached?.Page;
}
}
private void Store(string key, Entry entry)
{
if (_cache.Count >= MaxEntries)
{
_cache.Clear();
}
_cache[key] = entry;
}
private async Task<(InjectedPage? Page, bool Healthy)> BuildAsync(
string filePath, string? configured, string? authored, string providerBase, string siteUrl, CancellationToken cancellationToken)
{
var extension = Path.GetExtension(filePath).ToLowerInvariant();
var isHtml = extension is ".html" or ".htm";
var text = await File.ReadAllTextAsync(filePath, cancellationToken);
// A test instance points at itself: the authored production address becomes this instance's own. Only a
// configured PublicBaseUrl counts (never one derived from the request's Host header).
var replaceAuthored = configured is not null && authored is not null
&& !string.Equals(configured, authored, StringComparison.OrdinalIgnoreCase)
&& text.Contains(authored, StringComparison.Ordinal);
using var scope = scopes.CreateScope();
var providers = isHtml && text.Contains("<!--SLP:", StringComparison.Ordinal)
? scope.ServiceProvider.GetServices<IIndexHtmlMarkerProvider>().ToList()
: [];
var transforms = isHtml
? scope.ServiceProvider.GetServices<IHtmlPageTransform>().Where(t => t.Wants(text)).ToList()
: [];
if (!replaceAuthored && providers.Count == 0 && transforms.Count == 0)
{
return (null, true);
}
var healthy = true;
if (replaceAuthored)
{
text = text.Replace(authored!, configured!, StringComparison.Ordinal);
}
if (providers.Count > 0)
{
try
{
var markers = new Dictionary<string, string>(StringComparer.Ordinal);
foreach (var provider in providers)
{
foreach (var (name, replacement) in await provider.RenderAsync(providerBase, cancellationToken))
{
markers[name] = replacement;
}
}
foreach (var (name, replacement) in markers)
{
text = text.Replace($"<!--{name}-->", replacement, StringComparison.Ordinal);
}
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
healthy = false;
logger.LogError(ex, "Filling the website markers of {File} failed; serving them unfilled", Path.GetFileName(filePath));
}
}
var context = new HtmlTransformContext(siteUrl);
foreach (var transform in transforms)
{
try
{
text = await transform.ApplyAsync(text, context, cancellationToken);
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
healthy = false;
logger.LogError(ex, "Page transform {Transform} failed for {File}; serving the page without it", transform.GetType().Name, Path.GetFileName(filePath));
}
}
var body = Encoding.UTF8.GetBytes(text);
var etag = "\"" + Convert.ToHexString(SHA256.HashData(body))[..32].ToLowerInvariant() + "\"";
return (new InjectedPage(body, etag), healthy);
}
private static string? AuthoredOrigin(WebsiteOptions o) =>
Uri.TryCreate(o.AuthoredBaseUrl?.Trim(), UriKind.Absolute, out var uri) ? uri.GetLeftPart(UriPartial.Authority) : null;
}
/// <summary>Writes an <see cref="InjectedPage"/>: no-cache, a strong ETag, 304 on a matching <c>If-None-Match</c>, HEAD aware.</summary>
public static class InjectedPageWriter
{
public static string ContentTypeFor(string path) => Path.GetExtension(path).ToLowerInvariant() switch
{
".html" or ".htm" => "text/html; charset=utf-8",
".xml" => "text/xml; charset=utf-8",
".txt" => "text/plain; charset=utf-8",
_ => "application/octet-stream",
};
/// <summary>Files the prerendered host may pass through the injector.</summary>
public static bool IsInjectable(string path) => Path.GetExtension(path).ToLowerInvariant() is ".html" or ".htm" or ".xml" or ".txt";
public static async Task WriteAsync(HttpContext context, InjectedPage page, string contentType)
{
context.Response.ContentType = contentType;
context.Response.Headers["Cache-Control"] = "no-cache";
context.Response.Headers["ETag"] = page.ETag;
if (context.Response.StatusCode == StatusCodes.Status200OK
&& context.Request.Headers.IfNoneMatch.Contains(page.ETag))
{
context.Response.StatusCode = StatusCodes.Status304NotModified;
return;
}
context.Response.ContentLength = page.Body.Length;
if (!HttpMethods.IsHead(context.Request.Method))
{
await context.Response.Body.WriteAsync(page.Body, context.RequestAborted);
}
}
}
@@ -1,118 +0,0 @@
using System.Collections.Concurrent;
using System.Security.Cryptography;
using System.Text;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
namespace SlpModularCms.Core.Hosting.Website;
/// <summary>
/// A module's contribution to the website's <c>index.html</c>: replacement text for marker comments such as
/// <c>&lt;!--SLP:OFFERINGS-HTML--&gt;</c>. The key is the marker name without the comment delimiters
/// (<c>SLP:OFFERINGS-HTML</c>); the value is the HTML that replaces the whole comment (empty = remove it).
/// </summary>
public interface IIndexHtmlMarkerProvider
{
Task<IReadOnlyDictionary<string, string>> RenderAsync(string publicBaseUrl, CancellationToken cancellationToken);
}
/// <summary>Lets a module say that the markers' content changed (the page is rebuilt on the next request).</summary>
public interface IIndexHtmlCache
{
void Invalidate();
}
public sealed record InjectedPage(byte[] Body, string ETag);
/// <summary>
/// Fills the marker comments of the SpaFallback website's <c>index.html</c> from the registered
/// <see cref="IIndexHtmlMarkerProvider"/>s. The rendered page is cached for <see cref="CacheTtl"/> per public base URL
/// and dropped at once on <see cref="Invalidate"/> (a module calls it after a change) or when the file changes.
/// </summary>
public sealed class IndexHtmlInjector(
IServiceScopeFactory scopes,
IOptions<WebsiteOptions> options,
ILogger<IndexHtmlInjector> logger,
TimeProvider? time = null) : IIndexHtmlCache
{
public static readonly TimeSpan CacheTtl = TimeSpan.FromSeconds(60);
private static readonly TimeSpan FailureTtl = TimeSpan.FromSeconds(5);
private readonly TimeProvider _time = time ?? TimeProvider.System;
private readonly ConcurrentDictionary<string, Entry> _cache = new();
private long _version;
private sealed record Entry(long Version, DateTime FileTime, DateTimeOffset Expires, InjectedPage? Page);
public void Invalidate() => Interlocked.Increment(ref _version);
/// <summary>The page with its markers filled, or null when no provider is registered (serve the file as it is).</summary>
public async Task<InjectedPage?> GetAsync(string indexPath, HttpRequest request, CancellationToken cancellationToken)
{
var baseUrl = SpaSeoExtensions.BaseUrl(options.Value) ?? $"{request.Scheme}://{request.Host}";
var fileTime = File.GetLastWriteTimeUtc(indexPath);
var version = Interlocked.Read(ref _version);
var now = _time.GetUtcNow();
if (_cache.TryGetValue(baseUrl, out var cached)
&& cached.Version == version && cached.FileTime == fileTime && cached.Expires > now)
{
return cached.Page;
}
try
{
using var scope = scopes.CreateScope();
var providers = scope.ServiceProvider.GetServices<IIndexHtmlMarkerProvider>().ToList();
if (providers.Count == 0)
{
_cache[baseUrl] = new Entry(version, fileTime, now + CacheTtl, null);
return null;
}
var markers = new Dictionary<string, string>(StringComparer.Ordinal);
foreach (var provider in providers)
{
foreach (var (name, replacement) in await provider.RenderAsync(baseUrl, cancellationToken))
{
markers[name] = replacement;
}
}
var html = await File.ReadAllTextAsync(indexPath, cancellationToken);
// A test instance points at itself: the authored production address becomes this instance's own.
// Only a configured PublicBaseUrl counts (never one derived from the request's Host header).
var configured = SpaSeoExtensions.BaseUrl(options.Value);
var authored = Uri.TryCreate(options.Value.AuthoredBaseUrl?.Trim(), UriKind.Absolute, out var authoredUri)
? authoredUri.GetLeftPart(UriPartial.Authority)
: null;
if (configured is not null && authored is not null
&& !string.Equals(configured, authored, StringComparison.OrdinalIgnoreCase))
{
html = html.Replace(authored, configured, StringComparison.Ordinal);
}
foreach (var (name, replacement) in markers)
{
html = html.Replace($"<!--{name}-->", replacement, StringComparison.Ordinal);
}
var body = Encoding.UTF8.GetBytes(html);
var etag = "\"" + Convert.ToHexString(SHA256.HashData(body))[..32].ToLowerInvariant() + "\"";
var page = new InjectedPage(body, etag);
_cache[baseUrl] = new Entry(version, fileTime, now + CacheTtl, page);
return page;
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
// Never take the website down for its dynamic parts: keep the last good page if there is one, else
// serve the file with its markers untouched (they are HTML comments, so they render as nothing).
logger.LogError(ex, "Filling the website markers failed; serving the previous or the plain page");
var page = cached?.Page;
_cache[baseUrl] = new Entry(version, fileTime, now + FailureTtl, page);
return page;
}
}
}
@@ -36,6 +36,10 @@ public static class PrerenderedSiteExtensions
services.AddLogging(logging => logging.AddFilter(PrerenderedSiteMiddleware.LoggerCategory, level));
}
// Fills CMS content and the instance's own address into the pages it serves (see HtmlMarkerInjector).
services.AddSingleton<HtmlMarkerInjector>();
services.AddSingleton<IIndexHtmlCache>(provider => provider.GetRequiredService<HtmlMarkerInjector>());
// Presence of the marker switches on the full security-header set for website responses.
services.AddSingleton<WebsiteHostingMarker>();
@@ -30,6 +30,7 @@ public sealed class PrerenderedSiteMiddleware
private readonly RequestDelegate _next;
private readonly RequestDelegate _staticFiles;
private readonly WebsiteFileAccess _files;
private readonly HtmlMarkerInjector? _injector;
private readonly bool _noIndex;
private readonly ILogger _logger;
@@ -38,10 +39,12 @@ public sealed class PrerenderedSiteMiddleware
IWebHostEnvironment environment,
IOptions<WebsiteOptions> options,
ILoggerFactory loggerFactory,
WebsiteFileAccess files)
WebsiteFileAccess files,
HtmlMarkerInjector? injector = null)
{
_next = next;
_files = files;
_injector = injector;
_noIndex = options.Value.NoIndex;
_logger = loggerFactory.CreateLogger(LoggerCategory);
@@ -115,6 +118,17 @@ public sealed class PrerenderedSiteMiddleware
break;
case WebsiteResolution.ServeFile serve:
// Pages (and sitemap.xml / robots.txt) that carry CMS markers, or the production address the site was
// built with, are served through the injector; everything else stays a plain static file.
if (_injector is not null && InjectedPageWriter.IsInjectable(serve.RelativePath)
&& _files.GetFileInfo(serve.RelativePath).PhysicalPath is { } physicalPath
&& await _injector.GetAsync(physicalPath, request, context.RequestAborted) is { } injected)
{
context.SetEndpoint(null);
await InjectedPageWriter.WriteAsync(context, injected, InjectedPageWriter.ContentTypeFor(serve.RelativePath));
break;
}
// Routing already selected the catch-all fallback endpoint for the ORIGINAL path, and the
// static-file middleware steps aside whenever an endpoint is selected. Clearing it lets the
// file be served; the file was just confirmed to exist by the resolver.
@@ -22,8 +22,8 @@ public static class SpaSeoExtensions
public static IServiceCollection AddCmsSpaSeo(this IServiceCollection services, IConfiguration configuration)
{
services.AddOptions<WebsiteOptions>().Bind(configuration.GetSection(WebsiteOptions.SectionName));
services.AddSingleton<IndexHtmlInjector>();
services.AddSingleton<IIndexHtmlCache>(provider => provider.GetRequiredService<IndexHtmlInjector>());
services.AddSingleton<HtmlMarkerInjector>();
services.AddSingleton<IIndexHtmlCache>(provider => provider.GetRequiredService<HtmlMarkerInjector>());
return services;
}