Accelerator：Spectrum sidecar 客户端

概览

Accelerator 模块是 Spectrum 的 PHP 端客户端，而 Spectrum 是可选的进程外加速 sidecar。它是一个经过强化的 HTTP 客户端，提供断路器、JSON Web Token（JWT）能力令牌、临时性故障时的单次重试，以及用于流式传输工作进度的 server-sent-events 传输。即使没有它，引擎也能正常运行。此模块的存在是为了让加速能力可以被注入，而不是作为必要条件。

稳定度：实验性。 Spectrum 是选用的 sidecar，并非冻结的公开 API。它实现的 SpectrumInterface 被标记为实验性，位于 Contracts / Observability。此客户端会跟随该稳定级别。其传输、令牌格式与预算形状可能会在次要版本之间变动。

安装

composer require nextpdf/core:^3

概念总览

Spectrum 会将处理器密集型工作卸载到本机的 sidecar 进程。这类工作包括硬件检测、PDF 解析与图像压缩。SpectrumClient 是一个 PSR-18 客户端，实现了冻结的 NextPDF\Contracts\SpectrumInterface。它依赖于 ClientInterface、RequestFactoryInterface 与 StreamFactoryInterface，而不是硬编码绑定某个 HTTP 堆栈。

此客户端专为应对不可靠的依赖项而设计。断路器会在连续三次失败后开启。开启期间，isAvailable() 会在指数退避窗口内返回 false，因此热路径不会持续请求已经停机的 sidecar。探测结果会按存活时间（TTL）缓存。设置了应用程序密钥后，每个出站请求都会携带一个 Request Capability Token。该令牌是一个短有效期的 HS256 JWT，其范围限定为端点所需的能力。其有效期为 120 秒，在高管控授权模式下则为 30 秒。临时性 5xx 与超时错误会重试一次。验证与解析错误则绝不重试。

SpectrumClient 的状态按实例维护。断路器状态与探测缓存并不共用。每个 PHP-FPM worker 都应持有自己的实例。批次结果具有类型。BatchResult 携带 BatchItem 项目（每个项目都带有一个 BatchItemStatus）、一个带有成功率的 BatchSummary，以及一个可选的 trace id。HardwareReport 与 HardwareCapabilities 描述检测到的硬件层级。HardwareCapabilities::satisfies() 以编程方式回答层级要求。DegradePolicy 与 AuthorizationMode 枚举决定能力丧失的处理方式以及令牌严格度的行为。整个模块为 @since 2.1.0。

API 接口

类型	主要成员	角色
`SpectrumClient`	`isAvailable()`、`probe()`、`getBudget()`、`request()`	实现 `SpectrumInterface` 的 PSR-18 sidecar 客户端
`BatchResult`	`getItems()`、`getSummary()`、`filterByStatus()`、`traceId()`	具有类型的批次结果
`BatchItem` / `BatchItemStatus`	`isOk()`、`isSuccessful()`、`isRetryable()`	逐项结果与状态枚举
`BatchSummary`	`isFullSuccess()`、`successRate()`	汇总批次摘要
`HardwareReport`	`hasPro()`、`hasEnterprise()`、`isApiVersionCompatible()`	检测到的 sidecar 能力
`HardwareCapabilities`	`hasGpu()`、`satisfies()`、`bestAvailableTier()`	编程能力分支
`DegradePolicy` / `AuthorizationMode`	枚举 case	降级行为与令牌严格度

执行 composer docs:generate-api-php -- --module=Accelerator 可取得完整的 PHPDoc 表格。

代码示例——快速开始

在依赖 sidecar 之前，先通过断路器探测它。

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

代码示例——生产环境

在 sidecar 健康时通过它送出批次，不健康时则按降级策略回退。

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

边界情况与陷阱

isAvailable() 是某一时刻受断路器保护的检查。true 的结果在下一次调用之前可能变成 false。请妥善处理在此期间离线的 sidecar。
断路器与探测缓存的状态按实例维护。在多个 worker 之间共用一个 SpectrumClient 会使断路器失效。请让每个 worker 各自拥有一个实例。
能力令牌是短有效期的（120 秒，高管控模式下为 30 秒）。长时间执行的作业必须取得新的令牌，而非重复使用旧令牌。
验证与解析错误绝不重试；只有临时性 5xx 与超时会重试，且仅一次。请勿假设除此之外还有幂等重试。
SpectrumInterface 为 null 是一种有效的「无加速器」状态，并非错误。是否将其视为致命，由降级策略决定。

性能

此客户端本身的额外开销可忽略不计。实际工作发生在 sidecar 中。断路器是主要的可靠性杠杆。它可以在 sidecar 停机时限制被浪费的往返次数。1500 毫秒墙钟时间 / 64 MB 峰值的 performance_budget 是引擎的参考工作负载，并非 sidecar 的服务等级协议（SLA）。其可复现性配置为 structural。批次结果携带 trace id 与时间戳，因此两次执行在这些字段上会有差异。

安全注意事项

sidecar 边界是一个信任边界。设置了应用程序密钥后，请求会携带范围限定于端点的 HS256 能力令牌。请将该密钥视为由密钥管理工具管理的凭证，绝不提交至版本控制。高管控授权模式会将敏感端点的令牌有效期缩短为 30 秒。操作人员提供的 sidecar URL 会在构建配置时验证，而非在首次请求时验证：仅接受带有非空主机的 http:// 与 https://，或带有非空 socket 路径的 unix://；任何其他协议（gopher://、file://、ftp:// 等）或无主机的网络 URL 会在构建时 fail closed。这是针对 SSRF 与非预期出站流量的纵深防御，因此错误设置的端点绝不会到达 HTTP 客户端。sidecar 的响应属于外部数据。在这些响应重新进入引擎之前，请验证并将其视为不受信任。本页的 legal-review-required 出口管制分类反映出此加速功能带有加密传输，且尚待出口管制审查。在重新分发启用此功能的构建之前，请先查阅该审查。

一致性

此模块并未对任何 PDF 规范作出规范性声明。它是针对内部加速协议的 HTTP 客户端。该协议由引擎自行定义，并非必须引用条款的标准化协议。当 sidecar 所执行的工作（PDF 解析、压缩）具有一致性方面的要求时，该一致性会记载于相关模块页面，并由 /modules/core/conformance/ 中的 oracle 与 golden 测试套件验证。

另请参阅

Contracts / Observability——此客户端实现的 SpectrumInterface。
Observability 模块——用于观测加速工作运行时状态的接口。
Performance 模块——加速工作对应的预算。
引擎安全模型