AIDLC-documentatie voor andreaslop-site-hosting (U1 tot en met Code Generation)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-06 15:52:04 +01:00
co-authored by Claude Sonnet 5.5
parent 7d21d9024a
commit d355519cec
31 changed files with 1598 additions and 0 deletions
@@ -0,0 +1,31 @@
# Code Generation Plan - core-site-hosting (U1)
Single source of truth for U1 code generation. Brownfield: modify in place. Application code under `src/`; docs summary under `construction/core-site-hosting/code/`.
## Unit context
- Implements FR-U1-01..11 (requirements.md); rules R1-R26 (functional design); NFR-* and patterns P1-P9 (NFR design).
- No user stories (skipped). No database, no frontend, no deployment change (U1 Infrastructure Design skipped, confirmed by CMS & API).
- Depends on: existing `Core` hosting (`CmsHost`, `StaticContentExtensions`, security headers). Consumed later by U2 (`Api.AndreaSlopFotografie`).
- Test project: `src/SlpModularCms.Core.Tests` (xunit, FluentAssertions, NSubstitute). New test-only packages: `Microsoft.AspNetCore.TestHost` (in-memory server, no MariaDB needed) and `FsCheck.Xunit` (PBT-09); versions pinned to releases older than two weeks.
- Verified while planning: the rate limiter is endpoint-policy based (`login` etc.), so website files are not throttled (NFR design verification item 2).
## Steps
- [x] **Step 1 - Options and mode.** `src/SlpModularCms.Core/Hosting/CmsHostOptions.cs`: add `WebsiteMode` enum and `WebsiteMode` property (default `SpaFallback`). Add `Website/WebsiteOptions.cs` (`NoIndex`).
- [x] **Step 2 - Pure resolver.** `Website/WebsiteResolution.cs`, `Website/WebsitePathResolver.cs` implementing R1-R14 (incl. R3 dot segments, R11 trailing-slash redirect, `IsReservedPath`), max 3 predicate calls (P4).
- [x] **Step 3 - Resolver tests.** `Website/WebsitePathResolverTests.cs` (example tests per rule, call-count test) and `Website/WebsitePathResolverPropertyTests.cs` (FsCheck: PBT-03 invariants, idempotence; shared generators, PBT-07; seed logging, PBT-08). Add package references.
- [x] **Step 4 - StrictSite policy.** `CspPolicyCatalog`: `StrictSite` constant, `KnownPolicies`, `Build` overload with site origin lists, exact directive order (R24-R26). `SecurityHeadersOptions`: `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins`; `SecurityHeadersExtensions`: origin validation including the new lists; `CspPolicyProvider` passes the lists. Existing call sites compile unchanged.
- [x] **Step 5 - Policy tests.** Extend `CspPolicyCatalogTests` and `SecurityHeadersOptionsValidationTests`: byte-for-byte site CSP with the real origins, `Strict`/`Relaxed` unchanged, unknown names still fail, invalid site origins fail; PBT-02 round trip.
- [x] **Step 6 - Header forcing (P5).** `SecurityHeaderWriter.Apply(..., alwaysSendDocumentHeaders = false)`; `SecurityHeadersMiddleware` sets it for non-reserved paths when `WebsiteMode.PrerenderedPages`. Needs the mode in the middleware: register a small `WebsiteHostingMarker` (singleton) from `AddCmsWebsite`. Writer tests for the flag.
- [x] **Step 7 - File access.** `Website/WebsiteFileAccess.cs`: physical provider rooted at `wwwroot/web`, `Exists`, `Open`, fail-soft with logging (P2, P3), log path sanitiser (NFR-OB-04).
- [x] **Step 8 - Middleware and wiring.** `Website/PrerenderedSiteMiddleware.cs` (R15-R18, R22, caching, robots, noindex, logging), `Website/WebsiteNotFoundMiddleware.cs` (R20-R21), `Website/PrerenderedSiteExtensions.cs` (`AddCmsWebsite` with gzip-only compression and options validation; `UseCmsPrerenderedSite`; `UseCmsWebsiteNotFound`). `CmsHost` and `StaticContentExtensions`: branch on `WebsiteMode`; `SpaFallback` path untouched; pipeline order documented in `CmsHost`.
- [x] **Step 9 - Integration tests.** `Website/PrerenderedSiteIntegrationTests.cs` with an in-memory `TestServer` host composing the real security-header and website extensions over a temp `wwwroot/web`: pages, canonical 301s, trailing slash, assets (immutable), `no-cache`, 404 page with status 404, missing `404.html`, dotfiles and `.well-known`, reserved prefixes untouched (an unknown `/api/v1/x` stays a non-website 404), robots/noindex, full header set on page, asset, 301, 404, robots.txt (Q1 = A), gzip only, HEAD, no HTTPS-redirect loop on plain HTTP, missing `wwwroot/web` keeps host alive. Includes a local timing check (NFR-PF-02) printed to the test output.
- [x] **Step 10 - Regression.** Run the full `Core.Tests`, `Modules.*.Tests` and `Api.Tests`/`Api.SlpSoftware` suites (the ones needing MariaDB are run if a local DB is reachable, otherwise reported as not runnable with the reason).
- [x] **Step 11 - Documentation.** Update `WEBSITE_WORKSPACE.md` and `README.md` (mode, settings `Website:NoIndex`, `SecurityHeaders:AllowedSite*Origins`, `StrictSite`, logging category, behaviour table); mirror nothing in `AGENTS.md` (structure unchanged). Write `construction/core-site-hosting/code/code-summary.md`.
- [x] **Step 12 - Build and test (Step 13.5).** `dotnet build SlpModularCms.sln`, run all U1 tests, fix until green.
- [x] **Step 13 - Commit.** One commit on `feature/andreaslop-site-hosting` for U1 code (aidlc-docs committed separately or with it per repo habit); no push.
## Deployment artifacts
None in U1 (config samples for the Andrea client belong to U2).
## Story traceability
No stories (skipped by decision Q6). Traceability to requirements: Step 1 FR-U1-01; Step 2-3 FR-U1-02..04; Step 4-6 FR-U1-08..09; Step 7-8 FR-U1-03..07, 10; Step 11 FR-U1-11.
@@ -0,0 +1,20 @@
# Functional Design Questions - core-site-hosting (U1)
## Question 1: Security headers on non-HTML website responses
nginx sends the full header set (CSP, HSTS, nosniff, X-Frame-Options, Referrer-Policy and, on test, X-Robots-Tag) on every response, including assets, 301 redirects, robots.txt and the 404 page. The current host writer treats CSP, X-Frame-Options and Referrer-Policy as "HTML-only" headers. For website responses in `PrerenderedPages` mode:
- A) Send the full set on every website response, like nginx (assets, redirects, robots.txt, 404); the site's verify script can then assert identical headers everywhere (recommended)
- B) Keep the current rule: CSP, X-Frame-Options and Referrer-Policy only on HTML responses; HSTS and nosniff on all
- X) Other (please describe after [Answer]: tag below)
[Answer]: A (relayed via CMS & API: "Volledige set overal")
## Question 2: Hidden paths (dot segments)
nginx test conf serves any file under the root. Should the host refuse paths with a segment starting with a dot (for example `/.git/config`, `/.env`)?
- A) Refuse (404) every dot-segment path except `/.well-known/...` (recommended: protects accidental dotfiles in a delivered site, keeps ACME/security.txt possible)
- B) Refuse every dot-segment path without exception
- C) No special rule, same as nginx
- X) Other (please describe after [Answer]: tag below)
[Answer]: A (relayed via CMS & API: "Weigeren, behalve .well-known")
@@ -0,0 +1,8 @@
# Functional Design Plan - core-site-hosting (U1)
- [x] Analyse unit context (unit-of-work.md, requirements FR-U1-01..11, website repo rules BR-HST, nginx test conf)
- [x] Collect answers to `core-site-hosting-fd-questions.md`
- [x] Generate `business-logic-model.md` (resolution flow, request flow, header rules)
- [x] Generate `business-rules.md` (rule table R1.., decision flow)
- [x] Generate `domain-entities.md` (WebsiteResolution, options, policy header set, config keys)
- [x] No frontend artifacts (U1 has no UI)
@@ -0,0 +1,15 @@
# NFR Design Plan - core-site-hosting (U1)
## Steps
- [x] Analyse NFR requirements (nfr-requirements.md, tech-stack-decisions.md)
- [x] Evaluate question categories; no open questions (justification below)
- [x] Generate `nfr-design/nfr-design-patterns.md`
- [x] Generate `nfr-design/logical-components.md`
## Category evaluation (why no questions)
- Resilience: decided by NFR-AV-01..04 (host never stops, resolver total, read errors become 404 plus warning). No retries or circuit breakers apply to local file access.
- Scalability: NFR-SC-01 (one small site); no scaling mechanism needed.
- Performance: decided by Q3 (call-count test, timing check) and the no-cache decision D3.
- Security: Security Baseline table in nfr-requirements.md; implementation choices follow existing code (`SecurityHeaderWriter`, `PathPolicyResolver`) and have one obvious solution.
- Logical components: no queue, cache or breaker; only in-process classes. The one real design choice (how to force the full header set on website responses) follows from the existing writer and Q1 = A; it is documented and can be changed at the approval step.
- Risk 2 from application design (HTTPS redirection behind the proxy Pi): inspected; the existing `UseHttpsRedirection` is a no-op without an HTTPS port, same as `Api.SlpSoftware` today; verified by an integration test in code generation.
@@ -0,0 +1,40 @@
# NFR Requirements Plan - core-site-hosting (U1)
## Steps
- [x] Analyse functional design (business-rules R1-R26, flows, entities)
- [x] Collect answers to the questions below
- [x] Generate `nfr-requirements/nfr-requirements.md`
- [x] Generate `nfr-requirements/tech-stack-decisions.md`
- [x] Security Baseline and PBT applicability check (tabulated in the artifacts)
## Pre-filled assumptions (tell me if wrong, via Other on the last question)
- Scale: one small site on one Raspberry Pi behind the proxy Pi; tens of requests per second at most.
- Availability: same as the host today; a missing or half-delivered `wwwroot/web` must never stop the host (website paths 404, API and admin keep working).
- Security: Security Baseline applies (path validation in the resolver, secure defaults, no new dependencies); compression stays off for TLS-terminated traffic by default is irrelevant because the proxy Pi forwards plain HTTP.
- Tech stack: built-in ASP.NET Core only (no new NuGet packages), xUnit and FsCheck if already used in the repo for PBT.
## Question 1: Compression algorithms
nginx today uses gzip only. ASP.NET Core can also do Brotli.
- A) gzip only, same as nginx today (simplest, identical behaviour for the verify script) (recommended)
- B) Brotli and gzip (smaller responses; the site's verify script must then accept `br`)
- X) Other (please describe after [Answer]: tag below)
[Answer]: A (relayed via CMS & API: "Alleen gzip")
## Question 2: Observability of website traffic
- A) Log nothing extra per request; log only warnings (file read errors, missing `wwwroot/web` at startup once) (recommended, no log noise on a small Pi)
- B) Also log each 404 and each 301 at Information level (useful to spot broken links, noisy with crawlers)
- X) Other (please describe after [Answer]: tag below)
[Answer]: Relayed via CMS & API, Bryan verbatim: "Alleen waarschuwingen en meer op de pi, op productie later bepalen". Interpretation (to be confirmed by approval): dedicated logger category, 404/301 at Information, level per environment (test = Information, default/production = Warning).
## Question 3: Performance verification
Per-request `File.Exists` has no cache (design decision). How much proof do you want that this is fast enough?
- A) A unit/integration test asserting no unbounded work (a resolve does at most 3 file-exists calls) plus a simple local timing check recorded in the hand-back (recommended)
- B) Only the file-exists-call-count test, no timing check
- C) A load test against the test Pi after deploy (extra work in U2)
- X) Other (please describe after [Answer]: tag below)
[Answer]: A (relayed via CMS & API: "Aantaltest plus lokale tijdmeting")