Accelerator: Spectrum-sidecarclient

In een oogopslag

De Accelerator-module is de PHP-client voor Spectrum, de optionele out-of-process acceleratiesidecar. Het is een geharde Hypertext Transfer Protocol (HTTP)-client met een circuit breaker, JSON Web Token (JWT)-capabilitytokens, één nieuwe poging bij tijdelijke fouten en server-sent events-transport voor gestreamde taakvoortgang. De engine werkt ook zonder de sidecar. Gebruik deze module om acceleratie te injecteren zonder die verplicht te maken.

Stabiliteit: experimenteel. Spectrum is een optionele sidecar, geen bevroren publieke application programming interface (API). De SpectrumInterface die deze implementeert is gedocumenteerd als experimenteel op Contracts / Observability. Deze client volgt hetzelfde niveau. Het transport, het tokenformaat en de budgetvorm kunnen tussen minor-versies veranderen.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Spectrum verplaatst processorintensief werk naar een lokaal sidecarproces, zoals hardwaredetectie, het parsen van Portable Document Format (PDF) en beeldcompressie. SpectrumClient is een PHP Standards Recommendation 18 (PSR-18)-client die de bevroren NextPDF\Contracts\SpectrumInterface implementeert. Hij is afhankelijk van een ClientInterface, een RequestFactoryInterface en een StreamFactoryInterface, en dus niet van een hard ingebouwde Hypertext Transfer Protocol (HTTP)-stack.

De client gaat ervan uit dat de afhankelijkheid kan falen. Een circuit breaker opent na drie opeenvolgende fouten. Zolang die open is, retourneert isAvailable() gedurende een exponentieel backoff-venster false, zodat een hot path niet telkens een onbeschikbare sidecar blijft aanroepen. Het proberesultaat wordt gecachet met een time-to-live (TTL). Wanneer je een app-secret configureert, krijgt elk uitgaand verzoek een Request Capability Token mee. Dat token is een kortlevende HS256-JWT die beperkt is tot de capabilities die het endpoint vereist. De levensduur is 120 seconden, of 30 seconden in de high-control-autorisatiemodus. Tijdelijke 5xx- en time-outfouten worden één keer opnieuw geprobeerd. Authenticatie- en parsefouten worden nooit opnieuw geprobeerd.

SpectrumClient houdt status per instantie bij. De circuit-breakerstatus en de probecache worden niet gedeeld. Elke PHP FastCGI Process Manager (PHP-FPM)-worker moet een eigen instantie aanhouden. Batchresultaten zijn getypeerd. BatchResult bevat BatchItem-vermeldingen met een BatchItemStatus, een BatchSummary met een slagingspercentage en een optionele trace-ID. HardwareReport en HardwareCapabilities beschrijven het gedetecteerde hardwareniveau. HardwareCapabilities::satisfies() controleert programmatisch een niveauvereiste. De enums DegradePolicy en AuthorizationMode bepalen het gedrag bij capabilityverlies en hoe strikt tokens zijn. De hele module is @since 2.1.0.

API-oppervlak

Type	Belangrijkste leden	Rol
SpectrumClient	isAvailable(), probe(), getBudget(), request()	PSR-18-sidecarclient die SpectrumInterface implementeert
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Getypeerd batchresultaat
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Resultaat per item en status-enum
BatchSummary	isFullSuccess(), successRate()	Geaggregeerde batchsamenvatting
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Gedetecteerde sidecar-capabilities
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Programmatisch vertakken op capabilities
DegradePolicy / AuthorizationMode	enum-cases	Degradatiegedrag en strengheid van tokens

Voer composer docs:generate-api-php -- --module=Accelerator uit om de volledige PHPDoc-tabel te genereren.

Codevoorbeeld — Snelstart

Probe de sidecar via de circuit breaker voordat je erop vertrouwt.

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

Codevoorbeeld — Productie

Stuur een batch door de sidecar wanneer die gezond is, en val terug volgens het degradatiebeleid wanneer dat niet zo is.

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

Randgevallen en valkuilen

• isAvailable() is een momentopnamecontrole met circuit breaker. Een true-resultaat kan vóór de volgende aanroep false worden. Houd er rekening mee dat een sidecar tussen aanroepen kan wegvallen.
• De status voor de circuit breaker en de probecache is per instantie. Eén SpectrumClient delen over meerdere workers heen ondermijnt de breaker. Geef elke worker een eigen instantie.
• Capabilitytokens zijn kortlevend (120 s, 30 s in de high-control-modus). Een langlopende operatie moet een nieuw token verkrijgen en geen bestaand token hergebruiken.
• Authenticatie- en parsefouten worden nooit opnieuw geprobeerd; alleen tijdelijke 5xx-responses en time-outs worden opnieuw geprobeerd, en slechts één keer. Ga er niet van uit dat daarbuiten idempotent opnieuw wordt geprobeerd.
• Een null-SpectrumInterface is een geldige status “geen accelerator”, geen fout. Het degradatiebeleid bepaalt of dat fataal is.

Prestaties

De client voegt verwaarloosbare overhead toe; de sidecar doet het werk. De circuit breaker is de belangrijkste betrouwbaarheidsmaatregel. Die beperkt verspilde round-trips wanneer de sidecar onbeschikbaar is. Het performance_budget van 1500 ms wall / 64 MB piek is de referentiewerklast van de engine, geen service-level agreement (SLA) van de sidecar. Het reproduceerbaarheidsprofiel is structural. Een batchresultaat bevat een trace-ID en tijdstempels, dus twee runs verschillen in die velden.

Beveiligingsnotities

De sidecargrens is een vertrouwensgrens. Wanneer je een app-secret configureert, dragen verzoeken HS256-capabilitytokens mee die tot het endpoint beperkt zijn. Behandel dat secret als een credential uit een secret manager en commit het nooit. De high-control-autorisatiemodus verkort de levensduur van tokens tot 30 seconden voor gevoelige endpoints. De door de operator opgegeven Uniform Resource Locator (URL) van de sidecar wordt gevalideerd op het moment dat de configuratie wordt opgebouwd, niet pas bij het eerste verzoek: alleen http:// en https:// met een niet-lege host, of unix:// met een niet-leeg socketpad, worden geaccepteerd; elk ander schema (gopher://, file://, ftp://, …) of een netwerk-URL zonder host faalt fail-closed bij constructie. Dit is defense-in-depth tegen server-side request forgery (SSRF) en onverwacht uitgaand verkeer, zodat een verkeerd geconfigureerd endpoint de HTTP-client nooit bereikt. Sidecar-responses zijn externe gegevens. Valideer ze en behandel ze als niet-vertrouwd voordat ze de engine weer binnenkomen. De export-controleklasse legal-review-required op deze pagina geeft aan dat de acceleratiefunctie cryptografisch transport bevat en in afwachting is van een export-controlebeoordeling. Raadpleeg die beoordeling voordat je een build herdistribueert waarin dit is ingeschakeld.

Conformiteit

Deze module doet geen normatieve PDF-specificatieclaim. Het is een HTTP-client voor een intern acceleratieprotocol. Het protocol is door de engine gedefinieerd en niet gestandaardiseerd, dus er zijn hier geen clausules om te citeren. Waar sidecarwerk (PDF-parsing, compressie) een conformiteitsdimensie heeft, is die conformiteit gedocumenteerd op de betreffende modulepagina en gevalideerd door de oracle- en golden-suites in /modules/core/conformance/.

Zie ook

• Contracts / Observability — de SpectrumInterface die deze client implementeert.
• Observability module — runtime-statusoppervlak voor versneld werk.
• Performance module — budgetten voor versneld werk.
• Beveiligingsmodel van de engine