Accelerator: klient sidecara Spectrum

W skrócie

Moduł Accelerator to działający po stronie PHP klient dla Spectrum, opcjonalnego sidecara przyspieszającego działającego poza procesem. To wzmocniony klient Hypertext Transfer Protocol (HTTP) z wyłącznikiem awaryjnym, tokenami uprawnień JSON Web Token (JWT), pojedynczą ponowną próbą przy błędach przejściowych oraz transportem typu server-sent events do strumieniowania postępu zadań. Silnik działa również bez sidecara. Użyj tego modułu, aby dodać przyspieszenie bez czynienia go wymaganym.

Stabilność: eksperymentalna. Spectrum jest opcjonalnym sidecarem, a nie zamrożonym publicznym interfejsem programowania aplikacji (API). Implementowany przez niego interfejs SpectrumInterface udokumentowano jako eksperymentalny na stronie Contracts / Observability. Ten klient należy do tego samego poziomu. Transport, format tokenu oraz kształt budżetu mogą się zmieniać między wersjami pomocniczymi.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Spectrum przenosi zadania obciążające procesor do lokalnego procesu sidecara, w tym wykrywanie sprzętu, parsowanie formatu Portable Document Format (PDF) oraz kompresję obrazów. SpectrumClient to klient zgodny z PHP Standards Recommendation 18 (PSR-18), który implementuje zamrożony interfejs NextPDF\Contracts\SpectrumInterface. Opiera się na interfejsach ClientInterface, RequestFactoryInterface oraz StreamFactoryInterface, zamiast na sztywno wbudowanym stosie Hypertext Transfer Protocol (HTTP).

Klient zakłada, że zależność może ulec awarii. Wyłącznik awaryjny otwiera się po trzech kolejnych niepowodzeniach. Gdy jest otwarty, isAvailable() zwraca false w okresie wykładniczego odczekiwania, dzięki czemu ścieżka krytyczna nie wywołuje wciąż niedostępnego sidecara. Wynik sondowania jest buforowany z czasem życia (TTL). Po skonfigurowaniu sekretu aplikacji każde żądanie wychodzące zawiera token uprawnień żądania (Request Capability Token). Token to krótkotrwały JWT HS256 ograniczony do uprawnień wymaganych przez dany punkt końcowy. Jego czas życia wynosi 120 sekund lub 30 sekund w trybie autoryzacji o wysokim poziomie kontroli. Przejściowe błędy 5xx oraz przekroczenia limitu czasu są ponawiane jeden raz. Błędy uwierzytelniania i parsowania nigdy nie są ponawiane.

SspectrumClient przechowuje stan oddzielnie dla każdej instancji. Stan wyłącznika awaryjnego oraz pamięć podręczna sondowania nie są współdzielone. Każdy proces roboczy PHP FastCGI Process Manager (PHP-FPM) powinien mieć własną instancję. Wyniki przetwarzania wsadowego mają własne typy. BatchResult zawiera wpisy BatchItem ze statusem BatchItemStatus, podsumowanie BatchSummary ze wskaźnikiem powodzenia oraz opcjonalny identyfikator śledzenia. HardwareReport oraz HardwareCapabilities opisują wykryty poziom sprzętu. HardwareCapabilities::satisfies() sprawdza wymaganie poziomu programowo. Typy wyliczeniowe DegradePolicy oraz AuthorizationMode sterują zachowaniem przy utracie uprawnień oraz rygorem tokenów. Cały moduł jest oznaczony jako @since 2.1.0.

Powierzchnia API

Typ	Kluczowe składowe	Rola
SpectrumClient	isAvailable(), probe(), getBudget(), request()	Klient sidecara PSR-18, który implementuje SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Typowany wynik przetwarzania wsadowego
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Wynik pojedynczego elementu oraz typ wyliczeniowy statusu
BatchSummary	isFullSuccess(), successRate()	Zbiorcze podsumowanie przetwarzania wsadowego
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Wykryte możliwości sidecara
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Programowe rozgałęzianie według możliwości
DegradePolicy / AuthorizationMode	przypadki wyliczeniowe	Zachowanie przy degradacji oraz rygor tokenów

Uruchom composer docs:generate-api-php -- --module=Accelerator, aby wygenerować pełną tabelę PHPDoc.

Przykład kodu — szybki start

Zanim zaczniesz na nim polegać, sprawdź sidecara przez wyłącznik awaryjny.

<?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.';
}

Przykład kodu — produkcja

Wyślij partię przez sidecara, gdy działa, a w przeciwnym razie skorzystaj z mechanizmu awaryjnego zgodnie z polityką degradacji.

<?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 '';
    }
}

Przypadki brzegowe i pułapki

• isAvailable() to chwilowe sprawdzenie objęte wyłącznikiem awaryjnym. Wynik true może zmienić się na false przed następnym wywołaniem. Obsłuż sytuację, w której sidecar przestaje działać między wywołaniami.
• Stan wyłącznika awaryjnego i pamięć podręczna sondowania są przechowywane oddzielnie dla każdej instancji. Współdzielenie jednego SpectrumClient przez wiele procesów roboczych niweczy działanie wyłącznika. Przydziel każdemu procesowi roboczemu własną instancję.
• Tokeny uprawnień są krótkotrwałe (120 s, 30 s w trybie o wysokim poziomie kontroli). Długotrwała operacja musi pozyskać nowy token, a nie używać ponownie istniejącego.
• Błędy uwierzytelniania i parsowania nigdy nie są ponawiane; ponawiane są tylko przejściowe odpowiedzi 5xx oraz przekroczenia limitu czasu, i to jedynie raz. Nie zakładaj idempotentnego ponawiania wykraczającego poza ten zakres.
• Wartość null dla SpectrumInterface to prawidłowy stan „brak akceleratora”, a nie błąd. To polityka degradacji decyduje, czy jest to stan krytyczny.

Wydajność

Klient dodaje pomijalny narzut; właściwą pracę wykonuje sidecar. Wyłącznik awaryjny to główny mechanizm kontroli niezawodności. Ogranicza zmarnowane cykle żądanie–odpowiedź, gdy sidecar jest niedostępny. Wartość performance_budget wynosząca 1500 ms czasu rzeczywistego / 64 MB szczytowego zużycia pamięci odnosi się do referencyjnego obciążenia silnika, a nie do umowy o poziomie usług (SLA) sidecara. Profil odtwarzalności to structural. Wynik przetwarzania wsadowego zawiera identyfikator śledzenia oraz znaczniki czasu, więc dwa uruchomienia różnią się w tych polach.

Uwagi dotyczące bezpieczeństwa

Granica sidecara jest granicą zaufania. Po skonfigurowaniu sekretu aplikacji żądania zawierają tokeny uprawnień HS256 ograniczone do danego punktu końcowego. Traktuj ten sekret jak poświadczenie z menedżera sekretów i nigdy nie umieszczaj go w repozytorium. Tryb autoryzacji o wysokim poziomie kontroli skraca czas życia tokenu do 30 sekund dla wrażliwych punktów końcowych. Dostarczony przez operatora adres URL (Uniform Resource Locator) sidecara jest walidowany podczas tworzenia konfiguracji, a nie przy pierwszym żądaniu: akceptowane są wyłącznie http:// i https:// z niepustym hostem lub unix:// z niepustą ścieżką gniazda; każdy inny schemat (gopher://, file://, ftp://, …) lub sieciowy adres URL bez hosta zostaje odrzucony fail-closed już na etapie konstrukcji. To obrona w głąb przed fałszowaniem żądań po stronie serwera (SSRF) oraz nieoczekiwanym ruchem wychodzącym, dzięki czemu błędnie skonfigurowany punkt końcowy nigdy nie dociera do klienta HTTP. Odpowiedzi sidecara to dane zewnętrzne. Zwaliduj je i traktuj jako niezaufane, zanim ponownie trafią do silnika. Klasa kontroli eksportu legal-review-required przypisana do tej strony odzwierciedla fakt, że funkcja przyspieszania wykorzystuje transport kryptograficzny i oczekuje na przegląd pod kątem kontroli eksportu. Zapoznaj się z tym przeglądem, zanim rozpowszechnisz wersję, która ją włącza.

Zgodność

Ten moduł nie formułuje żadnych normatywnych twierdzeń dotyczących specyfikacji PDF. Jest to klient HTTP dla wewnętrznego protokołu przyspieszania. Protokół jest zdefiniowany przez silnik, a nie znormalizowany, więc nie ma tu klauzul, które można by zacytować. Tam, gdzie praca sidecara (parsowanie PDF, kompresja) ma wymiar zgodności, ta zgodność jest udokumentowana na odpowiedniej stronie modułu oraz walidowana przez oracle i pakiety wzorcowe w /modules/core/conformance/.

Zobacz także

• Contracts / Observability — interfejs SpectrumInterface implementowany przez tego klienta.
• Moduł Observability — powierzchnia stanu w czasie wykonania dla pracy objętej przyspieszeniem.
• Moduł Performance — budżety dla pracy objętej przyspieszeniem.
• Model bezpieczeństwa silnika