pub struct Failure { /* private fields */ }Expand description
A failure on its way to the client: status, stable code, public message, internal detail, kind and headers.
Renderers read the message only through Failure::public_message, which
is fixed for every 5xx.
§Examples
use davidrs::http::{Failure, StatusCode, INTERNAL_MESSAGE};
let refused = Failure::new(StatusCode::CONFLICT, "ERROR_ORDER_CLOSED", "The order is closed");
assert_eq!(refused.public_message(), "The order is closed");
let broken = Failure::new(StatusCode::BAD_GATEWAY, "FAULT_UPSTREAM", "connect 10.0.0.7 refused");
assert_eq!(broken.public_message(), INTERNAL_MESSAGE);
assert!(broken.internal_detail().contains("10.0.0.7"));Implementations§
Source§impl Failure
impl Failure
Sourcepub fn new(
status: StatusCode,
code: &'static str,
message: impl Into<String>,
) -> Self
pub fn new( status: StatusCode, code: &'static str, message: impl Into<String>, ) -> Self
A failure with an explicit status and a client-safe message.
A 5xx status discards message at render time; put anything
diagnostic in Failure::with_detail instead of the message.
Sourcepub fn internal(code: &'static str, detail: impl Into<String>) -> Self
pub fn internal(code: &'static str, detail: impl Into<String>) -> Self
A 500 whose detail is kept for diagnostics and never rendered.
Sourcepub fn from_error(code: &'static str, error: &dyn Error) -> Self
pub fn from_error(code: &'static str, error: &dyn Error) -> Self
A 500 built from an error, keeping its whole source chain as the
detail.
Sourcepub fn with_detail(self, detail: impl Into<String>) -> Self
pub fn with_detail(self, detail: impl Into<String>) -> Self
Attaches internal diagnostic text, never rendered.
Sourcepub fn with_kind(self, kind: FailureKind) -> Self
pub fn with_kind(self, kind: FailureKind) -> Self
Records where the failure came from.
Sourcepub fn with_header(self, name: &str, value: &str) -> Self
pub fn with_header(self, name: &str, value: &str) -> Self
Adds a response header that survives rendering.
It replaces a header of the same name the renderer sets. Adding a name
again keeps every value, as set-cookie needs.
An invalid name or value is dropped rather than panicking: a malformed
header must not turn a 429 into a crash.
Sourcepub fn with_headers<I, K, V>(self, headers: I) -> Self
pub fn with_headers<I, K, V>(self, headers: I) -> Self
Adds several response headers, dropping invalid ones as
Failure::with_header does.
Sourcepub fn status(&self) -> StatusCode
pub fn status(&self) -> StatusCode
The status that will be rendered.
Sourcepub fn kind(&self) -> FailureKind
pub fn kind(&self) -> FailureKind
Where the failure came from.
Sourcepub fn headers(&self) -> &[(HeaderName, HeaderValue)]
pub fn headers(&self) -> &[(HeaderName, HeaderValue)]
The headers a renderer puts on the response.
Sourcepub fn public_message(&self) -> &str
pub fn public_message(&self) -> &str
The message a client may see: the message for a 4xx, and
INTERNAL_MESSAGE for every 5xx however the failure was built.
Renderers must use this accessor for client-visible text.
internal_detail and Debug are diagnostic only.
Sourcepub fn internal_detail(&self) -> String
pub fn internal_detail(&self) -> String
The unredacted message and the detail joined as message: detail, for
a deliberate diagnostic. The message is left out when it is empty or
INTERNAL_MESSAGE.
Never put this in a response.
Sourcepub fn is_server_error(&self) -> bool
pub fn is_server_error(&self) -> bool
Whether the status is a 5xx, the failures worth logging at error level.
Trait Implementations§
impl Eq for Failure
Source§impl Error for Failure
impl Error for Failure
1.30.0 · Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()
Source§impl From<RuntimeError> for Failure
A 500 whose detail is the error’s source chain: ERROR_TIMEOUT with kind
FailureKind::Deadline for a deadline, ERROR_LIMIT_EXCEEDED for a
bounded limit, FAULT_UNHANDLED for anything else.
impl From<RuntimeError> for Failure
A 500 whose detail is the error’s source chain: ERROR_TIMEOUT with kind
FailureKind::Deadline for a deadline, ERROR_LIMIT_EXCEEDED for a
bounded limit, FAULT_UNHANDLED for anything else.
Source§fn from(error: RuntimeError) -> Self
fn from(error: RuntimeError) -> Self
impl StructuralPartialEq for Failure
Auto Trait Implementations§
impl Freeze for Failure
impl RefUnwindSafe for Failure
impl Send for Failure
impl Sync for Failure
impl Unpin for Failure
impl UnsafeUnpin for Failure
impl UnwindSafe for Failure
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key and return true if they are equal.Source§impl<T> FutureExt for T
impl<T> FutureExt for T
Source§fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
Source§fn with_current_context(self) -> WithContext<Self> ⓘ
fn with_current_context(self) -> WithContext<Self> ⓘ
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§impl<T, O> Matches<O> for Twhere
T: PartialEq<O>,
impl<T, O> Matches<O> for Twhere
T: PartialEq<O>,
fn validate_matches(&self, other: &O) -> bool
Source§impl<T> Pointable for T
impl<T> Pointable for T
Source§impl<T> PolicyExt for Twhere
T: ?Sized,
impl<T> PolicyExt for Twhere
T: ?Sized,
impl<T> Read<Exclusive, BecauseExclusive> for Twhere
T: ?Sized,
Source§impl<T> Requirement<T> for T
impl<T> Requirement<T> for T
Source§impl<T> ToCompactString for Twhere
T: Display,
impl<T> ToCompactString for Twhere
T: Display,
Source§fn try_to_compact_string(&self) -> Result<CompactString, ToCompactStringError>
fn try_to_compact_string(&self) -> Result<CompactString, ToCompactStringError>
ToCompactString::to_compact_string() Read moreSource§fn to_compact_string(&self) -> CompactString
fn to_compact_string(&self) -> CompactString
CompactString. Read more