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:
+26
@@ -0,0 +1,26 @@
|
||||
# Code Summary - core-site-hosting (U1)
|
||||
|
||||
## Created (src/SlpModularCms.Core/Hosting/Website/)
|
||||
- `WebsiteResolution.cs`, `WebsitePathResolver.cs` - pure resolver (R1-R14), max 2 file checks
|
||||
- `WebsiteOptions.cs` - `Website:NoIndex`
|
||||
- `WebsiteFileAccess.cs` - confined, fail-soft file provider, root looked up per call
|
||||
- `PrerenderedSiteMiddleware.cs` - redirects, robots, files via static-file middleware (cache rules, charset)
|
||||
- `WebsiteNotFoundHandler.cs` - final fallback: `404.html` with status 404, 405 for other methods
|
||||
- `PrerenderedSiteExtensions.cs` - `AddCmsWebsite` (gzip only), `UseCmsPrerenderedSite`, `MapCmsWebsiteNotFound`
|
||||
- `WebsiteHostingMarker.cs` - switches on the full header set
|
||||
|
||||
## Modified
|
||||
- `CmsHostOptions.cs` (+ `WebsiteMode`), `CmsHost.cs` (mode wiring, documented order), `StaticContentExtensions.cs` (mode parameter, defaults unchanged)
|
||||
- `Security/CspPolicyCatalog.cs` (+ `StrictSite`), `SecurityHeadersOptions.cs` (+ `AllowedSite*Origins`), `SecurityHeadersExtensions.cs` (validation, log), `CspPolicyProvider.cs`, `SecurityHeaderWriter.cs` (`alwaysSendDocumentHeaders`), `SecurityHeadersMiddleware.cs`
|
||||
- `WEBSITE_WORKSPACE.md`, `README.md`
|
||||
|
||||
## Tests (src/SlpModularCms.Core.Tests/Hosting/)
|
||||
- `Website/WebsitePathResolverTests.cs` (examples per rule), `WebsitePathResolverPropertyTests.cs` (FsCheck: PBT-03), `PrerenderedSiteIntegrationTests.cs` (in-memory server, 25 scenarios incl. full header set on page/asset/301/404/robots.txt, gzip-only, dotfiles, reserved prefixes, SpaFallback regression)
|
||||
- `Security/StrictSitePolicyTests.cs` (byte-for-byte CSP, PBT-02), `SecurityHeaderWriterDocumentHeadersTests.cs`
|
||||
- New test-only packages: `FsCheck.Xunit 3.4.0`, `Microsoft.AspNetCore.TestHost 10.0.9`
|
||||
|
||||
## Deviations from the design
|
||||
1. The resolver has no `IsNotFoundPage` flag on `ServeFile`; the 404 page is handled only by `WebsiteNotFoundHandler`.
|
||||
2. Max 2 resolver file checks (plus 1 for `404.html` in the final stage) = 3 per request, as designed.
|
||||
3. Routing selects the catch-all fallback endpoint before the website middleware; the middleware clears the endpoint before delegating to the static-file middleware (otherwise the framework skips serving).
|
||||
4. The not-found fallback uses an explicit `{*path}` pattern (the default `nonfile` pattern would leave `/assets/missing.js` with a bare 404).
|
||||
+77
@@ -0,0 +1,77 @@
|
||||
# Business Logic Model - core-site-hosting (U1)
|
||||
|
||||
## Resolution flow (pure resolver)
|
||||
```mermaid
|
||||
flowchart TD
|
||||
S["Raw path + query"] --> V{"R2 valid?"}
|
||||
V -- no --> NF["NotFound"]
|
||||
V -- yes --> RS{"R1 reserved?"}
|
||||
RS -- yes --> PASS["Not handled (middleware passes on)"]
|
||||
RS -- no --> DOT{"R3 dot segment, not .well-known?"}
|
||||
DOT -- yes --> NF
|
||||
DOT -- no --> ROOT{"path is /?"}
|
||||
ROOT -- yes --> IDX["ServeFile index.html"]
|
||||
ROOT -- no --> IX{"R6 index variant?"}
|
||||
IX -- yes --> RD0["Redirect /"]
|
||||
IX -- no --> F4{"R7 404 or 404.html?"}
|
||||
F4 -- yes --> NF
|
||||
F4 -- no --> KN{"Known page by lowercased name?"}
|
||||
KN -- yes --> CAN{"Exactly canonical /name?"}
|
||||
CAN -- yes --> SF["ServeFile name.html"]
|
||||
CAN -- no --> RD1["Redirect /name + query"]
|
||||
KN -- no --> EXT{"Has extension?"}
|
||||
EXT -- yes --> FE{"File exists?"}
|
||||
FE -- yes --> SF2["ServeFile asset"]
|
||||
FE -- no --> NF
|
||||
EXT -- no --> TS{"R11 ends in slash?"}
|
||||
TS -- yes --> RD2["Redirect stripped path + query"]
|
||||
TS -- no --> DIR{"name/index.html exists?"}
|
||||
DIR -- yes --> SF3["ServeFile name/index.html"]
|
||||
DIR -- no --> NF
|
||||
|
||||
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef redir fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef bad fill:#feb2b2,stroke:#c53030,stroke-width:1px,color:#000;
|
||||
classDef pass fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000;
|
||||
class IDX,SF,SF2,SF3 ok;
|
||||
class RD0,RD1,RD2 redir;
|
||||
class NF bad;
|
||||
class PASS pass;
|
||||
```
|
||||
|
||||
Text alternative: invalid paths and dotfiles are NotFound; reserved prefixes pass on; known pages are served when canonical or redirected once; files with extensions are served or NotFound; other paths try the trailing-slash strip (R11), then a directory index (trailing slashes are always stripped by redirect, even for unknown targets), else NotFound.
|
||||
|
||||
## Response flow (middleware)
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Request"] --> M{"GET or HEAD, not reserved?"}
|
||||
M -- no --> N["next()"]
|
||||
M -- yes --> RB{"NoIndex and /robots.txt?"}
|
||||
RB -- yes --> RT["200 Disallow all"]
|
||||
RB -- no --> R["Resolve"]
|
||||
R --> X{"Result"}
|
||||
X -- Redirect --> R301["301 Location"]
|
||||
X -- ServeFile --> SV["200 file, Cache-Control rule"]
|
||||
X -- NotFound --> N2["next() -> API routes"]
|
||||
N2 --> L{"Endpoint matched?"}
|
||||
L -- yes --> API["API response"]
|
||||
L -- no --> E404["404.html with status 404 (or empty 404)"]
|
||||
|
||||
classDef a fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef b fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class RT,R301,SV,E404 a;
|
||||
class N,N2,API b;
|
||||
```
|
||||
|
||||
Text alternative: the middleware answers robots, redirects and files itself; unresolved paths continue to the API routes, and only if nothing matches does the final stage serve the 404 page.
|
||||
|
||||
## Header application (Q1 = A)
|
||||
All website responses, whatever the branch (200 file, 301, robots, 404 page, empty 404), pass through the security-headers stage with the full set of the active policy. The headers stage detects website requests (non-reserved path in `PrerenderedPages` mode) and skips the HTML-only distinction for them. `X-Robots-Tag` is added by the website stage when `NoIndex` is set.
|
||||
|
||||
## Dot-segment handling (Q2 = A)
|
||||
Refusal happens inside the pure resolver (R3), so it is covered by property tests and cannot be bypassed by the middleware. `/.well-known/...` resolves like any file path.
|
||||
|
||||
## Error handling
|
||||
- Resolver never throws; invalid input is `NotFound`.
|
||||
- File read errors in the middleware (race with a site delivery) -> 404 page; logged at warning level without the raw path.
|
||||
- Missing `wwwroot/web` -> every website path 404 (plain); host still starts and serves API and admin.
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
# Business Rules - core-site-hosting (U1)
|
||||
|
||||
Applies only in `WebsiteMode.PrerenderedPages`. `SpaFallback` keeps today's behaviour.
|
||||
|
||||
## Path resolution (pure `WebsitePathResolver`)
|
||||
| # | Rule |
|
||||
|---|---|
|
||||
| R1 | Reserved: a path whose first segment is `admin`, `api` + `v1`, or `health` (whole segments, case-insensitive) is never resolved; the middleware passes it on. |
|
||||
| R2 | Invalid input is `NotFound`: null/empty, not starting with `/`, containing backslash, NUL or other control characters, `%`-encoded traversal after one decode pass, `..` segments, or longer than 2048 chars. |
|
||||
| R3 | **Dot segments (Q2 = A):** any segment starting with `.` is `NotFound`, except paths under `/.well-known/` (which are then served as ordinary files; `..` stays refused). |
|
||||
| R4 | A result `ServeFile` never points outside the website root; the relative path is forward-slash, validated before the predicate is called. |
|
||||
| R5 | `/` -> `ServeFile("index.html")`. |
|
||||
| R6 | `/index`, `/index.html`, `/index/` and case variants -> `Redirect("/")` (query preserved). |
|
||||
| R7 | `/404` and `/404.html` (any case) -> `NotFound` (no redirect, no serving of the page as 200). |
|
||||
| R8 | Path with a file extension: served as a file when it exists, else `NotFound`. Never lower-cased, never redirected (hashed asset names), never falls back to a page. Exception: `<name>.html` for a known page redirects (R10). |
|
||||
| R9 | Extensionless `/x` where `x.html` exists (name lower-cased) and the request is exactly `/x` -> `ServeFile("x.html")`. `/x/index.html` is served if it exists and `x.html` does not. |
|
||||
| R10 | Non-canonical request for a known page (case variant, `.html` suffix, trailing slash) -> one `Redirect("/<lowercase-name>")`, query string appended unchanged. Target comes from the known name, never from raw input. |
|
||||
| R11 | Any path longer than one character ending in one or more slashes (and not a known page, which R10 handles) -> `Redirect` (301) to the path with all trailing slashes stripped, query preserved, whether or not the target exists (website rule BR-HST-03; an unknown target yields the 404 page on the follow-up request). If the stripped target would start with `//` or `/\` or contain control characters it is `NotFound` (R12). `/` is never redirected. A redirect target never ends in a slash except `/` (idempotent with R6, R10). |
|
||||
| R12 | A redirect target starting with `//` or `/\` is never produced; such requests are `NotFound` (open-redirect guard). |
|
||||
| R13 | A directory without a page file is `NotFound`; no directory listing. |
|
||||
| R14 | Unknown path -> `NotFound`; the middleware turns it into the 404 page (R20). |
|
||||
|
||||
## Response rules (middleware)
|
||||
| # | Rule |
|
||||
|---|---|
|
||||
| R15 | `Redirect` -> status 301, relative `Location`, no body needed. |
|
||||
| R16 | Cache-Control: `/assets/**` -> `public, max-age=31536000, immutable`; every other website file -> `no-cache`. |
|
||||
| R17 | Compression only for non-reserved paths and these types: html, js, css, svg, json, xml, txt; `Vary: Accept-Encoding`. |
|
||||
| R18 | `Website:NoIndex = true`: `X-Robots-Tag: noindex, nofollow` on every website response; `GET /robots.txt` -> 200 `text/plain` `User-agent: *` / `Disallow: /`. When false, `/robots.txt` is served from the file if it exists, else 404. |
|
||||
| R19 | **Headers (Q1 = A):** every website response (page, asset, 301, 404, robots.txt) carries the full set of the active policy: CSP, HSTS, nosniff, `X-Frame-Options`, `Referrer-Policy`. The HTML-only distinction does not apply to website responses in this mode. API and admin responses keep today's rules. |
|
||||
| R20 | Unknown non-reserved path, after API routes had no match: serve `404.html` with status 404; if `404.html` is missing, plain 404 with empty body. Never `index.html`. |
|
||||
| R21 | An unknown `/api/v1` path stays an API 404 (not replaced by the website page). |
|
||||
| R22 | Methods: only GET and HEAD are served; others on website paths get 405 (`Allow: GET, HEAD`) unless an API route claims them. |
|
||||
|
||||
## StrictSite policy
|
||||
| # | Rule |
|
||||
|---|---|
|
||||
| R23 | `StrictSite` is in `KnownPolicies`; unknown policy names still fail startup validation. `Strict` and `Relaxed` outputs unchanged. |
|
||||
| R24 | CSP string, in this exact order: `default-src 'self'; script-src 'self' <site script origins>; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' <site connect origins>; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`. With the site's configured origins it equals the nginx value byte for byte. |
|
||||
| R25 | Site origin lists are used only by `StrictSite`; admin policies never gain them. Origins are validated like existing ones (https URL, no wildcard, no whitespace/semicolon). |
|
||||
| R26 | HSTS `max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`. |
|
||||
|
||||
## Security Baseline mapping (functional level)
|
||||
- Input validation centralised in the resolver (R2-R4, R12): satisfies path-traversal and open-redirect prevention.
|
||||
- Secure defaults: new settings default to today's behaviour (`SpaFallback`, empty lists, `NoIndex=false`).
|
||||
- Dotfile refusal (R3) prevents accidental disclosure from a delivered site.
|
||||
|
||||
## PBT properties (partial scope)
|
||||
- PBT-02 round trip: building a policy then parsing its CSP directives yields the configured origins.
|
||||
- PBT-03 invariants: for any input, `Resolve` never throws; `ServeFile` paths contain no `..`, backslash, leading `/` or dot segment (except `.well-known`); `Redirect` locations start with a single `/`, never `//` or `/\`.
|
||||
- Idempotence: resolving a `Redirect` target (same predicate) never yields a second `Redirect`; a `Redirect` location never ends in `/` except `/` itself.
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
# Domain Entities - core-site-hosting (U1)
|
||||
|
||||
No persistent data. All entities are in-memory values or configuration.
|
||||
|
||||
## Entities
|
||||
| Entity | Kind | Fields / values | Notes |
|
||||
|---|---|---|---|
|
||||
| `WebsiteMode` | enum | `SpaFallback` (0, default), `PrerenderedPages` (1) | On `CmsHostOptions.WebsiteMode` |
|
||||
| `WebsiteResolution` | closed union | `ServeFile(RelativePath, IsNotFoundPage)`, `Redirect(Location)`, `NotFound` | `Redirect` is always 301 with a relative `Location` built only from known-page names |
|
||||
| `WebsiteOptions` | options | `NoIndex: bool` (default false) | Section `Website`; validated at startup |
|
||||
| `SecurityHeadersOptions` (extended) | options | + `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins` | Used only by `StrictSite` |
|
||||
| `StrictSite` policy | header set | CSP, HSTS, nosniff, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` | CSP byte-identical to the site's current one |
|
||||
| Known page | derived | file `<lowercase-name>.html` present in `wwwroot/web` | Never cached; decided per request via the file-exists predicate |
|
||||
|
||||
## Configuration keys
|
||||
| Key | Default | Effect |
|
||||
|---|---|---|
|
||||
| `Website:NoIndex` | `false` | `X-Robots-Tag: noindex, nofollow` on every website response; `/robots.txt` answers `Disallow: /` |
|
||||
| `SecurityHeaders:DefaultPolicy` | `Strict` | Client sets `StrictSite` |
|
||||
| `SecurityHeaders:AllowedSiteScriptOrigins` | `[]` | Script origins of `StrictSite` |
|
||||
| `SecurityHeaders:AllowedSiteConnectOrigins` | `[]` | Connect origins of `StrictSite` |
|
||||
|
||||
## Relationships
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CmsHostOptions { WebsiteMode }
|
||||
class WebsiteResolution
|
||||
class ServeFile { RelativePath, IsNotFoundPage }
|
||||
class Redirect { Location }
|
||||
class NotFound
|
||||
class WebsiteOptions { NoIndex }
|
||||
class SecurityHeadersOptions { AllowedSiteScriptOrigins, AllowedSiteConnectOrigins }
|
||||
WebsiteResolution <|-- ServeFile
|
||||
WebsiteResolution <|-- Redirect
|
||||
WebsiteResolution <|-- NotFound
|
||||
CmsHostOptions --> WebsiteOptions : enables when PrerenderedPages
|
||||
SecurityHeadersOptions --> CmsHostOptions : StrictSite for site client
|
||||
```
|
||||
|
||||
Text alternative: `WebsiteResolution` has three variants; the host option enables the website options and the client configures the StrictSite origin lists.
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
# Logical Components - core-site-hosting (U1)
|
||||
|
||||
No infrastructure components (no queue, cache, breaker, store). All in-process.
|
||||
|
||||
| Component | Namespace / file (planned) | Role |
|
||||
|---|---|---|
|
||||
| `WebsitePathResolver`, `WebsiteResolution` | `Core.Hosting.Website` | Pure resolution (P1) |
|
||||
| `WebsiteOptions` (+ validator) | `Core.Hosting.Website` | `Website:NoIndex` |
|
||||
| `PrerenderedSiteMiddleware` | `Core.Hosting.Website` | HTTP adapter: redirects, files, robots, cache headers, logging |
|
||||
| `WebsiteNotFoundMiddleware` (final stage) | `Core.Hosting.Website` | `404.html` with status 404 after API routes |
|
||||
| `WebsiteFileAccess` | `Core.Hosting.Website` | Physical file provider rooted at `wwwroot/web`; exists/read with fail-soft (P2, P3) |
|
||||
| `PrerenderedSiteExtensions` | `Core.Hosting.Website` | `AddCmsWebsite`, `UseCmsPrerenderedSite`, `UseCmsWebsiteNotFound` |
|
||||
| `SecurityHeaderWriter` (extended), `SecurityHeadersMiddleware` (extended) | `Core.Hosting.Security` | P5 |
|
||||
| `CspPolicyCatalog` (+ `StrictSite`), `SecurityHeadersOptions` (+ site origin lists) | `Core.Hosting.Security` | R23-R26 |
|
||||
| `CmsHost`, `CmsHostOptions`, `StaticContentExtensions` | `Core.Hosting` | Mode wiring |
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
CH["CmsHost"] --> EXT["PrerenderedSiteExtensions"]
|
||||
EXT --> MW["PrerenderedSiteMiddleware"]
|
||||
EXT --> NF["WebsiteNotFoundMiddleware"]
|
||||
MW --> RES["WebsitePathResolver (pure)"]
|
||||
MW --> FA["WebsiteFileAccess"]
|
||||
NF --> FA
|
||||
CH --> SH["SecurityHeadersMiddleware"]
|
||||
SH --> W["SecurityHeaderWriter (+ force flag)"]
|
||||
SH --> CAT["CspPolicyCatalog (StrictSite)"]
|
||||
|
||||
classDef pure fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef sec fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class RES pure;
|
||||
class CH,EXT,MW,NF,FA core;
|
||||
class SH,W,CAT sec;
|
||||
```
|
||||
|
||||
Text alternative: the host wires the website extensions and the security-header middleware; the site middleware uses the pure resolver and the confined file access; the header middleware uses the writer and the policy catalog.
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
# NFR Design Patterns - core-site-hosting (U1)
|
||||
|
||||
| # | Pattern | Realises | Design |
|
||||
|---|---|---|---|
|
||||
| P1 | Pure core, thin adapter | NFR-MT-01, NFR-AV-03, PBT-03 | `WebsitePathResolver.Resolve` is a static total function; the middleware only translates `WebsiteResolution` into HTTP. Every rule R1-R14 is testable without a server. |
|
||||
| P2 | Defence in depth for path safety | Security Baseline | Layer 1: resolver validation (R2-R4, R12). Layer 2: file access only through a physical `IFileProvider` rooted at `wwwroot/web` (never `Path.Combine` with request data). A bug in one layer does not expose files outside the root. |
|
||||
| P3 | Fail-soft file access | NFR-AV-01, NFR-AV-02 | Predicate and read wrap IO errors: a missing root, a vanished file or a permission error yields `false` / 404 page plus a warning on `SlpModularCms.Website`. No exception reaches the pipeline. |
|
||||
| P4 | Bounded work per request | NFR-PF-01 | Resolution order is fixed so at most 3 predicate calls happen: (1) `<name>.html`, (2) the literal file for extension paths or `<name>/index.html`, (3) `404.html` for the final stage. Asserted with a counting predicate. |
|
||||
| P5 | Website-scope header forcing | R19, Q1 = A | `SecurityHeaderWriter.Apply` gets an extra parameter `alwaysSendDocumentHeaders`. `SecurityHeadersMiddleware` sets it true when `WebsiteMode` is `PrerenderedPages` and `PathString` is not reserved (`WebsitePathResolver.IsReservedPath`). Then CSP, X-Frame-Options and Referrer-Policy go on every website response whatever its content type (asset, 301, 404, robots.txt). API and admin keep the content-type rule. Default of the new parameter is false, so existing callers and tests are unchanged. |
|
||||
| P6 | Configuration-driven logging | NFR-OB-01..04 | A single `ILogger` with category `SlpModularCms.Website`; levels from `Logging:LogLevel` per environment. Path values are sanitised by a small helper before logging. |
|
||||
| P7 | Secure defaults | Security Baseline | `WebsiteMode.SpaFallback`, empty site origin lists and `NoIndex = false` reproduce today's behaviour; startup validation rejects invalid origins and unknown policy names. |
|
||||
| P8 | Single registration point | NFR-MT-01 | `AddCmsWebsite` / `UseCmsPrerenderedSite` own compression, noindex and the middleware; `CmsHost` only calls them when the mode asks for it, keeping `SpaFallback` untouched. |
|
||||
| P9 | Compression scoping | NFR-CP-01..03 | `UseWhen(path is not reserved)` around `UseResponseCompression`; gzip provider only, MIME list from the requirements. |
|
||||
|
||||
## Pipeline placement
|
||||
Security headers stay first (inside the exception handler). The website stage sits where `UseCmsStaticContent` is today, the 404 stage after `MapSentryTunnel`, replacing the catch-all website fallback in this mode.
|
||||
|
||||
## Behind the proxy Pi
|
||||
The proxy forwards plain HTTP/1.0 to the app port. `UseHttpsRedirection` finds no HTTPS port and does nothing; website redirects are relative (`Location: /over-mij`), so no scheme or host is ever constructed. HSTS is still sent by the host (non-Development), as nginx does.
|
||||
|
||||
## Open verification items (settled by tests in Code Generation)
|
||||
1. No HTTPS-redirect loop or absolute `http://` redirect with a plain HTTP request.
|
||||
2. Rate limiter default policy does not throttle website assets (check `AddCmsRateLimiting`).
|
||||
3. `HEAD` requests behave like `GET` without body.
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
# NFR Requirements - core-site-hosting (U1)
|
||||
|
||||
## Scalability
|
||||
- NFR-SC-01: one small site on one Raspberry Pi behind the proxy Pi; tens of requests per second at most. No horizontal scaling, no shared state, no cache to invalidate.
|
||||
|
||||
## Performance
|
||||
- NFR-PF-01: a `Resolve` call performs at most **3** file-exists checks (Q3 = A). Asserted by a test with a counting predicate.
|
||||
- NFR-PF-02: a simple local timing check (resolve + serve a page, many iterations) is run once and recorded in the hand-back note. No hard SLA; the goal is to show no per-request cost worth caching.
|
||||
- NFR-PF-03: static files are streamed (no full buffering); response compression applies only to the listed text types.
|
||||
- NFR-PF-04: no load test in U1. (A load test on the Pi was not chosen.)
|
||||
|
||||
## Compression
|
||||
- NFR-CP-01: **gzip only**, like nginx today (Q1 = A). No Brotli provider is registered.
|
||||
- NFR-CP-02: types: html, js, css, svg, json, xml, txt; `Vary: Accept-Encoding`; non-reserved paths only.
|
||||
- NFR-CP-03: compression stays at the ASP.NET default of "not over HTTPS"; the proxy Pi forwards plain HTTP so it applies in practice.
|
||||
|
||||
## Availability and reliability
|
||||
- NFR-AV-01: a missing or half-delivered `wwwroot/web` never stops the host: website paths answer 404, API and admin keep working.
|
||||
- NFR-AV-02: no restart needed after a website delivery (per-request file checks, no cache).
|
||||
- NFR-AV-03: the resolver is total (never throws); file read errors in the middleware become a 404 page plus a warning.
|
||||
- NFR-AV-04: existing clients (`Api`, `Api.SlpSoftware`) behave exactly as today; their tests stay green.
|
||||
|
||||
## Observability (Q2)
|
||||
Bryan: "Alleen waarschuwingen en meer op de pi, op productie later bepalen". Implementation:
|
||||
- NFR-OB-01: the website serving uses a dedicated logger category (`SlpModularCms.Website`).
|
||||
- NFR-OB-02: 404s and 301s are logged at **Information** on that category; warnings for read errors and a missing `wwwroot/web`.
|
||||
- NFR-OB-03: levels come from per-environment appsettings: test sets `Information` for that category; default and production stay `Warning`. Production is a later config change, no code change.
|
||||
- NFR-OB-04: logs contain the sanitised path (control characters removed, length capped), never headers or cookies.
|
||||
|
||||
## Security (Security Baseline, blocking)
|
||||
| Item | Status |
|
||||
|---|---|
|
||||
| Input validation (path traversal, encoded/backslash/NUL, over-long, open redirect) | Compliant by design: single pure function, property-tested (R2-R4, R12) |
|
||||
| Dotfile exposure | Compliant: R3 refuses dot segments except `.well-known` |
|
||||
| Secure defaults | Compliant: new settings default to today's behaviour |
|
||||
| Security headers on every website response | Compliant by R19, tested on page, asset, 301, 404, robots.txt |
|
||||
| Log injection | Compliant: NFR-OB-04 |
|
||||
| Secrets in code or config | N/A for U1 (no secrets); setup token is U2 |
|
||||
| New dependencies | None in production code |
|
||||
| Authn/authz | N/A for U1 (public static content); API and admin unchanged |
|
||||
| Rate limiting | Unchanged; website static serving is not limited (same as nginx today) |
|
||||
|
||||
## Maintainability and testing
|
||||
- NFR-MT-01: all nginx-parity rules in one pure class; the middleware is a thin adapter.
|
||||
- NFR-MT-02: tests: unit tests per rule R1-R26, integration tests (`WebApplicationFactory`-style) for headers on all response kinds, regression suites of `Api` and `Api.SlpSoftware`.
|
||||
- NFR-MT-03: docs updated (`WEBSITE_WORKSPACE.md`, `README.md`).
|
||||
|
||||
## Property-based testing (partial: PBT-02, 03, 07, 08, 09)
|
||||
- PBT-02: policy round trip (configured origins appear in the built CSP and parse back).
|
||||
- PBT-03: resolver invariants (never throws; `ServeFile` safe paths; `Redirect` targets safe, never end in `/` except `/`, resolving a target never redirects again).
|
||||
- PBT-07: generators for paths (unicode, encoded, dots, slashes, case variants) kept in a shared test helper.
|
||||
- PBT-08: failing seeds are printed and a shrunk counterexample is added as a regular unit test.
|
||||
- PBT-09: a PBT framework is required; see tech-stack-decisions.md.
|
||||
|
||||
## Usability
|
||||
- N/A (no UI in U1).
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
# Tech Stack Decisions - core-site-hosting (U1)
|
||||
|
||||
| # | Decision | Rationale |
|
||||
|---|---|---|
|
||||
| T1 | ASP.NET Core built-in `UseResponseCompression` with gzip provider only | Matches nginx; no new package; Q1 = A |
|
||||
| T2 | Built-in `IFileProvider` (physical, confined to `wwwroot/web`) for the file-exists predicate and streaming | No new package; traversal confinement is a second line of defence behind the resolver |
|
||||
| T3 | `ILogger` with category `SlpModularCms.Website`, level via `Logging:LogLevel` in appsettings per environment | Q2; production later = config only |
|
||||
| T4 | Test-only PBT framework **FsCheck.Xunit** (not currently in the repo) added to the Core test project | PBT-09 requires a framework; FsCheck is the standard for xUnit on .NET and is a test-only dependency (no production impact). Version pinned at code generation to a release older than two weeks |
|
||||
| T5 | `WebApplicationFactory`-based integration tests (or the existing test host pattern used by `Api` tests) | Verify headers and pipeline order end to end |
|
||||
| T6 | No new production NuGet packages | Smaller supply-chain surface (Security Baseline) |
|
||||
|
||||
**Flag for approval**: T4 adds a new test dependency; if you prefer a different PBT library, say so now.
|
||||
Reference in New Issue
Block a user