diff --git a/README.md b/README.md index 407d65f..2a9276a 100644 --- a/README.md +++ b/README.md @@ -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()) diff --git a/errors.go b/errors.go index 0579fab..c0b6bf3 100644 --- a/errors.go +++ b/errors.go @@ -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 @@ -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 { @@ -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") } @@ -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 diff --git a/errors_test.go b/errors_test.go index 86991a8..9373d91 100644 --- a/errors_test.go +++ b/errors_test.go @@ -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) + } +} diff --git a/example_test.go b/example_test.go index 12496da..7401e80 100644 --- a/example_test.go +++ b/example_test.go @@ -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 +}