DEV Community

ErasmusPierce7981
ErasmusPierce7981

Posted on

Node.js PDF API Boundaries for Hosted or Local Libraries and Password-Protected Files

#pdf #sre #node

Short answer: choose a hosted PDF API when the game team wants a stable template contract without owning a renderer fleet; choose a local PDF library when template changes, data residency, or a tight latency SLO require the rendering boundary to stay inside your workers. Under load, the important comparison is not the happy-path render time. It is who owns the queue, the fonts, the password operation, and the recovery policy when a monthly report burst arrives.

The page fires at 09:02 on the first business day. The alert says that archived player-spend reports are missing their delivery target. Support sees encrypted files eventually, but the report dashboard shows a growing backlog and a p99 archive age of 18 seconds. The first useful question is not “which renderer is faster?” It is “which boundary owns the delay?”

Measure it.

That distinction matters in gaming because a monthly report has an awkward shape: mostly quiet traffic, then a synchronized burst, with templates that change when legal text or regional tax rules change. A local library turns those changes into your build and test problem. A hosted API turns them into a contract and dependency problem. Both can be correct; the failure mode moves.

Start with template ownership, not the renderer

The platform team should write down who can change the template, who reviews fonts and pagination, and who can roll back a bad release. If the studio owns the layout and ships a new localized version every sprint, a local renderer keeps the fixture, font files, and code review in one repository. That makes a template diff observable before it reaches customers.

If the platform team owns a small set of stable templates, a hosted boundary can remove browser-runtime patching from the roadmap. That is useful only when the API exposes a versioned template contract, deterministic output rules, and an audit trail for the input and resulting bytes. “Hosted” is not a substitute for ownership; it changes the owner you have to coordinate with.

Here is the decision record I would keep beside the service-level objective:

Pressure Hosted PDF API Local PDF library
Template change authority Shared contract and provider release cadence Your repository, fixtures, and rollback
Burst latency Network, remote queue, and rendering time Worker queue, CPU, memory, and rendering time
Password-protected output Contract must specify encryption and key handling Encrypt bytes before archive upload in your trust boundary
Residency and offline regions Requires an approved data path Keeps customer bytes in the region you operate
On-call surface Dependency limits, quotas, and request tracing Patching, capacity, and process isolation

The catch is important: a hosted service is not suitable when customer files cannot cross a trust boundary or when an air-gapped region must render during a network partition. Stick with a local library there. A local library is also a poor fit when no team can own font updates and security patching; in that case, the apparent control is just unstaffed work.

What should latency under load mean for hosted and local PDF paths?

Define the SLO around the customer-visible artifact, not only the render call. For example, measure from job admission to a verified encrypted object in the archive. Break that interval into queue wait, template fetch, render, password protection, upload, and verification. A 400 ms render can still violate a 5-second SLO if the worker queue spends 4 seconds waiting for memory.

The alert-to-action trace should expose the earliest change. Queue age rising with flat render duration points to capacity. Render duration rising with stable queue age points to template complexity or a cold runtime. Upload duration rising while both are flat points to storage. The page should fire on SLO burn, while warnings on queue age and retry rate give the on-call time to act before the report is late.

I once assumed a single pdf_duration histogram was enough. It wasn't. The histogram hid a bimodal path: warm workers completed quickly, while a batch that loaded large font sets pushed cold workers into long garbage-collection pauses. Your mileage may vary, but the remedy is stable: tag each stage and record the template version, byte size, and concurrency at the time of the sample.

Use bounded concurrency and a deadline that covers the whole job. The renderer should be replaceable so the same corpus can exercise an HTTP client or a local implementation without changing archive semantics:

package reports

import (
    "context"
    "crypto/sha256"
    "fmt"
)

type Renderer interface {
    Render(context.Context, []byte, []byte) ([]byte, error)
}

type Archive interface {
    Put(context.Context, string, []byte) error
}

func RenderReport(ctx context.Context, renderer Renderer, archive Archive, template, data []byte, key string) error {
    pdf, err := renderer.Render(ctx, template, data)
    if err != nil {
        return fmt.Errorf("render report: %w", err)
    }
    // Encrypt and verify the PDF before it leaves the worker in production.
    digest := sha256.Sum256(pdf)
    objectKey := fmt.Sprintf("%s-%x.pdf", key, digest[:8])
    if err := archive.Put(ctx, objectKey, pdf); err != nil {
        return fmt.Errorf("archive report: %w", err)
    }
    return nil
}
Enter fullscreen mode Exit fullscreen mode

Load tests need the ugly inputs: the longest localized player name, the largest legal footer, a rotated password, and an archive that slows down while rendering continues. Test warm and cold workers separately. For a useful run, replay the same monthly cohort at several concurrency levels, hold the template version constant, and record queue age beside CPU, heap, file-descriptor use, and outbound connection count; then repeat with a deliberately slow archive so you can see whether backpressure protects the renderer or merely moves the pile into memory. The capacity number you want is the maximum concurrency at which p95 remains inside the SLO and memory stays below the eviction threshold, not the highest throughput observed for ten seconds. That number should be written into the deployment limit and revisited when the template or password settings change.

Make password handling and recovery explicit

Password protection does not grant authorization. Keep the secret in a key-management system, pass only a reference through the job, and verify that the archived artifact cannot be opened without the intended secret. Do not put the password in a URL, log line, retry payload, or object metadata. A failed verification is a data-integrity event, even if the renderer returned success.

Idempotency is the bridge between a timeout and a safe retry. Derive an idempotency key from the customer, reporting period, template version, and input digest. Store the render result only after encryption and verification. If an upload times out, retry the write with the same object key rather than rendering a second report and creating two competing artifacts.

False positives still cost attention. A threshold set below the normal month-start burst trains the on-call to mute the page; a threshold set above the error budget lets a saturated pool miss customer commitments. Keep separate signals for queue age, renderer errors, password verification, archive writes, and SLO burn so one noisy dependency does not erase the shape of the incident.

Revisit the boundary when the contract changes

The decision should be revisited when template ownership changes, not when a vendor comparison spreadsheet gets refreshed. A hosted API is a reasonable boundary for a small platform team that wants to retire renderer patching and can measure network and remote-queue latency. A local library is the better boundary for strict residency, offline operation, or a latency budget with no room for a remote dependency.

Neither choice removes capacity planning. The production contract remains explicit: versioned templates, bounded work, secret references instead of secret bytes, traceable artifacts, and a tested recovery path. Start with the boundary your team can actually operate, then prove the burst behavior with the same encrypted files customers will receive.

References

Further reading

Top comments (0)