런타임 및 지원 오류
이 항목들은 런타임 지원 계층이 발생시키는 예외를 다룹니다. 저하 정책, cURL 기반 HTTP 전송, 회복탄력성 서킷 브레이커, Security Information and Event Management(SIEM) 에미터, 렌더 매니페스트, PDF 검사, 카오스 엔지니어링 서브시스템입니다.
모든 NextPDF 예외는 NextPdfException을 확장하며, 이는 ContextAwareExceptionInterface를 구현하고 구조화된 진단 로깅을 위해 getContext(): array를 노출합니다. 서브클래스는 getContext()를 재정의할 때만 그 배열을 채웁니다. 기반은 빈 배열을 반환합니다. 이 페이지의 세 예외(DegradedException, CircuitBreakerOpenException, InspectException)는 PHP의 RuntimeException을 직접 확장하고 getContext() 대신 public readonly 속성으로 데이터를 노출합니다. 아래 각 항목은 클래스가 담는 정확한 속성 또는 컨텍스트 키를 소스에서 가져와 명시합니다.
저하 정책
섹션 제목: “저하 정책”DegradedException
섹션 제목: “DegradedException”- 발생 시점. 렌더링 파이프라인이 활성 저하 정책을 위반하는 저하된 기능을 만났을 때입니다.
DegradationPolicy::Strict에서는 모든 고영향 저하(ComplianceRisk,SemanticLoss,Blocking)가 이를 발생시킵니다.DegradationPolicy::Balanced에서는Blocking영향만 이를 발생시킵니다. - 클래스.
RuntimeException을 직접 확장합니다(NextPdfException이 아님). 따라서getContext()를 담지 않습니다. - 담는 데이터. 두 개의 public
readonly속성입니다.$capability(거부를 트리거한Capability값 객체로,id,status,reason,fallbackTarget,impact를 포함)와$policy(거부 시점에 활성화된DegradationPolicy)입니다. 메시지는Feature "<id>" is <status>: <reason> (policy: <policy>)형식입니다. - 복구.
$capability를 검사하여 누락된 기능과 그 원인을 식별하십시오. 그 기능이 요구하는 구성 요소를 설치하거나, 더 낮은 영향의 구성을 받아들이거나, 저하가 해당 사용 사례에 허용된다면 정책을Strict에서Balanced로 완화하십시오.$capability->isAvailable()/isDegraded()를 호출하여 사용자 대상 메시징을 구동하십시오.
HTTP 전송
섹션 제목: “HTTP 전송”이 세 예외는 cURL 기반 PSR-18 클라이언트와 그 보안 인식 데코레이터에서 비롯됩니다. 앞의 둘은 NextPdfException을 확장하지만 getContext()를 재정의하지 않으므로, 그들의 getContext()는 빈 배열을 반환합니다. 진단 데이터는 PSR-18 getRequest() 접근자와 연결된 이전 throwable을 통해 도달합니다.
CurlNetworkException
섹션 제목: “CurlNetworkException”- 발생 시점. 네트워크 수준 장애 때문에 HTTP 요청을 완료할 수 없을 때입니다. Domain Name System(DNS) 해석 실패, 연결 시간 초과, Transport Layer Security(TLS) 핸드셰이크 오류입니다. 또한 보안 인식 데코레이터가 보안 거부(Server-Side Request Forgery 거부, DNS 리바인딩 거부, 거부된 리다이렉트)에 대해 발생시키는 클래스이기도 합니다.
- 클래스. PSR-18
Psr\Http\Client\NetworkExceptionInterface를 구현합니다. - 담는 데이터.
getRequest()는 실패한RequestInterface를 반환합니다. 발단이 된 전송 오류는 존재하는 경우 연결된 이전 throwable입니다.getContext()는 빈 배열(기반 기본값)을 반환합니다. - 복구. 네트워크 장애는 일시적일 수 있습니다. 요청이 멱등이라면 백오프와 함께 재시도하십시오. 보안 거부는 일시적이지 않으며 반드시 fail-closed여야 합니다. 재시도하지 마십시오. 대신 대상 URL이나 SSRF 정책을 바로잡으십시오. 둘을 구분하려면 메시지와 이전 throwable을 읽으십시오.
CurlRequestException
섹션 제목: “CurlRequestException”- 발생 시점. 요청 자체가 잘못된 형식이어서 보낼 수 없을 때입니다. 예를 들어 잘못된 URL이거나, 어떤 네트워크 호출 전에 SSRF 검증에 실패한 요청입니다.
- 클래스. PSR-18
Psr\Http\Client\RequestExceptionInterface를 구현합니다. - 담는 데이터.
getRequest()는 문제가 된RequestInterface를 반환합니다. 기저의 원인은 존재하는 경우 연결된 이전 throwable입니다.getContext()는 빈 배열을 반환합니다. - 복구. 이는 일시적 장애가 아니라 호출자 입력 또는 정책 결함입니다. 변경 없이 재시도하지 마십시오. 요청 URL, 헤더 또는 본문을 수정하거나, 대상이 정당하게 허용된다면 SSRF 허용 목록을 조정한 뒤 요청을 다시 발행하십시오.
TransientHttpException
섹션 제목: “TransientHttpException”- 발생 시점.
SecurityAwareHttpClient내부에서 내부적으로, 진정으로 일시적인 내부 전송 장애(내부 PSR-18 클라이언트가 발생시킨 DNS, 연결, 시간 초과)를 제한된 재시도 예산의 대상으로 표시하기 위해서입니다. 이는 데코레이터의 재시도 루프가 인식하는 유일한 재시도 가능 클래스입니다. 래핑되지 않은 예외(데코레이터가 발생시킨 보안 거부)는 치명적으로 취급됩니다. - 클래스. PSR-18
Psr\Http\Client\NetworkExceptionInterface를 구현합니다.@internal로 표시됩니다.SecurityAwareHttpClient내부에서 전적으로 생성되고 래핑 해제되며 데코레이터를 절대 벗어나지 않습니다. - 담는 데이터.
getRequest()는 실패한 요청을 반환합니다. 원래의 내부 전송ClientExceptionInterface는 연결된 이전 throwable(getPrevious())로 보존되며, 재시도 예산이 소진되면 호출자에게 그대로 다시 표면화되므로 공개 PSR-18 계약은 변하지 않습니다.getContext()는 빈 배열을 반환합니다. - 복구. 애플리케이션 코드는 이 타입을 직접 잡지 않습니다. 재시도 예산이 소진된 뒤 데코레이터가 반환하는, 다시 표면화된 내부 예외를 잡고, 반복되는 일시적 실패를 상류 가용성 문제로 취급하십시오.
회복탄력성
섹션 제목: “회복탄력성”CircuitBreakerOpenException
섹션 제목: “CircuitBreakerOpenException”- 발생 시점.
CircuitBreakerState::Open상태의CircuitBreaker가 어떤 다운스트림 호출 전에 호출을 fail-fast로 거부할 때입니다. “원격 서비스에 지금 당장 도달할 수 없다”(일시적 전송 장애, 저하할 가치가 있음)와 “이 호출이 연결 풀을 소진시켰을 것이다”(fail-fast, 네트워크 시도 없음)를 호출자가 구분할 수 있게 하기 위해 존재합니다. 이는 Public Key Infrastructure(PKI) 클라이언트에 요구되는 배치 서비스 거부 완화입니다. - 클래스.
RuntimeException을 직접 확장하므로getContext()를 담지 않습니다. - 담는 데이터. 두 개의 public
readonly속성입니다.$breakerName(열린 브레이커의 식별자)과$secondsUntilHalfOpen(브레이커가 half-open으로 전이하기까지 남은 대략적인 쿨다운)입니다. 메시지는Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.형식입니다. - 복구. 브레이커를 두드리지 마십시오. 재시도하기 전에 적어도
$secondsUntilHalfOpen만큼 기다리거나 작업을 저하시키십시오. 네트워크 호출은 시도되지 않았으므로, 이는 원격 서비스 자체가 실패했다는 증거가 아닙니다. 연결 풀을 보호하는 역압입니다.
관측성
섹션 제목: “관측성”SiemEmitterException
섹션 제목: “SiemEmitterException”- 발생 시점. SIEM 이벤트 에미터가 레코드를 영속화하거나 체인에 연결할 수 없을 때입니다. 해시 체인 이벤트 로그와 JSON-lines 파일 에미터 어댑터에 공유되는 파일 시스템 수준 실패(
open,lock,seek,write,fflush,read)와 해시 체인 무결성 장애(chain: 순서가 어긋난 색인, 잘못된 형식의 꼬리 레코드, JSON 왕복 변환 드리프트)를 표면화합니다. - 클래스.
NextPdfException을 확장하고getContext()를 재정의합니다. - 컨텍스트 키.
operation(open,lock,seek,write,fflush,read,chain중 하나),path(대상 로그 경로),detail(바이트 수 또는 예상 대 실제 색인 같은 사람이 읽을 수 있는 세부 정보)입니다. 이들은getOperation(),getPath(),getDetail()을 통해서도 도달할 수 있습니다. 메시지는SIEM emitter <operation> failed for <path>: <detail>.형식입니다. - 복구. 이는 애플리케이션 로직이 아니라 인프라 또는 SecOps가 조치할 수 있는 사안입니다. 로그 볼륨 마운트, 디렉터리 권한, 사용 가능한 파일 디스크립터, 파일 시스템 상태를 확인하십시오.
chain작업 실패는 감사 로그의 변조 또는 손상 신호를 나타내므로, 조용히 재시도하지 말고 조사해야 합니다.
렌더 매니페스트
섹션 제목: “렌더 매니페스트”RenderManifestException
섹션 제목: “RenderManifestException”- 발생 시점. 구조, 타입 또는 스키마 호환성 오류 때문에
RenderManifest를 생성, 역직렬화 또는 읽을 수 없을 때입니다. 매니페스트는 모든 전송(CLI, Laravel 큐, Symfony, SaaS API)이 제출하는 버전 관리된 공개 계약이므로, 잘못된 형식이거나 호환되지 않는 매니페스트는 기본값으로 강제하지 않고 직접 표면화됩니다. - 클래스.
NextPdfException을 확장하고getContext()를 재정의합니다. 이름 있는 생성자가SPEC-MANIFEST-*네임스페이스에 안정적인 기계 판독 가능 코드를 설정합니다.RenderManifestException::shape()→SPEC-MANIFEST-001—RenderManifest::fromArray()중 형태 또는 타입 오류입니다.RenderManifestException::incompatibleVersion()→SPEC-MANIFEST-002— 호환되지 않는 주요 스키마 버전입니다(읽을 수 없음).RenderManifestException::missingField()→SPEC-MANIFEST-003— 빌더 마무리 중 필수 필드 누락입니다.RenderManifestException::unsupported()→SPEC-MANIFEST-004— 올바른 형식의 매니페스트가 현재 렌더러가 해석할 수 없는 입력 또는 템플릿을 참조합니다(예: URI 입력 또는 호스트 전용 템플릿 엔진).
- 컨텍스트 키.
manifest_code(SPEC-MANIFEST-*식별자)와reason(사람이 읽을 수 있는 실패 설명)입니다. 이들은getManifestCode()와getReason()을 통해서도 도달할 수 있습니다. 메시지는[<code>] <reason>형식입니다. - 복구.
manifest_code로 분기하십시오.SPEC-MANIFEST-001과SPEC-MANIFEST-003의 경우, 매니페스트 페이로드를 수정하십시오(필드 타입을 바로잡거나 누락된 필드를 제공).SPEC-MANIFEST-002의 경우, 지원되는 주요 스키마 버전에 대해 매니페스트를 다시 생성하거나 렌더러를 업그레이드하십시오.SPEC-MANIFEST-004의 경우, 현재 에디션이 해석할 수 있는 입력 또는 템플릿 엔진을 제공하십시오.
InspectException
섹션 제목: “InspectException”- 발생 시점. PDF 검사가 실패할 때입니다.
- 클래스.
RuntimeException을 직접 확장합니다(NextPdfException이 아님). 따라서getContext()를 담지 않습니다. - 담는 데이터. 두 개의 public
readonly속성입니다.$inspectCode(INSPECT-*네임스페이스의 기계 판독 가능 코드)와$retryable(호출자가 재시도해야 하는지 나타내는 불리언, 예를 들어 검사 사이드카가 일시적으로 다운된 경우)입니다. 발단이 된 원인은 존재하는 경우 연결된 이전 throwable입니다. - 복구. 구체 실패 클래스에 대해
$inspectCode로 분기하십시오.$retryable이true일 때는 실패가 일시적일 것으로 예상되므로(예: 사이드카 재시작) 백오프와 함께 재시도하십시오.false일 때는 입력 또는 구성을 결함으로 취급하고 변경 없이 재시도하지 마십시오.
카오스 엔지니어링
섹션 제목: “카오스 엔지니어링”ChaosReportWriteException
섹션 제목: “ChaosReportWriteException”- 발생 시점.
ChaosScenarioRunner::writeReport()가 집계된 카오스 데이 보고서를 디스크에 영속화할 수 없을 때입니다. 이는 일반 런타임 오류를 도메인 타입으로 대체한 것으로, 호출자가 시나리오 시뮬레이터 자체 내부에서 발생한 오류(러너가ChaosOutcome필드로 캡처함)와 혼동하지 않고 특정 보고서 디스크 실패를 잡을 수 있게 합니다. - 클래스.
NextPdfException을 확장하고getContext()를 재정의합니다. - 컨텍스트 키.
output_path(러너가 쓰려고 시도한 절대 경로)입니다.getOutputPath()를 통해서도 도달할 수 있습니다. 메시지는ChaosScenarioRunner: failed to write report to "<path>".형식입니다. - 복구. 이는 시나리오가 아니라 보고서 싱크의 쓰기 측 실패입니다. 출력 디렉터리가 존재하고 쓰기 가능하며 디스크 공간이 있는지 확인한 뒤 보고서 쓰기를 다시 실행하십시오. 카오스 결과 자체는 영향을 받지 않습니다.
RetrievalUnavailableException
섹션 제목: “RetrievalUnavailableException”- 발생 시점. 검색 엔드포인트(예: Voyage Retrieval Augmented Generation 서비스)를 사용할 수 없고 시스템이 캐시 전용 모드로 폴백하거나 fail-closed될 때입니다.
- 클래스.
NextPdfException을 확장하고getContext()를 재정의합니다. - 컨텍스트 키.
mode(실패 후 운영 모드 — 결과를 의미 캐시에서만 제공할 때CACHED_ONLY, 오래된 데이터 없이 요청을 완전히 거부할 때FAIL_CLOSED)와endpoint(도달할 수 없게 된 엔드포인트)입니다. 이들은getMode()와getEndpoint()를 통해서도 도달할 수 있습니다. 메시지는Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.형식입니다. - 복구.
mode를 읽어 시스템이 어떻게 저하되었는지 파악하십시오.CACHED_ONLY에서는 결과가 오래되었을 수 있습니다. 엔드포인트가 복구되면 새로 고치십시오.FAIL_CLOSED에서는 요청이 의도적으로 거부되었으며, 엔드포인트에 도달할 수 있게 된 뒤 재시도해야 합니다. 새 검색에 의존하기 전에 엔드포인트 연결(네트워크, 자격 증명, 서비스 상태)을 복원하십시오.