Enterprise редакция

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

Кратко

NextPDF\Enterprise\OutputPipeline выполняет множество манифестов конвейера Pro как один пакет. BatchPipelineOrchestrator оборачивает PipelineExecutor из Pro координацией пакета: защита с ограничением ресурсов на размер пакета, необязательный глобальный тайм-аут пакета, инъекция переменных на каждый манифест и агрегированный учёт. Необязательная проверка соответствия в конце пакета повторно проверяет каждый завершённый вывод через шлюз соответствия Enterprise и проваливает по умолчанию (fail closed). Каждый запуск возвращает BatchPipelineResult с результатами по каждому манифесту, счётчиками завершённых и проваленных, временем и необязательным отчётом о соответствии.

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

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

Редакция	Поверхность output-pipeline
Core	Нет поверхности output-pipeline.
Pro	Конвейер с одним манифестом (возможность `pro.output.pipeline`).
Enterprise	Пакетная оркестрация, ограничение размера пакета, тайм-аут пакета, передача на проверку соответствия.

Пакетная поверхность Enterprise не имеет отдельного кода возможности на каждую функцию; её закрывает граница пакета. Возможность Pro с одним манифестом pro.output.pipeline является предпосылкой, а не гейтом. Одна лишь лицензия Pro открывает доступ только к базовому конвейеру с одним манифестом, но не к этой пакетной поверхности.

composer require nextpdf/enterprise:^3

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Возбуждает или проваливает с	Примечания
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	Конфигурация по умолчанию; без шлюза; профиль `ComplianceProfile::PdfA4`	—	Ничего	Внедрите шлюз, когда включена проверка соответствия; без него каждый проверяемый манифест отмечается как проваленный.
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	Выполняет манифесты в порядке подачи; переменные разрешаются по ID манифеста	`BatchPipelineResult`	`OverflowException`, когда пакет превышает 10,000 манифестов; исключения шлюза, когда включена проверка соответствия (см. Граничные случаи)	`Throwable` из резолвера никогда не всплывает; исполнитель Pro понижает их до проваленных результатов шага.
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Параллелизм 4; без тайм-аута; без проверки соответствия	—	Ничего	Неизменяемый объект-значение. `timeoutMs = 0` отключает тайм-аут пакета.
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	Агрегирует значения `PipelineResult` по каждому манифесту	—	Ничего	Неизменяемый. `complianceReport` остаётся `null`, пока проверка не выполнена.
`BatchPipelineResult::allSucceeded()`	—	Проверяет `failedCount === 0`	`bool`	Ничего	Возвращает true для усечённого по тайм-ауту пакета с нулём провалов; см. Граничные случаи.
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	Ничего	Возвращает `1.0` для пустого пакета.
`BatchPipelineResult::hasComplianceReport()`	—	Проверяет `complianceReport !== null`	`bool`	Ничего	—

public function __construct(
    private readonly PipelineExecutor $executor,
    private readonly BatchPipelineConfig $config = new BatchPipelineConfig(),
    private readonly ?ComplianceGateway $complianceGateway = null,
    private readonly ComplianceProfile $complianceProfile = ComplianceProfile::PdfA4,
) {}

public function executeBatch(
    array $manifests,
    array $variablesMap = [],
): BatchPipelineResult

public function __construct(
    public int $maxConcurrency = 4,
    public int $timeoutMs = 0,
    public bool $complianceCheckOnComplete = false,
) {}

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

executeBatch() сначала проверяет размер пакета относительно предела в 10,000 манифестов. Пакет сверх предела возбуждает OverflowException до выполнения любого манифеста; ничего не деградирует молча.

Затем манифесты выполняются в порядке подачи через PipelineExecutor из Pro. Каждый манифест получает запись переменных, ключом которой служит его ID в $variablesMap; манифест без записи получает пустую карту переменных. Манифест считается завершённым, когда статус его PipelineResult равен Completed; любой другой терминальный статус считается проваленным. Исключения резолвера не всплывают: исполнитель Pro преобразует каждый Throwable резолвера в проваленный результат шага, поэтому executeBatch() всегда агрегирует результаты, а не прерывает пакет на середине из-за ошибки шага.

Когда timeoutMs больше нуля, прошедшее время проверяется перед стартом каждого манифеста. Как только бюджет исчерпан, оставшиеся манифесты пропускаются: они не производят PipelineResult и не считаются ни завершёнными, ни проваленными. totalManifests всегда сообщает поданное количество.

Когда включён complianceCheckOnComplete, оркестратор проверяет итоговый PDF каждого завершённого манифеста относительно настроенного ComplianceProfile через внедрённый ComplianceGateway. Проверка проваливает по умолчанию (fail closed):

Шлюз не внедрён: каждый проверяемый манифест отмечается как проваленный, поскольку соответствие никогда не проверялось.
Из выходных данных шагов манифеста не удаётся разрешить PDF-вывод: провал.
Шлюз не возвращает результата (недоступность sidecar в необязательном режиме): провал. Отсутствие положительного результата — это не прохождение.
Шлюз сообщает о любом несоответствии: провал.

Итоговый PDF разрешается сканированием выходных данных шагов завершённого манифеста, начиная с последнего шага, в поисках прямого строкового значения, начинающегося с заголовка %PDF. Выходные данные шагов никогда не вкладывают байтовые строки PDF в подмассивы; проверяются только прямые выходные значения. Манифесты, которые не завершились, пропускаются, а не проверяются.

Отчёт о соответствии — это массив с ключами profile, checked, passed, failed и failures; каждая запись о провале несёт manifestId и reason. Отчёт присоединяется к BatchPipelineResult::$complianceReport и доступен через hasComplianceReport().

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

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

Более 10,000 манифестов: OverflowException до старта любого выполнения.
timeoutMs = 0 означает отсутствие тайм-аута пакета. В продакшене задавайте конечное значение.
Усечение по тайм-ауту: пропущенные манифесты не попадают ни в один счётчик, поэтому completedCount + failedCount может быть меньше totalManifests. allSucceeded() проверяет только failedCount === 0 и может вернуть true для усечённого пакета. Сравните count($result->results) с totalManifests, чтобы обнаружить усечение.
successRate() возвращает 1.0 для пустого пакета (подано ноль манифестов).
ID манифестов не дедуплицируются на уровне пакета. Два манифеста с одинаковым ID оба выполняются и разрешают одну и ту же запись переменных.
Структурные ошибки манифеста (пустой список шагов, дублирующиеся ID шагов, неизвестная зависимость, цикл зависимостей, несовпадение типа вывода, отсутствующий шаг возобновления) возбуждают InvalidArgumentException при конструировании манифеста, ещё до вызова executeBatch().
При включённой проверке соответствия ComplianceGateway::validate() может возбудить ComplianceSidecarUnavailableException (sidecar недоступен в обязательном режиме) или InvalidArgumentException (для инструмента профиля не зарегистрирован валидатор). Любое из этих исключений всплывает из executeBatch() после выполнения, но до построения результата, поэтому результаты по каждому манифесту теряются для вызывающей стороны. В необязательном режиме шлюз вместо этого возвращает null, и манифест записывается как провал соответствия.
Шаг передачи на проверку соответствия внутри конвейера проваливается, когда ни один вышестоящий вывод шага не содержит распознаваемых байтов PDF; он никогда не проходит молча.
Этот модуль не выполняет криптографических операций; режим FIPS неприменим.

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

Для этого модуля не заявляется соответствия стандартам; это слой оркестрации. Необязательная проверка соответствия делегирует шлюзу соответствия Enterprise и его внешним валидаторам, которые несут собственные ссылки. Профиль по умолчанию — ComplianceProfile::PdfA4; другие профили шлюза охватывают дополнительные цели PDF/A, PDF/UA и PAdES.

Отчёт о соответствии излагает выводы валидатора относительно выбранного профиля. Он не сертифицирует документ, не гарантирует нормативной достаточности и не является юридической консультацией. Оценка того, отвечает ли вывод вашим обязательствам, — ваша ответственность.

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

В продакшен-развёртываниях параллельная диспетчеризация рабочих процессов и обратное давление обрабатываются отдельным sidecar-процессом выполнения. PHP-оркестратор предоставляет логику координации пакета и передачи на проверку соответствия и вызывается рабочим заданий, а не напрямую обработчиками запросов.
Резервный путь на PHP выполняет манифесты последовательно. maxConcurrency ограничивает число одновременных рабочих обратных вызовов в развёртывании с sidecar; выбор его размера относительно пула PHP-воркеров — ответственность оператора.
Резолвер шага передачи на проверку соответствия внутри конвейера — это внутренний тип, зарегистрированный для шагов типа inspect. Включайте проверку в конце пакета через BatchPipelineConfig, а не конструируя шаги конвейера для неё напрямую.
Создавайте экземпляры PipelineManifest заранее. Их структурная проверка выполняется в конструкторе, поэтому некорректные графы падают быстро и никогда не расходуют бюджет пакета.

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

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