icydb_core/serialize/
mod.rs

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

icydb_core/serialize/
mod.rs
