CBOR

CBOR is a flexible data format that emphasizes extremely small code size, small message size, and extendability. This library provides a Swift API for encoding and decoding Swift types using the CBOR serialization format.

The motivation for this library over existing implementations is twofold: performance, and reliability. Existing community implementations do not make correct use of Swift features like Optional and memory safety. This library aims to be safe while still outperforming other implementations. To that end, this library has been extensively fuzz tested to ensure your application never crashes due to malicious input. At the same time, this library boasts up to a 74% faster encoding and up to 89% faster decoding than existing implementations. See benchmarks for more details.

Features#

• Codable API for familiar Swift project integration.
• Customizable encoding options, such as date and key formatting.
• Customizable decoding, with the ability to reject non-deterministic CBOR data.
• Encoder creates deterministic CBOR data by default.
• A scan pass allows for decoding only the keys you need from an encoded object.
• Supports decoding half precision floats (Float16) as a regular Float.
• Runs on Linux, Android, and Windows using the swift-foundation project when available.
• Fuzz tested for reliability against crashes.
• Supports tagged items (will expand and add ability to inject your own tags in the future):
  • Dates
  • UUIDs
• Flexible date parsing (tags 0 or 1 with support for any numeric value representation).

Usage#

This library utilizes Swift's Codable API for all (de)serialization operations. It intentionally doesn't support streaming CBOR blobs. After installing the package using Swift Package Manager, use the CBOREncoder and CBORDecoder types to encode to and decode from CBOR blobs, respectively.

// Encode any `Encodable` value.
let encoder = CBOREncoder()
try encoder.encode(0) // Result: 0x00
try encoder.encode([404: "Not Found"]) // Result: 0xA1190194694E6F7420466F756E64

// Decode any `Decodable` type.
let decoder = CBORDecoder()
let intValue = try decoder.decode(Int.self, from: Data([0])) // Result: 0
// Result: ["AB": 1, "A": 2]
let mapValue = try decoder.decode([String: Int].self.self, from: Data([162, 98, 65, 66, 1, 97, 65, 2]))

The encoder and decoders can be customized via the en/decoder initializers or via a En/DecodingOptions struct.

// Customize encoder behavior.
let encoder = CBOREncoder(
	forceStringKeys: Bool = false,
    dateEncodingStrategy: EncodingOptions.DateStrategy = .double
)
// or via the options struct
let options = EncodingOptions(/* ... */)
let encoder = CBOREncoder(options: options)

// Customize the decoder behavior, such as enforcing deterministic CBOR.
let decoder = CBORDecoder(rejectIndeterminateLengths: Bool = false)
// or via the options struct
let options = DecodingOptions(/* ... */)
let decoder = CBORDecoder(options: options)

Documentation is hosted on the Swift Package Index.

Installation#

You can use the Swift Package Manager to download and import the library into your project:

dependencies: [
    .package(url: "https://github.com/thecoolwinter/CBOR.git", from: "1.0.0")
]

Then under targets:

targets: [
    .target(
    	// ...
        dependencies: [
            .product(name: "CBOR", package: "CBOR")
        ]
    )
]

Benchmarks#

These benchmarks range from simple to complex encoding and decoding operations compared to the SwiftCBOR library. Benchmarks source. Benchmarks are run on 10,000 samples and the p50 values are compared here.

Decoding (cpu time)#

Encoding (cpu time)#

Contributing#

By participating in this project you agree to follow the Contributor Code of Conduct. Pull requests and issues are welcome!

Sponsor#

This project has been developed in my spare time. To keep me motivated to continue to maintain it into the future, consider supporting my work!