Accelerator: cliente para el sidecar de Spectrum

De un vistazo

El módulo Accelerator es el cliente del lado de PHP para Spectrum, el sidecar opcional de aceleración fuera del proceso. Es un cliente HTTP reforzado. Proporciona un cortacircuitos, tokens de capacidad JSON Web Token (JWT), un único reintento ante fallos transitorios y un transporte de eventos enviados por el servidor para transmitir el progreso de los trabajos. El motor funciona sin él. Este módulo existe para que la aceleración sea inyectable, no obligatoria.

Estabilidad: experimental. Spectrum es un sidecar opcional, no una API pública congelada. La SpectrumInterface que implementa está documentada como experimental en Contracts / Observability. Este cliente sigue ese nivel. El transporte, el formato del token y la forma del presupuesto pueden cambiar entre versiones menores.

Instalación

composer require nextpdf/core:^3

Visión general conceptual

Spectrum descarga el trabajo intensivo de procesador en un proceso sidecar local. Ese trabajo incluye la detección de hardware, el análisis de PDF y la compresión de imágenes. SpectrumClient es un cliente PSR-18 que implementa la NextPDF\Contracts\SpectrumInterface congelada. Depende de una ClientInterface, una RequestFactoryInterface y una StreamFactoryInterface, no de una pila HTTP cableada de forma fija.

El cliente está diseñado para una dependencia poco fiable. Un cortacircuitos se abre tras tres fallos consecutivos. Mientras está abierto, isAvailable() devuelve false durante una ventana de retroceso exponencial, de modo que una ruta crítica no sature un sidecar caído. El resultado de la sonda se almacena en caché con un tiempo de vida (TTL). Cuando se configura un secreto de aplicación, cada solicitud saliente lleva un Request Capability Token. Ese token es un JWT HS256 de corta duración, con ámbito limitado a las capacidades requeridas por el endpoint. Su vida útil es de 120 segundos, o de 30 segundos en el modo de autorización de alto control. Los errores 5xx transitorios y los tiempos de espera se reintentan una vez. Los errores de autenticación y de análisis nunca se reintentan.

SspectrumClient tiene estado por instancia. El estado del cortacircuitos y la caché de la sonda no se comparten. Cada worker de PHP-FPM debería tener su propia instancia. Los resultados de lote están tipados. BatchResult contiene entradas BatchItem con un BatchItemStatus, un BatchSummary con una tasa de éxito y un identificador de traza opcional. HardwareReport y HardwareCapabilities describen el nivel de hardware detectado. HardwareCapabilities::satisfies() responde de forma programática a un requisito de nivel. Las enumeraciones DegradePolicy y AuthorizationMode deciden cómo se comporta una pérdida de capacidad y cuál es la estrictez del token. Todo el módulo es @since 2.1.0.

Superficie de la API

Tipo	Miembros clave	Rol
SpectrumClient	isAvailable(), probe(), getBudget(), request()	Cliente sidecar PSR-18 que implementa SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Resultado de lote tipado
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Resultado por elemento y enumeración de estado
BatchSummary	isFullSuccess(), successRate()	Resumen agregado del lote
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Capacidades detectadas del sidecar
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Ramificación programática de capacidades
DegradePolicy / AuthorizationMode	casos de la enumeración	Comportamiento de degradación y estrictez del token

Ejecutar composer docs:generate-api-php -- --module=Accelerator para obtener la tabla PHPDoc completa.

Ejemplo de código: inicio rápido

Sondear el sidecar después del cortacircuitos antes de depender de él.

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

Ejemplo de código: producción

Enviar un lote a través del sidecar cuando esté en buen estado y recurrir a la política de degradación cuando no lo esté.

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

Casos límite y trampas

• isAvailable() es una comprobación puntual, con cortacircuitos. Un resultado true puede pasar a false antes de la siguiente llamada. Gestionar un sidecar que se caiga entre medias.
• El estado del cortacircuitos y de la caché de la sonda es por instancia. Compartir un único SpectrumClient entre workers anula el cortacircuitos. Dar a cada worker el suyo propio.
• Los tokens de capacidad son de corta duración (120 s, 30 s en el modo de alto control). Una operación de larga duración debe obtener un token nuevo, no reutilizar uno.
• Los errores de autenticación y de análisis nunca se reintentan; solo se reintentan los errores 5xx transitorios y los tiempos de espera, y solo una vez. No suponer reintentos idempotentes más allá de eso.
• Una SpectrumInterface nula es un estado válido de «sin acelerador», no un error. La política de degradación decide si eso es fatal.

Rendimiento

La sobrecarga propia del cliente es insignificante. El trabajo se realiza en el sidecar. El cortacircuitos es la principal palanca de fiabilidad. Limita los viajes de ida y vuelta desperdiciados cuando el sidecar está caído. El performance_budget de 1500 ms de tiempo de pared / 64 MB de pico corresponde a la carga de trabajo de referencia del motor, no a un acuerdo de nivel de servicio (SLA) del sidecar. El perfil de reproducibilidad es structural. Un resultado de lote lleva un identificador de traza y marcas de tiempo, por lo que dos ejecuciones difieren en esos campos.

Notas de seguridad

El límite del sidecar es un límite de confianza. Las solicitudes llevan tokens de capacidad HS256 con ámbito limitado al endpoint cuando se configura un secreto de aplicación. Tratar ese secreto como una credencial procedente de un gestor de secretos, nunca incluida en el control de versiones. El modo de autorización de alto control reduce la vida útil del token a 30 segundos para los endpoints sensibles. La URL del sidecar suministrada por el operador se valida al construir la configuración, no en la primera solicitud: solo se aceptan http:// y https:// con un host no vacío, o unix:// con una ruta de socket no vacía; cualquier otro esquema (gopher://, file://, ftp://, …) o una URL de red sin host falla de forma cerrada durante la construcción. Esto es defensa en profundidad frente a SSRF y frente a la salida de tráfico inesperada, de modo que un endpoint mal configurado nunca llega al cliente HTTP. Las respuestas del sidecar son datos externos. Validarlas y tratarlas como no fiables antes de que vuelvan a entrar en el motor. La clase de control de exportación legal-review-required de esta página refleja que la función de aceleración incorpora transporte criptográfico y está pendiente de una revisión de control de exportación. Consultar esa revisión antes de redistribuir una compilación que la habilite.

Conformidad

Este módulo no hace ninguna afirmación normativa sobre la especificación PDF. Es un cliente HTTP para un protocolo de aceleración interno. El protocolo está definido por el motor; no es un protocolo estandarizado cuyas cláusulas deban citarse. Cuando el trabajo que realiza el sidecar (análisis de PDF, compresión) tiene una dimensión de conformidad, esa conformidad se documenta en la página del módulo correspondiente y se valida mediante el oráculo y las suites de referencia en /modules/core/conformance/.

Véase también

• Contracts / Observability: la SpectrumInterface que implementa este cliente.
• Módulo Observability: superficie de estado en tiempo de ejecución que observa el trabajo acelerado.
• Módulo Performance: presupuestos contra los que se ejecuta el trabajo acelerado.
• Modelo de seguridad del motor