clierr

Documentation

Overview

Package clierr centralizes how command errors map to user-facing messages and process exit codes, so main can stay a thin shell and every command surfaces failures consistently.

Index

• Constants
• func Code(err error) int
• func Friendly(err error) string
• func IsBrokenPipe(err error) bool
• func IsConnErr(err error) bool
• func IsIgnorableBrokenPipe(err error) bool
• func IsSilent(err error) bool
• func IsUsageErr(err error) bool
• func Silent(code int) error
• func WithCode(code int, err error) error
• func WithPartialResult(err error) error
• type Coded
  • func (e *Coded) Error() string
  • func (e *Coded) Unwrap() error
• type PartialResult
  • func (e *PartialResult) Error() string
  • func (e *PartialResult) Unwrap() error

Constants

const (
	CodeError      = 1   // generic runtime failure (load/parse errors, I/O, etc.)
	CodeUsage      = 2   // bad invocation (unknown flag, wrong arg count)
	CodeTestFailed = 3   // tests ran and some failed: `model test` (or coverage below --coverage-min), or `assertions test`
	CodeNetwork    = 4   // could not reach the OpenFGA server
	CodeCanceled   = 130 // interrupted (Ctrl-C); 128 + SIGINT
)

Process exit codes. Scripts and CI can branch on these instead of parsing stderr text.

Functions

func Code

func Code(err error) int

Code resolves the exit code for err: an explicit Coded wins, then an interruption maps to CodeCanceled, a bad invocation to CodeUsage, a network failure to CodeNetwork, and anything else to CodeError.

func Friendly

func Friendly(err error) string

Friendly renders err for a human: connection failures get an actionable hint (with the original error kept for detail); everything else is returned as-is.

func IsBrokenPipe

func IsBrokenPipe(err error) bool

IsBrokenPipe reports that the downstream stdout consumer closed its end of a pipe. This is normal shell control flow (for example `ofga ... | head`), not an OpenFGA network failure.

func IsConnErr

func IsConnErr(err error) bool

IsConnErr reports whether err looks like a network-level failure (refused connection, DNS lookup failure, timeout) rather than a normal API error. It checks the idiomatic net.Error interface first, then falls back to matching well-known substrings for errors that don't implement it.

func IsIgnorableBrokenPipe

func IsIgnorableBrokenPipe(err error) bool

IsIgnorableBrokenPipe reports a plain stdout EPIPE that may be treated as a successful short read by a downstream consumer. Explicitly coded failures still win even if an output write also encountered EPIPE.

func IsSilent

func IsSilent(err error) bool

IsSilent reports whether err is a Silent error whose message was already surfaced to the user and should not be printed again.

func IsUsageErr

func IsUsageErr(err error) bool

IsUsageErr reports whether err is one of cobra's or pflag's flag/argument validation failures (missing required flag, unknown flag/command, wrong arg count). These are bad invocations, not runtime failures, so they map to CodeUsage and a "--help" hint.

pflag returns a distinct type for each flag-parsing failure, so those are matched structurally with errors.As. Cobra's own arg-count/required-flag/ unknown-command errors have no dedicated type — they're plain strings in a fixed format (args.go, command.go) — so matching is anchored to that exact prefix with strings.HasPrefix. An unanchored substring match would also catch unrelated errors that merely mention the same words, e.g. an OS EINVAL surfacing as "open <path>: invalid argument", or a wrapped server message containing "requires"/"accepts" mid-sentence.

func Silent

func Silent(code int) error

Silent tags an exit code for a failure the command has already reported to the user (e.g. a model-test "N/Total test(s) failed" summary line). main honors the exit code but prints nothing further, so the summary is not duplicated. Use WithCode instead when the error carries a message the user still needs to see.

func WithCode

func WithCode(code int, err error) error

WithCode tags err with a specific exit code. Returns nil for a nil error.

func WithPartialResult

func WithPartialResult(err error) error

WithPartialResult tags err as carrying partial-commit detail. Returns nil for a nil error.

Types

type Coded

type Coded struct {
	C   int
	Err error
}

Coded wraps an error with an explicit process exit code.

func (*Coded) Error

func (e *Coded) Error() string

func (*Coded) Unwrap

func (e *Coded) Unwrap() error

type PartialResult

type PartialResult struct {
	Err error
}

PartialResult marks an error from an interrupted bulk operation (e.g. a tuple write that stopped partway through a batch) whose message already carries "N of M committed" detail. A Ctrl-C/SIGTERM cancellation handler can errors.As for this to still report what landed, instead of only "canceled".

func (*PartialResult) Error

func (e *PartialResult) Error() string

func (*PartialResult) Unwrap

func (e *PartialResult) Unwrap() error