blob: a5af00e7ff271af0e94ba511432b2b227122bcc8 [file] [log] [blame] [edit]
// skerr provides functions related to error reporting and stack traces.
package skerr
import (
"fmt"
"runtime"
"strings"
)
// StackTrace identifies a filename (base filename only) and line number.
type StackTrace struct {
File string
Line int
}
func (st *StackTrace) String() string {
return fmt.Sprintf("%s:%d", st.File, st.Line)
}
// CallStack returns a slice of StackTrace representing the current stack trace.
// The lines returned start at the depth specified by startAt: 0 means the call to CallStack,
// 1 means CallStack's caller, 2 means CallStack's caller's caller and so on. height means how
// many lines to include, counting deeper into the stack, with zero meaning to include all stack
// frames. If height is non-zero and there aren't enough stack frames, a placeholder value is used
// instead.
//
// Suppose the stacktrace looks like:
// skerr.go:300 <- the call to runtime.Caller in skerr.CallStack
// alpha.go:123
// beta.go:456
// gamma.go:789
// delta.go:123
// main.go: 70
// A typical call may look like skerr.CallStack(6, 1), which returns
// [{File:alpha.go, Line:123}, {File:beta.go, Line:456},...,
//
// {File:main.go, Line:70}, {File:???, Line:1}], omitting the not-helpful reference to
//
// CallStack and padding the response with a placeholder value, since the stack was not tall enough to
// show 6 items, starting at the second one.
func CallStack(height, startAt int) []StackTrace {
stack := []StackTrace{}
for i := 0; ; i++ {
_, file, line, ok := runtime.Caller(startAt + i)
if !ok {
if height <= 0 {
break
}
file = "???"
line = 1
} else {
slash := strings.LastIndex(file, "/")
if slash >= 0 {
file = file[slash+1:]
}
}
stack = append(stack, StackTrace{File: file, Line: line})
if height > 0 && len(stack) >= height {
break
}
}
return stack
}
// ErrorWithContext contains an original error with context info and a stack trace. It implements
// the error interface.
type ErrorWithContext struct {
// Wrapped is the original error. Never nil.
Wrapped error
// CallStack captures the caller's stack at the time the ErrorWithContext was created; most recent
// call first.
CallStack []StackTrace
// Context contains additional info from calls to Wrapf. The slice is in order of calls to Wrapf,
// which Error() prints in reverse.
Context []string
}
func (err *ErrorWithContext) Error() string {
var out strings.Builder
for i := len(err.Context) - 1; i >= 0; i-- {
_, _ = out.WriteString(err.Context[i])
_, _ = out.WriteString(": ")
}
_, _ = out.WriteString(err.Wrapped.Error())
if len(err.CallStack) > 0 {
_, _ = out.WriteString(". At")
for _, st := range err.CallStack {
_, _ = fmt.Fprintf(&out, " %s:%d", st.File, st.Line)
}
}
return out.String()
}
// Unwrap allows unwrapping an error as implemented in the `errors` standard
// library.
func (err *ErrorWithContext) Unwrap() error {
return err.Wrapped
}
func tryCast(err error) (*ErrorWithContext, bool) {
if wrapper, ok := err.(*ErrorWithContext); ok {
return wrapper, true
} else {
return nil, false
}
}
func wrap(err error, startAt int) error {
if _, ok := tryCast(err); ok {
return err
}
return &ErrorWithContext{
Wrapped: err,
CallStack: CallStack(0, startAt),
}
}
// Wrap adds stack trace info to err, if not already present. The return value will be of type
// ErrorWithContext. If err is nil, nil is returned instead.
func Wrap(err error) error {
if err == nil {
return nil
}
return wrap(err, 3)
}
// Unwrap returns the original error if err is ErrWithContext, otherwise just returns err.
func Unwrap(err error) error {
if wrapper, ok := tryCast(err); ok {
return wrapper.Wrapped
}
return err
}
// Fmt is equivalent to Wrap(fmt.Errorf(...)).
func Fmt(fmtStr string, args ...interface{}) error {
return wrap(fmt.Errorf(fmtStr, args...), 3)
}
// Wrapf adds context and stack trace info to err. Existing stack trace info will be preserved. The
// return value will be of type ErrorWithContext.
// Example: sklog.Wrapf(err, "When loading %d items from %s", count, url)
//
// If err is nil, nil is returned instead.
func Wrapf(err error, fmtStr string, args ...interface{}) error {
if err == nil {
return nil
}
newContext := fmt.Sprintf(fmtStr, args...)
if wrapper, ok := tryCast(err); ok {
callStack := wrapper.CallStack
if len(callStack) == 0 {
callStack = CallStack(0, 2)
}
return &ErrorWithContext{
Wrapped: wrapper.Wrapped,
CallStack: callStack,
Context: append(wrapper.Context, newContext),
}
} else {
return &ErrorWithContext{
Wrapped: err,
CallStack: CallStack(0, 2),
Context: []string{newContext},
}
}
}