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

5.2 KiB

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