Merge pull request 'Docs: ontwerp redirect-map voor prerendered sites' (#37) from docs/redirect-map-design into master
Continuous Integration / config-sls (push) Successful in 22s
Continuous Integration / changes (push) Successful in 32s
Continuous Integration / backend-build (push) Skipped
Continuous Integration / compile-sites (push) Skipped
Continuous Integration / backend-test (push) Skipped
Continuous Integration / vulnerability-scan (push) Skipped
Continuous Integration / frontend-prepare (push) Skipped
Continuous Integration / frontend-build (push) Skipped
Continuous Integration / frontend-test (push) Skipped
Continuous Integration / frontend-lint (push) Skipped
Continuous Integration / publish-sls-test (push) Skipped
Continuous Integration / publish-sls-production (push) Skipped
Continuous Integration / deploy-sls-test (push) Skipped
Continuous Integration / deploy-sls-production (push) Skipped
Continuous Integration / publish-asf-test (push) Skipped
Continuous Integration / smoke-sls-test (push) Skipped
Continuous Integration / config-asf (push) Successful in 13s
Continuous Integration / deploy-asf-test (push) Skipped
Continuous Integration / smoke-asf-test (push) Skipped
Continuous Integration / config-sls (push) Successful in 22s
Continuous Integration / changes (push) Successful in 32s
Continuous Integration / backend-build (push) Skipped
Continuous Integration / compile-sites (push) Skipped
Continuous Integration / backend-test (push) Skipped
Continuous Integration / vulnerability-scan (push) Skipped
Continuous Integration / frontend-prepare (push) Skipped
Continuous Integration / frontend-build (push) Skipped
Continuous Integration / frontend-test (push) Skipped
Continuous Integration / frontend-lint (push) Skipped
Continuous Integration / publish-sls-test (push) Skipped
Continuous Integration / publish-sls-production (push) Skipped
Continuous Integration / deploy-sls-test (push) Skipped
Continuous Integration / deploy-sls-production (push) Skipped
Continuous Integration / publish-asf-test (push) Skipped
Continuous Integration / smoke-sls-test (push) Skipped
Continuous Integration / config-asf (push) Successful in 13s
Continuous Integration / deploy-asf-test (push) Skipped
Continuous Integration / smoke-asf-test (push) Skipped
This commit was merged in pull request #37.
This commit is contained in:
@@ -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: <to>` (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<string, Entry>` 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.
|
||||
Reference in New Issue
Block a user