Accelerator : client sidecar pour Spectrum

En bref

Le module Accelerator est le client PHP de Spectrum, le sidecar d’accélération hors processus facultatif. C’est un client HTTP durci : il fournit un coupe-circuit, des jetons de capacité JSON Web Token (JWT), une nouvelle tentative unique en cas de défaut transitoire et un transport server-sent-events pour diffuser la progression des tâches. Le moteur fonctionne sans lui. Ce module existe pour que l’accélération soit injectable, pas obligatoire.

Stabilité : expérimentale. Spectrum est un sidecar facultatif, pas une API publique figée. L’interface SpectrumInterface qu’il implémente est documentée comme expérimentale dans Contracts / Observability. Ce client suit donc ce statut. Le transport, le format du jeton et la forme du budget peuvent changer entre versions mineures.

Installation

composer require nextpdf/core:^3

Vue d’ensemble conceptuelle

Spectrum décharge les traitements gourmands en processeur vers un processus sidecar local. Cela comprend la détection du matériel, l’analyse PDF et la compression d’images. SpectrumClient est un client PSR-18 qui implémente l’interface figée NextPDF\Contracts\SpectrumInterface. Il dépend d’un ClientInterface, d’un RequestFactoryInterface et d’un StreamFactoryInterface, pas d’une pile HTTP câblée en dur.

Le client est conçu pour dépendre d’un service peu fiable. Un coupe-circuit s’ouvre après trois échecs consécutifs. Tant qu’il est ouvert, isAvailable() renvoie false pendant une fenêtre de backoff exponentiel, afin qu’un chemin critique ne sollicite pas sans cesse un sidecar hors service. Le résultat de la sonde est mis en cache avec une durée de vie (TTL). Lorsqu’un secret applicatif est configuré, chaque requête sortante transporte un Request Capability Token. Ce jeton est un JWT HS256 de courte durée, dont la portée est limitée aux capacités requises par le point de terminaison. Sa durée de vie est de 120 secondes, ou de 30 secondes en mode d’autorisation à fort contrôle. Les erreurs 5xx transitoires et les expirations de délai font l’objet d’une seule nouvelle tentative. Les erreurs d’authentification et d’analyse ne sont jamais retentées.

SspectrumClient conserve un état propre à chaque instance. L’état du coupe-circuit et le cache de la sonde ne sont pas partagés. Chaque worker PHP-FPM doit disposer de sa propre instance. Les résultats de lot sont typés. BatchResult porte des entrées BatchItem avec un BatchItemStatus, un BatchSummary avec un taux de réussite, et un identifiant de trace facultatif. HardwareReport et HardwareCapabilities décrivent le palier matériel détecté. HardwareCapabilities::satisfies() indique par programme si une exigence de palier est satisfaite. Les énumérations DegradePolicy et AuthorizationMode déterminent le comportement en cas de perte de capacité et la rigueur des jetons. L’ensemble du module est @since 2.1.0.

Surface de l’API

Type	Membres clés	Rôle
SpectrumClient	isAvailable(), probe(), getBudget(), request()	Client sidecar PSR-18 implémentant SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Résultat de lot typé
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Résultat par élément et énumération de statut
BatchSummary	isFullSuccess(), successRate()	Résumé agrégé du lot
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Capacités détectées du sidecar
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Choix programmatique selon les capacités
DegradePolicy / AuthorizationMode	cas d’énumération	Comportement de dégradation et rigueur des jetons

Exécute composer docs:generate-api-php -- --module=Accelerator pour obtenir la table PHPDoc complète.

Exemple de code — Démarrage rapide

Sonde le sidecar via le coupe-circuit avant de t’y fier.

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

Exemple de code — Production

Envoie un lot via le sidecar lorsqu’il est sain, puis bascule sur la politique de dégradation lorsqu’il ne l’est pas.

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

Cas limites & pièges

• isAvailable() est une vérification ponctuelle protégée par coupe-circuit. Un résultat true peut devenir false avant l’appel suivant. Gère un sidecar qui disparaît entre-temps.
• L’état du coupe-circuit et celui du cache de la sonde sont propres à chaque instance. Partager un seul SpectrumClient entre les workers neutralise le coupe-circuit. Donne à chaque worker le sien.
• Les jetons de capacité sont de courte durée (120 s, 30 s en mode à fort contrôle). Une opération de longue durée doit obtenir un nouveau jeton, et non en réutiliser un.
• Les erreurs d’authentification et d’analyse ne sont jamais retentées ; seuls les 5xx transitoires et les expirations de délai le sont, et une seule fois. Ne suppose pas de nouvelle tentative idempotente au-delà de cela.
• Une SpectrumInterface nulle est un état « pas d’accélérateur » valide, pas une erreur. La politique de dégradation décide si cela est fatal.

Performance

La surcharge propre au client est négligeable. Le travail se fait dans le sidecar. Le coupe-circuit est le principal levier de fiabilité. Il limite les allers-retours inutiles lorsque le sidecar est hors service. Le performance_budget de 1500 ms en temps réel / 64 Mo de pic correspond à la charge de référence du moteur, pas à un accord de niveau de service (SLA) du sidecar. Le profil de reproductibilité est structural. Un résultat de lot porte un identifiant de trace et des horodatages, de sorte que deux exécutions diffèrent sur ces champs.

Notes de sécurité

La frontière du sidecar est une limite de confiance. Les requêtes portent des jetons de capacité HS256 dont la portée est limitée au point de terminaison lorsqu’un secret applicatif est configuré. Traite ce secret comme un identifiant provenant d’un gestionnaire de secrets, jamais stocké dans le dépôt. Le mode d’autorisation à fort contrôle raccourcit la durée de vie du jeton à 30 secondes pour les points de terminaison sensibles. L’URL du sidecar fournie par l’opérateur est validée lors de la construction de la configuration, et non à la première requête : seuls http:// et https:// avec un hôte non vide, ou unix:// avec un chemin de socket non vide, sont acceptés ; tout autre schéma (gopher://, file://, ftp://, …) ou une URL réseau sans hôte échoue en mode fermé à la construction. C’est une défense en profondeur contre le SSRF et les sorties réseau inattendues, afin qu’un point de terminaison mal configuré n’atteigne jamais le client HTTP. Les réponses du sidecar sont des données externes. Valide-les et traite-les comme non fiables avant qu’elles ne réintègrent le moteur. La classe de contrôle des exportations legal-review-required de cette page reflète le fait que la fonctionnalité d’accélération comporte un transport cryptographique et est en attente d’un examen de contrôle des exportations. Consulte cet examen avant de redistribuer une version qui l’active.

Conformité

Ce module n’avance aucune revendication normative sur la spécification PDF. C’est un client HTTP pour un protocole d’accélération interne. Le protocole est défini par le moteur, pas par un protocole normalisé dont les clauses doivent être citées. Lorsque le travail effectué par le sidecar (analyse PDF, compression) comporte une dimension de conformité, cette conformité est documentée sur la page de module correspondante et validée par l’oracle et les suites golden dans /modules/core/conformance/.

Voir aussi

• Contracts / Observability — la SpectrumInterface implémentée par ce client.
• Module Observability — surface d’état d’exécution qui observe les traitements accélérés.
• Module Performance — budgets par rapport auxquels s’exécutent les traitements accélérés.
• Modèle de sécurité du moteur