cbor v2.1.0 Release Notes

Release Date: 2020-02-17 // over 1 year ago
  • ๐Ÿš€ 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.