Skip to main content

codec_cbor/general/
read_header.rs

1// SPDX-FileCopyrightText: 2026 ReallyMe Technologies Limited
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5use zeroize::{Zeroize, ZeroizeOnDrop};
6
7use super::error::{error, CborError, ErrorReason};
8use super::float::Float;
9
10pub(super) const INLINE_ARGUMENT_LIMIT: u64 = 24;
11const SIMPLE_EXTENDED_MINIMUM: u64 = 32;
12const ADDITIONAL_INFORMATION_MASK: u8 = 0x1f;
13const MAJOR_TYPE_SHIFT: u32 = 5;
14
15/// Schema-generated CBOR major type and received argument width.
16pub use codec_proto::generated::proto::reallyme::codec::v1::{
17    CodecGeneralCborArgumentWidth as ArgumentWidth, CodecGeneralCborMajorType as MajorType,
18};
19
20fn decode_major_type(code: u8) -> Result<MajorType, CborError> {
21    match code {
22        0 => Ok(MajorType::Unsigned),
23        1 => Ok(MajorType::Negative),
24        2 => Ok(MajorType::Bytes),
25        3 => Ok(MajorType::Text),
26        4 => Ok(MajorType::Array),
27        5 => Ok(MajorType::Map),
28        6 => Ok(MajorType::Tag),
29        7 => Ok(MajorType::Simple),
30        _ => Err(error(ErrorReason::ReservedAdditionalInformation)),
31    }
32}
33
34pub(super) trait MajorTypeCode {
35    fn prefix(self) -> Result<u8, CborError>;
36}
37
38impl MajorTypeCode for MajorType {
39    fn prefix(self) -> Result<u8, CborError> {
40        match self {
41            Self::Unsigned => Ok(0x00),
42            Self::Negative => Ok(0x20),
43            Self::Bytes => Ok(0x40),
44            Self::Text => Ok(0x60),
45            Self::Array => Ok(0x80),
46            Self::Map => Ok(0xa0),
47            Self::Tag => Ok(0xc0),
48            Self::Simple => Ok(0xe0),
49            _ => Err(error(ErrorReason::ReservedAdditionalInformation)),
50        }
51    }
52}
53
54pub(super) fn preferred_width(value: u64) -> ArgumentWidth {
55    if value < INLINE_ARGUMENT_LIMIT {
56        ArgumentWidth::Inline
57    } else if value <= u64::from(u8::MAX) {
58        ArgumentWidth::One
59    } else if value <= u64::from(u16::MAX) {
60        ArgumentWidth::Two
61    } else if value <= u64::from(u32::MAX) {
62        ArgumentWidth::Four
63    } else {
64        ArgumentWidth::Eight
65    }
66}
67
68/// Borrowed received header. Successful header decoding makes no payload claim.
69///
70/// Numeric argument copies are wiped on drop. The received bytes remain owned
71/// by the caller, which must provide a zeroizing owner for sensitive input.
72pub struct Header<'a> {
73    encoded: &'a [u8],
74    major: MajorType,
75    width: ArgumentWidth,
76    argument: Option<u64>,
77}
78
79impl<'a> Header<'a> {
80    /// Exact received header bytes, including any non-preferred width.
81    #[must_use]
82    pub const fn received_bytes(&self) -> &'a [u8] {
83        self.encoded
84    }
85    /// Inspect the major type.
86    #[must_use]
87    pub const fn major_type(&self) -> MajorType {
88        self.major
89    }
90    /// Inspect the received argument or float-payload width.
91    #[must_use]
92    pub const fn argument_width(&self) -> ArgumentWidth {
93        self.width
94    }
95    /// Return an integer argument; floats, indefinite lengths, and breaks have none.
96    #[must_use]
97    pub fn argument(&self) -> Option<u64> {
98        if self.is_float() {
99            None
100        } else {
101            self.argument
102        }
103    }
104    /// Observe shortest argument encoding independently of payload validation.
105    /// Floats, indefinite lengths, and breaks return `None`.
106    #[must_use]
107    pub fn has_preferred_argument(&self) -> Option<bool> {
108        self.argument()
109            .map(|value| preferred_width(value) == self.width)
110    }
111    /// Observe whether a float uses the shortest width that holds its value
112    /// exactly, including NaN significands. Non-float headers return `None`.
113    pub fn has_preferred_float(&self) -> Result<Option<bool>, CborError> {
114        Ok(self.float()?.map(|value| value.width() == value.shortest()))
115    }
116    /// Inspect whether this header carries IEEE floating-point bits.
117    #[must_use]
118    pub const fn is_float(&self) -> bool {
119        matches!(self.major, MajorType::Simple)
120            && matches!(
121                self.width,
122                ArgumentWidth::Two | ArgumentWidth::Four | ArgumentWidth::Eight
123            )
124    }
125    /// Extract owned protected floating-point bits, if present.
126    pub fn float(&self) -> Result<Option<Float>, CborError> {
127        if !self.is_float() {
128            return Ok(None);
129        }
130        let value = self.argument.ok_or(error(ErrorReason::Truncated))?;
131        match self.width {
132            ArgumentWidth::Two => Ok(Some(Float::binary16(
133                u16::try_from(value).map_err(|_| error(ErrorReason::ArithmeticOverflow))?,
134            ))),
135            ArgumentWidth::Four => Ok(Some(Float::binary32(
136                u32::try_from(value).map_err(|_| error(ErrorReason::ArithmeticOverflow))?,
137            ))),
138            ArgumentWidth::Eight => Ok(Some(Float::binary64(value))),
139            _ => Err(error(ErrorReason::WrongType)),
140        }
141    }
142    /// Extract a simple-value code; floats and breaks return `None`.
143    pub fn simple_value(&self) -> Result<Option<u8>, CborError> {
144        if self.major != MajorType::Simple || self.is_float() || self.width == ArgumentWidth::Break
145        {
146            return Ok(None);
147        }
148        self.argument
149            .map(|value| u8::try_from(value).map_err(|_| error(ErrorReason::ArithmeticOverflow)))
150            .transpose()
151    }
152}
153
154impl Drop for Header<'_> {
155    fn drop(&mut self) {
156        self.argument.zeroize();
157    }
158}
159impl ZeroizeOnDrop for Header<'_> {}
160
161fn argument_bytes<const N: usize>(input: &[u8]) -> Result<[u8; N], CborError> {
162    let end = 1_usize
163        .checked_add(N)
164        .ok_or(error(ErrorReason::ArithmeticOverflow))?;
165    input
166        .get(1..end)
167        .ok_or(error(ErrorReason::Truncated))?
168        .try_into()
169        .map_err(|_| error(ErrorReason::Truncated))
170}
171
172/// Decode at most nine header bytes, without inspecting or normalizing the payload.
173pub fn read_header_prefix(input: &[u8]) -> Result<Header<'_>, CborError> {
174    let initial = *input.first().ok_or(error(ErrorReason::EmptyInput))?;
175    let major = decode_major_type(initial >> MAJOR_TYPE_SHIFT)?;
176    let info = initial & ADDITIONAL_INFORMATION_MASK;
177    let (width, argument, length) = match info {
178        0..=23 => (ArgumentWidth::Inline, Some(u64::from(info)), 1),
179        24 => (
180            ArgumentWidth::One,
181            Some(u64::from(u8::from_be_bytes(argument_bytes::<1>(input)?))),
182            2,
183        ),
184        25 => (
185            ArgumentWidth::Two,
186            Some(u64::from(u16::from_be_bytes(argument_bytes::<2>(input)?))),
187            3,
188        ),
189        26 => (
190            ArgumentWidth::Four,
191            Some(u64::from(u32::from_be_bytes(argument_bytes::<4>(input)?))),
192            5,
193        ),
194        27 => (
195            ArgumentWidth::Eight,
196            Some(u64::from_be_bytes(argument_bytes::<8>(input)?)),
197            9,
198        ),
199        31 if matches!(
200            major,
201            MajorType::Bytes | MajorType::Text | MajorType::Array | MajorType::Map
202        ) =>
203        {
204            (ArgumentWidth::Indefinite, None, 1)
205        }
206        31 if major == MajorType::Simple => (ArgumentWidth::Break, None, 1),
207        31 => return Err(error(ErrorReason::InvalidIndefiniteArgument)),
208        _ => return Err(error(ErrorReason::ReservedAdditionalInformation)),
209    };
210    if major == MajorType::Simple
211        && width == ArgumentWidth::One
212        && argument.is_some_and(|value| value < SIMPLE_EXTENDED_MINIMUM)
213    {
214        return Err(error(ErrorReason::InvalidSimpleValue));
215    }
216    let encoded = input.get(..length).ok_or(error(ErrorReason::Truncated))?;
217    Ok(Header {
218        encoded,
219        major,
220        width,
221        argument,
222    })
223}