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.
Related
Something unclear or missing on this page?