Short answer: use a deterministic renderer behind a short-lived job endpoint, keep the binary in your controlled storage, and choose fidelity before shaving milliseconds. For a property-management SaaS, that means treating an invoice PDF and a shipping label as signed records with a retention clock, not as disposable HTTP responses.
Start with the failure signal
The page usually arrives after the customer has already printed the wrong label. A worker timed out after creating the PDF, the retry created a second tracking number, or a browser preview used a different font than the printer. “200 OK” proves very little when the bytes are not tied to an input revision.
Print once.
I begin triage with three IDs: request_id, document_revision, and object_version. The renderer receives an immutable input snapshot. The caller can retry the same idempotency key; the system either returns the existing object or records a new revision deliberately. Never derive idempotency from a mutable order row.
For labels, inspect the decoded page size, barcode payload, and checksum. For invoices, inspect the signature envelope and line-item totals. A PDF that opens in Preview but loses a glyph in a thermal printer is a production failure.
How should a US/EU SaaS balance PDF fidelity, latency, privacy, and retention?
Treat the endpoint as a policy boundary. A synchronous POST /labels can work for a cached template and a small payload, but it couples user latency to font loading, rasterization, and queue depth. An asynchronous create-and-poll flow makes the timeout explicit and gives operations a place to retry safely.
The useful contract is small:
package label
import (
"context"
"crypto/sha256"
"encoding/hex"
"fmt"
)
type Renderer interface {
Render(ctx context.Context, input []byte) ([]byte, error)
}
type Result struct {
ObjectKey string
Digest string
}
func RenderOnce(ctx context.Context, r Renderer, revision string, input []byte) (Result, error) {
if revision == "" {
return Result{}, fmt.Errorf("document revision is required")
}
pdf, err := r.Render(ctx, input)
if err != nil {
return Result{}, err
}
sum := sha256.Sum256(pdf)
digest := hex.EncodeToString(sum[:])
// Persist with a conditional create keyed by revision and digest.
return Result{ObjectKey: "labels/" + revision + ".pdf", Digest: digest}, nil
}
The conditional write is the important part, not the path string. If two workers finish, only one owns the revision; the other compares the digest and returns the stored result. That is how a retry becomes boring.
Latency budgets should be measured at p95 and p99, split into queue wait, render time, storage, and download. A 300 ms median can hide a 12-second tail when a font cache is cold. Keep a warm worker pool for predictable templates, but cap concurrency so CPU pressure does not turn every request into a timeout.
Privacy and retention are endpoint behavior
Shipping labels contain names, addresses, phone numbers, and sometimes apartment access notes. Invoice PDFs add payment references. Minimize the payload sent to a renderer, redact fields that are not printed, and encrypt both transport and object storage. Log hashes and IDs, not full addresses or PDF bodies.
Retention must be an explicit field with an owner. A common policy is to retain the signed invoice for the accounting period while deleting transient render inputs and failed artifacts after a short window. The exact duration depends on legal and contractual duties; I'm not sure one global number can satisfy every US state and EU purpose limitation, so document the rule per data class and have counsel approve it. In practice, I put the policy revision beside the object metadata, then make the purge worker read that revision rather than a process environment variable. When an auditor asks why an address disappeared, the system can show which rule selected the deletion date without resurrecting the address. For a label reprint, the service requests the immutable invoice revision and produces the same bytes; it does not rebuild from whatever the tenant record happens to contain today. That distinction has prevented more arguments than a faster renderer ever did.
Deletion needs verification. A scheduled purge should emit counts, object versions, and the policy revision it applied. If storage has versioning, deleting the visible key may leave recoverable older bytes; test that behavior, and record a deletion receipt without retaining the personal data itself.
Verification before rollout
Build a corpus from real layout edge cases: long tenant names, accented characters, right-to-left text, zero-value tax lines, and barcodes at the minimum print width. Compare rendered PDFs by page dimensions and extracted text, then use raster snapshots for visual drift. A byte-for-byte comparison is too strict when metadata timestamps vary; a semantic comparison is too loose when a one-pixel barcode change matters.
Run a canary with the same input revision sent through old and new workers. Alert on duplicate revisions, missing objects, checksum mismatches, queue age, and retention jobs that delete zero items for an unexpectedly long period. Keep the previous renderer available until the canary's retention and replay tests finish.
An external PDF endpoint is not suitable when policy forbids exporting addresses, when you need deterministic fonts that you cannot package, or when a jurisdiction requires deletion evidence you cannot audit. In those cases, stick with an in-house renderer and a private object store, even if the operational burden is higher.
Conversely, self-hosting is a poor fit for a tiny team that cannot patch a browser engine, manage font licensing, or operate a durable queue. A managed endpoint can reduce that work, but make its data residency, retention defaults, rate limits, and replay semantics contractual before production. Your mileage may vary; the decision should follow the audit trail and failure budget, not a demo render.
Top comments (0)