Enterprise الإصدار

خطّاف الويب

لمحة سريعة

يُسلِّم ⁨NextPDF Enterprise⁩ أحداث المهام إلى نقاط طرفية لخطّاف الويب خاصة بكل مستأجِر عبر ⁨HTTP POST⁩، ويوقّع كل حمولة بتوقيع ⁨HMAC-SHA256⁩، ويعيد المحاولة بتراجع أُسّي، ويوجّه عمليات التسليم المُخفِقة نهائيًا إلى طابور رسائل مهملة للفحص وإعادة التشغيل. تصف هذه الصفحة سلوك خطّاف الويب القابل للملاحظة والعقد العام.

التوفّر والترخيص

تُشحَن هذه القدرة في ⁨NextPDF Enterprise⁩ (nextpdf/enterprise) وتُفعَّل بمظروف ترخيص من فئة ⁨Enterprise⁩. النشر الذي يفتقر إلى هذا الاستحقاق لا يحمّل أصناف القدرة. قارن الإصدارات واحصل على ترخيص.

سطح خطّاف الويب قدرة أساسية في ⁨Enterprise⁩، متوفّرة بمجرّد تثبيت حزمة ⁨Enterprise⁩؛ ولا يوجد علم منفصل لكل ميزة.

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

يسجّل المستأجِر عنوان ⁨URL⁩ لردّ النداء، وسرّ توقيع، وقائمة أنواع أحداث اختيارية. قائمة الأحداث الفارغة تعني «الاشتراك في كل الأحداث». التسجيلات ذات نطاق مستأجِر صارم: لا يرى المستأجِر ولا يدير إلا تسجيلاته الخاصة، ويُرفض التسجيل تحت مستأجِر غير مطابق. يعطّل إلغاء التسجيل التسجيلَ بدلًا من حذفه، فيُحفظ التاريخ؛ ولا تتلقّى الإرسالات إلا التسجيلات النشطة.

عند إرسال حدث مهمة لمستأجِر، يتلقّى كل تسجيل نشط مشترك في نوع الحدث تسليمًا. الحمولة مستند ⁨JSON⁩ موحَّد — معرّف تسليم فريد، ومعرّف المهمة، ونوع الحدث، وبيانات الحدث، وطابع زمني وفق ⁨RFC 3339⁩، ومعرّف المستأجِر. التسليم هو ⁨HTTP POST⁩ يحمل جسم ⁨JSON⁩ وأربع ترويسات: توقيع ⁨HMAC-SHA256⁩، وطابع زمني بالثواني اليونكسية، ومعرّف التسليم، ونوع الحدث. يُحسَب التوقيع فوق السلسلة الأساسية القانونية {timestamp}.{body} بسرّ التسجيل، فتُربَط ترويسة الطابع الزمني تشفيريًا بالجسم. يعيد المُستقبِل حساب ⁨HMAC⁩ فوق السلسلة الأساسية نفسها ويرفض عمليات التسليم التي يقع طابعها الزمني خارج نافذة طزاجة مقبولة، ما يحدّ من إعادة التشغيل.

يستخدم التسليم تراجعًا أُسّيًا. استجابة ⁨2xx⁩ نجاح. استجابة ⁨4xx⁩ غير 429 تُعامَل كرفض دائم ولا يُعاد. أما الإخفاقات الأخرى — ⁨5xx⁩، أو 429، أو خطأ اتصال — فتُعاد حتى عدد محاولات السياسة بتأخير مضاعِف محدود بحدّ أقصى. عند استنفاد كل المحاولات يُسجَّل التسليم في طابور رسائل مهملة في الذاكرة مع الحمولة الأصلية، وعدد المحاولات، والخطأ الأخير، وآخر حالة ⁨HTTP⁩؛ ويمكن وسم مدخل رسالة مهملة بأنه مُعاد التشغيل. تُشحَن سياستا إعادة محاولة — افتراضية (5 محاولات، أساس 1 ثانية، حدّ 5 دقائق) وقوية (10 محاولات، أساس 2 ثانية، حدّ 10 دقائق).

لماذا يعمل بهذه الطريقة

يُعامَل التسليم كسطح تشغيلي، لا كنداء يُطلَق ويُنسى. تُصنَّف الإخفاقات بحسب القصد. ⁨4xx⁩ غير 429 رفض حقيقي من المُستقبِل، فيتوقّف فورًا. ⁨5xx⁩، أو 429، أو خطأ اتصال حالة عابرة، فتستحق إعادة محاولة متراجعة محدودة. لا تُسقَط أبدًا بصمت عمليات التسليم التي تستنفد كل محاولة؛ بل تحطّ في طابور رسائل مهملة قابل للفحص يمكن إعادة تشغيله. يربط التوقيع طابعًا زمنيًا في سلسلته الأساسية، وتجتاز كل وجهة بوابة خروج، فتصمد الأصالة ومقاومة إعادة التشغيل بحكم التصميم لكل مستأجِر.

خلفية التصميم: تشغيل ⁨NextPDF⁩ في الإنتاج.

سطح الـ ⁨API⁩ العام

composer require nextpdf/enterprise:^3

نقاط التكامل المدعومة هي مدير خطّاف الويب (register، وunregister، وactiveRegistrations، وdispatch)، وكائن قيمة التسجيل (subscribesTo، وdeactivate)، والحمولة (fromJobEvent، وtoJson، وtoArray، وsign، وsignedTimestamp)، ومحرّك التسليم (deliver، وdeadLetters، وclearDeadLetters)، وسياسة إعادة المحاولة (delayForAttempt، وshouldRetry، وdefault، وaggressive)، ومدخل الرسالة المهملة (markReplayed).

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

use NextPDF\Enterprise\Webhook\WebhookManager;
use NextPDF\Enterprise\Webhook\WebhookRegistration;

$manager->register($tenant, new WebhookRegistration(
    id: $id,
    tenantId: $tenant->tenantId,
    url: 'https://customer.example.com/hooks/nextpdf',
    events: [],            // empty = subscribe to all event types
    secret: $signingSecret,
));

$delivered = $manager->dispatch($tenant, $jobEvent); // count of successes

التحقق من جانب المُستقبِل:

$ts = (int) $request->header('X-NextPDF-Timestamp');
if (abs(time() - $ts) > 300) {
    return new Response(401); // stale timestamp: reject to bound replay
}
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $rawBody, $sharedSecret);
if (! hash_equals($expected, $request->header('X-NextPDF-Signature'))) {
    return new Response(401);
}

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

use NextPDF\Enterprise\Webhook\WebhookDelivery;
use NextPDF\Enterprise\Webhook\WebhookRetryPolicy;

$delivery = new WebhookDelivery(
    $httpClient, $requestFactory, $streamFactory,
    retryPolicy: WebhookRetryPolicy::aggressive(), // 10 attempts, 2s base, 10min cap
    logger: $logger,
);

$manager = new WebhookManager($delivery, $logger);
$manager->dispatch($tenant, $jobEvent);

foreach ($delivery->deadLetters() as $dead) {
    $this->scheduleReplay($dead); // inspect last error + last HTTP status
}

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

قائمة الأحداث الفارغة تشترك في الكل. التسجيل الخالي من أنواع أحداث يتلقّى كل حدث؛ مرّر قائمة صريحة لتحديد نطاقه.
عزل المستأجِر مفروض. يُرفض التسجيل بمعرّف مستأجِر يختلف عن مستأجِر السياق؛ ولا يكرّر الإرسال إلا التسجيلات النشطة للمستأجِر المستدعي.
‏⁨4xx⁩ (ما عدا 429) نهائي. ⁨4xx⁩ غير 429 لا يُعاد — يُعامَل كرفض مُستقبِل دائم ويذهب إلى طابور الرسائل المهملة.
إلغاء التسجيل ناعم. يعطّل إلغاء التسجيل؛ والسجل يبقى ويُستبعَد من الإرسال.
طابور الرسائل المهملة في الذاكرة. هو للفحص وإعادة التشغيل ضمن عمر العملية؛ احفظ المدخلات بنفسك إن احتجت إعادة تشغيل دائمة عبر عمليات إعادة التشغيل.

الأداء

تتناسب تكلفة الإرسال مع عدد التسجيلات النشطة للمستأجِر المشتركة في الحدث. كل تسليم هو ⁨HMAC-SHA256⁩ واحد فوق السلسلة الأساسية الموقَّعة إضافةً إلى الرحلة الشبكية ذهابًا وإيابًا؛ وتضيف إعادات المحاولة تأخيرات تراجع أُسّي محدودة. التوقيع بترتيب ⁨O(payload size)⁩.

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

تُصادَق كل حمولة بتوقيع ⁨HMAC-SHA256⁩ مُفتَّح بسرّ التسجيل وتُرسَل في ترويسة X-NextPDF-Signature بصيغة sha256=<hex>. يغطّي التوقيع السلسلة الأساسية {timestamp}.{body}، ويسافر الطابع الزمني في ترويسة X-NextPDF-Timestamp؛ يتحقّق المُستقبِلون بمقارنة بزمن ثابت ويرفضون عمليات التسليم خارج نافذة طزاجة للحدّ من إعادة التشغيل. تجتاز عناوين ⁨URL⁩ للوجهة بوابة خروج مركزية قبل كل إرسال: ⁨HTTPS⁩ مشترط، وتُرفَض دون طلب المضيفات التي تُحلّ إلى عناوين خاصة أو محلّية أو محلّية الوصلة أو عناوين بيانات وصفية سحابية وتُوجَّه إلى طابور الرسائل المهملة. سرّ التوقيع لكل تسجيل؛ عامِله كبيانات اعتماد. يصادق التوقيع على سلامة الحمولة ومصدرها؛ وهو ليس طبقة تشفير — لا تضع أسرارًا في بيانات حدث لا ينبغي أن يراها المُستقبِل.

المطابقة

تستخدم مصادقة الحمولة ⁨HMAC⁩ مع ⁨SHA-256⁩، رمز مصادقة الرسالة المُفتَّح بالتجزئة وفق ⁨FIPS PUB 198-1⁩؛ ويُدرِج ⁨OWASP ASVS 5.0⁩ ⁨HMAC-SHA-256⁩ ضمن خوارزميات مصادقة الرسائل المعتمدة لديه.
طوابع الحمولة الزمنية سلاسل تاريخ-وقت وفق ⁨RFC 3339⁩. ملاحظة: لم يُستجلَب ⁨RFC 3339⁩ من مجموعة ⁨RAG⁩ لهذه الصفحة؛ والصيغة مُعلَنة في الشيفرة (⁨RFC 3339⁩ ممتدّة) وموسومة بأنها مُعلَنة في الشيفرة لا متحقَّقة عبر ⁨RAG⁩.

عقد السلوك

التسجيلات ذات نطاق مستأجِر صارم؛ ويُرفض التسجيل تحت مستأجِر غير مطابق وإلغاء التسجيل تعطيل ناعم يحفظ التاريخ.
قائمة الأحداث الفارغة تشترك في كل الأحداث؛ ولا تتلقّى التسليم إلا التسجيلات النشطة المشتركة في نوع الحدث.
كل تسليم هو ⁨HTTP POST⁩ بجسم ⁨JSON⁩ إضافةً إلى ترويسة توقيع ⁨HMAC-SHA256⁩ (فوق السلسلة الأساسية {timestamp}.{body})، وترويسة طابع زمني بالثواني اليونكسية، ومعرّف التسليم، ونوع الحدث.
⁨2xx⁩ نجاح؛ و⁨4xx⁩ غير 429 رفض دائم (لا إعادة محاولة)؛ و⁨5xx⁩، أو 429، أو خطأ اتصال يُعاد حتى عدد محاولات السياسة بتراجع مضاعِف محدود.
تُسجِّل المحاولات المستنفَدة التسليمَ في طابور رسائل مهملة في الذاكرة (الحمولة، وعدد المحاولات، والخطأ الأخير، وآخر حالة)؛ ويمكن وسم مدخل رسالة مهملة بأنه مُعاد التشغيل.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا والسطح العام المدعوم فقط. مسارات فضاء الأسماء الداخلية، والأصناف المساعِدة، وجداول الآليات، وأسماء ملفات أدلة التشغيل، وبادئات التذاكر خارجة عن النطاق.

الاحتياط في ⁨Core⁩

لا يملك ⁨NextPDF Core⁩ (⁨Apache-2.0⁩) أي سطح لتسجيل خطّاف الويب أو تسليمه — لا شيء؛ وليس لهذه القدرة أي مكافئ على مستوى ⁨Core⁩.

الاحتياط في ⁨Pro⁩

لا يملك ⁨NextPDF Pro⁩ أي سطح لتسجيل خطّاف الويب أو تسليمه — لا شيء؛ وليس لهذه القدرة أي مكافئ على مستوى ⁨Pro⁩. يُشحَن مدير خطّاف الويب، والتسجيل، والحمولة، ومحرّك التسليم، وسياسة إعادة المحاولة في حزمة nextpdf/enterprise فقط.

ملاحظة حدود ⁨Enterprise⁩

تُوصَف سياسة إعادة المحاولة، وجدول التراجع، ومعالجة الرسائل المهملة على مستوى السلوك. طابور الرسائل المهملة في الذاكرة للفحص وإعادة التشغيل ضمن عمر العملية؛ أما الحفظ الدائم عبر عمليات إعادة التشغيل وأي أجزاء تسليم داخلية فخارجة عن نطاق السطح العام.

حدود التوزيع

يملك المشغِّل النقاط الطرفية لردّ النداء، وأسرار التوقيع لكل تسجيل (تُعامَل كبيانات اعتماد)، والحفظ الدائم لمدخلات الرسائل المهملة إن طُلِبت إعادة التشغيل عبر عمليات إعادة التشغيل، ووضعية ⁨HTTPS⁩ لعناوين ⁨URL⁩ للمُستقبِل. يوقّع ⁨NextPDF Enterprise⁩ ويُسلِّم لكنه لا يحفظ بنفسه التسجيلات ولا الرسائل المهملة بعد عمر العملية.

حدود الامتثال القانوني

لا ينطبق أي قيد لضوابط التصدير على سطح خطّاف الويب. يصادق توقيع ⁨HMAC⁩ على سلامة الحمولة ومصدرها؛ وهو ليس طبقة تشفير — يجب على المشغّلين عدم وضع أسرار في بيانات حدث لا ينبغي أن يراها المُستقبِل. هذه الوثائق ليست رأيًا قانونيًا؛ استشر مستشاري الامتثال والشؤون القانونية لديك.