Errors on the wire¶
An error that crosses a process boundary usually arrives as a string. Its
sentinel no longer matches, its hint is a fragment of text, and its kind is
gone. errors/wire exists so the receiving process can treat the error as the
sending one did.
One model, many formats¶
Every format translates between bytes and one model, and every decision about
what a layer becomes on the wire is made once, in wire, before any format sees
it. That is why two formats agree: they are not two implementations kept in step,
but two renderings of the same tree. The conformance suite holds a new format to
that.
JSON is in the core because it costs nothing new: this module already links
encoding/json through log/slog. Protobuf is a separate module, because it
brings a dependency nobody who does not use it should carry. Any other format is
someone's codec, built against the same schema.
The edge chooses, not the error¶
It is tempting to have the code that makes an error say how it should travel. It cannot know. The same error may leave one process as an HTTP body to a browser and as a gRPC detail to another service. The place it leaves knows, and so does the receiver, through what it says it accepts. So the choice is made at the edge, once, and errors carry no format at all.
A wrapper that encoded itself was tried, and it fails twice. json.Marshal sees
only the outermost value, so once anything wraps the error the encoding is lost
without complaint. And a type that marshals itself takes over slog's JSON
output as well.
Identity by registration¶
errors.Is compares pointers, and a pointer means nothing in another process.
So a sentinel's kind is its identity on the wire: NewSentinel registers the
instance under its kind, and a receiver that links the same package maps the
kind back to the same pointer. The standard library's own sentinels are
registered under reserved kinds, because ctx.Err() == context.Canceled is how
callers check them.
Strangers are kept, not dropped¶
A receiver will meet layers it has never heard of: a newer kind, or a wrapper from a package it does not link. Each decodes to a layer that keeps its message, its kind and everything below it, so every reader keeps working past it. A process that relays the error forwards that layer exactly as it arrived.
Untrusted by default¶
The bytes come from another process, which may be hostile or simply newer. So decoding is bounded, a malformed document fails rather than half-decodes, and a panic in a consumer's own codec fails that decode instead of the process. Stacks are not sent unless asked for, because a stack is a map of your code.
The decisions behind each of these are in spec 0003, errors that cross a process boundary, on this project's wiki.