A two-way migration bridge between the thin, shipped github.com/ubgo/goerr and the full github.com/ubgo/errx. Adopt errx incrementally — package by package — without a big-bang rewrite and without breaking code still written against goerr.
- Why
- Install
- Migration strategy
From— goerr → errxTo— errx → goerr- Field safety across the bridge
- API
goerr is small and already in production in some services. Rewriting everything at once is risky. This bridge lets a new module use the full errx model while still interoperating with callers and dependencies that produce or expect goerr — so the migration can be gradual and reversible.
go get github.com/ubgo/errx/contrib/goerrPulls github.com/ubgo/goerr and github.com/ubgo/errx.
- New / refactored code uses
errxdirectly. - At the boundary where inbound
goerrarrives (a dependency you haven't migrated), callshim.From(err)to lift it into a full*errx.Error— identity, messages, trace id, severity and key/values are preserved. - At the boundary where a not-yet-migrated caller expects
goerr, callshim.To(err)to hand back a*goerr.Error. - Delete the bridge calls module-by-module as both sides move to
errx.
import shim "github.com/ubgo/errx/contrib/goerr"
// inbound: dependency still returns *goerr.Error
func (s *Service) Handle(ctx context.Context) error {
if err := legacy.Do(ctx); err != nil {
return errx.Wrap(shim.From(err), "service: handle"). // now full errx
WithOwner("payments")
}
return nil
}
// outbound: a caller still expects *goerr.Error
func Adapt(err error) *goerr.Error { return shim.To(err) }shim.From(err) *errx.Error finds a *goerr.Error anywhere in the chain (errors.As) and maps:
| goerr | errx |
|---|---|
Message |
operator message |
MessageUser |
WithPublic |
Code |
WithCode |
TraceID |
WithTrace(id, "") |
Level |
WithSeverity (debug/info/warn/error/fatal) |
KV map |
unsafe fields (With) |
Data |
With("data", …) |
If no goerr is present the error is wrapped as-is. From(nil) returns nil.
shim.To(err) *goerr.Error maps an errx error back:
| errx | goerr |
|---|---|
| operator message | Message |
Public() (or operator if unset) |
MessageUser |
Code() |
WithCode |
SeverityOf() |
WithLevel |
TraceID() |
WithTraceID |
| safe fields | WithKVMap |
To(nil) returns nil.
To copies only WithSafe fields into goerr KV. Unsafe fields are dropped, never silently exposed through the bridge. From brings goerr KV/Data in as unsafe fields (redacted at trust boundaries by default) — mark them WithSafe explicitly if they are non-sensitive and you want them surfaced.
| Symbol | Purpose |
|---|---|
shim.From(err error) *errx.Error |
Lift inbound goerr (chain-aware) into a full errx error. |
shim.To(err error) *goerr.Error |
Convert an errx error back to goerr for un-migrated callers. |
See the root README for the full errx model.