Lỗi môi trường chạy và hỗ trợ

Phạm vi

Các mục này lập tài liệu cho các ngoại lệ được nêu ra bởi lớp hỗ trợ môi trường chạy: chính sách suy giảm, truyền tải HTTP dựa-trên-cURL, circuit breaker khả-năng-phục-hồi, bộ phát Security Information and Event Management (SIEM), render manifest, kiểm tra PDF, và hệ thống con kỹ thuật chaos.

Mọi ngoại lệ NextPDF đều mở rộng NextPdfException, vốn hiện thực ContextAwareExceptionInterface và phơi bày getContext(): array cho việc ghi nhật ký chẩn đoán có cấu trúc. Một lớp con điền mảng đó chỉ khi nó ghi đè getContext(); lớp cơ sở trả về một mảng rỗng. Ba ngoại lệ trên trang này (DegradedException, CircuitBreakerOpenException, và InspectException) mở rộng trực tiếp RuntimeException của PHP và phơi bày dữ liệu của chúng qua các thuộc tính công khai readonly thay vì getContext(). Mỗi mục bên dưới nêu tên chính xác các thuộc tính hoặc khóa context mà lớp mang theo, lấy từ mã nguồn.

Chính sách suy giảm

`DegradedException`

Được ném khi. Quy trình kết xuất gặp một năng lực bị suy giảm vi phạm chính sách suy giảm đang hoạt động. Dưới DegradationPolicy::Strict, bất kỳ suy giảm có tác động cao nào (ComplianceRisk, SemanticLoss, hoặc Blocking) đều nêu nó ra; dưới DegradationPolicy::Balanced, chỉ một tác động Blocking mới nêu nó ra.
Lớp. Mở rộng trực tiếp RuntimeException (không phải NextPdfException), nên nó không mang getContext().
Dữ liệu mang theo. Hai thuộc tính công khai readonly: $capability (đối tượng giá trị Capability đã kích hoạt việc từ chối, bao gồm id, status, reason, fallbackTarget, và impact của nó) và $policy (chính sách DegradationPolicy đang hoạt động tại thời điểm từ chối). Thông báo có dạng Feature "<id>" is <status>: <reason> (policy: <policy>).
Khôi phục. Kiểm tra $capability để xác định tính năng còn thiếu và nguyên nhân của nó. Hoặc cài đặt thành phần mà năng lực yêu cầu, chấp nhận một cấu hình tác-động-thấp-hơn, hoặc nới chính sách từ Strict về Balanced khi suy giảm là chấp nhận được cho trường hợp dùng. Gọi $capability->isAvailable() / isDegraded() để điều khiển thông điệp hướng tới người dùng.

Truyền tải HTTP

Ba ngoại lệ này bắt nguồn từ ứng dụng khách PSR-18 dựa-trên-cURL và bộ trang trí nhận-biết-bảo-mật của nó. Hai cái đầu mở rộng NextPdfException nhưng không ghi đè getContext(), nên getContext() của chúng trả về một mảng rỗng; dữ liệu chẩn đoán được với tới qua accessor PSR-18 getRequest() và throwable trước trong chuỗi.

`CurlNetworkException`

Được ném khi. Yêu cầu HTTP không thể hoàn tất vì một lỗi cấp-mạng: lỗi phân giải Domain Name System (DNS), timeout kết nối, hoặc lỗi handshake Transport Layer Security (TLS). Nó cũng là lớp mà bộ trang trí nhận-biết-bảo-mật nêu ra cho một từ chối bảo mật (từ chối Server-Side Request Forgery, từ chối DNS-rebinding, hoặc một redirect bị từ chối).
Lớp. Hiện thực PSR-18 Psr\Http\Client\NetworkExceptionInterface.
Dữ liệu mang theo. getRequest() trả về RequestInterface thất bại. Lỗi truyền tải bắt nguồn, khi có, là throwable trước trong chuỗi. getContext() trả về một mảng rỗng (mặc định cơ sở).
Khôi phục. Một lỗi mạng có thể là nhất thời — thử lại với backoff nếu yêu cầu là idempotent. Một từ chối bảo mật không nhất thời và phải thất bại theo hướng đóng: đừng thử lại; thay vào đó sửa URL đích hoặc chính sách SSRF. Đọc thông báo và throwable trước để phân biệt hai cái.

`CurlRequestException`

Được ném khi. Bản thân yêu cầu không thể được gửi vì nó bị hỏng khuôn, ví dụ một URL không hợp lệ hoặc một yêu cầu thất bại ở xác thực SSRF trước bất kỳ lệnh gọi mạng nào.
Lớp. Hiện thực PSR-18 Psr\Http\Client\RequestExceptionInterface.
Dữ liệu mang theo. getRequest() trả về RequestInterface gây lỗi; nguyên nhân nền, khi có, là throwable trước trong chuỗi. getContext() trả về một mảng rỗng.
Khôi phục. Đây là một lỗi đầu-vào-của-caller hoặc lỗi chính sách, không phải một lỗi nhất thời. Đừng thử lại khi chưa thay đổi. Sửa URL yêu cầu, header, hoặc thân, hoặc điều chỉnh allowlist SSRF nếu đích được phép một cách chính đáng, rồi phát lại yêu cầu.

`TransientHttpException`

Được ném khi. Nội bộ, bên trong SecurityAwareHttpClient, để đánh dấu một lỗi truyền-tải-trong nhất thời thực sự (DNS, kết nối, hoặc timeout được nêu bởi ứng dụng khách PSR-18 bên trong) là đủ điều kiện cho ngân sách thử lại có giới hạn. Nó là lớp đủ-điều-kiện-thử-lại duy nhất mà vòng lặp thử-lại của bộ trang trí nhận diện; một ngoại lệ không-bọc (một từ chối bảo mật do bộ trang trí nêu) được coi là chí mạng.
Lớp. Hiện thực PSR-18 Psr\Http\Client\NetworkExceptionInterface. Đánh dấu @internal — nó được tạo và mở-bọc hoàn toàn trong SecurityAwareHttpClient và không bao giờ lọt khỏi bộ trang trí.
Dữ liệu mang theo. getRequest() trả về yêu cầu thất bại. ClientExceptionInterface truyền-tải-trong gốc được giữ là throwable trước trong chuỗi (getPrevious()) và được phơi bày lại nguyên văn cho caller một khi ngân sách thử lại cạn kiệt, nên hợp đồng PSR-18 công khai không đổi. getContext() trả về một mảng rỗng.
Khôi phục. Mã ứng dụng không bắt kiểu này trực tiếp. Bắt ngoại lệ bên trong được phơi-bày-lại mà bộ trang trí trả về sau khi ngân sách thử-lại cạn kiệt, và coi các lỗi nhất thời lặp lại là một vấn đề về tính sẵn sàng phía thượng nguồn.

Khả năng phục hồi

`CircuitBreakerOpenException`

Được ném khi. Một CircuitBreaker ở trạng thái CircuitBreakerState::Open từ chối một lệnh gọi theo kiểu fail-fast, trước bất kỳ lệnh gọi hạ nguồn nào. Nó tồn tại để cho phép các caller phân biệt “dịch vụ từ xa hiện không thể tiếp cận” (một lỗi truyền tải nhất thời, đáng suy giảm) với “connection pool sẽ bị cạn kiệt bởi lệnh gọi này” (fail-fast, không có mạng nào được thử) — biện pháp giảm thiểu từ-chối-dịch-vụ theo lô cần thiết cho các ứng dụng khách Public Key Infrastructure (PKI).
Lớp. Mở rộng trực tiếp RuntimeException, nên nó không mang getContext().
Dữ liệu mang theo. Hai thuộc tính công khai readonly: $breakerName (định danh của breaker đang mở) và $secondsUntilHalfOpen (thời gian cooldown gần đúng còn lại trước khi breaker chuyển sang half-open). Thông báo có dạng Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
Khôi phục. Đừng dồn dập gọi breaker — chờ ít nhất $secondsUntilHalfOpen trước khi thử lại, hoặc suy giảm thao tác. Không lệnh gọi mạng nào được thử, nên đây không phải là bằng chứng rằng dịch vụ từ xa tự nó thất bại; nó là back-pressure bảo vệ connection pool.

Khả năng quan sát

`SiemEmitterException`

Được ném khi. Một bộ phát sự kiện SIEM không thể lưu hoặc móc xích một bản ghi. Nó phơi bày các lỗi cấp-hệ-thống-tệp (open, lock, seek, write, fflush, read) và các lỗi toàn vẹn hash-chain (chain: chỉ mục sai thứ tự, bản ghi đuôi hỏng khuôn, hoặc lệch round-trip JSON) chia sẻ giữa log sự kiện hash-chain và các adapter bộ phát tệp JSON-lines.
Lớp. Mở rộng NextPdfException và ghi đè getContext().
Khóa context. operation (một trong open, lock, seek, write, fflush, read, chain), path (đường dẫn log đích), và detail (một chi tiết dễ đọc cho con người như số byte hoặc chỉ-mục-mong-đợi-so-với-thực-tế). Những thứ này cũng được với tới qua getOperation(), getPath(), và getDetail(). Thông báo có dạng SIEM emitter <operation> failed for <path>: <detail>.
Khôi phục. Đây là việc có thể hành động bởi hạ tầng hoặc SecOps, không phải bởi logic ứng dụng. Kiểm tra mount của log-volume, quyền thư mục, các file descriptor khả dụng, và sức khỏe hệ thống tệp. Một lỗi thao tác chain cho thấy một tín hiệu giả mạo hoặc hỏng trong log audit và nên được điều tra, không âm thầm thử lại.

Manifest kết xuất

`RenderManifestException`

Được ném khi. Một RenderManifest không thể được dựng, giải-tuần-tự-hóa, hoặc đọc vì một lỗi cấu trúc, kiểu, hoặc tương-thích-schema. Manifest là một hợp đồng công khai được đánh phiên bản do mọi truyền tải gửi (CLI, hàng đợi Laravel, Symfony, API SaaS), nên một manifest hỏng khuôn hoặc không tương thích được phơi bày trực tiếp thay vì bị ép về mặc định.
Lớp. Mở rộng NextPdfException và ghi đè getContext(). Các constructor có tên đặt một mã ổn định, máy đọc được trong không gian tên SPEC-MANIFEST-*:
- RenderManifestException::shape() → SPEC-MANIFEST-001 — lỗi hình dạng hoặc kiểu trong RenderManifest::fromArray().
- RenderManifestException::incompatibleVersion() → SPEC-MANIFEST-002 — phiên bản schema chính không tương thích (không thể được đọc).
- RenderManifestException::missingField() → SPEC-MANIFEST-003 — thiếu một trường bắt buộc trong khi hoàn tất builder.
- RenderManifestException::unsupported() → SPEC-MANIFEST-004 — một manifest hợp khuôn tham chiếu một đầu vào hoặc template mà trình kết xuất hiện tại không thể phân giải (ví dụ một đầu vào URI hoặc một engine template chỉ-chạy-trên-host).
Khóa context. manifest_code (định danh SPEC-MANIFEST-*) và reason (mô tả lỗi dễ đọc cho con người). Những thứ này cũng được với tới qua getManifestCode() và getReason(). Thông báo có dạng [<code>] <reason>.
Khôi phục. Rẽ nhánh theo manifest_code. Với SPEC-MANIFEST-001 và SPEC-MANIFEST-003, sửa payload manifest (sửa kiểu trường hoặc cung cấp trường còn thiếu). Với SPEC-MANIFEST-002, tạo lại manifest đối với một phiên bản schema chính được hỗ trợ hoặc nâng cấp trình kết xuất. Với SPEC-MANIFEST-004, cung cấp một đầu vào hoặc engine template mà phiên bản hiện tại có thể phân giải.

Kiểm tra

`InspectException`

Được ném khi. Kiểm tra PDF thất bại.
Lớp. Mở rộng trực tiếp RuntimeException (không phải NextPdfException), nên nó không mang getContext().
Dữ liệu mang theo. Hai thuộc tính công khai readonly: $inspectCode (một mã máy đọc được trong không gian tên INSPECT-*) và $retryable (một boolean cho biết caller có nên thử lại — ví dụ khi một sidecar kiểm tra tạm thời ngừng). Nguyên nhân bắt nguồn, khi có, là throwable trước trong chuỗi.
Khôi phục. Rẽ nhánh theo $inspectCode cho lớp lỗi cụ thể. Khi $retryable là true, thử lại với backoff vì lỗi được kỳ vọng là nhất thời (chẳng hạn một lần khởi động lại sidecar); khi false, coi đầu vào hoặc cấu hình là khiếm khuyết và đừng thử lại khi chưa thay đổi.

Kỹ thuật chaos

`ChaosReportWriteException`

Được ném khi. ChaosScenarioRunner::writeReport() không thể lưu báo cáo chaos-day tổng hợp xuống đĩa. Nó là một thay thế có-kiểu-theo-lĩnh-vực cho một lỗi môi-trường-chạy chung, nên các caller có thể bắt lỗi đĩa-báo-cáo cụ thể mà không lẫn nó với các lỗi được nêu bên trong các bộ mô phỏng kịch bản (runner ghi lại những lỗi đó dưới dạng các trường ChaosOutcome).
Lớp. Mở rộng NextPdfException và ghi đè getContext().
Khóa context. output_path (đường dẫn tuyệt đối mà runner đã cố ghi). Nó cũng được với tới qua getOutputPath(). Thông báo có dạng ChaosScenarioRunner: failed to write report to "<path>".
Khôi phục. Đây là một lỗi phía-ghi của sink báo cáo, không phải của các kịch bản. Kiểm tra thư mục output tồn tại và ghi được và rằng dung lượng đĩa có sẵn, rồi chạy lại lần ghi báo cáo. Bản thân các kết quả chaos không bị ảnh hưởng.

`RetrievalUnavailableException`

Được ném khi. Một điểm cuối truy xuất (ví dụ một dịch vụ Voyage Retrieval Augmented Generation) không có sẵn và hệ thống hoặc dự phòng về chế độ chỉ-cache hoặc thất bại theo hướng đóng.
Lớp. Mở rộng NextPdfException và ghi đè getContext().
Khóa context. mode (chế độ vận hành sau lỗi — CACHED_ONLY khi kết quả được phục vụ chỉ từ cache ngữ nghĩa, hoặc FAIL_CLOSED khi yêu cầu bị từ chối hoàn toàn không có dữ liệu cũ) và endpoint (điểm cuối đã trở nên không thể tiếp cận). Những thứ này cũng được với tới qua getMode() và getEndpoint(). Thông báo có dạng Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
Khôi phục. Đọc mode để biết hệ thống đã suy giảm thế nào. Dưới CACHED_ONLY, kết quả có thể cũ; làm mới một khi điểm cuối khôi phục. Dưới FAIL_CLOSED, yêu cầu đã bị từ chối theo thiết kế và phải được thử lại sau khi điểm cuối có thể tiếp cận. Khôi phục kết nối tới điểm cuối (mạng, thông tin xác thực, sức khỏe dịch vụ) trước khi phụ thuộc vào truy xuất tươi.

Lỗi môi trường chạy và hỗ trợ

Phạm vi

Chính sách suy giảm

DegradedException

Truyền tải HTTP

CurlNetworkException

CurlRequestException

TransientHttpException

Khả năng phục hồi

CircuitBreakerOpenException