Skip to content

Commit 6cdde66

Browse files
x448fxamacker
andauthored
Update CBOR docs for v2.4.0 (#318)
- v2.4.0 passed 3.4 billion execs fuzzing - add gravitational/teleport as a user - remove mention of very outdated cbor-fuzz which was replaced long ago - bump minimum fuzzing to 1+ billion execs for each new release as discussed with @fxamacker - fix broken links in the badges - minor updates to README during review Co-authored-by: Faye Amacker <[email protected]>
1 parent 5ea68a6 commit 6cdde66

File tree

1 file changed

+10
-10
lines changed

1 file changed

+10
-10
lines changed

README.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
11
# CBOR Codec in Go
22

3-
[![](https://github.com/fxamacker/images/raw/master/cbor/v2.3.0/fxamacker_cbor_banner.png)](#cbor-library-in-go)
3+
[![](https://github.com/fxamacker/images/raw/master/cbor/v2.4.0/fxamacker_cbor_banner.png)](#cbor-library-in-go)
44

55
[![](https://github.com/fxamacker/cbor/workflows/ci/badge.svg)](https://github.com/fxamacker/cbor/actions?query=workflow%3Aci)
66
[![](https://github.com/fxamacker/cbor/workflows/cover%20%E2%89%A598%25/badge.svg)](https://github.com/fxamacker/cbor/actions?query=workflow%3A%22cover+%E2%89%A598%25%22)
77
[![](https://github.com/fxamacker/cbor/workflows/linters/badge.svg)](https://github.com/fxamacker/cbor/actions?query=workflow%3Alinters)
88
[![CodeQL](https://github.com/fxamacker/cbor/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/fxamacker/cbor/actions/workflows/codeql-analysis.yml)
9-
[![](https://img.shields.io/badge/fuzzing-1%2B%20billion-44c010)]()
9+
[![](https://img.shields.io/badge/fuzzing-3%2B%20billion%20execs-44c010)](#fuzzing-and-code-coverage)
1010
[![Go Report Card](https://goreportcard.com/badge/github.com/fxamacker/cbor)](https://goreportcard.com/report/github.com/fxamacker/cbor)
11-
[![](https://img.shields.io/badge/go-%3E%3D%201.12-blue)]()
11+
[![](https://img.shields.io/badge/go-%3E%3D%201.12-blue)](#cbor-library-installation)
1212

13-
[__fxamacker/cbor__](https://github.com/fxamacker/cbor) is a modern [CBOR](https://tools.ietf.org/html/rfc8949) codec in [Go](https://golang.org). It's like `encoding/json` for CBOR with time-saving features. It balances [security](https://github.com/fxamacker/cbor/#cbor-security), usability, [speed](https://github.com/fxamacker/cbor/#cbor-performance), and other competing factors.
13+
[__fxamacker/cbor__](https://github.com/fxamacker/cbor) is a modern [CBOR](https://tools.ietf.org/html/rfc8949) codec in [Go](https://golang.org). It's like `encoding/json` for CBOR with time-saving features. It balances [security](https://github.com/fxamacker/cbor/#cbor-security), usability, [speed](https://github.com/fxamacker/cbor/#cbor-performance), data size, program size, and other competing factors.
1414

1515
Features include CBOR tags, duplicate map key detection, float64→32→16, and Go struct tags (`toarray`, `keyasint`, `omitempty`). API is close to `encoding/json` plus predefined CBOR options like Core Deterministic Encoding, Preferred Serialization, CTAP2, etc.
1616

17-
Combining Preferred Serialization and struct tags (`toarray`, `keyasint`, `omitempty`) reduces programming effort and creates very compact data size.
17+
Using CBOR [Preferred Serialization](https://www.rfc-editor.org/rfc/rfc8949.html#name-preferred-serialization) with Go struct tags (`toarray`, `keyasint`, `omitempty`) reduces programming effort and creates smaller encoded data size.
1818

19-
fxamacker/cbor is used by Arm Ltd., Berlin Institute of Health at Charité, Chainlink, ConsenSys, Dapper Labs, Duo Labs (cisco), EdgeX Foundry, Mozilla, Netherlands (govt), Oasis Labs, Taurus SA, Teleport, and others.
19+
fxamacker/cbor has 98% coverage and is fuzz tested. It won't exhaust RAM decoding 9 bytes of bad CBOR data. It's used by Arm Ltd., Berlin Institute of Health at Charité, Chainlink, ConsenSys, Dapper Labs, Duo Labs (cisco), EdgeX Foundry, Mozilla, Netherlands (govt), Oasis Labs, Taurus SA, Teleport, and others.
2020

2121
Install with `go get github.com/fxamacker/cbor/v2` and `import "github.com/fxamacker/cbor/v2"`.
2222
See [Quick Start](#quick-start) to save time.
@@ -27,7 +27,7 @@ See [Quick Start](#quick-start) to save time.
2727

2828
CBOR is an [Internet Standard](https://en.wikipedia.org/wiki/Internet_Standard) by [IETF](https://www.ietf.org). It's used in other standards like [WebAuthn](https://en.wikipedia.org/wiki/WebAuthn) by [W3C](https://www.w3.org), [COSE (RFC 8152)](https://tools.ietf.org/html/rfc8152), [CWT (RFC 8392)](https://tools.ietf.org/html/rfc8392), [CDDL (RFC 8610)](https://datatracker.ietf.org/doc/html/rfc8610) and [more](CBOR_GOLANG.md).
2929

30-
[Reasons for choosing CBOR](https://github.com/fxamacker/cbor/wiki/Why-CBOR) vary by project. Some projects replaced protobuf, encoding/json, or encoding/gob with CBOR. For example, by replacing gRPC+protobuf with gRPC+CBOR.
30+
[Reasons for choosing CBOR](https://github.com/fxamacker/cbor/wiki/Why-CBOR) vary by project. Some projects replaced protobuf, encoding/json, encoding/gob, etc. with CBOR. For example, by replacing protobuf with CBOR in gRPC.
3131

3232
## Why fxamacker/cbor?
3333

@@ -1031,9 +1031,9 @@ __Over 375 tests__ must pass on 4 architectures before tagging a release. They
10311031

10321032
__Code coverage__ must not fall below 95% when tagging a release. Code coverage is above 98% (`go test -cover`) for cbor v2.3 which is among the highest for libraries (in Go) of this type.
10331033

1034-
__Coverage-guided fuzzing__ must pass 250+ million execs using a large corpus before tagging a release. Fuzzing is usually continued after the release is tagged and is manually stopped after reaching 1+ billion execs. Fuzzing uses a custom version of [fxamacker/cbor-fuzz](https://github.com/fxamacker/cbor-fuzz).
1034+
__Coverage-guided fuzzing__ must pass 1+ billion execs using a large corpus before tagging a release. Fuzzing is usually continued after the release is tagged and is manually stopped after reaching 1-3 billion execs. Fuzzing uses a customized version of [dvyukov/go-fuzz](https://github.com/dvyukov/go-fuzz).
10351035

1036-
To prevent delays to release schedules, fuzzing is not restarted for a release if changes are limited to docs and comments.
1036+
To prevent delays to release schedules, fuzzing is not restarted for a release if changes are limited to ci, docs, and comments.
10371037

10381038
<hr>
10391039

@@ -1088,7 +1088,7 @@ __Words of encouragement and support__
10881088

10891089

10901090
## License
1091-
Copyright © 2019-2021 [Faye Amacker](https://github.com/fxamacker).
1091+
Copyright © 2019-2022 [Faye Amacker](https://github.com/fxamacker).
10921092

10931093
fxamacker/cbor is licensed under the MIT License. See [LICENSE](LICENSE) for the full license text.
10941094

0 commit comments

Comments
 (0)