icydb_core/value/
storage_key.rs

1//! Module: value::storage_key
2//! Responsibility: decoded scalar key values and legacy fixed-frame encoding.
3//! Does not own: typed primary-key semantics (`Id<E>`) or query coercion rules.
4//! Boundary: shared by primary-key normalization and data/index compatibility layers.
5//!
6//! `StorageKey` is the decoded scalar key value used behind public primary-key
7//! traits. New persisted store-key bytes are owned by the compact key taxonomy.
8
9#![expect(clippy::cast_possible_truncation)]
10
11use crate::{
12    error::InternalError,
13    traits::Repr,
14    types::{Account, Principal, Subaccount, Timestamp, Ulid},
15};
16use candid::CandidType;
17use serde::Deserialize;
18use std::cmp::Ordering;
19use thiserror::Error as ThisError;
20
21//
22// StorageKeyEncodeError
23// Errors returned when encoding a storage key for persistence.
24//
25
26#[derive(Debug, ThisError)]
27pub enum StorageKeyEncodeError {
28    #[error("account owner principal exceeds max length: {len} bytes (limit {max})")]
29    AccountOwnerTooLarge { len: usize, max: usize },
30
31    #[error("value kind '{kind}' is not storage-key encodable")]
32    UnsupportedValueKind { kind: &'static str },
33
34    #[error("principal exceeds max length: {len} bytes (limit {max})")]
35    PrincipalTooLarge { len: usize, max: usize },
36}
37
38impl From<StorageKeyEncodeError> for InternalError {
39    fn from(err: StorageKeyEncodeError) -> Self {
40        Self::serialize_unsupported(err.to_string())
41    }
42}
43
44//
45// StorageKeyDecodeError
46// Errors returned when decoding a persisted storage key payload.
47//
48
49#[derive(Debug, ThisError)]
50pub enum StorageKeyDecodeError {
51    #[error("corrupted StorageKey: invalid size")]
52    InvalidSize,
53
54    #[error("corrupted StorageKey: invalid tag")]
55    InvalidTag,
56
57    #[error("corrupted StorageKey: invalid principal length")]
58    InvalidPrincipalLength,
59
60    #[error("corrupted StorageKey: non-zero {field} padding")]
61    NonZeroPadding { field: &'static str },
62
63    #[error("corrupted StorageKey: invalid account payload ({reason})")]
64    InvalidAccountPayload { reason: &'static str },
65}
66
67//
68// StorageKey
69//
70// Decoded scalar key value used by persistence and indexing.
71//
72// The fixed-width byte frame remains a compatibility codec. Compact
73// `EncodedPrimaryKey` / `RawDataStoreKey` bytes are the 0.159 store-key path.
74// This type is deliberately separated from typed primary-key values (`Id<E>`).
75//
76
77#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq)]
78pub enum StorageKey {
79    Account(Account),
80    Int(i64),
81    Principal(Principal),
82    Subaccount(Subaccount),
83    Timestamp(Timestamp),
84    Nat(u64),
85    Ulid(Ulid),
86    Unit,
87}
88
89impl StorageKey {
90    // ── Variant tags (DO NOT reorder) ────────────────────────────────
91    pub(crate) const TAG_ACCOUNT: u8 = 0;
92    pub(crate) const TAG_INT: u8 = 1;
93    pub(crate) const TAG_PRINCIPAL: u8 = 2;
94    pub(crate) const TAG_SUBACCOUNT: u8 = 3;
95    pub(crate) const TAG_TIMESTAMP: u8 = 4;
96    pub(crate) const TAG_NAT: u8 = 5;
97    pub(crate) const TAG_ULID: u8 = 6;
98    pub(crate) const TAG_UNIT: u8 = 7;
99
100    /// Fixed serialized size in bytes (protocol invariant).
101    /// DO NOT CHANGE without migration.
102    pub const STORED_SIZE_BYTES: u64 = 64;
103    pub const STORED_SIZE_USIZE: usize = Self::STORED_SIZE_BYTES as usize;
104
105    const TAG_SIZE: usize = 1;
106    pub(crate) const TAG_OFFSET: usize = 0;
107
108    pub(crate) const PAYLOAD_OFFSET: usize = Self::TAG_SIZE;
109    const PAYLOAD_SIZE: usize = Self::STORED_SIZE_USIZE - Self::TAG_SIZE;
110
111    pub(crate) const INT_SIZE: usize = 8;
112    pub(crate) const NAT_SIZE: usize = 8;
113    pub(crate) const TIMESTAMP_SIZE: usize = 8;
114    pub(crate) const ULID_SIZE: usize = 16;
115    pub(crate) const SUBACCOUNT_SIZE: usize = 32;
116    const ACCOUNT_MAX_SIZE: usize = 62;
117
118    const fn tag(&self) -> u8 {
119        match self {
120            Self::Account(_) => Self::TAG_ACCOUNT,
121            Self::Int(_) => Self::TAG_INT,
122            Self::Principal(_) => Self::TAG_PRINCIPAL,
123            Self::Subaccount(_) => Self::TAG_SUBACCOUNT,
124            Self::Timestamp(_) => Self::TAG_TIMESTAMP,
125            Self::Nat(_) => Self::TAG_NAT,
126            Self::Ulid(_) => Self::TAG_ULID,
127            Self::Unit => Self::TAG_UNIT,
128        }
129    }
130
131    /// Sentinel key representing the maximum storable value.
132    #[must_use]
133    pub fn max_storable() -> Self {
134        Self::Account(Account::max_storable())
135    }
136
137    /// Global minimum key for scan bounds.
138    pub const MIN: Self = Self::Account(Account::storage_min_sentinel());
139
140    #[must_use]
141    pub const fn lower_bound() -> Self {
142        Self::MIN
143    }
144
145    #[must_use]
146    pub const fn upper_bound() -> Self {
147        Self::Unit
148    }
149
150    const fn variant_rank(&self) -> u8 {
151        self.tag()
152    }
153
154    const fn from_account_encode_error(
155        err: crate::types::AccountEncodeError,
156    ) -> StorageKeyEncodeError {
157        match err {
158            crate::types::AccountEncodeError::OwnerEncode(inner) => {
159                Self::from_principal_encode_error(inner)
160            }
161            crate::types::AccountEncodeError::OwnerTooLarge { len, max } => {
162                StorageKeyEncodeError::AccountOwnerTooLarge { len, max }
163            }
164        }
165    }
166
167    const fn from_principal_encode_error(
168        err: crate::types::PrincipalEncodeError,
169    ) -> StorageKeyEncodeError {
170        match err {
171            crate::types::PrincipalEncodeError::TooLarge { len, max } => {
172                StorageKeyEncodeError::PrincipalTooLarge { len, max }
173            }
174        }
175    }
176
177    /// Encode this key into its fixed-size on-disk representation.
178    pub fn to_bytes(self) -> Result<[u8; Self::STORED_SIZE_USIZE], StorageKeyEncodeError> {
179        // Phase 1: write variant tag and select fixed payload window.
180        let mut buf = [0u8; Self::STORED_SIZE_USIZE];
181        buf[Self::TAG_OFFSET] = self.tag();
182        let payload = &mut buf[Self::PAYLOAD_OFFSET..=Self::PAYLOAD_SIZE];
183
184        // Phase 2: encode variant payload into the normalized fixed-width frame.
185        match self {
186            Self::Account(v) => {
187                let bytes = v
188                    .to_stored_bytes()
189                    .map_err(Self::from_account_encode_error)?;
190                payload[..Self::ACCOUNT_MAX_SIZE].copy_from_slice(&bytes);
191            }
192            Self::Int(v) => {
193                let biased = v.cast_unsigned() ^ (1u64 << 63);
194                payload[..Self::INT_SIZE].copy_from_slice(&biased.to_be_bytes());
195            }
196            Self::Nat(v) => payload[..Self::NAT_SIZE].copy_from_slice(&v.to_be_bytes()),
197            Self::Timestamp(v) => {
198                payload[..Self::TIMESTAMP_SIZE].copy_from_slice(&v.repr().to_be_bytes());
199            }
200            Self::Principal(v) => {
201                let bytes = v
202                    .stored_bytes()
203                    .map_err(Self::from_principal_encode_error)?;
204                let len = bytes.len();
205                payload[0] =
206                    u8::try_from(len).map_err(|_| StorageKeyEncodeError::PrincipalTooLarge {
207                        len,
208                        max: Principal::MAX_LENGTH_IN_BYTES as usize,
209                    })?;
210                payload[1..=len].copy_from_slice(bytes);
211            }
212            Self::Subaccount(v) => payload[..Self::SUBACCOUNT_SIZE].copy_from_slice(&v.to_array()),
213            Self::Ulid(v) => payload[..Self::ULID_SIZE].copy_from_slice(&v.to_bytes()),
214            Self::Unit => {}
215        }
216
217        Ok(buf)
218    }
219
220    pub fn try_from_bytes(bytes: &[u8]) -> Result<Self, StorageKeyDecodeError> {
221        let bytes: &[u8; Self::STORED_SIZE_USIZE] = bytes
222            .try_into()
223            .map_err(|_| StorageKeyDecodeError::InvalidSize)?;
224
225        Self::try_from_stored_bytes(bytes)
226    }
227
228    /// Decode one storage key from one already size-validated stored frame.
229    pub(crate) fn try_from_stored_bytes(
230        bytes: &[u8; Self::STORED_SIZE_USIZE],
231    ) -> Result<Self, StorageKeyDecodeError> {
232        let tag = bytes[Self::TAG_OFFSET];
233        let payload = &bytes[Self::PAYLOAD_OFFSET..=Self::PAYLOAD_SIZE];
234
235        let ensure_zero_padding = |used: usize, ctx: &'static str| {
236            if payload[used..].iter().all(|&b| b == 0) {
237                Ok(())
238            } else {
239                Err(StorageKeyDecodeError::NonZeroPadding { field: ctx })
240            }
241        };
242
243        // Phase 2: decode tagged payload and enforce zero-padding invariants.
244        match tag {
245            Self::TAG_ACCOUNT => {
246                let end = Account::STORED_SIZE as usize;
247                ensure_zero_padding(end, "account")?;
248                Ok(Self::Account(
249                    Account::try_from_bytes(&payload[..end]).map_err(|reason| {
250                        StorageKeyDecodeError::InvalidAccountPayload { reason }
251                    })?,
252                ))
253            }
254            Self::TAG_INT => {
255                let mut buf = [0u8; Self::INT_SIZE];
256                buf.copy_from_slice(&payload[..Self::INT_SIZE]);
257                ensure_zero_padding(Self::INT_SIZE, "int")?;
258                Ok(Self::Int(
259                    (u64::from_be_bytes(buf) ^ (1u64 << 63)).cast_signed(),
260                ))
261            }
262            Self::TAG_PRINCIPAL => {
263                let len = payload[0] as usize;
264                if len > Principal::MAX_LENGTH_IN_BYTES as usize {
265                    return Err(StorageKeyDecodeError::InvalidPrincipalLength);
266                }
267                ensure_zero_padding(1 + len, "principal")?;
268                Ok(Self::Principal(Principal::from_slice(&payload[1..=len])))
269            }
270            Self::TAG_SUBACCOUNT => {
271                ensure_zero_padding(Self::SUBACCOUNT_SIZE, "subaccount")?;
272                let mut buf = [0u8; Self::SUBACCOUNT_SIZE];
273                buf.copy_from_slice(&payload[..Self::SUBACCOUNT_SIZE]);
274                Ok(Self::Subaccount(Subaccount::from_array(buf)))
275            }
276            Self::TAG_TIMESTAMP => {
277                ensure_zero_padding(Self::TIMESTAMP_SIZE, "timestamp")?;
278                let mut buf = [0u8; Self::TIMESTAMP_SIZE];
279                buf.copy_from_slice(&payload[..Self::TIMESTAMP_SIZE]);
280                Ok(Self::Timestamp(Timestamp::from_repr(i64::from_be_bytes(
281                    buf,
282                ))))
283            }
284            Self::TAG_NAT => {
285                ensure_zero_padding(Self::NAT_SIZE, "nat")?;
286                let mut buf = [0u8; Self::NAT_SIZE];
287                buf.copy_from_slice(&payload[..Self::NAT_SIZE]);
288                Ok(Self::Nat(u64::from_be_bytes(buf)))
289            }
290            Self::TAG_ULID => {
291                ensure_zero_padding(Self::ULID_SIZE, "ulid")?;
292                let mut buf = [0u8; Self::ULID_SIZE];
293                buf.copy_from_slice(&payload[..Self::ULID_SIZE]);
294                Ok(Self::Ulid(Ulid::from_bytes(buf)))
295            }
296            Self::TAG_UNIT => {
297                ensure_zero_padding(0, "unit")?;
298                Ok(Self::Unit)
299            }
300            _ => Err(StorageKeyDecodeError::InvalidTag),
301        }
302    }
303}
304
305impl Ord for StorageKey {
306    fn cmp(&self, other: &Self) -> Ordering {
307        match (self, other) {
308            (Self::Account(a), Self::Account(b)) => a.cmp(b),
309            (Self::Int(a), Self::Int(b)) => a.cmp(b),
310            (Self::Principal(a), Self::Principal(b)) => a.cmp(b),
311            (Self::Nat(a), Self::Nat(b)) => a.cmp(b),
312            (Self::Ulid(a), Self::Ulid(b)) => a.cmp(b),
313            (Self::Subaccount(a), Self::Subaccount(b)) => a.cmp(b),
314            (Self::Timestamp(a), Self::Timestamp(b)) => a.cmp(b),
315            _ => self.variant_rank().cmp(&other.variant_rank()),
316        }
317    }
318}
319
320impl PartialOrd for StorageKey {
321    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
322        Some(self.cmp(other))
323    }
324}
325
326impl TryFrom<&[u8]> for StorageKey {
327    type Error = StorageKeyDecodeError;
328    fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
329        Self::try_from_bytes(bytes)
330    }
331}
332
333//
334// TESTS
335//
336
337#[cfg(test)]
338mod tests {
339    use super::{StorageKey, StorageKeyDecodeError, StorageKeyEncodeError};
340    use crate::{
341        types::{
342            Account, Date, Decimal, Duration, Float32, Float64, Int, Int128, Nat, Nat128,
343            Principal, Subaccount, Timestamp, Ulid,
344        },
345        value::{Value, ValueEnum, primary_key_value_from_runtime_value},
346    };
347
348    macro_rules! sample_value_for_scalar {
349        (Account) => {
350            Value::Account(Account::dummy(7))
351        };
352        (Blob) => {
353            Value::Blob(vec![1u8, 2u8, 3u8])
354        };
355        (Bool) => {
356            Value::Bool(true)
357        };
358        (Date) => {
359            Value::Date(Date::new(2024, 1, 2))
360        };
361        (Decimal) => {
362            Value::Decimal(Decimal::new(123, 2))
363        };
364        (Duration) => {
365            Value::Duration(Duration::from_secs(1))
366        };
367        (Enum) => {
368            Value::Enum(ValueEnum::loose("example"))
369        };
370        (Float32) => {
371            Value::Float32(Float32::try_new(1.25).expect("Float32 sample should be finite"))
372        };
373        (Float64) => {
374            Value::Float64(Float64::try_new(2.5).expect("Float64 sample should be finite"))
375        };
376        (Int) => {
377            Value::Int(-7)
378        };
379        (Int128) => {
380            Value::Int128(Int128::from(123i128))
381        };
382        (IntBig) => {
383            Value::IntBig(Int::from(99i32))
384        };
385        (Principal) => {
386            Value::Principal(Principal::from_slice(&[1u8, 2u8, 3u8]))
387        };
388        (Subaccount) => {
389            Value::Subaccount(Subaccount::new([1u8; 32]))
390        };
391        (Text) => {
392            Value::Text("example".to_string())
393        };
394        (Timestamp) => {
395            Value::Timestamp(Timestamp::from_secs(1))
396        };
397        (Nat) => {
398            Value::Nat(7)
399        };
400        (Nat128) => {
401            Value::Nat128(Nat128::from(9u128))
402        };
403        (NatBig) => {
404            Value::NatBig(Nat::from(11u64))
405        };
406        (Ulid) => {
407            Value::Ulid(Ulid::from_u128(42))
408        };
409        (Unit) => {
410            Value::Unit
411        };
412    }
413
414    fn registry_storage_encodable_cases() -> Vec<(Value, bool)> {
415        macro_rules! collect_cases {
416            ( @entries $( ($scalar:ident, $family:expr, $value_pat:pat, is_numeric_value = $is_numeric:expr, supports_numeric_coercion = $supports_numeric_coercion:expr, supports_arithmetic = $supports_arithmetic:expr, supports_equality = $supports_equality:expr, supports_ordering = $supports_ordering:expr, is_keyable = $is_keyable:expr, is_storage_key_encodable = $is_storage_key_encodable:expr) ),* $(,)? ) => {
417                vec![ $( (sample_value_for_scalar!($scalar), $is_storage_key_encodable) ),* ]
418            };
419            ( @args $($ignore:tt)*; @entries $( ($scalar:ident, $family:expr, $value_pat:pat, is_numeric_value = $is_numeric:expr, supports_numeric_coercion = $supports_numeric_coercion:expr, supports_arithmetic = $supports_arithmetic:expr, supports_equality = $supports_equality:expr, supports_ordering = $supports_ordering:expr, is_keyable = $is_keyable:expr, is_storage_key_encodable = $is_storage_key_encodable:expr) ),* $(,)? ) => {
420                vec![ $( (sample_value_for_scalar!($scalar), $is_storage_key_encodable) ),* ]
421            };
422        }
423
424        scalar_registry!(collect_cases)
425    }
426
427    #[test]
428    fn storage_key_try_from_value_matches_registry_flag() {
429        for (value, expected_encodable) in registry_storage_encodable_cases() {
430            assert_eq!(
431                primary_key_value_from_runtime_value(&value).is_ok(),
432                expected_encodable,
433                "value: {value:?}"
434            );
435        }
436    }
437
438    #[test]
439    fn storage_key_known_encodability_contracts() {
440        assert!(primary_key_value_from_runtime_value(&Value::Unit).is_ok());
441        assert!(primary_key_value_from_runtime_value(&Value::Decimal(Decimal::new(1, 0))).is_err());
442        assert!(primary_key_value_from_runtime_value(&Value::Text("x".to_string())).is_err());
443        assert!(primary_key_value_from_runtime_value(&Value::Account(Account::dummy(1))).is_ok());
444    }
445
446    #[test]
447    fn storage_key_unsupported_values_report_kind() {
448        let decimal_err = primary_key_value_from_runtime_value(&Value::Decimal(Decimal::new(1, 0)))
449            .expect_err("Decimal is not storage-key encodable");
450        assert!(matches!(
451            decimal_err,
452            StorageKeyEncodeError::UnsupportedValueKind { kind } if kind == "Decimal"
453        ));
454
455        let text_err = primary_key_value_from_runtime_value(&Value::Text("x".to_string()))
456            .expect_err("Text is not storage-key encodable");
457        assert!(matches!(
458            text_err,
459            StorageKeyEncodeError::UnsupportedValueKind { kind } if kind == "Text"
460        ));
461    }
462
463    #[test]
464    fn storage_keys_sort_deterministically_across_mixed_variants() {
465        let mut keys = vec![
466            primary_key_value_from_runtime_value(&Value::Unit).expect("Unit is encodable"),
467            primary_key_value_from_runtime_value(&Value::Ulid(Ulid::from_u128(2)))
468                .expect("Ulid is encodable"),
469            primary_key_value_from_runtime_value(&Value::Nat(2)).expect("Nat is encodable"),
470            primary_key_value_from_runtime_value(&Value::Timestamp(Timestamp::from_secs(2)))
471                .expect("Timestamp is encodable"),
472            primary_key_value_from_runtime_value(&Value::Subaccount(Subaccount::new([3u8; 32])))
473                .expect("Subaccount is encodable"),
474            primary_key_value_from_runtime_value(&Value::Principal(Principal::from_slice(&[9u8])))
475                .expect("Principal is encodable"),
476            primary_key_value_from_runtime_value(&Value::Int(-1)).expect("Int is encodable"),
477            primary_key_value_from_runtime_value(&Value::Account(Account::dummy(3)))
478                .expect("Account is encodable"),
479        ];
480
481        keys.sort();
482
483        let expected = vec![
484            StorageKey::Account(Account::dummy(3)),
485            StorageKey::Int(-1),
486            StorageKey::Principal(Principal::from_slice(&[9u8])),
487            StorageKey::Subaccount(Subaccount::new([3u8; 32])),
488            StorageKey::Timestamp(Timestamp::from_secs(2)),
489            StorageKey::Nat(2),
490            StorageKey::Ulid(Ulid::from_u128(2)),
491            StorageKey::Unit,
492        ];
493
494        assert_eq!(keys, expected);
495    }
496
497    #[test]
498    fn storage_key_decode_rejects_invalid_size_as_structured_error() {
499        let err =
500            StorageKey::try_from_bytes(&[]).expect_err("decode should reject invalid key size");
501        assert!(matches!(err, StorageKeyDecodeError::InvalidSize));
502    }
503
504    #[test]
505    fn storage_key_decode_rejects_invalid_tag_as_structured_error() {
506        let mut bytes = [0u8; StorageKey::STORED_SIZE_USIZE];
507        bytes[StorageKey::TAG_OFFSET] = 0xFF;
508
509        let err = StorageKey::try_from_bytes(&bytes).expect_err("decode should reject invalid tag");
510        assert!(matches!(err, StorageKeyDecodeError::InvalidTag));
511    }
512
513    #[test]
514    fn storage_key_decode_rejects_non_zero_padding_with_segment_context() {
515        let mut bytes = [0u8; StorageKey::STORED_SIZE_USIZE];
516        bytes[StorageKey::TAG_OFFSET] = StorageKey::TAG_UNIT;
517        bytes[StorageKey::PAYLOAD_OFFSET] = 1;
518
519        let err = StorageKey::try_from_bytes(&bytes)
520            .expect_err("decode should reject non-zero padding for unit payload");
521        assert!(matches!(
522            err,
523            StorageKeyDecodeError::NonZeroPadding { field } if field == "unit"
524        ));
525    }
526}
icydb_core/value/storage_key.rs

icydb_core/value/
storage_key.rs
