8.1 KiB
Functional Design: business logic model (units H1 to H5)
Bundled for all units; answers of Bryan (2026-11-16) are applied. Names refer to application-design/. HTML for the region and preload is defined by the ASF golden files (web/contract/host-injection/hero/, commit 13f78c4), which are authoritative.
H1. Image pipeline
Upload admission (IMediaUploadGuard.AdmitAsync)
- Reject at once when the declared length is above the maximum (10 MB) or the stream turns out longer (read through a counting stream, stop at the limit).
- Read the first bytes and decide the format from the signature, never from a name or
Content-Type: JPEG, PNG, GIF, BMP, TIFF (both byte orders), WebP (RIFF....WEBP), and the ISO-BMFF family for AVIF and HEIC/HEIF (ftypwith brandavif,avis,heic,heix,hevc,mif1,msf1). Anything else (SVG, PDF, executables, text) is rejected asunsupported_format. - Inspect through the library with an explicit format and resource limits: pixel size, frame count. Reject
too_many_pixels(above the pixel ceiling),corrupt(decode error),timeout. - Animated input (GIF, WebP, AVIF sequences) is reduced to the first frame.
- Wait for a free processing slot (at most
MaxParallelJobs); when none frees within a few seconds answerbusy(HTTP 429).
Render planning (pure)
For an image of W x H pixels, a ratio r = n:d, a focus setting (fx, fy, z) (centre 0.5, 0.5 and z = 1 by default; a ratio may have its own setting, otherwise the general one applies):
- The largest crop of ratio
rinside the image:cw0 x ch0(ifW/H > n/dthench0 = H,cw0 = ch0 * n / d, elsecw0 = W,ch0 = cw0 * d / n). - With zoom
z >= 1the crop iscw = cw0 / zbych = ch0 / z. - The crop is centred on the point
(fx * W, fy * H)and then moved the smallest amount needed to lie inside the image. So the subject stays as close to the centre of the crop as the image allows, and a crop never leaves the image. - Widths: from the configured steps for the ratio (
wide: 640, 960, 1280, 1600, 2560;tall: 480, 640, 960, 1280) keep those<= cw(never upscale). If none is<= cw, one variant atcwis made. The height isround(width * d / n). - Formats per width: WebP always; AVIF when the processor reports AVIF output; the page-critical HTML uses WebP only (contract).
- Quality: WebP 80, AVIF 50. Metadata is removed from every output; EXIF orientation is applied before cropping.
Set hash and addresses
setHash = first 16 hex characters of SHA-256 over the canonical string sha256-of-original | wide:fx,fy,z | tall:fx,fy,z (numbers rounded to 4 decimals, invariant culture). A change of focus therefore gives a new set and new addresses; an identical upload of the same photo with the same focus gives the same set (no second copy is stored). Variant file name: <ratio>-<width>.<ext> (wide-1600.webp, tall-960.avif); address /media/hero/<setHash>/<name>.
Self-test at start-up
The processor decodes and encodes a tiny embedded image in every supported format and logs the capability list (input and output formats, library version). A failure marks the processor unavailable: uploads answer 503 with a generic message; reading and publishing are unaffected.
H3. Media store and serving
- Keys: variants
hero/<setHash>/<ratio>-<width>.<ext>; originalsoriginals/<sha256>.<ext>(never served). Only keys made by the code exist; a client file name is never used in a path. - Write: a set is written to a temporary directory next to the target and moved into place with one rename; a half-written set is never visible.
- Serve
GET|HEAD /media/{**path}: the path must match^hero/[0-9a-f]{16}/(wide|tall)-[0-9]{2,5}\.(webp|avif|jpg)$(area pattern from a registered allow-list, so other areas can register their own); otherwise 404. Headers:Content-Typefrom the extension,Cache-Control: public, max-age=31536000, immutable, strongETag(from the set hash and name),X-Content-Type-Options: nosniff,Vary: Accept-Encodingnot needed (images are not recompressed).If-None-Matchequal gives 304. Rate limit policymedia-public. - Clean-up (hosted service, daily): removes sets and originals that no image row references and that are older than 7 days (a retired set is stamped when it stops being referenced; the files go 7 days later). Never removes a referenced file.
- Free space and size: before writing, check free space (at least the expected output plus a margin) and the total size of the media directory against the safety limit
Media:MaxTotalBytes; refuse with a generic message when exceeded.
H2. Hero backend
Save (PUT /api/v1/hero, whole hero replaced)
Input: hero fields, buttons, display, schedule, slide list in order (id optional for a new slide, imageId, alt, decorative, isActive). In one transaction: validate everything, update the hero, upsert slides, remove slides no longer listed, renumber the order, record actor and time. Afterwards IIndexHtmlCache.Invalidate().
Public read model (PublicHeroService.GetActiveAsync)
Returns null (204) when: no hero row for the language, IsActive false, now before StartsAt or at or after EndsAt, or the hero has no title. Otherwise: only active slides that have a stored image; a slide without alt that is not decorative is not published (the admin does not allow saving it anyway); order as saved. Each slide carries the general focus, plus the per-ratio overrides, and all stored variants (WebP and AVIF) with their ratio, width, type and address. The result is also what the HTML transform and the data block use, so the three always agree.
Image operations
- Upload (
POST /api/v1/hero/images): guard, store original, render the planned sets for the default focus, save the row, return the image with its variants. - Set focus (
PUT /api/v1/hero/images/{id}/focus): validate ranges (0..1, zoom1..4), compute the new set hash, render the sets into new addresses, update the row, stamp the old set as retired; the slides keep pointing at the same image id. - Delete (
DELETE /api/v1/hero/images/{id}): refused with 409 and a clear message while any slide uses the image (Bryan, Q1); otherwise the row goes and its set and original are stamped retired.
H4. Injection
Order of work for a page that mentions hero markers: get PublicHeroDto? once per request cycle; if null, leave regions and preload as baked (and the data block carries "hero": null); otherwise:
HERO-HTMLregion: exactly the ASF golden rules (title lines with<br>, tagline span, buttons, first kept slide as<picture>; slides skipped when they have no alt and are not decorative, a path outside our host, or no size; WebP only;object-positionfrom the focus of the ratio that theimgshows, i.e. the general focus).HERO-PRELOADregion in the head: one preload fortallwithmedia="(orientation: portrait)"and one forwidewithmedia="(orientation: landscape)"when both exist; one withoutmediawhen only one ratio exists;srcset,sizes,mediabyte-equal to the picture.- Data block: key
herowith the wholePublicHeroDto(all slides) in the shared block.
Fail-open: any exception, an unreadable hero or a missing marker leaves that part as baked; a failing data-block contributor leaves the whole block as baked.
Safety ceiling for unlimited slides (Bryan: no administrator limit, a technical ceiling only): the hero endpoint, the HTML transform and the data block never emit more than Hero:MaxPublishedSlides slides (default 50, configurable) so the first HTML and the data block cannot grow without bound; when a hero has more active slides the first 50 in order are published and the admin shows a notice. The ceiling is reported to Bryan; LCP and page weight stay leading (the first HTML contains only the first slide).
H5. Admin
Screens and states are in frontend-components.md; the admin only shows a live badge (Bryan, Q5): "Live" or "Niet live" with the schedule dates, no long reason text. Uploads are limited per user (20 per hour). Every validation message comes from the server (ProblemDetails-style error with a field) and is shown at the field.