Documentation
¶
Overview ¶
Package errs wraps internal errors and analyzes them at a boundary.
It is the diagnostic layer only. Public errors are apperror values, which carry the catalog code clients branch on; package errors are sentinels that callers compare with errors.Is. errs adds what a boundary needs to write one useful record per unit of work: where the error was produced (a captured stack), who is at fault, structured attributes, and a redacted rendering of the whole chain.
Traversal follows Unwrap() error, Unwrap() []error and, for errors that implement only Cause() error, Cause(). apperror keeps its cause out of Unwrap on purpose, so errors.Is and errors.As do not cross a public error; Cause() lets diagnostics cross it without changing that.
Index ¶
- func Answer(ctx context.Context, err error) (*apperror.Error, apperror.Fault)
- func CallerEnded(ctx context.Context) bool
- func FaultOf(err error) apperror.Fault
- func Forwarded(err error) error
- func New(msg string, attrs ...slog.Attr) error
- func NewDependency(msg string, attrs ...slog.Attr) error
- func NewWithDepth(depth int, msg string, attrs ...slog.Attr) error
- func Recorded(err error) error
- func Recovered(v any) error
- func RedactURLs(text string) string
- func Remote(err error) error
- func Text(err error) string
- func WithTimeout(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc)
- func Wrap(err error, msg string, attrs ...slog.Attr) error
- func WrapDependency(err error, msg string, attrs ...slog.Attr) error
- func WrapDependencyWithDepth(depth int, err error, msg string, attrs ...slog.Attr) error
- func WrapWithDepth(depth int, err error, msg string, attrs ...slog.Attr) error
- type Frame
- type Report
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Answer ¶ added in v0.22.0
Answer is the public error a boundary answers err with, and the fault it attributes err to. ctx is the unit's own context; nil means no caller. Every transport renders its answer from it, in this order:
- The caller has ended and the chain holds a cancellation: canceled.
- The outermost catalog apperror on the chain, unless it came from a remote that refused a request this process sent and was not forwarded.
- The generic code for the fault: http.bad_request for a client fault, internal otherwise.
A native gRPC status takes part in the attribution but is never the answer. The answer of a nil err is nil.
func CallerEnded ¶
CallerEnded reports whether ctx has ended because its caller canceled it or its deadline passed: its cause is exactly context.Canceled or context.DeadlineExceeded. A context this process ended for its own reason, such as an idle timeout or a lost run, did not end by its caller. A nil ctx has no caller and never ends.
func FaultOf ¶
FaultOf is the fault Analyze attributes err to when no caller has canceled the unit. An RPC server sends it to its client with the error.
func Forwarded ¶
Forwarded declares that the caller deliberately passed end-user input to the downstream, so a remote client fault stays a client fault here.
func NewDependency ¶
NewDependency creates an error attributed to a dependency.
func NewWithDepth ¶
NewWithDepth is New with the recorded stack starting depth frames further up. A helper that builds one kind of error uses it so the source names the helper's caller.
func Recorded ¶ added in v0.22.0
Recorded marks a failure another result record in this process has already recorded: a nested unit that wrote its own record when it ended. An outer boundary still records it, at no more than WARN. The error value is unchanged.
func Recovered ¶
Recovered turns a value from recover into an internal error with a stack. Call it directly in the deferred function. The stack starts where the panic happened. The panic value can hold user data, so it is not part of the error text; only a runtime error keeps its description.
func RedactURLs ¶
RedactURLs removes the userinfo, query and fragment of every URL in text. Rendering a chain applies it; text from outside the process (an upstream error message) must go through it before it becomes an attribute. A URL that does not parse keeps only its scheme, since the rest may hold credentials.
func Remote ¶
Remote marks an error received from an internal RPC. The error value is unchanged: status.FromError and status.Code still read the received status.
func WithTimeout ¶
WithTimeout creates a timeout this process sets for itself. When it expires the context's cause is not context.DeadlineExceeded, so Analyze does not attribute the failure to the caller.
func Wrap ¶
Wrap adds context to err and keeps the chain; errors.Is and errors.As still see err. It returns nil when err is nil.
func WrapDependency ¶
WrapDependency wraps err and attributes it to a dependency.
func WrapDependencyWithDepth ¶
WrapDependencyWithDepth is WrapDependency with depth as in WrapWithDepth.
Types ¶
type Report ¶
type Report struct {
Fault apperror.Fault
Reason string
Text string
Source *Frame
Stack []Frame
Attrs []slog.Attr
Remote bool
RemoteFault apperror.Fault
Unlocated bool
Panic bool
// Recorded reports that a nested unit in this process has already
// recorded this failure (see Recorded).
Recorded bool
// contains filtered or unexported fields
}
Report is what Analyze concludes about an error chain at a boundary.
Source Files