5.8 KiB
Services and orchestration: hero-module
Services
| Service | Responsibility | Collaborators |
|---|---|---|
HeroService (management) |
Reads and saves the hero: validates fields (lengths, button targets via ButtonTargetValidator, schedule order, slide count and order), writes the hero and slides in one transaction, calls the cache invalidation. |
IHeroRepository, ITextCatalog, IIndexHtmlCache |
HeroImageService |
The upload pipeline and focus changes (below). Owns the rule that every stored file belongs to exactly one image set. | IMediaUploadGuard, IImageProcessor, IMediaStore, IHeroImageRepository, IIndexHtmlCache |
PublicHeroService |
Builds the public read model from the stored hero: schedule and IsActive applied, inactive slides removed, variants that exist listed, the first-slide choice made once here. |
IHeroRepository, TimeProvider |
Core MediaEndpoint |
Serves stored variants; no knowledge of the Hero module. | IMediaStore |
Core CmsDataBlockTransform |
Composes the #cms-data block from all contributors. |
ICmsDataBlockContributor implementations |
HeroHtmlTransform |
Writes the hero region and the preload region from the same PublicHeroDto through HeroPictureRenderer. |
IPublicHeroService |
Orchestration
Upload of an image
sequenceDiagram
box rgba(246,224,94,0.4) Admin
participant A as Admin browser
end
box rgba(99,179,237,0.4) Host
participant C as HeroImagesController
participant S as HeroImageService
participant G as MediaUploadGuard
participant P as ImageProcessor
participant M as MediaStore
participant R as Repository
end
A->>C: POST image (multipart)
C->>S: UploadAsync(stream, length, actor)
S->>G: AdmitAsync (size, real format, bounds, timeout, gate)
G-->>S: ImageInfo or rejection
S->>M: Put original (set directory)
S->>P: Render variants per ratio and width
P-->>S: encoded files, metadata stripped
S->>M: Put variants
S->>R: Save HeroImage (hash, size, variants)
S-->>C: HeroImageDto
C-->>A: 201 with the image and its variants
Text alternative: the admin uploads; the service admits the file, stores the original, renders and stores the variants, saves the metadata, and returns the image with its variant addresses.
Rules of the pipeline:
- Reject early (size, real format, pixel count, frame count, timeout); a rejection is a clear 400 and nothing is stored.
- Write to a temporary location first; only a completely processed set is made visible (one move per set). A failure removes the partial files.
- The set hash is computed from the original's SHA-256 and the crop parameters; the variant addresses contain it.
- At most a few uploads are processed in parallel (gate); the rest wait or get 429.
Change of focus
SetFocusAsync validates the numbers (ranges), recomputes the set hash, renders the affected ratios again into the new set directory, saves the new addresses, then removes the old set directory (after the commit). A site that still holds the old data block keeps working until its cache expires (the old files go after a grace period, decided in Functional Design).
Publishing and live updates
flowchart LR
Save["PUT /hero or image change"] --> Repo["Repository (commit)"]
Repo --> Inval["IIndexHtmlCache.Invalidate()"]
Inval --> Cache["HtmlMarkerInjector cache dropped"]
Req["Next page request"] --> Inj["HtmlMarkerInjector"]
Inj --> T1["CmsDataBlockTransform<br/>(offerings, banners, hero)"]
Inj --> T2["HeroHtmlTransform<br/>(region + first slide)"]
Inj --> T3["HeroHtmlTransform<br/>(preload region, head)"]
T1 --> Pub["PublicHeroService"]
T2 --> Pub
T3 --> Pub
Api["GET /api/v1/hero"] --> Pub
classDef act fill:#FFA726,stroke:#E65100,color:#000;
classDef core fill:#BBDEFB,stroke:#1565C0,color:#000;
classDef mod fill:#9ae6b4,stroke:#2f855a,color:#000;
class Save,Req,Api act;
class Inval,Cache,Inj,T1 core;
class Repo,T2,T3,Pub mod;
Text alternative: a save commits and invalidates the page cache; the next page request rebuilds the page through the data block, region and preload, all reading the one public read model, which the public endpoint also uses.
Failure behaviour
| Where | Behaviour |
|---|---|
| Upload or processing fails | Fail closed: 4xx with a generic message, partial files removed, nothing published. |
PublicHeroService fails or finds no active hero |
Region, preload and hero key are left as baked (data block: hero is null; the site keeps the baked hero). The page is served. |
| A contributor fails | The data block is left as baked entirely. |
| Media file missing or unreadable | 404 for that address; the data block lists only variants that were stored. |
| Storage unwritable | Upload fails with a generic 503-style message and an error log; public reads are unaffected. |
Cross-cutting
- Texts: validation and rejection messages go through
ITextCatalogwithHeroTextskeys (hero.validation.*,hero.image.*); the technical rejection reason codes stay English constants. - Authorization: management routes
AdminOnly; public routes anonymous and marked[PublicSiteEndpoint]so they pass the availability gate. - Rate limiting: new policies
hero-public(120 per 60 s like offerings),media-public(high, per client address, allows the page's images),hero-upload(low, per user). - Logging: structured, with the request id, actor and image id; never file contents or file names from the client.
- Auditing:
UpdatedBy/UpdatedAton the hero andCreatedAtplus actor on images, plus a log line per change (who, what, when) for SECURITY-13. - Cache keys: the injector's per-file cache already keys by page; hero changes call
Invalidate()like offerings and banners do.