Accelerator: cliente do sidecar Spectrum

Visão geral

O módulo Accelerator é o cliente PHP para o Spectrum, o sidecar opcional de aceleração executado fora do processo. Trata-se de um cliente Hypertext Transfer Protocol (HTTP) reforçado, com circuit breaker, tokens de capacidade JSON Web Token (JWT), mecanismo de nova tentativa para falhas transitórias e transporte por server-sent events para transmitir o progresso dos jobs em fluxo. O motor continua funcionando sem o sidecar. Use este módulo para adicionar aceleração sem torná-la obrigatória.

Estabilidade: experimental. O Spectrum é um sidecar opcional, não uma interface de programação de aplicativos (API) pública e congelada. A SpectrumInterface que ele implementa está documentada como experimental em Contracts / Observability. Este cliente segue esse nível. O transporte, o formato do token e o formato do budget podem mudar entre versões secundárias.

Instalação

composer require nextpdf/core:^3

Visão conceitual

O Spectrum desloca o processamento pesado para um processo sidecar local, incluindo detecção de hardware, análise de Portable Document Format (PDF) e compressão de imagens. O SpectrumClient é um cliente PHP Standards Recommendation 18 (PSR-18) que implementa a NextPDF\Contracts\SpectrumInterface, que é congelada. Ele depende de uma ClientInterface, de uma RequestFactoryInterface e de uma StreamFactoryInterface, e não de uma pilha Hypertext Transfer Protocol (HTTP) definida de forma fixa no código.

O cliente pressupõe que a dependência pode falhar. Um circuit breaker abre após três falhas consecutivas. Enquanto está aberto, isAvailable() retorna false durante uma janela de backoff exponencial, para que um caminho crítico não continue chamando um sidecar indisponível. O resultado da sondagem é armazenado em cache com um time-to-live (TTL). Quando você configura um segredo de aplicação, toda requisição de saída carrega um Request Capability Token. O token é um JWT HS256 de vida curta, limitado às capacidades exigidas pelo endpoint. Seu tempo de vida é de 120 segundos, ou 30 segundos no modo de autorização de alto controle. Erros 5xx transitórios e timeouts passam por uma nova tentativa. Erros de autenticação e de análise nunca passam por nova tentativa.

SspectrumClient mantém estado por instância. O estado do circuit breaker e o cache de sondagem não são compartilhados. Cada worker do PHP FastCGI Process Manager (PHP-FPM) deve manter a própria instância. Os resultados de lote são tipados. O BatchResult carrega entradas BatchItem com um BatchItemStatus, um BatchSummary com taxa de sucesso e um trace ID opcional. HardwareReport e HardwareCapabilities descrevem o nível de hardware detectado. HardwareCapabilities::satisfies() verifica programaticamente um requisito de nível. Os enums DegradePolicy e AuthorizationMode controlam o comportamento em caso de perda de capacidade e o rigor dos tokens. O módulo inteiro é @since 2.1.0.

Superfície da API

Tipo	Membros principais	Função
SpectrumClient	isAvailable(), probe(), getBudget(), request()	Cliente de sidecar PSR-18 que implementa a SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Resultado de lote tipado
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Resultado por item e enum de status
BatchSummary	isFullSuccess(), successRate()	Resumo agregado do lote
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Capacidades do sidecar detectadas
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Decisão programática por capacidade
DegradePolicy / AuthorizationMode	casos do enum	Comportamento de degradação e rigor dos tokens

Execute composer docs:generate-api-php -- --module=Accelerator para gerar a tabela completa do PHPDoc.

Exemplo de código — início rápido

Sonde o sidecar por meio do circuit breaker antes de depender dele.

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

Exemplo de código — produção

Envie um lote pelo sidecar quando ele estiver saudável e recorra à política de degradação quando não estiver.

<?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 extremos e armadilhas

• isAvailable() é uma verificação pontual, protegida por circuit breaker. Um resultado true pode virar false antes da próxima chamada. Trate a possibilidade de o sidecar cair entre as chamadas.
• O estado do circuit breaker e do cache de sondagem é mantido por instância. Compartilhar um único SpectrumClient entre workers anula o breaker. Dê a cada worker a própria instância.
• Os tokens de capacidade têm vida curta (120 s, 30 s no modo de alto controle). Uma operação de longa duração deve obter um novo token, e não reutilizar um existente.
• Erros de autenticação e de análise nunca passam por nova tentativa; apenas respostas 5xx transitórias e timeouts passam, e somente uma vez. Não presuma nenhuma outra nova tentativa idempotente além disso.
• Uma SpectrumInterface nula é um estado válido de “sem accelerator”, não um erro. A política de degradação decide se isso é fatal.

Desempenho

O cliente adiciona uma sobrecarga insignificante; o sidecar faz o trabalho. O circuit breaker é o principal controle de confiabilidade. Ele limita chamadas de ida e volta desperdiçadas quando o sidecar está indisponível. O performance_budget de 1500 ms de wall / 64 MB de pico corresponde à carga de trabalho de referência do motor, não a um service-level agreement (SLA) do sidecar. O perfil de reprodutibilidade é structural. Um resultado de lote carrega um trace ID e timestamps, de modo que duas execuções diferem nesses campos.

Notas de segurança

O limite do sidecar também é um limite de confiança. Quando você configura um segredo de aplicação, as requisições carregam tokens de capacidade HS256 limitados ao endpoint. Trate esse segredo como uma credencial proveniente de um gerenciador de segredos e nunca faça commit dele. O modo de autorização de alto controle reduz o tempo de vida do token para 30 segundos em endpoints sensíveis. O Uniform Resource Locator (URL) do sidecar fornecido pelo operador é validado quando a configuração é construída, e não na primeira requisição: apenas http:// e https:// com um host não vazio, ou unix:// com um caminho de socket não vazio, são aceitos; qualquer outro esquema (gopher://, file://, ftp://, …) ou uma URL de rede sem host falha de forma fechada na construção. Isso é defesa em profundidade contra server-side request forgery (SSRF) e tráfego de saída inesperado, de modo que um endpoint mal configurado nunca chega ao cliente HTTP. As respostas do sidecar são dados externos. Valide-as e trate-as como não confiáveis antes que voltem a entrar no motor. A classe de controle de exportação legal-review-required nesta página reflete que o recurso de aceleração envolve transporte criptográfico e está aguardando uma revisão de controle de exportação. Consulte essa revisão antes de redistribuir um build que a habilite.

Conformidade

Este módulo não faz nenhuma afirmação normativa sobre a especificação PDF. Ele é um cliente HTTP para um protocolo de aceleração interno. O protocolo é definido pelo motor, não padronizado; portanto, não há cláusulas a citar aqui. Quando o trabalho do sidecar (análise de PDF, compressão) tem uma dimensão de conformidade, essa conformidade é documentada na página do módulo relevante e validada pelas suítes oracle e golden em /modules/core/conformance/.

Veja também

• Contracts / Observability — a SpectrumInterface implementada por este cliente.
• Módulo Observability — superfície de estado em runtime para o trabalho acelerado.
• Módulo Performance — budgets para o trabalho acelerado.
• Modelo de segurança do motor