datum-persistence 0.11.3

Event sourcing, durable state, and CQRS persistence for Datum
Documentation
//! Typed serialization frames, serializer dispatch, and schema adapters.

use std::{collections::HashMap, fmt};

use crate::{PersistenceError, PersistenceResult};

mod adapter;
#[cfg(feature = "protobuf")]
mod protobuf;

pub use adapter::{EventAdapter, IdentityAdapter, StateAdapter};
#[cfg(feature = "protobuf")]
pub use protobuf::ProstSerializer;

/// Stable serializer identifier stored with every serialized payload.
///
/// Values are durable protocol ids: changing the id for an existing serializer
/// makes previously stored payloads undecodable unless the old id remains
/// registered.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct SerializerId(u32);

impl SerializerId {
    /// Creates a serializer id from its durable numeric representation.
    #[must_use]
    pub const fn new(value: u32) -> Self {
        Self(value)
    }

    /// Returns the durable numeric representation.
    #[must_use]
    pub const fn as_u32(self) -> u32 {
        self.0
    }
}

impl fmt::Display for SerializerId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

impl From<u32> for SerializerId {
    fn from(value: u32) -> Self {
        Self::new(value)
    }
}

impl From<SerializerId> for u32 {
    fn from(value: SerializerId) -> Self {
        value.as_u32()
    }
}

/// Durable serialized value stored by persistence backends.
///
/// Both `serializer_id` and `manifest` are protocol identifiers. They must
/// remain decodable for as long as payloads using them remain in storage.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SerializedPayload {
    /// Serializer catalog id used to encode `payload`.
    pub serializer_id: SerializerId,
    /// Serializer-specific durable type/version hint.
    pub manifest: String,
    /// Encoded payload bytes.
    pub payload: Vec<u8>,
}

impl SerializedPayload {
    /// Creates a serialized payload frame.
    #[must_use]
    pub fn new(serializer_id: SerializerId, manifest: impl Into<String>, payload: Vec<u8>) -> Self {
        Self {
            serializer_id,
            manifest: manifest.into(),
            payload,
        }
    }
}

/// Synchronous serializer for one journal representation type.
///
/// Serializer ids and manifests are durable protocol identifiers. Implementors
/// must preserve decoding support for every id/manifest already written.
pub trait PersistenceSerializer<J>: Send + Sync + 'static {
    /// Returns this serializer's durable catalog id.
    fn serializer_id(&self) -> SerializerId;

    /// Returns the durable type/version hint to store for `value`.
    fn manifest(&self, value: &J) -> String;

    /// Encodes a journal value.
    fn serialize(&self, value: &J) -> PersistenceResult<Vec<u8>>;

    /// Decodes a journal value using its stored serializer manifest.
    fn deserialize(&self, manifest: &str, payload: &[u8]) -> PersistenceResult<J>;
}

/// Per-journal-type registry with one primary encoder and id-based decoders.
pub struct SerializerCatalog<J> {
    primary: Box<dyn PersistenceSerializer<J>>,
    registered: HashMap<SerializerId, Box<dyn PersistenceSerializer<J>>>,
}

impl<J: 'static> SerializerCatalog<J> {
    /// Creates a catalog whose primary serializer is used by [`Self::encode`].
    #[must_use]
    pub fn new<S>(primary: S) -> Self
    where
        S: PersistenceSerializer<J>,
    {
        Self {
            primary: Box::new(primary),
            registered: HashMap::new(),
        }
    }

    /// Registers an additional decoder.
    ///
    /// Duplicate durable ids are rejected without changing the catalog.
    pub fn register<S>(&mut self, serializer: S) -> PersistenceResult<()>
    where
        S: PersistenceSerializer<J>,
    {
        let serializer_id = serializer.serializer_id();
        if serializer_id == self.primary.serializer_id()
            || self.registered.contains_key(&serializer_id)
        {
            return Err(PersistenceError::DuplicateSerializer(serializer_id));
        }
        self.registered.insert(serializer_id, Box::new(serializer));
        Ok(())
    }

    /// Registers an additional decoder and returns the updated catalog.
    pub fn with_serializer<S>(mut self, serializer: S) -> PersistenceResult<Self>
    where
        S: PersistenceSerializer<J>,
    {
        self.register(serializer)?;
        Ok(self)
    }

    /// Encodes a value with the primary serializer.
    pub fn encode(&self, value: &J) -> PersistenceResult<SerializedPayload> {
        Ok(SerializedPayload::new(
            self.primary.serializer_id(),
            self.primary.manifest(value),
            self.primary.serialize(value)?,
        ))
    }

    /// Decodes a frame by dispatching on its stored serializer id.
    pub fn decode(&self, frame: &SerializedPayload) -> PersistenceResult<J> {
        let serializer = self
            .serializer(frame.serializer_id)
            .ok_or(PersistenceError::UnknownSerializer(frame.serializer_id))?;
        serializer.deserialize(&frame.manifest, &frame.payload)
    }

    /// Returns the primary serializer id used for new writes.
    #[must_use]
    pub fn primary_serializer_id(&self) -> SerializerId {
        self.primary.serializer_id()
    }

    fn serializer(&self, serializer_id: SerializerId) -> Option<&dyn PersistenceSerializer<J>> {
        if serializer_id == self.primary.serializer_id() {
            Some(self.primary.as_ref())
        } else {
            self.registered.get(&serializer_id).map(Box::as_ref)
        }
    }
}

#[cfg(test)]
mod tests {
    use std::sync::{Arc, Mutex};

    use super::*;

    struct TestSerializer {
        id: SerializerId,
        manifest: &'static str,
        seen_manifest: Arc<Mutex<Option<String>>>,
    }

    impl PersistenceSerializer<String> for TestSerializer {
        fn serializer_id(&self) -> SerializerId {
            self.id
        }

        fn manifest(&self, _value: &String) -> String {
            self.manifest.to_owned()
        }

        fn serialize(&self, value: &String) -> PersistenceResult<Vec<u8>> {
            Ok(value.as_bytes().to_vec())
        }

        fn deserialize(&self, manifest: &str, payload: &[u8]) -> PersistenceResult<String> {
            *self.seen_manifest.lock().unwrap() = Some(manifest.to_owned());
            String::from_utf8(payload.to_vec())
                .map_err(|error| PersistenceError::Serialization(error.to_string()))
        }
    }

    fn serializer(id: u32, manifest: &'static str) -> (TestSerializer, Arc<Mutex<Option<String>>>) {
        let seen_manifest = Arc::new(Mutex::new(None));
        (
            TestSerializer {
                id: SerializerId::new(id),
                manifest,
                seen_manifest: Arc::clone(&seen_manifest),
            },
            seen_manifest,
        )
    }

    #[test]
    fn catalog_encodes_with_primary_and_dispatches_registered_id() {
        let (primary, _) = serializer(10, "primary-v1");
        let (secondary, secondary_manifest) = serializer(20, "secondary-v2");
        let mut catalog = SerializerCatalog::new(primary);
        catalog.register(secondary).unwrap();

        let encoded = catalog.encode(&"write".to_owned()).unwrap();
        assert_eq!(encoded.serializer_id, SerializerId::new(10));
        assert_eq!(encoded.manifest, "primary-v1");

        let old_frame =
            SerializedPayload::new(SerializerId::new(20), "stored-v1", b"read".to_vec());
        assert_eq!(catalog.decode(&old_frame).unwrap(), "read");
        assert_eq!(
            secondary_manifest.lock().unwrap().as_deref(),
            Some("stored-v1")
        );
    }

    #[test]
    fn catalog_rejects_unknown_and_duplicate_ids() {
        let (primary, _) = serializer(10, "primary-v1");
        let mut catalog = SerializerCatalog::new(primary);

        let unknown = SerializedPayload::new(SerializerId::new(99), "", Vec::new());
        assert!(matches!(
            catalog.decode(&unknown),
            Err(PersistenceError::UnknownSerializer(id)) if id == SerializerId::new(99)
        ));

        let (duplicate, _) = serializer(10, "other");
        assert!(matches!(
            catalog.register(duplicate),
            Err(PersistenceError::DuplicateSerializer(id)) if id == SerializerId::new(10)
        ));

        let (secondary, _) = serializer(20, "secondary");
        catalog.register(secondary).unwrap();
        let (duplicate_secondary, _) = serializer(20, "replacement");
        assert!(matches!(
            catalog.register(duplicate_secondary),
            Err(PersistenceError::DuplicateSerializer(id)) if id == SerializerId::new(20)
        ));
        assert_eq!(catalog.primary_serializer_id(), SerializerId::new(10));
    }
}