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:
+31
@@ -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.
|
||||
+20
@@ -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")
|
||||
+8
@@ -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)
|
||||
+15
@@ -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.
|
||||
+40
@@ -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")
|
||||
Reference in New Issue
Block a user