Node.js Logistics Report PDF: Charts Rendered as Images in HTML

#node #pdf #sre

A Node.js logistics report PDF with charts rendered as images in HTML should be reproducible, yet the page says unsigned_documents > 0 for a dispatch batch that closed 18 minutes ago. The on-call view shows a job ID, 240 source documents, 317 output documents, and nothing that answers the useful question: did the merge invalidate a signed PDF, did the split omit a signature-bearing page, or did an audit event arrive late?

Short answer: render charts to deterministic image bytes before the Node.js HTML-to-PDF stage, but treat that rendered report as a new document. Never claim that an input PDF signature survives a merge or split. Preserve signed originals, hash every input and output, record the ordered transformation, and sign the resulting bundle separately when policy requires it. Alert on a broken reconciliation invariant, not on a vague renderer failure count.

That distinction matters in logistics because a bundle is rarely just a report. A proof of delivery may sit beside a shipment summary, a customs form, and a chart of temperature readings. The chart can be regenerated; the signed proof should remain independently verifiable. PDF is standardized by ISO 32000-2, but a valid PDF container does not, by itself, prove that a business transformation retained the right pages or preserved the meaning of a signature.

What should the page have fired on?

Work backward from the page. unsigned_documents > 0 mixes at least three states: no output signature was requested, signing is pending, or verification failed. Only one is necessarily an incident. A better signal joins the manifest, transformation result, signature policy, and terminal audit event, then pages when the state cannot become correct without intervention.

For each job, write an immutable manifest before rendering. It needs a job identifier, the ordered source object identifiers and SHA-256 digests, page-selection rules, the digest of each chart image, the expected output count, and the applicable signature policy. After generation, append output digests, page counts, signer or signing-service identity where applicable, verification status, and a timestamped terminal event. Do not overwrite the first record to make the dashboard green.

The invariant is small enough to say out loud: every accepted input appears exactly once in the transformation record; every selected page maps to an output page; every output digest is recorded; and every output that requires a signature has a successful verification event. Page on a violated invariant after the job reaches its deadline. Ticket a delayed optional signature. Measure renderer errors separately.

What page fired? That question forces the alert to carry evidence: job ID, violated invariant, policy name, last completed stage, and a link to the append-only audit record. A chart of failure rates is useful later, but it cannot tell an on-call engineer which shipment is blocked.

How should Node.js render report charts as images for a PDF?

A browser rendering live chart JavaScript introduces timing into a document that should be reproducible. Fonts may finish after the chart library, animations may still be running, and a retry can capture a different frame. Generate each chart as PNG or another supported raster format at a fixed pixel size, compute its digest, and reference immutable bytes from the HTML. The Node.js coordinator should wait for all image work to finish before it submits the document for PDF rendering.

Use explicit dimensions in HTML so layout does not shift while assets load. Keep labels, units, time zone, data range, and series order in the manifest as well as in the visible report; an image digest proves which pixels were used, while those fields explain what the pixels meant. A transport-temperature chart without a time zone is an attractive incident report waiting to happen.

Freeze it there.

The critical boundary is after chart rendering and before PDF creation. At that point, freeze the HTML template version, CSS version, font digests, image digests, and normalized report data. A retry must consume that frozen input set. If mutable URLs are fetched again, the same job ID can produce a different document and the audit trail becomes ambiguous.

The following Go verifier is intentionally separate from the Node.js coordinator. It demonstrates the gate that should run against a completed manifest before a job is declared successful; code language does not change the invariant.

package audit

import (
    "crypto/sha256"
    "encoding/hex"
    "errors"
)

type Output struct {
    Bytes             []byte
    RecordedSHA256    string
    SignatureRequired bool
    SignatureVerified bool
}

func Verify(outputs []Output, expected int) error {
    if len(outputs) != expected {
        return errors.New("output count does not match manifest")
    }
    for _, output := range outputs {
        sum := sha256.Sum256(output.Bytes)
        if hex.EncodeToString(sum[:]) != output.RecordedSHA256 {
            return errors.New("output digest does not match manifest")
        }
        if output.SignatureRequired && !output.SignatureVerified {
            return errors.New("required output signature did not verify")
        }
    }
    return nil
}

Keep this gate boring. It should not infer policy, repair records, or retry signing; those actions belong to distinct stages with their own audit events.

A signature is attached to bytes, not business intent

Merging signed PDFs changes the resulting byte sequence. Splitting pages creates new files. The safe operational model is therefore preservation plus derivation: retain each signed source unchanged, verify it on intake, and record that the generated bundle derives from specified source digests under a specified transformation. If the bundle itself must be signed, sign that output as a separate artifact and retain its verification result. This model also handles mixed bundles. Suppose 240 inputs produce 317 outputs because customs packets split by destination while delivery records merge by route. Count equality would be the wrong control. The manifest must express the expected fan-out and fan-in, including page ranges and ordering, so reconciliation tests the declared mapping rather than assuming one input becomes one output. Do not put a signature image into HTML and call the PDF signed. A scanned mark can be visible evidence in a workflow, but cryptographic verification needs the actual digital-signature structure, certificate path, validation policy, and the exact signed bytes. Those are separate claims. The audit event should say which claim was checked.

Pixels are not proof.

Instrument the transformation, not the renderer

The first dashboard probably counts render attempts, durations, and exceptions. Keep those metrics, but add stage events that correspond to recoverable work: manifest committed, sources verified, chart images frozen, HTML rendered, PDF validated, output signed, signature verified, and terminal reconciliation passed. Each event carries the job ID and attempt ID; only the manifest carries document-level identifiers, which limits accidental high-cardinality metric labels.

Three service-level indicators are more actionable than a generic success rate: terminal jobs with a passing reconciliation invariant, policy-required outputs with a successful signature verification, and jobs completed before their operational deadline. A renderer can return successfully while the wrong page range was selected. Conversely, a transient renderer error followed by a valid, reconciled retry should not wake anyone.

Retries need an idempotency key bound to the frozen manifest digest. Store a new attempt event each time, but publish an output only if its digest and mapping pass the gate. If two attempts produce different output digests from identical frozen inputs, quarantine both results and investigate determinism rather than choosing the later one. This is where long-lived audit data earns its storage cost.

Testing should follow the same boundary. Use fixtures containing portrait and landscape pages, rotated pages, missing optional charts, Unicode labels, a signed source, and a declared split/merge mapping. Assert mappings and digests in integration tests; visually compare a small golden set for clipping and font substitution. Deployment can canary a new renderer or template version against frozen fixtures without mixing its output into live shipment records.

The threshold can create its own incident

A zero-tolerance page is appropriate for a terminal job whose required output signature fails verification or whose page mapping cannot reconcile. It is noisy for work still inside its deadline, optional signatures, and retryable intermediate attempts. Delay the evaluation until the terminal condition or deadline, then group alerts by policy and failure stage so one broken signing dependency produces one actionable page rather than hundreds.

There is a real trade-off. Waiting too long delays a shipment; paging on every intermediate miss trains the on-call to distrust the alert. Use the business deadline from the manifest, subtract the measured time needed for a controlled retry, and page when the remaining recovery window is threatened. The exact threshold must come from observed stage latency and the dispatch commitment, not from a round number copied between services.

The closing check is blunt: can the responder identify the affected job, prove which bytes entered and left it, see the page mapping, and distinguish a missing required signature from a late event without opening a general-purpose dashboard? If not, the instrumentation is unfinished. Fix that before tuning the chart colors.

DEV Community