From cbf7afa31621448167122eabab876ac4c12b8054 Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Wed, 18 Nov 2026 21:20:39 +0100 Subject: [PATCH] Docs: ontwerp redirect-map voor oude WordPress-URL's (voorstel, niet gebouwd) Co-Authored-By: Claude Sonnet 5.5 --- .../redirect-map-design.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 aidlc-docs/features/andreaslop-site-hosting/redirect-map-design.md diff --git a/aidlc-docs/features/andreaslop-site-hosting/redirect-map-design.md b/aidlc-docs/features/andreaslop-site-hosting/redirect-map-design.md new file mode 100644 index 0000000..a8bbc46 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/redirect-map-design.md @@ -0,0 +1,87 @@ +# Redirect-map voor oude (WordPress-)URL's: ontwerp + +Status (2026-11-18): ONTWERP, niet gebouwd. Wacht op akkoord van ASF-Main over het formaat (paragraaf 2). Aanleiding: de oude WordPress-URL's van andreaslop.nl moeten op productie (IIS) netjes doorverwijzen of 410/404 geven, en de URL Rewrite-module van de hoster is onbevestigd. De regels horen daarom bij de website (data) en worden door de host uitgevoerd, op test en productie hetzelfde. + +## 1. Uitgangspunten + +- De website levert een bestand met de regels mee in de voorgerenderde map; de host heeft een generieke lezer. Geen ASF-specifieke code in de host. +- Alleen exacte padregels. Geen query-stringregels (`?p=123`, `?page_id=7`), geen patronen/regex, geen wildcards. Wat daar niet in past, blijft een gewone 404 (en kan later met een apart ontwerp). +- Vroeg in de pijplijn (voor de bestaande padherleiding van de website), maar na de gereserveerde paden (`/admin`, `/api/v1`, `/health`) en alleen voor GET en HEAD. +- Zelfde gedrag op test en productie: geen omgevingsafhankelijke instelling. +- Een kapot of ontbrekend bestand legt de site nooit plat: de vorige geldige lijst blijft staan, een melding in het log. + +## 2. Formaat (graag akkoord van ASF) + +Bestand: `redirects.json` in de root van de website (`wwwroot/web/redirects.json`, dus naast `index.html`), UTF-8. + +```json +{ + "version": 1, + "redirects": [ + { "from": "/over-mij-2/", "to": "/over-mij", "status": 301 }, + { "from": "/portfolio/bruiloft", "to": "/portfolio", "status": 301 }, + { "from": "/blog/oud-bericht", "status": 410 }, + { "from": "/wp-content/uploads/x.jpg", "status": 404 } + ] +} +``` + +Regels voor het bestand: + +| Veld | Regel | +|---|---| +| `version` | Verplicht, nu `1`. Een onbekende versie wordt als ongeldig bestand behandeld (zie 4). | +| `from` | Verplicht. Pad dat met één `/` begint, geen query of fragment, geen `//`, geen `..`, geen dubbele punt-segmenten. Percent-codering is toegestaan (`/caf%C3%A9`) en wordt vóór het vergelijken gedecodeerd. Maximaal 2048 tekens. Het eerste segment mag niet `admin`, `health` of `api/v1` zijn (gereserveerde paden van de host). | +| `to` | Verplicht bij 301, verboden bij 404/410. Een pad dat met één `/` begint (aanbevolen: dan werkt het op test en productie gelijk) of een absolute `https://`-URL naar een externe site. Geen query-string in `to`. | +| `status` | `301`, `404` of `410`. Andere waarden (302, 307, 308, 200, ...) zijn ongeldig. | + +Matching: +- Exact op het pad, **hoofdletterongevoelig**, en met en zonder slot-slash als dezelfde regel: `/over-mij-2/` en `/over-mij-2` vinden dezelfde regel. Het opgeven van beide in het bestand telt als dubbel (zie 4). `/` zelf kan niet als bron (de startpagina). +- De query-string van het verzoek speelt geen rol bij het zoeken en wordt bij 301 **niet** meegegeven aan de bestemming. +- Een regel wint van een bestaand bestand/pad van de website (de eigenaar kiest bewust). Bronnen die een echte pagina zijn, horen er dus niet in: de validatie meldt dat niet, de website-build kan het controleren. + +Antwoorden: +- 301: `Location: ` (relatief pad blijft relatief, zoals de bestaande 301's van de host), `Cache-Control: public, max-age=3600`. +- 404 en 410: het antwoord van de site zelf met de eigen 404-pagina (`404.html`, als aanwezig) als body, maar met de gevraagde statuscode (dus 410 met de 404-pagina). `Cache-Control: no-cache`. Meta-robots-gedrag verandert niet. +- Logging in de bestaande categorie `SlpModularCms.Website` (`Information`: `Website redirect-map 301 /van -> /naar`), zoals de andere 301's. +- Het bestand zelf is niet opvraagbaar (`GET /redirects.json` = 404), net als alle bestanden die de host niet als pagina of asset toont. + +Beperkingen (afgedwongen bij het laden): maximaal 5000 regels, bestand maximaal 1 MB, geen dubbele bronnen (na normaliseren), geen regel waarvan `to` gelijk is aan `from`, geen kringverwijzingen. Ketens (`a -> b -> c`) mogen; de host vlakt ze bij het laden af (`a -> c`, maximaal 10 stappen) zodat een bezoeker één redirect ziet. Een `to` die zelf op 404/410 staat, is ongeldig. + +## 3. Waar in de host + +- Nieuw: `WebsiteRedirectMap` (Core/Hosting/Website): parser, validator, opzoeklijst (`Dictionary` op genormaliseerd pad), en het laden/herladen. +- `PrerenderedSiteMiddleware.InvokeAsync`: direct na de controles op gereserveerd pad, `X-Robots-Tag`, methode en `robots.txt`, **voor** `WebsitePathResolver.Resolve`: opzoeken, antwoorden, klaar. Geen apart middleware-onderdeel in `CmsHost`. +- `WebsiteFileAccess`/resolver: `redirects.json` telt als "niet bestaand" voor het serveren. +- Alleen actief in `WebsiteMode.PrerenderedPages`; in de SPA-modus (SLS) gebeurt er niets en bestaat de service niet. +- Geen nieuwe configuratiesleutels nodig. (Optioneel later: `Website:RedirectMapFile` om de bestandsnaam te kiezen; nu niet.) + +## 4. Laden en herladen + +- Het pad van het bestand volgt de websitemap (`WebsiteFileAccess`), dus dezelfde symlink/release-wissel als de rest van de site. +- Geladen bij de eerste aanvraag (lazy) en daarna herbeoordeeld hooguit elke 5 seconden aan de hand van `LastWriteTimeUtc` + lengte van het bestand (geen `FileSystemWatcher`: onbetrouwbaar op symlinks en netwerkschijven en onnodig voor dit volume). Een gewijzigd bestand wordt dus binnen ongeveer 5 seconden actief, zonder herstart. Een deploy die de hele map vervangt, werkt hetzelfde. +- Een nieuw bestand wordt volledig gevalideerd voordat het de huidige lijst vervangt (atomisch: een verwijzing naar de nieuwe, onveranderlijke lijst). Is het ongeldig (JSON-fout, onbekende versie, regel ongeldig, limieten overschreden, kring): de vorige geldige lijst blijft actief, `Warning` in het log met de eerste vijf fouten (regelnummer en reden, geen volledige inhoud) en de fout verschijnt in Sentry via de bestaande logging. Een verwijderd bestand = lege lijst (niets wordt omgeleid). +- Het laden gebeurt buiten de verzoek-hot-path: de controle van de wijzigingstijd is een enkele `File.GetLastWriteTimeUtc` per 5 seconden, de rest een dictionary-opzoeking. + +## 5. Tests + +Unit (Core.Tests, geen I/O behalve een tijdelijke map): +1. Parser/validator: geldig bestand; ontbrekende velden; onbekende statussen; `to` bij 404/410; `to` ontbreekt bij 301; `from` zonder `/`, met `//`, `..`, query/fragment, te lang; versie 2; dubbele bronnen (ook `/a` en `/a/`, en `/A`); `from == to`; kring; keten wordt afgevlakt; `to` die zelf 404/410 is; meer dan 5000 regels; bestand groter dan 1 MB; lege lijst. +2. Opzoeken: hoofdletterongevoelig; met/zonder slot-slash; percent-gecodeerd en unicode; query-string wordt genegeerd en niet doorgegeven; `/` niet als bron. +3. Herladen: wijziging wordt binnen het interval opgepikt (met een nepklok); ongeldig nieuw bestand laat de oude lijst staan en logt een Warning; verwijderd bestand maakt de lijst leeg; bestand dat eerst ontbreekt en later verschijnt. +Integratie (bestaande `PrerenderedSiteIntegrationTests`-opzet, in-memory host): +4. 301 met `Location` en `Cache-Control`; 410 met de 404-pagina als body en statuscode 410; 404; HEAD werkt; POST wordt niet omgeleid; `/admin`, `/api/v1`, `/health` blijven buiten schot ook als een regel ze noemt (de validatie verbiedt ze als bron: `from` met een gereserveerd eerste segment is ongeldig). +5. Een regel wint van een bestaand bestand; `GET /redirects.json` = 404; zonder bestand gedrag ongewijzigd (alle bestaande tests blijven groen). +6. Zelfde antwoorden met `Website:NoIndex=true` (test) en `false` (productie); in de SPA-modus (SLS-compositie) doet het bestand niets. +7. `SiteContractTests` voor de ASF-host: de service is geregistreerd; voor SLS niet. +Documentatie: `docs/` en README krijgen een korte beschrijving van het bestand en de limieten; de website-repo van ASF levert het bestand (generator, controle dat `from` geen bestaande pagina is en dat `to` bestaat). + +## 6. Vragen aan ASF-Main + +1. Past dit formaat (met name `version`, `from`/`to`/`status`, relatieve `to`)? Zijn er andere statuscodes of velden nodig (bijv. een opmerkingveld `note` dat de host negeert: kan, zeg het maar)? +2. Hoe veel regels verwacht je (de limiet is 5000)? Staan er `?p=`-URL's of andere querystring-regels in `oude-urls.md` die dit ontwerp niet dekt? Die blijven dan 404. +3. Is hoofdletterongevoelig zoeken goed (WordPress is dat ook), en wil je voor de 410/404-antwoorden de eigen 404-pagina als body (voorstel) of een kale pagina? +4. Wie genereert `redirects.json` en waar komt het in de build terecht (`dist/redirects.json`), zodat het naast `index.html` in `wwwroot/web` belandt? +5. Moeten 301-bestemmingen op een andere host (absolute `https://...`) mogelijk zijn? (Voorstel: ja, alleen `https`.) + +Bouwen na jullie akkoord op paragraaf 2; geschat: één kleine PR in Core (parser, lezer, middleware-aanroep) met de tests hierboven.