tailscale/util/vizerror/vizerror.go

83 lines
2.3 KiB
Go
Raw Permalink Normal View History

// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
// Package vizerror provides types and utility funcs for handling visible errors
// that are safe to display to end users.
package vizerror
import (
"errors"
"fmt"
)
// Error is an error that is safe to display to end users.
type Error struct {
publicErr error // visible to end users
wrapped error // internal
}
// Error implements the error interface. The returned string is safe to display
// to end users.
func (e Error) Error() string {
return e.publicErr.Error()
}
// New returns an error that formats as the given text. It always returns a vizerror.Error.
func New(publicMsg string) error {
err := errors.New(publicMsg)
return Error{
publicErr: err,
wrapped: err,
}
}
// Errorf returns an Error with the specified publicMsgFormat and values. It always returns a vizerror.Error.
//
// Warning: avoid using an error as one of the format arguments, as this will cause the text
// of that error to be displayed to the end user (which is probably not what you want).
func Errorf(publicMsgFormat string, a ...any) error {
err := fmt.Errorf(publicMsgFormat, a...)
return Error{
publicErr: err,
wrapped: err,
}
}
// Unwrap returns the underlying error.
//
// If the Error was constructed using [WrapWithMessage], this is the wrapped (internal) error
// and not the user-visible error message.
func (e Error) Unwrap() error {
return e.wrapped
}
// Wrap wraps publicErr with a vizerror.Error.
//
// Deprecated: this is almost always the wrong thing to do. Are you really sure
// you know exactly what err.Error() will stringify to and be safe to show to
// users? [WrapWithMessage] is probably what you want.
func Wrap(publicErr error) error {
if publicErr == nil {
return nil
}
return Error{publicErr: publicErr, wrapped: publicErr}
}
// WrapWithMessage wraps the given error with a message that's safe to display
// to end users. The text of the wrapped error will not be displayed to end
// users.
//
// WrapWithMessage should almost always be preferred to [Wrap].
func WrapWithMessage(wrapped error, publicMsg string) error {
return Error{
publicErr: errors.New(publicMsg),
wrapped: wrapped,
}
}
// As returns the first vizerror.Error in err's chain.
func As(err error) (e Error, ok bool) {
ok = errors.As(err, &e)
return
}