6.1 KiB
6.1 KiB
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. |