Ошибки среды выполнения и поддержки

Область применения

Эти записи описывают исключения, генерируемые слоем поддержки среды выполнения: политикой деградации, транспортом HTTP на базе cURL, предохранителем отказоустойчивости, эмиттером Security Information and Event Management (SIEM), манифестом рендеринга, инспекцией PDF и подсистемой хаос-инженерии.

Каждое исключение NextPDF наследуется от NextPdfException, который реализует ContextAwareExceptionInterface и предоставляет getContext(): array для структурированного диагностического логирования. Подкласс заполняет этот массив только тогда, когда переопределяет getContext(); базовый возвращает пустой массив. Три исключения на этой странице (DegradedException, CircuitBreakerOpenException и InspectException) наследуются от PHP-класса RuntimeException напрямую и раскрывают свои данные через публичные свойства readonly вместо getContext(). Каждая запись ниже называет точные свойства или ключи контекста, которые несёт класс, взятые из исходного кода.

Политика деградации

`DegradedException`

Генерируется, когда. Конвейер рендеринга встречает деградировавшую возможность, которая нарушает активную политику деградации. Под DegradationPolicy::Strict любая деградация высокого воздействия (ComplianceRisk, SemanticLoss или Blocking) генерирует его; под DegradationPolicy::Balanced его генерирует только воздействие Blocking.
Класс. Наследуется напрямую от RuntimeException (не от NextPdfException), поэтому он не несёт getContext().
Несомые данные. Два публичных свойства readonly: $capability ( объект-значение Capability, вызвавший отклонение, включая его id, status, reason, fallbackTarget и impact) и $policy ( политика DegradationPolicy, активная на момент отклонения). Сообщение имеет форму Feature "<id>" is <status>: <reason> (policy: <policy>).
Восстановление. Изучите $capability, чтобы определить отсутствующую возможность и её причину. Либо установите компонент, который требует возможность, примите конфигурацию более низкого воздействия, либо ослабьте политику с Strict до Balanced, когда деградация приемлема для сценария использования. Вызовите $capability->isAvailable() / isDegraded(), чтобы управлять сообщениями для пользователя.

Транспорт HTTP

Эти три исключения происходят из клиента PSR-18 на базе cURL и его декоратора с учётом безопасности. Первые два наследуются от NextPdfException, но не переопределяют getContext(), поэтому их getContext() возвращает пустой массив; диагностические данные достижимы через метод доступа PSR-18 getRequest() и связанное предыдущее throwable.

`CurlNetworkException`

Генерируется, когда. HTTP-запрос нельзя завершить из-за сбоя сетевого уровня: сбой разрешения Domain Name System (DNS), тайм-аут соединения или ошибка рукопожатия Transport Layer Security (TLS). Это также класс, который декоратор с учётом безопасности генерирует при отклонении по безопасности (отказ при Server-Side Request Forgery, отказ при DNS-rebinding или запрещённый редирект).
Класс. Реализует PSR-18 Psr\Http\Client\NetworkExceptionInterface.
Несомые данные. getRequest() возвращает сбойный RequestInterface. Исходная ошибка транспорта, когда присутствует, является связанным предыдущим throwable. getContext() возвращает пустой массив (базовое значение по умолчанию).
Восстановление. Сетевой сбой может быть временным — повторите с откатом, если запрос идемпотентен. Отклонение по безопасности не является временным и должно завершиться отказом: не повторяйте; вместо этого исправьте целевой URL или политику SSRF. Прочтите сообщение и предыдущее throwable, чтобы различить эти два случая.

`CurlRequestException`

Генерируется, когда. Сам запрос нельзя отправить, потому что он некорректен, например недопустимый URL или запрос, не прошедший проверку SSRF до любого сетевого вызова.
Класс. Реализует PSR-18 Psr\Http\Client\RequestExceptionInterface.
Несомые данные. getRequest() возвращает проблемный RequestInterface; базовая причина, когда присутствует, является связанным предыдущим throwable. getContext() возвращает пустой массив.
Восстановление. Это дефект ввода вызывающей стороны или политики, а не временный сбой. Не повторяйте без изменений. Исправьте URL запроса, заголовки или тело, или скорректируйте список разрешённых SSRF, если цель законно допустима, затем переотправьте запрос.

`TransientHttpException`

Генерируется, когда. Внутренне, внутри SecurityAwareHttpClient, чтобы пометить действительно временный сбой внутреннего транспорта (DNS, соединение или тайм-аут, сгенерированные внутренним клиентом PSR-18) как пригодный для ограниченного бюджета повторов. Это единственный пригодный для повтора класс, который распознаёт цикл повторов декоратора; необёрнутое исключение (отклонение по безопасности, сгенерированное декоратором) считается фатальным.
Класс. Реализует PSR-18 Psr\Http\Client\NetworkExceptionInterface. Помечен @internal — он создаётся и разворачивается полностью внутри SecurityAwareHttpClient и никогда не покидает декоратор.
Несомые данные. getRequest() возвращает сбойный запрос. Исходное ClientExceptionInterface внутреннего транспорта сохраняется как связанное предыдущее throwable (getPrevious()) и переподаётся дословно вызывающей стороне, как только бюджет повторов исчерпан, поэтому публичный контракт PSR-18 не изменяется. getContext() возвращает пустой массив.
Восстановление. Код приложения не перехватывает этот тип напрямую. Перехватывайте переподанное внутреннее исключение, которое декоратор возвращает после исчерпания бюджета повторов, и считайте повторяющиеся временные сбои проблемой доступности выше по потоку.

Отказоустойчивость

`CircuitBreakerOpenException`

Генерируется, когда. CircuitBreaker в состоянии CircuitBreakerState::Open отклоняет вызов с быстрым отказом, до любого вызова ниже по потоку. Он существует, чтобы вызывающие стороны могли отличить «удалённая служба сейчас недоступна» ( временный сбой транспорта, который стоит деградировать) от «пул соединений был бы исчерпан этим вызовом» (быстрый отказ, сеть не задействована) — смягчение пакетного отказа в обслуживании (DoS), требуемое для клиентов Public Key Infrastructure (PKI).
Класс. Наследуется напрямую от RuntimeException, поэтому он не несёт getContext().
Несомые данные. Два публичных свойства readonly: $breakerName ( идентификатор открытого предохранителя) и $secondsUntilHalfOpen (приблизительное оставшееся время остывания до перехода предохранителя в полуоткрытое состояние). Сообщение имеет форму Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
Восстановление. Не долбите предохранитель — подождите как минимум $secondsUntilHalfOpen перед повтором или деградируйте операцию. Сетевой вызов не предпринимался, поэтому это не свидетельство того, что сама удалённая служба дала сбой; это противодавление, защищающее пул соединений.

Наблюдаемость

`SiemEmitterException`

Генерируется, когда. Эмиттер событий SIEM не может сохранить или связать запись. Он выявляет сбои уровня файловой системы (open, lock, seek, write, fflush, read) и сбои целостности хеш-цепочки (chain: индекс не по порядку, некорректная хвостовая запись или дрейф при JSON-обороте), общие для журнала событий хеш-цепочки и адаптеров эмиттера файла JSON-lines.
Класс. Наследуется от 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`

Генерируется, когда. 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`

Генерируется, когда. Инспекция PDF завершается сбоем.
Класс. Наследуется напрямую от RuntimeException (не от NextPdfException), поэтому он не несёт getContext().
Несомые данные. Два публичных свойства readonly: $inspectCode ( машиночитаемый код в пространстве имён INSPECT-*) и $retryable ( булево значение, указывающее, должна ли вызывающая сторона повторить — например, когда сопроводитель инспекции временно недоступен). Исходная причина, когда присутствует, является связанным предыдущим throwable.
Восстановление. Ветвитесь по $inspectCode для конкретного класса сбоя. Когда $retryable равно true, повторите с откатом, потому что сбой ожидаемо временный (например перезапуск сопроводителя); когда false, считайте ввод или конфигурацию дефектом и не повторяйте без изменений.

Хаос-инженерия

`ChaosReportWriteException`

Генерируется, когда. ChaosScenarioRunner::writeReport() не может сохранить агрегированный отчёт о дне хаоса на диск. Это типизированная по домену замена обобщённой ошибки среды выполнения, поэтому вызывающие стороны могут перехватить конкретный сбой записи отчёта на диск без смешивания его с ошибками, сгенерированными внутри самих симуляторов сценариев (раннер фиксирует их как поля ChaosOutcome).
Класс. Наследуется от NextPdfException и переопределяет getContext().
Ключи контекста. output_path (абсолютный путь, по которому раннер пытался записать). Он также достижим через getOutputPath(). Сообщение имеет форму ChaosScenarioRunner: failed to write report to "<path>".
Восстановление. Это сбой на стороне записи приёмника отчёта, а не сценариев. Проверьте, что выходной каталог существует и доступен для записи и что место на диске доступно, затем повторно запустите запись отчёта. Сами результаты хаоса не затронуты.

`RetrievalUnavailableException`

Генерируется, когда. Конечная точка извлечения (например, служба Retrieval Augmented Generation Voyage) недоступна, и система либо откатывается к режиму только кеша, либо завершается отказом.
Класс. Наследуется от NextPdfException и переопределяет getContext().
Ключи контекста. mode (режим работы после сбоя — CACHED_ONLY, когда результаты обслуживаются только из семантического кеша, или FAIL_CLOSED, когда запрос полностью отклонён без устаревших данных) и endpoint (конечная точка, ставшая недоступной). Они также достижимы через getMode() и getEndpoint(). Сообщение имеет форму Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
Восстановление. Прочтите mode, чтобы узнать, как деградировала система. Под CACHED_ONLY результаты могут быть устаревшими; обновите их, когда конечная точка восстановится. Под FAIL_CLOSED запрос был отклонён по замыслу и должен быть повторён после того, как конечная точка станет доступной. Восстановите связность конечной точки (сеть, учётные данные, работоспособность службы) перед тем, как полагаться на свежее извлечение.

Ошибки среды выполнения и поддержки

Область применения

Политика деградации

DegradedException

Транспорт HTTP

CurlNetworkException

CurlRequestException

TransientHttpException

Отказоустойчивость

CircuitBreakerOpenException