watermelon_proto/
status_code.rs

1use core::{
2    fmt::{self, Display, Formatter},
3    num::NonZero,
4    str::FromStr,
5};
6
7use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
8
9use crate::util;
10
11/// A NATS status code
12///
13/// Constants are provided for known and accurately status codes
14/// within the NATS Server.
15///
16/// Values are guaranteed to be in range `100..1000`.
17#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
18pub struct StatusCode(NonZero<u16>);
19
20impl StatusCode {
21    /// The Jetstream consumer hearthbeat timeout has been reached with no new messages to deliver
22    ///
23    /// See [ADR-9].
24    ///
25    /// [ADR-9]: https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-9.md
26    pub const IDLE_HEARTBEAT: StatusCode = Self::new_internal(100);
27    /// The request has successfully been sent
28    pub const OK: StatusCode = Self::new_internal(200);
29    /// The requested Jetstream resource doesn't exist
30    pub const NOT_FOUND: StatusCode = Self::new_internal(404);
31    /// The pull consumer batch reached the timeout
32    pub const TIMEOUT: StatusCode = Self::new_internal(408);
33    /// The request was sent to a subject that does not appear to have any subscribers listening
34    pub const NO_RESPONDERS: StatusCode = Self::new_internal(503);
35
36    /// Decodes a status code from a slice of ASCII characters.
37    ///
38    /// The ASCII representation is expected to be in the form of `"NNN"`, where `N` is a numeric
39    /// digit.
40    ///
41    /// # Errors
42    ///
43    /// It returns an error if the slice of bytes does not contain a valid status code.
44    pub fn from_ascii_bytes(buf: &[u8]) -> Result<Self, StatusCodeError> {
45        if buf.len() != 3 {
46            return Err(StatusCodeError);
47        }
48
49        util::parse_u16(buf)
50            .map_err(|_| StatusCodeError)?
51            .try_into()
52            .map(Self)
53            .map_err(|_| StatusCodeError)
54    }
55
56    const fn new_internal(val: u16) -> Self {
57        Self(NonZero::new(val).unwrap())
58    }
59}
60
61impl FromStr for StatusCode {
62    type Err = StatusCodeError;
63
64    fn from_str(s: &str) -> Result<Self, Self::Err> {
65        Self::from_ascii_bytes(s.as_bytes())
66    }
67}
68
69impl Display for StatusCode {
70    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
71        Display::fmt(&self.0, f)
72    }
73}
74
75impl TryFrom<u16> for StatusCode {
76    type Error = StatusCodeError;
77
78    fn try_from(value: u16) -> Result<Self, Self::Error> {
79        if (100..1000).contains(&value) {
80            Ok(Self(NonZero::new(value).unwrap()))
81        } else {
82            Err(StatusCodeError)
83        }
84    }
85}
86
87impl From<StatusCode> for u16 {
88    fn from(value: StatusCode) -> Self {
89        value.0.get()
90    }
91}
92
93impl Serialize for StatusCode {
94    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
95        u16::from(*self).serialize(serializer)
96    }
97}
98
99impl<'de> Deserialize<'de> for StatusCode {
100    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
101        let n = u16::deserialize(deserializer)?;
102        n.try_into().map_err(de::Error::custom)
103    }
104}
105
106/// An error encountered while parsing [`StatusCode`]
107#[derive(Debug, thiserror::Error)]
108#[non_exhaustive]
109#[error("invalid status code")]
110pub struct StatusCodeError;
111
112#[cfg(test)]
113mod tests {
114    use alloc::string::ToString;
115
116    use claims::assert_err;
117
118    use super::StatusCode;
119
120    #[test]
121    fn valid_status_codes() {
122        let status_codes = [100, 200, 404, 408, 409, 503];
123
124        for status_code in status_codes {
125            assert_eq!(
126                status_code,
127                u16::from(StatusCode::try_from(status_code).unwrap())
128            );
129
130            let s = status_code.to_string();
131            assert_eq!(
132                status_code,
133                u16::from(StatusCode::from_ascii_bytes(s.as_bytes()).unwrap())
134            );
135        }
136    }
137
138    #[test]
139    fn invalid_status_codes() {
140        let status_codes = [0, 5, 55, 9999];
141
142        for status_code in status_codes {
143            assert_err!(StatusCode::try_from(status_code));
144
145            let s = status_code.to_string();
146            assert_err!(StatusCode::from_ascii_bytes(s.as_bytes()));
147        }
148    }
149}
watermelon_proto/status_code.rs

watermelon_proto/
status_code.rs
