How it works
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
- managed (default) — the supervised local pool described above; the fastest option, since instances are already running.
- external — connect to LibreOffice instances you run elsewhere over the UNO socket protocol; documents are streamed.
- fallback — plain
soffice --convert-toshell-outs with a throwaway profile. Used automatically (via a circuit breaker) when the pool is unhealthy, or exclusively withpool.mode = "fallback-only"— no pyuno required.
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
- API keys are high-entropy, stored as SHA-256 hashes, shown exactly once, revocable per key.
- Per-app restrictions: allowed source IPs/CIDRs/hostnames and allowed Referers; per-app quotas for file size, daily and per-minute job counts, and concurrency.
- Webhooks are signed with a per-app HMAC secret
(
X-Libreserv-Signature); the client library verifies them in constant time. - Admin accounts (argon2-hashed passwords) are separate from API keys and only access the web UI.