Operating NextPDF in production

Spec Spec: ISO 9241-112:2025, §6.1.2.3 ISO 9241-112:2025 §6.1.2.3 Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 Evidence ◈ Artifact-backed Evidence: Artifact-backed

At a glance

Running a PDF engine in production is not “call it and ship the bytes.” You own what it tells you when a render is healthy, what it does when one is not, where you tap it for observability, and which dangerous operations it refuses to perform silently. This page describes the operational surface — the seams and properties a team takes on the day NextPDF runs for real.

Why this matters

A document engine fails differently from a typical service. The failures are often quiet: a degraded layout that still produces a file, a blocked external resource that changes the output, an unsigned document that looks signed. If the engine hides these, you find them through a customer, not a dashboard. If it surfaces them, they become an alert and a runbook entry instead of an incident.

Operability is therefore not a feature you add later. It is whether the engine was built to tell you the truth about each render — and NextPDF was.

The short version

• Every render produces a structured report. Success, page count, render time, peak memory, warning codes, fallback occurrences, blocked external resources — serializable to JSON for your dashboard.
• The engine emits typed lifecycle events through a PSR-14 dispatcher with zero overhead when nothing is listening — your audit and metrics hooks attach there.
• Failure modes are explicit, not silent. Degraded parity is reported. The high-level signature surface fails fast. Output is written atomically. External subresource fetching is off by construction in the in-process HTML path.
• Dangerous operations require a human in Connect. When NextPDF is exposed to AI agents, destructive or privacy-critical tools are gated behind a confirmation challenge — the most important operational property stated where you will see it (ISO 9241-112 §6.1.2.3).

How NextPDF approaches it

The operating model rests on one principle: a render should never lie about what it did. Three mechanisms make that concrete — a report, an event stream, and a set of fail-safe behaviors. A fourth applies when the engine is driven by an agent.

1. Observe each render Collect the per-render report — success, timing, peak memory, warnings, fallbacks, blocked-resource counts — into your telemetry sink.
2. Subscribe to lifecycle events Attach PSR-14 listeners for document, security, and serialization events for audit logging and metrics.
3. Detect degradation Treat degraded-parity and fallback signals as health indicators, not noise. They mean the output differs from the ideal render.
4. Gate the dangerous path In Connect, route destructive or privacy-critical operations through the human confirmation gate before they execute.

The operational surface end to end: instrumentation is opt-in and zero-cost when unused; failure modes surface as data or fast failures, never as a quietly wrong file.

The report is an immutable snapshot designed for aggregation. It carries whether the render succeeded, how long it took, peak memory, per-code warning counts, whether a safe rendering mode was active, how many external resource requests were denied, and which layout fallbacks occurred. That last group matters operationally. A rising count of “flex fell back to block” across a fleet is a signal that a template changed, and you see it before any user complains.

The event seam is PSR-14 compatible and deliberately cheap. The dispatcher returns immediately when no listener is registered for an event class. Because of that, adding the seam costs nothing until you use it. There are typed events for document creation and output, page addition, content and font loading, encryption applied, signature applied, and PDF serialized. These are the points an audit log or a metrics counter actually cares about. The observability contracts (metrics counter, gauge, histogram, trace span, HSM audit log) ship with no-op implementations. The engine is therefore fully functional with zero telemetry wiring, and it becomes observable when you bind real implementations.

Human-factors note: Human-factors note

The single property to remember: NextPDF prefers a loud, fast failure or an honest degraded report over a silently wrong document. The high-level signature call fails fast rather than emit an unsigned file. Output is written atomically, so a concurrent reader sees the old file or the new one, never a half-written one. The in-process HTML renderer cannot be configured to fetch remote subresources. Server-side request forgery and cloud-metadata probes are removed by construction, not by a setting you must remember. Operationally, your alerts fire on the failure, not on its downstream consequence.

What the evidence says

This page is artifact-backed: the operational surface is real classes and contracts you can wire today. Evidence ◈ Artifact-backed Evidence: Artifact-backed

The report is code: RenderReport is an immutable, JSON-serializable value object with exactly the fields described — success, page count, render time, peak memory, per-code warning counts, safe-mode flag, external-resource denials, fallback occurrences, timestamp. The event seam is code: a PSR-14 EventDispatcher with a zero-overhead fast path and a typed event hierarchy spanning document, security, content, and writer events. The fail-safe behaviors are code. The atomic output write closes a documented time-of-check/time-of-use gap. The in-process HTML path’s no-remote-subresources guarantee is a @security contract enforced by construction. The high-level signature surface raises a blocking diagnostic rather than emitting an unsigned PDF.

The agent-safety property is code in NextPDF Connect: Evidence { } Code-backed Evidence: Code-backed a four-level risk model (safe, caution, review, approval-required) and a confirmation gate that, for an approval-required tool, issues a single-use challenge token and refuses to proceed until you relay that token back. The risk of a tool comes from exactly two sources: its own declaration and an operator override that can only raise it. The dangerous surface therefore cannot be quietly widened.

The way this page is organized is itself standard-backed: Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 recommends structuring operational information by the tasks the reader performs, which is why the four stages map to observe, subscribe, detect, and gate.

Practical example

The code below shows the observability seam: a PSR-14 listener that turns lifecycle events and the render report into telemetry. It illustrates the seam. The metrics sink is yours.

<?php

declare(strict_types=1);

use NextPDF\Event\Document\DocumentOutputEvent;
use NextPDF\Event\Security\SignatureAppliedEvent;
use Psr\Log\LoggerInterface;

/**
 * Audit + metrics listener for production operation.
 *
 * Attaching this costs nothing until events fire — the dispatcher
 * short-circuits when no listener is registered for an event class.
 */
final readonly class OperationsListener
{
    public function __construct(
        private LoggerInterface $logger,
    ) {}

    public function onSignatureApplied(SignatureAppliedEvent $event): void
    {
        // Compliance trail: who signed, at what level, why.
        $this->logger->info('pdf.signature.applied', [
            'level'  => $event->signatureLevel,
            'signer' => $event->signerName,
            'reason' => $event->reason,
        ]);
    }

    public function onDocumentOutput(DocumentOutputEvent $event): void
    {
        // Pair this with the engine's RenderReport for the full picture:
        // success, render_time_ms, peak_memory_bytes, fallback_occurrences.
        $this->logger->info('pdf.document.output', [
            'event' => $event::class,
        ]);
    }
}

The point is the seam, not the body. The engine hands you typed events and a structured report. What you forward, sample, or alert on is an operations decision the engine deliberately leaves to you.

Common misconception

The operational misconception is “if it returned bytes, it worked.” A render can succeed and still be degraded. A layout fell back, an external image was blocked and silently absent, a feature was unsupported in the active mode. The bytes exist. The document is not what the template intended. The engine reports these as warnings and fallback counts precisely so “returned bytes” is not mistaken for “rendered correctly”. Treating the return value as the only success signal is the error this surface exists to prevent.

A second misconception, specific to Connect: that exposing PDF tools to an agent is safe because the tools are “just rendering”. Destructive, overwriting, or privacy-critical operations are gated behind a human confirmation challenge for a reason. Bypassing or auto-answering that gate re-introduces exactly the risk it removes.

Limits and boundaries

• The engine instruments; it does not run your observability stack. It emits a report and typed events; collection, alerting, dashboards, and retention are yours.
• No-op observability is the default. Metrics, traces, and HSM audit logs are inert until you bind real implementations — by design, so the engine works with zero wiring. But it means nothing is recorded until you opt in.
• The SSRF fail-safe applies to the in-process HTML path. External renderer bridges (browser/Office) make outbound calls by their nature and carry their own transport hardening. This guarantee is specifically about the in-process path.
• The human-confirmation gate is a NextPDF Connect property. It governs agent-driven invocation. It is not a general PDF feature, and it binds on tool name and a nonce, not on argument hashing.
• The high-level signature surface fails fast. It is not a wired signer. Operationally, treat its diagnostic as the signal, and use the wired lower-level path to do the actual signing.
• This page is artifact-backed: every seam named is a real class or contract, but operating them well is your responsibility.

Observability and operational seams — edition availability

Edition	Availability
Core	○ The RenderReport, the PSR-14 event dispatcher and typed event hierarchy, the no-op observability contracts, atomic output writes, and the in-process SSRF fail-safe are all Core.
Pro	○ Adds security lifecycle events (encryption/signature applied) with operational substance once signing is in use.
Enterprise	○ Adds the HSM audit-log seam and validation findings as operational signals; NextPDF Connect adds the human-confirmation gate for agent-driven, high-risk operations.

Related docs

• The pipeline model — the staged shape that makes these observability seams possible and where they sit.
• HSM-backed signing — the operational shape of hardware-backed keys and where the audit boundary sits.
• High-volume document generation — turning the per-render report into capacity and health signals at scale.

Glossary

• RenderReport — the engine’s immutable, JSON-serializable per-render metrics snapshot used as the primary health signal.
• PSR-14 — the PHP standard for an event dispatcher; NextPDF’s dispatcher is compatible and zero-overhead when unused.
• Degraded parity — a render that completed but whose output differs from the ideal because a feature fell back or was unsupported.
• Fallback occurrence — a recorded instance of the layout engine substituting a simpler behavior (for example flex rendered as block).
• SSRF (Server-Side Request Forgery) — an attack where a server is tricked into making requests to internal targets. Removed by construction in the in-process HTML path.
• Confirmation gate — the NextPDF Connect mechanism that requires a human-relayed single-use token before a high-risk, agent-invoked tool executes.
• Atomic write — an output write where a concurrent reader sees either the previous file or the complete new one, never a partial file.