Expand description
Privacy-safe Axum integration for the diagprint diagnostics lifecycle.
diagprint-axum adapts structured diagnostics and Axum request failures
without adding Axum or an async runtime dependency to diagprint core.
§Explicit diagnostic emission
Response construction and HTTP adaptation remain side-effect free.
Applications that want sink delivery must opt in with
DiagnosticEmissionExt::emit_to.
Explicit emission performs one synchronous diagprint::DiagnosticSink::emit
attempt. It does not automatically flush, retry, queue, persist, or start
background work.
The sink receives the complete internal diagnostic while the HTTP response
continues to follow its existing privacy policy. Sink failures are retained
as EmissionOutcome::Failed response metadata and do not replace the HTTP
response.
§Application-state ergonomics
DiagnosticState groups a cloneable diagprint::Reporter with one
shared diagprint::DiagnosticSink for use in Axum application state.
Application errors can be converted into correlated Problem Details and
explicitly emitted with DiagnosticState::emit_problem.
This remains an explicit side effect. Storing a sink in application state does not cause responses, errors, or diagnostics to emit automatically.
§Handler result ergonomics
ApplicationResultExt::emit_problem converts Result<T, E> values whose
error implements ApplicationError into an EmittedProblemResult
while keeping synchronous emission explicit.
Ok(T) values pass through unchanged and perform no emission.
With async-delivery enabled,
AsyncApplicationResultExt::emit_problem_async provides the bounded async
counterpart. Queue acceptance remains distinct from completed delivery.
With async-delivery enabled, AsyncDiagnosticState groups a cloneable
diagprint::Reporter with one shared bounded
diagprint_async::AsyncDiagnosticSink.
AsyncDiagnosticState::emit_problem explicitly adapts an application
error into correlated Problem Details and submits the complete internal
diagnostic through the existing bounded async sink.
Queue ownership, backpressure, flush, and shutdown remain application lifecycle responsibilities.
An enqueued outcome means queue acceptance, not completed delivery.
§Optional asynchronous delivery
The async-delivery feature adds an explicit asynchronous submission bridge
backed by diagprint-async.
AsyncDiagnosticEmissionExt::emit_to_async submits one diagnostic through
an existing bounded diagprint_async::AsyncDiagnosticSink.
An Enqueued outcome means queue acceptance, not completed sink delivery.
Queue ownership, backpressure, flushing, and shutdown remain the
responsibility of diagprint-async and the application lifecycle.
The Axum adapter does not create a second queue, spawn a task per request, retry delivery, flush automatically, or shut the sink down.
The async-delivery feature is disabled by default. Without it,
diagprint-async is not part of the crate’s normal dependency graph.
HTTP responses are treated as an externalization boundary. Internal diagnostic messages and codes are therefore redacted by default.
Structs§
- Async
Diagnostic Sink - Bounded asynchronous front-end for a synchronous
DiagnosticSink. - Async
Diagnostic State - Cloneable application-level state for bounded asynchronous diagnostic submission.
- Async
Emission - A value paired with the result of one asynchronous diagnostic submission.
- Client
Error Body - Privacy-filtered diagnostic information returned to an HTTP client.
- Client
Error Envelope - JSON envelope returned to an HTTP client.
- Diagnostic
Response - Axum HTTP response backed by one structured diagprint diagnostic.
- Diagnostic
State - Cloneable application-level diagnostic state for Axum handlers.
- Emission
- A value paired with the result of an explicit diagnostic emission attempt.
- Invalid
Request Id - Error returned when a request ID does not satisfy the correlation-ID contract.
- Missing
Request Context - Error returned when a handler requests
RequestContextwithout the request-correlation middleware having established one. - Problem
Details - RFC 9457 Problem Details JSON document.
- Problem
Details Policy - Policy controlling the RFC 9457 representation of a diagnostic response.
- Problem
Details Response - Axum response that renders a
DiagnosticResponseas RFC 9457 Problem Details. - Report
Submit Error - Request
Context - Privacy-safe HTTP request context attached by
request_context_middleware. - Request
Id - Validated request-level correlation identifier.
- Response
Policy - Policy controlling which diagnostic information may cross the HTTP response boundary.
- Submission
Summary
Enums§
- Async
Emission Outcome - Result of one explicit asynchronous diagnostic submission attempt.
- Async
Sink Error - Backpressure
Policy - Behavior when the bounded delivery queue reaches capacity.
- Emission
Outcome - Result of an explicit diagnostic emission attempt.
- Problem
Extension Error - Error returned when an RFC 9457 extension member cannot be added.
- Rejection
Kind - Broad extractor-rejection category represented by a diagnostic.
- Submit
Outcome
Constants§
- ABOUT_
BLANK - RFC 9457 generic problem type.
- MAX_
REQUEST_ ID_ LEN - Maximum accepted length of an inbound request ID.
- PROBLEM_
JSON_ MEDIA_ TYPE - RFC 9457 media type for JSON Problem Details responses.
- REQUEST_
ID_ HEADER - HTTP header used for request-level correlation.
Traits§
- Application
Error - Application/domain error that can be adapted into diagprint HTTP responses.
- Application
Error Ext - Convenience adapters available to every
ApplicationError. - Application
Result Ext - Explicit synchronous diagnostic emission for application/domain results.
- Async
Application Result Ext - Explicit bounded asynchronous diagnostic submission for application/domain results.
- Async
Diagnostic Emission Ext - Explicit asynchronous diagnostic submission for diagprint and diagprint-axum values.
- Axum
Rejection Ext - Converts supported Axum extractor rejections into structured diagnostics.
- Diagnostic
Emission Ext - Explicit diagnostic emission for diagprint and diagprint-axum values.
- Diagnostic
Response Ext - Convenience conversion from a diagnostic into an HTTP response.
- Problem
Details Response Ext - Extension trait for converting an existing
DiagnosticResponseinto an RFC 9457 response.
Functions§
- request_
context_ middleware - Axum middleware that establishes privacy-safe request correlation.
Type Aliases§
- Async
Emitted Problem Result - Handler result whose error side contains an explicit bounded asynchronous Problem Details submission outcome.
- Diagnostic
Result - Handler result whose error side is a privacy-safe diagnostic response.
- Emitted
Problem Result - Handler result whose error side is an explicitly emitted RFC 9457 Problem Details response.