Files
slp-modular-cms/aidlc-docs/features/hero-module/inception/application-design/services.md
T

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, HeroPreloadMarkerProvider Write the region and the preload 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:

  1. Reject early (size, real format, pixel count, frame count, timeout); a rejection is a clear 400 and nothing is stored.
  2. Write to a temporary location first; only a completely processed set is made visible (one move per set). A failure removes the partial files.
  3. The set hash is computed from the original's SHA-256 and the crop parameters; the variant addresses contain it.
  4. 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["HeroPreloadMarkerProvider<br/>(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 ITextCatalog with HeroTexts keys (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/UpdatedAt on the hero and CreatedAt plus 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.