failure-mapping.md

Failure Mapping

HTTPKernel uses explicit failure mapping rather than a single untyped error path.

Default Mapper

The package currently ships:

• LiquidRazor\HttpKernel\Lib\Runtime\DefaultHttpFailureMapper

It maps package-level failures to:

• HttpResponseInterface
• HttpTransportOutput
• TransportStatus

Current Mappings

Request Rejection

These currently map to HTTP 400 and TransportStatus::Rejected:

• HttpRequestAdaptationFailed
• HttpRequestBodyNormalizationFailed

Execution Or Internal Failure

These currently map to HTTP 500 and TransportStatus::Failed:

• InvalidHttpHandlerResult
• HttpExecutionFailed
• HttpResponseEmissionFailed
• generic HttpKernelException
• unknown Throwable

Metadata Preservation

Mapped outputs preserve explicit failure metadata, including:

• http_kernel.failure_key
• http_kernel.failure_class
• http_kernel.failure_message
• http_kernel.http_status_code
• http_kernel.http_reason_phrase
• http_kernel.transport_status

Existing transport context metadata is preserved alongside the mapped failure metadata.

Transport Status And HTTP Status

HTTP status and transport status remain separate.

For example:

• HTTP 404 can still be wrapped in TransportStatus::Success
• a mapped transport failure can still carry a valid HTTP response object

That separation is preserved by the response finalizer and emitter boundary.