The constraint is the audit trail, not the button that says “download.” For a media SaaS watermarking customer files before external sharing, the endpoint should produce a deterministic PDF, encrypt it with a customer-controlled password, and emit an append-only record that ties the exact bytes to the requester. Short answer: choose an asynchronous, idempotent worker path for large files, keep a small synchronous path for previews, and measure p95/p99 latency separately from rendering fidelity.
That sounds less exciting than picking a PDF library. It is also the part that survives an incident review.
What does a password-protected PDF endpoint owe the audit log?
Treat the PDF as an artifact with a lineage, not as a response body. The audit event needs a request id, tenant and document identifiers, authorization decision, watermark policy version, input object version, encryption policy identifier, and a digest of the final bytes. Store the event before publishing the share link, then record the publication and every revocation as separate events. A mutable “last status” row loses the story you will need later.
Password handling deserves its own boundary. Accept the password over TLS, keep only a verifier or a reference to a managed secret, and never put it in query parameters or ordinary request logs. The service can return a short-lived capability for the encrypted object; it should not return the plaintext source object merely because rendering failed.
One practical shape is a two-stage contract. The request creates a job and an idempotency key. The worker reads a versioned source, applies the watermark, encrypts the output, computes its digest, and commits the audit event in the same publication transaction. A retry with the same key returns the existing artifact instead of creating a second, confusing audit trail.
How should US and EU teams balance fidelity, latency, and complexity under load?
Start with a fidelity budget. Fonts, transparency, embedded color profiles, annotations, and page geometry are common places where “looks right on my laptop” turns into a customer complaint. Keep a corpus of representative media contracts and compare rendered pages by perceptual hash plus a small set of semantic checks (page count, dimensions, and text extraction). A byte-for-byte comparison is useful for determinism, but it is not a proxy for visual fidelity.
Then define latency as a distribution. A 400 ms median does not help the customer whose 99th-percentile 200-page catalog waits 40 seconds. Separate queue wait, object fetch, rasterization, encryption, and upload timings. Under load, cap concurrent renders per tenant and use backpressure; unbounded fan-out simply moves the outage into memory pressure. I'm not sure a single global timeout is ever correct here: your mileage will vary with page count, image density, and the region where the source object lives.
For US/EU data, make residency an explicit placement decision. Keep source and derived objects in an allowed region, carry the region and retention class into the audit event, and test failover without silently copying customer PDFs across the Atlantic. The endpoint contract should expose a clear “queued” state and a retry-safe status check, so clients do not poll a rendering process that may already have completed.
| Decision | Lower latency choice | Higher assurance choice | Cost or risk to name |
|---|---|---|---|
| Rendering | Warm workers and bounded concurrency | Isolated workers per trust zone | Idle capacity versus startup delay |
| Encryption | Encrypt after rendering in one pipeline | Separate key-encryption and artifact-encryption steps | More audit events and coordination |
| Delivery | Short-lived signed capability | Proxy every download through policy checks | Proxy bandwidth and operational load |
| Region | Route to the nearest allowed worker | Pin tenant to a residency region | Less elasticity during a regional spike |
Which failure modes make a “working” PDF endpoint unsafe?
The first is a split-brain artifact: the link points at a new object while the audit row still describes the old watermark policy. Commit by immutable version, and make the link reference that version. The second is a retry storm. Clients, queues, and load balancers can all retry; idempotency must exist at the job boundary and at the publication boundary.
The third is silent degradation. A renderer that substitutes a font or drops an annotation may still return HTTP 200. Record warnings as structured metadata, set a policy for when a warning blocks publication, and keep the original source untouched. A fourth failure is leakage through observability: PDF names, passwords, and signed URLs often end up in traces unless redaction is tested, not merely configured. In a media catalog, one missing glyph can alter a legal notice; a dropped annotation can erase a rights restriction; and a successful status code can hide both facts until the recipient forwards the file. The test must therefore inspect the artifact, the policy version, and the audit event together, across retries and worker restarts, instead of treating each subsystem as healthy in isolation.
Keep the source immutable.
I once assumed a checksum in an object store was enough. It was not. The checksum proved which bytes were uploaded, while the audit question was why those bytes were authorized. That distinction changed the schema: authorization and policy decisions now sit beside the artifact digest, with no mutable field pretending to be history.
How can a small team test the endpoint before choosing a vendor?
Build a harness around a generic object interface and a generic PDF renderer. Feed it the corpus, vary concurrency, inject slow reads and duplicate deliveries, and collect p50, p95, and p99 for each stage. Test wrong passwords, expired capabilities, revoked shares, and worker restarts. The useful output is a decision record, not a leaderboard.
The harness can stay plain Python. It should make the idempotency and audit assertions visible enough that a reviewer can challenge them.
from dataclasses import dataclass
from hashlib import sha256
@dataclass(frozen=True)
class Artifact:
object_version: str
policy_version: str
digest: str
def publish(rendered_pdf: bytes, object_version: str, policy_version: str) -> Artifact:
digest = sha256(rendered_pdf).hexdigest()
# The real implementation commits this event with the immutable object.
audit_event = {
"object_version": object_version,
"policy_version": policy_version,
"artifact_sha256": digest,
}
append_audit_event(audit_event)
store_immutable_object(digest, rendered_pdf)
return Artifact(object_version, policy_version, digest)
The catch is that a generic interface does not remove operational work. You still own key rotation, retention deletion, regional routing, renderer patching, and evidence that the deletion really happened. Stick with a managed document pipeline when your team cannot staff those controls; choose a self-hosted renderer when deterministic fonts or offline processing are requirements. Neither choice excuses measuring tail latency with your real corpus.
A compact rollout rule for password-protected customer files
Ship the preview path first, with a strict page and byte limit. Promote larger jobs to the queue, publish only after the audit event and encrypted object are both durable, and expose a status endpoint that is idempotent and region-aware. During a canary, compare fidelity diffs and p99 stage timings against the baseline; stop the rollout when either regresses beyond a threshold agreed with support and compliance.
The endpoint is ready when a reviewer can answer three questions from the log: which source version was used, which policy authorized the watermark and password protection, and which exact bytes were delivered. Everything else is tuning.
