Accelerator: клиент для сопроводительного процесса Spectrum

Кратко

Модуль Accelerator — это PHP-клиент для Spectrum, дополнительного внепроцессного сопроводительного процесса ускорения. Это расширенный клиент Hypertext Transfer Protocol (HTTP) с предохранителем, токенами возможностей JSON Web Token (JWT), одной повторной попыткой при временных сбоях и транспортом server-sent events для потоковой передачи прогресса задания. Движок работает и без сопроводительного процесса. Используйте этот модуль, чтобы добавить ускорение, не делая его обязательным.

Стабильность: экспериментальная. Spectrum — это дополнительный сопроводительный процесс, а не замороженный публичный API. Реализуемый им SpectrumInterface задокументирован как экспериментальный на странице Contracts / Observability. Этот клиент следует тому же уровню. Транспорт, формат токена и структура бюджета могут меняться между минорными версиями.

Установка

composer require nextpdf/core:^3

Концептуальный обзор

Spectrum выносит ресурсоёмкие для процессора задачи в локальный сопроводительный процесс, включая обнаружение оборудования, разбор Portable Document Format (PDF) и сжатие изображений. SpectrumClient — это клиент PHP Standards Recommendation 18 (PSR-18), который реализует замороженный NextPDF\Contracts\SpectrumInterface. Он зависит от ClientInterface, RequestFactoryInterface и StreamFactoryInterface, а не от жёстко заданного стека Hypertext Transfer Protocol (HTTP).

Клиент рассчитан на то, что зависимость может отказать. Предохранитель размыкается после трёх последовательных сбоев. Пока он разомкнут, isAvailable() возвращает false в течение окна экспоненциальной задержки, поэтому горячий путь не продолжает обращаться к недоступному сопроводительному процессу. Результат проверки кэшируется со временем жизни (TTL). Когда вы настраиваете секрет приложения, каждый исходящий запрос содержит Request Capability Token. Токен — это короткоживущий HS256 JWT с областью действия, ограниченной возможностями, которые требует конечная точка. Его время жизни составляет 120 секунд или 30 секунд в режиме авторизации с повышенным контролем. Временные ошибки 5xx и тайм-ауты повторяются один раз. Ошибки аутентификации и разбора никогда не повторяются.

SspectrumClient хранит состояние на уровне экземпляра. Состояние предохранителя и кэш проверки не разделяются. Каждый воркер PHP FastCGI Process Manager (PHP-FPM) должен иметь собственный экземпляр. Результаты пакетной обработки типизированы. BatchResult содержит записи BatchItem с BatchItemStatus, BatchSummary с долей успешных результатов и необязательный идентификатор трассировки. HardwareReport и HardwareCapabilities описывают обнаруженный уровень оборудования. HardwareCapabilities::satisfies() программно проверяет требование к уровню. Перечисления DegradePolicy и AuthorizationMode управляют поведением при потере возможностей и строгостью токена. Весь модуль имеет @since 2.1.0.

Поверхность API

Тип	Ключевые члены	Роль
SpectrumClient	isAvailable(), probe(), getBudget(), request()	Клиент PSR-18 для сопроводительного процесса, реализующий SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Типизированный результат пакетной обработки
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Результат по каждому элементу и перечисление статусов
BatchSummary	isFullSuccess(), successRate()	Сводка по всей пакетной обработке
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Обнаруженные возможности сопроводительного процесса
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Программное ветвление с учётом возможностей
DegradePolicy / AuthorizationMode	варианты перечисления	Поведение при деградации и строгость токена

Запустите composer docs:generate-api-php -- --module=Accelerator, чтобы сгенерировать полную таблицу PHPDoc.

Пример кода — быстрый старт

Проверьте сопроводительный процесс через предохранитель, прежде чем полагаться на него.

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

Пример кода — продакшен

Отправляйте пакет через сопроводительный процесс, когда он работоспособен, и переходите в резервный режим согласно политике деградации, когда он недоступен.

<?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 до следующего вызова. Обрабатывайте ситуацию, когда сопроводительный процесс отключается между вызовами.
• Состояние предохранителя и кэш проверки привязаны к отдельному экземпляру. Совместное использование одного SpectrumClient несколькими воркерами сводит на нет работу предохранителя. Выделяйте каждому воркеру собственный экземпляр.
• Токены возможностей короткоживущие (120 с, 30 с в режиме повышенного контроля). Длительная операция должна получать новый токен, а не использовать повторно прежний.
• Ошибки аутентификации и разбора никогда не повторяются; повторяются только временные ответы 5xx и тайм-ауты, и только один раз. Не рассчитывайте на идемпотентный повтор сверх этого.
• Значение SpectrumInterface, равное null, — это допустимое состояние “ускоритель отсутствует”, а не ошибка. Политика деградации решает, является ли это фатальным.

Производительность

Клиент добавляет незначительные накладные расходы; всю работу выполняет сопроводительный процесс. Предохранитель — это основной механизм управления надёжностью. Он ограничивает лишние обращения, когда сопроводительный процесс недоступен. performance_budget в 1500 мс реального времени / 64 МБ пиковой памяти — это эталонная нагрузка движка, а не соглашение об уровне обслуживания (SLA) для сопроводительного процесса. Профиль воспроизводимости — structural. Результат пакетной обработки содержит идентификатор трассировки и метки времени, поэтому два запуска различаются в этих полях.

Замечания по безопасности

Граница сопроводительного процесса — это граница доверия. Когда вы настраиваете секрет приложения, запросы содержат токены возможностей HS256 с областью действия, ограниченной конечной точкой. Относитесь к этому секрету как к учётным данным в менеджере секретов и никогда не коммитьте его. Режим авторизации с повышенным контролем сокращает время жизни токена до 30 секунд для чувствительных конечных точек. Заданный оператором Uniform Resource Locator (URL) сопроводительного процесса проверяется при построении конфигурации, а не при первом запросе: принимаются только http:// и https:// с непустым хостом или unix:// с непустым путём к сокету; любая другая схема (gopher://, file://, ftp://, …) или сетевой URL без хоста отклоняется по принципу fail-closed при построении. Это многоуровневая защита от подделки запросов на стороне сервера (SSRF) и непредвиденного исходящего трафика, поэтому неправильно настроенная конечная точка никогда не достигает HTTP-клиента. Ответы сопроводительного процесса — это внешние данные. Проверяйте их и считайте недоверенными, прежде чем снова передавать в движок. Класс экспортного контроля legal-review-required на этой странице отражает, что функция ускорения использует криптографический транспорт и требует проверки на соответствие экспортному контролю. Сверьтесь с этой проверкой, прежде чем распространять сборку, в которой эта функция включена.

Соответствие

Этот модуль не заявляет нормативное соответствие спецификации PDF. Это HTTP-клиент для внутреннего протокола ускорения. Протокол определяется движком и не стандартизирован, поэтому здесь нет пунктов, на которые можно было бы сослаться. Там, где работа сопроводительного процесса (разбор PDF, сжатие) имеет аспект соответствия, это соответствие задокументировано в соответствующем модуле и проверяется наборами oracle и golden в /modules/core/conformance/.

См. также

• Contracts / Observability — SpectrumInterface, реализуемый этим клиентом.
• Observability module — поверхность состояния runtime для ускоренной работы.
• Performance module — бюджеты для ускоренной работы.
• Модель безопасности движка