جسر العرض عند الحافة لخدمة Cloudflare في NextPDF — نظرة عامة

لمحة سريعة

nextpdf/cloudflare هو جسر للعرض عند الحافة. يُبقي تطبيق ⁨PHP⁩ لديك لغة ترميز النص التشعبي (⁨HTML⁩)، بينما يُبقي ⁨Cloudflare Worker⁩ المتصفح بلا واجهة. يرسل الجسر محتوى ⁨HTML⁩ إلى ⁨Worker⁩ عبر بروتوكول نقل النص التشعبي الآمن (⁨HTTPS⁩)، ويتلقى بايتات بتنسيق المستندات المحمولة (⁨PDF⁩) بعد العرض. لا يعمل أي متصفح بلا واجهة داخل عملية ⁨PHP⁩ لديك، ولا يتطلب الجسر ملف ⁨Chromium⁩ ثنائيًا محليًا على المسار الذي يملكه.

تنتمي الحزمة إلى منظومة ⁨NextPDF⁩ وتعتمد على nextpdf/core^3.0. وهي شِفرة بروتوكول اتصال: تبني طلبًا بترميز كائنات ⁨JavaScript⁩ (⁨JSON⁩)، وتتحقق من صحة المُدخل والوجهة، وترسل الطلب عبر عميل توصية معايير ⁨PHP⁩ رقم 18 (⁨PSR-18⁩)، ثم تحلل الاستجابة إلى كائن نتيجة مُنمَّط. يقع تنفيذ ⁨Worker⁩ خارج نطاق هذه الحزمة. يتواصل هذا الجسر مع ⁨Worker⁩ الذي تنشره أنت.

حدّ الثقة

السمة المميزة لهذا الجسر هي أن محتوى ⁨HTML⁩ يعبر حدًّا شبكيًّا إلى محرك متصفح لا تتحكم فيه مباشرة. كل ضابط أمني في الحزمة موجود بسبب هذا الحدّ.

يجري التحقق من صحة محتوى ⁨HTML⁩ قبل أن يغادر عملية ⁨PHP⁩ (CloudflareSecurityPolicy::validate()).
يجري التحقق من صحة محدد موقع المورد الموحد (⁨URL⁩) للوجهة قبل إرسال الطلب (CloudflareSecurityPolicy::validateWorkerUrl())، ثم يُعاد التحقق منه عند إرسال الطلب لإغلاق نافذة ⁨time-of-check/time-of-use⁩ (assertPinsStillValid()).
يمكن لطبقة النقل تثبيت مجموعة عناوين بروتوكول الإنترنت (⁨IP⁩) المُحلَّلة والمفتاح العام لشهادة الخادم (Transport\PinnedCurlTransport).

إذا كنت تُقيّم هذا الجسر للاستخدام في الإنتاج، فاقرأ /⁨integrations/cloudflare/security-and-operations/⁩ قبل /⁨integrations/cloudflare/quickstart/.⁩ النموذج الأمني ليس إضافة لاحقة، بل يفسّر سبب تشكيل الحزمة بهذه الصورة.

ما يفعله

القدرة	مدعوم بـ
عرض محتوى ⁨HTML⁩ إلى ⁨PDF⁩ عبر ⁨Cloudflare Worker⁩	`CloudflareHtmlRenderer::render()`
فحص قابلية الوصول (طلب `HEAD` ببروتوكول نقل النص التشعبي (⁨HTTP⁩))	`CloudflareHtmlRenderer::isAvailable()`
طبقة نقل محايدة تجاه المورّد	حقن `ClientInterface` متوافق مع ⁨PSR-18⁩
تحصين المُدخلات (الحجم، قنبلة ⁨base64⁩، إعادة التحميل عبر ⁨meta-refresh⁩)	`CloudflareSecurityPolicy::validate()`
الدفاع ضد تزوير الطلبات من جانب الخادم (⁨SSRF⁩) / إعادة ربط نظام أسماء النطاقات (⁨DNS⁩)	`CloudflareSecurityPolicy::validateWorkerUrl()` + `assertPinsStillValid()`
تثبيت المفتاح العام لأمن طبقة النقل (⁨TLS⁩)، وتثبيت ⁨DNS⁩ عند طبقة ⁨cURL⁩	`Transport\PinnedCurlTransport`
الرجوع إلى ⁨Chrome⁩ محلي عند تعذُّر الوصول إلى ⁨Worker⁩	`Contract\LocalRendererFactoryInterface`
تحليل الاستجابة الثنائية واستجابة ⁨JSON⁩ (⁨base64⁩)	`CloudflareResponseParser`
قياسات الحافة عن بُعد (زمن العرض، موقع الحافة، ارتفاع المحتوى)	`CloudflareRenderResult`
خطوط مخصصة من حاوية ⁨R2⁩	`CloudflareRenderPayload` (`r2FontBucket`، `fontFiles`)
طبقة حماية واجهة برمجة التطبيقات (⁨API⁩) (مصادقة المفتاح، حجم الحمولة، تحديد المعدل)	`ApiProtection`
أرشفة ملفات ⁨PDF⁩ إلى ⁨R2⁩ عبر واجهة ⁨API⁩ المتوافقة مع ⁨S3⁩	`R2ArchiveManager`

يقابل كل صف صنفًا في مساحة الأسماء NextPDF\Cloudflare. يُتحقق من كل صف بمطابقته مع سلوك ذلك الصنف واختباره، لا مع مستند مواصفات.

ما لا يفعله

لا يُشغّل متصفحًا. بل ⁨Worker⁩ هو الذي يُشغّله.
لا ينشر ⁨Worker⁩ الخاص بك ولا يهيّئه. أنت تملك ذلك الأثر.
لا يوقّع ملفات ⁨PDF.⁩ يعود التوقيع إلى nextpdf/core أو الإصدارات التجارية. عندما تحتاج إلى التوقيع، اعرض أولًا، ثم وقّع البايتات المُرجَعة بالمحرك. يوفّر ⁨NextPDF Pro⁩ توقيع ⁨PAdES B-B.⁩ أما أوضاع التحقق طويل الأمد (⁨long-term-validation⁩)، فهي قدرة في إصدار ⁨Enterprise.⁩
لا يؤكد أي سعة أو حدّ لمنصة ⁨Cloudflare.⁩ حدود الحجم والوقت الوحيدة التي يذكرها هذا التوثيق هي الحدود التي تفرضها هذه الحزمة عبر تهيئتها الخاصة (انظر /⁨integrations/cloudflare/configuration/⁩).

سياستا الأمان

يحمل الجسر سياستين متمايزتين ومتكاملتين. الخلط بينهما من أكثر أخطاء المراجعة شيوعًا. وفيما يلي كل واحدة منهما.

سياسة أمان ⁨HTML⁩ (HtmlSecurityPolicyInterface، والافتراضية NextPDF\Html\DefaultHtmlSecurityPolicy، يوفّرها nextpdf/core): تصفية المحتوى عند طبقة التحليل، وتُطبَّق قبل أن يصل المحتوى إلى ⁨Worker.⁩ احصل عليها باستخدام getHtmlSecurityPolicy().
سياسة أمان ⁨Cloudflare⁩ (CloudflareSecurityPolicy، ساكنة): تعالج شواغل طبقة النقل: حجم المُدخل، اكتشاف قنبلة فك ضغط ⁨base64⁩، حظر ⁨meta-refresh⁩، فرض ⁨HTTPS⁩، والدفاع ضد ⁨SSRF⁩ / إعادة ربط ⁨DNS⁩ لعنوان ⁨URL⁩ الخاص بـ ⁨Worker.⁩

يذكر ⁨docblock⁩ الخاص بأداة العرض هذا الفصل. وتعيد هذه الصفحة ذِكره لأن مراجعي الإنتاج يحتاجون إلى رؤية الاسمين معًا على شاشة واحدة.

نموذج العرض على الحافة

يتبع استدعاء render() واحد هذا التسلسل القابل للرصد. يُستمد التسلسل مباشرة من CloudflareHtmlRenderer::render().

فحص اكتمال التهيئة (workerUrl وapiToken غير فارغين). إذا فشل الفحص، يرجع الجسر إلى أداة عرض محلية أو يطرح CloudflareNotAvailableException.
التحقق من صحة محتوى ⁨HTML⁩ مقابل الحجم الأقصى المُهيَّأ، وسقف عناوين ⁨URI⁩ بترميز ⁨base64⁩، وحظر ⁨meta-refresh.⁩
التحقق من صحة عنوان ⁨URL⁩ الخاص بـ ⁨Worker⁩، وهو ما يحلّ المضيف ويُرجع مجموعة عناوين ⁨IP⁩ المُدقَّقة.
بناء الحمولة (CloudflareRenderPayload).
تؤكد إعادة فحص وقت الاستخدام أن إجابة ⁨DNS⁩ للمضيف لم تتغير منذ الخطوة 3.
يُرسَل طلب POST عبر ⁨HTTP⁩ من خلال طبقة نقل ⁨cURL⁩ المثبَّتة عند وجود مجموعة عناوين ⁨IP⁩ أو مجموعة تثبيت لمعلومات المفتاح العام للموضوع (⁨SPKI⁩) مع توافر ResponseFactory متوافق مع ⁨PSR-17⁩، وإلا فعبر عميل ⁨PSR-18⁩ المحقون.
تُحلَّل الاستجابة إلى CloudflareRenderResult.

أي كائن قابل للطرح غير CloudflareRenderException يُفعّل مسار الرجوع. يُعاد طرح CloudflareRenderException (خطأ ⁨HTTP⁩ أو استجابة مشوَّهة من ⁨Worker⁩) دون تغيير. هذا فشل من جانب ⁨Worker⁩، لا فشل في قابلية الوصول، لذلك لا يرجع الجسر.

انظر أيضًا

/⁨integrations/cloudflare/install/⁩ — ثبّت الحزمة وعميلًا متوافقًا مع ⁨PSR-18.⁩
/⁨integrations/cloudflare/configuration/⁩ — كل حقل تهيئة، مع قيمته الافتراضية المُتحقَّق منها من المصدر.
/⁨integrations/cloudflare/quickstart/⁩ — أول عملية عرض لديك قابلة للتشغيل.
/⁨integrations/cloudflare/production-usage/⁩ — الرجوع الاحتياطي، القياس عن بُعد، أرشفة ⁨R2⁩، حماية ⁨API.⁩
/⁨integrations/cloudflare/security-and-operations/⁩ — تفاصيل تشغيلية لحدّ الثقة.
/⁨integrations/cloudflare/troubleshooting/⁩ — أنماط الفشل مُربوطة بالاستثناءات.
/⁨integrations/cloudflare/boot-and-discovery/⁩ — كيفية اتصال الجسر بإطار العمل المضيف.
/⁨integrations/cloudflare/integration/⁩ — شغّل ⁨NextPDF⁩ عبر خدمات ⁨Cloudflare.⁩