« Changelog History


cbor v2.2.0 Release Notes

Release Date: 2020-02-25 // about 4 years ago

  • IMPORTANT : This release fixes a bug that affects all prior versions (1.x and 2.x). Please update if you use Go arrays instead of slices with CBOR indef length arrays). Bug was detected by newer fxamacker/cbor-fuzz.

    🚀 v2.2 is a small release and is the most reliable version currently available.

    🔄 Changes include:

    • 👍 Feat: Support decoding CBOR byte string (major type 2) to Go byte array. (commit 52db071). Thanks @ZenGround0 for requesting this feature.
    • Feat: Add more decoding options (MaxNestedLevels, MaxArrayElements, MaxMapKeyPairs, IndefLength, TagsMd.) (commit cb23445)
    • Feat: Add more encoding options (IndefLength, TagsMd.) (commit cb23445)
    • 🛠 Fix: Fix potential error when decoding shorter CBOR indef length array to Go array (slice wasn't affected). This bug affects all prior versions of 1.x and 2.x. (commit c7f2cc7)
    • 📄 Docs: Replace README.md markdown tables with SVG tables to work around go.dev bugs. Less than half were replaced to avoid delaying this release. Thanks @x448 for working on this until close to midnight!!!

    🚀 v2.2 passed 473 million execs fuzzing before release on Feb 24, 2020 (Central Time) and is continuing.


Previous changes from v2.1.0

  • 🚀 This release focused on three items:

    • CBOR tags (major type 6) for encoding and decoding
    • Duplicate map key detection options for decoding
    • Faster decoding with less memory use (to help offset overhead of new features)

    Decoding got faster and memory use dropped more than expected, especially for 'keyasint' structs.

    ✅ Here's how this library compares to another one using default options and test data from RFC 8392 A.1.

    fxamacker/cbor 2.1 ugorji/go 1.1.7
    Encode CWT claims 457 ns/op, 176 B/op, 2 allocs/op 995 ns/op, 1424 B/op, 4 allocs/op
    Decode CWT claims 796 ns/op, 176 B/op, 6 allocs/op 1105 ns/op, 568 B/op, 6 allocs/op

    🔄 Changes include:

    • 👍 #44 - Add support for CBOR tags (major type 6) with API for built-in and user-defined tags
    • #122 - Add decoding options for duplicate map keys
    • #147 - Decode "keyasint" structs 26% faster and with 57% fewer allocs (COSE, CWT, etc.)
    • #125 - Add encoding option to tag or not tag time values
    • #47 - Improve decoding speed (optimizations already identified during v1)
    • 🚀 Basic optimization for CBOR tags feature, more can be done in later releases
    • 0️⃣ #151 - Implement default encoding for uninitialized time.Time values when tag-required option is specified.
    • ⚡️ Update README.md and benchmarks

    There will be three ways to create EncMode (and similar API for DecMode):

    Function (returns EncMode) Encoding Mode
    EncOptions{...}.EncMode() immutable options, no tags
    🍱 🆕 EncOptions{...}.EncModeWithTags(ts)
    🍱 🆕 EncOptions{...}.EncModeWithSharedTags(ts)

    🏗 To minimize bloat, only tags 0 and 1 (datetime) are going to be part of the default build. The API provides a way for users to register and handle other CBOR tags for user-defined Go types.

    🚀 In future releases, additional tags may be provided by the library in a modular way (possibly build flags or optional packages).

    Special Thanks

    📄 @x448 for helping with v2.1 API, docs, and providing the general idea for DupMapKeyEnforcedAPF.
    @kostko for providing feedback on the draft v2.1 API for CBOR tags.
    @laurencelundblade for providing feedback to @x448 regarding CBOR Null & Undef interop with JSON.
    @ZenGround0 for using this library in go-filecoin and requesting a useful feature that'll be in v2.2.

    v2.1 fuzzing passed 380+ million execs and is still running.