6 releases (breaking)

0.6.0 Jan 14, 2024
0.5.0 Nov 24, 2023
0.4.0 Aug 20, 2022
0.3.0 Aug 18, 2022
0.1.0 Aug 9, 2022

#1946 in Encoding


Used in compris

MIT/Apache

98KB
2.5K SLoC

borc: CBOR done right

borc is an implementation of CBOR, the Concise Binary Object Representation, as defined in RFC 8949. CBOR is a simple but powerful data format whose potential has so far gone underused, especially in the Rust space (due to the dominance of Serde, which does not and probably cannot support its full feature set). borc aims to be a one-stop shop for CBOR and CBOR-based protocols.

Status

borc provides both the basic CBOR data model (without any special handling of tags) and an extended data model. Both models are provided in streaming and tree-based forms, akin to SAX and DOM in the XML world.

The following extensions are currently implemented:

  • dates and times using the chrono crate (requires the chrono feature)
  • bignums using the num-bigint crate (requires the num-bigint feature)

The following measures are taken to ensure that the extended implementations can add new extensions while maintaining backwards compatibility:

  • The enums used for their data structures are marked #[non_exhaustive]. This permits adding additional variants at any time without breaking clients at compile time.
  • Extensions are optional at compile-time, if they are complex (enough to result in noticeably slower processing) or require additional dependencies.
  • Extensions are also optional at run-time on a per-encoder/decoder basis, so that it is safe for all users to simply ignore or use unreachable!() to handle extensions they don't care about (since those extensions won't actually show up).

Theoretically it might be better to pursue a layered implementation, with extensions implemented as filters over lower-level, less capable implementations. This would also allow external crates to implement extensions that borc proper would not. However, I think that would be more verbose, less efficient at runtime, and error-prone (since there would be no way to stop users from accidentally repeating a layer twice, for instance). Of course, anyone can still implement additional extensions as layers in that way.

License

This library is distributed under the terms of either of:

at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~0.5–1.3MB
~28K SLoC