All Versions
Latest Version
Avg Release Cycle
10 days
Latest Release
1572 days ago

Changelog History
Page 1

  • v2.2.0 Changes

    February 25, 2020

    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 markdown tables with SVG tables to work around 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.

  • v2.1.0 Changes

    February 17, 2020

    ๐Ÿš€ 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 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.

  • v2.0.1 Changes

    February 06, 2020

    ๐Ÿ”„ Changes include:

    • ๐Ÿ›  Fix: API bug introduced in v2.0.0 with (Un)Marshaler and (Un)MarshalerWithMode interface mixup
    • ๐Ÿ›  Fix: Reject CBOR non-array data for structs decorated with "toarray"

    More at #129 and #137.

    Special thanks to ZenGround0 for reporting issues.

    v2.0.1 passed 300+ million execs in fuzzing (still running). v2.0.0 passed 1+ billion execs fuzzing.

  • v2.0.0 Changes

    February 03, 2020

    ๐Ÿ”„ Changes in v2.0:

    • ๐Ÿ‘Œ Improved API.
    • ๐ŸŽ Faster performance.
    • โฌ‡๏ธ Reduced memory usage.
    • ๐Ÿ‘Œ Improved code quality using around 20 linters.
    • Replaced EncOptions.TimeRFC3339 bool with TimeMode (5 settings).
    • Decode NaN and Infinity time values to Go's "zero time" value.
    • โœ‚ Removed deprecated v1 options and Valid() function.
    • Many improvements to

    Why 2.0?

    v2.0 was needed to simplify adding new features planned for v2.1 and v2.2.


    • ๐Ÿ‘ v2.1 (Feb. 9, 2020) support for CBOR tags (major type 6) and some decoder optimizations.
    • v2.2 (Feb. 2020) options for handling duplicate map keys.

    ๐Ÿšš CBOR Tags (major type 6) was moved to milestone v2.1. and is over 50% done.


    ๐Ÿš€ v2.0 passed 1+ billion execs in coverage-guided fuzzing before release. This is the most well-tested and most reliable release of this library. Upgrading is highly recommended.

    ๐Ÿ‘Œ Improved API

    In v2, more function signatures match encoding/json. These are the most widely used:
    Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, decoder.Decode.

    "Mode" in this API means definite way of encoding or decoding.

    EncMode and DecMode are interfaces created from EncOptions or DecOptions structs.

    EncMode and DecMode use immutable options so their behavior won't accidentally change at runtime. Modes are intended to be reused and are safe for concurrent use.

    // Create EncOptions, using either struct literal or a function.
    opts := cbor.CanonicalEncOptions()
    // If needed, modify options -- e.g. how time values should be encoded.
    opts.Time = cbor.TimeUnix
    // Create reusable EncMode interface with immutable options, safe for concurrent use.
    em, err := opts.EncMode()   
    // Use EncMode like encoding/json, with same function signatures.
    b, err := em.Marshal(v)
    // or
    encoder := em.NewEncoder(w)
    err := encoder.Encode(v)

    ๐Ÿ“ฆ Package Level Functions

    ๐Ÿ“ฆ These package level functions use default options without CBOR tags. Their API matches encoding/json. EncMode and DecMode also provide these functions with same signatures.

    b, err := cbor.Marshal(v)
    err := cbor.Unmarshal(b, &v)
    encoder := cbor.NewEncoder(w)
    decoder := cbor.NewDecoder(r)


    Replaced EncOptions.TimeRFC3339 bool with TimeMode:

    • TimeUnix // secs, encodes to CBOR integer using fewest bytes
    • TimeUnixMicro // ฮผs, encodes to CBOR float with subsecs in fractional part
    • TimeUnixDynamic // secs or ฮผs, encodes to either int or float depending on empty subsecs
    • TimeRFC3339 // secs, encodes to string
    • ๐Ÿšš TimeRFC3339Nano // ns, encodes to string with trailing zeros removed
  • v1.5.1 Changes

    February 10, 2020

    ๐Ÿš€ This release is outdated. Upgrading to v2.0.1 or newer is recommended.

    ๐Ÿ”„ Changes include:

    • ๐Ÿ‘€ Backport v2.0 fix to v1.5 (sanitize decoded NaN and Infinity time values.) See issue #141.
    • โž• Add more unit tests for floating-point data.

    Fuzzing passed 500+ million execs on Feb 9, 2020.

  • v1.5.0 Changes

    January 13, 2020


    • โž• add extensive encoding options while maintaining backward compatibility
    • โž• add four functions that return predefined and modifiable EncOptions
    • ๐Ÿ‘Œ support for preferred serialization (encoding both integers and floating-point values to their smallest forms)
    • ๐Ÿ‘Œ support for encoding float16 (IEEE 754 binary16), prior versions already supported decoding

    ๐Ÿ”„ Changes include:

    • ๐Ÿ”‹ Feature: Add funcs that return predefined encoding configs (commit b7b5733, e203b29)
      • CanonicalEncOptions() -- Canonical CBOR (RFC 7049)
      • CTAP2EncOptions() -- CTAP2 Canonical CBOR
      • CoreDetEncOptions() -- Core Deterministic Encoding
      • PreferredUnsortedEncOptions() - Preferred unsorted serialization
    • ๐Ÿ”‹ Feature: Add ShortestFloat option for encoding (commit 29e78ee)
      • ShortestFloatNone (default)
      • ShortestFloat16
    • ๐Ÿ”‹ Feature: Add NanConvertMode for encoding (commit 16c573c)
      • NaNConvertNone
      • NanConvert7e00
      • NanConvertQuiet
      • NaNConvertPreserveSignal
    • ๐Ÿ”‹ Feature: Add InfConvertMode for encoding (commit 16c573c)
      • InfConvertNone
      • InfConvertFloat16
    • ๐Ÿ”จ Refactor and improve quality of code, docs, and tests

    Fuzzing reached 250+ million execs with Go 1.13 and an older version of our float16 library. The newer version of our float16 library does not contain coding changes but we restarted fuzzing anyway and will let it continue until it reaches 1+ billion execs.

  • v1.4.0 Changes

    December 25, 2019

    ๐Ÿš€ Release v1.4.0 (Dec 25, 2019)

    ๐Ÿ”„ Changes include:

    • ๐Ÿ”‹ Feature: Deprecate bool encoding options and add int SortMode (commit 3b78ee0)
    • Reliability: Use float16 to float32 conversion func that had all 65536 results verified to be correct (commit 48850b2)
    • ๐Ÿ›  Fix: Fix decoding of float16 subnormal numbers (commit 48850b2)

    ๐Ÿš€ Fuzzing reached 532+ million execs with Go 1.12 at the time of release. It will continue fuzzing until 1+ billion execs are reached with Go 1.13.

    corpus: 1237 (20h39m ago), crashers: 0, restarts: 1/10000, execs: 534729619 (6603/sec), cover: 2016, uptime: 22h29m
  • v1.3.4 Changes

    December 19, 2019

    ๐Ÿš€ Release v1.3.4 (Dec 18, 2019)

    ๐Ÿ”จ v1.3.1 to v.1.3.4 benefited from extensive code review and refactoring.

    ๐Ÿ”„ Changes include:

    • ๐Ÿ›  Fix: Limit nested levels to 32 for arrays, maps, tags to prevent stack exhaustion exploits (commit 3aa4328)
    • ๐Ÿ›  Fix: Fix error when decoding to not-nil interface (commit d26d3cd)
    • ๐Ÿ”จ Misc: Refactor to improve readability and maintainability (commit d2d6a95)

    ๐Ÿš€ Fuzzing reached 370+ million execs with Go 1.12 at the time of release. It will continue fuzzing until 1+ billion execs are reached with Go 1.13.

    workers: 2, corpus: 1222 (14h4m ago), crashers: 0, restarts: 1/10000, execs: 370423177 (5300/sec), cover: 1999, uptime: 19h24m
  • v1.3.3 Changes

    December 10, 2019

    ๐Ÿš€ Release v1.3.3 (Dec 9, 2019)

    ๐Ÿ”„ Changes include:

    • ๐Ÿ›  Fix: Fix panic when encoding new type with float32 as its underlying type (commit bb1c06a)
    • ๐Ÿ›  Fix: Change CBOR string validation error from SemanticError to SyntaxError (commit acaec05)
    • ๐Ÿ›  Fix: Reject CBOR indefinite length byte/text string with tagged chunks (commit 28e2c0b)
    • ๐Ÿ›  Fix: Reject CBOR indefinite length text string with invalid UTF-8 chunks (commit 9f1f677)
    • ๐Ÿšš Misc: Add unit tests based on latest 7049bis and remove tests made redundant by this (commit ac1c292)

    ๐Ÿš€ Fuzzing reached 276+ million execs. It will continue to run until 1+ billion execs are reached or v2.0 is released.

    workers: 2, corpus: 1071 (22h56m ago), crashers: 0, restarts: 1/10000, execs: 276970074 (3352/sec), cover: 2011, uptime: 22h57m
  • v1.3.2 Changes

    November 27, 2019

    ๐Ÿš€ Release v1.3.2 (Nov 27, 2019)

    ๐Ÿš€ This release checks for additional issues while decoding well-formed CBOR messages.

    ๐Ÿ”„ Changes include:

    • Skip CBOR array/map elements on incompatible Go type
    • Check if CBOR type can be used as Go map key when map key type is interface{}

    โšก๏ธ A separate project, cbor-fuzz was updated to use new fxamacker/cbor features it had missed. Cover is noticably higher (better) during fuzzing.

    โšก๏ธ UPDATE: Fuzzing reached 4.2+ billion execs on Dec 3, 2019. Corpus is temporarily low (as shown here) for v1.3.2, but it's already 1000+ after combining Go 1.12 + Go 1.13 fuzzing corpus folders after this run.

    2019/12/03 15:37:19 workers: 2, corpus: 602 (12h17m ago), crashers: 0, restarts: 1/10000, execs: 4226276531 (7203/sec), cover: 2000, uptime: 162h59m