NextPDF Connect — ناقل gRPC

لمحة سريعة

يشغّل ناقل ⁨gRPC⁩ الأمر bin/nextpdf-grpc داخل مجمّع عمال ⁨gRPC⁩ الخاص بـ ⁨RoadRunner.⁩ ويقدّم خدمة nextpdf.connect.v1.NextPDFConnect، ويدعم العرض بتدفّق من الخادم، ويصادق كل استدعاء برمز حامل في البيانات الوصفية، ويُعدّ لاستخدام ⁨TLS⁩ متبادل في ملف النشر المُجمَّع.

التثبيت

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

نظرة مفاهيمية عامة

تستخدم خدمة ⁨gRPC⁩ خدمات التطبيق نفسها التي يستخدمها ناقل نقل الحالة التمثيلية (⁨REST⁩): العرض، والمهام، والجلسات، والقدرات، والعمليات. ويتولّى عامل ⁨gRPC⁩ من ⁨Spiral RoadRunner⁩ معالجة الاستدعاءات. عقد الاتصال هو حزمة ⁨Protocol Buffers⁩ المسمّاة nextpdf.connect.v1، والمُعرّفة بواسطة ملفات .proto المرفقة مع الحزمة.

تستخدم المصادقة مخزن المفاتيح وآلية التحقق نفسيهما المُستخدَمين في ⁨REST.⁩ يقرأ مُصادِق ⁨gRPC⁩ مفتاح البيانات الوصفية authorization، الذي ينقله ⁨gRPC⁩ على هيئة ترويسات بروتوكول نقل النص التشعّبي الإصدار 2 (⁨HTTP/2⁩). ويُحلّل الرمز Bearer npk_live_…، ثم يتحقق من مُعرّف المفتاح (⁨kid⁩) وملخّص ⁨SHA-256⁩ بمقارنة ثابتة الزمن. يُفشِل المُصادِق الاستدعاء بحالة ⁨gRPC⁩ UNAUTHENTICATED عندما يكون المفتاح مفقوداً أو مُشوّهاً أو غير معروف أو مُعطّلاً أو منتهي الصلاحية. إنّ التنفيذ غير الصحيح للمصادقة هو خطر المصادقة المعطوبة ⁨OWASP API2⁩:2023؛ وتحد مقارنة الملخّص ثابتة الزمن من هذا الخطر.

سطح ⁨API⁩

استدعاءات الخدمة (⁨RPCs⁩)

تعرض خدمة nextpdf.connect.v1.NextPDFConnect استدعاءات إجراءات بعيدة (⁨RPCs⁩) أحادية وبتدفّق من الخادم:

⁨RPC⁩	النوع	الغرض
Render	أحادي	عرض متزامن
RenderStream	تدفّق من الخادم	عرض متدفّق على هيئة أجزاء
SubmitJob / GetJobStatus / GetJobResult / CancelJob	أحادي	مهام غير متزامنة
GetJobResultStream	تدفّق من الخادم	نتيجة غير متزامنة متدفّقة
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender	أحادي	جلسات ذات حالة
SessionRenderStream	تدفّق من الخادم	عرض الجلسة متدفّق
ExecuteCapability / GetCapabilities	أحادي	توزيع القدرات والاستبطان
HealthCheck / ReadinessCheck	أحادي	الحيوية والجاهزية

يوزّع ExecuteCapability العمليات المُقيّدة بحسب المستوى نفسها التي توزّعها مسارات عمليات ⁨REST.⁩ ولا يمكن الوصول إلى عمليات ⁨Pro⁩ و⁨Enterprise⁩ إلا عند تثبيت تلك الحزم. وفي ما يخصّ التوقيع، يوفّر ⁨NextPDF Connect⁩ مع ⁨Pro⁩ توقيعاً إلكترونياً متقدّماً لملفات ⁨PDF⁩ وفق ⁨PAdES⁩ من المستوى الأساسي ⁨B⁩ (⁨B-B⁩) فقط.

التدفّق

ترسل استدعاءات ⁨RPC⁩ ذات التدفّق من الخادم النتيجة على هيئة دفق أجزاء مرتّب، وهو ما يناسب ملفات ⁨PDF⁩ الكبيرة والتسليم التدريجي. وتُعيد استدعاءات ⁨RPC⁩ الأحادية النتيجة كاملةً في رسالة واحدة.

مثال برمجي — بداية سريعة

شغّل ملف ⁨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

في كل استدعاء، عيّن البيانات الوصفية authorization الخاصة باعتماد الاستدعاء إلى Bearer npk_live_{kid}_{secret}.

مثال برمجي — الإنتاج

يشغّل ملف ⁨gRPC⁩ المُجمَّع ⁨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). إنّ إعادة محاولة إرسال مهمة أحادية مُتساوية القوى بعد انقطاع الاتصال آمنة: إذ إن تكرار طلب مُتساوي القوى له التأثير المقصود نفسه لطلب واحد (⁨RFC 9110⁩ §9.2.2).

الحالات الحدّية والمزالق

• UNAUTHENTICATED، وليس حالة ⁨HTTP.⁩ يتسبب الرمز غير الصحيح أو المفقود في فشل استدعاء ⁨RPC⁩ بحالة ⁨gRPC⁩ UNAUTHENTICATED، وليس بالرمز 401. مخطّط الرمز الحامل وتنسيق npk_live_ مطابقان لـ ⁨REST.⁩

• RESOURCE_EXHAUSTED عند محاولات ما قبل المصادقة المفرطة. تُقيَّد محاولات ما قبل المصادقة المتكرّرة الصادرة من هوية عميل واحدة، وتفشل بحالة ⁨gRPC⁩ RESOURCE_EXHAUSTED. هذه الحالة هي مكافئ ⁨gRPC⁩ لـ ⁨HTTP⁩ 429، وتطبّق وضع مكافحة الأتمتة نفسه المطبّق في ⁨REST.⁩ هذا الضابط مُفعّل افتراضياً، لذا ينبغي للعملاء التراجع بدلاً من إعادة المحاولة فوراً. راجع وضع تحديد معدّل ⁨HTTP⁩ في /⁨connect/production-usage/.⁩

• ⁨TLS⁩ المتبادل هو إعداد نشر، وليس إعداداً افتراضياً. يتطلّب مستمع ⁨gRPC⁩ أسراراً مُهيّأة على نحو صحيح لمفتاح الخادم وشهادة الخادم وسلطة تصديق شهادة العميل (⁨CA⁩). من دونها، لن يقدّم الملف المُجمَّع الخدمة؛ وهذا مقصود. أنشئها وأدِر تدويرها خارج النطاق.

• التقييد بحسب المستوى ما زال سارياً. يتطلّب ExecuteCapability لعملية ⁨Pro⁩ أو ⁨Enterprise⁩ تثبيت الحزمة ومفتاحاً مُخوّلاً.

• العمليات عالية المخاطر ما زالت تخضع للتقييد. العمليات التي تُشغّل أداة ApprovalRequired تستخدم بوابة التدخّل البشري نفسها. راجع /⁨connect/hitl-risk-tiers/.⁩

الأداء

يعالج كل عامل ⁨gRPC⁩ استدعاءً واحداً في كل مرة. ويُحدَّد حجم المجمّع بصورة مستقلّة عن مجمّع ⁨HTTP⁩ (افتراضياً عاملان)، ويكون عادةً أصغر لأن عملاء ⁨gRPC⁩ أقل عدداً، ولأن اتصالاتهم تدوم مدة أطول. استخدم استدعاءات ⁨RPC⁩ ذات التدفّق من الخادم للمخرجات الكبيرة لتجنّب تخزين ملف ⁨PDF⁩ بأكمله في رسالة واحدة.

ملاحظات أمنية

شغّل ناقل ⁨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⁩ نفسه مواصفة خارجية تقع خارج مجموعة المعايير المُقيّدة. تعريفات ⁨Protocol Buffers⁩ المرفقة nextpdf.connect.v1 هي عقد الاتصال المُعتمَد.

السياق التجاري

لا يتيح ExecuteCapability الوصول إلى عمليات ⁨Pro⁩ و⁨Enterprise⁩ إلا عند تثبيت nextpdf/premium إلى جانب الخادم. لا تُغيّر المستويات المُثبَّتة الناقل أو المصادقة أو إعداد ⁨TLS.⁩

انظر أيضاً

• /⁨connect/security-and-operations/⁩ — المصادقة و⁨TLS⁩ المتبادل ونموذج التهديد
• /⁨connect/deployment/⁩ — ملف ⁨RoadRunner⁩ المُجمَّع وأسرار ⁨TLS⁩
• /⁨transports/mcp/⁩ · /⁨transports/rest/⁩ — النواقل الأخرى
• /⁨connect/tool-catalog/⁩ — طريقة ارتباط ExecuteCapability بالكتالوج
• /⁨connect/production-usage/⁩ — المهام وإعادة المحاولات مُتساوية القوى