Błędy środowiska wykonawczego i wsparcia

Zakres

Te wpisy dokumentują wyjątki zgłaszane przez warstwę wsparcia środowiska wykonawczego: politykę degradacji, transport HTTP oparty na cURL, wyłącznik obwodu odporności, emiter Security Information and Event Management (SIEM), manifest renderowania, inspekcję PDF oraz podsystem inżynierii chaosu.

Większość wyjątków NextPDF rozszerza NextPdfException, który implementuje ContextAwareExceptionInterface i udostępnia getContext(): array do ustrukturyzowanego logowania diagnostycznego. Podklasa wypełnia tę tablicę tylko wtedy, gdy nadpisuje getContext(); baza zwraca pustą tablicę. Trzy wyjątki na tej stronie (DegradedException, CircuitBreakerOpenException oraz InspectException) rozszerzają RuntimeException PHP bezpośrednio i udostępniają swoje dane przez publiczne właściwości readonly zamiast getContext(). Każdy wpis poniżej podaje dokładne właściwości lub klucze kontekstu, które dana klasa niesie, zaczerpnięte ze źródła.

Polityka degradacji

DegradedException

• Zgłaszany, gdy. Potok renderowania napotyka zdegradowaną możliwość, która narusza aktywną politykę degradacji. W trybie DegradationPolicy::Strict każda degradacja o dużym wpływie (ComplianceRisk, SemanticLoss lub Blocking) go zgłasza; w trybie DegradationPolicy::Balanced zgłasza go tylko wpływ Blocking.
• Klasa. Rozszerza RuntimeException bezpośrednio (a nie NextPdfException), więc nie niesie getContext().
• Niesione dane. Dwie publiczne właściwości readonly: $capability (obiekt wartości Capability, który wyzwolił odrzucenie, w tym jego id, status, reason, fallbackTarget oraz impact) i $policy (polityka DegradationPolicy aktywna w chwili odrzucenia). Komunikat ma postać Feature "<id>" is <status>: <reason> (policy: <policy>).
• Naprawa. Sprawdź $capability, aby zidentyfikować brakującą funkcję i jej przyczynę. Albo zainstaluj komponent, którego ta możliwość wymaga, zaakceptuj konfigurację o mniejszym wpływie, albo złagodź politykę ze Strict na Balanced, gdy degradacja jest akceptowalna dla danego zastosowania. Wywołaj $capability->isAvailable() / isDegraded(), aby sterować komunikatami dla użytkownika.

Transport HTTP

Te trzy wyjątki pochodzą z klienta PSR-18 opartego na cURL oraz jego dekoratora świadomego bezpieczeństwa. Pierwsze dwa rozszerzają NextPdfException, ale nie nadpisują getContext(), więc ich getContext() zwraca pustą tablicę; dane diagnostyczne są osiągalne przez akcesor PSR-18 getRequest() oraz powiązany poprzedni throwable.

CurlNetworkException

• Zgłaszany, gdy. Żądania HTTP nie da się ukończyć z powodu błędu na poziomie sieci: awaria rozwiązywania Domain Name System (DNS), przekroczenie limitu czasu połączenia lub błąd uzgadniania Transport Layer Security (TLS). To również klasa, którą dekorator świadomy bezpieczeństwa zgłasza w przypadku odrzucenia bezpieczeństwa (odmowa Server-Side Request Forgery, odmowa DNS-rebinding lub zablokowane przekierowanie).
• Klasa. Implementuje PSR-18 Psr\Http\Client\NetworkExceptionInterface.
• Niesione dane. getRequest() zwraca nieudane RequestInterface. Pierwotny błąd transportu, gdy obecny, jest powiązanym poprzednim throwable. getContext() zwraca pustą tablicę (wartość domyślną bazy).
• Naprawa. Błąd sieci może być przejściowy — ponów z wycofaniem, jeśli żądanie jest idempotentne. Odrzucenie bezpieczeństwa nie jest przejściowe i musi zadziałać w trybie fail-closed: nie ponawiaj; popraw zamiast tego docelowy URL lub politykę SSRF. Odczytaj komunikat i poprzedni throwable, aby odróżnić te dwa przypadki.

CurlRequestException

• Zgłaszany, gdy. Samego żądania nie da się wysłać, ponieważ jest źle sformowane, na przykład nieprawidłowy URL lub żądanie, które nie przeszło walidacji SSRF przed jakimkolwiek wywołaniem sieciowym.
• Klasa. Implementuje PSR-18 Psr\Http\Client\RequestExceptionInterface.
• Niesione dane. getRequest() zwraca problematyczne RequestInterface; bazowa przyczyna, gdy obecna, jest powiązanym poprzednim throwable. getContext() zwraca pustą tablicę.
• Naprawa. To defekt danych wejściowych wywołującego lub polityki, a nie błąd przejściowy. Nie ponawiaj bez zmian. Popraw URL żądania, nagłówki lub ciało albo dostosuj listę dozwolonych SSRF, jeśli cel jest zasadnie dozwolony, a następnie ponownie wyślij żądanie.

TransientHttpException

• Zgłaszany, gdy. Wewnętrznie, w obrębie SecurityAwareHttpClient, aby oznaczyć faktycznie przejściowy błąd wewnętrznego transportu (DNS, połączenie lub limit czasu zgłoszony przez wewnętrznego klienta PSR-18) jako kwalifikujący się do ograniczonego budżetu ponowień. To jedyna klasa kwalifikująca się do ponowienia, którą rozpoznaje pętla ponowień dekoratora; nieopakowany wyjątek (odrzucenie bezpieczeństwa zgłoszone przez dekorator) jest traktowany jako fatalny.
• Klasa. Implementuje PSR-18 Psr\Http\Client\NetworkExceptionInterface. Oznaczony jako @internal — jest tworzony i rozpakowywany całkowicie wewnątrz SecurityAwareHttpClient i nigdy nie wydostaje się z dekoratora.
• Niesione dane. getRequest() zwraca nieudane żądanie. Pierwotny ClientExceptionInterface wewnętrznego transportu jest zachowany jako powiązany poprzedni throwable (getPrevious()) i ponownie ujawniany wywołującemu dosłownie po wyczerpaniu budżetu ponowień, więc publiczny kontrakt PSR-18 jest niezmieniony. getContext() zwraca pustą tablicę.
• Naprawa. Kod aplikacji nie przechwytuje tego typu bezpośrednio. Przechwyć ponownie ujawniony wewnętrzny wyjątek, który dekorator zwraca po wyczerpaniu budżetu ponowień, i potraktuj powtarzające się awarie przejściowe jako nadrzędny problem dostępności.

Odporność

CircuitBreakerOpenException

• Zgłaszany, gdy. CircuitBreaker w stanie CircuitBreakerState::Open odrzuca wywołanie szybko-i-bez-czekania (fail-fast), przed jakimkolwiek wywołaniem downstream. Istnieje po to, by wywołujący odróżniali „zdalna usługa jest teraz nieosiągalna” (przejściowy błąd transportu, wart degradacji) od „pula połączeń zostałaby wyczerpana przez to wywołanie” (fail-fast, bez próby sieciowej) — ograniczanie wsadowego ataku odmowy usługi wymagane dla klientów Public Key Infrastructure (PKI).
• Klasa. Rozszerza RuntimeException bezpośrednio, więc nie niesie getContext().
• Niesione dane. Dwie publiczne właściwości readonly: $breakerName (identyfikator otwartego wyłącznika) oraz $secondsUntilHalfOpen (przybliżony pozostały czas schłodzenia, zanim wyłącznik przejdzie w stan half-open). Komunikat ma postać Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
• Naprawa. Nie nękaj wyłącznika — poczekaj co najmniej $secondsUntilHalfOpen przed ponowieniem albo zdegraduj operację. Żadne wywołanie sieciowe nie zostało podjęte, więc nie jest to dowód, że sama zdalna usługa zawiodła; to przeciwciśnienie chroniące pulę połączeń.

Obserwowalność

SiemEmitterException

• Zgłaszany, gdy. Emiter zdarzeń SIEM nie może utrwalić ani połączyć rekordu. Ujawnia awarie na poziomie systemu plików (open, lock, seek, write, fflush, read) oraz błędy integralności łańcucha haszującego (chain: indeks poza kolejnością, źle sformowany rekord końcowy lub dryf cyklu JSON) współdzielone przez dziennik zdarzeń z łańcuchem haszującym oraz adaptery emitera plików JSON-lines.
• Klasa. Rozszerza NextPdfException i nadpisuje getContext().
• Klucze kontekstu. operation (jedno z open, lock, seek, write, fflush, read, chain), path (docelowa ścieżka dziennika) oraz detail (czytelny dla człowieka szczegół, taki jak liczba bajtów lub oczekiwany-wobec-rzeczywistego indeks). Są one również osiągalne przez getOperation(), getPath() oraz getDetail(). Komunikat ma postać SIEM emitter <operation> failed for <path>: <detail>.
• Naprawa. To jest możliwe do obsłużenia przez infrastrukturę lub SecOps, a nie przez logikę aplikacji. Zweryfikuj montowanie woluminu dziennika, uprawnienia katalogu, dostępne deskryptory plików oraz kondycję systemu plików. Awaria operacji chain wskazuje sygnał manipulacji lub uszkodzenia w dzienniku audytu i należy ją zbadać, a nie po cichu ponawiać.

Manifest renderowania

RenderManifestException

• Zgłaszany, gdy. RenderManifest nie może zostać skonstruowany, zdeserializowany ani odczytany z powodu błędu strukturalnego, typu lub zgodności schematu. Manifest jest wersjonowanym kontraktem publicznym przesyłanym przez każdy transport (CLI, kolejka Laravel, Symfony, API SaaS), więc źle sformowany lub niezgodny manifest jest ujawniany bezpośrednio, a nie sprowadzany do wartości domyślnych.
• Klasa. Rozszerza NextPdfException i nadpisuje getContext(). Nazwane konstruktory ustawiają stabilny, czytelny maszynowo kod w przestrzeni nazw SPEC-MANIFEST-*:
  • RenderManifestException::shape() → SPEC-MANIFEST-001 — błąd kształtu lub typu podczas RenderManifest::fromArray().
  • RenderManifestException::incompatibleVersion() → SPEC-MANIFEST-002 — niezgodna główna wersja schematu (nie da się odczytać).
  • RenderManifestException::missingField() → SPEC-MANIFEST-003 — brakujące wymagane pole podczas finalizacji w builderze.
  • RenderManifestException::unsupported() → SPEC-MANIFEST-004 — poprawnie sformowany manifest odwołuje się do danych wejściowych lub szablonu, których bieżący mechanizm renderujący nie może rozwiązać (na przykład dane wejściowe URI lub silnik szablonów tylko po stronie hosta).
• Klucze kontekstu. manifest_code (identyfikator SPEC-MANIFEST-*) oraz reason (czytelny dla człowieka opis awarii). Są one również osiągalne przez getManifestCode() oraz getReason(). Komunikat ma postać [<code>] <reason>.
• Naprawa. Rozgałęziaj logikę na manifest_code. Dla SPEC-MANIFEST-001 i SPEC-MANIFEST-003 popraw ładunek manifestu (popraw typ pola lub dostarcz brakujące pole). Dla SPEC-MANIFEST-002 wygeneruj manifest ponownie względem obsługiwanej głównej wersji schematu albo zaktualizuj mechanizm renderujący. Dla SPEC-MANIFEST-004 dostarcz dane wejściowe lub silnik szablonów, które bieżąca edycja może rozwiązać.

Inspekcja

InspectException

• Zgłaszany, gdy. Inspekcja PDF się nie powiedzie.
• Klasa. Rozszerza RuntimeException bezpośrednio (a nie NextPdfException), więc nie niesie getContext().
• Niesione dane. Dwie publiczne właściwości readonly: $inspectCode (kod czytelny maszynowo w przestrzeni nazw INSPECT-*) oraz $retryable (wartość logiczna wskazująca, czy wywołujący powinien ponowić — na przykład gdy pomocniczy proces inspekcji (sidecar) jest chwilowo wyłączony). Pierwotna przyczyna, gdy obecna, jest powiązanym poprzednim throwable.
• Naprawa. Rozgałęziaj logikę na $inspectCode w celu określenia konkretnej klasy awarii. Gdy $retryable jest true, ponów z wycofaniem, ponieważ awaria spodziewana jest jako przejściowa (taka jak restart sidecara); gdy false, potraktuj dane wejściowe lub konfigurację jako defekt i nie ponawiaj bez zmian.

Inżynieria chaosu

ChaosReportWriteException

• Zgłaszany, gdy. ChaosScenarioRunner::writeReport() nie może utrwalić zagregowanego raportu dnia chaosu na dysku. To zastępnik typu domenowego dla generycznego błędu środowiska wykonawczego, aby wywołujący mogli przechwycić konkretną awarię zapisu raportu bez mylenia jej z błędami zgłoszonymi wewnątrz samych symulatorów scenariuszy (runner przechwytuje je jako pola ChaosOutcome).
• Klasa. Rozszerza NextPdfException i nadpisuje getContext().
• Klucze kontekstu. output_path (bezwzględna ścieżka, do której runner próbował zapisać). Jest również osiągalna przez getOutputPath(). Komunikat ma postać ChaosScenarioRunner: failed to write report to "<path>".
• Naprawa. To awaria po stronie zapisu odbiornika raportu, a nie scenariuszy. Zweryfikuj, że katalog wyjściowy istnieje i jest zapisywalny oraz że jest dostępne miejsce na dysku, a następnie ponownie uruchom zapis raportu. Same wyniki chaosu są niezmienione.

RetrievalUnavailableException

• Zgłaszany, gdy. Punkt końcowy pobierania (na przykład usługa Voyage Retrieval Augmented Generation) jest niedostępny, a system albo cofa się do trybu tylko z pamięci podręcznej, albo działa w trybie fail-closed.
• Klasa. Rozszerza NextPdfException i nadpisuje getContext().
• Klucze kontekstu. mode (tryb działania po awarii — CACHED_ONLY, gdy wyniki są serwowane wyłącznie z pamięci podręcznej semantycznej, lub FAIL_CLOSED, gdy żądanie zostaje odmówione całkowicie bez przestarzałych danych) oraz endpoint (punkt końcowy, który stał się nieosiągalny). Są one również osiągalne przez getMode() oraz getEndpoint(). Komunikat ma postać Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
• Naprawa. Odczytaj mode, aby dowiedzieć się, jak system się zdegradował. W trybie CACHED_ONLY wyniki mogą być przestarzałe; odśwież po wyzdrowieniu punktu końcowego. W trybie FAIL_CLOSED żądanie zostało odmówione z założenia i musi zostać ponowione po osiągalności punktu końcowego. Przywróć łączność punktu końcowego (sieć, poświadczenia, kondycja usługi), zanim zaczniesz polegać na świeżym pobieraniu.

Zobacz także

• Indeks dokumentacji błędów
• Rozwiązywanie problemów z podpisami i znacznikami czasu
• Rozwiązywanie problemów: szyfrowanie i uprawnienia
• Rozwiązywanie problemów: czcionki i tagowanie
• Rozwiązywanie problemów: walidacja PDF/A i PDF/UA