Skip to content

v2.10.0

Latest
Latest

Choose a tag to compare

View all tags
@fxamacker fxamacker released this 28 Oct 15:59
v2.10.0
cc2e8fb
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

v2.10 speeds up encoding by up to 2.88× and decoding by up to 1.87× with zero memory regressions (B/op, allocs/op), reduces memory use, adds the toindefarray struct tag option, and fixes bugs. The Contributing Guidelines, Security Policy, and templates were extensively updated.

Encoding sorted nested maps of dynamic JSON-like data to CBOR drops from 70 allocs/op to 1 and from 7.2 KiB/op to 4.0 KiB/op in the benchmarks below. Encoding time.Time, big.Int, Tag and Marshaler values, and decoding into time.Time, big.Int and Tag, use 1 to 2 fewer allocs/op (20% to 50% fewer).

This release does not use Go's unsafe package. Performance in user apps depends on configuration and data.

Tests were refactored and coverage increased to 97.7%. Fuzz tests (not yet public) were also extended. Internal checklists and procedures were updated to reduce potential mistakes.

Performance and Benchmarks

Across all 215 benchmarks, there are zero memory regressions (B/op, allocs/op). Just one benchmark showed a speed dip: Marshal/struct_many_flds_all_omitempty_all_empty/map is ~4-5% slower, but only when a struct has 32 fields that are both omitzero and empty (same scenario with an 8-field struct is now faster).

Benchmarks ran with Go 1.26.10 on linux/amd64 (benchstat n=10, p=0.000):

  • CBOR Speedup by Data Type: groups of different benchmarks summarized per row
  • CBOR Encoding Reflection-Free Speedup: dynamic JSON-like data types and common types

CBOR Speedup by Data Type

Unmarshal Speedup ΔSec/op
Single values (bool, int, float, byte string, text string) 1.10× to 1.51×¹ -8.87% to -33.92%¹
Epoch time, bignum, other tags 1.18× to 1.64× -15.33% to -38.91%
Arrays and maps to non-struct 1.33× to 1.87× -24.63% to -46.49%
Arrays and maps to structs 1.06× to 1.52× -5.46% to -34.40%
Real-world (COSE, CWT, SenML, WebAuthn) 1.35× to 1.64× -26.06% to -39.19%

¹ 2.54× speedup (-60.64%) when decoding into a named []byte type that has methods.

Marshal Speedup ΔSec/op
Single values (bool, int, float, byte slice, string) 1.32× to 1.55× -24.49% to -35.41%
time.Time, big.Int, Tag, Marshaler² 1.15× to 1.63× -12.94% to -38.84%
Slices and maps 1.35× to 2.88× -25.97% to -65.26%
Structs 1.57× to 2.17× -36.37% to -53.96%
Structs with omitempty fields 0.95׳ to 1.35× +5.01%³ to -25.96%
Real-world (COSE, CWT, SenML, WebAuthn) 1.12× to 1.33× -10.66% to -24.77%

² For addressable values (reached through a pointer, struct field, slice element or map value).

³ Only when every field is omitempty and empty: 7.6 ns slower for a 32-field struct, 2.37 ns faster for an 8-field struct. This is the only performance regression in all 215 benchmarks.

CBOR Encoding Reflection-Free Speedup

PR #870 optimized common types: int, int64, uint, uint64, float64, bool, string, nil, []byte, []any, map[any]any, map[string]any, and map[string]string.

Marshal Benchmark
v2.9.6 → v2.10		 Speedup Time
ΔSec/op		 Memory
ΔB/op		 Memory
ΔAllocs/op
[]any 2.50× -607.5 ns (-60.03%) - -
map[string]any 2.60× -821.9 ns (-61.47%) - -
map[string]string 2.59× -335.9 ns (-61.34%) - -
nested_map[any]any 2.88× -16.542 µs (-65.26%) - -
nested_map[string]any 2.78× -14.201 µs (-64.01%) - -
nested_map[any]any, bw_lex 2.53× -22.36 µs (-60.54%) -3314 (-44.72%) -69 (-98.57%)
nested_map[string]any, bw_lex 2.41× -19.52 µs (-58.54%) -3323 (-44.79%) -69 (-98.57%)
  • bw_lex = SortBytewiseLexical. Memory improvements are from #774 and #860.

Upgrade Notes

  • Go 1.24 or newer is required (#773). All tests (97.7% coverage) pass on Go 1.24-1.27.
  • Pointer-receiver marshal methods (user-implemented methods) are called on the original value instead of a copy when the value is addressable (#866).
  • Marshal configured to use TagsForbidden returns an error for a big.Int outside [-2^64, 2^64-1], and EncMode creation returns an error for settings that would emit tags if TagsForbidden is also set (#868).
  • Decoder advances past well-formed data items rejected by DecOptions value or serialization restrictions (e.g. NaN, IndefLength), and Skip skips them without an error (#872).
  • Marshal configured to emit text-based time returns an error for time.Time outside RFC 3339 limits (#873).

TinyGo (experimental)

TinyGo support for v2.10.0 is available in tag tinygo-beta/v2.10.0-tinygo0.42 (branch feature/cbor-tinygo-beta). It requires TinyGo 0.42.0 or newer. It is experimental and not fuzz tested. For details, see TinyGo (https://github.com/fxamacker/cbor#tinygo) in the README.

What's Changed

⭐ Features

  • feat: add toindefarray struct tag option for CBOR indefinite-length arrays by @tdnguyenND in #770

🚀 Optimizations

  • Optimize encoding speed primarily for slices, maps, and structs by @fxamacker in #806
  • Reduce decoding time up to 17% for all CBOR data types by @fxamacker in #807
  • Reduce decoding time by inlining well-formedness checks by @fxamacker in #810
  • Optimize decoding CBOR byte string by @fxamacker in #811
  • Optimize decoding CBOR text string by up to 16% by @fxamacker in #812
  • Reduce allocs and bound memory of keyValue pool by @fxamacker in #860
  • Reduce allocations when encoding addressable values by @fxamacker in #866
  • Add reflection-free encoding for common types (up to 2.8x faster) by @fxamacker in #870
  • Reduce allocs to speed up time.Time, Tag, and big.Int by @fxamacker in #886

🛠 Improvements

🐞 Bug Fixes

  • Enforce TagsForbidden for bignums and ByteSliceLaterFormat by @fxamacker in #868
  • Advance Decoder past restricted CBOR data items by @fxamacker in #872
  • Reject marshaling out-of-range time.Time to RFC 3339 by @fxamacker in #873
  • Fix some error messages returned by EncMode() and DecMode() by @fxamacker in #883
  • Fix float range check when decoding Unix time by @fxamacker in #889

🧪 Testing

📖 Documentation

📖 Contributing Guidelines, Security Policy, and Templates

  • Update PR template to clarify approval requirement by @fxamacker in #849
  • Rewrite security policy and reporting guidelines by @fxamacker in #864
  • Rewrite PR template to reduce risks from AI and uncoordinated PRs by @fxamacker in #865
  • Rewrite bug report form to reduce security risks by @fxamacker in #867
  • Rewrite feature request form to help triage and reduce risks by @fxamacker in #869
  • Replace docs issue template with an issue form by @fxamacker in #874
  • Update security policy, PR template, and issue forms by @fxamacker in #875
  • Update CONTRIBUTING.md to reduce risks by @fxamacker in #862
  • Improve issue forms for triage and previews by @fxamacker in #880

CI / GitHub Actions

🔎 Details

Other Changes

Ported from release-2.9

Already released in v2.9.3 through v2.9.6.

🔎 Details

Dependabot Updates

🔎 Details

New Contributors

Full Changelog: v2.9.6...v2.10.0

Contributors

dependabot, fxamacker, and tdnguyenND
Assets 2
Loading