Output Pipeline — глубокий справочник

Кратко

Эта страница — углублённый справочник по публичной поверхности NextPDF\Pro\OutputPipeline. Она охватывает построение и валидацию манифеста, топологический порядок выполнения, семантику повторов и тайм-аута, поведение возобновления и отказоустойчивый (fail-closed) гейт возможностей Pack. Для каждого публичного символа указаны параметры, значения по умолчанию и режимы отказа. Сначала прочитайте страницу возможности Output Pipeline для руководства по рабочим процессам.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права не загружает классы возможности. Сравните редакции и получите лицензию.

Исполнитель и семь из десяти типов шагов не имеют пофункционального флага. Три типа шагов дополнительно требуют возможности Pack:

Тип шага	Значение в манифесте	Требуемая возможность	Pack
Redact	redact	pack.privacy.redact	Privacy Pack
Extract	extract	pack.intelligence.extract	Intelligence Pack
OCR overlay	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

Гейт применяется во время выполнения, отказоустойчиво (fail-closed), до того как шаг достигнет своего резолвера. Нелицензированный гейтированный шаг даёт проваленный результат шага с кодом SPEC-LIC-001 и требуемой возможностью; резолвер не вызывается. Конвейер без внедрённого резолвера возможностей отклоняет каждый гейтированный шаг.

Поверхность публичного API

composer require nextpdf/pro:^3

Метапакет nextpdf/premium устанавливает код nextpdf/pro; этот модуль находится в пространстве имён NextPDF\Pro\OutputPipeline.

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается с	Примечания
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Связывает встроенный реестр резолверов и необязательный источник прав	PipelineExecutor	Ничего не объявлено	Нулевой резолвер возможностей отклоняет каждый шаг, гейтированный по Pack
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Выполняет шаги в топологическом порядке и агрегирует результаты	PipelineResult	Ничего не объявлено; сбои резолвера фиксируются как проваленные результаты шага	Рассчитан на выполнение внутри асинхронного обработчика заданий
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Проверяет граф шагов при создании	PipelineManifest	InvalidArgumentException при пустом списке шагов, дублирующихся ID шагов, неизвестных зависимостях, циклах, несовпадении типов вывода или отсутствующем шаге возобновления; OverflowException при превышении 10 000 шагов	Вся валидация завершается до какого-либо выполнения
PipelineManifest::topologicalOrder	нет	Упорядочивает шаги так, что зависимости идут перед зависимыми	list<PipelineStep>	Ничего не объявлено	Детерминирован для данного манифеста
PipelineManifest::getStep	string $stepId	Линейный поиск по ID шага	?PipelineStep	Ничего не объявлено	null для неизвестного ID
PipelineManifest::rootSteps	нет	Возвращает шаги без зависимостей	list<PipelineStep>	Ничего не объявлено	Корневые шаги выполняются первыми
PipelineManifestBuilder::create	string $manifestId	Начинает новый построитель	self	Ничего не объявлено	Конструктор приватный; это единственная точка входа
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Добавляет шаг; нулевой тип вывода выводится из типа шага	self	Ничего не объявлено	Валидация откладывается до build()
PipelineManifestBuilder::stopOnError	bool $stop = true	Задаёт остановку при первом сбое	self	Ничего не объявлено	По умолчанию true
PipelineManifestBuilder::maxRetries	int $retries	Задаёт предел повторов на шаг	self	Ничего не объявлено	По умолчанию 0 (без повторов)
PipelineManifestBuilder::timeout	int $timeoutMs	Задаёт глобальный тайм-аут конвейера	self	Ничего не объявлено	0 отключает тайм-аут
PipelineManifestBuilder::resumeFrom	string $stepId	Задаёт точку возобновления	self	Ничего не объявлено	Шаг должен существовать на момент build()
PipelineManifestBuilder::build	нет	Создаёт проверенный манифест	PipelineManifest	Как у PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Неизменяемые параметры выполнения	PipelineOptions	Ничего не объявлено	Readonly объект-значение
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Неизменяемое определение шага	PipelineStep	Ничего не объявлено	При прямом создании тип вывода по умолчанию — PDF для любого типа
PipelineStep::isRoot	нет	True, когда у шага нет зависимостей	bool	Ничего не объявлено	—
PipelineStepType (enum)	—	Десять строковых вариантов: generate, merge, split, inspect, compress, sign, convert, плюс гейтированные redact, extract, ocr_overlay	—	—	По одному варианту на каждую встроенную операцию
PipelineStepType::requiresPack	нет	True для Redact, Extract и OcrOverlay	bool	Ничего не объявлено	Все остальные варианты возвращают false
PipelineStepType::requiredCapability	нет	Сопоставляет гейтированные варианты с их кодами возможностей	?string	Ничего не объявлено	null для негейтированных вариантов
PipelineStatus (enum)	—	Пять вариантов: pending, running, completed, failed, cancelled	—	—	Общий для результатов конвейера и шага
PipelineStatus::isTerminal	нет	True для Completed, Failed и Cancelled	bool	Ничего не объявлено	Pending и Running — нетерминальные
StepOutputType (enum)	—	Три варианта: pdf, json, metadata	—	—	Управляет валидацией рёбер на этапе сборки
StepOutputType::forStepType	PipelineStepType $stepType	Тип вывода по умолчанию для типа шага	self	Ничего не объявлено	Inspect и Extract сопоставляются с JSON; все остальные типы — с PDF
StepOutputType::isCompatibleWith	self $expectedInput	True при совпадении типов или для вывода PDF	bool	Ничего не объявлено	Вспомогательный; PDF — универсальный вход
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	Контекст в памяти на один запуск	PipelineContext	Ничего не объявлено	Нет TTL, срока действия, персистентности или хранилища
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult при записи)	Записывает или читает результат шага	void / ?StepResult	Ничего не объявлено	null для ещё не выполненного шага
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed при записи)	Сохраняет или читает промежуточный вывод	void / mixed	Ничего не объявлено	null для отсутствующего вывода
PipelineContext::hasStepResult	string $stepId	Выполнялся ли уже шаг	bool	Ничего не объявлено	Поддерживает проверки возобновления
PipelineContext::allStepResults	нет	Все зафиксированные к текущему моменту результаты	array<string, StepResult>	Ничего не объявлено	С ключом по ID шага
PipelineContext::isResume	нет	Возобновляется ли запуск с шага	bool	Ничего не объявлено	—
PipelineResult::isSuccess	нет	True только для общего статуса Completed	bool	Ничего не объявлено	Результат создаётся исполнителем
PipelineResult::getStepResult	string $stepId	Находит один результат шага по ID	?StepResult	Ничего не объявлено	null для пропущенных или неизвестных шагов
PipelineResult::failedSteps	нет	Отбирает проваленные результаты шагов	list<StepResult>	Ничего не объявлено	Пустой список при полном успехе
StepResult::isSuccess	нет	True только для статуса шага Completed	bool	Ничего не объявлено	Содержит stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	Позитивная проверка права на один код возможности	bool	Не должен бросать	Запрет по умолчанию: false для неизвестных, истёкших или несопоставленных кодов

Сигнатуры точек входа

final class PipelineExecutor
{
    public function __construct(
        private readonly StepResolverRegistry $registry,
        private readonly ?CapabilityResolverInterface $capabilityResolver = null,
    )

    public function execute(PipelineManifest $manifest, array $variables = []): PipelineResult
}

final class PipelineManifestBuilder
{
    public static function create(string $manifestId): self

    public function addStep(
        string $id,
        PipelineStepType $type,
        array $parameters = [],
        array $dependsOn = [],
        ?StepOutputType $outputType = null,
    ): self

    public function stopOnError(bool $stop = true): self

    public function maxRetries(int $retries): self

    public function timeout(int $timeoutMs): self

    public function resumeFrom(string $stepId): self

    public function build(): PipelineManifest
}

interface CapabilityResolverInterface
{
    public function hasCapability(string $capability): bool;
}

Контракт поведения

Валидация манифеста

Валидация выполняется в конструкторе PipelineManifest, до какого-либо выполнения. По порядку: список шагов должен быть непустым; количество шагов ограничено 10 000, что превращает состязательно глубокие цепочки зависимостей в перехватываемое OverflowException вместо исчерпания нативного стека; ID шагов должны быть уникальными; каждая ссылка dependsOn должна разрешаться; граф зависимостей должен быть ацикличным; типы вывода должны быть совместимы; объявленный шаг возобновления должен существовать. Каждое нарушение вызывает InvalidArgumentException с конкретным сообщением.

Проверка типа вывода применяется к шагам, тип которых сопоставляется с выводом PDF: каждая зависимость такого шага сама должна производить вывод PDF. Рёбра зависимостей к типам шагов, производящим JSON (inspect, extract), в этом релизе по типу не проверяются.

Порядок выполнения, возобновление и тайм-аут

execute($manifest, $variables) создаёт новый PipelineContext, вычисляет топологический порядок и выполняет шаги последовательно в этом порядке. Если задана точка возобновления, предыдущие шаги пропускаются, пока не будет достигнут названный шаг. Пропущенные предшественники не выполняются повторно, а их выводы не восстанавливаются: контекст относится к одному запуску и хранится в памяти, поэтому возобновлённый шаг, читающий вывод пропущенного предшественника, получает null.

Глобальный тайм-аут, если он положителен, проверяется между шагами, перед стартом каждого шага. По истечении статус конвейера становится Failed, а оставшиеся шаги не запускаются. Уже выполняющийся шаг никогда не прерывается посреди исполнения, поэтому один длинный шаг может выйти за пределы бюджета.

Повторы и фиксация сбоев

Каждый шаг получает не более maxRetries + 1 попыток. Успешная попытка возвращается немедленно. Любая неудачная попытка — результат Failed от резолвера или брошенный Throwable — повторяется, пока остаются попытки; возвращается результат последней попытки. Throwable, брошенный внутри резолвера, понижается до проваленного результата шага с сообщением исключения или Unknown error, если сообщение пустое. Поэтому execute() всегда возвращает PipelineResult; он никогда не пробрасывает сбой резолвера.

Тип шага без зарегистрированного резолвера даёт проваленный результат шага с явным сообщением; запуск не прерывается. При stopOnError равном true (по умолчанию) выполнение останавливается на первом проваленном шаге, и статус конвейера — Failed. При false выполнение продолжается, а итоговый статус — Failed, если хоть один шаг провалился, иначе Completed.

Гейт возможностей Pack

Перед любой диспетчеризацией резолвера каждый гейтированный по Pack шаг (Redact, Extract, OcrOverlay) проверяется через внедрённый CapabilityResolverInterface. Гейт отказоустойчив (fail-closed): отсутствующий резолвер, ответ false или несопоставленный код возможности — всё это отклоняет шаг. Отклонение создаёт проваленный результат шага, ошибка которого содержит код SPEC-LIC-001, тип шага и требуемую возможность. Гейтированное отклонение не расходует попытки повтора и сообщает длительность 0.0. Реализации резолвера должны возвращать true только для позитивно имеющегося права и не должны бросать исключения.

Агрегация результатов

PipelineResult сообщает ID манифеста, общий статус, результаты по каждому шагу в порядке выполнения, общую длительность в миллисекундах, а также общее число шагов, число завершённых и число проваленных. stepsTotal считает каждый шаг в манифесте, включая шаги, пропущенные при возобновлении или не достигнутые после остановки; stepsCompleted и stepsFailed считают только выполненные шаги.

Граничные случаи и режимы отказа

• Исполнитель рассчитан на асинхронное выполнение внутри обработчика заданий. Встраиваемое использование блокирует вызывающую сторону на всё время работы конвейера.
• Глобальный тайм-аут — это проверка между шагами. Один длинный шаг может выйти за пределы бюджета; ни один шаг не прерывается на лету.
• Возобновление пропускает шаги только в рамках одного выполнения. Оно не восстанавливает выводы из какого-либо хранилища; возобновление между запусками с кэшированными выводами не реализовано.
• При прямом создании PipelineStep тип вывода по умолчанию — PDF для любого типа шага. Используйте построитель или передавайте тип вывода явно, чтобы шаги inspect и extract объявляли вывод JSON, а валидация рёбер оставалась осмысленной.
• Исключение резолвера с пустым сообщением нормализуется в Unknown error в результате шага.
• Проваленные результаты шага, созданные гейтом или отсутствующим резолвером, сообщают длительность 0.0.
• PipelineResult::getStepResult() возвращает null как для неизвестных ID, так и для шагов, пропущенных при возобновлении или остановке; различайте по stepsTotal относительно длины списка результатов.
• Этот модуль не выполняет криптографических операций и не определяет FIPS-специфичного поведения. Позиция FIPS для шага sign определяется модулем подписания, а не конвейером.

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

Конвейер не выполняет собственной работы по соответствию форматам. Соответствие каждого созданного артефакта принадлежит модулю, стоящему за выполняющим шагом — подписание, оптимизация, конвертация и так далее — и документируется на справочных страницах этих модулей. Эта страница не утверждает внешних идентификаторов пунктов; каждое утверждение основано на исходном коде продукта. NextPDF не делает заявлений о сертификации.

Заметки по разработке

• Исходный код модуля содержит @since 2.2.0; этот справочник документирует поверхность в том виде, в каком она поставляется в nextpdf/pro 3.1.0.
• Все классы final; типы манифеста, параметров, шага и результата — readonly объекты-значения. Создавайте новые экземпляры вместо изменения.
• StepResolverInterface и StepResolverRegistry помечены @internal. Резолверы шагов только встроенные; пользовательские кастомные обработчики шагов в этом релизе не поддерживаются.
• CapabilityResolverInterface — публичный шов для прав. Реализации должны действовать по принципу запрета по умолчанию и не должны разрешать по умолчанию.
• Этот PHP-исполнитель — путь валидации манифеста и последовательного выполнения; продакшн-развёртывания могут диспетчеризовать через sidecar для параллельной оркестрации. Гейт возможностей на пути PHP в любом случае независимо отказоустойчив (fail-closed).
• Детали внутреннего механизма остаются во внутренней документации репозитория исходного кода и находятся за рамками этого руководства.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую поверхность публичного API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов — за рамками.

См. также

• Output Pipeline — страница возможности с руководством по рабочим процессам.
• Output Pipeline — углублённый справочник NextPDF Enterprise — пакетная оркестрация по манифестам.
• Document — углублённый справочник
• Accelerator — углублённый справочник