99 lines
5.8 KiB
Markdown
99 lines
5.8 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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 `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.
|