- Pure WebsitePathResolver (canonieke 301's, echte 404, dotfiles geweigerd, gereserveerde prefixes) - PrerenderedSiteMiddleware, 404-fallback na de API-routes, gzip, Cache-Control, NoIndex/robots.txt - Beleid StrictSite met eigen AllowedSite*Origins; volledige headerset op alle websiteresponses - Tests: voorbeelden, FsCheck-properties en integratietests op een in-memory server Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
6.4 KiB
Website Workspace Contract
Dit document is voor wie de publieke website bouwt die naast de SlpModularCms-admin draait. Je hoeft de rest van deze repository niet te lezen om een werkende site te kunnen opleveren — dit contract is compleet genoeg om zelfstandig te volgen.
Doelpad
De website hoort in wwwroot/web/, in de root van de gepubliceerde applicatie. Dit pad moet
minimaal een index.html bevatten. Alles onder wwwroot/web/ is van jou — de applicatie zelf raakt
deze map nooit aan buiten het plaatsen van de bestanden die je aanlevert, en een CMS-deploy verwijdert
of overschrijft de inhoud nooit (zie "Waarom dit veilig is" hieronder).
wwwroot/
web/ ← jouw site komt hier (dit contract)
index.html ← verplicht
assets/...
...
admin/ ← VERBODEN — dit is de CMS admin-UI, hoort niet bij deze repo
Verboden en gereserveerde paden
Verboden — plaats hier nooit bestanden:
wwwroot/admin/— dit is de CMS admin-single-page-app, wordt door deze repository zelf beheerd en bij elke build overschreven- De applicatie-root zelf (waar de
.dll-bestanden van de API staan)
Gereserveerd — deze paden bestaan al en je site mag er niet mee botsen:
/admin— de CMS admin-UI/api/v1— de backend-API/health— infrastructuur-liveness-check (zie hieronder — dit is geen CMS-functionaliteit)
Als jouw site een eigen route of bestand op een van deze paden zou plaatsen, wint de gereserveerde route altijd.
Routing (SPA-fallback)
Voor paden die geen bestandsextensie hebben (bijv. /over-ons, /producten/123) valt de
applicatie terug op wwwroot/web/index.html — zo werkt client-side routing (React Router, Vue
Router, of vergelijkbaar) zoals verwacht. Voor paden die er wél uitzien als een bestand (bijv.
/assets/logo.png) geldt geen fallback: ontbreekt het bestand, dan krijg je gewoon een 404, niet
per ongeluk de index.html.
Dit betekent: bouw je een Single Page Application, dan hoeft je routing-configuratie niets speciaals te doen voor deze server — de fallback wordt door de applicatie zelf verzorgd.
Alternatief: voorgerenderde site (WebsiteMode = PrerenderedPages)
Een client kan kiezen voor een voorgerenderde meerpaginasite (elke pagina is een eigen .html-bestand)
in plaats van de SPA-fallback hierboven. Dat is een keuze van de client (new CmsHostOptions { WebsiteMode = WebsiteMode.PrerenderedPages } in zijn Program.cs); zonder die keuze verandert er niets. De host serveert dan
zoals nginx dat deed:
| Verzoek | Resultaat |
|---|---|
/ |
index.html |
/over-mij |
over-mij.html (ook map/index.html als map.html ontbreekt) |
/Over-Mij, /over-mij.html, /over-mij/ |
één 301 naar /over-mij (query blijft behouden; relatieve Location) |
/index, /index.html |
301 naar / |
| elk ander pad met slash aan het eind | 301 naar het pad zonder slash (ook als dat niet bestaat; daarna volgt de 404) |
bestand met extensie (/assets/app.abc.js) |
het bestand zelf; nooit omgezet naar kleine letters of doorgestuurd; ontbreekt het, dan 404 |
onbekend pad, /404, /404.html, map zonder pagina |
404.html met status 404 (bestaat 404.html niet: kale 404); nooit index.html |
pad met een segment dat met een punt begint (/.env, /.git/...) |
404; alleen /.well-known/... blijft bereikbaar |
/admin, /api/v1, /health |
nooit door de website afgehandeld; een onbekend /api/v1-pad blijft een API-404 |
Caching: pagina's en overige rootbestanden Cache-Control: no-cache, alles onder /assets/ public, max-age=31536000, immutable. Tekstbestanden (html, css, js, svg, json, xml, txt) worden met gzip gecomprimeerd (geen Brotli). De pagina's
worden per verzoek bij het bestandssysteem opgezocht, zonder cache: een nieuwe website-deploy is direct zichtbaar, zonder
herstart van de host.
Headers: elke websiterespons (pagina, asset, 301, 404, robots.txt) krijgt de volledige set (CSP, HSTS, nosniff,
X-Frame-Options, Referrer-Policy). Het beleid is StrictSite: dezelfde CSP als de site nu heeft
(script-src 'self' plus de origins uit SecurityHeaders:AllowedSiteScriptOrigins, connect-src 'self' plus
SecurityHeaders:AllowedSiteConnectOrigins). Die twee lijsten gelden alleen voor StrictSite; de admin-policies
worden er niet soepeler van.
Een testinstantie zet Website:NoIndex = true: dan krijgt elke websiterespons X-Robots-Tag: noindex, nofollow en geeft
/robots.txt User-agent: * / Disallow: /.
De API aanroepen
Roep /api/v1/... aan met relatieve URL's (bijv. fetch('/api/v1/System/capabilities')). Omdat
je site en de API door hetzelfde proces op dezelfde origin worden geserveerd, is dit een same-origin
request — er is geen CORS-configuratie nodig, en er hoeft niets ingesteld te worden om dit te laten
werken.
Content-Security-Policy
Jouw site valt onder het Relaxed-beleid (de standaardpolicy voor alle paden die niet expliciet
Strict zijn — /admin, /api/v1 en /health krijgen Strict, / (jouw site) niet). Dit beleid is
bewust minder streng, zodat je niet gebonden bent aan restricties die voor de CMS-admin gelden maar
die je als website-bouwer nooit zou hoeven kennen. De exacte permissieve/strikte policy-definities
staan in code (SlpModularCms.Core), niet in configuratie — je hoeft ze niet zelf te lezen om te
weten dat je site onder het permissieve beleid valt.
Umami-analytics insluiten
Als de instantie analytics gebruikt, wordt het Umami-trackingscript geladen via een build-time
omgevingsvariabele op de admin-kant (VITE_UMAMI_SCRIPT_URL / VITE_UMAMI_WEBSITE_ID) — dat
script wordt dus niet door jouw site zelf ingesloten. Wil je dat jouw website ook gemeten wordt via
dezelfde Umami-instantie, vraag dan de scriptregel en het bijbehorende website-ID op bij wie de CMS
beheert, en neem die regel zelf op in je index.html (Umami's standaard <script>-snippet). Dit
contract schrijft niets voor over jouw eigen analytics-keuze — dit is puur de informatie die je nodig
hebt als je bij dezelfde Umami-instantie wilt aansluiten.
Waarom dit veilig is
Een deploy van de CMS zelf gebeurt via een atomische release-switch: een nieuwe release komt in een
verse map te staan en pas daarna wisselt de actieve release in één keer over. wwwroot/web/ staat
buiten die verwisselde map en wordt er telkens in gelinkt — een CMS-deploy kan je site dus
structureel niet raken, ongeacht hoe vaak de CMS zelf wordt bijgewerkt.