# cboritem ![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue) [![cboritem on crates.io](https://img.shields.io/crates/v/cboritem)](https://crates.io/crates/cboritem) [![cboritem on docs.rs](https://docs.rs/cboritem/badge.svg)](https://docs.rs/cboritem) [![Source Code Repository](https://img.shields.io/badge/Code-On%20Codeberg-blue?logo=Codeberg)](https://codeberg.org/chrysn/cboritem)

## cboritem: A serialized CBOR item

A [`CborItem<'a>`][__link0] is a newtype around [`&'a [u8]`][__link1] that upholds the invariant of
containing a single serialized CBOR item. A [`ThinCborItem<'a>`][__link2] is its start
pointer; when accessing it, users rely on that property to stop reading at the end of the item.

In a sense, the types are similar to [`&str`][__link3] and [`CStr`][__link4], respectively,
once the latter follows the [plan][__link5] of eventually becoming a thin pointer.

### Library use

Their use is for efficiently storing pre-verified slices of CBOR items, eg. when implementing
[packed CBOR][__link6]. They can also serve as an interface point between CBOR libraries (easing error
handling because end-of-stream and bytes-after-the-data errors are panic-worthy invariants;
other parsing errors may still occur if there is any well-formed data the parser can not
process, or that violates basic validity requirements), and as a marker type by which CBOR
parsers can be instructed to process any item into a slice for later detailed inspection.

This crate is not a CBOR library, thus it contains no functions to safely create any of its
types (as that requires a CBOR parser). Instead, its intention is to be produced by CBOR
parsers after they have verified that the invariant upholds.

### Invariant definition

The invariant upheld in this crate’s types is that their bytes are exactly one well-formed CBOR
item as defined in [RFC8949][__link7]; in particular, that means they contain at least one byte.

The invariants in this crates are **soundness invariants**: Receivers of a CBOR item may not
just panic when they find invalid CBOR, but they may invoke undefined behavior (eg. by calling
[`unreachable_unchecked`][__link8]. Consequently, creating a CBOR
item requires use of the `unsafe` keyword, with the invariants being checked by the parser that
creates the item.

This is a necessary consequence of providing thin pointers: The invariants are relied on by
users who read through a raw pointer, which on inaccurate data would result in reads beyond the
original allocated object, which is undefined behavior.

### Examples

```rust
use cboritem::{CborItem, ThinCborItem};
let onehundred = [0x24, 0x64];
assert_eq!(onehundred[0], 0x24);
let onehundred = unsafe { CborItem::new(&onehundred) };
let onehundred: ThinCborItem<'_> = onehundred.as_thin();
assert_eq!(core::mem::size_of_val(&onehundred), core::mem::size_of::<&u8>());
// One byte can always be read, so we don't need a CBOR parser to tell us it is safe
if onehundred.first() == 0x24 {
    assert_eq!(unsafe { onehundred.offset(1).read() }, 100);
} else {
    panic!("Unexpected type or integer size");
}
```

### Future development

Later versions may add types or variants of the current types (by means of associated types
with a default), eg. to descibe additional constraints such as

* Embedded strings are UTF-8
* No duplicate keys are present
* Adhers to the Common Deterministic Encoding
* Contains no indefinite-length items
* The CBOR item conforms to some particular CDDL structure

If any extensions are made that change CBOR’s validity rules (eg. i=28 is defined for 128-bit
integer arguments), this crate would go through a major release to support them.


 [__cargo_doc2readme_dependencies_info]: ggGkYW0BYXSEG_W_Gn_kaocAGwCcVPfenh7eGy6gYLEwyIe4G6-xw_FwcbpjYXKEG6Yy1ucqB8HyG7_7-eLiRsMRGz59Evt0Ie9DG-bow14s3BPmYWSBgmhjYm9yaXRlbWUwLjEuMg
 [__link0]: https://docs.rs/cboritem/0.1.2/cboritem/struct.CborItem.html
 [__link1]: https://doc.rust-lang.org/stable/std/primitive.u8.html
 [__link2]: https://docs.rs/cboritem/0.1.2/cboritem/struct.ThinCborItem.html
 [__link3]: https://doc.rust-lang.org/stable/std/primitive.str.html
 [__link4]: https://doc.rust-lang.org/stable/core/?search=ffi::CStr
 [__link5]: https://internals.rust-lang.org/t/pre-rfc-make-cstr-a-thin-pointer/6258
 [__link6]: https://datatracker.ietf.org/doc/draft-ietf-cbor-packed/
 [__link7]: https://datatracker.ietf.org/doc/html/rfc8949
 [__link8]: https://doc.rust-lang.org/stable/core/?search=hint::unreachable_unchecked