reliar-core 0.3.0

Pure envelope/message model shared by every Reliar crate — no storage or transport dependency.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

//! Transport mapping abstraction (ADR 0004). Implemented by transport crates such as
//! `reliar-transport-nats`, never by `reliar-core` itself.

use crate::SerializedEnvelope;

/// Converts a [`SerializedEnvelope`] to and from one transport's native message type `M`.
///
/// No implementation ships from `reliar-core` — a mapper's transport headers are a
/// **projection** of [`Metadata`](crate::Metadata), not a second source of truth (ADR 0004).
/// The reserved `reliar-*` header names a mapper writes are a public contract that every
/// transport crate follows so headers mean the same thing everywhere.
///
/// ```
/// use reliar_core::{EnvelopeMapper, SerializedEnvelope};
///
/// /// A toy in-memory transport message: just the raw body, no headers.
/// struct RawMessage(bytes::Bytes);
///
/// struct RawMapper;
///
/// #[derive(Debug)]
/// struct RawMapError;
/// impl core::fmt::Display for RawMapError {
///     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
///         f.write_str("cannot decode a bare payload back into an envelope")
///     }
/// }
/// impl std::error::Error for RawMapError {}
///
/// impl EnvelopeMapper<RawMessage> for RawMapper {
///     type Error = RawMapError;
///
///     fn encode(&self, envelope: &SerializedEnvelope) -> Result<RawMessage, Self::Error> {
///         Ok(RawMessage(envelope.body.clone()))
///     }
///
///     fn decode(&self, _message: RawMessage) -> Result<SerializedEnvelope, Self::Error> {
///         // A real mapper reads the envelope's metadata back from transport headers; this toy
///         // one has none to read, so decoding is always an error.
///         Err(RawMapError)
///     }
/// }
/// ```
pub trait EnvelopeMapper<M> {
    /// The mapper's own error type.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Encodes a canonical envelope into the transport's native message type.
    ///
    /// # Errors
    ///
    /// Returns `Self::Error` if the transport's native message type cannot represent the
    /// envelope (e.g. a field it cannot carry).
    ///
    /// ```
    /// use reliar_core::{Envelope, EnvelopeMapper, Message};
    /// # struct RawMessage(bytes::Bytes);
    /// # struct RawMapper;
    /// # #[derive(Debug)]
    /// # struct RawMapError;
    /// # impl core::fmt::Display for RawMapError {
    /// #     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { f.write_str("nope") }
    /// # }
    /// # impl std::error::Error for RawMapError {}
    /// # impl EnvelopeMapper<RawMessage> for RawMapper {
    /// #     type Error = RawMapError;
    /// #     fn encode(&self, envelope: &reliar_core::SerializedEnvelope) -> Result<RawMessage, Self::Error> {
    /// #         Ok(RawMessage(envelope.body.clone()))
    /// #     }
    /// #     fn decode(&self, _message: RawMessage) -> Result<reliar_core::SerializedEnvelope, Self::Error> {
    /// #         Err(RawMapError)
    /// #     }
    /// # }
    ///
    /// #[derive(serde::Serialize, serde::Deserialize)]
    /// struct Ping;
    /// impl Message for Ping {
    ///     const TYPE: &'static str = "ping";
    ///     const VERSION: u16 = 1;
    /// }
    ///
    /// let envelope = Envelope::builder(Ping)
    ///     .build()
    ///     .map_body(|_| bytes::Bytes::from_static(b"{}"));
    ///
    /// let wire = RawMapper.encode(&envelope)?;
    /// assert_eq!(wire.0.as_ref(), b"{}");
    /// # Ok::<(), RawMapError>(())
    /// ```
    fn encode(&self, envelope: &SerializedEnvelope) -> Result<M, Self::Error>;

    /// Decodes a transport message back into a canonical envelope.
    ///
    /// # Errors
    ///
    /// Returns `Self::Error` if the transport message cannot be decoded into a canonical
    /// envelope (a missing required framework header, or a malformed one).
    ///
    /// ```
    /// use reliar_core::EnvelopeMapper;
    /// # struct RawMessage(bytes::Bytes);
    /// # struct RawMapper;
    /// # #[derive(Debug)]
    /// # struct RawMapError;
    /// # impl core::fmt::Display for RawMapError {
    /// #     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { f.write_str("nope") }
    /// # }
    /// # impl std::error::Error for RawMapError {}
    /// # impl EnvelopeMapper<RawMessage> for RawMapper {
    /// #     type Error = RawMapError;
    /// #     fn encode(&self, envelope: &reliar_core::SerializedEnvelope) -> Result<RawMessage, Self::Error> {
    /// #         Ok(RawMessage(envelope.body.clone()))
    /// #     }
    /// #     fn decode(&self, _message: RawMessage) -> Result<reliar_core::SerializedEnvelope, Self::Error> {
    /// #         Err(RawMapError)
    /// #     }
    /// # }
    ///
    /// // This toy mapper has no headers to read back, so decoding is always an error.
    /// assert!(RawMapper.decode(RawMessage(bytes::Bytes::new())).is_err());
    /// ```
    fn decode(&self, message: M) -> Result<SerializedEnvelope, Self::Error>;
}