datum_persistence/serialization/
mod.rs1use std::{collections::HashMap, fmt};
4
5use crate::{PersistenceError, PersistenceResult};
6
7mod adapter;
8#[cfg(feature = "protobuf")]
9mod protobuf;
10
11pub use adapter::{EventAdapter, IdentityAdapter, StateAdapter};
12#[cfg(feature = "protobuf")]
13pub use protobuf::ProstSerializer;
14
15#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
21pub struct SerializerId(u32);
22
23impl SerializerId {
24 #[must_use]
26 pub const fn new(value: u32) -> Self {
27 Self(value)
28 }
29
30 #[must_use]
32 pub const fn as_u32(self) -> u32 {
33 self.0
34 }
35}
36
37impl fmt::Display for SerializerId {
38 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
39 self.0.fmt(f)
40 }
41}
42
43impl From<u32> for SerializerId {
44 fn from(value: u32) -> Self {
45 Self::new(value)
46 }
47}
48
49impl From<SerializerId> for u32 {
50 fn from(value: SerializerId) -> Self {
51 value.as_u32()
52 }
53}
54
55#[derive(Debug, Clone, PartialEq, Eq)]
60pub struct SerializedPayload {
61 pub serializer_id: SerializerId,
63 pub manifest: String,
65 pub payload: Vec<u8>,
67}
68
69impl SerializedPayload {
70 #[must_use]
72 pub fn new(serializer_id: SerializerId, manifest: impl Into<String>, payload: Vec<u8>) -> Self {
73 Self {
74 serializer_id,
75 manifest: manifest.into(),
76 payload,
77 }
78 }
79}
80
81pub trait PersistenceSerializer<J>: Send + Sync + 'static {
86 fn serializer_id(&self) -> SerializerId;
88
89 fn manifest(&self, value: &J) -> String;
91
92 fn serialize(&self, value: &J) -> PersistenceResult<Vec<u8>>;
94
95 fn deserialize(&self, manifest: &str, payload: &[u8]) -> PersistenceResult<J>;
97}
98
99pub struct SerializerCatalog<J> {
101 primary: Box<dyn PersistenceSerializer<J>>,
102 registered: HashMap<SerializerId, Box<dyn PersistenceSerializer<J>>>,
103}
104
105impl<J: 'static> SerializerCatalog<J> {
106 #[must_use]
108 pub fn new<S>(primary: S) -> Self
109 where
110 S: PersistenceSerializer<J>,
111 {
112 Self {
113 primary: Box::new(primary),
114 registered: HashMap::new(),
115 }
116 }
117
118 pub fn register<S>(&mut self, serializer: S) -> PersistenceResult<()>
122 where
123 S: PersistenceSerializer<J>,
124 {
125 let serializer_id = serializer.serializer_id();
126 if serializer_id == self.primary.serializer_id()
127 || self.registered.contains_key(&serializer_id)
128 {
129 return Err(PersistenceError::DuplicateSerializer(serializer_id));
130 }
131 self.registered.insert(serializer_id, Box::new(serializer));
132 Ok(())
133 }
134
135 pub fn with_serializer<S>(mut self, serializer: S) -> PersistenceResult<Self>
137 where
138 S: PersistenceSerializer<J>,
139 {
140 self.register(serializer)?;
141 Ok(self)
142 }
143
144 pub fn encode(&self, value: &J) -> PersistenceResult<SerializedPayload> {
146 Ok(SerializedPayload::new(
147 self.primary.serializer_id(),
148 self.primary.manifest(value),
149 self.primary.serialize(value)?,
150 ))
151 }
152
153 pub fn decode(&self, frame: &SerializedPayload) -> PersistenceResult<J> {
155 let serializer = self
156 .serializer(frame.serializer_id)
157 .ok_or(PersistenceError::UnknownSerializer(frame.serializer_id))?;
158 serializer.deserialize(&frame.manifest, &frame.payload)
159 }
160
161 #[must_use]
163 pub fn primary_serializer_id(&self) -> SerializerId {
164 self.primary.serializer_id()
165 }
166
167 fn serializer(&self, serializer_id: SerializerId) -> Option<&dyn PersistenceSerializer<J>> {
168 if serializer_id == self.primary.serializer_id() {
169 Some(self.primary.as_ref())
170 } else {
171 self.registered.get(&serializer_id).map(Box::as_ref)
172 }
173 }
174}
175
176#[cfg(test)]
177mod tests {
178 use std::sync::{Arc, Mutex};
179
180 use super::*;
181
182 struct TestSerializer {
183 id: SerializerId,
184 manifest: &'static str,
185 seen_manifest: Arc<Mutex<Option<String>>>,
186 }
187
188 impl PersistenceSerializer<String> for TestSerializer {
189 fn serializer_id(&self) -> SerializerId {
190 self.id
191 }
192
193 fn manifest(&self, _value: &String) -> String {
194 self.manifest.to_owned()
195 }
196
197 fn serialize(&self, value: &String) -> PersistenceResult<Vec<u8>> {
198 Ok(value.as_bytes().to_vec())
199 }
200
201 fn deserialize(&self, manifest: &str, payload: &[u8]) -> PersistenceResult<String> {
202 *self.seen_manifest.lock().unwrap() = Some(manifest.to_owned());
203 String::from_utf8(payload.to_vec())
204 .map_err(|error| PersistenceError::Serialization(error.to_string()))
205 }
206 }
207
208 fn serializer(id: u32, manifest: &'static str) -> (TestSerializer, Arc<Mutex<Option<String>>>) {
209 let seen_manifest = Arc::new(Mutex::new(None));
210 (
211 TestSerializer {
212 id: SerializerId::new(id),
213 manifest,
214 seen_manifest: Arc::clone(&seen_manifest),
215 },
216 seen_manifest,
217 )
218 }
219
220 #[test]
221 fn catalog_encodes_with_primary_and_dispatches_registered_id() {
222 let (primary, _) = serializer(10, "primary-v1");
223 let (secondary, secondary_manifest) = serializer(20, "secondary-v2");
224 let mut catalog = SerializerCatalog::new(primary);
225 catalog.register(secondary).unwrap();
226
227 let encoded = catalog.encode(&"write".to_owned()).unwrap();
228 assert_eq!(encoded.serializer_id, SerializerId::new(10));
229 assert_eq!(encoded.manifest, "primary-v1");
230
231 let old_frame =
232 SerializedPayload::new(SerializerId::new(20), "stored-v1", b"read".to_vec());
233 assert_eq!(catalog.decode(&old_frame).unwrap(), "read");
234 assert_eq!(
235 secondary_manifest.lock().unwrap().as_deref(),
236 Some("stored-v1")
237 );
238 }
239
240 #[test]
241 fn catalog_rejects_unknown_and_duplicate_ids() {
242 let (primary, _) = serializer(10, "primary-v1");
243 let mut catalog = SerializerCatalog::new(primary);
244
245 let unknown = SerializedPayload::new(SerializerId::new(99), "", Vec::new());
246 assert!(matches!(
247 catalog.decode(&unknown),
248 Err(PersistenceError::UnknownSerializer(id)) if id == SerializerId::new(99)
249 ));
250
251 let (duplicate, _) = serializer(10, "other");
252 assert!(matches!(
253 catalog.register(duplicate),
254 Err(PersistenceError::DuplicateSerializer(id)) if id == SerializerId::new(10)
255 ));
256
257 let (secondary, _) = serializer(20, "secondary");
258 catalog.register(secondary).unwrap();
259 let (duplicate_secondary, _) = serializer(20, "replacement");
260 assert!(matches!(
261 catalog.register(duplicate_secondary),
262 Err(PersistenceError::DuplicateSerializer(id)) if id == SerializerId::new(20)
263 ));
264 assert_eq!(catalog.primary_serializer_id(), SerializerId::new(10));
265 }
266}