icydb_core/serialize/
mod.rs

1mod cbor;
2
3use serde::{Serialize, de::DeserializeOwned};
4use std::fmt;
5use thiserror::Error as ThisError;
6
7/// Generic CBOR serialization infrastructure.
8///
9/// This module is format-level only:
10/// - No database-layer constants or policy limits are defined here.
11/// - Callers that need bounded decode must pass explicit limits.
12/// - Engine-specific decode policy belongs in subsystem wrappers (for example, `db::codec`).
13
14///
15/// SerializeError
16///
17
18#[derive(Debug, ThisError)]
19pub enum SerializeError {
20    #[error("serialize error: {0}")]
21    Serialize(String),
22
23    #[error("deserialize error: {0}")]
24    Deserialize(String),
25
26    #[error("deserialize size limit exceeded: {len} bytes (limit {max_bytes})")]
27    DeserializeSizeLimitExceeded { len: usize, max_bytes: usize },
28}
29
30///
31/// SerializeErrorKind
32///
33/// Stable error-kind taxonomy for serializer failures.
34///
35
36#[derive(Clone, Copy, Debug, Eq, PartialEq)]
37pub enum SerializeErrorKind {
38    Serialize,
39    Deserialize,
40    DeserializeSizeLimitExceeded,
41}
42
43impl SerializeErrorKind {
44    #[must_use]
45    pub const fn as_str(self) -> &'static str {
46        match self {
47            Self::Serialize => "serialize",
48            Self::Deserialize => "deserialize",
49            Self::DeserializeSizeLimitExceeded => "deserialize_size_limit_exceeded",
50        }
51    }
52}
53
54impl fmt::Display for SerializeErrorKind {
55    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
56        f.write_str(self.as_str())
57    }
58}
59
60impl SerializeError {
61    /// Return a stable error kind independent of backend error-message text.
62    #[must_use]
63    pub const fn kind(&self) -> SerializeErrorKind {
64        match self {
65            Self::Serialize(_) => SerializeErrorKind::Serialize,
66            Self::Deserialize(_) => SerializeErrorKind::Deserialize,
67            Self::DeserializeSizeLimitExceeded { .. } => {
68                SerializeErrorKind::DeserializeSizeLimitExceeded
69            }
70        }
71    }
72}
73
74/// Serialize a value using the default `canic` serializer.
75///
76/// This helper keeps the error type aligned with the rest of `icydb`.
77pub fn serialize<T>(ty: &T) -> Result<Vec<u8>, SerializeError>
78where
79    T: Serialize,
80{
81    cbor::serialize(ty)
82}
83
84/// Return serialized byte length using the default `canic` serializer without
85/// allocating an output buffer.
86pub fn serialized_len<T>(ty: &T) -> Result<usize, SerializeError>
87where
88    T: Serialize,
89{
90    cbor::serialize_len(ty)
91}
92
93/// Deserialize a value produced by [`serialize`].
94pub fn deserialize<T>(bytes: &[u8]) -> Result<T, SerializeError>
95where
96    T: DeserializeOwned,
97{
98    cbor::deserialize(bytes)
99}
100
101/// Deserialize a value produced by [`serialize`], with an explicit size limit.
102///
103/// Size limits are caller policy, not serialization-format policy.
104pub fn deserialize_bounded<T>(bytes: &[u8], max_bytes: usize) -> Result<T, SerializeError>
105where
106    T: DeserializeOwned,
107{
108    cbor::deserialize_bounded(bytes, max_bytes)
109}
icydb_core/serialize/mod.rs

icydb_core/serialize/
mod.rs
