Skip to content

refactor!: capture stacks with the runtime package - #22

Merged
josuegiron merged 1 commit into
masterfrom
refactor/drop-go-errors
Nov 21, 2026
Merged

josuegiron merged 1 commit into
masterfrom
refactor/drop-go-errors

Conversation

@josuegiron

Copy link
Copy Markdown
Member

Scope

ERR-07 phase 3 (owner-approved 2026-11-21): remove the exported Error.Wrapper field (deprecated in v0.7.0) and the github.com/go-errors/errors dependency; stacks use the runtime package. Leaves out any other API change. Not a stack. Planned on top: a jgolang/log PR raising errors to v0.8.0 (log v1.7.4).

Reason

Wrapper *goerrors.Error tied this leaf module's public API to its only third-party dependency, which it used only to capture and format stacks; runtime.Callers/runtime.CallersFrames do that (KISS-01). log stopped reading Wrapper in v1.7.3. Decision recorded in docs/adr/0002-standard-library-stack-traces.md.

Changes

  • errors.go, functions.go: unexported wrapped error and stack *callStack replace Wrapper. Constructors capture up to 50 program counters with runtime.Callers (same skip, same cap as go-errors). StackTrace/StackTraceStr resolve frames with runtime.CallersFrames on every call and cache nothing on the shared value, so concurrent reads are race-free by construction (ERR-06). Package/name split matches go-errors, so the format is unchanged. The stack sits behind a pointer so Error stays comparable with ==.
  • go.mod: go-errors removed; go.sum is empty and deleted.
  • Tests: rewrote the tests that read Wrapper; added exact top-frame tests (both formats), 50-frame cap, nil receiver, inlined caller, compile-time comparability check. Added errors_benchmark_test.go.
  • README.md, ADR 0002.

Output differences

  • Non-inlined frames: identical (checked against go-errors before removing it: top level, sentinel, 60-deep recursion capped at 50 frames).
  • A function inlined into its caller now appears with its real name and line; go-errors repeated the callee or named an unrelated function such as stdlib errors.New for such frames.
  • Wrapping a *goerrors.Error now captures a fresh stack instead of reusing its stack.

Verification

  • gofmt -l . empty, go vet ./..., go test -race ./..., govulncheck ./... clean; go list -m all lists only this module; go doc -all . diff shows only the removed field.
  • Benchmarks (benchstat, n=6): allocs/op NewC 5→4, With 6→5, StackTrace 17→17, StackTraceStr 13→13; B/op NewC 624→560, With 632→568, StackTrace 984→1168, StackTraceStr 1344→1528 (the runtime.CallersFrames iterator). Time: an interleaved run shows no significant change (noise on this machine is ±15–30%).

Release notes (v0.8.0)

Breaking:

  • Error.Wrapper is removed. Use Detail for the wrapped cause's text and StackTrace/StackTraceStr for the stack.
  • If you also use github.com/jgolang/log, require log v1.7.3 or later. Older log releases read Wrapper and fail to compile against v0.8.0.

Changed:

  • No third-party dependencies: github.com/go-errors/errors is gone (its global MaxStackDepth no longer affects this module; the depth is fixed at 50).
  • Inlined callers appear in stack traces with their real name and line.
  • Wrapping a *goerrors.Error captures a new stack at the call site.
  • Creating an error makes one allocation less; reading a stack trace allocates about 184 bytes more.

🤖 Generated with Claude Code

Remove the exported Wrapper field, deprecated in v0.7.0, and the
github.com/go-errors/errors dependency. Constructors capture program
counters with runtime.Callers (at most 50 frames) and StackTrace and
StackTraceStr resolve them with runtime.CallersFrames on every call,
caching nothing on the shared error, so concurrent reads stay race-free.
Frames keep their package, name, file and line format. A function
inlined into its caller now shows its real name and line.

BREAKING CHANGE: Error.Wrapper is removed; use Detail, StackTrace or
StackTraceStr. github.com/jgolang/log must be v1.7.3 or later.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@josuegiron
josuegiron merged commit 2d5d1e4 into master Nov 21, 2026
2 checks passed
@josuegiron
josuegiron deleted the refactor/drop-go-errors branch November 21, 2026 19:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant