Accelerator: عميل sidecar لـ Spectrum

لمحة سريعة

وحدة ⁨Accelerator⁩ هي عميل ⁨PHP⁩ لـ ⁨Spectrum⁩، وهو ⁨sidecar⁩ الاختياري للتسريع الذي يعمل خارج العملية. إنها عميل ⁨Hypertext Transfer Protocol⁩ (⁨HTTP⁩) مُحصَّن مزوّد بقاطع دائرة، ورموز قدرات ⁨JSON Web Token⁩ (⁨JWT⁩)، ومحاولة إعادة واحدة للأعطال العابرة، ونقل عبر الأحداث المُرسَلة من الخادم لبثّ تقدّم المهام. يعمل المحرك من دون ⁨sidecar.⁩ استخدم هذه الوحدة لإدخال التسريع من دون جعله إلزاميًا.

الاستقرار: تجريبي. ‏⁨Spectrum⁩ هو ⁨sidecar⁩ اختياري، وليس واجهة عامة مجمَّدة لبرمجة التطبيقات (⁨API⁩). إنّ SpectrumInterface الذي ينفّذه موثَّق بأنه تجريبي في ⁨Contracts⁩ / ⁨Observability⁩. يتّبع هذا العميل تلك الفئة. قد يتغيّر النقل، وصيغة الرمز، وشكل الميزانية بين الإصدارات الثانوية.

التثبيت

composer require nextpdf/core:^3

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

يُفرّغ ⁨Spectrum⁩ الأعمال الثقيلة على المعالج إلى عملية ⁨sidecar⁩ محلية، بما في ذلك اكتشاف العتاد، وتحليل ⁨Portable Document Format⁩ (⁨PDF⁩)، وضغط الصور. SpectrumClient هو عميل ⁨PHP Standards Recommendation 18⁩ (⁨PSR-18⁩) ينفّذ الواجهة المجمَّدة NextPDF\Contracts\SpectrumInterface. يعتمد على ClientInterface، وRequestFactoryInterface، وStreamFactoryInterface، ولا يعتمد على حزمة ⁨Hypertext Transfer Protocol⁩ (⁨HTTP⁩) مُثبَّتة بصورة جامدة.

يفترض العميل أن التبعية قد تفشل. يُفتح قاطع الدائرة بعد ثلاثة إخفاقات متتالية. وعندما يكون مفتوحًا، تُعيد isAvailable() القيمة false طوال نافذة تراجع أُسّي، حتى لا يواصل مسار ساخن استدعاء ⁨sidecar⁩ غير متاح. تُخزَّن نتيجة الفحص مؤقتًا بمدة بقاء (⁨TTL⁩). عند تهيئة سرّ التطبيق، يحمل كل طلب صادر رمز قدرة الطلب (⁨Request Capability Token⁩). الرمز هو ⁨JWT⁩ من نوع ⁨HS256⁩ قصير العمر ومُحدَّد النطاق على القدرات المطلوبة لنقطة النهاية. عمره 120 ثانية، أو 30 ثانية في وضع التفويض عالي التحكّم. تُعاد محاولة أخطاء 5⁨xx⁩ العابرة وأخطاء انتهاء المهلة مرة واحدة. لا تُعاد محاولة أخطاء المصادقة والتحليل مطلقًا.

يحتفظ SspectrumClient بالحالة لكل نسخة على حدة. لا تُشارَك حالة قاطع الدائرة ولا ذاكرة الفحص المؤقتة. ينبغي أن يحتفظ كل عامل ⁨PHP FastCGI Process Manager⁩ (⁨PHP-FPM⁩) بنسخته الخاصة. نتائج الدُّفعة ذات أنواع مُحدَّدة. يحمل BatchResult مدخلات BatchItem بحالة BatchItemStatus، وBatchSummary بمعدّل نجاح، ومُعرّف تتبّع اختياري. يصف HardwareReport وHardwareCapabilities فئة العتاد المكتشَفة. تتحقّق HardwareCapabilities::satisfies() من متطلّب فئة برمجيًا. ويتحكّم تعدادا DegradePolicy وAuthorizationMode في سلوك فقدان القدرات وصرامة الرمز. الوحدة بأكملها هي @since 2.1.0.

سطح ⁨API⁩

النوع	الأعضاء الرئيسيون	الدور
SpectrumClient	isAvailable(), probe(), getBudget(), request()	عميل ⁨sidecar⁩ من نوع ⁨PSR-18⁩ ينفّذ SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	نتيجة دُفعة ذات نوع مُحدَّد
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	نتيجة لكل عنصر وتعداد الحالة
BatchSummary	isFullSuccess(), successRate()	ملخّص دُفعة مُجمَّع
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	قدرات ⁨sidecar⁩ المكتشَفة
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	تفرّع برمجي حسب القدرات
DegradePolicy / AuthorizationMode	حالات التعداد	سلوك التدهور وصرامة الرمز

شغّل composer docs:generate-api-php -- --module=Accelerator لإنشاء جدول ⁨PHPDoc⁩ الكامل.

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

افحص ⁨sidecar⁩ عبر قاطع الدائرة قبل الاعتماد عليه.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Contracts\SpectrumInterface;

function describeAccelerator(SpectrumInterface $spectrum): string
{
    if ($spectrum->isAvailable() !== true) {
        return 'Accelerator unavailable; engine runs in pure-PHP mode.';
    }

    $report = $spectrum->probe();

    return $report->hasEnterprise() ? 'Enterprise accelerator tier active.' : 'Standard accelerator tier active.';
}

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

أرسل دُفعة عبر ⁨sidecar⁩ عندما يكون سليمًا، وارجع إلى البديل وفق سياسة التدهور عندما لا يكون متاحًا.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Accelerator\DegradePolicy;
use NextPDF\Contracts\SpectrumInterface;
use Psr\Log\LoggerInterface;

final readonly class AcceleratedCompressor
{
    public function __construct(
        private ?SpectrumInterface $spectrum,
        private DegradePolicy $policy,
        private LoggerInterface $logger,
    ) {}

    /** @param list<array{id: string, data: string}> $images @return string Raw sidecar body. */
    public function compress(array $images): string
    {
        if ($this->spectrum?->isAvailable() === true) {
            return $this->spectrum->request('POST', '/v1/compress', json: ['images' => $images], scope: ['compress']);
        }

        if ($this->policy === DegradePolicy::Strict) {
            throw new \RuntimeException('Accelerator required under the strict degrade policy.');
        }

        $this->logger->info('Spectrum unavailable; using PHP image path.');

        return '';
    }
}

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

• isAvailable() فحص لحظي خاضع لقاطع الدائرة. قد تتحوّل النتيجة true إلى false قبل الاستدعاء التالي. عالِج حالة ⁨sidecar⁩ الذي يتوقف بين الاستدعاءات.
• حالة قاطع الدائرة وذاكرة الفحص المؤقتة خاصتان بكل نسخة على حدة. تؤدي مشاركة SpectrumClient واحد عبر العمّال إلى إبطال عمل القاطع. امنح كل عامل نسخته الخاصة.
• رموز القدرات قصيرة العمر (120 ⁨s⁩، و30 ⁨s⁩ في الوضع عالي التحكّم). يجب على العملية الطويلة الأمد أن تحصل على رمز جديد، لا أن تعيد استخدام رمز قديم.
• لا تُعاد محاولة أخطاء المصادقة والتحليل مطلقًا؛ لا تُعاد إلا محاولة استجابات 5⁨xx⁩ العابرة وحالات انتهاء المهلة، ومرة واحدة فقط. لا تفترض بعدها إعادة محاولة عديمة الأثر الجانبي.
• القيمة ⁨null⁩ لـ SpectrumInterface حالة صالحة تعني “بلا مُسرِّع”، وليست خطأ. تحدّد سياسة التدهور ما إذا كان ذلك قاتلًا.

الأداء

يضيف العميل حملًا إضافيًا لا يُذكر؛ فـ ⁨sidecar⁩ هو من يؤدّي العمل. قاطع الدائرة هو أداة التحكّم الرئيسية في الموثوقية. فهو يحدّ من رحلات الذهاب والإياب المهدرة عندما يكون ⁨sidecar⁩ غير متاح. إنّ performance_budget البالغ 1500 ⁨ms⁩ زمنًا فعليًا / 64 ⁨MB⁩ ذروةً هو حِمل العمل المرجعي للمحرك، وليس اتفاقية مستوى خدمة (⁨SLA⁩) لـ ⁨sidecar.⁩ ملف تعريف قابلية إعادة الإنتاج هو structural. تحمل نتيجة الدُّفعة مُعرّف تتبّع وطوابع زمنية، لذلك يختلف تشغيلان في تلك الحقول.

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

حدّ ⁨sidecar⁩ هو حدّ ثقة. عند تهيئة سرّ التطبيق، تحمل الطلبات رموز قدرات ⁨HS256⁩ مُحدَّدة النطاق على نقطة النهاية. تعامل مع ذلك السرّ بوصفه اعتماد ولوج من مدير أسرار، ولا تُودِعه في نظام التحكّم بالإصدارات مطلقًا. يُقصّر وضع التفويض عالي التحكّم عمر الرمز إلى 30 ثانية لنقاط النهاية الحسّاسة. يُتحقَّق من ⁨Uniform Resource Locator⁩ (⁨URL⁩) الخاص بـ ⁨sidecar⁩، والمُقدَّم من المشغّل، عند إنشاء التهيئة لا عند الطلب الأول: لا يُقبل سوى http:// وhttps:// بمضيف غير فارغ، أو unix:// بمسار مقبس غير فارغ؛ أمّا أي مخطّط آخر (gopher://، file://، ftp://، …) أو ⁨URL⁩ شبكي بلا مضيف، فيفشل فشلًا مغلقًا عند الإنشاء. هذا دفاع متعمّق ضد تزوير الطلب من جانب الخادم (⁨SSRF⁩) والخروج غير المتوقّع للبيانات، بحيث لا تصل نقطة نهاية مُهيَّأة بصورة خاطئة إلى عميل ⁨HTTP⁩ مطلقًا. استجابات ⁨sidecar⁩ بيانات خارجية. تحقّق منها وعامِلها بوصفها غير موثوقة قبل إدخالها من جديد إلى المحرك. تعكس فئة التحكّم بالتصدير legal-review-required على هذه الصفحة أنّ ميزة التسريع تحمل نقلًا تشفيريًا وهي قيد مراجعة للتحكّم بالتصدير. راجِع تلك المراجعة قبل إعادة توزيع إصدار يُفعّلها.

المطابقة

لا تقدّم هذه الوحدة أي ادّعاء معياري بشأن مواصفة ⁨PDF.⁩ إنها عميل ⁨HTTP⁩ لبروتوكول تسريع داخلي. البروتوكول مُعرَّف من المحرك، وليس مُوحَّدًا، لذلك لا توجد بنود للاستشهاد بها هنا. وحيثما يكون لعمل ⁨sidecar⁩ (تحليل ⁨PDF⁩، والضغط) بُعد مطابقة، تُوثَّق تلك المطابقة على صفحة الوحدة المعنية ويُتحقَّق منها بواسطة مجموعات الأوراكل والمجموعات الذهبية في /modules/core/conformance/.

انظر أيضًا

• ⁨Contracts⁩ / ⁨Observability⁩ — ‏SpectrumInterface الذي ينفّذه هذا العميل.
• وحدة ⁨Observability⁩ — سطح حالة وقت التشغيل للعمل المُسرَّع.
• وحدة ⁨Performance⁩ — ميزانيات العمل المُسرَّع.
• نموذج أمن المحرك