NextPDF を本番環境で運用する

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

概要

PDF エンジンの本番運用は、「呼び出してバイト列を出力するだけ」ではありません。レンダリングが正常なときにエンジンが何を知らせるか、正常でないときに何をするか、可観測性のためにどこから情報を取り出すか、そしてどの危険な操作を黙って実行しないのか。これらはすべて、あなたの責任範囲です。このページでは、NextPDF を実際に運用し始めた日にチームが引き受ける接続点と特性、つまり運用面を説明します。

なぜ重要か

ドキュメントエンジンの障害は、一般的なサービス障害とは異なる形で現れます。こうした障害は、しばしば静かです。レイアウトが劣化していてもファイルは生成される、外部リソースがブロックされて出力が変わる、未署名なのに署名済みに見えるドキュメントができる、といったケースです。エンジンがこれらを隠してしまうと、ダッシュボードではなく顧客経由で気づくことになります。エンジンがこれらを表面化すれば、インシデントではなくアラートと Runbook の項目として扱えます。

したがって運用性は、後から追加する機能ではありません。各レンダリングについて真実を伝えるようにエンジンが設計されているかどうかの問題であり、NextPDF はその前提で設計されています。

要点

• すべてのレンダリングが構造化レポートを生成します。 成否、ページ数、レンダリング時間、ピークメモリ、警告コード、フォールバックの発生回数、ブロックされた外部リソース――これらはダッシュボード向けに JSON へシリアライズできます。
• エンジンは型付きのライフサイクルイベントを発行します。 PSR-14 ディスパッチャーを介して発行され、リスナーがない場合のオーバーヘッドはゼロです――監査やメトリクスのフックはここに接続します。
• 障害モードは明示的であり、静かではありません。 劣化パリティは報告されます。高レベルの署名 API は早期に失敗します。出力はアトミックに書き込まれます。インプロセスの HTML パスでは、外部サブリソースの取得は構造的に無効になっています。
• Connect では危険な操作に人間の介在が必要です。 NextPDF を AI エージェントに公開する場合、破壊的またはプライバシーに関わるツールは確認チャレンジの背後でゲートされます――これは最も重要な運用特性であり、目立つ場所に明記されています（ISO 9241-112 §6.1.2.3）。

NextPDF のアプローチ

この運用モデルは、ひとつの原則に基づいています。レンダリングは、自身が行ったことについて決して嘘をついてはなりません。 これを具体化するのが、レポート、イベントストリーム、一連のフェイルセーフな挙動という三つのメカニズムです。四つ目のメカニズムは、エージェントがエンジンを駆動する場合に適用されます。

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.

運用面のエンドツーエンド。計装はオプトインであり、使わなければコストはゼロです。障害モードはデータまたは早期失敗として表面化し、黙って誤ったファイルになることはありません。

レポートは、集計を前提に設計された不変のスナップショットです。レポートには、レンダリングが成功したかどうか、所要時間、ピークメモリ、コードごとの警告数、セーフレンダリングモードが有効だったかどうか、拒否された外部リソース要求の数、どのレイアウトフォールバックが発生したかが含まれます。この最後のグループが運用上重要です。フリート全体で「flex が block にフォールバックした」回数が増えているなら、それはテンプレートが変更されたというシグナルであり、ユーザーから苦情が届く前に気づけます。

イベントの接続点は PSR-14 互換で、意図的に軽量に作られています。ディスパッチャーは、対象のイベントクラスにリスナーが登録されていない場合、即座に戻ります。そのため、この接続点を追加しても、実際に使うまでコストはかかりません。ドキュメントの作成と出力、ページの追加、コンテンツとフォントの読み込み、暗号化の適用、署名の適用、PDF のシリアライズに対する型付きイベントが用意されています。これらは、監査ログやメトリクスカウンターが実際に関心を持つポイントです。可観測性のコントラクト（メトリクスカウンター、ゲージ、ヒストグラム、トレーススパン、HSM 監査ログ）には、no-op 実装が同梱されています。そのためエンジンは、テレメトリの配線がゼロでも完全に機能し、実装をバインドすると可観測になります。

Human-factors note: Human-factors note

覚えておくべき特性はひとつです。NextPDF は、黙って誤ったドキュメントを生成するよりも、目立つ早期失敗や正直な劣化レポートを優先します。高レベルの署名呼び出しは、未署名のファイルを出力するのではなく、早期に失敗します。出力はアトミックに書き込まれるため、並行する読み取り側には古いファイルか新しいファイルのいずれかが見え、 途中まで書き込まれたファイルが見えることは決してありません。インプロセスの HTML レンダラーは、 リモートのサブリソースを取得するようには構成できません。サーバーサイドリクエストフォージェリやクラウドメタデータの探索は、構造的に排除されています。あなたが覚えておかなければならない設定に依存しているわけではありません。運用上、アラートは障害そのもので発火し、 その下流の影響で発火するのではありません。

エビデンスが示すこと

このページはアーティファクト裏付けです。ここで扱う運用面は、今日すぐに配線できる実在のクラスとコントラクトで構成されています。 Evidence ◈ Artifact-backed Evidence: Artifact-backed

レポートはコードです。RenderReport は不変で JSON シリアライズ可能な値オブジェクトであり、ここで説明したフィールド――成否、ページ数、レンダリング時間、ピークメモリ、コードごとの警告数、セーフモードフラグ、外部リソースの拒否、フォールバックの発生、タイムスタンプ――を正確に備えています。イベントの接続点もコードです。オーバーヘッドゼロの高速パスを備えた PSR-14 の EventDispatcher と、ドキュメント、セキュリティ、コンテンツ、ライターの各イベントにまたがる型付きイベント階層があります。フェイルセーフな挙動もコードです。アトミックな出力書き込みは、文書化された time-of-check/time-of-use のギャップを塞ぎます。インプロセスの HTML パスにおける「リモートサブリソースなし」の保証は、構造的に強制される @security コントラクトです。高レベルの署名 API は、未署名の PDF を出力するのではなく、処理を中断する診断を発生させます。

エージェント安全性の特性は、NextPDF Connect のコードです。 Evidence { } Code-backed Evidence: Code-backed 四段階のリスクモデル（safe、caution、 review、approval-required）と確認ゲートがあり、このゲートは approval-required のツールに対して使い捨てのチャレンジトークンを発行し、 そのトークンが返されるまで処理を進めることを拒否します。ツールのリスクは、 厳密に二つの源――そのツール自身の宣言と、リスクを引き上げることしかできないオペレーターのオーバーライド――からのみ生じます。したがって、危険な範囲を黙って広げることはできません。

このページの構成方法そのものも標準裏付けです。 Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 は、 運用情報を、読者が実行するタスクに沿って構造化すること（チャンク化）を推奨しています。 そのため、この四つの段階は「観測する」「購読する」「検出する」「ゲートする」に対応しています。

実践例

以下のコードは、可観測性の接続点を示すものです。ライフサイクルイベントとレンダリングレポートをテレメトリに変換する PSR-14 リスナーです。これは接続点の例であり、メトリクスの出力先はあなたが用意します。

<?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,
        ]);
    }
}

要点は接続点であって、実装本体ではありません。エンジンは、型付きイベントと構造化レポートをあなたに渡します。何を転送し、サンプリングし、アラート対象にするかは、エンジンが意図的にあなたへ委ねている運用上の判断です。

よくある誤解

運用上の誤解とは、*「バイト列が返ってきたなら、うまくいった」*という考え方です。レンダリングは成功しても、なお劣化していることがあります。レイアウトがフォールバックした、外部画像がブロックされて黙って欠落した、有効なモードではある機能がサポートされていなかった、といったケースです。バイト列は存在します。しかし、そのドキュメントはテンプレートが意図したものではありません。エンジンがこれらを警告やフォールバック数として報告するのは、まさに「バイト列が返ってきた」を「正しくレンダリングされた」と取り違えないようにするためです。戻り値を唯一の成功シグナルとして扱うことこそ、この仕組みが防ぐために存在する誤りです。

Connect に固有の二つ目の誤解は、PDF ツールは「ただレンダリングするだけ」だからエージェントに公開しても安全だ、というものです。破壊的な操作、上書き操作、プライバシーに関わる操作が、人間による確認チャレンジの背後でゲートされているのには理由があります。そのゲートを迂回したり自動で応答したりすると、ゲートが取り除いているまさにそのリスクを再び持ち込むことになります。

限界と境界

• エンジンは計装を行いますが、あなたの可観測性スタックを運用するわけではありません。 エンジンはレポートと型付きイベントを発行します。収集、アラート、ダッシュボード、保持はあなたの責任です。
• no-op の可観測性がデフォルトです。 メトリクス、トレース、HSM 監査ログは、実際の実装をバインドするまで何もしません――これは意図的な設計であり、エンジンは配線ゼロで動作します。ただしこれは、オプトインするまで何も記録されないことを意味します。
• SSRF フェイルセーフはインプロセスの HTML パスに適用されます。 外部レンダラーのブリッジ（ブラウザ/Office）は、その性質上アウトバウンド呼び出しを行い、独自のトランスポート堅牢化を備えています。この保証は、あくまでインプロセスのパスに関するものです。
• 人間による確認ゲートは NextPDF Connect の特性です。 これはエージェント駆動の呼び出しを統制するものであり、一般的な PDF 機能ではありません。また、引数のハッシュではなく、ツール名と nonce に対してバインドされます。
• 高レベルの署名 API は早期に失敗します。これは配線済みの署名器ではありません。 運用上は、その診断をシグナルとして扱い、実際の署名には配線済みの低レベルパスを使ってください。
• このページはアーティファクト裏付けです。ここに挙げた接続点はいずれも実在のクラスまたはコントラクトですが、それらをうまく運用するのはあなたの責任です。

Observability and operational seams — edition availability

Edition	Availability
Core	○ RenderReport、PSR-14 イベントディスパッチャーと型付きイベント階層、no-op の可観測性コントラクト、アトミックな出力書き込み、 インプロセスの SSRF フェイルセーフは、すべて Core に含まれます。
Pro	○ セキュリティのライフサイクルイベント（暗号化/署名の適用）を追加し、 署名を使い始めると、運用上の意味を持ちます。
Enterprise	○ HSM 監査ログの接続点と、検証で見つかった事項を運用シグナルとして追加します。NextPDF Connect は、 エージェント駆動の高リスク操作に、人間による確認ゲートを追加します。

関連ドキュメント

• パイプラインモデル ― これらの可観測性接続点を可能にする段階的な構造と、その位置づけ。
• HSM 裏付けの署名 ― ハードウェアで裏付けられた鍵の運用形態と、監査境界の位置づけ。
• 大量ドキュメント生成 ― レンダリングごとのレポートを、大規模なキャパシティとヘルスシグナルに変える方法。

用語集

• RenderReport ― エンジンが生成する、レンダリングごとの不変で JSON シリアライズ可能なメトリクススナップショット。主要なヘルスシグナルとして使われる。
• PSR-14 ― イベントディスパッチャーの PHP 標準。NextPDF のディスパッチャーはこれに互換であり、使われていないときのオーバーヘッドはゼロ。
• 劣化パリティ ― 完了したものの、機能がフォールバックしたかサポートされなかったために、出力が理想とは異なるレンダリング。
• フォールバックの発生 ― レイアウトエンジンがより単純な挙動に置き換えたことを記録した事例（例：flex を block としてレンダリング）。
• SSRF（サーバーサイドリクエストフォージェリ） ― サーバーを騙して内部のターゲットへ要求を送らせる攻撃。インプロセスの HTML パスでは構造的に排除されている。
• 確認ゲート ― 高リスクなエージェント呼び出しツールが実行される前に、人間が中継する使い捨てトークンを要求する NextPDF Connect の仕組み。
• アトミック書き込み ― 並行する読み取り側に、以前のファイルか完全な新しいファイルのいずれかが見え、部分的なファイルは決して見えない出力書き込み。