Accelerator: Spectrum-Sidecar-Client

Auf einen Blick

Das Accelerator-Modul ist der PHP-seitige Client für Spectrum, den optionalen, prozessexternen Beschleunigungs-Sidecar. Es stellt einen gehärteten HTTP-Client bereit: mit Circuit Breaker, JSON-Web-Token-(JWT-)Capability-Token, einmaligem Wiederholungsversuch bei vorübergehenden Fehlern und Server-Sent-Events-Transport für gestreamten Job-Fortschritt. Die Engine funktioniert auch ohne dieses Modul. Dieses Modul sorgt dafür, dass Beschleunigung injizierbar bleibt und keine Voraussetzung ist.

Stabilität: experimentell. Spectrum ist ein optionaler Sidecar, keine eingefrorene öffentliche API. Das SpectrumInterface, das er implementiert, ist unter Contracts / Observability als experimentell dokumentiert. Dieser Client folgt dieser Stufe. Transport, Token-Format und Budget-Struktur können sich zwischen Minor-Versionen ändern.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Spectrum lagert prozessorlastige Aufgaben an einen lokalen Sidecar-Prozess aus. Dazu zählen Hardware-Erkennung, PDF-Parsing und Bildkomprimierung. SpectrumClient ist ein PSR-18-Client, der das eingefrorene NextPDF\Contracts\SpectrumInterface implementiert. Er hängt von einem ClientInterface, einem RequestFactoryInterface und einem StreamFactoryInterface ab, nicht von einem fest verdrahteten HTTP-Stack.

Der Client ist für eine unzuverlässige Abhängigkeit ausgelegt. Ein Circuit Breaker öffnet sich nach drei aufeinanderfolgenden Fehlern. Solange er offen ist, gibt isAvailable() während eines exponentiellen Backoff-Fensters false zurück, damit ein Hot Path einen ausgefallenen Sidecar nicht weiter belastet. Das Probe-Ergebnis wird mit einer Time-to-Live (TTL) zwischengespeichert. Wenn ein App-Secret konfiguriert ist, trägt jede ausgehende Anfrage ein Request-Capability-Token. Dieses Token ist ein kurzlebiges HS256-JWT, das auf die erforderlichen Capabilities des Endpunkts beschränkt ist. Seine Lebensdauer beträgt 120 Sekunden oder 30 Sekunden im High-Control-Autorisierungsmodus. Vorübergehende 5xx- und Timeout-Fehler werden einmal wiederholt. Authentifizierungs- und Parse-Fehler werden niemals wiederholt.

SspectrumClient ist pro Instanz zustandsbehaftet. Der Zustand des Circuit Breakers und der Probe-Cache werden nicht gemeinsam genutzt. Jeder PHP-FPM-Worker sollte eine eigene Instanz verwenden. Batch-Ergebnisse sind typisiert. BatchResult enthält BatchItem-Einträge mit einem BatchItemStatus, eine BatchSummary mit Erfolgsquote und eine optionale Trace-ID. HardwareReport und HardwareCapabilities beschreiben die erkannte Hardware-Stufe. HardwareCapabilities::satisfies() prüft eine Stufenanforderung programmatisch. Die Enums DegradePolicy und AuthorizationMode legen fest, wie ein Capability-Verlust gehandhabt wird und wie strikt Token behandelt werden. Das gesamte Modul ist mit @since 2.1.0 gekennzeichnet.

API-Oberfläche

Typ	Wichtige Mitglieder	Rolle
SpectrumClient	isAvailable(), probe(), getBudget(), request()	PSR-18-Sidecar-Client, der SpectrumInterface implementiert
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Typisiertes Batch-Ergebnis
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Ergebnis und Status-Enum pro Element
BatchSummary	isFullSuccess(), successRate()	Aggregierte Batch-Zusammenfassung
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Erkannte Sidecar-Capabilities
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Programmatische Capability-Verzweigung
DegradePolicy / AuthorizationMode	enum-Fälle	Degradationsverhalten und Token-Striktheit

Führen Sie composer docs:generate-api-php -- --module=Accelerator aus, um die vollständige PHPDoc-Tabelle zu erhalten.

Codebeispiel — Schnellstart

Prüfen Sie den Sidecar über die vom Circuit Breaker abgesicherte Abfrage, bevor Sie sich auf ihn verlassen.

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

Codebeispiel — Produktion

Senden Sie einen Batch über den Sidecar, wenn er gesund ist, und greifen Sie gemäß der Degradationsrichtlinie auf den Fallback zurück, wenn er es nicht ist.

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

Sonderfälle & Fallstricke

• isAvailable() ist eine zeitpunktbezogene, durch den Circuit Breaker abgesicherte Prüfung. Ein Ergebnis von true kann vor dem nächsten Aufruf zu false werden. Planen Sie ein, dass der Sidecar dazwischen ausfallen kann.
• Der Zustand von Circuit Breaker und Probe-Cache ist pro Instanz. Die gemeinsame Nutzung eines einzigen SpectrumClient über mehrere Worker hinweg hebelt den Breaker aus. Geben Sie jedem Worker einen eigenen.
• Capability-Token sind kurzlebig (120 s, 30 s im High-Control-Modus). Ein lang laufender Vorgang muss ein frisches Token beziehen und darf keines wiederverwenden.
• Authentifizierungs- und Parse-Fehler werden niemals wiederholt; nur vorübergehende 5xx-Fehler und Timeouts werden wiederholt, und das nur einmal. Gehen Sie nicht von weiteren idempotenten Wiederholungsversuchen aus.
• Ein null-SpectrumInterface ist ein gültiger Zustand „kein Accelerator“, kein Fehler. Die Degradationsrichtlinie entscheidet, ob das fatal ist.

Performance

Der Eigen-Overhead des Clients ist vernachlässigbar. Die Arbeit findet im Sidecar statt. Der Circuit Breaker ist der wichtigste Zuverlässigkeitshebel. Er begrenzt verschwendete Round-Trips, wenn der Sidecar ausgefallen ist. Das performance_budget von 1500 ms Wall-Time / 64 MB Spitzenwert bezieht sich auf die Referenz-Workload der Engine, nicht auf ein Service-Level-Agreement (SLA) des Sidecars. Das Reproduzierbarkeitsprofil ist structural. Ein Batch-Ergebnis enthält eine Trace-ID und Zeitstempel, sodass sich zwei Durchläufe in diesen Feldern unterscheiden.

Sicherheitshinweise

Die Sidecar-Grenze ist eine Vertrauensgrenze. Anfragen tragen auf den Endpunkt beschränkte HS256-Capability-Token, wenn ein App-Secret konfiguriert ist. Behandeln Sie dieses Secret als Anmeldedaten aus einem Secret Manager und committen Sie es niemals. Der High-Control-Autorisierungsmodus verkürzt die Token-Lebensdauer für sensible Endpunkte auf 30 Sekunden. Die vom Betreiber angegebene Sidecar-URL wird beim Erstellen der Konfiguration validiert, nicht erst bei der ersten Anfrage: Akzeptiert werden nur http:// und https:// mit einem nicht leeren Host oder unix:// mit einem nicht leeren Socket-Pfad; jedes andere Schema (gopher://, file://, ftp://, …) oder eine hostlose Netzwerk-URL schlägt bei der Konstruktion fehl (fail-closed). Dies ist Defence-in-Depth gegen SSRF und unerwarteten ausgehenden Datenverkehr, damit ein falsch konfigurierter Endpunkt niemals den HTTP-Client erreicht. Sidecar-Antworten sind externe Daten. Validieren Sie sie und behandeln Sie sie als nicht vertrauenswürdig, bevor sie wieder in die Engine gelangen. Die Exportkontrollklasse legal-review-required auf dieser Seite spiegelt wider, dass die Beschleunigungsfunktion kryptografischen Transport nutzt und eine Exportkontrollprüfung aussteht. Konsultieren Sie diese Prüfung, bevor Sie einen Build weiterverteilen, der sie aktiviert.

Konformität

Dieses Modul erhebt keinen normativen Anspruch auf die PDF-Spezifikation. Es ist ein HTTP-Client für ein internes Beschleunigungsprotokoll. Das Protokoll ist Engine-definiert, nicht standardisiert und hat keine Klauseln, die zitiert werden müssten. Wo die Arbeit, die der Sidecar ausführt (PDF-Parsing, Komprimierung), eine Konformitätsdimension hat, ist diese Konformität auf der entsprechenden Modulseite dokumentiert und wird durch die Oracle- und Golden-Suites unter /modules/core/conformance/ validiert.

Siehe auch

• Contracts / Observability — das SpectrumInterface, das dieser Client implementiert.
• Observability-Modul — Oberfläche für den Laufzeitzustand, die beschleunigte Arbeit beobachtet.
• Performance-Modul — die Budgets, an denen beschleunigte Arbeit gemessen wird.
• Sicherheitsmodell der Engine