Documentation
¶
Overview ¶
Package errors is a fork of `github.com/go-errors/errors` that adds support for gRPC status codes, public messages, as well as stack-traces.
This is particularly useful when you want to understand the state of execution when an error was returned unexpectedly.
It provides the type *Error which implements the standard golang error interface, so you can use this library interchangably with code that is expecting a normal error return.
For example:
package crashy
import "github.com/go-errors/errors"
var Crashed = errors.Errorf("something really bad just happened")
func Crash() error {
return errors.NewC(Crashed, codes.Internal).
WithUserPresentableMessage("An unknown error occurred")
}
This can be called as follows:
package main
import (
"crashy"
"fmt"
"github.com/go-errors/errors"
)
func main() {
err := crashy.Crash()
if err != nil {
if errors.Is(err, crashy.Crashed) {
fmt.Println(err.(*errors.Error).ErrorStack())
} else {
panic(err)
}
}
}
Index ¶
- Variables
- func As(err error, target interface{}) bool
- func Code(err error) codes.Code
- func Codef(code codes.Code, format string, a ...interface{}) error
- func Errorf(format string, a ...interface{}) error
- func HTTPStatusCode(err error) int
- func Is(e error, original error) bool
- func Join(errs ...error) error
- func MaybeWrap(e interface{}, skip int) error
- func Unwrap(err error) error
- type Error
- func Mark(e interface{}, skip int) *Error
- func New(e interface{}) *Error
- func NewC(e interface{}, code codes.Code) *Error
- func ParsePanic(text string) (*Error, error)
- func ParseStack(b []byte) (*Error, error)
- func WithCode(err error, code codes.Code) *Error
- func WithDetails(err error, details ...protoiface.MessageV1) *Error
- func WithHTTPStatusCode(err error, code int) *Error
- func WithUserPresentableMessage(err error, userPresentableMessage string, args ...any) *Error
- func Wrap(e interface{}, skip int) *Error
- func WrapPrefix(e interface{}, prefix string, skip int) *Error
- func (err *Error) Append(str string) *Error
- func (err *Error) Callers() []uintptr
- func (err *Error) Code() codes.Code
- func (err *Error) Details() []protoiface.MessageV1
- func (err *Error) Error() string
- func (err *Error) ErrorStack() string
- func (err *Error) GRPCStatus() *status.Status
- func (err *Error) HTTPStatusCode() int
- func (err *Error) MinimalStack(skip, length int) []string
- func (err *Error) Stack() []byte
- func (err *Error) StackFrames() []StackFrame
- func (err *Error) TypeName() string
- func (err *Error) Unwrap() error
- func (err *Error) UserPresentableMessage() string
- func (err *Error) WithCode(code codes.Code) *Error
- func (err *Error) WithDetails(details ...protoiface.MessageV1) *Error
- func (err *Error) WithHTTPStatusCode(code int) *Error
- func (err *Error) WithUserPresentableMessage(userPresentableMessage string, args ...any) *Error
- type StackFrame
Constants ¶
This section is empty.
Variables ¶
var MaxStackDepth = 50
The maximum number of stackframes on any error.
Functions ¶
func As ¶
As finds the first error in err's tree that matches target, and if one is found, sets target to that error value and returns true. Otherwise, it returns false.
For more information see stdlib errors.As.
func Code ¶
Code returns a gRPC status code for an error. If the error is nil, it returns codes.OK. If error exposes a `Code()` method, it is returned. Otherwise codes.Internal is returned.
func Errorf ¶
Errorf creates a new error with the given message. You can use it as a drop-in replacement for fmt.Errorf() to provide descriptive errors in return values.
func HTTPStatusCode ¶
HTTPStatusCode returns an HTTP status code for an error. If the error is nil, it returns http.StatusOK. If error exposes a `HTTPStatusCode()` method, it is returned. Otherwise http.StatusInternalServerError is returned.
func Is ¶
Is detects whether the error is equal to a given error. Errors are considered equal by this function if they are matched by errors.Is or if their contained errors are matched through errors.Is.
func Join ¶
Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if every value in errs is nil. The error formats as the concatenation of the strings obtained by calling the Error method of each element of errs, with a newline between each string.
A non-nil error returned by Join implements the Unwrap() []error method.
For more information see stdlib errors.Join.
func MaybeWrap ¶
MaybeWrap makes an Error from the given value. Nil is passed through safely to avoid nil pointer problems with the Error struct.
func Unwrap ¶
Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.
Unwrap only calls a method of the form "Unwrap() error". In particular Unwrap does not unwrap errors returned by Join.
For more information see stdlib errors.Unwrap.
Types ¶
type Error ¶
type Error struct {
Err error
// contains filtered or unexported fields
}
Error is an error with an attached stacktrace. It can be used wherever the builtin error interface is expected.
func Mark ¶
Mark takes an error and sets the stack trace from the point it was called, overriding any previous stack trace that may have been set. The skip parameter indicates how far up the stack to start the stacktrace. 0 is from the current call, 1 from its caller, etc.
func New ¶
func New(e interface{}) *Error
New makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The stacktrace will point to the line of code that called New.
func ParsePanic ¶
ParsePanic allows you to get an error object from the output of a go program that panicked. This is particularly useful with https://github.com/mitchellh/panicwrap.
func ParseStack ¶
ParseStack is intended to be used with the results of `debug.Stack` this is a hack for now and should be improved.
func WithCode ¶
WithCode takes an error and adds a gRPC status code to it. If the error is not already an `Error`, it will be wrapped in one.
func WithDetails ¶
func WithDetails(err error, details ...protoiface.MessageV1) *Error
WithDetails takes an error and adds gRPC details to it. If the error is not already an `Error`, it will be wrapped in one.
func WithHTTPStatusCode ¶
WithHTTPStatusCode takes an error and adds an explicit HTTP status code to it, overriding the HTTP status mapped from the gRPC code.
func WithUserPresentableMessage ¶
WithUserPresentableMessage takes an error message and adds a public message to it. If the error is not already an `Error`, it will be wrapped in one. The user presentable message is what Prefab will return to the client.
func Wrap ¶
Wrap makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The skip parameter indicates how far up the stack to start the stacktrace. 0 is from the current call, 1 from its caller, etc.
func WrapPrefix ¶
WrapPrefix makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The prefix parameter is used to add a prefix to the error message when calling Error(). The skip parameter indicates how far up the stack to start the stacktrace. 0 is from the current call, 1 from its caller, etc.
func (*Error) Callers ¶
Callers satisfies the bugsnag ErrorWithCallerS() interface so that the stack can be read out.
func (*Error) Details ¶
func (err *Error) Details() []protoiface.MessageV1
Details returns the gRPC details associated with the error.
func (*Error) ErrorStack ¶
ErrorStack returns a string that contains both the error message and the callstack.
func (*Error) GRPCStatus ¶
GRPCStatus returns a gRPC status object for the error.
func (*Error) HTTPStatusCode ¶
HTTPStatusCode returns the HTTP status code that should be returned to the client. If a code is set, it will be used, otherwise a default will be returned based on the gRPC code.
func (*Error) MinimalStack ¶
MinimalStack returns a minimal stack trace suitable for printing in logs.
func (*Error) Stack ¶
Stack returns the callstack formatted the same way that go does in runtime/debug.Stack().
func (*Error) StackFrames ¶
func (err *Error) StackFrames() []StackFrame
StackFrames returns an array of frames containing information about the stack.
func (*Error) UserPresentableMessage ¶
UserPresentableMessage returns the error string that should be returned to the client.
func (*Error) WithDetails ¶
func (err *Error) WithDetails(details ...protoiface.MessageV1) *Error
WithDetails sets the gRPC details associated with the error.
func (*Error) WithHTTPStatusCode ¶
WithHTTPStatusCode sets the HTTP status code that should be returned to the client.
type StackFrame ¶
type StackFrame struct {
// The path to the file containing this ProgramCounter
File string
// The LineNumber in that file
LineNumber int
// The Name of the function that contains this ProgramCounter
Name string
// The Package that contains this function
Package string
// The underlying ProgramCounter
ProgramCounter uintptr
}
A StackFrame contains all necessary information about to generate a line in a callstack.
func NewStackFrame ¶
func NewStackFrame(pc uintptr) StackFrame
NewStackFrame popoulates a stack frame object from the program counter.
func (*StackFrame) Func ¶
func (frame *StackFrame) Func() *runtime.Func
Func returns the function that contained this frame.
func (*StackFrame) SourceLine ¶
func (frame *StackFrame) SourceLine() (string, error)
SourceLine gets the line of code (from File and Line) of the original source if possible.
func (*StackFrame) String ¶
func (frame *StackFrame) String() string
String returns the stackframe formatted in the same way as go does in runtime/debug.Stack().
Source Files