Skip to main content

Crate diagprint_axum

Crate diagprint_axum 

Source
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§

AsyncDiagnosticSink
Bounded asynchronous front-end for a synchronous DiagnosticSink.
AsyncDiagnosticState
Cloneable application-level state for bounded asynchronous diagnostic submission.
AsyncEmission
A value paired with the result of one asynchronous diagnostic submission.
ClientErrorBody
Privacy-filtered diagnostic information returned to an HTTP client.
ClientErrorEnvelope
JSON envelope returned to an HTTP client.
DiagnosticResponse
Axum HTTP response backed by one structured diagprint diagnostic.
DiagnosticState
Cloneable application-level diagnostic state for Axum handlers.
Emission
A value paired with the result of an explicit diagnostic emission attempt.
InvalidRequestId
Error returned when a request ID does not satisfy the correlation-ID contract.
MissingRequestContext
Error returned when a handler requests RequestContext without the request-correlation middleware having established one.
ProblemDetails
RFC 9457 Problem Details JSON document.
ProblemDetailsPolicy
Policy controlling the RFC 9457 representation of a diagnostic response.
ProblemDetailsResponse
Axum response that renders a DiagnosticResponse as RFC 9457 Problem Details.
ReportSubmitError
RequestContext
Privacy-safe HTTP request context attached by request_context_middleware.
RequestId
Validated request-level correlation identifier.
ResponsePolicy
Policy controlling which diagnostic information may cross the HTTP response boundary.
SubmissionSummary

Enums§

AsyncEmissionOutcome
Result of one explicit asynchronous diagnostic submission attempt.
AsyncSinkError
BackpressurePolicy
Behavior when the bounded delivery queue reaches capacity.
EmissionOutcome
Result of an explicit diagnostic emission attempt.
ProblemExtensionError
Error returned when an RFC 9457 extension member cannot be added.
RejectionKind
Broad extractor-rejection category represented by a diagnostic.
SubmitOutcome

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§

ApplicationError
Application/domain error that can be adapted into diagprint HTTP responses.
ApplicationErrorExt
Convenience adapters available to every ApplicationError.
ApplicationResultExt
Explicit synchronous diagnostic emission for application/domain results.
AsyncApplicationResultExt
Explicit bounded asynchronous diagnostic submission for application/domain results.
AsyncDiagnosticEmissionExt
Explicit asynchronous diagnostic submission for diagprint and diagprint-axum values.
AxumRejectionExt
Converts supported Axum extractor rejections into structured diagnostics.
DiagnosticEmissionExt
Explicit diagnostic emission for diagprint and diagprint-axum values.
DiagnosticResponseExt
Convenience conversion from a diagnostic into an HTTP response.
ProblemDetailsResponseExt
Extension trait for converting an existing DiagnosticResponse into an RFC 9457 response.

Functions§

request_context_middleware
Axum middleware that establishes privacy-safe request correlation.

Type Aliases§

AsyncEmittedProblemResult
Handler result whose error side contains an explicit bounded asynchronous Problem Details submission outcome.
DiagnosticResult
Handler result whose error side is a privacy-safe diagnostic response.
EmittedProblemResult
Handler result whose error side is an explicitly emitted RFC 9457 Problem Details response.