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 會將 CPU 密集型工作卸載到本機 sidecar 行程。這類工作包括硬體偵測、PDF 剖析與影像壓縮。SpectrumClient 是一個 PSR-18 用戶端，實作了凍結的 NextPDF\Contracts\SpectrumInterface。它依賴 ClientInterface、RequestFactoryInterface 與 StreamFactoryInterface，而非硬綁定的 HTTP 堆疊。

此用戶端是為了處理不穩定的相依項而打造的。斷路器會在連續三次失敗後開啟。開啟期間，isAvailable() 會在指數退避視窗內回傳 false，避免熱路徑持續打向已停機的 sidecar。探測結果會以存活時間（TTL）快取。設定應用程式密鑰後，每個對外請求都會攜帶一個 Request Capability Token。該權杖是短效 HS256 JWT，其範圍限定於端點所需的能力。其存活時間為 120 秒，在高控管授權模式下則為 30 秒。暫時性的 5xx 與逾時錯誤會重試一次。驗證與剖析錯誤則絕不重試。

每個 SspectrumClient 實例都有自己的狀態。斷路器狀態與探測快取不會共用。每個 PHP-FPM 工作者都應持有各自的實例。批次結果有明確型別。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`	enum 案例	降級行為與權杖嚴格度

執行 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。
斷路器與探測快取的狀態是逐實例的。若在多個工作者間共用一個 SpectrumClient，會使斷路器失效。請讓每個工作者各自擁有一個。
能力權杖是短效的（120 秒，高控管模式下為 30 秒）。長時間執行的作業必須取得新的權杖，而非重複使用舊的。
驗證與剖析錯誤絕不重試；只有暫時性的 5xx 與逾時會重試，且僅一次。請勿假設除此之外還有冪等重試。
null 的 SpectrumInterface 是一種有效的「無加速器」狀態，並非錯誤。是否將其視為致命，由降級策略決定。

效能

此用戶端本身的額外負擔可忽略不計；實際工作發生在 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 模組——加速工作對應的預算。
引擎安全模型