NextPDF Connect の本番運用

概要

本番環境の NextPDF Connect デプロイメントでは、ヘルスチェックとレディネスチェック、同期および非同期のレンダリングパス、冪等性制御、クライアント単位および IP 単位のレート制限、オプションのステートフルセッションなど、運用面の機能を公開します。このページでは、それらを本番環境で運用する方法を説明します。

インストール

composer require nextpdf/server

概念の概要

REST トランスポートは PSR-15 のミドルウェアパイプラインです。各リクエストは、リクエスト ID の割り当て、ボディサイズの制限、CORS、認証、ケイパビリティ認可、レート制限、冪等性、タイムアウトの順にミドルウェアを通過し、その後ハンドラーに到達します。gRPC トランスポートは、RoadRunner の gRPC ワーカーを介して同じアプリケーションサービスを再利用します。

レンダリングには 2 つの形式があります。同期の POST /api/v1/render は操作を実行し、レスポンスで PDF を返します。非同期 ジョブは POST /api/v1/jobs を使用します。ジョブ ID を含むレスポンスを即座に返し、結果は後から GET /api/v1/jobs/{id}/result で取得します。ジョブは共有 SQLite ストアに永続化されるため、どのワーカーでもステータスや結果の問い合わせに応答できます。

API サーフェス

ヘルスとレディネス

エンドポイント	認証	意味
`GET /healthz`	なし	プロセス稼働中
`GET /readyz`	なし	サーバーのリクエスト受付準備完了

ライブネスプローブには /healthz を、レディネスプローブには /readyz を指定します。どちらのエンドポイントも匿名アクセスのため、オーケストレーターに資格情報は不要です。

非同期ジョブ

エンドポイント	メソッド	目的
`/api/v1/jobs`	`POST`	レンダリングジョブの送信
`/api/v1/jobs/{id}`	`GET`	ジョブステータス
`/api/v1/jobs/{id}/result`	`GET`	ジョブ結果（PDF）
`/api/v1/jobs/{id}`	`DELETE`	ジョブのキャンセル

セッション（オプトイン）

環境変数 NEXTPDF_SESSIONS_ENABLED が true で、かつツールが利用可能な場合、セッションエンドポイントではステートフルなビルドを利用できます。セッションを作成し、ページ、テキスト、画像、テーブル、HTML を追加して、フォントを設定してからレンダリングします。セッションには、クライアント単位の上限とアイドルタイムアウトが設定されています。デフォルトでは無効です。

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

非同期ジョブを送信して、結果をポーリングします。

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

コードサンプル — 本番環境

冪等性キーを送信して、リクエストを安全に再試行できるようにします。

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

同じ冪等性キーで再送されたリクエストは、2 つ目のジョブを作成せず、元の結果を返します。これにより、通信障害後でも送信を安全に繰り返せます。この安全性は、冪等なメソッドが備える特性です。つまり、リクエストを繰り返しても、意図された効果は 1 回送信した場合と同じです（RFC 9110 §9.2.2）。そのため、レスポンスを読み取る前に接続が切断された場合でも、リクエストを自動的に再試行できます（RFC 9110 §9.2.2）。

エッジケースと注意点

ワーカー間で正しくレート制限を行うには Redis が必要です。 クライアント単位および IP 単位のリミッターは、構成されたストアを使用します。インメモリストアで複数のワーカーを実行している場合、各ワーカーが独立してカウントするため、実効的な制限値はワーカー数の分だけ増えます。複数ワーカーのプールでは、必ず Redis ストアを使用してください。
スロットリングされたリクエストは 429 を返します。 制限を超えると、サーバーはレート制限のステータスセマンティクスに従い、429 Too Many Requests と Retry-After ヘッダーで応答します（RFC 6585 §4）。すぐに再試行せず、Retry-After を尊重してください。
ジョブの結果は無期限ではありません。 ジョブストアは、NEXTPDF_JOB_GC_MAX_AGE_SECONDS の経過後に古いエントリをガベージコレクションします。結果は期限切れになる前に取得してください。
セッションはメモリを消費します。 セッションは処理中のドキュメントを保持します。クライアント単位のセッション上限とアイドルタイムアウトにより、このコストを抑えます。最悪ケースのメモリを見積もらずに、これらの値を引き上げないでください。

パフォーマンス

同期パスは、レンダリングが完了するまでワーカーを占有します。大規模または時間のかかるレンダリングでは、非同期ジョブパスを優先してください。非同期ジョブパスはワーカーをただちに解放し、クライアントが結果をポーリングします。観測されたレンダリングレイテンシと同時実行数に基づいて、ワーカープールのサイズを調整してください。RoadRunner のメトリクスエンドポイントを監視してください。

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

ヘルスチェック以外のすべてのエンドポイントには、有効な API キーが必要です。クライアントのティアにより、許可される操作とペイロードサイズが制限されます。冪等性キーはクライアントが指定します。これらは不透明な値として扱い、論理操作ごとに一意にしてください。詳しくは /connect/security-and-operations/. を参照してください。

適合性

主張	出典	`reference_id`
冪等性: 繰り返したリクエスト = 1 回分の効果	RFC 9110 §9.2.2
冪等なリクエストは障害後に再試行可能	RFC 9110 §9.2.2
`429` + `Retry-After`（レート制限用）	RFC 6585 §4

商用コンテキスト

対象のツールがインストールされている場合、ティアごとのペイロードおよびタイムアウトの上限は、Pro キーおよび Enterprise キーで引き上げられます。デフォルトのデプロイメントには、core ティアの上限が適用されます。