Skip to content

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.