How it works

your applications libreserv-api REST API · admin UI libreserv-worker queue consumer · pool PostgreSQL jobs · keys · usage Valkey job queue LibreOffice pool slot-0 slot-1 slot-2 HTTPS enqueue consume UNO

The two processes

libreserv-api accepts uploads, enforces authentication, restrictions and quotas, enqueues jobs, and serves the admin UI. libreserv-worker consumes the queue and converts documents on a pool of warm LibreOffice instances. Each pool slot is a small driver child process — the only code that speaks pyuno — which owns its own soffice --headless with an isolated profile. Drivers are supervised: health-pinged, recycled after a configurable number of jobs (LibreOffice leaks), and killed and restarted with backoff when they hang or die. Documents move through a configurable spool directory.

Three conversion engines

Job lifecycle

queued → running → succeeded, then expired once file retention passes. A job that fails on a transient error (instance died, timeout) is retried on another slot; a document that genuinely cannot be converted goes to failed with a machine-readable error_code. Jobs can be canceled while queued or running. Every transition is recorded as a timestamped event, and each job keeps a plain-text log of what happened — engine used, timings, retries, LibreOffice stderr excerpts.

Storage: who owns what

PostgreSQL is the authoritative store — apps, hashed API keys, jobs, events, daily usage rollups. Valkey holds only the queue and ephemeral state: losing it never loses durable data (the worker reconciles on startup). The spool directory holds originals, results, and per-job logs until retention.files expires; job rows and events survive until retention.history_days, and usage rollups survive both.

Security model