NextPDF Connect — ทรานสปอร์ต gRPC

ภาพรวมโดยย่อ

ทรานสปอร์ต gRPC รัน bin/nextpdf-grpc ในพูลเวิร์กเกอร์ gRPC ของ RoadRunner ทรานสปอร์ตนี้ให้บริการ nextpdf.connect.v1.NextPDFConnect รองรับการเรนเดอร์แบบ server-streaming ยืนยันตัวตนแต่ละการเรียกด้วย bearer token ใน metadata และตั้งค่าให้ใช้ mutual Transport Layer Security (TLS) ในโปรไฟล์การปรับใช้แบบรวม

การติดตั้ง

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

ภาพรวมเชิงแนวคิด

บริการ gRPC ใช้ชุดแอปพลิเคชันเซอร์วิสเดียวกับทรานสปอร์ต Representational State Transfer (REST) ได้แก่ render, jobs, sessions, capabilities และ operations เวิร์กเกอร์ gRPC ของ Spiral RoadRunner จัดการการเรียกเหล่านี้ สัญญาการสื่อสารระดับ wire คือแพ็กเกจ Protocol Buffers nextpdf.connect.v1 ซึ่งกำหนดโดยไฟล์ .proto ที่มาพร้อมกับแพ็กเกจ

การยืนยันตัวตนใช้ key store และการตรวจสอบความถูกต้องชุดเดียวกับ REST ตัวยืนยันตัวตนของ gRPC อ่านคีย์ metadata authorization ซึ่ง gRPC ส่งผ่านเป็นเฮดเดอร์ Hypertext Transfer Protocol version 2 (HTTP/2) ตัวยืนยันตัวตนแยกวิเคราะห์โทเคน Bearer npk_live_… จากนั้นตรวจสอบความถูกต้องของตัวระบุคีย์ (kid) และ SHA-256 digest ด้วยการเปรียบเทียบแบบ constant-time ตัวยืนยันตัวตนทำให้การเรียกล้มเหลวด้วยสถานะ UNAUTHENTICATED ของ gRPC เมื่อคีย์หายไป มีรูปแบบไม่ถูกต้อง ไม่รู้จัก ถูกปิดใช้งาน หรือหมดอายุ การนำการยืนยันตัวตนไปใช้อย่างไม่ถูกต้องคือความเสี่ยง OWASP API2:2023 Broken Authentication การเปรียบเทียบ digest แบบ constant-time ช่วยลดความเสี่ยงนี้

พื้นผิว API

RPC ของบริการ

บริการ nextpdf.connect.v1.NextPDFConnect ให้บริการ remote procedure call (RPC) ทั้งแบบ unary และ server-streaming ดังนี้

RPC	รูปแบบ	วัตถุประสงค์
Render	unary	การเรนเดอร์แบบ synchronous
RenderStream	server-streaming	เรนเดอร์และสตรีมเป็นชังก์
SubmitJob / GetJobStatus / GetJobResult / CancelJob	unary	งานแบบ async
GetJobResultStream	server-streaming	สตรีมผลลัพธ์แบบ async
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender	unary	เซสชันแบบ stateful
SessionRenderStream	server-streaming	เรนเดอร์เซสชันแบบสตรีม
ExecuteCapability / GetCapabilities	unary	การส่งต่อและการตรวจสอบความสามารถ
HealthCheck / ReadinessCheck	unary	liveness และ readiness

ExecuteCapability ส่งต่อ operation ภายใต้ข้อจำกัดตามระดับชุดเดียวกับเส้นทาง operation ของ REST operation ของ Pro และ Enterprise จะเข้าถึงได้ก็ต่อเมื่อติดตั้งแพ็กเกจเหล่านั้น สำหรับการลงนาม NextPDF Connect เมื่อมี Pro จะรองรับการลงนามแบบ Portable Document Format (PDF) Advanced Electronic Signatures (PAdES) baseline-B (B-B) เท่านั้น

การสตรีม

RPC แบบ server-streaming ส่งผลลัพธ์เป็นสตรีมของชังก์ตามลำดับ ซึ่งเหมาะกับไฟล์ PDF ขนาดใหญ่และการส่งมอบแบบเพิ่มทีละส่วน RPC แบบ unary คืนผลลัพธ์ทั้งหมดในข้อความเดียว

ตัวอย่างโค้ด — เริ่มต้นใช้งานอย่างรวดเร็ว

เริ่มโปรไฟล์ 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

สำหรับทุกการเรียก ให้ตั้งค่า metadata ของ call-credential authorization เป็น Bearer npk_live_{kid}_{secret}

ตัวอย่างโค้ด — โปรดักชัน

โปรไฟล์แบบรวมจะรัน gRPC ด้วย mutual TLS

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) การลองส่งงานแบบ unary ที่เป็น idempotent ซ้ำหลังการเชื่อมต่อหลุดนั้นปลอดภัย เพราะการส่งคำขอที่เป็น idempotent ซ้ำให้ผลลัพธ์ตามที่ตั้งใจเหมือนกับการส่งคำขอเพียงครั้งเดียว (RFC 9110 §9.2.2)

กรณีขอบและข้อควรระวัง

• UNAUTHENTICATED ไม่ใช่สถานะ HTTP โทเคนที่ไม่ถูกต้องหรือหายไปทำให้ RPC ล้มเหลวด้วยรหัสสถานะ UNAUTHENTICATED ของ gRPC ไม่ใช่ 401 โดยใช้รูปแบบ bearer scheme และ npk_live_ เหมือนกับ REST ทุกประการ

• RESOURCE_EXHAUSTED เมื่อมีการพยายาม pre-auth มากเกินไป การพยายาม pre-authentication ซ้ำๆ จากอัตลักษณ์ไคลเอนต์เดียวกันจะถูกจำกัดอัตราและล้มเหลวด้วยสถานะ RESOURCE_EXHAUSTED ของ gRPC สถานะนี้เทียบเท่ากับ HTTP 429 ในฝั่ง gRPC และใช้มาตรการต่อต้าน automation แบบเดียวกับ REST การควบคุมนี้เปิดใช้งานเป็นค่าเริ่มต้น ดังนั้นไคลเอนต์ควรเว้นระยะการเรียกแทนที่จะลองใหม่ทันที ดูแนวทางการจำกัดอัตรา HTTP ได้ที่ /connect/production-usage/

• mutual TLS เป็นการตั้งค่าระดับการปรับใช้ ไม่ใช่ค่าเริ่มต้น ตัวรับฟัง gRPC ต้องการ secret ของ server key, server certificate และ client certificate authority (CA) ที่จัดเตรียมไว้อย่างถูกต้อง หากไม่มีรายการเหล่านี้ โปรไฟล์แบบรวมจะไม่ให้บริการ ซึ่งเป็นการออกแบบโดยตั้งใจ ให้สร้างและหมุนเวียนรายการเหล่านี้นอกช่องทาง

• การจำกัดตามระดับยังคงมีผล ExecuteCapability สำหรับ operation ของ Pro หรือ Enterprise ต้องมีการติดตั้งแพ็กเกจและมีคีย์ที่ได้รับสิทธิ์

• operation ที่มีความเสี่ยงสูงยังคงถูกควบคุม operation ที่ขับเคลื่อนเครื่องมือแบบ ApprovalRequired ใช้การควบคุมแบบ human-in-the-loop เดียวกัน ดู /connect/hitl-risk-tiers/.

ประสิทธิภาพ

เวิร์กเกอร์ gRPC แต่ละตัวจัดการหนึ่งการเรียกในแต่ละครั้ง ขนาดพูลถูกกำหนดแยกจากพูล HTTP (ค่าเริ่มต้นคือเวิร์กเกอร์สองตัว) และมักจะเล็กกว่าเพราะมีไคลเอนต์ gRPC น้อยกว่า อีกทั้งการเชื่อมต่อของไคลเอนต์เหล่านั้นอยู่ได้นานกว่า ใช้ RPC แบบ server-streaming สำหรับเอาต์พุตขนาดใหญ่เพื่อหลีกเลี่ยงการบัฟเฟอร์ PDF ทั้งไฟล์ในข้อความเดียว

หมายเหตุด้านความปลอดภัย

รันทรานสปอร์ต gRPC ด้วย mutual TLS บนทุกเครือข่ายที่ไม่น่าเชื่อถือ อย่าใช้ตัวรับฟังแบบ plaintext เป็นอันขาด ให้ถือว่า client CA, server key และ server certificate เป็น secret ที่ mount ตอนรันไทม์ อย่าฝังไว้ในอิมเมจเป็นอันขาด การยืนยันตัวตนด้วย bearer บังคับใช้เพิ่มเติมจากใบรับรอง ไม่ใช่สิ่งทดแทนใบรับรอง แนวทางนี้ต้องการการตั้งค่าการปรับใช้ที่ถูกต้อง ดู /connect/security-and-operations/ และ /connect/deployment/

การปฏิบัติตามมาตรฐาน

คำกล่าวอ้าง	แหล่งที่มา	reference_id
การยืนยันตัวตนที่บกพร่องบั่นทอนความปลอดภัยของ API	มาตรฐาน OWASP API Security Top 10, API2:2023
คำขอที่เป็น idempotent สามารถลองใหม่ได้หลังจากล้มเหลว	RFC 9110 §9.2.2

โปรโตคอล gRPC เป็นข้อกำหนดภายนอกซึ่งอยู่นอกคลังมาตรฐานที่ควบคุมไว้ นิยาม Protocol Buffers nextpdf.connect.v1 ที่มาพร้อมแพ็กเกจคือสัญญาการสื่อสารระดับ wire อย่างเป็นทางการที่ใช้เป็นแหล่งอ้างอิง

บริบทเชิงพาณิชย์

ExecuteCapability เข้าถึง operation ของ Pro และ Enterprise ได้ก็ต่อเมื่อติดตั้ง nextpdf/premium ควบคู่ไปกับเซิร์ฟเวอร์ ระดับที่ติดตั้งจะไม่เปลี่ยนทรานสปอร์ต การยืนยันตัวตน หรือการตั้งค่า TLS

ดูเพิ่มเติม

• /connect/security-and-operations/ — การยืนยันตัวตน, mutual TLS, โมเดลภัยคุกคาม
• /connect/deployment/ — โปรไฟล์ RoadRunner แบบรวมและ TLS secret
• /transports/mcp/ · /transports/rest/ — ทรานสปอร์ตอื่นๆ
• /connect/tool-catalog/ — วิธีที่ ExecuteCapability จับคู่กับแคตตาล็อก
• /connect/production-usage/ — งานและการลองใหม่แบบ idempotent