Skip to main content

protocol/
cbor.rs

1//! Strict, definite-length RFC 8949 subset used on the wire (port of `src/cbor`).
2//!
3//! Values mirror what JavaScript can hold: integers are limited to the safe range
4//! (`|n| <= 2^53 - 1`) and an integral float other than `-0` is the same value as the integer.
5
6use std::fmt;
7
8pub const DEFAULT_MAX_CBOR_BYTE_LENGTH: usize = 16 * 1024 * 1024;
9pub const DEFAULT_MAX_CBOR_CONTAINER_LENGTH: usize = 1_000_000;
10pub const DEFAULT_MAX_CBOR_DEPTH: usize = 64;
11const MAX_UINT32: u64 = 0xffff_ffff;
12const MAX_CONFIGURED_DEPTH: usize = 512;
13
14#[derive(Debug, Clone)]
15pub enum Value {
16    Null,
17    Bool(bool),
18    Int(i64),
19    Float(f64),
20    Text(String),
21    Bytes(Vec<u8>),
22    Array(Vec<Value>),
23    /// Entries in wire order; keys are unique.
24    Map(Vec<(String, Value)>),
25}
26
27impl Value {
28    pub fn text(value: impl Into<String>) -> Self {
29        Value::Text(value.into())
30    }
31
32    pub fn map<const N: usize>(entries: [(&str, Value); N]) -> Self {
33        Value::Map(entries.into_iter().map(|(k, v)| (k.to_owned(), v)).collect())
34    }
35
36    pub fn get(&self, key: &str) -> Option<&Value> {
37        match self {
38            Value::Map(entries) => entries.iter().find(|(k, _)| k == key).map(|(_, v)| v),
39            _ => None,
40        }
41    }
42
43    pub fn as_str(&self) -> Option<&str> {
44        match self {
45            Value::Text(text) => Some(text),
46            _ => None,
47        }
48    }
49
50    /// The JavaScript number this value denotes, if it is one.
51    fn number(&self) -> Option<f64> {
52        match self {
53            Value::Int(n) => Some(*n as f64),
54            Value::Float(f) => Some(*f),
55            _ => None,
56        }
57    }
58}
59
60impl PartialEq for Value {
61    /// JavaScript equality of decoded values: `1` and `1.0` are the same number, `-0` is not `0`.
62    fn eq(&self, other: &Self) -> bool {
63        match (self, other) {
64            (Value::Null, Value::Null) => true,
65            (Value::Bool(a), Value::Bool(b)) => a == b,
66            (Value::Text(a), Value::Text(b)) => a == b,
67            (Value::Bytes(a), Value::Bytes(b)) => a == b,
68            (Value::Array(a), Value::Array(b)) => a == b,
69            (Value::Map(a), Value::Map(b)) => {
70                a.len() == b.len() && a.iter().all(|(k, v)| b.iter().any(|(bk, bv)| bk == k && bv == v))
71            }
72            _ => match (self.number(), other.number()) {
73                (Some(a), Some(b)) => a == b && a.is_sign_negative() == b.is_sign_negative(),
74                _ => false,
75            },
76        }
77    }
78}
79
80#[derive(Debug, Clone, PartialEq, Eq)]
81pub struct CborError(pub String);
82
83impl fmt::Display for CborError {
84    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
85        f.write_str(&self.0)
86    }
87}
88
89impl std::error::Error for CborError {}
90
91fn err<T>(message: impl Into<String>) -> Result<T, CborError> {
92    Err(CborError(message.into()))
93}
94
95#[derive(Debug, Clone, Copy, PartialEq, Eq)]
96pub struct CborOptions {
97    /// Maximum encoded input/output bytes and maximum byte/text string length.
98    pub max_byte_length: usize,
99    /// Maximum number of elements in an array or entries in a map.
100    pub max_container_length: usize,
101    /// Maximum recursive item depth.
102    pub max_depth: usize,
103}
104
105impl Default for CborOptions {
106    fn default() -> Self {
107        Self {
108            max_byte_length: DEFAULT_MAX_CBOR_BYTE_LENGTH,
109            max_container_length: DEFAULT_MAX_CBOR_CONTAINER_LENGTH,
110            max_depth: DEFAULT_MAX_CBOR_DEPTH,
111        }
112    }
113}
114
115impl CborOptions {
116    fn validate(&self) -> Result<(), CborError> {
117        let limits = [
118            ("maxByteLength", self.max_byte_length, MAX_UINT32 as usize),
119            ("maxContainerLength", self.max_container_length, MAX_UINT32 as usize),
120            ("maxDepth", self.max_depth, MAX_CONFIGURED_DEPTH),
121        ];
122        for (name, value, maximum) in limits {
123            if value > maximum {
124                return err(format!("{name} must be an integer between 0 and {maximum}"));
125            }
126        }
127        Ok(())
128    }
129}
130
131struct Writer<'a> {
132    out: Vec<u8>,
133    options: &'a CborOptions,
134}
135
136impl Writer<'_> {
137    fn bytes(&mut self, bytes: &[u8]) -> Result<(), CborError> {
138        if self.out.len() + bytes.len() > self.options.max_byte_length {
139            return err(format!(
140                "CBOR byte length exceeds configured limit of {}",
141                self.options.max_byte_length
142            ));
143        }
144        self.out.extend_from_slice(bytes);
145        Ok(())
146    }
147
148    fn argument(&mut self, major: u8, value: u64) -> Result<(), CborError> {
149        let prefix = major << 5;
150        if value < 24 {
151            self.bytes(&[prefix | value as u8])
152        } else if value <= 0xff {
153            self.bytes(&[prefix | 24, value as u8])
154        } else if value <= 0xffff {
155            self.bytes(&[prefix | 25])?;
156            self.bytes(&(value as u16).to_be_bytes())
157        } else if value <= MAX_UINT32 {
158            self.bytes(&[prefix | 26])?;
159            self.bytes(&(value as u32).to_be_bytes())
160        } else {
161            self.bytes(&[prefix | 27])?;
162            self.bytes(&value.to_be_bytes())
163        }
164    }
165
166    fn text(&mut self, value: &str) -> Result<(), CborError> {
167        if value.len() > self.options.max_byte_length {
168            return err(format!(
169                "CBOR text string length exceeds configured limit of {}",
170                self.options.max_byte_length
171            ));
172        }
173        self.argument(3, value.len() as u64)?;
174        self.bytes(value.as_bytes())
175    }
176
177    fn integer(&mut self, value: i64) -> Result<(), CborError> {
178        if !(-jsrt::number::MAX_SAFE_INTEGER..=jsrt::number::MAX_SAFE_INTEGER).contains(&value) {
179            return err("CBOR integers must be safe JavaScript integers");
180        }
181        if value >= 0 {
182            self.argument(0, value as u64)
183        } else {
184            self.argument(1, (-1 - value) as u64)
185        }
186    }
187
188    fn value(&mut self, value: &Value, depth: usize) -> Result<(), CborError> {
189        let options = self.options;
190        if depth > options.max_depth {
191            return err(format!(
192                "CBOR nesting depth exceeds configured limit of {}",
193                options.max_depth
194            ));
195        }
196        match value {
197            Value::Null => self.bytes(&[0xf6]),
198            Value::Bool(b) => self.bytes(&[if *b { 0xf5 } else { 0xf4 }]),
199            Value::Int(n) => self.integer(*n),
200            Value::Float(f) => {
201                if !f.is_finite() {
202                    return err("CBOR numbers must be finite");
203                }
204                if f.fract() == 0.0 && !(*f == 0.0 && f.is_sign_negative()) {
205                    if f.abs() > jsrt::number::MAX_SAFE_INTEGER as f64 {
206                        return err("CBOR integers must be safe JavaScript integers");
207                    }
208                    return self.integer(*f as i64);
209                }
210                self.bytes(&[0xfb])?;
211                self.bytes(&f.to_be_bytes())
212            }
213            Value::Text(text) => self.text(text),
214            Value::Bytes(bytes) => {
215                if bytes.len() > options.max_byte_length {
216                    return err(format!(
217                        "CBOR byte string length exceeds configured limit of {}",
218                        options.max_byte_length
219                    ));
220                }
221                self.argument(2, bytes.len() as u64)?;
222                self.bytes(bytes)
223            }
224            Value::Array(items) => {
225                if items.len() > options.max_container_length {
226                    return err(format!(
227                        "CBOR array length exceeds configured limit of {}",
228                        options.max_container_length
229                    ));
230                }
231                self.argument(4, items.len() as u64)?;
232                items.iter().try_for_each(|item| self.value(item, depth + 1))
233            }
234            Value::Map(entries) => {
235                if entries.len() > options.max_container_length {
236                    return err(format!(
237                        "CBOR map length exceeds configured limit of {}",
238                        options.max_container_length
239                    ));
240                }
241                self.argument(5, entries.len() as u64)?;
242                for (key, entry) in entries {
243                    self.text(key)?;
244                    self.value(entry, depth + 1)?;
245                }
246                Ok(())
247            }
248        }
249    }
250}
251
252pub fn encode_cbor(value: &Value, options: &CborOptions) -> Result<Vec<u8>, CborError> {
253    options.validate()?;
254    let mut writer = Writer {
255        out: Vec::new(),
256        options,
257    };
258    writer.value(value, 0)?;
259    Ok(writer.out)
260}
261
262struct Reader<'a> {
263    bytes: &'a [u8],
264    offset: usize,
265    options: &'a CborOptions,
266}
267
268impl Reader<'_> {
269    fn byte(&mut self) -> Result<u8, CborError> {
270        let Some(&value) = self.bytes.get(self.offset) else {
271            return err("Truncated CBOR payload");
272        };
273        self.offset += 1;
274        Ok(value)
275    }
276
277    fn take(&mut self, length: u64) -> Result<&[u8], CborError> {
278        if length > (self.bytes.len() - self.offset) as u64 {
279            return err("Truncated CBOR payload");
280        }
281        let start = self.offset;
282        self.offset += length as usize;
283        Ok(&self.bytes[start..self.offset])
284    }
285
286    fn argument(&mut self, info: u8) -> Result<u64, CborError> {
287        match info {
288            0..=23 => Ok(u64::from(info)),
289            24 => Ok(u64::from(self.byte()?)),
290            25 => Ok(u64::from(u16::from_be_bytes(
291                self.take(2)?.try_into().unwrap_or_default(),
292            ))),
293            26 => Ok(u64::from(u32::from_be_bytes(
294                self.take(4)?.try_into().unwrap_or_default(),
295            ))),
296            27 => {
297                let high = self.argument(26)?;
298                let low = self.argument(26)?;
299                if high > 0x1f_ffff {
300                    return err("Decoded CBOR integer or length is outside the safe range");
301                }
302                Ok((high << 32) | low)
303            }
304            31 => err("Indefinite-length CBOR items are not supported"),
305            _ => err("Malformed CBOR additional information"),
306        }
307    }
308
309    fn length(&mut self, info: u8, kind: &str, limit: usize) -> Result<u64, CborError> {
310        if info == 31 {
311            return err(format!("Indefinite-length CBOR {kind}s are not supported"));
312        }
313        let length = self.argument(info)?;
314        if length > limit as u64 {
315            return err(format!("CBOR {kind} length exceeds configured limit of {limit}"));
316        }
317        Ok(length)
318    }
319
320    fn item(&mut self, depth: usize) -> Result<Value, CborError> {
321        let options = self.options;
322        if depth > options.max_depth {
323            return err(format!(
324                "CBOR nesting depth exceeds configured limit of {}",
325                options.max_depth
326            ));
327        }
328        let initial = self.byte()?;
329        let info = initial & 0x1f;
330        match initial >> 5 {
331            0 => Ok(Value::Int(self.argument(info)? as i64)),
332            1 => {
333                let value = -1 - self.argument(info)? as i64;
334                if value < -jsrt::number::MAX_SAFE_INTEGER {
335                    return err("Decoded CBOR integer is outside the safe range");
336                }
337                Ok(Value::Int(value))
338            }
339            2 => {
340                let length = self.length(info, "byte string", options.max_byte_length)?;
341                Ok(Value::Bytes(self.take(length)?.to_vec()))
342            }
343            3 => {
344                let length = self.length(info, "text string", options.max_byte_length)?;
345                match std::str::from_utf8(self.take(length)?) {
346                    Ok(text) => Ok(Value::text(text)),
347                    Err(_) => err("CBOR text string contains invalid UTF-8"),
348                }
349            }
350            4 => {
351                let length = self.length(info, "array", options.max_container_length)?;
352                let mut items = Vec::new();
353                for _ in 0..length {
354                    items.push(self.item(depth + 1)?);
355                }
356                Ok(Value::Array(items))
357            }
358            5 => {
359                let length = self.length(info, "map", options.max_container_length)?;
360                let mut entries: Vec<(String, Value)> = Vec::new();
361                for _ in 0..length {
362                    let Value::Text(key) = self.item(depth + 1)? else {
363                        return err("CBOR map keys must be strings");
364                    };
365                    if entries.iter().any(|(k, _)| *k == key) {
366                        return err("CBOR map contains a duplicate key");
367                    }
368                    let value = self.item(depth + 1)?;
369                    entries.push((key, value));
370                }
371                Ok(Value::Map(entries))
372            }
373            6 => err("CBOR tags are not supported"),
374            _ => self.simple(info),
375        }
376    }
377
378    fn simple(&mut self, info: u8) -> Result<Value, CborError> {
379        match info {
380            20 => Ok(Value::Bool(false)),
381            21 => Ok(Value::Bool(true)),
382            22 => Ok(Value::Null),
383            27 => {
384                let value = f64::from_be_bytes(self.take(8)?.try_into().unwrap_or_default());
385                if !value.is_finite() {
386                    return err("Decoded CBOR number must be finite");
387                }
388                if value.fract() == 0.0 && value.abs() > jsrt::number::MAX_SAFE_INTEGER as f64 {
389                    return err("Decoded CBOR integer is outside the safe range");
390                }
391                if value.fract() == 0.0 && !(value == 0.0 && value.is_sign_negative()) {
392                    return Ok(Value::Int(value as i64));
393                }
394                Ok(Value::Float(value))
395            }
396            31 => err("CBOR break marker is not supported"),
397            _ => err("Unsupported CBOR simple value or floating-point width"),
398        }
399    }
400}
401
402/// Decodes exactly one item from the protocol's strict RFC 8949 subset.
403pub fn decode_cbor(bytes: &[u8], options: &CborOptions) -> Result<Value, CborError> {
404    options.validate()?;
405    if bytes.len() > options.max_byte_length {
406        return err(format!(
407            "CBOR byte length exceeds configured limit of {}",
408            options.max_byte_length
409        ));
410    }
411    let mut reader = Reader {
412        bytes,
413        offset: 0,
414        options,
415    };
416    let value = reader.item(0)?;
417    if reader.offset != bytes.len() {
418        return err("CBOR payload contains trailing data");
419    }
420    Ok(value)
421}