The wire package¶
gitlab.com/phpboyscout/go/errors/wire encodes and decodes errors from this
module. The full API is on
pkg.go.dev; this
page lists what a caller needs at a glance and the rules behind it.
Encoding and decoding¶
| Call | Does |
|---|---|
Marshal(err, codec, opts...) |
encodes err with one codec |
Unmarshal(b, codec, opts...) |
decodes b, bounded as untrusted input |
NewEncoder(codecs, opts...) and Encode(err, accept, opts...) |
chooses a codec by an Accept value, the first codec being the default |
NewReaders(codecs, opts...) and Decode(mediaType, b, opts...) |
chooses a codec by the sender's media type, ignoring its parameters |
FromError(err, opts...) and (*Error).ToError(opts...) |
builds or reads the model directly, for a codec or a carrier of your own |
Options given to NewEncoder or NewReaders are defaults. Options given to a
call override them for that call only.
A codec's media type is its own: an Accept of plain application/json
matches none of the built-in codecs, while application/* and */* do. Where
two codecs declare the same media type, the first is used.
Codecs¶
| Codec | Media type |
|---|---|
wire.JSON |
application/vnd.phpboyscout.error.v1+json |
wire.JSON writes protojson's rendering of the schema, reads what protojson
reads (a 64-bit integer as a string or a number, a form by name or number), and
refuses what protojson refuses, including a duplicated member name. It scans a
document's tokens against the bounds before decoding it, so a hostile document is
refused before it is allocated.
Any type with MediaType, Encode and Decode is a codec; wiretest.Run
checks one. A codec that also implements BoundedDecoder is handed the bounds
while it parses.
Options¶
| Option | Default | Bounds |
|---|---|---|
WithStacks() |
off | sends each layer's stack, as module-relative frames |
WithMaxDepth(n) |
64 | how deep a tree may nest |
WithMaxLayers(n) |
1,024 | how many layers a tree may hold |
WithMaxText(n) |
64 KiB | any one string in a tree |
WithMaxItems(n) |
8,192 | attributes and frames in the whole tree, groups included |
WithMaxInputBytes(n) |
4 MiB | an encoded document |
Encoding applies the depth and layer bounds too, so an encoder never writes a tree a receiver on the defaults refuses.
Errors¶
| Error | When |
|---|---|
ErrNil |
encoding a nil error |
ErrBound |
a decode, or an encode's depth or layers, exceeds a bound |
ErrVersion |
a model version other than 1 |
ErrMalformed |
anything else wrong with the input, including an empty or null document, an unknown form and two payload members |
ErrNotAcceptable |
an Accept value admits none of an encoder's codecs |
ErrUnsupportedMediaType |
readers hold no codec for the declared media type |
A failed decode returns no tree, never part of one.
What a decoded error is¶
| Sent | Decodes to |
|---|---|
| a sentinel or leaf registered under its kind, with the same message | the registered instance |
context.Canceled, context.DeadlineExceeded, io.EOF, io.ErrUnexpectedEOF, io.ErrClosedPipe, fs.ErrNotExist, fs.ErrExist, fs.ErrPermission, fs.ErrClosed |
the instance itself |
a layer whose kind has a registered LayerCodec |
whatever that codec's Decode returns |
| anything else | a layer reporting the sent kind, payload and causes, which re-encodes exactly |
Every decoded layer answers Hints, Details, Attrs, KindOf, Is and
RemoteFrames as the original did, and logs and prints through this module's
renderers. Where the original's outermost layer was a foreign type with no
renderer of its own, such as an fmt.Errorf wrapper, the decoded error logs as a
structured group and %+v shows its hints, where the original showed only its
message.
A message containing invalid UTF-8 crosses with each bad byte replaced by U+FFFD, since every codec's strings must be valid.
Registration¶
| Call | Registers |
|---|---|
errors.NewSentinel(kind, msg) |
the sentinel, under its kind |
RegisterLeaf(kind, err) |
a leaf not built with NewSentinel |
RegisterLayer(kind, codec) |
a codec for a wrapper type of your own |
Conflicts() |
lists every kind that will not decode to its registration, and why |
A registration is refused, and listed by Conflicts, when its kind is under
errors. or std. (reserved for the core), when its value cannot be compared
with ==, or when the instance is already registered under another kind. An
instance always encodes under the kind it was first registered with.
Messages¶
Each layer's message is rebuilt from its causes rather than re-sent at every depth:
| Form | Message |
|---|---|
FormLeaf |
its text |
FormTransparent |
its one cause's message |
FormPrefix |
its text, ": ", its one cause's message |
FormJoined |
its causes' messages, joined by newlines |
FormFull |
its text, whatever its causes say |
The set is closed. Any other form fails the decode.
Attribute values¶
An slog value of kind String, Int64, Uint64, Float64, Bool,
Duration, Time or Group keeps its kind. KindAny and KindLogValuer are
resolved and sent as their string, because an arbitrary Go value has no portable
form. Attach a value as a number if it must arrive as one.
A time arrives in UTC, since the schema's timestamp has no zone. One outside the years 1 to 9999, which the schema cannot hold, arrives as its RFC 3339 string.
The schema¶
proto/phpboyscout/errors/v1/error.proto in this module is the contract every
codec implements. It changes by protobuf's rules: fields are added, never
renamed or renumbered, and every reader ignores one it does not know.