Files
slp-modular-cms/aidlc-docs/features/hero-module/construction/nfr-design/nfr-design-patterns.md
T

51 lines
5.2 KiB
Markdown

# NFR Design: patterns for the hero-module (H1, H3, H4)
Each NFR of `nfr-requirements.md` is mapped to a pattern and the component that carries it.
## Patterns
| Pattern | Applies to | Where it lives | Notes |
|---|---|---|---|
| **Defence in depth for uploads**: size gate, signature allow-list, library decode with resource limits, parallelism gate, per-user rate limit, timeout, rejection codes | SEC-01, SEC-07, R-02 | `IMediaUploadGuard` (Core.Media), `HeroImagesController` (size limit attribute and `hero-upload` policy) | Each layer rejects alone; no single check is the only protection. A counting stream enforces the byte limit even when the declared length lies. |
| **Resource limits in the library**: `ResourceLimits.Width/Height/Area/Memory/Time` set once at start-up from `Media:*` options | SEC-01, P-03 | `MagickImageProcessor` initialisation | Process-wide limits, not per call; documented because Magick's limits are global. Format policy: decode only the allow-listed formats by passing the explicit `MagickFormat` after the signature check. |
| **Bulkhead**: a semaphore with `MaxParallelJobs` slots and a short wait; when full the answer is `busy` (429) | SEC-01, S-01 | `MediaProcessingGate` | Protects the host's CPU and memory on the Pi. |
| **Atomic publish of a set**: write to a temp directory, then one rename into place; clean the temp on failure (`try/finally`) | R-02, BR-M03 | `FileSystemMediaStore.PutSetAsync` | Nothing half-written is ever addressable. |
| **Content-addressed, immutable addresses** | P-05, FR-14 | `MediaPaths` | The set hash contains the original's SHA-256 and the crop parameters; a change gives a new address; long immutable caching is safe. |
| **Retire, then delete** (grace of 7 days) | R-04, BR-I08 | `HeroMediaCleanupService` (hosted, daily) | Sets are stamped when they stop being referenced; deleted later; idempotent; never deletes a referenced key (checked against the database right before deleting). |
| **Single read model** | NFR-09, BR-P04 | `PublicHeroService` | The endpoint, the region, the preload and the data block cannot disagree. |
| **One renderer for picture and preload** | P-01, BR-J01 | `HeroPictureRenderer` | Same inputs and the same formatting functions produce `srcset`, `sizes`, `media`; golden-tested. |
| **Fail-open injection, fail-closed upload** | R-01, R-02 | transforms catch and log; upload throws typed rejections | Documented deliberate asymmetry (SECURITY-15). |
| **Composable data block** | C-01 | `CmsDataBlockTransform` + contributors | Output of Offerings unchanged; contributors ordered by `Order`; a throwing contributor leaves the block baked. |
| **Self-test and capability reporting** | R-03, C-02 | `ImageProcessorSelfTest` hosted service; `GET /api/v1/System/capabilities` lists the accepted input formats | A failed self-test disables uploads only. |
| **Start-up directory check** | R-03, BR-M04 | `MediaDirectoryCheck` hosted service | Creates the directory when missing (when permitted), writes and deletes a probe file; logs the result; a failed check disables uploads. |
| **Output encoding at the edge** | SEC-03, BR-H08 | `HeroPictureRenderer` and the data contributor | Text stored as typed, encoded when written; the JSON for the script element uses the existing `HtmlMarkerEditor.EscapeForScript`. |
| **Allow-listed addresses** | SEC-03, BR-M01 | `MediaPaths.TryParse` and the endpoint's area registry | Anything else is a 404. |
| **Audit trail** | SEC-05 | `HeroService`, `HeroImageService` | Log line per change with actor, entity and id (no content), plus `UpdatedBy`/`CreatedBy` columns. |
| **Rate-limit policies** | SEC-07 | `ServiceCollectionExtensions` of the module and Core | `hero-public` 120/60 s per client address, `media-public` 600/60 s, `hero-upload` 20 per hour per user. |
## Logical components added by this stage
| Component | Role |
|---|---|
| `MagickImageProcessor` | The `IImageProcessor` implementation (sets limits, decodes, crops, resizes, strips, encodes) |
| `MediaProcessingGate` | The bulkhead |
| `ImageProcessorSelfTest` | Hosted self-test and capability list |
| `MediaDirectoryCheck` | Hosted start-up check of the directory |
| `HeroMediaCleanupService` | Daily clean-up of retired files |
| `MediaAreaRegistry` | The allow-list of media areas and their path patterns (`hero`) |
## Security compliance summary (this stage)
| Rule | Status | Evidence |
|---|---|---|
| SECURITY-03 | Compliant (design) | structured logs with request id and actor, no contents or client names |
| SECURITY-04 | Compliant | `nosniff` on media; existing headers on pages |
| SECURITY-05 | Compliant | validation of every field, signature allow-list, target allow-list, encoding |
| SECURITY-08 | Compliant | `AdminOnly`, object checks, public endpoints expose published data only |
| SECURITY-09 | Compliant | generic errors, no listing, media outside the web root |
| SECURITY-10 | Compliant | pinned package, vulnerability scan covers it |
| SECURITY-11 | Compliant | rate limits, gate, abuse cases listed in the tests |
| SECURITY-13 | Compliant | audit logs and columns; no unsafe deserialization (typed JSON only) |
| SECURITY-15 | Compliant | explicit error handling, global handler, deliberate fail-open and fail-closed split |
| SECURITY-01, 02, 06, 07, 12, 14 | N/A | no new infrastructure or authentication |