NextPDF Connect — gRPC トランスポート

概要

gRPC トランスポートは、RoadRunner の gRPC ワーカープール内で bin/nextpdf-grpc を実行します。nextpdf.connect.v1.NextPDFConnect サービスを提供し、サーバーストリーミングによるレンダリングをサポートします。呼び出しメタデータ内のベアラートークンで認証し、結合デプロイプロファイルでは相互 TLS が構成されます。

インストール

composer require nextpdf/server
./vendor/bin/rr get-binary

概念の概要

gRPC サービスは、Spiral RoadRunner の gRPC ワーカーを介して、REST トランスポートと同じアプリケーションサービス（レンダリング、ジョブ、セッション、ケイパビリティ、オペレーション）を共有します。ワイヤーコントラクトは Protocol Buffers パッケージ nextpdf.connect.v1 で、パッケージに同梱される .proto ファイルで定義されています。

認証は、REST のキーストアと検証をそのまま再利用します。gRPC オーセンティケーターは authorization メタデータキーを読み取り（gRPC の呼び出しメタデータは HTTP/2 ヘッダーとして伝送されます）、Bearer npk_live_… トークンを解析し、kid と SHA-256 ダイジェストを定時間比較で検証します。キーが欠落している、不正な形式である、不明である、無効化されている、または期限切れの場合、オーセンティケーターはその呼び出しを gRPC の UNAUTHENTICATED ステータスで失敗させます。認証の実装が正しくない場合は、OWASP API2:2023 の Broken Authentication リスクに該当します。定時間のダイジェスト比較がその緩和策です。

API サーフェス

サービス RPC

nextpdf.connect.v1.NextPDFConnect サービスは、ユーナリ RPC とサーバーストリーミング RPC を公開します。

RPC	形態	用途
`Render`	ユーナリ	同期レンダリング
`RenderStream`	サーバーストリーミング	レンダリング（チャンク単位でストリーミング）
`SubmitJob` / `GetJobStatus` / `GetJobResult` / `CancelJob`	ユーナリ	非同期ジョブ
`GetJobResultStream`	サーバーストリーミング	非同期結果（ストリーミング）
`CreateSession` / `GetSession` / `DestroySession` / `SessionOperation` / `SessionRender`	ユーナリ	ステートフルセッション
`SessionRenderStream`	サーバーストリーミング	セッションレンダリング（ストリーミング）
`ExecuteCapability` / `GetCapabilities`	ユーナリ	ケイパビリティのディスパッチとイントロスペクション
`HealthCheck` / `ReadinessCheck`	ユーナリ	ライブネスとレディネス

ExecuteCapability は、REST のオペレーションルートと同じティアゲート対象オペレーションをディスパッチします。Pro および Enterprise のオペレーションには、それらのパッケージがインストールされている場合にのみアクセスできます。署名がディスパッチされる場合、Pro を有効にした NextPDF Connect が提供するのは PAdES baseline-B（B-B）署名のみです。

ストリーミング

サーバーストリーミング RPC は、結果を順序付きのチャンクストリームとして送信します。この方式は大きな PDF や逐次配信に適しています。ユーナリ RPC は、完全な結果を 1 つのメッセージで返します。

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

gRPC 専用プロファイルを起動します。

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.grpc.yaml

同梱の proto から、使用する gRPC ツールチェーンでクライアントを生成します。

# proto/nextpdf/connect/v1/*.proto — package nextpdf.connect.v1
protoc --proto_path=proto --<lang>_out=. proto/nextpdf/connect/v1/service.proto

すべての呼び出しで、call-credential メタデータの authorization を Bearer npk_live_{kid}_{secret} に設定します。

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

結合プロファイルは、相互 TLS を有効にして gRPC を実行します。

export NEXTPDF_GRPC_TLS_KEY=/run/secrets/grpc-server.key
export NEXTPDF_GRPC_TLS_CERT=/run/secrets/grpc-server.crt
export NEXTPDF_GRPC_TLS_CA=/run/secrets/grpc-client-ca.crt
./vendor/bin/rr serve -c .rr.full.yaml

このプロファイルでは、サーバーは自身の証明書を提示し、クライアント証明書を要求して検証します（require_and_verify_client_cert）。接続が切断された後でも、冪等なユーナリのジョブ送信は安全に再試行できます。冪等なリクエストを繰り返しても、1 回のリクエストと同じ意図された効果になります（RFC 9110 §9.2.2）。

エッジケースと注意点

HTTP ステータスではなく UNAUTHENTICATED が返ります。 トークンが不正な場合、または欠落している場合、RPC は gRPC の UNAUTHENTICATED ステータスコードで失敗し、401 は返しません。ベアラースキームと npk_live_ 形式は、REST と同一です。
過剰な認証前試行に対する RESOURCE_EXHAUSTED。 単一のクライアント識別子からの認証前試行が繰り返されると、スロットリングされ、gRPC の RESOURCE_EXHAUSTED ステータスで失敗します。これは HTTP 429 に相当する gRPC のステータスであり、REST サーフェスが適用するものと同じアンチオートメーション体制です。この制御はデフォルトで有効なため、クライアントは直ちに再試行せず、バックオフしてください。HTTP のレート制限体制については、/connect/production-usage/. を参照してください。
相互 TLS はデフォルトではなく、デプロイ時の構成です。 gRPC リスナーには、正しくプロビジョニングされたサーバー鍵、サーバー証明書、およびクライアント CA のシークレットが必要です。これらがない場合、結合プロファイルはサービスを提供しません。これは意図された動作です。これらの生成とローテーションは帯域外で行ってください。
ティアゲーティングは引き続き適用されます。 Pro または Enterprise のオペレーションに対する ExecuteCapability には、パッケージのインストールと、権限が付与されたキーが必要です。
高リスクのオペレーションは引き続きゲートされます。 ApprovalRequired ツールを駆動するオペレーションは、同じ human-in-the-loop ゲートを通過します。 /connect/hitl-risk-tiers/. を参照してください。

パフォーマンス

各 gRPC ワーカーは、一度に 1 件の呼び出しを処理します。このプールのサイズは HTTP プール（デフォルトは 2 ワーカー）とは独立して設定されます。gRPC クライアントは通常、数が少なく長寿命であるため、このプールは HTTP プールより小さく設定されることが一般的です。大きな出力では、PDF 全体を 1 つのメッセージにバッファリングしないよう、サーバーストリーミング RPC を使用してください。

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

信頼できないネットワークでは、gRPC トランスポートを相互 TLS で実行してください。平文リスナーを使用してはいけません。クライアント CA、サーバー鍵、サーバー証明書は、実行時にマウントするシークレットとして扱い、イメージに組み込まないでください。ベアラー認証は、証明書の代わりではなく、証明書に加えて適用されます。これは、正しいデプロイ構成を必要とするセキュリティ姿勢です。/connect/security-and-operations/ および /connect/deployment/. を参照してください。

準拠

主張	出典	`reference_id`
認証の不備は API のセキュリティを損なう	OWASP API Security Top 10、API2:2023 より
冪等なリクエストは失敗後に再試行可能	RFC 9110 §9.2.2

gRPC プロトコル自体は、ゲート対象の標準コーパスには含まれない外部仕様です。正式なワイヤーコントラクトは、同梱の nextpdf.connect.v1 Protocol Buffers 定義です。

商用に関する補足

ExecuteCapability が Pro および Enterprise のオペレーションを利用できるのは、サーバーとともに nextpdf/premium がインストールされている場合のみです。トランスポート、認証、TLS の構成は、インストールされているティアによって変わることはありません。