Short answer: generate a shipment video's poster once, after upload and before publication, when moderation must cover every image customers can see. Store that approved result as an immutable static asset. Per-view derivation postpones work, but it also creates more chances for an unreviewed frame, a timeout, or a policy change to alter a tracking page. The decisive metric is moderation coverage, not the transform's unit price.
| Strategy | Moderation boundary | Request-path work | Pick this when | Main risk |
|---|---|---|---|---|
| Publish-time | Poster is checked before release | Static read | One poster serves many public views | Publication waits for processing |
| First-view | A miss starts derivation and review | Cache miss plus job | Access is sparse and visibility stays closed | The first request creates a race |
| Every-view | Every response repeats enforcement | Decode, select, encode, check | The frame truly varies by request | Coverage relies on every request path |
That is the field guide. A driver may upload a proof-of-condition video once, while customers open its shipment page many times. Ask where a visible image can enter the system without passing the same release gate.
Should you derive a poster at publish or on every page view?
A poster is its own published artifact. Calling it a by-product of playback hides a state transition: pixels become a durable preview on lists, notifications, and tracking pages. The poster therefore needs an explicit relationship to its source revision, moderation result, and policy revision.
Publish-time generation makes that relationship auditable. The video begins non-public. A worker selects the intended frame, applies orientation and dimensions, encodes it, and sends that exact output through moderation. Publication becomes eligible only when the approved record and bytes both exist. No page-view handler improvises.
Coverage is measurable. For every public video, require exactly one referenced poster revision with an approval decision. Count missing links and records where approval names an older revision. Those are release-integrity signals. Alert on them before average transform latency.
Measure both.
Per-view generation moves the boundary into a busier place. A cache helps repeated reads, but a cache is not an approval record. If a miss can produce new pixels, the result must remain private while review is pending or unavailable. Otherwise moderation quietly becomes best effort.
This is the trap.
Pick publish-time derivation for public shipment pages
Choose this path when many viewers see the same poster and publication can wait. It concentrates decoding, encoding, and moderation into one workflow per revision. Delivery becomes an ordinary static read, so traffic doesn't multiply transform work.
The before and after are crisp. Before release, the system may retry jobs and expose progress only to authorized operators. After release, the customer path reads a specific approved object. A retry must be idempotent: the same source revision and transform specification converge on the same logical poster rather than append another public candidate.
Use an immutable object key or equivalent version identity. Mutable bytes under a stable public identity can separate the delivered image from the decision that authorized it. If cropping or frame selection changes, create revision B, moderate it, switch the reference atomically, and retain or retire revision A according to policy.
Publication does take longer. That's an honest trade. Upload acknowledgment and public visibility needn't be the same event: accept the upload, show processing state to the operator, and release the media only after the gate completes.
Pick first-view work only behind a closed gate
First-view generation can fit private previews, sparse archives, or videos that may never be opened. It avoids deriving unused posters. Yet the first customer request shouldn't become both a production job and an authorization decision. Keep the reference closed until the candidate has an approval record; use a previously approved neutral placeholder while work is pending if the product supports that behavior.
The 5-part cache key must include every input that changes pixels or policy meaning: source revision, frame-selection rule, crop dimensions, output format, and moderation-policy revision. Miss one and a subtle mismatch appears. The cache says hit while the governance record describes another artifact.
Every-view derivation is narrower. It fits a frame that genuinely varies by request and can be reviewed for each distinct output. A normal tracking thumbnail rarely has that property. Repeated processing is only the visible drawback; moderation availability also joins the synchronous page dependency chain.
Implement one observable release state machine
The boundary needs explicit states and one rule: only an approved poster revision can make a video public.
type PosterState =
| { kind: "uploaded"; sourceRevision: string }
| { kind: "deriving"; sourceRevision: string; attempt: number }
| { kind: "awaiting_review"; sourceRevision: string; posterRevision: string }
| {
kind: "approved";
sourceRevision: string;
posterRevision: string;
policyRevision: string;
objectKey: string;
}
| { kind: "rejected"; sourceRevision: string; posterRevision: string };
function releasePoster(state: PosterState) {
if (state.kind !== "approved") {
throw new Error("Poster is not eligible for public release");
}
return { objectKey: state.objectKey, revision: state.posterRevision };
}
Keep the worker and handler boring. The worker advances state; the delivery handler never generates media. In words: uploaded video -> deterministic transform -> candidate poster -> moderation decision -> atomic public reference. Rejection exits to an operator-visible state, not delivery.
Emit events at transitions, not only exceptions. Useful dimensions include source revision, poster revision, policy revision, outcome, and attempt count. Keep customer identifiers and raw media URLs out of metric labels. Logs can carry correlation identifiers; bounded metrics should answer how many public videos lack approval, how long candidates await review, and how often jobs retry.
Deployment tests should force awkward ordering. Publish while derivation is pending. Run the same job twice. Approve revision A while B is created. Change policy before a cached candidate is released. The invariant stays simple: the public reference resolves only to the exact revision named by an approval record.
Image format is a separate delivery decision. Browser support, transparency, animation, and compression behavior differ among formats. Select formats only after defining which outputs receive review. If two encodings can change visible pixels, record them as derivatives instead of assuming one approval transfers invisibly.
Test the gate, then watch the denominator
Use fixtures for landscape and portrait video, rotation metadata, a very short clip, and a source whose selected frame is rejected. This is not a universal benchmark. It proves each outcome reaches its intended state and no failure path opens publication.
Track coverage as a ratio with an explicit denominator: public videos that require posters. The numerator is the subset whose current poster revision has approval under the required policy. A worker can report a high success rate while coverage remains poor because older public records were never processed. Report both.
Split latency into queue wait, derivation, moderation wait, and commit time. A slow release then remains diagnosable without encouraging a shortcut around review. Measure static delivery separately from the publication pipeline; combining them produces an average that describes neither experience.
Publish-time work has limits. It doesn't make moderation infallible, and it cannot choose the best representation of damaged freight without an explicit frame policy. A transform or policy change may also require reprocessing. Handle that as a controlled migration: generate a revision, review it, then switch the reference.
Keep the gate closed.
The decision rule is concise. If a stable poster will be public and moderation must cover every visible derivative, create and approve it before release. Use first-view work for sparse access only while visibility remains closed. Reserve every-view generation for outputs that truly vary per request and can carry equivalent enforcement on every path.
Top comments (0)