NextPDF Connect — transport gRPC

Tổng quan nhanh

Transport gRPC chạy bin/nextpdf-grpc trong một nhóm worker gRPC của RoadRunner. Transport này phục vụ dịch vụ nextpdf.connect.v1.NextPDFConnect, hỗ trợ kết xuất kiểu server-streaming, xác thực từng lệnh gọi bằng bearer token trong metadata và được cấu hình để dùng Transport Layer Security (TLS) hai chiều trong profile triển khai kết hợp.

Cài đặt

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

Tổng quan khái niệm

Dịch vụ gRPC sử dụng cùng các dịch vụ ứng dụng như transport Representational State Transfer (REST): render, jobs, sessions, capabilities và operations. Một worker gRPC Spiral RoadRunner xử lý các lệnh gọi. Hợp đồng wire là gói Protocol Buffers nextpdf.connect.v1, được định nghĩa trong các tệp .proto đi kèm với gói.

Xác thực dùng cùng key store và cùng quy trình kiểm tra như REST. Bộ xác thực gRPC đọc khóa metadata authorization, được gRPC mang theo dưới dạng header Hypertext Transfer Protocol version 2 (HTTP/2). Bộ này phân tích token Bearer npk_live_…, rồi kiểm tra định danh khóa (kid) và digest SHA-256 bằng phép so sánh thời gian hằng định. Bộ xác thực làm lệnh gọi thất bại với trạng thái gRPC UNAUTHENTICATED khi khóa bị thiếu, sai định dạng, không xác định, bị vô hiệu hóa hoặc đã hết hạn. Triển khai xác thực sai là rủi ro OWASP API2:2023 Broken Authentication; phép so sánh digest thời gian hằng định giúp giảm thiểu rủi ro này.

Bề mặt API

Các RPC của dịch vụ

Dịch vụ nextpdf.connect.v1.NextPDFConnect cung cấp các lệnh gọi thủ tục từ xa (RPC) kiểu unary và server-streaming:

RPC	Kiểu	Mục đích
Render	unary	Kết xuất đồng bộ
RenderStream	server-streaming	Kết xuất, truyền theo từng chunk
SubmitJob / GetJobStatus / GetJobResult / CancelJob	unary	Tác vụ bất đồng bộ
GetJobResultStream	server-streaming	Kết quả bất đồng bộ, truyền theo luồng
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender	unary	Phiên có trạng thái
SessionRenderStream	server-streaming	Kết xuất phiên, truyền theo luồng
ExecuteCapability / GetCapabilities	unary	Điều phối và truy vấn nội tại capability
HealthCheck / ReadinessCheck	unary	Liveness và readiness

ExecuteCapability điều phối cùng các operation bị giới hạn theo tier như các route operation của REST. Chỉ có thể truy cập các operation Pro và Enterprise khi các gói tương ứng đã được cài đặt. Đối với việc ký, NextPDF Connect cùng với Pro chỉ cung cấp khả năng ký Portable Document Format (PDF) Advanced Electronic Signatures (PAdES) baseline-B (B-B).

Streaming

Các RPC server-streaming gửi kết quả dưới dạng một luồng chunk có thứ tự, phù hợp với tệp PDF lớn và cách phân phối tăng dần. Các RPC unary trả về toàn bộ kết quả trong một thông điệp.

Mẫu mã — bắt đầu nhanh

Khởi động profile chỉ-gRPC:

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

Tạo một client từ các tệp .proto đi kèm bằng bộ công cụ gRPC của bạn:

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

Trong mỗi lệnh gọi, hãy đặt call credential trong metadata authorization thành Bearer npk_live_{kid}_{secret}.

Mẫu mã — Production

Profile kết hợp chạy gRPC với TLS hai chiều:

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

Trong profile này, máy chủ trình chứng chỉ của mình, đồng thời yêu cầu và xác minh chứng chỉ của máy khách (require_and_verify_client_cert). Có thể thử lại một lần gửi tác vụ unary có tính lũy đẳng sau khi kết nối bị ngắt: việc lặp lại một yêu cầu lũy đẳng có cùng tác động dự kiến như một yêu cầu duy nhất (RFC 9110 §9.2.2).

Trường hợp đặc biệt và điều cần lưu ý

• UNAUTHENTICATED, không phải là một trạng thái HTTP. Token sai hoặc bị thiếu sẽ làm RPC thất bại với mã trạng thái gRPC UNAUTHENTICATED, chứ không phải 401. Lược đồ bearer và định dạng npk_live_ giống hệt như ở REST.

• RESOURCE_EXHAUSTED khi có quá nhiều lần thử trước khi xác thực. Các lần thử trước khi xác thực lặp lại từ cùng một danh tính client sẽ bị điều tiết và thất bại với trạng thái gRPC RESOURCE_EXHAUSTED. Trạng thái này tương đương với HTTP 429 trong gRPC, đồng thời áp dụng cùng tư thế chống tự động hóa như REST. Cơ chế kiểm soát này được bật theo mặc định, vì vậy client nên chờ giãn cách thay vì thử lại ngay lập tức. Xem tư thế giới hạn tốc độ HTTP tại /connect/production-usage/.

• TLS hai chiều là một cấu hình triển khai, không phải mặc định. Listener gRPC yêu cầu các secret được cấp phát đúng, gồm khóa máy chủ, chứng chỉ máy chủ và certificate authority (CA) của máy khách. Nếu thiếu chúng, profile kết hợp sẽ không phục vụ; đây là chủ đích. Hãy tạo và xoay vòng chúng qua kênh riêng.

• Giới hạn theo tier vẫn được áp dụng. ExecuteCapability cho một operation Pro hoặc Enterprise yêu cầu gói phải được cài đặt và khóa phải có quyền tương ứng.

• Các operation rủi ro cao vẫn bị kiểm soát. Các operation kích hoạt một công cụ ApprovalRequired sẽ dùng cùng cổng kiểm soát có sự tham gia của con người. Xem /connect/hitl-risk-tiers/.

Hiệu năng

Mỗi worker gRPC xử lý một lệnh gọi tại một thời điểm. Nhóm worker này được định cỡ độc lập với nhóm HTTP (mặc định hai worker) và thường nhỏ hơn vì có ít client gRPC hơn, đồng thời các kết nối của chúng tồn tại lâu hơn. Hãy dùng các RPC server-streaming cho kết quả lớn để tránh phải buffer toàn bộ PDF trong một thông điệp.

Ghi chú bảo mật

Hãy chạy transport gRPC với TLS hai chiều trên mọi mạng không đáng tin cậy; không bao giờ dùng listener văn bản thuần. Hãy coi CA của máy khách, khóa máy chủ và chứng chỉ máy chủ là các secret được gắn vào lúc chạy, không bao giờ nhúng sẵn vào image. Xác thực bearer được áp dụng bổ sung cho chứng chỉ, chứ không thay thế chứng chỉ. Tư thế này đòi hỏi cấu hình triển khai đúng đắn. Xem /connect/security-and-operations/ và /connect/deployment/.

Tuân thủ

Tuyên bố	Nguồn	reference_id
Xác thực bị hỏng làm tổn hại đến bảo mật API	OWASP API Security Top 10, API2:2023
Yêu cầu lũy đẳng có thể thử lại sau khi thất bại	RFC 9110 §9.2.2

Bản thân giao thức gRPC là một đặc tả bên ngoài, nằm ngoài kho tiêu chuẩn được kiểm soát. Các định nghĩa Protocol Buffers nextpdf.connect.v1 đi kèm là hợp đồng wire chính thức.

Bối cảnh thương mại

ExecuteCapability chỉ truy cập được các operation Pro và Enterprise khi nextpdf/premium được cài đặt cùng với máy chủ. Các tier đã cài đặt không thay đổi cấu hình transport, xác thực hay TLS.

Xem thêm

• /connect/security-and-operations/ — xác thực, TLS hai chiều, mô hình mối đe dọa
• /connect/deployment/ — profile RoadRunner kết hợp và các secret TLS
• /transports/mcp/ · /transports/rest/ — các transport còn lại
• /connect/tool-catalog/ — cách ExecuteCapability ánh xạ tới catalog
• /connect/production-usage/ — tác vụ và thử lại lũy đẳng