Kesalahan runtime dan pendukung

Cakupan

Entri-entri ini mendokumentasikan eksepsi yang dimunculkan oleh lapisan pendukung runtime: kebijakan degradasi, transport HTTP yang didukung-cURL, circuit breaker ketahanan, emitter Security Information and Event Management (SIEM), render manifest, inspeksi PDF, dan subsistem chaos-engineering.

Setiap eksepsi NextPDF memperluas NextPdfException, yang mengimplementasikan ContextAwareExceptionInterface dan memaparkan getContext(): array untuk pencatatan diagnostik terstruktur. Sebuah subkelas mengisi array tersebut hanya ketika ia menimpa getContext(); basis mengembalikan array kosong. Tiga eksepsi pada halaman ini (DegradedException, CircuitBreakerOpenException, dan InspectException) memperluas RuntimeException PHP secara langsung dan memaparkan datanya melalui properti readonly publik alih-alih getContext(). Setiap entri di bawah menyebutkan properti atau kunci konteks persis yang dibawa kelas tersebut, diambil dari sumber.

Kebijakan degradasi

DegradedException

• Dilemparkan ketika. Pipeline rendering menjumpai kapabilitas terdegradasi yang melanggar kebijakan degradasi aktif. Di bawah DegradationPolicy::Strict, setiap degradasi berdampak-tinggi (ComplianceRisk, SemanticLoss, atau Blocking) memunculkannya; di bawah DegradationPolicy::Balanced, hanya dampak Blocking yang memunculkannya.
• Kelas. Memperluas RuntimeException secara langsung (bukan NextPdfException), sehingga ia tidak membawa getContext().
• Data yang dibawa. Dua properti readonly publik: $capability (objek nilai Capability yang memicu penolakan, termasuk id, status, reason, fallbackTarget, dan impact-nya) dan $policy (kebijakan DegradationPolicy yang aktif pada saat penolakan). Pesan tersebut berbentuk Feature "<id>" is <status>: <reason> (policy: <policy>).
• Pemulihan. Periksa $capability untuk mengidentifikasi fitur yang hilang dan penyebabnya. Baik pasang komponen yang dibutuhkan kapabilitas tersebut, terima konfigurasi berdampak-lebih-rendah, atau longgarkan kebijakan dari Strict ke Balanced ketika degradasi dapat diterima untuk kasus penggunaan tersebut. Panggil $capability->isAvailable() / isDegraded() untuk mengendalikan pesan yang menghadap-pengguna.

Transport HTTP

Ketiga eksepsi ini berasal dari klien PSR-18 yang didukung-cURL dan dekorator sadar-keamanannya. Dua yang pertama memperluas NextPdfException tetapi tidak menimpa getContext(), sehingga getContext()-nya mengembalikan array kosong; data diagnostik dijangkau melalui aksesor getRequest() PSR-18 dan throwable sebelumnya yang terangkai.

CurlNetworkException

• Dilemparkan ketika. Permintaan HTTP tidak dapat diselesaikan karena sebuah fault tingkat-jaringan: kegagalan resolusi Domain Name System (DNS), timeout koneksi, atau kesalahan handshake Transport Layer Security (TLS). Ini juga merupakan kelas yang dimunculkan dekorator sadar-keamanan untuk penolakan keamanan (penolakan Server-Side Request Forgery, penolakan DNS-rebinding, atau redirect yang ditolak).
• Kelas. Mengimplementasikan PSR-18 Psr\Http\Client\NetworkExceptionInterface.
• Data yang dibawa. getRequest() mengembalikan RequestInterface yang gagal. Kesalahan transport yang berasal, saat hadir, adalah throwable sebelumnya yang terangkai. getContext() mengembalikan array kosong (bawaan basis).
• Pemulihan. Sebuah fault jaringan mungkin transien — coba ulang dengan backoff jika permintaan idempoten. Penolakan keamanan tidak transien dan harus gagal- tertutup: jangan coba ulang; perbaiki URL target atau kebijakan SSRF sebagai gantinya. Baca pesan dan throwable sebelumnya untuk membedakan keduanya.

CurlRequestException

• Dilemparkan ketika. Permintaan itu sendiri tidak dapat dikirim karena cacat, misalnya URL tidak valid atau permintaan yang gagal validasi SSRF sebelum panggilan jaringan apa pun.
• Kelas. Mengimplementasikan PSR-18 Psr\Http\Client\RequestExceptionInterface.
• Data yang dibawa. getRequest() mengembalikan RequestInterface yang bermasalah; penyebab yang mendasarinya, saat hadir, adalah throwable sebelumnya yang terangkai. getContext() mengembalikan array kosong.
• Pemulihan. Ini adalah cacat masukan-pemanggil atau kebijakan, bukan fault transien. Jangan coba ulang tanpa perubahan. Perbaiki URL, header, atau body permintaan, atau sesuaikan allowlist SSRF jika target memang diizinkan secara sah, lalu ajukan ulang permintaan tersebut.

TransientHttpException

• Dilemparkan ketika. Secara internal, di dalam SecurityAwareHttpClient, untuk menandai sebuah fault transport-dalam yang benar-benar transien (DNS, koneksi, atau timeout yang dimunculkan klien PSR-18 dalam) sebagai memenuhi syarat untuk anggaran retry terbatas. Ini adalah satu-satunya kelas yang memenuhi-syarat-retry yang dikenali loop retry dekorator; eksepsi yang tidak terbungkus (penolakan keamanan yang dimunculkan dekorator) diperlakukan sebagai fatal.
• Kelas. Mengimplementasikan PSR-18 Psr\Http\Client\NetworkExceptionInterface. Ditandai @internal — eksepsi ini dibuat dan dibuka sepenuhnya di dalam SecurityAwareHttpClient dan tidak pernah lolos dari dekorator.
• Data yang dibawa. getRequest() mengembalikan permintaan yang gagal. Eksepsi ClientExceptionInterface transport-dalam yang asli dipertahankan sebagai throwable sebelumnya yang terangkai (getPrevious()) dan dimunculkan-ulang apa adanya ke pemanggil setelah anggaran retry habis, sehingga kontrak PSR-18 publik tidak berubah. getContext() mengembalikan array kosong.
• Pemulihan. Kode aplikasi tidak menangkap tipe ini secara langsung. Tangkap eksepsi dalam yang dimunculkan-ulang yang dikembalikan dekorator setelah anggaran retry habis, dan perlakukan kegagalan transien berulang sebagai masalah ketersediaan di hulu.

Ketahanan

CircuitBreakerOpenException

• Dilemparkan ketika. Sebuah CircuitBreaker dalam status CircuitBreakerState::Open menolak panggilan secara fail-fast, sebelum pemanggilan di hilir apa pun. Eksepsi ini ada untuk memungkinkan pemanggil membedakan “layanan jarak jauh tidak terjangkau saat ini” (sebuah fault transport transien, layak didegradasi) dari “kumpulan koneksi akan habis oleh panggilan ini” (fail-fast, tidak ada jaringan yang dicoba) — mitigasi denial-of-service batch yang diwajibkan untuk klien Public Key Infrastructure (PKI).
• Kelas. Memperluas RuntimeException secara langsung, sehingga ia tidak membawa getContext().
• Data yang dibawa. Dua properti readonly publik: $breakerName (pengenal breaker terbuka) dan $secondsUntilHalfOpen (perkiraan cooldown yang tersisa sebelum breaker beralih ke half-open). Pesan tersebut berbentuk Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
• Pemulihan. Jangan menggempur breaker — tunggu setidaknya $secondsUntilHalfOpen sebelum mencoba ulang, atau degradasikan operasinya. Tidak ada panggilan jaringan yang dicoba, sehingga ini bukan bukti bahwa layanan jarak jauh itu sendiri gagal; ini adalah back-pressure yang melindungi kumpulan koneksi.

Observabilitas

SiemEmitterException

• Dilemparkan ketika. Sebuah emitter event SIEM tidak dapat memersistensikan atau merangkai sebuah rekaman. Ia memunculkan kegagalan tingkat-sistem-berkas (open, lock, seek, write, fflush, read) dan fault integritas hash-chain (chain: indeks tak-urut, rekaman tail cacat, atau drift round-trip JSON) yang dibagikan di seluruh log event hash-chain dan adaptor emitter berkas JSON-lines.
• Kelas. Memperluas NextPdfException dan menimpa getContext().
• Kunci konteks. operation (salah satu dari open, lock, seek, write, fflush, read, chain), path (jalur log target), dan detail (sebuah detail yang dapat dibaca manusia seperti jumlah byte atau indeks yang-diharapkan-versus-aktual). Ini juga dapat dijangkau melalui getOperation(), getPath(), dan getDetail(). Pesan tersebut berbentuk SIEM emitter <operation> failed for <path>: <detail>.
• Pemulihan. Ini dapat ditindaklanjuti oleh infrastruktur atau SecOps, bukan oleh logika aplikasi. Verifikasi mount log-volume, izin direktori, deskriptor berkas yang tersedia, dan kesehatan sistem berkas. Sebuah kegagalan operasi chain menunjukkan sinyal pengrusakan atau korupsi dalam log audit dan seharusnya diselidiki, bukan dicoba ulang secara senyap.

Render manifest

RenderManifestException

• Dilemparkan ketika. Sebuah RenderManifest tidak dapat dikonstruksi, dideserialisasi, atau dibaca karena kesalahan struktural, tipe, atau kompatibilitas-skema. Manifest adalah kontrak publik berversi yang diajukan oleh setiap transport (CLI, antrean Laravel, Symfony, API SaaS), sehingga manifest yang cacat atau tidak kompatibel dimunculkan secara langsung alih-alih dipaksa ke bawaan.
• Kelas. Memperluas NextPdfException dan menimpa getContext(). Konstruktor yang dinamai menetapkan kode yang dapat-dibaca-mesin dan stabil dalam namespace SPEC-MANIFEST-*:
  • RenderManifestException::shape() → SPEC-MANIFEST-001 — kesalahan bentuk atau tipe selama RenderManifest::fromArray().
  • RenderManifestException::incompatibleVersion() → SPEC-MANIFEST-002 — versi skema mayor yang tidak kompatibel (tidak dapat dibaca).
  • RenderManifestException::missingField() → SPEC-MANIFEST-003 — bidang wajib hilang selama finalisasi builder.
  • RenderManifestException::unsupported() → SPEC-MANIFEST-004 — sebuah manifest yang terbentuk dengan baik mereferensikan masukan atau template yang tidak dapat diresolusi renderer saat ini (misalnya masukan URI atau mesin template host-only).
• Kunci konteks. manifest_code (pengenal SPEC-MANIFEST-*) dan reason (deskripsi kegagalan yang dapat dibaca manusia). Ini juga dapat dijangkau melalui getManifestCode() dan getReason(). Pesan tersebut berbentuk [<code>] <reason>.
• Pemulihan. Bercabanglah pada manifest_code. Untuk SPEC-MANIFEST-001 dan SPEC-MANIFEST-003, perbaiki payload manifest (perbaiki tipe bidang atau suplai bidang yang hilang). Untuk SPEC-MANIFEST-002, hasilkan ulang manifest terhadap versi skema mayor yang didukung atau mutakhirkan renderer. Untuk SPEC-MANIFEST-004, suplai masukan atau mesin template yang dapat diresolusi edisi saat ini.

Inspeksi

InspectException

• Dilemparkan ketika. Inspeksi PDF gagal.
• Kelas. Memperluas RuntimeException secara langsung (bukan NextPdfException), sehingga ia tidak membawa getContext().
• Data yang dibawa. Dua properti readonly publik: $inspectCode (sebuah kode yang dapat-dibaca-mesin dalam namespace INSPECT-*) dan $retryable (sebuah boolean yang menunjukkan apakah pemanggil sebaiknya mencoba ulang — misalnya ketika sebuah sidecar inspeksi sementara mati). Penyebab yang berasal, saat hadir, adalah throwable sebelumnya yang terangkai.
• Pemulihan. Bercabanglah pada $inspectCode untuk kelas kegagalan tertentu. Ketika $retryable adalah true, coba ulang dengan backoff karena kegagalan diperkirakan transien (seperti restart sidecar); ketika false, perlakukan masukan atau konfigurasi sebagai cacat dan jangan coba ulang tanpa perubahan.

Chaos engineering

ChaosReportWriteException

• Dilemparkan ketika. ChaosScenarioRunner::writeReport() tidak dapat memersistensikan laporan chaos-day teragregasi ke disk. Ini adalah pengganti bertipe-domain untuk kesalahan runtime generik, sehingga pemanggil dapat menangkap kegagalan report-disk yang spesifik tanpa mengaburkannya dengan kesalahan yang dimunculkan di dalam simulator skenario itu sendiri (runner menangkap yang itu sebagai bidang ChaosOutcome).
• Kelas. Memperluas NextPdfException dan menimpa getContext().
• Kunci konteks. output_path (jalur absolut yang dicoba ditulis runner). Ia juga dapat dijangkau melalui getOutputPath(). Pesan tersebut berbentuk ChaosScenarioRunner: failed to write report to "<path>".
• Pemulihan. Ini adalah kegagalan sisi-tulis dari sink laporan, bukan dari skenario. Verifikasi direktori keluaran ada dan dapat ditulis serta bahwa ruang disk tersedia, lalu jalankan ulang penulisan laporan. Hasil chaos itu sendiri tidak terpengaruh.

RetrievalUnavailableException

• Dilemparkan ketika. Sebuah endpoint retrieval (misalnya layanan Voyage Retrieval Augmented Generation) tidak tersedia dan sistem baik jatuh kembali ke mode cached-only atau gagal-tertutup.
• Kelas. Memperluas NextPdfException dan menimpa getContext().
• Kunci konteks. mode (mode operasi setelah kegagalan — CACHED_ONLY ketika hasil disajikan hanya dari cache semantik, atau FAIL_CLOSED ketika permintaan ditolak sepenuhnya tanpa data basi) dan endpoint (endpoint yang menjadi tak terjangkau). Ini juga dapat dijangkau melalui getMode() dan getEndpoint(). Pesan tersebut berbentuk Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
• Pemulihan. Baca mode untuk mengetahui bagaimana sistem terdegradasi. Di bawah CACHED_ONLY, hasil mungkin basi; segarkan setelah endpoint pulih. Di bawah FAIL_CLOSED, permintaan ditolak by design dan harus dicoba ulang setelah endpoint terjangkau. Pulihkan konektivitas endpoint (jaringan, kredensial, kesehatan layanan) sebelum bergantung pada retrieval segar.

Lihat juga

• Indeks referensi kesalahan
• Pemecahan masalah tanda tangan dan stempel waktu
• Pemecahan masalah: enkripsi dan izin
• Pemecahan masalah: font dan tagging
• Pemecahan masalah: validasi PDF/A dan PDF/UA