Media processing: failure is a first-class state #168

New issue

Closed

opened 2026-08-09 19:49:13 +00:00 by rosa · 0 comments

rosa commented

2026-08-09 19:49:13 +00:00

Owner

Part of the "defer media processing to a background job" spec (PR #165; ADR-0020).
Completes the deferred pipeline by making failure a first-class outcome rather than
an endlessly-retried job.

What to build

Have the optimize_media job classify its failures and drive the Media to a
terminal Failed state where appropriate.

A permanent failure — bytes that passed the request-path magic-byte sniff but
are undecodable, a decompression bomb over the decode bound, anything outside the
allowlist — marks the Media Failed, deletes the staged original, and does not
retry (maps to the terminal Error::Abort classification). A transient failure
— out of memory under load, a full disk — retries with backoff a bounded number of
times (maps to the retryable Error::Failed), and once retries are exhausted the
Media falls to Failed.

Because the upload was fire-and-forget, a Failed Media is surfaced on its author's
own views rather than left to render as a silently broken image. (A dedicated
notification channel beyond surfacing the status is out of scope — spec.)

Acceptance criteria

Undecodable / decompression-bomb / off-allowlist input in the job marks the Media Failed with no retry and deletes the staged original.
A transient failure retries with backoff and, once exhausted, leaves the Media Failed.
The permanent/transient split maps onto the existing terminal-vs-retryable job classification.
A Failed Media is visible as Failed on its author's own views.
GET /media/{id} returns 404 for a Failed Media, and its Photo stays omitted from page and feeds.
Job-handler tests assert the classification directly: a bomb/undecodable/off-allowlist input yields the terminal outcome and a Failed Media with the staged file gone; a transient failure yields the retryable outcome.

Blocked by

#167

Part of the "defer media processing to a background job" spec (PR #165; ADR-0020). Completes the deferred pipeline by making failure a first-class outcome rather than an endlessly-retried job. ## What to build Have the `optimize_media` job classify its failures and drive the Media to a terminal **Failed** state where appropriate. A **permanent** failure — bytes that passed the request-path magic-byte sniff but are undecodable, a decompression bomb over the decode bound, anything outside the allowlist — marks the Media **Failed**, deletes the staged original, and does not retry (maps to the terminal `Error::Abort` classification). A **transient** failure — out of memory under load, a full disk — retries with backoff a bounded number of times (maps to the retryable `Error::Failed`), and once retries are exhausted the Media falls to Failed. Because the upload was fire-and-forget, a Failed Media is surfaced on its author's own views rather than left to render as a silently broken image. (A dedicated notification channel beyond surfacing the status is out of scope — spec.) ## Acceptance criteria - [ ] Undecodable / decompression-bomb / off-allowlist input in the job marks the Media Failed with no retry and deletes the staged original. - [ ] A transient failure retries with backoff and, once exhausted, leaves the Media Failed. - [ ] The permanent/transient split maps onto the existing terminal-vs-retryable job classification. - [ ] A Failed Media is visible as Failed on its author's own views. - [ ] `GET /media/{id}` returns 404 for a Failed Media, and its Photo stays omitted from page and feeds. - [ ] Job-handler tests assert the classification directly: a bomb/undecodable/off-allowlist input yields the terminal outcome and a Failed Media with the staged file gone; a transient failure yields the retryable outcome. ## Blocked by - #167

rosa added the

workflow

ready-for-agent

label

2026-08-09 19:49:22 +00:00

rosa referenced this issue from a commit

2026-08-09 22:15:53 +00:00

feat: make media-processing failure a terminal state

rosa referenced this issue from a commit

2026-08-09 23:54:10 +00:00

feat: make media-processing failure a terminal state

rosa closed this issue