feat: init

libraries/native_model/src/header.rs

@@ -0,0 +1,9 @@
+use zerocopy::little_endian::U32;
+use zerocopy::{AsBytes, FromBytes, FromZeroes};
+
+#[derive(FromZeroes, FromBytes, AsBytes, Debug)]
+#[repr(C)]
+pub struct Header {
+    pub(crate) type_id: U32,
+    pub(crate) version: U32,
+}

libraries/native_model/src/lib.rs

@@ -0,0 +1,114 @@
+//! `native_model` is a Rust crate that acts as a thin wrapper around serialized data, adding identity and version information.
+//!
+//! - It aims to ensure:
+//!   - **Interoperability**: Different applications can work together even if they use different data model versions.
+//!   - **Data Consistency**: Ensures the data is processed as expected.
+//!   - **Flexibility**: Allows the use of any serialization format.
+//!   - **Minimal Performance Overhead**: Current performance shows linearly increasing encoding overhead with data size, and constant decoding overhead (~162 picoseconds) for all data sizes.
+//! - **Suitability**:
+//!   - Suitable for applications that are written in Rust, evolve independently, store data locally, and require incremental upgrades.
+//!   - Not suitable for non-Rust applications, systems not controlled by the user, or when human-readable formats are needed.
+//! - **Setup**:
+//!   - Users must define their own serialization format and data model. Examples and a `native_model` macro are provided for this purpose.
+//! - **Development Stage**:
+//!   - The crate is in early development, and performance is expected to improve over time.
+//!
+//! See examples in the [README.md](https://github.com/vincent-herlemont/native_model) file.
+
+mod header;
+mod model;
+pub mod wrapper;
+
+pub use model::*;
+
+/// Macro to generate a [`native_model`] implementation for a struct.
+pub use native_model_macro::*;
+
+use wrapper::*;
+
+use thiserror::Error;
+
+pub type Result<T> = std::result::Result<T, Error>;
+
+#[derive(Error, Debug)]
+pub enum Error {
+    #[error("Invalid header")]
+    InvalidHeader,
+    #[error("Failed to decode native model")]
+    DecodeError,
+    #[error(transparent)]
+    DecodeBodyError(#[from] DecodeBodyError),
+    #[error(transparent)]
+    EncodeBodyError(#[from] EncodeBodyError),
+    #[error(transparent)]
+    UpgradeError(#[from] UpgradeError),
+    #[error("Upgrade from {} to {} is not supported", from, to)]
+    UpgradeNotSupported { from: u32, to: u32 },
+    #[error(transparent)]
+    DowngradeError(#[from] DowngradeError),
+    #[error("Downgrade from {} to {} is not supported", from, to)]
+    DowngradeNotSupported { from: u32, to: u32 },
+    #[error("Wrong type id expected: {}, actual: {}", expected, actual)]
+    WrongTypeId { expected: u32, actual: u32 },
+}
+
+pub type DecodeResult<T> = std::result::Result<T, DecodeBodyError>;
+
+#[derive(Error, Debug)]
+#[error("Decode body error: {msg}")]
+pub struct DecodeBodyError {
+    pub msg: String,
+    #[source]
+    pub source: anyhow::Error,
+}
+
+pub type EncodeResult<T> = std::result::Result<T, EncodeBodyError>;
+
+#[derive(Error, Debug)]
+#[error("Encode body error: {msg}")]
+pub struct EncodeBodyError {
+    pub msg: String,
+    #[source]
+    pub source: anyhow::Error,
+}
+
+#[derive(Error, Debug)]
+#[error("Upgrade error: {msg}")]
+pub struct UpgradeError {
+    pub msg: String,
+    #[source]
+    pub source: anyhow::Error,
+}
+
+#[derive(Error, Debug)]
+#[error("Downgrade error: {msg}")]
+pub struct DowngradeError {
+    pub msg: String,
+    #[source]
+    pub source: anyhow::Error,
+}
+
+/// Allows to encode a [`native_model`] into a [`Vec<u8>`].
+///
+/// See examples:
+///    - [README.md](https://github.com/vincent-herlemont/native_model) file.
+///    - other [examples](https://github.com/vincent-herlemont/native_model/tree/master/tests/example)
+pub fn encode<T: Model>(model: &T) -> Result<Vec<u8>> {
+    T::native_model_encode(model)
+}
+
+/// Allows to encode a [`native_model`] into a [`Vec<u8>`] with a specific version.
+/// See examples:
+///    - [README.md](https://github.com/vincent-herlemont/native_model) file.
+///    - other [examples](https://github.com/vincent-herlemont/native_model/tree/master/tests/example)
+pub fn encode_downgrade<T: Model>(model: T, version: u32) -> Result<Vec<u8>> {
+    T::native_model_encode_downgrade(model, version)
+}
+
+/// Allows to decode a [`native_model`] from a [`Vec<u8>`] and returns the version ([`u32`]).
+/// See examples:
+///    - [README.md](https://github.com/vincent-herlemont/native_model) file.
+///    - other [examples](https://github.com/vincent-herlemont/native_model/tree/master/tests/example)
+pub fn decode<T: Model>(data: Vec<u8>) -> Result<(T, u32)> {
+    T::native_model_decode(data)
+}

libraries/native_model/src/model.rs

@@ -0,0 +1,60 @@
+use crate::{DecodeResult, EncodeResult, Result};
+
+pub trait Model: Sized {
+    fn native_model_id() -> u32;
+    fn native_model_version() -> u32;
+
+    // --------------- Decode ---------------
+
+    fn native_model_decode_body(data: Vec<u8>) -> DecodeResult<Self>
+    where
+        Self: Sized;
+
+    fn native_model_decode_upgrade_body(data: Vec<u8>, version: u32) -> Result<Self>
+    where
+        Self: Sized;
+
+    fn native_model_decode(data: Vec<u8>) -> Result<(Self, u32)>
+    where
+        Self: Sized,
+    {
+        let native_model = crate::Wrapper::deserialize(&data[..]).unwrap();
+        let source_version = native_model.get_version();
+        let result =
+            Self::native_model_decode_upgrade_body(native_model.value().to_vec(), source_version)?;
+        Ok((result, source_version))
+    }
+
+    // --------------- Encode ---------------
+
+    fn native_model_encode_body(&self) -> EncodeResult<Vec<u8>>
+    where
+        Self: Sized;
+
+    fn native_model_encode_downgrade_body(self, version: u32) -> Result<Vec<u8>>
+    where
+        Self: Sized;
+
+    fn native_model_encode(&self) -> Result<Vec<u8>>
+    where
+        Self: Sized,
+    {
+        let mut data = self.native_model_encode_body()?;
+        crate::native_model_encode(
+            &mut data,
+            Self::native_model_id(),
+            Self::native_model_version(),
+        );
+        Ok(data)
+    }
+
+    fn native_model_encode_downgrade(self, version: u32) -> Result<Vec<u8>>
+    where
+        Self: Sized,
+    {
+        let version = version.clone();
+        let mut data = self.native_model_encode_downgrade_body(version)?;
+        crate::native_model_encode(&mut data, Self::native_model_id(), version);
+        Ok(data)
+    }
+}

libraries/native_model/src/wrapper.rs

@@ -0,0 +1,86 @@
+use crate::header::Header;
+use zerocopy::little_endian::U32;
+use zerocopy::{AsBytes, ByteSlice, ByteSliceMut, Ref};
+
+#[derive(Debug)]
+pub struct Wrapper<T: ByteSlice> {
+    header: Ref<T, Header>, // Deprecated: Rename LayoutVerified to Ref #203
+    value: T,
+}
+
+impl<T: ByteSlice> Wrapper<T> {
+    pub fn deserialize(packed: T) -> Option<Self> {
+        let (header_lv, rest) = Ref::<_, Header>::new_from_prefix(packed)?;
+        let native_model = Self {
+            header: header_lv,
+            value: rest,
+        };
+        Some(native_model)
+    }
+
+    pub fn value(&self) -> &T {
+        &self.value
+    }
+
+    pub fn get_type_id(&self) -> u32 {
+        self.header.type_id.get()
+    }
+
+    pub fn get_version(&self) -> u32 {
+        self.header.version.get()
+    }
+}
+
+impl<T: ByteSliceMut> Wrapper<T> {
+    pub fn set_type_id(&mut self, type_id: u32) {
+        self.header.type_id = U32::new(type_id);
+    }
+
+    pub fn set_version(&mut self, version: u32) {
+        self.header.version = U32::new(version);
+    }
+}
+
+pub fn native_model_encode(value: &mut Vec<u8>, type_id: u32, version: u32) {
+    let header = Header {
+        type_id: U32::new(type_id),
+        version: U32::new(version),
+    };
+    let header = header.as_bytes();
+    value.reserve(header.len());
+    value.splice(..0, header.iter().cloned());
+
+    // Try to do with unsafe code to improve performance but benchmark shows that it's the same
+    //
+    // // Add header to the beginning of the vector
+    // unsafe {
+    //     // get the raw pointer to the vector's buffer
+    //     let ptr = value.as_mut_ptr();
+    //
+    //     // move the existing elements to the right
+    //     ptr.offset(header.len() as isize)
+    //         .copy_from_nonoverlapping(ptr, value.len());
+    //
+    //     // copy the elements from the header to the beginning of the vector
+    //     ptr.copy_from_nonoverlapping(header.as_ptr(), header.len());
+    //
+    //     // update the length of the vector
+    //     value.set_len(value.len() + header.len());
+    // }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::{native_model_encode, Wrapper};
+
+    #[test]
+    fn native_model_deserialize_with_body() {
+        let mut data = vec![0u8; 8];
+        native_model_encode(&mut data, 200000, 100000);
+        assert_eq!(data.len(), 16);
+        let model = Wrapper::deserialize(&data[..]).unwrap();
+        assert_eq!(model.get_type_id(), 200000);
+        assert_eq!(model.get_version(), 100000);
+        assert_eq!(model.value().len(), 8);
+    }
+}