Documentation
¶
Overview ¶
Package strictjson — the reader that bounds a document and remembers why it stopped.
Package strictjson decodes exactly one JSON document into a Go value, refusing everything the permissive decoder lets through, within a byte bound, with errors that never quote the input.
The universal codec's json format is encoding/json with its defaults: no size limit, unknown members silently dropped, a member matched to a field case-insensitively, a duplicated name resolved by whichever came last, and trailing data after the value ignored. Each of those is a way for one document to be read two ways — by this program and by whatever else parsed it first — and none of them fails. This package is the other decoder, built on encoding/json/v2 whose defaults already refuse most of them:
- a document longer than the bound is refused before it is buffered past the bound;
- an object member the target does not declare is refused, and so is one that differs from a declared name only by case;
- a duplicated member name, invalid UTF-8, and anything after the one value are refused;
- a number out of the field's range is refused rather than wrapped.
Every refusal is a typed error whose text is a fixed sentence: the document's bytes appear in no Public, no Private and no wrapped cause. Where the document failed is available through PointerOf, as a JSON Pointer built from the document's own member names — a location, never a value.
Index ¶
- Constants
- func CheckArguments(v any, maxBytes int64) error
- func Decode(r io.Reader, v any, maxBytes int64) error
- func DecodeChecked(r io.Reader, v any, maxBytes int64, oversize func(error) bool) error
- func Misconfigured(argument string) error
- func PointerOf(err error) (pointer string, ok bool)
- func Unreadable(failure error) error
Constants ¶
const MaxPointerBytes int = 256
MaxPointerBytes bounds the JSON Pointer a refusal carries. A pointer is built from the document's member names, so its length is the document's to choose; past the bound it is cut back to the deepest ancestor that fits, which still points at the right place, just less precisely.
Variables ¶
This section is empty.
Functions ¶
func CheckArguments ¶
CheckArguments refuses the two calls no input can make succeed — a non-positive bound, and a v that is not a non-nil pointer — with DecodeMisconfigured naming the argument, and returns nil otherwise. Decode runs it first; a caller reading from something other than a plain reader (the HTTP form in the httpbody package) runs it before touching its input, so the same call is refused the same way through every door.
func Decode ¶
Decode reads exactly one JSON value from r into v, which must be a non-nil pointer, reading at most maxBytes bytes of it.
It refuses — with DocumentTooLarge, DocumentEmpty, DocumentMalformed, MemberUnknown, ValueMismatched or DocumentUnreadable — every document the package comment lists, and DecodeMisconfigured when maxBytes is not positive, v is not a non-nil pointer, or r is nil. On a refusal v may have been partly written; a caller that keeps v after an error keeps a half-decoded value.
A document longer than maxBytes is refused whatever the decoder made of the part it read: the truncation, not the prefix, is the finding. The reader is never read past maxBytes + 1 bytes.
func DecodeChecked ¶
DecodeChecked reads and decodes one bounded document from r into v, for a caller that has already refused what CheckArguments refuses and holds a non-nil reader. oversize recognises a read error that is itself a size refusal — http.MaxBytesError, for a request body — so it is reported as DocumentTooLarge rather than as a failed read; nil recognises none.
It is how the HTTP form reuses this decoder without this package naming net/http: the recogniser is the caller's, and so is the import.
func Misconfigured ¶
Misconfigured refuses a call before anything is read: DecodeMisconfigured, with the argument's name — never its value — as a field.
func PointerOf ¶
PointerOf returns where a document Decode refused went wrong — or one the httpbody package's DecodeRequest refused — as a JSON Pointer (RFC 6901), "" being the document itself, and reports whether err carries one.
The pointer is built from the document's own member names and array indices, so it is the input's text, bounded to MaxPointerBytes: a location, never a value. Render it as untrusted — escape it in HTML, quote it in a log.
func Unreadable ¶
Unreadable is the refusal of a reader that failed before the document ended: DocumentUnreadable, the origin, carrying the failure's TYPE as its cause field and never its message, which a reader may have built from the bytes it read. The HTTP form uses it for a body whose first read failed.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package httpbody decodes the JSON body of an HTTP request with the strict decoder of its parent package, adding the three things only an HTTP body has: a bound net/http enforces too, an empty body settled before anything else, and a media type that must declare JSON.
|
Package httpbody decodes the JSON body of an HTTP request with the strict decoder of its parent package, adding the three things only an HTTP body has: a bound net/http enforces too, an empty body settled before anything else, and a media type that must declare JSON. |