cbor v2.2.0 Release Notes

Release Date: 2020-02-25 // about 1 year 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.