Hero-module: Functional Design, NFR Requirements, NFR Design en Infrastructure Design (H1-H5)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 15:09:40 +01:00
co-authored by Claude Sonnet 5.5
parent 5f6d2b4bd2
commit 259d48bd9c
10 changed files with 455 additions and 5 deletions
@@ -0,0 +1,68 @@
# NFR Requirements: hero-module (units H1, H3, H4; applies to H2 and H5 where noted)
Derived from `requirements.md` section 5, the security extension (blocking), the functional design and the library proof. Bryan approved the library, the defaults and the safety approach on 2026-11-16.
## Performance
| ID | Requirement | Measure |
|---|---|---|
| P-01 | **LCP**: the LCP element is in the first HTML and does not regress against the baked version: ASF the first slide `<picture>` with `fetchpriority="high"`, `width`/`height`, and the matching preload; SLS the title text. | Lighthouse (lab) on the test hosts before and after, mobile profile: LCP not worse than the baked page; no layout shift from the hero (CLS contribution 0). |
| P-02 | **Weight**: the first slide image sent to a phone is the `tall` variant; target at most 80 KB WebP at 960 wide for a photo like the ASF ones (measured 37 to 64 KB), at most 250 KB for the largest desktop variant. | Recorded in the build and test summary. |
| P-03 | **Processing time**: an upload of a 10 MB photo is processed (all sets) within 10 seconds on the Pi and 5 seconds on a workstation; the request does not time out. | Timed in the integration test and on the test host. |
| P-04 | **Page build**: the hero adds at most 5 ms (cached) to building an injected page; the 60-second cache and ETag/304 behaviour stay as for the other parts. | Unit and integration tests. |
| P-05 | **Media serving**: a media file answers from disk with a strong ETag and 304; no processing on the request path. | Integration test. |
## Scalability and capacity
| ID | Requirement |
|---|---|
| S-01 | Expected size: one hero per site, tens of slides at most, a few uploads per day; the design must stay correct under concurrent uploads (processing gate) but is not built for throughput. |
| S-02 | Disk: the media directory is limited by `Media:MaxTotalBytes` (2 GB default); uploads refused with a generic message above it; free space checked before writing. |
| S-03 | The data block and the hero JSON are bounded by `Hero:MaxPublishedSlides` (50): the first HTML does not grow without bound. |
## Reliability and availability
| ID | Requirement |
|---|---|
| R-01 | Page injection is fail-open per part; a failing media directory, library or database read never takes a page down. |
| R-02 | Uploads fail closed with a stable code and a generic message; nothing partial is visible (atomic set writes); a crash during processing leaves no referenced half-set. |
| R-03 | Start-up self-test of the image library and a writability check of the media directory; when they fail, uploads answer 503 and a clear error is logged; public reads continue. |
| R-04 | Orphan clean-up never deletes referenced files and tolerates being interrupted (idempotent, daily). |
| R-05 | A restart or deploy keeps all images (directory outside the release) and the metadata (database). |
## Security (blocking, extension enabled)
| ID | Requirement | Rule |
|---|---|---|
| SEC-01 | Upload hardening: size limit at framework level, signature allow-list, library decode with explicit format and resource limits (pixels, side length, memory, time), parallelism gate, per-user rate limit, no client file names in paths, no SVG. | SECURITY-05, 11 |
| SEC-02 | Management endpoints require `AdminOnly` server side; object ids are verified against the hero; the public endpoints expose only published data. | SECURITY-08 |
| SEC-03 | Output encoding: all text encoded for HTML and for JSON in script; the button target allow-list prevents `javascript:` and other schemes; the media endpoint only serves registered path patterns; `X-Content-Type-Options: nosniff`. | SECURITY-04, 05 |
| SEC-04 | Generic error responses; no stack traces or paths; the global handler stays. | SECURITY-09, 15 |
| SEC-05 | Logging with request id and actor, no file contents and no client file names; changes auditable (who, what, when). | SECURITY-03, 13 |
| SEC-06 | Dependencies pinned and scanned: `Magick.NET-Q8-AnyCPU` 15.1.0 (Apache-2.0) is added to the vulnerability scan; the package is kept current; no unused packages. | SECURITY-10 |
| SEC-07 | Rate limiting on `hero-public`, `media-public` and `hero-upload`; abuse cases covered by tests (oversized, decompression bomb, polyglot, path tricks, repeated uploads). | SECURITY-11 |
| SEC-08 | Media directory permissions: only the host's service account writes; no directory listing; files are never executed (no handler mapping in IIS for the media directory when it lives under a web root; it lives outside the web root). | SECURITY-09 |
## Maintainability and testability
| ID | Requirement |
|---|---|
| M-01 | The image library only behind `IImageProcessor`; the store only behind `IMediaStore`; both replaceable. |
| M-02 | Pure functions (`FocusMath`, `VariantPlanner`, `MediaPaths`, `ButtonTargetValidator`, `HeroPictureRenderer`) property-tested (extension partial): crop inside the image; widths monotonic and never above the source; the set hash changes iff the crop parameters change; targets accepted are of the three forms; encoded text round-trips; the first slide and the preload attributes equal the picture attributes. |
| M-03 | Golden files for the region and the preload (ASF), for the data block and for the Offerings output stay byte-exact. |
| M-04 | Image fixtures for each input format, including corrupt, truncated, oversized and polyglot files; a real HEIC photo is added when one can be obtained (HEIC is a declared capability only until then, per Bryan). |
| M-05 | Texts per `docs/translation-files.md`; OpenAPI snapshot regenerated. |
## Usability and accessibility
| ID | Requirement |
|---|---|
| U-01 | Admin: keyboard operation of reorder and focus point, labels, live regions, a clear badge; the server messages in Dutch. |
| U-02 | Sites: alt text required (or decorative), slider accessibility kept in the site (contract). |
## Compatibility
| ID | Requirement |
|---|---|
| C-01 | The existing public contracts and markers do not change; the Offerings data block output is byte-identical. |
| C-02 | Platforms: win-x64 self-contained (IIS), linux-x64 (CI), linux-arm64 (Pi); proven on the first two, confirmed on the Pi at the first test deploy by the start-up self-test. |