ข้อผิดพลาดรันไทม์และการสนับสนุน

ขอบเขต

รายการเหล่านี้บันทึก exception ที่ยกโดยชั้น runtime support: นโยบายการลดทอน การขนส่ง HTTP ที่ขับเคลื่อนด้วย cURL ตัว resilience circuit breaker ตัวปล่อย Security Information and Event Management (SIEM) render manifest การตรวจสอบ PDF และระบบย่อย chaos-engineering

ทุก exception ของ NextPDF สืบทอดจาก NextPdfException ซึ่งนำ ContextAwareExceptionInterface ไปใช้และเปิดเผย getContext(): array สำหรับ การล็อกวินิจฉัยแบบมีโครงสร้าง ซับคลาสเติมอาร์เรย์นั้นเฉพาะเมื่อมัน เขียนทับ getContext() ฐานคืนอาร์เรย์ว่าง สาม exception บน หน้านี้ (DegradedException, CircuitBreakerOpenException, และ InspectException) สืบทอดจาก RuntimeException ของ PHP โดยตรงและเปิดเผยข้อมูลผ่านพร็อพเพอร์ตี public readonly แทน getContext() แต่ละรายการด้านล่างระบุชื่อ พร็อพเพอร์ตีหรือคีย์ context ที่แน่นอนที่คลาสพกพา ดึงมาจาก source

นโยบายการลดระดับการทำงาน

DegradedException

• ถูกยกเมื่อใด ไปป์ไลน์การเรนเดอร์พบความสามารถที่ถูกลดทอน ซึ่งละเมิดนโยบายการลดทอนที่ทำงานอยู่ ภายใต้ DegradationPolicy::Strict การลดทอนผลกระทบสูงใดๆ (ComplianceRisk, SemanticLoss, หรือ Blocking) ยกมัน ภายใต้ DegradationPolicy::Balanced เฉพาะผลกระทบ Blocking เท่านั้นที่ยกมัน
• Class สืบทอดจาก RuntimeException โดยตรง (ไม่ใช่ NextPdfException) มัน จึงไม่พกพา getContext()
• Data carried พร็อพเพอร์ตี public readonly สองตัว: $capability (value object Capability ที่ทำให้เกิดการปฏิเสธ รวมถึง id, status, reason, fallbackTarget, และ impact) และ $policy ( DegradationPolicy ที่ทำงานอยู่ ณ เวลาปฏิเสธ) ข้อความมีรูปแบบ Feature "<id>" is <status>: <reason> (policy: <policy>)
• Recovery ตรวจสอบ $capability เพื่อระบุคุณสมบัติที่ขาดหายและ สาเหตุของมัน ติดตั้งส่วนประกอบที่ความสามารถต้องการ ยอมรับ การกำหนดค่าผลกระทบต่ำลง หรือผ่อนนโยบายจาก Strict เป็น Balanced เมื่อการลดทอนยอมรับได้สำหรับ use case เรียก $capability->isAvailable() / isDegraded() เพื่อขับการส่งข้อความที่ผู้ใช้เห็น

การขนส่ง HTTP

exception สามตัวนี้มีต้นกำเนิดใน client PSR-18 ที่ขับเคลื่อนด้วย cURL และ decorator ที่ตระหนักความปลอดภัยของมัน สองตัวแรกสืบทอดจาก NextPdfException แต่ไม่ เขียนทับ getContext() ดังนั้น getContext() ของมันคืนอาร์เรย์ว่าง ข้อมูลวินิจฉัยเข้าถึงได้ผ่าน accessor getRequest() ของ PSR-18 และ throwable ก่อนหน้าที่เชื่อมโยงกัน

CurlNetworkException

• ถูกยกเมื่อใด คำขอ HTTP ไม่อาจทำให้สำเร็จได้เนื่องจาก ข้อบกพร่องระดับเครือข่าย: ความล้มเหลวการ resolve Domain Name System (DNS), การ timeout การเชื่อมต่อ หรือข้อผิดพลาด handshake Transport Layer Security (TLS) มัน ยังเป็นคลาสที่ decorator ที่ตระหนักความปลอดภัยยกขึ้นสำหรับการ ปฏิเสธด้านความปลอดภัย (การปฏิเสธ Server-Side Request Forgery การปฏิเสธ DNS-rebinding หรือ redirect ที่ถูกปฏิเสธ)
• Class นำ PSR-18 Psr\Http\Client\NetworkExceptionInterface ไปใช้
• Data carried getRequest() คืน RequestInterface ที่ล้มเหลว ข้อผิดพลาดการขนส่งต้นทาง เมื่อมี เป็น throwable ก่อนหน้าที่เชื่อมโยงกัน getContext() คืนอาร์เรย์ว่าง (ค่าเริ่มต้นฐาน)
• Recovery ข้อบกพร่องเครือข่ายอาจชั่วคราว — ลองใหม่ด้วย backoff หาก คำขอเป็น idempotent การปฏิเสธด้านความปลอดภัยไม่ชั่วคราวและต้องล้มเหลว แบบปิด: อย่าลองใหม่ แก้ URL เป้าหมายหรือนโยบาย SSRF แทน อ่านข้อความและ throwable ก่อนหน้าเพื่อแยกทั้งสอง

CurlRequestException

• ถูกยกเมื่อใด คำขอเองไม่อาจถูกส่งได้เพราะมันผิดรูป ตัวอย่างเช่น URL ที่ไม่ถูกต้องหรือคำขอที่ล้มเหลวการตรวจสอบยืนยัน SSRF ก่อน การเรียกเครือข่ายใดๆ
• Class นำ PSR-18 Psr\Http\Client\RequestExceptionInterface ไปใช้
• Data carried getRequest() คืน RequestInterface ที่เป็นปัญหา สาเหตุพื้นฐาน เมื่อมี เป็น throwable ก่อนหน้าที่เชื่อมโยงกัน getContext() คืนอาร์เรย์ว่าง
• Recovery นี่เป็นข้อบกพร่องของ input ผู้เรียกหรือนโยบาย ไม่ใช่ข้อบกพร่อง ชั่วคราว อย่าลองใหม่โดยไม่เปลี่ยน แก้ URL คำขอ header หรือ body หรือ ปรับ allowlist ของ SSRF หากเป้าหมายได้รับอนุญาตโดยชอบ แล้ว ส่งคำขอใหม่

TransientHttpException

• ถูกยกเมื่อใด ภายใน SecurityAwareHttpClient เพื่อทำเครื่องหมาย ข้อบกพร่อง inner-transport ที่ชั่วคราวอย่างแท้จริง (DNS การเชื่อมต่อ หรือ timeout ที่ยกโดย client PSR-18 ภายใน) ว่ามีสิทธิ์สำหรับงบประมาณการลองใหม่ที่มีขอบเขต มันเป็นคลาสเดียวที่มีสิทธิ์ลองใหม่ที่ลูปการลองใหม่ของ decorator รู้จัก exception ที่ไม่ถูก wrap (การปฏิเสธด้านความปลอดภัยที่ decorator ยก) ถูก ถือว่าเป็นภัยร้ายแรง
• Class นำ PSR-18 Psr\Http\Client\NetworkExceptionInterface ไปใช้ ทำเครื่องหมาย @internal — มันถูกสร้างและ unwrap ทั้งหมดภายใน SecurityAwareHttpClient และไม่เคยหลุดออกจาก decorator
• Data carried getRequest() คืนคำขอที่ล้มเหลว ClientExceptionInterface ของ inner-transport ดั้งเดิมถูกรักษาไว้เป็น throwable ก่อนหน้าที่เชื่อมโยงกัน (getPrevious()) และถูกปรากฏใหม่ตามตัวอักษรไปยังผู้เรียก เมื่องบประมาณการลองใหม่หมดลง สัญญา PSR-18 สาธารณะจึง ไม่เปลี่ยนแปลง getContext() คืนอาร์เรย์ว่าง
• Recovery โค้ดแอปพลิเคชันไม่จับชนิดนี้โดยตรง จับ exception ภายในที่ปรากฏใหม่ที่ decorator คืนหลังจากงบประมาณการลองใหม่ ถูกใช้ และถือว่าความล้มเหลวชั่วคราวที่เกิดซ้ำเป็นปัญหาความพร้อมใช้งานต้นน้ำ

ความยืดหยุ่น

CircuitBreakerOpenException

• ถูกยกเมื่อใด CircuitBreaker ในสถานะ CircuitBreakerState::Open ปฏิเสธการเรียกแบบ fail-fast ก่อนการเรียกใช้ปลายน้ำใดๆ มันมีอยู่เพื่อให้ ผู้เรียกแยก “บริการระยะไกลเข้าถึงไม่ได้ตอนนี้” ( ข้อบกพร่องการขนส่งชั่วคราว ควรลดทอน) ออกจาก “connection pool จะ ถูกใช้จนหมดโดยการเรียกนี้” (fail-fast ไม่มีการพยายามเครือข่าย) — การ มิติเกชัน batch denial-of-service ที่จำเป็นสำหรับ client Public Key Infrastructure (PKI)
• Class สืบทอดจาก RuntimeException โดยตรง มันจึงไม่พกพา getContext()
• Data carried พร็อพเพอร์ตี public readonly สองตัว: $breakerName ( ตัวระบุของ breaker ที่เปิด) และ $secondsUntilHalfOpen ( ระยะ cooldown โดยประมาณที่เหลือก่อน breaker เปลี่ยนเป็น half-open) ข้อความ มีรูปแบบ Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
• Recovery อย่ากระหน่ำ breaker — รออย่างน้อย $secondsUntilHalfOpen ก่อนลองใหม่ หรือลดทอน operation ไม่มีการ เรียกเครือข่ายเกิดขึ้น นี่จึงไม่ใช่หลักฐานว่าบริการระยะไกล เองล้มเหลว มันเป็น back-pressure ที่ปกป้อง connection pool

การสังเกตการณ์

SiemEmitterException

• ถูกยกเมื่อใด ตัวปล่อยเหตุการณ์ SIEM ไม่อาจ persist หรือ chain record มัน ปรากฏความล้มเหลวระดับ filesystem (open, lock, seek, write, fflush, read) และข้อบกพร่องความครบถ้วน hash-chain (chain: ดัชนี นอกลำดับ record tail ที่ผิดรูป หรือ JSON round-trip drift) ที่ใช้ร่วมกันทั่ว hash-chain event log และ adapter ตัวปล่อยไฟล์ JSON-lines
• Class สืบทอดจาก NextPdfException และเขียนทับ getContext()
• Context keys operation (หนึ่งใน open, lock, seek, write, fflush, read, chain), path (path ของ log เป้าหมาย) และ detail ( รายละเอียดที่มนุษย์อ่านได้ เช่น จำนวนไบต์หรือดัชนีที่คาดหวังเทียบกับจริง) สิ่งเหล่านี้ยังเข้าถึงได้ผ่าน getOperation(), getPath(), และ getDetail() ข้อความมีรูปแบบ SIEM emitter <operation> failed for <path>: <detail>.
• Recovery นี่ทำตามได้โดยฝ่ายโครงสร้างพื้นฐานหรือ SecOps ไม่ใช่โดย ลอจิกแอปพลิเคชัน ตรวจสอบ mount ของ log-volume สิทธิ์ของไดเรกทอรี file descriptor ที่ใช้ได้ และสุขภาพ filesystem ความล้มเหลว operation chain บ่งชี้สัญญาณ tamper หรือ corruption ใน audit log และควร ถูกตรวจสอบ ไม่ใช่ลองใหม่อย่างเงียบๆ

manifest การเรนเดอร์

RenderManifestException

• ถูกยกเมื่อใด RenderManifest ไม่อาจถูกสร้าง deserialize หรือ อ่านได้เนื่องจากข้อผิดพลาดเชิงโครงสร้าง ชนิด หรือความเข้ากันได้ของ schema manifest เป็นสัญญาสาธารณะแบบมีเวอร์ชันที่ส่งโดยทุก transport (CLI, Laravel queue, Symfony, SaaS API) manifest ที่ผิดรูปหรือไม่เข้ากันจึง ถูกปรากฏโดยตรงแทนการบีบให้เป็นค่าเริ่มต้น
• Class สืบทอดจาก NextPdfException และเขียนทับ getContext() constructor ที่ระบุชื่อตั้งรหัสที่เครื่องอ่านได้และเสถียรใน namespace SPEC-MANIFEST-*:
  • RenderManifestException::shape() → SPEC-MANIFEST-001 — ข้อผิดพลาดรูปทรงหรือ ชนิดระหว่าง RenderManifest::fromArray()
  • RenderManifestException::incompatibleVersion() → SPEC-MANIFEST-002 — เวอร์ชัน major ของ schema ที่ไม่เข้ากัน (อ่านไม่ได้)
  • RenderManifestException::missingField() → SPEC-MANIFEST-003 — ฟิลด์ ที่จำเป็นขาดหายระหว่างการ finalize builder
  • RenderManifestException::unsupported() → SPEC-MANIFEST-004 — manifest ที่มีรูปแบบดีอ้างถึง input หรือ template ที่ตัวเรนเดอร์ปัจจุบัน ไม่อาจ resolve ได้ (ตัวอย่างเช่น URI input หรือ template engine แบบ host-only)
• Context keys manifest_code (ตัวระบุ SPEC-MANIFEST-*) และ reason (คำอธิบายความล้มเหลวที่มนุษย์อ่านได้) สิ่งเหล่านี้ยังเข้าถึงได้ผ่าน getManifestCode() และ getReason() ข้อความมีรูปแบบ [<code>] <reason>
• Recovery แยกกิ่งบน manifest_code สำหรับ SPEC-MANIFEST-001 และ SPEC-MANIFEST-003 ให้แก้ payload ของ manifest (แก้ชนิดฟิลด์หรือ จัดหาฟิลด์ที่ขาดหาย) สำหรับ SPEC-MANIFEST-002 ให้สร้าง manifest ใหม่ เทียบกับเวอร์ชัน major ของ schema ที่รองรับหรืออัปเกรดตัวเรนเดอร์ สำหรับ SPEC-MANIFEST-004 ให้จัดหา input หรือ template engine ที่ edition ปัจจุบัน resolve ได้

การตรวจสอบ

InspectException

• ถูกยกเมื่อใด การตรวจสอบ PDF ล้มเหลว
• Class สืบทอดจาก RuntimeException โดยตรง (ไม่ใช่ NextPdfException) มัน จึงไม่พกพา getContext()
• Data carried พร็อพเพอร์ตี public readonly สองตัว: $inspectCode ( รหัสที่เครื่องอ่านได้ใน namespace INSPECT-*) และ $retryable ( boolean ที่บ่งชี้ว่าผู้เรียกควรลองใหม่หรือไม่ — ตัวอย่างเช่นเมื่อ inspection sidecar ล่มชั่วคราว) สาเหตุต้นทาง เมื่อ มี เป็น throwable ก่อนหน้าที่เชื่อมโยงกัน
• Recovery แยกกิ่งบน $inspectCode สำหรับคลาสความล้มเหลวที่เฉพาะเจาะจง เมื่อ $retryable เป็น true ให้ลองใหม่ด้วย backoff เพราะคาดว่าความล้มเหลว จะชั่วคราว (เช่นการ restart sidecar) เมื่อ false ให้ถือว่า input หรือการกำหนดค่าเป็นข้อบกพร่องและอย่าลองใหม่โดยไม่เปลี่ยน

วิศวกรรมความโกลาหล

ChaosReportWriteException

• ถูกยกเมื่อใด ChaosScenarioRunner::writeReport() ไม่อาจ persist รายงาน chaos-day ที่รวมแล้วลงดิสก์ มันเป็นการแทนที่แบบมีชนิดโดเมนสำหรับ runtime error ทั่วไป ผู้เรียกจึงจับความล้มเหลว report-disk ที่เฉพาะเจาะจง ได้โดยไม่รวมมันกับข้อผิดพลาดที่ยกภายในตัวจำลอง scenario เอง (runner จับพวกนั้นเป็นฟิลด์ ChaosOutcome)
• Class สืบทอดจาก NextPdfException และเขียนทับ getContext()
• Context keys output_path (absolute path ที่ runner พยายาม เขียน) มันยังเข้าถึงได้ผ่าน getOutputPath() ข้อความมี รูปแบบ ChaosScenarioRunner: failed to write report to "<path>".
• Recovery นี่เป็นความล้มเหลวฝั่งเขียนของ report sink ไม่ใช่ของ scenario ตรวจสอบว่าไดเรกทอรีเอาต์พุตมีอยู่และเขียนได้และว่าพื้นที่ดิสก์ ใช้ได้ แล้วรันการเขียนรายงานใหม่ ผล chaos เองไม่ได้รับผลกระทบ

RetrievalUnavailableException

• ถูกยกเมื่อใด ปลายทางการดึงข้อมูล (ตัวอย่างเช่นบริการ Voyage Retrieval Augmented Generation) ไม่พร้อมใช้งานและระบบ fall back ไปยังโหมด cached-only หรือล้มเหลวแบบปิด
• Class สืบทอดจาก NextPdfException และเขียนทับ getContext()
• Context keys mode (โหมดการทำงานหลังความล้มเหลว — CACHED_ONLY เมื่อผลลัพธ์ถูกเสิร์ฟจาก semantic cache เท่านั้น หรือ FAIL_CLOSED เมื่อคำขอถูกปฏิเสธทั้งหมดโดยไม่มีข้อมูลค้าง) และ endpoint (ปลายทางที่กลายเป็นเข้าถึงไม่ได้) สิ่งเหล่านี้ยังเข้าถึงได้ ผ่าน getMode() และ getEndpoint() ข้อความมีรูปแบบ Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
• Recovery อ่าน mode เพื่อเรียนรู้ว่าระบบลดทอนอย่างไร ภายใต้ CACHED_ONLY ผลลัพธ์อาจค้าง รีเฟรชเมื่อปลายทางกู้คืน ภายใต้ FAIL_CLOSED คำขอถูกปฏิเสธโดยการออกแบบและต้องลองใหม่ หลังจากปลายทางเข้าถึงได้ กู้คืนการเชื่อมต่อปลายทาง (เครือข่าย credential สุขภาพบริการ) ก่อนพึ่งพาการดึงข้อมูลใหม่

ดูเพิ่มเติม

• Error reference index
• Troubleshoot signatures and timestamps
• Troubleshooting: encryption and permissions
• Troubleshooting: fonts and tagging
• Troubleshooting: PDF/A and PDF/UA validation