House-move inventory: Slow PDFs as background jobs - Part 9
~8 min read
By the end of September the room PDF could do a lot: a summary page, every box's contents, each box's photo and each item's photo, then every invoice attachment merged on the end. It was also taking long enough that production started returning 504s - the reverse proxy gave up before the PDF finished.
This post is about the fix, and about a decision I'm glad I made: not putting it in the database.
First, the cheap fix (and why it wasn't enough)
The first reaction is to raise the timeout, and I did: deploy/nginx-inventory-system.conf got a proxy_read_timeout / proxy_send_timeout bump to ten minutes. But a request that holds a connection open for minutes is fragile in every way a phone user cares about: switch apps, lock the screen, lose signal, and the work is thrown away.
So the timeout stayed as defence in depth, and the real change was to stop building the PDF inside the request.
Queue, poll, fetch
Phase 3.33 turned the two slow exports - the room sheet, and the box sheet with ?invoices=true - into background jobs:
POST /pdf-jobs/rooms/{room_id}/sheettakes the same query parameters as the synchronous endpoint and returns202with ajob_idimmediately.GET /pdf-jobs/{job_id}reportspending,doneorerror.GET /pdf-jobs/{job_id}/fileserves the finished PDF.
The fast exports (labels, a plain box sheet, a box sheet with just photos) stay synchronous. They didn't need it, and a GET that returns a PDF is the simplest possible thing for a link.
PdfJobManager, deliberately small
The implementation is api/pdf_jobs.py, and the module docstring is blunt about its limits:
Jobs are process-local and unpersisted - restarting the API drops any in flight, which just means the caller clicks "Generate" again. There is deliberately no database table for this: it is ephemeral, short-lived state, not domain data.
In detail: a ThreadPoolExecutor with two workers runs the render off the request thread. A job record is a small dataclass - id, status, filename, label, file id, error, timestamps - held in a dict behind a lock. The finished PDF isn't kept in memory; it's cached via a second LocalFileStore, the same opaque-id storage attachments already use, pointed at $INVENTORY_PDF_CACHE_DIR (default: a pdf-cache/ sibling of the attachments directory).
Records and their files are swept 24 hours after creation, long enough for "grab that PDF again later today", and create() sweeps stale jobs before adding a new one, so there's no background janitor thread to get wrong.
Why not a table? A jobs table would have needed a migration, a repository method set, tests - and for what? If the process restarts mid-render, the right recovery is to click the button again. Persisting it would add machinery to preserve something nobody wants preserved. The clock is injectable here too, so the 24-hour sweep is tested by advancing a fake clock rather than waiting.
One honest limitation: with two workers and an in-memory registry this only works with one API process. For a single-container deploy, that's the deployment. If it ever scaled out, jobs would need to move somewhere shared.
The front end: three pieces
usePdfJob, a hook that starts the job and polls it.<PdfJobLink>, which replaces a plain<a>for these buttons. Idle it says "Generate…", pending it disables and polls, done it swaps in a real link (served from the cache, no regeneration) and opens it once automatically.- The Exports page.
The Exports page exists because of a flaw I noticed immediately: click Generate, navigate away, and the job is invisible. There was nowhere to check on a slow export or find out why one failed. So each job carries a label built by the route handler (not the caller) - e.g. Room sheet — Kitchen (sealed) + invoices - and GET /pdf-jobs lists them newest first. The page shows label, status pill, created and expiry times, a "View ↗" link when done, or the error message, and polls every two seconds while anything is pending.
The label's modifiers are assembled from the request: (sealed) for a status filter, (going: definite, maybe) for a decision filter, + invoices, + photos. It's a small thing, but it's what lets you tell three Kitchen exports apart.
Errors are results
Any exception inside the render is caught and recorded on the job (job.status = "error", job.error = str(exc)), then reported through the poll endpoint like any other state. That sounds obvious, but it means a failure inside a background thread isn't swallowed - it appears on the Exports page with its message. Post 12 leans on this: the all-rooms export raises a plain validation error when no box matches, and the job simply ends in error with that message.
Next: the post where I wrote a complete login system and then deleted it.
Previous: ← Sheets, labels and French · Next: Built, then deleted: authentication →
