- 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>
114 lines
6.4 KiB
Markdown
114 lines
6.4 KiB
Markdown
# 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.
|