GRI-2127: background conversion for PDF/PPTX uploads, with job progress #264

Merged
vivy merged 3 commits from feature/GRI-2127-background-conversion-progress into dev 2026-11-16 02:57:37 +00:00
Member

Server side of forge #263 (part 2 of #233), GRI-2127.

Problem

An 83-slide PPTX converted inside the upload request, which could take
more than five minutes on the test server — long enough for a browser or
server timeout to cut the upload before it ever got an answer.

What changed

A .pdf/.pptx upload now stores the original file and answers
immediately with a placeholder media row and a queued job. Conversion
runs afterwards in a background task. Images, videos and URL items are
unaffected — still synchronous, same as before.

Contract (for #233's panel side to poll)

POST /media with a .pdf or .pptx: 201, body is still an array (for
consistency with every other upload), with exactly one item:

[{ "id": "...", "kind": "document", "job_state": "queued", ... }]
  • kind is "document" for a .pdf (its final kind is always document,
    only pdf_pages is still unknown) or "pending" for a .pptx (not known
    yet whether it becomes video or document).
  • job_state is only present in this upload response, always "queued".
    It is not present on GET /media list items — poll the job endpoint for
    progress, not the catalog.

GET /media/{media_id}/job:

{
  "media_id": "...",
  "state": "queued | converting | rendering | encoding | done | failed",
  "page": 3,
  "page_total": 10,
  "error_step": null,
  "error_message": null
}
  • page/page_total ("page N of M rendered") are set only while pages are
    being stored (the PDF render, or the .pptx slide-image fallback) — not
    during a .pptx's MP4 join, which has no page count.
  • error_step/error_message are set only once state == "failed".
  • 404 for media that does not exist, that the caller's campus may not
    see (same campus scoping as every other media endpoint — delete_media's
    may_access check), or that never had a job at all (an image, video, url
    upload, or a document's own page).
  • Once a job resolves (done or failed), GET /media reflects the final
    kind/pdf_pages/pages as usual.

Behaviour change on failure (AC-3-06 superseded)

A failed conversion — a corrupt PDF, a .pptx neither the render nor the
fallback can process — used to mean a clean upload refusal with no catalog
entry at all. That guarantee only held while conversion ran inside the
upload request; now nothing is waiting on the upload's answer, so the
failure shows up as job.state == "failed" with error_step and
error_message, and the placeholder row is left exactly as the upload
created it. plan/tests/mvp-acceptance.md's AC-3-03 and AC-3-06 wording
("at upload time", "the upload reports a clear error") describes the old
mechanism, not the new one — flagging this for the product manager/CTO to
update if they agree, rather than editing the acceptance doc myself.

Not in scope

Cancelling a running conversion, same as the issue says.

Tests

Written from "Done when", in their own commit before the implementation:

  • media_acceptance_integration.rs: rewrote AC-3-03 and AC-3-06 to poll
    the job instead of reading the upload response; AC-3-06 renamed and its
    doc comment explains the supersession.
  • pptx_video_acceptance_integration.rs: rewrote all four existing tests
    to poll the job; added the_upload_answers_before_the_conversion_finishes
    (a slow fake soffice proves the response lands well before the render
    does — the actual fix for forge #263) and
    a_successful_join_removes_the_orphaned_original_pptx_file (the
    placeholder's sha256 moves from the original to the video's; the
    original file must not be left behind — caught a real bug during review,
    fixed in the implementation commit).
  • media_integration.rs: updated the one PDF-upload test that asserted the
    old synchronous refusal.

Ran locally: cargo test -p server (full crate, DB-backed) and
scripts/local-gates.sh --rust-only (fmt, clippy, tests, cargo-deny) —
every gate passed. Forge CI runs the full gates again on this PR.

Follow-up for the product manager/CTO

  • plan/tests/mvp-acceptance.md AC-3-03/AC-3-06 wording describes the
    pre-GRI-2127 synchronous mechanism; worth a pass once this lands.
  • plan/server/media-pipeline.md's "Documents" section updated to describe
    the background job; not otherwise touched.
Server side of forge #263 (part 2 of #233), GRI-2127. ## Problem An 83-slide PPTX converted *inside* the upload request, which could take more than five minutes on the test server — long enough for a browser or server timeout to cut the upload before it ever got an answer. ## What changed A `.pdf`/`.pptx` upload now stores the original file and answers immediately with a placeholder `media` row and a `queued` job. Conversion runs afterwards in a background task. Images, videos and URL items are unaffected — still synchronous, same as before. ### Contract (for #233's panel side to poll) `POST /media` with a `.pdf` or `.pptx`: `201`, body is still an array (for consistency with every other upload), with exactly one item: ```json [{ "id": "...", "kind": "document", "job_state": "queued", ... }] ``` - `kind` is `"document"` for a `.pdf` (its final kind is always `document`, only `pdf_pages` is still unknown) or `"pending"` for a `.pptx` (not known yet whether it becomes `video` or `document`). - `job_state` is only present in this upload response, always `"queued"`. It is not present on `GET /media` list items — poll the job endpoint for progress, not the catalog. `GET /media/{media_id}/job`: ```json { "media_id": "...", "state": "queued | converting | rendering | encoding | done | failed", "page": 3, "page_total": 10, "error_step": null, "error_message": null } ``` - `page`/`page_total` ("page N of M rendered") are set only while pages are being stored (the PDF render, or the `.pptx` slide-image fallback) — not during a `.pptx`'s MP4 join, which has no page count. - `error_step`/`error_message` are set only once `state == "failed"`. - `404` for media that does not exist, that the caller's campus may not see (same campus scoping as every other media endpoint — `delete_media`'s `may_access` check), or that never had a job at all (an image, video, url upload, or a document's own page). - Once a job resolves (`done` or `failed`), `GET /media` reflects the final `kind`/`pdf_pages`/pages as usual. ### Behaviour change on failure (AC-3-06 superseded) A failed conversion — a corrupt PDF, a `.pptx` neither the render nor the fallback can process — used to mean a clean upload refusal with no catalog entry at all. That guarantee only held while conversion ran inside the upload request; now nothing is waiting on the upload's answer, so the failure shows up as `job.state == "failed"` with `error_step` and `error_message`, and the placeholder row is left exactly as the upload created it. `plan/tests/mvp-acceptance.md`'s AC-3-03 and AC-3-06 wording ("at upload time", "the upload reports a clear error") describes the old mechanism, not the new one — flagging this for the product manager/CTO to update if they agree, rather than editing the acceptance doc myself. ### Not in scope Cancelling a running conversion, same as the issue says. ## Tests Written from "Done when", in their own commit before the implementation: - `media_acceptance_integration.rs`: rewrote AC-3-03 and AC-3-06 to poll the job instead of reading the upload response; AC-3-06 renamed and its doc comment explains the supersession. - `pptx_video_acceptance_integration.rs`: rewrote all four existing tests to poll the job; added `the_upload_answers_before_the_conversion_finishes` (a slow fake `soffice` proves the response lands well before the render does — the actual fix for forge #263) and `a_successful_join_removes_the_orphaned_original_pptx_file` (the placeholder's `sha256` moves from the original to the video's; the original file must not be left behind — caught a real bug during review, fixed in the implementation commit). - `media_integration.rs`: updated the one PDF-upload test that asserted the old synchronous refusal. Ran locally: `cargo test -p server` (full crate, DB-backed) and `scripts/local-gates.sh --rust-only` (fmt, clippy, tests, cargo-deny) — every gate passed. Forge CI runs the full gates again on this PR. ## Follow-up for the product manager/CTO - `plan/tests/mvp-acceptance.md` AC-3-03/AC-3-06 wording describes the pre-GRI-2127 synchronous mechanism; worth a pass once this lands. - `plan/server/media-pipeline.md`'s "Documents" section updated to describe the background job; not otherwise touched.
Written from the issue's "Done when" before the implementation: a
.pdf/.pptx upload must answer once the file is stored, with a job the
caller polls for progress and failure, instead of blocking the request on
the conversion itself. Supersedes the old inline-conversion tests'
all-or-nothing assumption (AC-3-03, AC-3-06, and the pptx acceptance
suite), which only held while conversion ran inside the upload request.
GRI-2127: background conversion for PDF/PPTX uploads, with job progress
All checks were successful
CI / the pre-push hook (pull_request) Successful in 3s
CI / cargo fmt (pull_request) Successful in 5s
CI / install.sh client upgrade (pull_request) Successful in 8s
CI / cargo deny (pull_request) Successful in 14s
CI / cargo deny advisories (pull_request) Successful in 24s
CI / repository boundary (pull_request) Successful in 3s
CI / cargo clippy (pull_request) Successful in 58s
CI / frontend-web (pull_request) Successful in 1m5s
CI / cargo test (pull_request) Successful in 3m17s
CI / Notify gate failed (pull_request) Has been skipped
CI / CI (pull_request) Successful in 1s
3c54f7c3e4
An 83-slide PPTX converted inside the upload request could take more
than five minutes, long enough for a browser or server timeout to cut
the upload before it ever got an answer (forge #263, part 2 of #233).

A .pdf/.pptx upload now stores the original and answers immediately with
a placeholder media row and a queued job; conversion runs afterwards in a
spawned task. GET /media/{id}/job reports the job's state (queued /
converting / rendering / encoding / done / failed), page N of M once
known, and the failed step and error text. A .pptx's placeholder is
`kind = "pending"` until the job resolves it to video or document, since
which one it becomes isn't known until the render or its fallback runs.

A failed conversion now leaves the placeholder row and a failed job
rather than refusing the upload with no catalog entry at all (AC-3-06,
and the pptx "both paths missing" case): nothing is waiting on the
upload's answer any more, so there is no longer a clean-refusal moment
to report the failure at.
vivy requested changes 2026-11-16 02:21:04 +00:00
Dismissed
vivy left a comment

Review (Vivy). Contract is good and CI is green. One change before merge, one note.

Must fix — a restart strands every unfinished job. Nothing resumes or closes a job that is queued/converting/rendering/encoding when the process stops. media_jobs is only written by the task that tokio::spawn started, so after a restart or redeploy that row stays non-terminal for ever: the panel (#233) polls a spinner that never ends, and the pending media row can never be used or told apart from a live job. A redeploy during an 83-slide upload is the case this issue exists for.

Ask: at server start, before the router serves, one UPDATE media_jobs SET state='failed', page=NULL, page_total=NULL, error_step='interrupted', error_message='the server restarted during conversion; upload the file again', updated_at=now() WHERE state NOT IN ('done','failed'). Plus one test: insert a job in converting, run the startup sweep, GET /media/{id}/job reads failed / interrupted. Re-running the conversion from the stored original is nicer but not needed now.

Note, not blocking: there is no limit on concurrent conversions — five uploads start five renders at once. A Semaphore (config key, default 1–2) is a follow-up; say so on #263 if you do not do it here.

AC-3-03/AC-3-06 wording: agreed it describes the old mechanism; I will ask for the acceptance doc update separately.

Review (Vivy). Contract is good and CI is green. One change before merge, one note. **Must fix — a restart strands every unfinished job.** Nothing resumes or closes a job that is `queued`/`converting`/`rendering`/`encoding` when the process stops. `media_jobs` is only written by the task that `tokio::spawn` started, so after a restart or redeploy that row stays non-terminal for ever: the panel (#233) polls a spinner that never ends, and the `pending` media row can never be used or told apart from a live job. A redeploy during an 83-slide upload is the case this issue exists for. Ask: at server start, before the router serves, one `UPDATE media_jobs SET state='failed', page=NULL, page_total=NULL, error_step='interrupted', error_message='the server restarted during conversion; upload the file again', updated_at=now() WHERE state NOT IN ('done','failed')`. Plus one test: insert a job in `converting`, run the startup sweep, `GET /media/{id}/job` reads `failed` / `interrupted`. Re-running the conversion from the stored original is nicer but not needed now. **Note, not blocking:** there is no limit on concurrent conversions — five uploads start five renders at once. A `Semaphore` (config key, default 1–2) is a follow-up; say so on #263 if you do not do it here. AC-3-03/AC-3-06 wording: agreed it describes the old mechanism; I will ask for the acceptance doc update separately.
GRI-2127: fail background conversion jobs left non-terminal by a restart
All checks were successful
CI / the pre-push hook (pull_request) Successful in 5s
CI / cargo fmt (pull_request) Successful in 5s
CI / install.sh client upgrade (pull_request) Successful in 9s
CI / cargo deny (pull_request) Successful in 16s
CI / cargo deny advisories (pull_request) Successful in 15s
CI / repository boundary (pull_request) Successful in 5s
CI / cargo clippy (pull_request) Successful in 1m3s
CI / frontend-web (pull_request) Successful in 57s
CI / cargo test (pull_request) Successful in 3m59s
CI / Notify gate failed (pull_request) Has been skipped
CI / CI (pull_request) Successful in 1s
89cf8f8e78
A media_jobs row stuck in queued/converting/rendering/encoding by a crash
or redeploy had no task left to finish it, so the panel would poll
GET /media/{id}/job forever. recover_interrupted_jobs now runs once at
start-up, right after migrations, marking every such job failed with
error_step "interrupted".
Author
Member

Fixed per review (3c54f7c3): server::media::recover_interrupted_jobs runs once at start-up in main.rs, right after db::migrate and before the HTTP listener binds. It updates every media_jobs row not already done/failed to state = 'failed', error_step = 'interrupted', with an error message naming the restart — so a job the previous process left running (crash, redeploy, restart) resolves to a terminal state instead of spinning the panel forever.

Added an_interrupted_job_is_recovered_as_failed_at_start_up in media_integration.rs: inserts a job directly in converting state, calls the recovery function, and asserts the job endpoint reports failed/interrupted with a non-empty error message; a second case proves a done job is left untouched.

Concurrency limit left as the agreed follow-up, not in this PR.

cargo test -p server (serialized, --test-threads=1 — this build host's shared Postgres hits PoolTimedOut under the default parallel test threads from unrelated concurrent load, not from this change) and cargo fmt --check / cargo clippy -p server --all-targets -- -D warnings all green locally. Forge CI running on 89cf8f8.

Fixed per review (3c54f7c3): `server::media::recover_interrupted_jobs` runs once at start-up in `main.rs`, right after `db::migrate` and before the HTTP listener binds. It updates every `media_jobs` row not already `done`/`failed` to `state = 'failed'`, `error_step = 'interrupted'`, with an error message naming the restart — so a job the previous process left running (crash, redeploy, restart) resolves to a terminal state instead of spinning the panel forever. Added `an_interrupted_job_is_recovered_as_failed_at_start_up` in `media_integration.rs`: inserts a job directly in `converting` state, calls the recovery function, and asserts the job endpoint reports `failed`/`interrupted` with a non-empty error message; a second case proves a `done` job is left untouched. Concurrency limit left as the agreed follow-up, not in this PR. `cargo test -p server` (serialized, `--test-threads=1` — this build host's shared Postgres hits `PoolTimedOut` under the default parallel test threads from unrelated concurrent load, not from this change) and `cargo fmt --check` / `cargo clippy -p server --all-targets -- -D warnings` all green locally. Forge CI running on 89cf8f8.
vivy approved these changes 2026-11-16 02:57:34 +00:00
vivy left a comment

Fix verified on 89cf8f8e: fail_interrupted_jobs runs after migrations and before the listener binds, marks every queued/converting/rendering/encoding job failed with error_step = interrupted, and leaves done/failed rows alone; the test covers both. CI green on all 7 required contexts. Approving.

Note for later, not blocking: this assumes one server process per database. A second instance would fail the running jobs of the first at its start-up. Fine for the campus test.

Fix verified on 89cf8f8e: fail_interrupted_jobs runs after migrations and before the listener binds, marks every queued/converting/rendering/encoding job failed with error_step = interrupted, and leaves done/failed rows alone; the test covers both. CI green on all 7 required contexts. Approving. Note for later, not blocking: this assumes one server process per database. A second instance would fail the running jobs of the first at its start-up. Fine for the campus test.
vivy merged commit 13f1f05c56 into dev 2026-11-16 02:57:37 +00:00
vivy deleted branch feature/GRI-2127-background-conversion-progress 2026-11-16 02:57:37 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grimoirix/grimoire-of-digital-signage!264
No description provided.