Skip to content

Commit 1b57893

Browse files
authored
Update README.md
Update for v1.4 release, including new CBOR comparison charts.
1 parent ac78adf commit 1b57893

1 file changed

Lines changed: 14 additions & 14 deletions

File tree

README.md

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
[![CBOR Library - Slideshow and Latest Docs.](https://github.com/x448/images/raw/master/cbor/cbor_slides.gif)](https://github.com/fxamacker/cbor/blob/master/README.md)
1+
[![CBOR Library - Slideshow and Latest Docs.](https://github.com/fxamacker/images/raw/master/cbor/v1.4.0/cbor_slides.gif)](https://github.com/fxamacker/cbor/blob/master/README.md)
22

33
# CBOR library in Go
4-
This library is a CBOR encoder and decoder. There are many CBOR libraries. Choose this CBOR library if you value your time, program size, and system reliability.
4+
This library is a CBOR encoder and decoder. Each release passes 375+ tests and 250+ million execs in fuzzing with 1000+ CBOR files. Choose this CBOR library if you value your time, program size, and system reliability.
55

66
[![Build Status](https://travis-ci.com/fxamacker/cbor.svg?branch=master)](https://travis-ci.com/fxamacker/cbor)
77
[![codecov](https://codecov.io/gh/fxamacker/cbor/branch/master/graph/badge.svg?v=4)](https://codecov.io/gh/fxamacker/cbor)
@@ -25,7 +25,7 @@ New struct tags like __`keyasint`__ and __`toarray`__ make compact CBOR data lik
2525

2626
<hr>
2727

28-
[![CBOR API](https://github.com/fxamacker/images/raw/master/cbor/cbor_easy_api.png)](#usage)
28+
[![CBOR API](https://github.com/fxamacker/images/raw/master/cbor/v1.4.0/cbor_easy_api.png)](#usage)
2929

3030
<hr>
3131

@@ -37,15 +37,15 @@ Comparisons are between this newer library and a well-known library that had 1,0
3737

3838
__This library is safer__. Small malicious CBOR messages are rejected quickly before they exhaust system resources.
3939

40-
![alt text](https://github.com/fxamacker/images/raw/master/cbor/v1.3.4/cbor_safety_comparison.png "CBOR library safety comparison")
40+
![alt text](https://github.com/fxamacker/images/raw/master/cbor/v1.4.0/cbor_safety_comparison.png "CBOR library safety comparison")
4141

4242
__This library is smaller__. Programs like senmlCat can be 4 MB smaller by switching to this library. Programs using more complex CBOR data types can be 9.2 MB smaller.
4343

44-
![alt text](https://github.com/fxamacker/images/raw/master/cbor/v1.3.4/cbor_size_comparison.png "CBOR library and program size comparison chart")
44+
![alt text](https://github.com/fxamacker/images/raw/master/cbor/v1.4.0/cbor_size_comparison.png "CBOR library and program size comparison chart")
4545

4646
__This library is faster__ for encoding and decoding CBOR Web Token (CWT). However, speed is only one factor and it can vary depending on data types and sizes. Unlike the other library, this one doesn't use Go's ```unsafe``` package or code gen.
4747

48-
![alt text](https://github.com/fxamacker/images/raw/master/cbor/v1.3.4/cbor_speed_comparison.png "CBOR library speed comparison chart")
48+
![alt text](https://github.com/fxamacker/images/raw/master/cbor/v1.4.0/cbor_speed_comparison.png "CBOR library speed comparison chart")
4949

5050
The resource intensive `codec.CborHandle` initialization (in the other library) was placed outside the benchmark loop to make sure their library wasn't penalized.
5151

@@ -56,17 +56,17 @@ Version 1.x has:
5656

5757
* __Stable API__ – won't make breaking API changes.
5858
* __Stable requirements__ – will always support Go v1.12 (unless there's compelling reason).
59-
* __Passed fuzzing__ – v1.3.4 passed 370+ million execs in coverage-guided fuzzing when it was released.
59+
* __Passed fuzzing__ – v1.4 passed 532+ million execs in coverage-guided fuzzing at the time of release. And v1.4 will continue fuzzing until it reaches 1+ billion execs (or until a newer release needs fuzzing.)
6060

61-
Each commit passes 145+ unit tests (plus many more subtests). Each release also passes 250+ million execs in coverage-guided fuzzing using 1,000+ CBOR files (corpus). See [Fuzzing and Code Coverage](#fuzzing-and-code-coverage).
61+
Each commit passes 375+ tests. Each release also passes 250+ million execs in coverage-guided fuzzing using 1,000+ CBOR files (corpus). See [Fuzzing and Code Coverage](#fuzzing-and-code-coverage).
6262

6363
Recent activity:
6464

65-
* [x] [Release v1.2](https://github.com/fxamacker/cbor/releases) -- add RawMessage type, Marshaler and Unmarshaler interfaces.
6665
* [x] [Release v1.3](https://github.com/fxamacker/cbor/releases) -- faster encoding and decoding.
6766
* [x] [Release v1.3](https://github.com/fxamacker/cbor/releases) -- add `toarray` struct tag to simplify using CBOR arrays.
6867
* [x] [Release v1.3](https://github.com/fxamacker/cbor/releases) -- add `keyasint` struct tag to simplify using CBOR maps with int keys.
69-
* [x] [Release v1.3.4](https://github.com/fxamacker/cbor/releases) -- (latest) bugfixes and refactoring. Limit nested levels to 32 for arrays, maps, tags.
68+
* [x] [Release v1.3.4](https://github.com/fxamacker/cbor/releases) -- bugfixes and refactoring. Limit nested levels to 32 for arrays, maps, tags.
69+
* [x] [Release v1.4](https://github.com/fxamacker/cbor/releases) -- (latest) Deprecate bool encoding options and add int SortMode. Use float16 to float32 conversion func that had all 65536 results verified to be correct. Fix decoding of float16 subnormal numbers.
7070

7171
Coming soon: support for CBOR tags (major type 6) and new encoding option to shrink floats. After that, options for handling duplicate map keys.
7272

@@ -81,7 +81,7 @@ This library is designed to be:
8181

8282
Competing factors are balanced:
8383

84-
* __Speed__ vs __safety__ vs __size__ – to keep size small, avoid code generation. For safety, validate data and avoid Go's `unsafe` pkg. For speed, use safe optimizations such as caching struct metadata. v1.3 is faster than a well-known library that uses `unsafe` and code gen.
84+
* __Speed__ vs __safety__ vs __size__ – to keep size small, avoid code generation. For safety, validate data and avoid Go's `unsafe` pkg. For speed, use safe optimizations such as caching struct metadata. v1.4 is faster than a well-known library that uses `unsafe` and code gen.
8585
* __Standards compliance__ – CBOR ([RFC 7049](https://tools.ietf.org/html/rfc7049)) with minor [limitations](#limitations). Encoding modes include default (no sorting), [RFC 7049 canonical](https://tools.ietf.org/html/rfc7049#section-3.9), and [CTAP2 canonical](https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-client-to-authenticator-protocol-v2.0-id-20180227.html#ctap2-canonical-cbor-encoding-form). Decoding also checks for all required malformed data mentioned in latest RFC 7049bis. See [Standards](#standards) section.
8686

8787
All releases prioritize reliability to avoid crashes on decoding malformed CBOR data. See [Fuzzing and Coverage](#fuzzing-and-code-coverage).
@@ -150,9 +150,9 @@ Like Go's `encoding/json`, data validation checks the entire message to prevent
150150

151151
## Fuzzing and Code Coverage
152152

153-
__Over 145 unit tests (plus many more subtests)__ must pass before tagging a release. They include all RFC 7049 examples, bugs found by fuzzing, 2 maliciously crafted CBOR data, and over 87 tests with malformed data based on RFC 7049bis.
153+
__Over 375 tests__ must pass before tagging a release. They include all RFC 7049 examples, bugs found by fuzzing, 2 maliciously crafted CBOR data, and over 87 tests with malformed data based on RFC 7049bis.
154154

155-
__Code coverage__ must not fall below 95% when tagging a release. Code coverage is 97.8% (`go test -cover`) for cbor v1.3 which is among the highest for libraries (in Go) of this type.
155+
__Code coverage__ must not fall below 95% when tagging a release. Code coverage is 97.8% (`go test -cover`) for cbor v1.4 which is among the highest for libraries (in Go) of this type.
156156

157157
__Coverage-guided fuzzing__ must pass 250+ million execs before tagging a release. E.g. v1.3.2 was tagged when it reached 364.9 million execs and continued fuzzing (4+ billion execs) with [fxamacker/cbor-fuzz](https://github.com/fxamacker/cbor-fuzz). Default corpus has:
158158

@@ -413,7 +413,7 @@ Please read the license for additional disclaimers and terms.
413413

414414
## Special Thanks
415415
* Carsten Bormann for RFC 7049 (CBOR), his fast confirmation to my RFC 7049 errata, approving my pull request to 7049bis, and his patience when I misread a line in 7049bis.
416-
* Montgomery Edwards⁴⁴⁸ for updating the README.md, creating comparison charts, and filing many helpful issues.
416+
* Montgomery Edwards⁴⁴⁸ for contributing float16 conversion code, updating the README.md, creating comparison charts & slideshow, and filing many helpful issues.
417417
* Stefan Tatschner for being the 1st to discover my CBOR library, filing issues #1 and #2, and recommending this library.
418418
* Yawning Angel for replacing a library with this one in a big project after an external security audit, and filing issue #5.
419419
* Jernej Kos for filing issue #11 (add feature similar to json.RawMessage) and his kind words about this library.

0 commit comments

Comments
 (0)