Accelerator: client per il sidecar Spectrum

In sintesi

Il modulo Accelerator è il client lato PHP per Spectrum, il sidecar di accelerazione opzionale fuori processo. È un client HTTP irrobustito. Fornisce un circuit breaker, token di capacità JSON Web Token (JWT), un solo ritentativo in caso di guasti transitori e un trasporto server-sent-events per trasmettere in streaming l’avanzamento dei job. Il motore continua a funzionare anche senza di esso. Questo modulo serve a rendere l’accelerazione iniettabile, non obbligatoria.

Stabilità: sperimentale. Spectrum è un sidecar opzionale, non un’API pubblica congelata. L’SpectrumInterface che implementa è documentata come sperimentale in Contracts / Observability. Questo client segue lo stesso livello. Il trasporto, il formato del token e la struttura del budget possono cambiare tra versioni minori.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Spectrum delega a un processo sidecar locale il lavoro a forte uso di processore. Questo lavoro include il rilevamento dell’hardware, l’analisi dei PDF e la compressione delle immagini. SpectrumClient è un client PSR-18 che implementa l’NextPDF\Contracts\SpectrumInterface congelata. Dipende da un ClientInterface, un RequestFactoryInterface e uno StreamFactoryInterface, non da uno stack HTTP vincolato.

Il client è progettato per gestire una dipendenza inaffidabile. Un circuit breaker si apre dopo tre guasti consecutivi. Mentre è aperto, isAvailable() restituisce false durante una finestra di backoff esponenziale, evitando che un percorso critico invii richieste ripetute a un sidecar inattivo. Il risultato della sonda è memorizzato in cache con un time-to-live (TTL). Quando è configurato un segreto dell’applicazione, ogni richiesta in uscita trasporta un Request Capability Token. Il token è un JWT HS256 a breve durata, con ambito limitato alle capacità richieste dall’endpoint. La sua durata è di 120 secondi, oppure 30 secondi in modalità di autorizzazione ad alto controllo. Gli errori transitori 5xx e i timeout vengono ritentati una volta. Gli errori di autenticazione e di analisi non vengono mai ritentati.

SspectrumClient è stateful a livello di singola istanza. Lo stato del circuit breaker e la cache della sonda non sono condivisi. Ogni worker PHP-FPM dovrebbe possedere la propria istanza. I risultati dei batch sono tipizzati. BatchResult trasporta voci BatchItem con un BatchItemStatus, un BatchSummary con un tasso di successo e un id di traccia opzionale. HardwareReport e HardwareCapabilities descrivono il livello hardware rilevato. HardwareCapabilities::satisfies() valuta programmaticamente un requisito di livello. Gli enum DegradePolicy e AuthorizationMode determinano il comportamento in caso di perdita di capacità e il livello di severità dei token. L’intero modulo è @since 2.1.0.

Superficie API

Tipo	Membri chiave	Ruolo
SpectrumClient	isAvailable(), probe(), getBudget(), request()	Client sidecar PSR-18 che implementa SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Esito tipizzato del batch
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Risultato per voce ed enum di stato
BatchSummary	isFullSuccess(), successRate()	Riepilogo aggregato del batch
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Capacità del sidecar rilevate
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Ramificazione programmatica delle capacità
DegradePolicy / AuthorizationMode	casi enum	Comportamento di degradazione e severità dei token

Eseguire composer docs:generate-api-php -- --module=Accelerator per ottenere la tabella PHPDoc completa.

Esempio di codice — Avvio rapido

Sondare il sidecar dietro il circuit breaker prima di farne affidamento.

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

Esempio di codice — Produzione

Inviare un batch attraverso il sidecar quando è integro e ricorrere al fallback secondo la politica di degradazione se non lo è.

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

Casi limite e insidie

• isAvailable() è un controllo puntuale, soggetto al circuit breaker. Un risultato true può diventare false prima della chiamata successiva. Prevedere che il sidecar possa cadere nel frattempo.
• Lo stato del circuit breaker e della cache della sonda è locale alla singola istanza. Condividere un singolo SpectrumClient tra i worker vanifica il breaker. Assegnarne uno a ogni worker.
• I token di capacità sono a breve durata (120 s, 30 s in modalità ad alto controllo). Un’operazione di lunga durata deve ottenere un token nuovo, non riutilizzarne uno.
• Gli errori di autenticazione e di analisi non vengono mai ritentati; solo gli errori 5xx transitori e i timeout lo sono, e una sola volta. Non presumere ritentativi idempotenti oltre tale limite.
• Un SpectrumInterface null è uno stato «nessun acceleratore» valido, non un errore. La politica di degradazione decide se ciò è fatale.

Prestazioni

Il sovraccarico proprio del client è trascurabile. Il lavoro avviene nel sidecar. Il circuit breaker è la principale leva di affidabilità. Limita i round-trip sprecati quando il sidecar è inattivo. Il performance_budget di 1500 ms di wall / 64 MB di picco è il carico di lavoro di riferimento del motore, non un service-level agreement (SLA) del sidecar. Il profilo di riproducibilità è structural. Il risultato di un batch trasporta un id di traccia e timestamp, quindi due esecuzioni differiscono per quei campi.

Note sulla sicurezza

Il confine del sidecar è un confine di fiducia. Le richieste trasportano token di capacità HS256 con ambito limitato all’endpoint quando è configurato un segreto dell’applicazione. Trattare quel segreto come una credenziale proveniente da un gestore di segreti, mai inserita in commit. La modalità di autorizzazione ad alto controllo riduce la durata del token a 30 secondi per gli endpoint sensibili. L’URL del sidecar fornito dall’operatore è validato quando la configurazione viene costruita, non alla prima richiesta: sono accettati solo http:// e https:// con un host non vuoto, oppure unix:// con un percorso di socket non vuoto; qualsiasi altro schema (gopher://, file://, ftp://, …) o un URL di rete privo di host fallisce in modo chiuso alla costruzione. È difesa in profondità contro SSRF ed egress imprevisti: un endpoint mal configurato non raggiunge mai il client HTTP. Le risposte del sidecar sono dati esterni. Validarle e trattarle come non attendibili prima che rientrino nel motore. La classe di controllo dell’esportazione legal-review-required su questa pagina riflette il fatto che la funzionalità di accelerazione comporta un trasporto crittografico ed è in attesa di una revisione sul controllo dell’esportazione. Consultare quella revisione prima di redistribuire una build che la abilita.

Conformità

Questo modulo non formula alcuna affermazione normativa sulla specifica PDF. È un client HTTP per un protocollo di accelerazione interno. Il protocollo è definito dal motore, non da uno standard le cui clausole debbano essere citate. Laddove il lavoro svolto dal sidecar (analisi dei PDF, compressione) abbia una dimensione di conformità, tale conformità è documentata nella pagina del modulo pertinente e validata dall’oracolo e dalle suite golden in /modules/core/conformance/.

Vedere anche

• Contracts / Observability — l’SpectrumInterface che questo client implementa.
• Modulo Observability — superficie dello stato a runtime che osserva il lavoro accelerato.
• Modulo Performance — i budget rispetto ai quali viene eseguito il lavoro accelerato.
• Modello di sicurezza del motore