Skip to main content

datum_persistence/serialization/
mod.rs

1//! Typed serialization frames, serializer dispatch, and schema adapters.
2
3use 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/// Stable serializer identifier stored with every serialized payload.
16///
17/// Values are durable protocol ids: changing the id for an existing serializer
18/// makes previously stored payloads undecodable unless the old id remains
19/// registered.
20#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
21pub struct SerializerId(u32);
22
23impl SerializerId {
24    /// Creates a serializer id from its durable numeric representation.
25    #[must_use]
26    pub const fn new(value: u32) -> Self {
27        Self(value)
28    }
29
30    /// Returns the durable numeric representation.
31    #[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/// Durable serialized value stored by persistence backends.
56///
57/// Both `serializer_id` and `manifest` are protocol identifiers. They must
58/// remain decodable for as long as payloads using them remain in storage.
59#[derive(Debug, Clone, PartialEq, Eq)]
60pub struct SerializedPayload {
61    /// Serializer catalog id used to encode `payload`.
62    pub serializer_id: SerializerId,
63    /// Serializer-specific durable type/version hint.
64    pub manifest: String,
65    /// Encoded payload bytes.
66    pub payload: Vec<u8>,
67}
68
69impl SerializedPayload {
70    /// Creates a serialized payload frame.
71    #[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
81/// Synchronous serializer for one journal representation type.
82///
83/// Serializer ids and manifests are durable protocol identifiers. Implementors
84/// must preserve decoding support for every id/manifest already written.
85pub trait PersistenceSerializer<J>: Send + Sync + 'static {
86    /// Returns this serializer's durable catalog id.
87    fn serializer_id(&self) -> SerializerId;
88
89    /// Returns the durable type/version hint to store for `value`.
90    fn manifest(&self, value: &J) -> String;
91
92    /// Encodes a journal value.
93    fn serialize(&self, value: &J) -> PersistenceResult<Vec<u8>>;
94
95    /// Decodes a journal value using its stored serializer manifest.
96    fn deserialize(&self, manifest: &str, payload: &[u8]) -> PersistenceResult<J>;
97}
98
99/// Per-journal-type registry with one primary encoder and id-based decoders.
100pub 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    /// Creates a catalog whose primary serializer is used by [`Self::encode`].
107    #[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    /// Registers an additional decoder.
119    ///
120    /// Duplicate durable ids are rejected without changing the catalog.
121    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    /// Registers an additional decoder and returns the updated catalog.
136    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    /// Encodes a value with the primary serializer.
145    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    /// Decodes a frame by dispatching on its stored serializer id.
154    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    /// Returns the primary serializer id used for new writes.
162    #[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}