Enterprise 에디션

Output Pipeline — 심층 참조

한눈에 보기

NextPDF\Enterprise\OutputPipeline는 많은 Pro 파이프라인 매니페스트를 하나의 배치로 실행합니다. BatchPipelineOrchestrator는 Pro PipelineExecutor를 배치 조정으로 감쌉니다: 배치 크기에 대한 한정 리소스 가드, 선택적 전역 배치 시간 초과, 매니페스트별 변수 주입, 집계 회계입니다. 선택적 배치 종료 적합성 검사는 완료된 모든 출력을 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`	배치가 10,000개 매니페스트를 초과하면 `OverflowException`; 적합성 검사가 활성화된 경우 게이트웨이 예외(엣지 케이스 참조)	해석기(resolver)의 `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`	없음	실패가 0인 시간 초과로 잘린 배치에서 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을 발생시키며, 조용히 저하되는 것은 없습니다.

그런 다음 매니페스트는 Pro PipelineExecutor를 통해 제출 순서로 실행됩니다. 각 매니페스트는 $variablesMap에서 자신의 ID로 키가 지정된 변수 항목을 받습니다; 항목이 없는 매니페스트는 빈 변수 맵을 받습니다. 매니페스트는 PipelineResult 상태가 Completed일 때 완료로 계산되며, 그 외의 모든 종료 상태는 실패로 계산됩니다. 해석기 예외는 새어 나가지 않습니다: Pro 실행기가 모든 해석기 Throwable을 실패한 단계 결과로 변환하므로, executeBatch()는 단계 오류로 배치 도중에 중단하는 대신 항상 결과를 집계합니다.

timeoutMs가 0보다 크면, 각 매니페스트가 시작되기 전에 경과 시간이 확인됩니다. 예산이 소진되면 나머지 매니페스트는 건너뜁니다: 이들은 PipelineResult를 생성하지 않으며, 완료로도 실패로도 계산되지 않습니다. totalManifests는 항상 제출된 개수를 보고합니다.

complianceCheckOnComplete가 활성화되면, 오케스트레이터는 주입된 ComplianceGateway를 통해 완료된 모든 매니페스트의 최종 PDF를 구성된 ComplianceProfile에 대해 검증합니다. 이 검사는 실패 시 닫힘(fail closed)으로 동작합니다:

게이트웨이가 주입되지 않음: 적합성이 검증된 적이 없으므로, 검사된 모든 매니페스트가 실패로 보고됩니다.
매니페스트의 단계 출력에서 PDF 출력을 해석할 수 없음: 실패.
게이트웨이가 결과를 반환하지 않음(선택 모드 사이드카 사용 불가): 실패. 긍정적 결과의 부재는 통과가 아닙니다.
게이트웨이가 부적합을 보고함: 실패.

최종 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()는 빈 배치(제출된 매니페스트 0개)에 대해 1.0을 반환합니다.
매니페스트 ID는 배치 수준에서 중복 제거되지 않습니다. ID를 공유하는 두 매니페스트는 모두 실행되며 동일한 변수 항목을 해석합니다.
구조적 매니페스트 오류(빈 단계 목록, 중복 단계 ID, 알 수 없는 종속성, 종속성 순환, 출력 유형 불일치, 누락된 재개 단계)는 executeBatch()가 호출되기 전에 매니페스트 생성 시점에 InvalidArgumentException을 발생시킵니다.
적합성 검사가 활성화된 경우, ComplianceGateway::validate()는 ComplianceSidecarUnavailableException(필수 모드에서 사이드카 사용 불가) 또는 InvalidArgumentException(프로파일의 도구에 등록된 검증기 없음)을 던질 수 있습니다. 두 예외 중 어느 것이든 실행 후 결과가 빌드되기 전에 executeBatch()를 벗어나므로, 매니페스트별 결과가 호출자에게 손실됩니다. 선택 모드에서는 게이트웨이가 대신 null을 반환하며, 해당 매니페스트는 적합성 실패로 기록됩니다.
파이프라인 내 적합성 핸드오프 단계는 상위 단계 출력에 인식 가능한 PDF 바이트가 없으면 실패하며, 결코 조용히 통과하지 않습니다.
이 모듈은 어떠한 암호화 연산도 수행하지 않으며, FIPS 모드는 적용되지 않습니다.

적합성(Conformance)

이 모듈에 대해 표준 적합성은 주장되지 않습니다; 이는 오케스트레이션 계층입니다. 선택적 적합성 검사는 Enterprise 적합성 게이트웨이와 그 외부 검증기에 미루며, 이들은 자체 참조를 담습니다. 기본 프로파일은 ComplianceProfile::PdfA4이며, 다른 게이트웨이 프로파일은 추가적인 PDF/A, PDF/UA, PAdES 대상을 다룹니다.

적합성 보고서는 선택된 프로파일에 대한 검증기 발견 사항을 명시합니다. 문서를 인증하거나, 규제 충분성을 보장하거나, 법률 자문을 구성하지 않습니다. 출력이 사용자의 의무를 충족하는지 판단하는 것은 사용자의 책임입니다.

개발 노트

프로덕션 배포에서 병렬 워커 디스패치와 배압은 별도의 실행 사이드카가 처리합니다. PHP 오케스트레이터는 배치 조정과 적합성 핸드오프 로직을 제공하며, 요청 핸들러가 아니라 작업 워커에 의해 호출됩니다.
PHP 폴백 경로는 매니페스트를 순차적으로 실행합니다. maxConcurrency는 사이드카 기반 배포에서 동시 워커 콜백을 제한하며, PHP 워커 풀에 상대적으로 크기를 조정하는 것은 운영자의 책임입니다.
파이프라인 내 적합성 핸드오프 단계 해석기는 inspect 유형 단계에 등록된 내부 타입입니다. 이를 위한 파이프라인 단계를 직접 구성하는 대신 BatchPipelineConfig를 통해 배치 종료 검증을 활성화하십시오.
PipelineManifest 인스턴스를 일찍 구성하십시오. 이들의 구조적 검증은 생성자에서 실행되므로, 유효하지 않은 그래프는 빠르게 실패하며 배치 예산을 결코 소비하지 않습니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만을 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 테이블, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.