Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,9 @@ Built-in codes carry kinds: `ValRequired`, `ValFormat` and `AppValidation` are v

## Stack Traces

`StackTraceStr` returns a text stack trace. `StackTrace` returns a `slog.Value` group that can be attached to structured logs. Stack traces can contain source paths and function names, so keep them in internal logs only.
`StackTraceStr` returns a text stack trace. `StackTrace` returns a `slog.Value` group that can be attached to structured logs. `Detail` returns the text of the wrapped cause without the error's own code and friendly message (a wrapped `*Error` keeps its own `[code](message)` prefix). Stack traces and details can contain source paths, function names and other implementation details, so keep them in internal logs only.

The exported `Wrapper` field is deprecated since v0.7.0 and will be removed in v0.8.0: use `Detail` for the cause's text and `StackTrace` or `StackTraceStr` for the stack.

```go
slog.Error("operation failed", "error", err, "stack", err.(*jerrors.Error).StackTrace())
Expand Down
27 changes: 24 additions & 3 deletions errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@ import (

// Error wraps another error with a stack trace, optional friendly message, and optional code.
type Error struct {
// Wrapper holds the wrapped cause and the stack trace captured with it.
//
// Deprecated: use Detail for the wrapped cause's text and StackTrace or
// StackTraceStr for the stack trace. Wrapper exposes
// github.com/go-errors/errors and will be removed in v0.8.0.
Wrapper *errors.Error
Message string // A non-technical, user-friendly message describing the error.
cause error
Expand All @@ -20,6 +25,22 @@ type Error struct {
defined bool
}

// Detail returns the full text of the error this Error wraps, without this
// Error's own code and friendly message: the formatted text for New and NewC,
// the sentinel's message for Wrap of a Define sentinel, and otherwise the text
// of the wrapped error, which includes its own code prefix and message when it
// is an *Error. It returns "" for a nil receiver and for an error without a
// stack trace, such as a Define sentinel.
// Like the stack trace, it can contain implementation details; keep it in
// internal logs and return PublicMessage to users.
func (err *Error) Detail() string {
if err == nil || err.Wrapper == nil {
return ""
}

return err.Wrapper.Error()
}

// StackTraceStr returns the stack trace captured when this Error was created.
func (err *Error) StackTraceStr() string {
if err == nil || err.Wrapper == nil {
Expand All @@ -34,11 +55,11 @@ func (err *Error) StackTraceStr() string {
buffer.WriteString(err.Message)
buffer.WriteString("\n\n")
buffer.WriteString("· Cause: ")
buffer.WriteString(err.Wrapper.Error())
buffer.WriteString(err.Detail())
buffer.WriteString("\n\n")
} else {
buffer.WriteString("\n\n")
buffer.WriteString(err.Wrapper.Error())
buffer.WriteString(err.Detail())
buffer.WriteString("\n\n")
}

Expand Down Expand Up @@ -146,7 +167,7 @@ func (err *Error) prefix() string {
// the same code, its own prefix and the separator after it are cut from its
// text, and onlyPrefix reports that nothing else was left to print.
func (err *Error) wrappedText() (text string, onlyPrefix bool) {
full := err.Wrapper.Error()
full := err.Detail()
inner, ok := err.Wrapper.Err.(*Error)
if !ok || inner == nil || !sameCode(inner.Code, err.Code) {
return full, false
Expand Down
38 changes: 38 additions & 0 deletions errors_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -616,3 +616,41 @@ func expectedFrameTexts(err *Error) (string, []slog.Attr) {
}
return buffer.String(), attrs
}

func TestDetailReturnsWrappedCauseText(t *testing.T) {
inner := NewC(codes.AppValidation, "title is empty")
tests := []struct {
name string
err error
want string
}{
{name: "New", err: New("disk %s", "full"), want: "disk full"},
{name: "NewC", err: NewC(codes.AppValidation, "title is empty"), want: "title is empty"},
{name: "Wrap of a plain error", err: Wrap(stderrors.New("timeout")), want: "timeout"},
{name: "With", err: With(stderrors.New("timeout"), "loading board"), want: "timeout"},
{name: "WithC", err: WithC(stderrors.New("timeout"), codes.AppProcessing, "loading board"), want: "timeout"},
{name: "WrapC of an *Error without cause", err: WrapC(inner, codes.AppProcessing), want: inner.Error()},
{name: "WrapC of an *Error wraps its cause", err: WrapC(With(stderrors.New("timeout"), "loading"), codes.AppProcessing), want: "timeout"},
{name: "With of an *Error", err: With(inner, "saving"), want: inner.Error()},
{name: "Wrap of a Define sentinel", err: Wrap(errDefinedTitleRequired), want: "title is required"},
{name: "Define sentinel has no detail", err: errDefinedTitleRequired, want: ""},
}

for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
got := test.err.(*Error).Detail()

if got != test.want {
t.Fatalf("Expected %q, got %q", test.want, got)
}
})
}
}

func TestDetailOfNilErrorIsEmpty(t *testing.T) {
var err *Error

if got := err.Detail(); got != "" {
t.Fatalf("Expected empty detail, got %q", got)
}
}
11 changes: 11 additions & 0 deletions example_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,14 @@ func ExampleKindOf() {
// validation
// true
}

func ExampleError_Detail() {
err := jerrors.With(stderrors.New("connection refused"), "loading board")

var coded *jerrors.Error
if stderrors.As(err, &coded) {
fmt.Println(coded.Detail())
}
// Output:
// connection refused
}
Loading