NextPDF Connect — gRPC 傳輸

概覽

gRPC 傳輸會在 RoadRunner 的 gRPC worker 池中執行 bin/nextpdf-grpc。它提供 nextpdf.connect.v1.NextPDFConnect 服務，支援伺服器串流繪製，會以呼叫 metadata 中的 bearer token 進行驗證，並在合併部署設定檔中設定雙向 TLS。

安裝

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

概念總覽

gRPC 服務位於 Spiral RoadRunner 的 gRPC worker 後方，與 REST 傳輸共用同一組應用服務——繪製、jobs、sessions、capabilities、operations。線路合約是 Protocol Buffers 套件 nextpdf.connect.v1，由套件隨附的 .proto 檔定義。

驗證沿用 REST 的金鑰儲存區與驗證流程。gRPC 驗證器會讀取 authorization metadata 鍵——gRPC 呼叫 metadata 是透過 HTTP/2 標頭傳遞——剖析 Bearer npk_live_… token，並使用常數時間比對來驗證 kid 與 SHA-256 摘要。當金鑰遺失、格式錯誤、未知、已停用或已過期時，驗證器會以 gRPC UNAUTHENTICATED 狀態使呼叫失敗。驗證若實作不正確，即屬 OWASP API2:2023 的失效驗證（Broken Authentication）風險；常數時間摘要比對就是其緩解措施。

API 介面

服務 RPC

這個 nextpdf.connect.v1.NextPDFConnect 服務提供一元（unary）與伺服器串流 RPC：

RPC	形式	用途
`Render`	一元（unary）	同步繪製
`RenderStream`	伺服器串流	繪製，以區塊串流傳送
`SubmitJob` / `GetJobStatus` / `GetJobResult` / `CancelJob`	一元（unary）	非同步 jobs
`GetJobResultStream`	伺服器串流	非同步結果，以串流傳送
`CreateSession` / `GetSession` / `DestroySession` / `SessionOperation` / `SessionRender`	一元（unary）	具狀態 sessions
`SessionRenderStream`	伺服器串流	session 繪製，以串流傳送
`ExecuteCapability` / `GetCapabilities`	一元（unary）	capability 分派與自我檢視
`HealthCheck` / `ReadinessCheck`	一元（unary）	存活與就緒檢查

由 ExecuteCapability 分派的階層受控（tier-gated）operations，與 REST operation 路由相同；Pro 與 Enterprise operations 只有在安裝對應套件時才能存取。在簽章分派方面，搭配 Pro 的 NextPDF Connect 僅提供 PAdES baseline-B（B-B）簽章。

串流

伺服器串流 RPC 會將結果以有序區塊串流送出，適合大型 PDF 與漸進式傳遞。一元（unary）RPC 則在單一訊息中回傳完整結果。

程式碼範例——快速開始

啟動只包含 gRPC 的設定檔：

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

使用你的 gRPC 工具鏈，從隨附的 proto 產生用戶端：

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

每次呼叫都將 authorization 呼叫憑證 metadata 設為 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）。連線中斷後，重試具冪等性的一元 job 提交是安全的——重複一個冪等請求的預期效果，與只送一次請求相同（RFC 9110 §9.2.2）。

邊界情況與陷阱

是 UNAUTHENTICATED，而非 HTTP 狀態碼。 token 錯誤或遺失時，RPC 會以 gRPC UNAUTHENTICATED 狀態碼失敗，而非 401。bearer 機制與 npk_live_ 格式都與 REST 完全相同。
過多的預先驗證嘗試會回傳 RESOURCE_EXHAUSTED。 來自同一用戶端身分的重複預先驗證嘗試會受到節流，並以 gRPC RESOURCE_EXHAUSTED 狀態失敗——也就是 HTTP 429 在 gRPC 的對應，也是 REST 介面所採用的同一套反自動化態勢。這項控制預設為啟用，因此用戶端應退避（back off），而非立即重試。HTTP 速率限制態勢請參見 /connect/production-usage/。
雙向 TLS 是一項部署設定，而非預設。 gRPC 監聽器需要正確佈建的伺服器金鑰、伺服器憑證與用戶端 CA secrets。如果缺少這些項目，合併設定檔就不會提供服務；這是刻意設計。請以頻外（out of band）方式產生並輪替它們。
階層控管仍然適用。 針對 Pro 或 Enterprise operation 的 ExecuteCapability，需要已安裝該套件並具備有權限的金鑰。
高風險 operations 仍會受到控管。 會驅動 ApprovalRequired 工具的 operations，會通過同一道人為介入（human-in-the-loop）關卡。請參閱 /connect/hitl-risk-tiers/。

效能

每個 gRPC worker 一次處理一個呼叫。這個池的大小獨立於 HTTP 池（預設兩個 worker）的設定，通常較小，因為 gRPC 用戶端較少且生命週期較長。大型輸出請使用伺服器串流 RPC，以避免把整份 PDF 緩衝在單一訊息中。

安全性注意事項

在任何不受信任的網路上，都必須以雙向 TLS 執行 gRPC 傳輸——絕不使用明文監聽器。請將用戶端 CA、伺服器金鑰與伺服器憑證視為在執行階段掛載的 secrets，絕不烘焙進映像檔。bearer 驗證是在憑證之外額外強制執行，而非取代憑證。這是一種需要正確部署設定才能成立的安全姿態。請參閱 /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 只有在伺服器端安裝 nextpdf/premium 時，才能觸及 Pro 與 Enterprise operations。已安裝的階層不會改變傳輸、驗證與 TLS 設定。

另請參閱

/connect/security-and-operations/——驗證、雙向 TLS、威脅模型
/connect/deployment/——合併 RoadRunner 設定檔與 TLS secrets
/transports/mcp/ · /transports/rest/——其他傳輸
/connect/tool-catalog/——ExecuteCapability 如何對映到 catalog
/connect/production-usage/——jobs 與冪等重試