aboutsummaryrefslogtreecommitdiffstats
path: root/vendor/github.com/breml/errchkjson/README.md
diff options
context:
space:
mode:
authorTaras Madan <tarasmadan@google.com>2022-09-05 14:27:54 +0200
committerGitHub <noreply@github.com>2022-09-05 12:27:54 +0000
commitb2f2446b46bf02821d90ebedadae2bf7ae0e880e (patch)
tree923cf42842918d6bebca1d6bbdc08abed54d274d /vendor/github.com/breml/errchkjson/README.md
parente6654faff4bcca4be92e9a8596fd4b77f747c39e (diff)
go.mod, vendor: update (#3358)
* go.mod, vendor: remove unnecessary dependencies Commands: 1. go mod tidy 2. go mod vendor * go.mod, vendor: update cloud.google.com/go Commands: 1. go get -u cloud.google.com/go 2. go mod tidy 3. go mod vendor * go.mod, vendor: update cloud.google.com/* Commands: 1. go get -u cloud.google.com/storage cloud.google.com/logging 2. go mod tidy 3. go mod vendor * go.mod, .golangci.yml, vendor: update *lint* Commands: 1. go get -u golang.org/x/tools github.com/golangci/golangci-lint@v1.47.0 2. go mod tidy 3. go mod vendor 4. edit .golangci.yml to suppress new errors (resolved in the same PR later) * all: fix lint errors hash.go: copy() recommended by gosimple parse.go: ent is never nil verifier.go: signal.Notify() with unbuffered channel is bad. Have no idea why. * .golangci.yml: adjust godot rules check-all is deprecated, but still work if you're hesitating too - I'll remove this commit
Diffstat (limited to 'vendor/github.com/breml/errchkjson/README.md')
-rw-r--r--vendor/github.com/breml/errchkjson/README.md131
1 files changed, 131 insertions, 0 deletions
diff --git a/vendor/github.com/breml/errchkjson/README.md b/vendor/github.com/breml/errchkjson/README.md
new file mode 100644
index 000000000..197959738
--- /dev/null
+++ b/vendor/github.com/breml/errchkjson/README.md
@@ -0,0 +1,131 @@
+# errchkjson
+
+[![Test Status](https://github.com/breml/errchkjson/actions/workflows/ci.yml/badge.svg)](https://github.com/breml/errchkjson/actions/workflows/ci.yml) [![Go Report Card](https://goreportcard.com/badge/github.com/breml/errchkjson)](https://goreportcard.com/report/github.com/breml/errchkjson) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Checks types passed to the json encoding functions. Reports unsupported types and reports occurrences where the check for the returned error can be omitted.
+
+Consider this [http.Handler](https://pkg.go.dev/net/http#Handler):
+
+```Go
+func JSONHelloWorld(w http.ResponseWriter, r *http.Request) {
+ response := struct {
+ Message string
+ Code int
+ }{
+ Message: "Hello World",
+ Code: 200,
+ }
+
+ body, err := json.Marshal(response)
+ if err != nil {
+ panic(err) // unreachable, because json encoding of a struct with just a string and an int will never return an error.
+ }
+
+ w.Write(body)
+}
+```
+
+Because the `panic` is not possible to happen, one might refactor the code like this:
+
+```Go
+func JSONHelloWorld(w http.ResponseWriter, r *http.Request) {
+ response := struct {
+ Message string
+ Code int
+ }{
+ Message: "Hello World",
+ Code: 200,
+ }
+
+ body, _ := json.Marshal(response)
+
+ w.Write(body)
+}
+```
+
+This is ok, as long as the struct is not altered in such a way, that could potentially lead
+to `json.Marshal` returning an error.
+
+`errchkjson` allows you to lint your code such that the above error returned from `json.Marshal`
+can be omitted while still staying safe, because as soon as an unsafe type is added to the
+response type, the linter will warn you.
+
+## Installation
+
+Download `errchkjson` from the [releases](https://github.com/breml/errchkjson/releases) or get the latest version from source with:
+
+```shell
+go get github.com/breml/errchkjson/cmd/errchkjson
+```
+
+## Usage
+
+### Shell
+
+Check everything:
+
+```shell
+errchkjson ./...
+```
+
+`errchkjson` also recognizes the following command-line options:
+
+The `-omit-safe` flag disables checking for safe returns of errors from json.Marshal
+
+## Types
+
+### Safe
+
+The following types are safe to use with [json encoding functions](https://pkg.go.dev/encoding/json), that is, the encoding to JSON can not fail:
+
+Safe basic types:
+
+* `bool`
+* `int`, `int8`, `int16`, `int32`, `int64`, `uint`, `uint8`, `uint16`, `uint32`, `uint64`, `uintptr`
+* `string`
+* Pointer type of the above listed basic types
+
+Composed types (struct, map, slice, array) are safe, if the type of the value is
+safe. For structs, only exported fields are relevant. For maps, the key needs to be either an integer type or a string.
+
+### Unsafe
+
+The following types are unsafe to use with [json encoding functions](https://pkg.go.dev/encoding/json), that is, the encoding to JSON can fail (return an error):
+
+Unsafe basic types:
+
+* `float32`, `float64`
+* `interface{}`
+* Pointer type of the above listed basic types
+
+Any composed types (struct, map, slice, array) containing an unsafe basic type.
+
+If a type implements the `json.Marshaler` or `encoding.TextMarshaler` interface (e.g. `json.Number`).
+
+### Forbidden
+
+Forbidden basic types:
+
+* `complex64`, `complex128`
+* `chan`
+* `func`
+* `unsafe.Pointer`
+
+Any composed types (struct, map, slice, array) containing a forbidden basic type. Any map
+using a key with a forbidden type (`bool`, `float32`, `float64`, `struct`).
+
+## Accepted edge case
+
+For `encoding/json.MarshalIndent`, there is a (pathological) edge case, where this
+function could [return an error](https://cs.opensource.google/go/go/+/refs/tags/go1.18:src/encoding/json/scanner.go;drc=refs%2Ftags%2Fgo1.18;l=181) for an otherwise safe argument, if the argument has
+a nesting depth larger than [`10000`](https://cs.opensource.google/go/go/+/refs/tags/go1.18:src/encoding/json/scanner.go;drc=refs%2Ftags%2Fgo1.18;l=144) (as of Go 1.18).
+
+## Bugs found during development
+
+During the development of `errcheckjson`, the following issues in package `encoding/json` of the Go standard library have been found and PR have been merged:
+
+* [Issue #34154: encoding/json: string option (struct tag) on string field with SetEscapeHTML(false) escapes anyway](https://github.com/golang/go/issues/34154)
+* [PR #34127: encoding/json: fix and optimize marshal for quoted string](https://github.com/golang/go/pull/34127)
+* [Issue #34268: encoding/json: wrong encoding for json.Number field with string option (struct tag)](https://github.com/golang/go/issues/34268)
+* [PR #34269: encoding/json: make Number with the ,string option marshal with quotes](https://github.com/golang/go/pull/34269)
+* [PR #34272: encoding/json: validate strings when decoding into Number](https://github.com/golang/go/pull/34272)