Skip to main content

ic_db/
key.rs

1//! Exact typed index operands and ordered component bytes; no query execution.
2
3use crate::{
4    Account, Date, Decimal, Duration, Error, FieldType, Float32, Float64, Principal, Subaccount,
5    Timestamp, TypeSchema, U256, Ulid, codec::Decoder, types::unit_enum_len,
6};
7
8/// One exact ordered scalar operand for index prefixes and fluent comparisons.
9/// Operand types must match declared fields;
10/// integers are never implicitly widened, narrowed or coerced across signedness.
11/// This is a bounded scalar boundary, not a general expression/value representation.
12#[derive(Clone, Copy, Debug, PartialEq, Eq)]
13pub enum IndexValue<'a> {
14    /// An absent optional component, ordered before present values.
15    Absent,
16    /// Exact u8 component.
17    Nat8(u8),
18    /// Exact u16 component.
19    Nat16(u16),
20    /// Exact u32 component.
21    Nat32(u32),
22    /// Exact u64 component.
23    Nat64(u64),
24    /// Exact u128 component.
25    Nat128(u128),
26    /// Exact unsigned 256-bit component, without narrower-integer coercion.
27    U256(U256),
28    /// Exact ULID identity, without integer or text coercion.
29    Ulid(Ulid),
30    /// Exact bounded calendar date; no integer or text coercion.
31    Date(Date),
32    /// Exact millisecond duration; no integer coercion.
33    Duration(Duration),
34    /// Exact decimal; the declared field scale must represent it without rounding.
35    Decimal(Decimal),
36    /// Exact millisecond timestamp; no integer coercion.
37    Timestamp(Timestamp),
38    /// Exact account identity; no coercion from another key type.
39    Account(Account),
40    /// Exact subaccount identity; no coercion from another key type.
41    Subaccount(Subaccount),
42    /// Finite canonical 64-bit float; no cross-width or integer coercion.
43    Float64(Float64),
44    /// Finite canonical 32-bit float; no cross-width or integer coercion.
45    Float32(Float32),
46    /// Exact i8 component.
47    Int8(i8),
48    /// Exact i16 component.
49    Int16(i16),
50    /// Exact i32 component.
51    Int32(i32),
52    /// Exact i64 component.
53    Int64(i64),
54    /// Exact i128 component.
55    Int128(i128),
56    /// Canonical identity, ordered by length then significant bytes.
57    Principal(Principal),
58    /// False sorts before true; no numeric coercion.
59    Bool(bool),
60    /// Exact UTF-8 bytes, without case folding or normalization.
61    Text(&'a str),
62    /// Exact raw bytes in lexicographic order; shorter byte prefixes sort first.
63    Blob(&'a [u8]),
64    /// Unit enum in canonical variant-name order, bound to its complete definition.
65    UnitEnum {
66        /// Declared enum identity and alternatives.
67        definition: &'static TypeSchema,
68        /// Zero-based ordinal in canonical variant-name order.
69        ordinal: u8,
70    },
71}
72
73// Scalar wrappers preserve their schema name during admission and projection.
74// Key encoding and fluent operands use the existing primitive semantics.
75pub(crate) fn operand_type(field: FieldType) -> FieldType {
76    if let FieldType::Named(link) = field
77        && let crate::TypeBody::Wrapped(inner) = (link.definition)().body
78    {
79        return inner;
80    }
81    field
82}
83impl<'a> IndexValue<'a> {
84    pub(crate) fn admit(self, field: FieldType, optional: bool) -> Result<(), Error> {
85        if self == Self::Absent {
86            return if optional {
87                Ok(())
88            } else {
89                Err(Error::InvalidOperand)
90            };
91        }
92        match (self, operand_type(field)) {
93            (
94                Self::UnitEnum {
95                    definition,
96                    ordinal,
97                },
98                FieldType::Named(link),
99            ) => {
100                let expected = (link.definition)();
101                if unit_enum_len(definition).is_some_and(|len| usize::from(ordinal) < len)
102                    && unit_enum_len(expected).is_some()
103                    && link.name == definition.name
104                    && definition == expected
105                {
106                    Ok(())
107                } else {
108                    Err(Error::InvalidOperand)
109                }
110            }
111            (Self::Nat8(_), FieldType::Nat8)
112            | (Self::Nat16(_), FieldType::Nat16)
113            | (Self::Nat32(_), FieldType::Nat32)
114            | (Self::Nat64(_), FieldType::Nat64)
115            | (Self::Nat128(_), FieldType::Nat128)
116            | (Self::Float32(_), FieldType::Float32)
117            | (Self::Float64(_), FieldType::Float64)
118            | (Self::Subaccount(_), FieldType::Subaccount)
119            | (Self::U256(_), FieldType::U256)
120            | (Self::Ulid(_), FieldType::Ulid)
121            | (Self::Date(_), FieldType::Date)
122            | (Self::Duration(_), FieldType::Duration)
123            | (Self::Timestamp(_), FieldType::Timestamp)
124            | (Self::Int8(_), FieldType::Int8)
125            | (Self::Int16(_), FieldType::Int16)
126            | (Self::Int32(_), FieldType::Int32)
127            | (Self::Int64(_), FieldType::Int64)
128            | (Self::Int128(_), FieldType::Int128)
129            | (Self::Bool(_), FieldType::Bool) => Ok(()),
130            (Self::Decimal(value), FieldType::Decimal { scale }) => value
131                .coefficient_at_scale(scale)
132                .map(|_| ())
133                .ok_or(Error::InvalidOperand),
134            (Self::Account(value), FieldType::Account) => {
135                Self::Principal(value.owner).admit(FieldType::Principal, false)
136            }
137            (Self::Principal(value), FieldType::Principal) => {
138                if value.as_slice().len() <= crate::codec::MAX_PRINCIPAL_BYTES {
139                    Ok(())
140                } else {
141                    Err(Error::Limit)
142                }
143            }
144            (Self::Text(value), FieldType::Text { max_bytes }) => {
145                if value.len() <= max_bytes as usize {
146                    Ok(())
147                } else {
148                    Err(Error::Limit)
149                }
150            }
151            (Self::Blob(value), FieldType::Blob { max_bytes }) => {
152                if value.len() <= max_bytes as usize {
153                    Ok(())
154                } else {
155                    Err(Error::Limit)
156                }
157            }
158            _ => Err(Error::InvalidOperand),
159        }
160    }
161
162    // Append a scalar payload after optional membership has been decided.
163    fn append_to(self, out: &mut Vec<u8>) {
164        match self {
165            Self::Absent => {}
166            Self::UnitEnum { ordinal, .. } => out.push(ordinal),
167            Self::Nat8(value) => out.extend(value.to_be_bytes()),
168            Self::Nat16(value) => out.extend(value.to_be_bytes()),
169            Self::Nat32(value) => out.extend(value.to_be_bytes()),
170            Self::Nat64(value) => out.extend(value.to_be_bytes()),
171            Self::Nat128(value) => out.extend(value.to_be_bytes()),
172            Self::Float32(value) => out.extend(value.ordered_bytes()),
173            Self::Float64(value) => out.extend(value.ordered_bytes()),
174            Self::Subaccount(value) => out.extend(value),
175            Self::Account(value) => {
176                Self::Principal(value.owner).append_to(out);
177                out.extend(value.effective_subaccount());
178            }
179            Self::U256(value) => out.extend(value.to_be_bytes()),
180            Self::Ulid(value) => out.extend(value.to_bytes()),
181            Self::Timestamp(value) => Self::Int64(value.as_millis()).append_to(out),
182            Self::Decimal(value) => value.append_ordered(out),
183            Self::Duration(value) => Self::Nat64(value.as_millis()).append_to(out),
184            Self::Date(value) => Self::Int32(value.as_days_since_epoch()).append_to(out),
185            Self::Int8(value) => {
186                let mut bytes = value.to_be_bytes();
187                bytes[0] ^= 0x80;
188                out.extend(bytes);
189            }
190            Self::Int16(value) => {
191                let mut bytes = value.to_be_bytes();
192                bytes[0] ^= 0x80;
193                out.extend(bytes);
194            }
195            Self::Int32(value) => {
196                let mut bytes = value.to_be_bytes();
197                bytes[0] ^= 0x80;
198                out.extend(bytes);
199            }
200            Self::Int64(value) => {
201                let mut bytes = value.to_be_bytes();
202                bytes[0] ^= 0x80;
203                out.extend(bytes);
204            }
205            Self::Int128(value) => {
206                let mut bytes = value.to_be_bytes();
207                bytes[0] ^= 0x80;
208                out.extend(bytes);
209            }
210            Self::Principal(value) => {
211                // Row/query admission enforces the durable 29-byte bound.
212                out.push(value.as_slice().len() as u8);
213                out.extend(value.as_slice());
214            }
215            Self::Bool(value) => out.push(u8::from(value)),
216            Self::Text(value) => append_bytes(value.as_bytes(), out),
217            Self::Blob(value) => append_bytes(value, out),
218        }
219    }
220
221    pub(crate) fn append_component(self, optional: bool, out: &mut Vec<u8>) {
222        if optional {
223            out.push(u8::from(self != Self::Absent));
224        }
225        self.append_to(out);
226    }
227
228    pub(crate) fn read(reader: &mut Decoder<'a>, field: FieldType) -> Result<Self, Error> {
229        Ok(match operand_type(field) {
230            FieldType::Named(link) => {
231                let definition = (link.definition)();
232                let len = unit_enum_len(definition).ok_or(Error::Corrupt)?;
233                let ordinal = reader.unit_enum(len)?;
234                Self::UnitEnum {
235                    definition,
236                    ordinal,
237                }
238            }
239            FieldType::Nat8 => Self::Nat8(reader.nat8()?),
240            FieldType::Nat16 => Self::Nat16(reader.nat16()?),
241            FieldType::Nat32 => Self::Nat32(reader.nat32()?),
242            FieldType::Nat64 => Self::Nat64(reader.nat64()?),
243            FieldType::Nat128 => Self::Nat128(reader.nat128()?),
244            FieldType::Float32 => Self::Float32(reader.float32()?),
245            FieldType::Float64 => Self::Float64(reader.float64()?),
246            FieldType::Subaccount => Self::Subaccount(reader.subaccount()?),
247            FieldType::Account => Self::Account(reader.account()?),
248            FieldType::U256 => Self::U256(reader.u256()?),
249            FieldType::Ulid => Self::Ulid(reader.ulid()?),
250            FieldType::Date => Self::Date(reader.date()?),
251            FieldType::Decimal { scale } => Self::Decimal(reader.decimal(scale)?),
252            FieldType::Duration => Self::Duration(reader.duration()?),
253            FieldType::Timestamp => Self::Timestamp(reader.timestamp()?),
254            FieldType::Int8 => Self::Int8(reader.int8()?),
255            FieldType::Int16 => Self::Int16(reader.int16()?),
256            FieldType::Int32 => Self::Int32(reader.int32()?),
257            FieldType::Int64 => Self::Int64(reader.int64()?),
258            FieldType::Int128 => Self::Int128(reader.int128()?),
259            FieldType::Principal => Self::Principal(reader.principal()?),
260            FieldType::Bool => Self::Bool(reader.boolean()?),
261            FieldType::Text { max_bytes } => Self::Text(reader.text_ref(max_bytes as usize)?),
262            FieldType::Blob { max_bytes } => Self::Blob(reader.blob_ref(max_bytes as usize)?),
263            _ => return Err(Error::Corrupt),
264        })
265    }
266}
267
268// Minimum completion of a query prefix, including unknown trailing components.
269// Variable-width identities reserve their shortest valid frame, not their maximum.
270pub(crate) fn minimum_bytes(field: FieldType) -> Result<usize, Error> {
271    Ok(match operand_type(field) {
272        FieldType::Named(link) if unit_enum_len((link.definition)()).is_some() => 1,
273        FieldType::Bool
274        | FieldType::Nat8
275        | FieldType::Int8
276        | FieldType::Principal
277        | FieldType::Decimal { .. } => 1,
278        FieldType::Nat16 | FieldType::Int16 | FieldType::Text { .. } | FieldType::Blob { .. } => 2,
279        FieldType::Nat32 | FieldType::Int32 | FieldType::Float32 | FieldType::Date => 4,
280        FieldType::Nat64
281        | FieldType::Int64
282        | FieldType::Float64
283        | FieldType::Timestamp
284        | FieldType::Duration => 8,
285        FieldType::Nat128 | FieldType::Int128 | FieldType::Ulid => 16,
286        FieldType::U256 | FieldType::Subaccount => 32,
287        FieldType::Account => 33,
288        _ => return Err(Error::InvalidOperand),
289    })
290}
291
292/// Shared generated/stored-row membership and component encoding.
293#[doc(hidden)]
294#[must_use]
295pub fn encode_index(values: &[(IndexValue<'_>, bool)], present_only: bool) -> Option<Vec<u8>> {
296    if present_only && values.iter().any(|(value, _)| *value == IndexValue::Absent) {
297        return None;
298    }
299    let mut bytes = Vec::new();
300    for &(value, optional) in values {
301        value.append_component(optional, &mut bytes);
302    }
303    Some(bytes)
304}
305
306impl<'a, T: Into<IndexValue<'a>>> From<Option<T>> for IndexValue<'a> {
307    fn from(value: Option<T>) -> Self {
308        value.map_or(Self::Absent, Into::into)
309    }
310}
311
312impl From<u8> for IndexValue<'_> {
313    fn from(value: u8) -> Self {
314        Self::Nat8(value)
315    }
316}
317impl From<u16> for IndexValue<'_> {
318    fn from(value: u16) -> Self {
319        Self::Nat16(value)
320    }
321}
322impl From<u32> for IndexValue<'_> {
323    fn from(value: u32) -> Self {
324        Self::Nat32(value)
325    }
326}
327impl From<u64> for IndexValue<'_> {
328    fn from(value: u64) -> Self {
329        Self::Nat64(value)
330    }
331}
332impl From<u128> for IndexValue<'_> {
333    fn from(value: u128) -> Self {
334        Self::Nat128(value)
335    }
336}
337impl From<i8> for IndexValue<'_> {
338    fn from(value: i8) -> Self {
339        Self::Int8(value)
340    }
341}
342impl From<i16> for IndexValue<'_> {
343    fn from(value: i16) -> Self {
344        Self::Int16(value)
345    }
346}
347impl From<i32> for IndexValue<'_> {
348    fn from(value: i32) -> Self {
349        Self::Int32(value)
350    }
351}
352impl From<i64> for IndexValue<'_> {
353    fn from(value: i64) -> Self {
354        Self::Int64(value)
355    }
356}
357impl From<i128> for IndexValue<'_> {
358    fn from(value: i128) -> Self {
359        Self::Int128(value)
360    }
361}
362impl From<Principal> for IndexValue<'_> {
363    fn from(value: Principal) -> Self {
364        Self::Principal(value)
365    }
366}
367
368impl From<U256> for IndexValue<'_> {
369    fn from(value: U256) -> Self {
370        Self::U256(value)
371    }
372}
373
374impl From<Ulid> for IndexValue<'_> {
375    fn from(value: Ulid) -> Self {
376        Self::Ulid(value)
377    }
378}
379
380impl From<Timestamp> for IndexValue<'_> {
381    fn from(value: Timestamp) -> Self {
382        Self::Timestamp(value)
383    }
384}
385
386impl From<Decimal> for IndexValue<'_> {
387    fn from(value: Decimal) -> Self {
388        Self::Decimal(value)
389    }
390}
391
392impl From<Duration> for IndexValue<'_> {
393    fn from(value: Duration) -> Self {
394        Self::Duration(value)
395    }
396}
397
398impl From<Date> for IndexValue<'_> {
399    fn from(value: Date) -> Self {
400        Self::Date(value)
401    }
402}
403
404impl From<Float32> for IndexValue<'_> {
405    fn from(value: Float32) -> Self {
406        Self::Float32(value)
407    }
408}
409
410impl From<Float64> for IndexValue<'_> {
411    fn from(value: Float64) -> Self {
412        Self::Float64(value)
413    }
414}
415
416impl From<Subaccount> for IndexValue<'_> {
417    fn from(value: Subaccount) -> Self {
418        Self::Subaccount(value)
419    }
420}
421
422impl From<Account> for IndexValue<'_> {
423    fn from(value: Account) -> Self {
424        Self::Account(value)
425    }
426}
427
428// Schema admission and byte framing share the fixed-width contract here.
429fn fixed_width(field: FieldType) -> Option<usize> {
430    match field {
431        FieldType::Named(link) if unit_enum_len((link.definition)()).is_some() => Some(1),
432        FieldType::Nat8 | FieldType::Int8 | FieldType::Bool => Some(1),
433        FieldType::Nat16 | FieldType::Int16 => Some(2),
434        FieldType::Nat32 | FieldType::Int32 | FieldType::Float32 | FieldType::Date => Some(4),
435        FieldType::Nat64
436        | FieldType::Int64
437        | FieldType::Float64
438        | FieldType::Timestamp
439        | FieldType::Duration => Some(8),
440        FieldType::Nat128 | FieldType::Int128 | FieldType::Ulid => Some(16),
441        FieldType::U256 | FieldType::Subaccount => Some(32),
442        _ => None,
443    }
444}
445
446pub(crate) fn supports(field: FieldType) -> bool {
447    let field = operand_type(field);
448    fixed_width(field).is_some()
449        || matches!(
450            field,
451            FieldType::Principal
452                | FieldType::Account
453                | FieldType::Text { .. }
454                | FieldType::Blob { .. }
455                | FieldType::Decimal { .. }
456        )
457}
458
459// Consume exactly one self-delimiting component at the key integrity boundary.
460pub(crate) fn consume(bytes: &mut &[u8], field: FieldType) -> Result<(), Error> {
461    let field = operand_type(field);
462    if let FieldType::Named(link) = field {
463        let len = unit_enum_len((link.definition)()).ok_or(Error::Corrupt)?;
464        let (&ordinal, rest) = bytes.split_first().ok_or(Error::Corrupt)?;
465        if usize::from(ordinal) >= len {
466            return Err(Error::Corrupt);
467        }
468        *bytes = rest;
469        return Ok(());
470    }
471    if let FieldType::Decimal { scale } = field {
472        let (value, width) = Decimal::read_ordered(bytes).ok_or(Error::Corrupt)?;
473        value.coefficient_at_scale(scale).ok_or(Error::Corrupt)?;
474        *bytes = &bytes[width..];
475        return Ok(());
476    }
477    if let FieldType::Text { max_bytes } | FieldType::Blob { max_bytes } = field {
478        let mut decoded = 0;
479        loop {
480            let end = bytes
481                .iter()
482                .position(|&byte| byte == 0)
483                .ok_or(Error::Corrupt)?;
484            if matches!(field, FieldType::Text { .. }) {
485                std::str::from_utf8(&bytes[..end]).map_err(|_| Error::Corrupt)?;
486            }
487            decoded += end;
488            let escaped = *bytes.get(end + 1).ok_or(Error::Corrupt)?;
489            *bytes = &bytes[end + 2..];
490            match escaped {
491                0 if decoded <= max_bytes as usize => return Ok(()),
492                255 => decoded += 1,
493                _ => return Err(Error::Corrupt),
494            }
495            if decoded > max_bytes as usize {
496                return Err(Error::Corrupt);
497            }
498        }
499    }
500    if field == FieldType::Bool && !matches!(bytes.first(), Some(0 | 1)) {
501        return Err(Error::Corrupt);
502    }
503    let width = if matches!(field, FieldType::Principal | FieldType::Account) {
504        let (&len, _) = bytes.split_first().ok_or(Error::Corrupt)?;
505        if usize::from(len) > crate::codec::MAX_PRINCIPAL_BYTES {
506            return Err(Error::Corrupt);
507        }
508        usize::from(len) + 1 + if field == FieldType::Account { 32 } else { 0 }
509    } else {
510        fixed_width(field).ok_or(Error::Corrupt)?
511    };
512    let component = bytes.get(..width).ok_or(Error::Corrupt)?;
513    match field {
514        FieldType::Date => {
515            let mut encoded: [u8; 4] = component.try_into().map_err(|_| Error::Corrupt)?;
516            encoded[0] ^= 0x80;
517            Date::try_from_days_since_epoch(i32::from_be_bytes(encoded)).ok_or(Error::Corrupt)?;
518        }
519        FieldType::Float32 => {
520            Float32::from_ordered_bytes(component.try_into().map_err(|_| Error::Corrupt)?)
521                .ok_or(Error::Corrupt)?;
522        }
523        FieldType::Float64 => {
524            Float64::from_ordered_bytes(component.try_into().map_err(|_| Error::Corrupt)?)
525                .ok_or(Error::Corrupt)?;
526        }
527        _ => {}
528    }
529    *bytes = &bytes[width..];
530    Ok(())
531}
532
533impl From<bool> for IndexValue<'_> {
534    fn from(value: bool) -> Self {
535        Self::Bool(value)
536    }
537}
538impl<'a> From<&'a str> for IndexValue<'a> {
539    fn from(value: &'a str) -> Self {
540        Self::Text(value)
541    }
542}
543
544impl<'a> From<&'a String> for IndexValue<'a> {
545    fn from(value: &'a String) -> Self {
546        Self::Text(value)
547    }
548}
549
550impl<'a> From<&'a Vec<u8>> for IndexValue<'a> {
551    fn from(value: &'a Vec<u8>) -> Self {
552        Self::Blob(value)
553    }
554}
555
556impl<'a, const N: usize> From<&'a [u8; N]> for IndexValue<'a> {
557    fn from(value: &'a [u8; N]) -> Self {
558        Self::Blob(value)
559    }
560}
561
562impl<'a> From<&'a [u8]> for IndexValue<'a> {
563    fn from(value: &'a [u8]) -> Self {
564        Self::Blob(value)
565    }
566}
567
568// IcyDB's terminated-byte rule, also used for raw bytes: preserve lexical order
569// and component boundaries, including empty values and embedded zeroes.
570fn append_bytes(value: &[u8], out: &mut Vec<u8>) {
571    for &byte in value {
572        out.push(byte);
573        if byte == 0 {
574            out.push(255);
575        }
576    }
577    out.extend([0, 0]);
578}