NextPDF Connect におけるワーカーセーフなセッションライフサイクル

概要

長時間稼働する PHP ワーカー（RoadRunner、Swoole、Laravel Octane）では、適切なセッションライフサイクルを使用します。各リクエストで専用のドキュメントセッションを作成し、output_pdf の後に破棄します。フォント、ページ、ハンドルの状態が、ワーカーのリクエスト境界をまたいで漏れることはありません。対象ツールは create_pdf、set_font、add_text、output_pdf で、いずれも Core です。

インストール

composer require nextpdf/server

トランスポートをバインドします。このパターンは、どのトランスポートでも同じように機能します。

概念の概要

document_id は、1 つのリクエストにスコープされた不透明なハンドルです。ルールは リクエストごとに作成し、リクエストごとに破棄し、決してキャッシュも共有もしない です。デフォルトの destroy: true では、output_pdf がドキュメントをレンダリングし、単一のアトミックなステップでセッションを解放します。同じワーカー上の次のリクエストは、新しい独立したセッションを取得します。前のセッションのフォントとコンテンツは残りません。各ツールの結果は通常のトランスポートレスポンスです（PSR-18 §p2）。サーバーコード自体は、オートロード境界によって分離されています（PSR-4 §3）。セッションストアは、リクエストをまたぐ唯一の状態であり、id でキー付けされています。

API サーフェス

ツール	役割	リスク階層
`create_pdf`	リクエストごとのセッション開始	安全
`set_font`	アクティブなフォント設定（セッションごと）	注意
`add_text`	コンテンツ書き込み	注意
`output_pdf`	レンダリングとセッション破棄	承認必須/レビュー（base64）

ツールカタログが正式なカタログです。利用できるツールは、インストールされている階層によって異なります。

コードサンプル — クイックスタート

リクエスト 1：create_pdf → set_font → add_text → output_pdf（destroy: true）。同じワーカー上のリクエスト 2 は、まったく新しい create_pdf セッションを開始します。古い id はすでに無効です。フォントは引き継がれないため、再度設定してください。

コードサンプル — 本番

クリーンアップが必ず実行されるように、ライフサイクルをラップします。

リクエスト開始時にセッションを取得します。
コンテンツを構築します。
finally 相当のブロックで、セッションを破棄する output_pdf を呼び出します。出力後に検査するフローのために destroy: false を使用した場合は、代わりにセッションを明示的に破棄します。

document_id を、ワーカーグローバル、静的変数、または共有コンテナに決して保存しないでください。この値をコルーチン、ファイバー、またはリクエストハンドラー間で決して渡さないでください。

エッジケースと注意点

破棄後に id を再利用した場合。 不明なドキュメントとしてエラーを返します。リクエストごとに新しいセッションを作成してください。
output_pdf を忘れた場合。 セッションの TTL が切れるか、プロセスが再起動するまで、メモリ使用量が静かに増え続けます。必ず最終処理を行ってください。
負荷時のセッション上限。 ストアには同時実行の上限があります。速やかに破棄することで、上限超過を避けられます。
クリーンアップなしの destroy: false。 メモリ使用量が徐々に増えていきます。出力後に明示的に検査するフローでのみ使用し、その後セッションを破棄してください。
同時リクエスト間で id を共有した場合。 出力を破損させる競合状態になります。各リクエストは自身のセッションを所有します。

パフォーマンス

リクエストごとの出力は数 KB です。利点は、ワーカーの稼働期間全体を通じて、メモリ使用量を上限内に収められることです。プロファイルは structural です。

セキュリティに関する注意

セッションの分離は、機密性を支える特性でもあります。ハンドルが共有されず、出力時にセッションが破棄されるため、あるリクエストのコンテンツが別のリクエストに到達することはありません。

適合性

ステートメント	仕様	条項	reference_id
各ツールの結果は通常のトランスポートレスポンス。	PSR-18	§p2
コードはオートロードのクラス→ファイルのマッピングによって分離。	PSR-4	§3

商用コンテキスト

該当なし。すべてのツールが Core です。

トランスポートの可用性

トランスポート	利用可否	備考
MCP（stdio）	可	ワーカーごとに 1 つの stdio プロセスが一般的。
REST	可	HTTP リクエスト境界とセッション境界の対応。
gRPC	可	RPC シーケンスごとに 1 セッション。

HITL リスク階層

create_pdf は Safe です。set_font と add_text は Caution です。output_pdf は Approval Required で、base64 モードでは Review に格下げされます。ワーカーでは base64 出力が一般的な経路であり、ゲート対象はありません（HITL リスク階層）。

確認ゲートの JSON エンベロープ

base64 ワーカー出力：

{ "allowed": true }