commonware_sync/net/
mod.rs

1use bytes::{Buf, BufMut};
2use commonware_codec::{DecodeExt, Encode, EncodeSize, Error, Read, ReadExt, ReadRangeExt, Write};
3use std::mem::size_of;
4
5/// Maximum message size in bytes (10MB).
6pub const MAX_MESSAGE_SIZE: usize = 10 * 1024 * 1024;
7
8pub mod request_id;
9pub use request_id::RequestId;
10pub mod io;
11pub mod resolver;
12pub mod wire;
13pub use resolver::Resolver;
14
15/// A message that can be sent over the wire.
16pub(super) trait Message: Encode + DecodeExt<()> + Sized + Send + Sync + 'static {
17    fn request_id(&self) -> RequestId;
18}
19
20/// Error codes for protocol errors.
21#[derive(Debug, Clone)]
22pub enum ErrorCode {
23    /// Invalid request parameters.
24    InvalidRequest,
25    /// Database error occurred.
26    DatabaseError,
27    /// Network error occurred.
28    NetworkError,
29    /// Request timeout.
30    Timeout,
31    /// Internal server error.
32    InternalError,
33}
34
35impl Write for ErrorCode {
36    fn write(&self, buf: &mut impl BufMut) {
37        let discriminant = match self {
38            ErrorCode::InvalidRequest => 0u8,
39            ErrorCode::DatabaseError => 1u8,
40            ErrorCode::NetworkError => 2u8,
41            ErrorCode::Timeout => 3u8,
42            ErrorCode::InternalError => 4u8,
43        };
44        discriminant.write(buf);
45    }
46}
47
48impl EncodeSize for ErrorCode {
49    fn encode_size(&self) -> usize {
50        size_of::<u8>()
51    }
52}
53
54impl Read for ErrorCode {
55    type Cfg = ();
56
57    fn read_cfg(buf: &mut impl Buf, _: &()) -> Result<Self, Error> {
58        let discriminant = u8::read(buf)?;
59        match discriminant {
60            0 => Ok(ErrorCode::InvalidRequest),
61            1 => Ok(ErrorCode::DatabaseError),
62            2 => Ok(ErrorCode::NetworkError),
63            3 => Ok(ErrorCode::Timeout),
64            4 => Ok(ErrorCode::InternalError),
65            _ => Err(Error::InvalidEnum(discriminant)),
66        }
67    }
68}
69
70/// Error from the server.
71#[derive(Debug, Clone)]
72pub struct ErrorResponse {
73    /// Unique identifier matching the original request.
74    pub request_id: RequestId,
75    /// Error code.
76    pub error_code: ErrorCode,
77    /// Human-readable error message.
78    pub message: String,
79}
80
81impl Write for ErrorResponse {
82    fn write(&self, buf: &mut impl BufMut) {
83        self.request_id.write(buf);
84        self.error_code.write(buf);
85        self.message.as_bytes().to_vec().write(buf);
86    }
87}
88
89impl EncodeSize for ErrorResponse {
90    fn encode_size(&self) -> usize {
91        self.request_id.encode_size()
92            + self.error_code.encode_size()
93            + self.message.as_bytes().to_vec().encode_size()
94    }
95}
96
97impl Read for ErrorResponse {
98    type Cfg = ();
99
100    fn read_cfg(buf: &mut impl Buf, _: &()) -> Result<Self, Error> {
101        let request_id = RequestId::read_cfg(buf, &())?;
102        let error_code = ErrorCode::read(buf)?;
103        let message_bytes = Vec::<u8>::read_range(buf, 0..=MAX_MESSAGE_SIZE)?;
104        let message = String::from_utf8(message_bytes)
105            .map_err(|_| Error::Invalid("ErrorResponse", "invalid UTF-8 in message"))?;
106        Ok(Self {
107            request_id,
108            error_code,
109            message,
110        })
111    }
112}
113
114#[cfg(test)]
115mod tests {
116    use crate::net::{request_id::Generator, wire::GetOperationsRequest, ErrorCode};
117    use commonware_codec::{DecodeExt as _, Encode as _};
118    use commonware_utils::NZU64;
119
120    #[test]
121    fn test_error_code_roundtrip_serialization() {
122        let test_cases = vec![
123            ErrorCode::InvalidRequest,
124            ErrorCode::DatabaseError,
125            ErrorCode::NetworkError,
126            ErrorCode::Timeout,
127            ErrorCode::InternalError,
128        ];
129
130        for error_code in test_cases {
131            // Serialize
132            let encoded = error_code.encode().to_vec();
133
134            // Deserialize
135            let decoded = ErrorCode::decode(&encoded[..]).expect("Failed to decode ErrorCode");
136
137            // Verify they match
138            match (&error_code, &decoded) {
139                (ErrorCode::InvalidRequest, ErrorCode::InvalidRequest) => {}
140                (ErrorCode::DatabaseError, ErrorCode::DatabaseError) => {}
141                (ErrorCode::NetworkError, ErrorCode::NetworkError) => {}
142                (ErrorCode::Timeout, ErrorCode::Timeout) => {}
143                (ErrorCode::InternalError, ErrorCode::InternalError) => {}
144                _ => panic!("ErrorCode roundtrip failed: {error_code:?} != {decoded:?}"),
145            }
146        }
147    }
148
149    #[test]
150    fn test_get_operations_request_validation() {
151        // Valid request
152        let requester = Generator::new();
153        let request = GetOperationsRequest {
154            request_id: requester.next(),
155            size: 100,
156            start_loc: 10,
157            max_ops: NZU64!(50),
158        };
159        assert!(request.validate().is_ok());
160
161        // Invalid start_loc
162        let request = GetOperationsRequest {
163            request_id: requester.next(),
164            size: 100,
165            start_loc: 100,
166            max_ops: NZU64!(50),
167        };
168        assert!(matches!(
169            request.validate(),
170            Err(crate::Error::InvalidRequest(_))
171        ));
172
173        // start_loc beyond size
174        let request = GetOperationsRequest {
175            request_id: requester.next(),
176            size: 100,
177            start_loc: 150,
178            max_ops: NZU64!(50),
179        };
180        assert!(matches!(
181            request.validate(),
182            Err(crate::Error::InvalidRequest(_))
183        ));
184    }
185}
commonware_sync/net/mod.rs

commonware_sync/net/
mod.rs
