Caching & performance

How fast gpdf-api is, where the latency comes from, and what you can do to keep it fast.

Caching & performance

This is the page that doesn't apologise for talking about milliseconds.

What we measure

Every successful response sets X-GPDF-Latency-Us — render time on the server, in microseconds. End-to-end (your client → us → your client) takes longer because of TLS, routing, and the body write itself.

Recent (us-central1 same-region) numbers:

Shape P50 P95 P99
1-page A4, Latin only 13 ms 23 ms 45 ms
1-page A4 with CJK 14 ms 25 ms 49 ms
100-page A4 batch 408 ms 578 ms 720 ms
1000-page A4 batch 3.9 s 5.1 s 6.3 s

These are wall-clock HTTP latencies, not "server CPU time". They include the entire round trip from a client in the same region.

The bench data lives in gpdf-app/data/bench.json and is refreshed weekly by a CI job.

Where the time goes

For a typical 1-page invoice request, here's the breakdown:

TLS + edge          ~5–25 ms     (network, region-dependent)
Auth + quota         ~0.3 ms     (LRU cache hit; ~3 ms on cold cache)
Render               1–10 ms     (depends on page complexity)
Body write           1–3 ms      (Cloud Run egress)

The cold cache path costs 2–3 ms because we have to look up the API key in Firestore. Subsequent requests for the same key hit an in-process LRU and pay almost nothing.

How you can keep it fast

Most of the latency is in your hands.

1. Reuse HTTP connections

Connection: keep-alive is on by default for both Node fetch (Node 18+) and Go http.Client. If you're using curl --new-conn or a pre-Node-18 polyfill, you're paying for TLS on every call.

// Node ≥ 18: default global agent already keeps connections alive.
const res = await fetch(url, { ... })

// Older Node: use undici or keepAlive Agent
import { Agent, fetch } from 'undici'
const agent = new Agent({ keepAliveTimeout: 30_000 })
await fetch(url, { dispatcher: agent, ... })

Same for Go:

client := &http.Client{
    Transport: &http.Transport{
        IdleConnTimeout:     30 * time.Second,
        MaxIdleConnsPerHost: 16,
    },
}

2. Cache the template, send only data

If your template is fixed and only the variables change, build the JSON envelope once:

const template = readFileSync('invoice-template.json', 'utf8')

async function renderInvoice(data) {
  const body = JSON.stringify({ template: JSON.parse(template), data })
  return fetch(url, { method: 'POST', headers, body })
}

We don't dedupe templates server-side — sending the same blob a million times costs a million times the bandwidth.

3. Compress request bodies

Large data blocks (long item lists, detailed records) compress 5–10× as gzip:

import { gzipSync } from 'node:zlib'
const body = gzipSync(Buffer.from(JSON.stringify({ template, data })))

await fetch(url, {
  method: 'POST',
  headers: { ...headers, 'Content-Encoding': 'gzip' },
  body
})

The body-size cap (8 MiB) is measured after decompression, so gzip lets you ship larger payloads, not just shrink the wire.

4. Don't poll /v1/pdf like a queue

Each call counts as a render. If you need exactly-once delivery, dedupe with an idempotency key on your side. We don't bill for retries we didn't run, but every 200 you got really did happen.

5. Batch where you can

For 100 invoices: one request that renders all 100 (via a range in the template) is faster than 100 separate requests for the same total bytes out, because you pay TLS, auth, and quota lookup once. The trade-off is response size — keep an eye on the 5/15/∞ MB plan caps.

Where the slowness comes from when it does

Real customer renders that hit the 30-second timeout are almost always one of:

Cause Symptom Fix
External image fetch hung Latency stuck at 4–8 s, error template_error Inline as base64.
Pathological table layout 1000+ row tables with keep-together everywhere Drop keep-together or chunk rows.
Go-template recursion Memory blow-up + 504 Profile your data shape; the engine doesn't have an eval loop limit.
Region drift P50 of 200+ ms You're calling from outside us-central1. Move closer or wait for multi-region.

Self-host performance

The same engine ships with the self-host binary. Numbers on a 4-vCPU box (no Cloud Run) typically beat the SaaS measurements above by 10–30%, because there's no internet hop. If you're rendering at very high QPS, self-host is the way.

Something unclear or missing on this page?