coap_message/
error.rs

1//! Traits for the errors of fallible operations
2//!
3//! This currently only contains traits for rendering onto a [`crate::MinimalWritableMessage`], as
4//! errors are expected to be simple, and ideally widely reusable both on systems that only provide
5//! `MinimalWritableMessage` and more powerful ones.
6//!
7//! Traits for rendering onto more powerful messages can be added on demand.
8
9use core::fmt::Debug;
10
11/// Indicates that an error type can be rendered into a CoAP response
12///
13/// The error may encode details as to what went wrong in the response. Implementors should be
14/// aware that this may leak information, but it is ultimately the responsibility of the
15/// application to decide which errors to pass on to the client, and which are to be filtered.
16///
17/// As rough guidance, it is generally expected that problems with the input would be represented
18/// in the error (for example, an error would indicate which option was not understood, or where in
19/// the payload parsing went wrong), but should not reveal details such as the local variables or a
20/// stack trace to unauthorized clients.
21///
22/// This error trait is most useful in CoAP servers, both for errors that occur during processing
23/// of the request and for errors that occur during preparation of the response.
24///
25/// In a CoAP client, it is less useful, as the error is likely to be handled internally and not
26/// rendered (which is why [core::fmt::Debug] is a common co-occurring requirement). The trait can
27/// still be useful to coerce both locally and remotely occurring errors into a consistent
28/// perspective, as long as care is taken to not to send users on the wrong debugging path. Client
29/// side errors should render in such a way that they can be sent to the origin client when
30/// implementing a proxy.
31///
32/// While not on its own depending on Debug, it is usually combined with it.
33pub trait RenderableOnMinimal {
34    /// Error to return when even the error rendering is unsuccessful (a "double error").
35    ///
36    /// This is generic over an Inner Error, because rendering may happen on any type of message,
37    /// each of which has its own write errors, so the total error often contains a message type
38    /// dependent error.
39    ///
40    /// For Renderables that do not have "own" errors (i.e. where the only reason rendering would
41    /// fail is if an operation on the MinimalWritableMessage fails), this can be set to `IE`. It
42    /// is recommended that the there is a conversion `From<IE>` `Into<Self::Error>`, as that
43    /// allows the [`Self::render()`] method to `?` out errors.
44    type Error<IE: RenderableOnMinimal + Debug>: RenderableOnMinimal + Debug;
45
46    /// Express the error in a CoAP response message
47    ///
48    /// The implementation should assume that the message is uninitialized, i.e., that it must set
49    /// the code, options and payload in sequence.
50    fn render<M: crate::MinimalWritableMessage>(
51        self,
52        message: &mut M,
53    ) -> Result<(), Self::Error<M::UnionError>>;
54}
coap_message/error.rs

coap_message/
error.rs
