Output Pipeline — 심층 참조

한눈에 보기

이 페이지는 NextPDF\Pro\OutputPipeline의 공개 표면에 대한 심층 참조입니다. 매니페스트 구성 및 검증, 위상(topological) 실행 순서, 재시도 및 타임아웃 시맨틱, 재개 동작, 그리고 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 코드와 필요 기능을 담은 Failed 단계 결과를 산출하며, 리졸버는 결코 호출되지 않습니다. 기능 리졸버가 주입되지 않은 파이프라인은 모든 게이트된 단계를 거부합니다.

공개 API 표면

composer require nextpdf/pro:^3

nextpdf/premium 메타패키지가 nextpdf/pro 코드를 설치합니다. 이 모듈은 NextPDF\Pro\OutputPipeline 네임스페이스 아래에 있습니다.

심벌	매개변수	기본 동작	반환	예외 또는 실패 조건	비고
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	내장 리졸버 레지스트리와 선택적 권한 소스를 바인딩합니다	PipelineExecutor	선언된 것 없음	null 기능 리졸버는 모든 pack 게이트 단계를 거부합니다
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	단계를 위상 순서로 실행하고 결과를 집계합니다	PipelineResult	선언된 것 없음. 리졸버 실패는 Failed 단계 결과로 포착됩니다	비동기 작업 워커 내부에서 실행하도록 설계됨
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	생성 시 단계 그래프를 검증합니다	PipelineManifest	빈 단계 목록, 중복 단계 ID, 알 수 없는 의존성, 순환, 출력 타입 불일치, 또는 누락된 재개 단계에 대해 InvalidArgumentException. 10 000단계 초과 시 OverflowException	모든 검증은 실행 전에 완료됩니다
PipelineManifest::topologicalOrder	없음	의존성을 그 의존 대상보다 먼저 오도록 단계를 정렬합니다	list<PipelineStep>	선언된 것 없음	주어진 매니페스트에 대해 결정적입니다
PipelineManifest::getStep	string $stepId	단계 ID로 선형 조회합니다	?PipelineStep	선언된 것 없음	알 수 없는 ID에는 null
PipelineManifest::rootSteps	없음	의존성이 없는 단계를 반환합니다	list<PipelineStep>	선언된 것 없음	루트 단계가 먼저 실행됩니다
PipelineManifestBuilder::create	string $manifestId	새 빌더를 시작합니다	self	선언된 것 없음	생성자는 private이며, 이것이 유일한 진입점입니다
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	단계를 추가합니다. 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	없음	Redact, Extract, OcrOverlay에 대해 true	bool	선언된 것 없음	그 외 모든 케이스는 false를 반환합니다
PipelineStepType::requiredCapability	없음	게이트된 케이스를 해당 기능 코드로 매핑합니다	?string	선언된 것 없음	게이트되지 않은 케이스에는 null
PipelineStatus (enum)	—	다섯 가지 케이스: pending, running, completed, failed, cancelled	—	—	파이프라인과 단계 결과가 공유합니다
PipelineStatus::isTerminal	없음	Completed, Failed, Cancelled에 대해 true	bool	선언된 것 없음	Pending과 Running은 비종단입니다
StepOutputType (enum)	—	세 가지 케이스: pdf, json, metadata	—	—	빌드 타임 엣지 검증을 구동합니다
StepOutputType::forStepType	PipelineStepType $stepType	단계 타입의 기본 출력 타입	self	선언된 것 없음	Inspect와 Extract는 JSON으로, 그 외 모든 타입은 PDF로 매핑됩니다
StepOutputType::isCompatibleWith	self $expectedInput	같은 타입 일치 또는 PDF 출력에 대해 true	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	없음	전체 상태가 Completed일 때만 true	bool	선언된 것 없음	결과는 익스큐터가 생성합니다
PipelineResult::getStepResult	string $stepId	ID로 단계 결과 하나를 찾습니다	?StepResult	선언된 것 없음	건너뛴 단계나 알 수 없는 단계에는 null
PipelineResult::failedSteps	없음	실패한 단계 결과를 필터링합니다	list<StepResult>	선언된 것 없음	완전 성공 시 빈 목록
StepResult::isSuccess	없음	단계 상태가 Completed일 때만 true	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은 예외 메시지를 담은 Failed 단계 결과로 강등되며, 메시지가 비어 있으면 Unknown error가 됩니다. 따라서 execute()는 항상 PipelineResult를 반환하며, 리졸버 실패를 결코 전파하지 않습니다.

등록된 리졸버가 없는 단계 타입은 명시적 메시지와 함께 Failed 단계 결과를 산출하며, 실행은 중단되지 않습니다. stopOnError가 true(기본값)이면 실행은 첫 실패 단계에서 중단되고 파이프라인 상태는 Failed가 됩니다. false이면 실행은 계속되며, 단계 중 하나라도 실패하면 최종 상태는 Failed, 그렇지 않으면 Completed입니다.

Pack 기능 게이트

리졸버 디스패치에 앞서, 모든 pack 게이트 단계(Redact, Extract, OcrOverlay)는 주입된 CapabilityResolverInterface에 대해 검사됩니다. 게이트는 fail-closed입니다. 누락된 리졸버, false 응답, 또는 매핑되지 않은 기능 코드는 모두 단계를 거부합니다. 거부는 오류가 SPEC-LIC-001 코드, 단계 타입, 필요 기능을 담은 Failed 단계 결과를 생성합니다. 게이트 거부는 재시도 시도를 소비하지 않으며 0.0의 소요 시간을 보고합니다. 리졸버의 구현은 긍정적으로 보유한 권한에 대해서만 true를 반환해야 하며 예외를 던지지 않아야 합니다.

결과 집계

PipelineResult는 매니페스트 ID, 전체 상태, 실행 순서의 단계별 결과, 밀리초 단위의 총 소요 시간, 그리고 전체·완료·실패 단계 카운트를 보고합니다. stepsTotal은 재개로 건너뛴 단계나 중단 후 도달하지 못한 단계를 포함하여 매니페스트의 모든 단계를 셉니다. stepsCompleted와 stepsFailed는 실행된 단계만 셉니다.

엣지 케이스 및 실패 모드

• 익스큐터는 작업 워커 내부의 비동기 실행을 위해 설계되었습니다. 인라인 사용은 전체 파이프라인 동안 호출자를 차단합니다.
• 전역 타임아웃은 단계 사이의 검사입니다. 하나의 긴 단계가 예산을 초과할 수 있으며, 어떤 단계도 실행 도중에 중단되지 않습니다.
• 재개는 동일한 실행 내에서만 단계를 건너뜁니다. 어떤 스토어에서도 출력을 복원하지 않으며, 캐시된 출력을 사용한 실행 간 재개는 구현되어 있지 않습니다.
• PipelineStep을 직접 생성하면 모든 단계 타입에 대해 출력 타입이 PDF로 기본 설정됩니다. inspect와 extract 단계가 JSON 출력을 선언하고 엣지 검증이 유의미하게 유지되도록, 빌더를 사용하거나 출력 타입을 명시적으로 전달하십시오.
• 메시지가 비어 있는 리졸버 예외는 단계 결과에서 Unknown error로 정규화됩니다.
• 게이트나 누락된 리졸버가 생성한 Failed 단계 결과는 0.0의 소요 시간을 보고합니다.
• PipelineResult::getStepResult()는 알 수 없는 ID와 재개나 중단으로 건너뛴 단계 모두에 대해 null을 반환합니다. stepsTotal과 결과 목록 길이를 비교하여 구별하십시오.
• 이 모듈은 암호 연산을 수행하지 않으며 FIPS 특유의 동작을 정의하지 않습니다. sign 단계의 FIPS 태세는 파이프라인이 아니라 서명 모듈이 관장합니다.

적합성

파이프라인은 자체적인 형식 적합성 작업을 수행하지 않습니다. 생성된 각 아티팩트의 적합성은 실행 단계 뒤에 있는 모듈 — 서명, 최적화, 변환 등 — 이 소유하며, 해당 모듈의 참조 페이지에 문서화되어 있습니다. 이 페이지는 외부 조항 식별자를 주장하지 않습니다. 모든 진술은 제품 소스에 근거합니다. NextPDF는 어떠한 인증도 주장하지 않습니다.

개발 노트

• 모듈 소스는 @since 2.2.0을 담고 있습니다. 이 참조는 nextpdf/pro 3.1.0으로 제공된 표면을 문서화합니다.
• 모든 클래스는 final입니다. 매니페스트, 옵션, 단계, 결과 타입은 readonly 값 객체입니다. 변경하는 대신 새 인스턴스를 생성하십시오.
• StepResolverInterface와 StepResolverRegistry는 @internal입니다. 단계 리졸버는 내장 전용이며, 사용자 정의 커스텀 단계 핸들러는 이 릴리스에서 지원되지 않습니다.
• CapabilityResolverInterface는 공개 권한 심(seam)입니다. 구현은 누락 시 거부여야 하며 기본 허용해서는 안 됩니다.
• 이 PHP 익스큐터는 매니페스트 검증 및 순차 실행 경로입니다. 프로덕션 배포는 병렬 오케스트레이션을 위해 사이드카를 통해 디스패치할 수 있습니다. PHP 경로의 기능 게이트는 어느 쪽이든 독립적으로 fail-closed입니다.
• 내부 메커니즘 세부 사항은 소스 저장소의 내부 문서에 남아 있으며 이 매뉴얼의 범위를 벗어납니다.

공개 경계

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

함께 보기

• Output Pipeline — 워크플로 안내를 위한 기능 페이지.
• Output Pipeline — NextPDF Enterprise 심층 참조 — 매니페스트 전반의 배치 오케스트레이션.
• Document — 심층 참조
• Accelerator — 심층 참조