Documentation

The terminal outcome of processing one mirror job, deciding whether the message is acked or left to redeliver.

Classify a mirror-artifact fetch fault into a terminal job outcome. An artifact over the plan-sized byte cap is a terminal, dead-lettered fault: it is deterministic in the artifact's own size, so a redelivery re-fetches the same over-cap bytes and fails identically, and it must not silently vanish -- it is handed to the backend's dead-letter terminus (see DeadLettered). Any other fetch fault (an unformable URL, a transport failure) is a transient retry, since a redelivery may succeed.

Process one mirror job end to end: probe the mirror target for the job's version (a confirmed-present version is acked outright, the duplicate-suppression short-circuit), then re-evaluate current policy, and only on a current admit fetch the artifact, verify it against the integrity digests of the artifact that re-evaluation re-admitted, and publish it to the mirror target. Returns the JobOutcome that decides ack vs. redeliver.

The presence probe exists for the enqueue-to-availability window: mirroring is demand-driven, so every public-leg admit of a still-unmirrored version enqueues its own job, and a fleet-wide install of a novel version enqueues many. Without the probe each duplicate pays a full artifact download and an integrity recompute before the publish discovers the version is already present (the idempotent already-present answer); with it, a duplicate costs one metadata round trip. The probe is an optimisation, never a gate: it skips only work whose publish would have been that no-op, so the policy re-evaluation below still guards every artifact that actually publishes.

The policy re-evaluation is the ingest-time gate. The version was gated at serve time, but the enqueue-to-process window is asynchronous and unbounded, so policy may have tightened toward deny since (a new denylist entry, a freshly-published advisory, a rule-config change). The worker re-runs the same rules the serve path gates with, over the version resolved through the same single-version fetch-and-project, so a now-denied version is dropped (acked, never published) rather than frozen into the rule-exempt trusted mirror store; a version the upstream has since withdrawn is likewise dropped, while metadata that cannot be re-fetched (or a rule that cannot be computed) leaves the job for redelivery. A current admit carries the re-admitted artifact's integrity digests to the tamper gate, so the fetched bytes are verified against the exact set the integrity floor cleared (the queue payload carries no digest at all): a tampered or corrupt artifact fails the job with no publish, since the mirror is later served without the rules.

The receipt handle is taken so a long publish can extendVisibility to hold the message before its window lapses.

The per-job domain span (the worker tracing port) wraps the whole probe → re-evaluate → fetch → verify → publish, projecting the terminal outcome onto the span so a refused or dropped job is explainable from the trace, and linking back to the request that enqueued the job through the trace context the job carries (jobTraceContext). The span body is discharged to IO through the unlift, so the loop's structured log lines still compose through the ambient katip context.

Process one received batch sequentially, so each job gets the full visibility budget rather than competing with its batch-mates for it. A batch is at most the queue's configured batch size (≤ 10), so sequential processing is a deliberate throughput-vs-budget choice, not a scaling bottleneck.

The liveness heartbeat advances after each completed job, not once for the whole batch, so the /livez staleness bound (workerHeartbeatStaleAfter) need only cover one job's worst case rather than a whole sequential batch of large-artifact publishes: a healthy worker mid-batch is not mistaken for a stalled one.

The visibility window one publish is given before its message could redeliver mid-write. Sized to comfortably cover a publish of the largest artifact the memory plan's fetch cap admits (the mirror-artifact tenant, at most 512 MiB at its ceiling): even over a slow mirror-target link (a conservative ~2 MiB/s floor) that uploads in well under this, so a successful publish never redelivers mid-flight. A failed publish does not wait this out -- the failure path resets the message to visible at once (see releaseForRetry) -- so the generous hold costs nothing on the retry path; this is the background worker's correct trade (never interrupt a slow success; retry latency on failure does not matter).

The liveness staleness bound (workerHeartbeatStaleAfter) is sized to exceed a fetch and a publish of this budget, so a healthy worker mid-publish is never read as stalled; Ecluse.Worker.LivenessSpec pins that relationship so the two constants cannot drift apart.