zalven88/pdf-engine repository overview

⁠pdf-engine

HTML + Minijinja⁠ templates → PDF. Rust, rendered in-process by Fulgur⁠ (no browser, no external binaries). Returns the PDF or uploads it to S3.

~1,000 invoices/s on 10 cores · ~2.5 ms per render · amd64 + arm64 image.

⁠Run

docker run -d -p 6767:6767 \
  -e API_BEARER_TOKEN=secret \
  -e STORAGE_URL=http://minio:9000 -e STORAGE_BUCKET=pdfs \
  -e STORAGE_ACCESS_KEY=... -e STORAGE_SECRET_KEY=... \
  zalven88/pdf-engine:1.1.0

STORAGE_* is required even if you only use /api/to-bytes. Inside Docker Compose, use the service name (e.g. http://minio:9000), not localhost.

⁠API

Form fields (multipart/form-data):

curl -H "Authorization: Bearer secret" \
  --form-string 'template=<h1>Invoice {{ no }}</h1>' -F 'data={"no": 42}' \
  http://localhost:6767/api/to-bytes -o invoice.pdf

Responses are gzip/brotli/zstd compressed (level 6) when the client asks.

⁠Configuration

Everything optional is off by default; set it in .env or the container environment.

⁠Images

<img src="data:image/..."> always works. Remote https:// images load only from ASSET_ALLOWED_HOSTS: no redirects, no private/loopback addresses (checked after DNS), images only, size and time limits. Blocked or broken images are skipped; the PDF still renders.

⁠Fonts

The image ships 29 Noto fonts (Latin, Serif, Mono, CJK, Arabic, Hebrew, Thai, emoji) via fonts/fonts.conf⁠. sans-serif/Arial → Noto Sans, serif → Noto Serif, monospace → Noto Sans Mono. To add one: copy it into /usr/share/fonts/pdf-engine, then POST /api/fonts/reload (or run with FONT_WATCH=true).

⁠CSS

Most document CSS works. Known gaps (e.g. repeating <thead>, float, z-index) and workarounds: docs/css.md⁠.

⁠Performance

Full results and sizing: docs/performance.md⁠.

⁠Development

make test       # functional test suites
make check      # fmt + tests (CI)
make bench      # micro-benchmarks
make stress     # load test (MODE=matrix|sweep|soak)
make help       # everything else

No Rust locally? Use the docker- variants (make docker-test, ...).

⁠Release

Bump version in Cargo.toml, add a CHANGELOG.md⁠ entry, commit, then make release. It tags vX.Y.Z and pushes zalven88/pdf-engine:X.Y.Z, X.Y, X and latest for amd64 and arm64.

⁠License

MIT. Rendering by Fulgur (MIT/Apache-2.0); fonts by Noto⁠ (OFL).

⁠Performance

Results: one machine, 10 CPUs (Linux aarch64, Docker Desktop), via make docker-stress / make docker-bench. Rerun on your own hardware before capacity planning.

⁠Load test: what 100,000 PDFs takes on one 10-core server

⁠Load test: scenario matrix (concurrency 32)

All 2,100 requests in the matrix returned 200.

⁠Load test: concurrency sweep (20-line invoice)

Throughput peaks at two to four in-flight requests per core. Beyond that, requests queue on the render semaphore (one permit per core), so latency rises while memory stays bounded.

⁠Load test: soak, 20,000 invoices on one server

Memory plateaus around 450 MB with no sustained growth (mimalloc keeps freed memory for reuse), and every request succeeded.

⁠Micro-benchmarks (single thread)

Rendering is where the time goes. Templating, encryption and compression together add well under 1 ms. Level 6 compresses almost as well as level 9 at the same cost.

⁠What makes it fast

• Shared font context: Fulgur normally rebuilds its font collection from fontconfig for every document. A small patch (vendor/fulgur, see PATCHES.md⁠) builds it once per process, which made renders 4–6× faster. Fonts added after startup need a restart.
• Curated font set: every font fontconfig exposes is enumerated, so the image exposes 29 files instead of ~2,300.
• mimalloc: rendering allocates heavily; mimalloc is ~10% faster than the system allocator.
• Zero-copy output: the PDF is one buffer from the renderer to the socket or S3.

⁠Production sizing

• Memory: budget ~600 MB per instance for invoice-style documents and ~1.5 GB if you render large CJK/emoji-heavy documents. Set a container memory limit with that headroom.
• Concurrency: the server caps concurrent renders at one per core; scale out with more instances rather than more concurrency per instance.
• Timeouts: keep RENDER_TIMEOUT_SECS above your p99 for the largest documents you generate. A render can't be interrupted once started; a timed-out render keeps its concurrency slot until it finishes.
• Fonts: keep FONTCONFIG_FILE pointed at the curated set; every extra font file adds per-render cost.
• Compression: gzip at level 6 saves ~20% on PDFs; clients that don't send Accept-Encoding get the raw PDF.

⁠Running the benchmarks

make stress                  # load test: matrix + concurrency sweep + 20k soak
make stress MODE=matrix      # one part only: matrix | sweep | soak
make bench                   # micro-benchmarks (local runs also write target/criterion/report/index.html)

# Load-test a deployed instance (no memory numbers):
PDF_URL=https://pdf.example.com API_BEARER_TOKEN=... make stress MODE=matrix

make stress runs scripts/loadtest.sh⁠. Without PDF_URL it builds a release binary and starts a fresh server for every scenario, measuring that server's peak memory. Use the production font set (FONTCONFIG_FILE, or make docker-stress) for representative numbers. Tunables: REQUESTS, CONCURRENCY, SWEEP, SOAK_ROUNDS, SOAK_BATCH.

Each scenario is an ignored test in tests/stress_tests.rs⁠ and can run on its own:

STRESS_URL=http://localhost:6767 API_BEARER_TOKEN=... STRESS_REQUESTS=2000 STRESS_CONCURRENCY=32 \
  cargo test --release --test stress_tests -- --ignored --nocapture stress_to_bytes_invoice

Set STRESS_MAX_P99_MS to make a scenario fail when its p99 latency exceeds the limit; that works as a performance gate in CI. Micro-benchmark sources are in benches/render.rs⁠.