README
¶
errx
errx is a structured error handling library for Go built on top of errorx. It provides two cross-cutting error properties — a machine-readable reason code and a list of human remediation hints — plus helpers to attach and extract them.
Features
- Machine-readable
Reasoncodes for programmatic error branching - Human-readable remediation hints attached to errors
- Cause-chain traversal through both errorx and
errors.Unwraplayers Format()renderer for CLI/diagnostic output with resolution blocks
Installation
go get github.com/automa-saga/errx
Usage
package main
import (
"fmt"
"os"
"github.com/joomcode/errorx"
"github.com/automa-saga/errx"
)
var (
errNS = errorx.NewNamespace("myapp")
errConfigLoad = errNS.NewType("config_load")
)
const ReasonConfigMissing errx.Reason = "ConfigMissing"
func main() {
// Create a structured error with a reason code and remediation hints.
err := errx.Decorate(
errConfigLoad.New("config file not found: app.yaml"),
ReasonConfigMissing,
"Create app.yaml in the working directory",
"Copy from app.yaml.example and fill in required values",
)
// Extract reason for programmatic branching.
if reason, ok := errx.ReasonOf(err); ok {
fmt.Printf("reason = %s\n", reason)
}
// Render the full error with resolution block for a human.
fmt.Fprintln(os.Stderr, errx.Format(err))
}
Output:
reason = ConfigMissing
myapp.config_load: config file not found: app.yaml {reason: ConfigMissing}
Resolution:
- Create app.yaml in the working directory
- Copy from app.yaml.example and fill in required values
API
| Function | Description |
|---|---|
WithReason(err, reason) |
Attach a Reason code to an error |
WithHints(err, hints...) |
Attach remediation hints to an error |
Decorate(err, reason, hints...) |
Attach both reason and hints in one call |
ReasonOf(err) |
Extract the Reason from anywhere in the cause chain |
Hints(err) |
Extract hints from anywhere in the cause chain |
Format(err) |
Render error + resolution block for human display |
License
Apache License 2.0. See the LICENSE file for details.
Documentation
¶
Overview ¶
Package errx provides structured error handling on top of github.com/joomcode/errorx. It owns two cross-cutting error properties — a machine-readable reason code and a list of human remediation hints — plus helpers to attach and extract them.
Convention ¶
Each subsystem package declares its own errorx namespace and a small set of typed errors in a local errors.go, e.g.:
var (
errNS = errorx.NewNamespace("uc")
errManifestInvalid = errNS.NewType("manifest_invalid")
errK8sAPI = errNS.NewType("k8s_api_failed", errorx.Temporary())
)
Errors are created from those types and decorated with a reason + hints:
return errx.WithHints(
errx.WithReason(errManifestInvalid.Wrap(err, "parse %s", path), "ManifestInvalid"),
"Regenerate the deployment package",
"Confirm manifests/consensus-node-components.yaml has schemaVersion: 1",
)
- The reason code is PascalCase so a log line, an error, and any /status
output line up on the same identifier.
- Hints are concrete next steps an operator can take; attach them only when
a meaningful remediation exists (config/disk/RBAC), not for internal bugs.
- Mark transient errors (worth a retry) with the errorx.Temporary() trait on
the type; terminal errors carry no such trait.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // PropertyReason carries the Reason code. It is printable, so it renders in // the error string for at-a-glance correlation. PropertyReason = errorx.RegisterPrintableProperty("reason") // PropertyResolution carries a []string of remediation hints — concrete next // steps an operator can take. It is surfaced by logging / diagnostic tooling // rather than embedded in the error message. PropertyResolution = errorx.RegisterProperty("resolution") )
Functions ¶
func Decorate ¶
Decorate attaches a reason code and optional hints in one call — the common case, equivalent to WithHints(WithReason(err, reason), hints...). Returns nil when err is nil.
func Format ¶
Format renders err for a human surface (a CLI failure, a fatal startup log): the full error message followed by a "Resolution:" block listing any attached remediation hints. When no hints are attached it returns err.Error() unchanged. Returns "" for a nil error.
func WithHints ¶
WithHints attaches remediation hints to err (err is wrapped if it is not already an errorx error). A call with no hints returns err unchanged.
func WithReason ¶
WithReason attaches a Reason code to err. err should already be an errorx error (from a Type.New/.Wrap); a plain error is wrapped so the reason is never silently dropped. Returns nil when err is nil.
Types ¶
type Reason ¶
type Reason string
Reason is a stable, machine-readable error/condition code. Callers define their own vocabulary as typed constants (e.g. `const ReasonX errx.Reason = "X"`) so reason codes are enumerable in one place and typo-safe at call sites. The convention is PascalCase so an error, its log line, and any status output share one identifier.
Source Files
Directories