reason

Documentation

Overview

Package reason defines an optional, structured refinement for derrors codes.

Where Code answers “what kind of error is this?” (invalid, not_found, unavailable, ...), Reason can answer “where / in what operation / in what component this happened?”, e.g.:

• "apimachinery.schema.gvk.parse"
• "storage.pg.connect"
• "auth.jwt.verify"

Reason is intentionally optional: the zero value ("") is allowed and indicates that no further refinement is provided. This lets callers attach a reason only when they actually have a meaningful, stable one to report.

Index

• Constants
• Variables
• func Normalize(s string) string
• func Validate(r Reason) error
• type Reason
  • func MustParse(s string) Reason
  • func Parse(s string) (Reason, error)
  • func (r Reason) MarshalText() ([]byte, error)
  • func (r Reason) String() string
  • func (r *Reason) UnmarshalText(text []byte) error

Constants

const (
	// MinLength is the minimum length for a non-empty reason.
	// We keep it at 3 so that trivial values like "x" are not considered
	// meaningful reasons. Remember: the empty string is still allowed and
	// means "no reason provided".
	MinLength = 3

	// MaxLength is the maximum length for a valid reason.
	// 128 characters is enough even for 4 segments with descriptive names.
	MaxLength = 128
)

MinLength and MaxLength define the allowed length range for a canonical reason string.

We allow reasons to be a bit longer than codes, because they often contain multiple segments (module.component.operation).

Variables

var (
	// ErrReasonInvalidFormat is returned when a reason does not conform to
	// the expected format.
	ErrReasonInvalidFormat = errors.New("derrors: invalid reason format")
	// ErrReasonInvalidLength is returned when a reason is too short or too long.
	ErrReasonInvalidLength = errors.New("derrors: invalid reason length")
)

Functions

func Normalize

func Normalize(s string) string

Normalize takes an arbitrary string and tries to bring it closer to the canonical reason form.

We do *very* conservative transformations:

• trim spaces
• lower-case
• convert "/" to "." (because callers may build paths with slashes)
• replace "-" with "_" (to align with code-style identifiers)

It does NOT guarantee validity — callers should still call Parse/Validate.

func Validate

func Validate(r Reason) error

Validate checks whether the provided Reason is in canonical form.

The empty reason ("") is considered valid here, because the whole point of this type is to be optional. If you need to enforce "must be non-empty", add that check at call site.

Types

type Reason

type Reason string

Reason is the canonical, validated representation of an error reason.

Reasons are dot-separated hierarchical identifiers with a small, fixed depth. Each segment names a module, component, or operation inside the system.

Example valid reasons:

• "apimachinery.schema.gvk.parse"
• "apimachinery.schema.types.validate"
• "storage.pg.connect"
• "auth.jwt.verify"
• "network.dns.resolve"

The intent is to make it easy to programmatically build such identifiers from known package/component/operation names, and later to let mappers/loggers quickly match on these prefixes.

var Empty Reason = ""

Empty is the zero-value reason. It is considered "not provided" and is valid to store in error structs. Callers that require a non-empty, canonical reason should explicitly call Validate.

func MustParse

func MustParse(s string) Reason

MustParse is the panic-on-error variant of Parse. It is useful for declaring package-level reason constants in var/const blocks.

NOTE: unlike Parse, MustParse does NOT allow the empty string — passing an empty string here is almost always a programmer error.

func Parse

func Parse(s string) (Reason, error)

Parse takes a user-provided string, normalizes it and validates it. On success it returns a canonical Reason value.

Parse also accepts the empty string and returns reason.Empty without error. This is what makes Reason an "optional" part of the error model.

func (Reason) MarshalText

func (r Reason) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

We allow marshaling of the empty reason as an empty slice to not break JSON/YAML encoders that rely on TextMarshaler.

func (Reason) String

func (r Reason) String() string

String returns the canonical string representation of the reason.

func (*Reason) UnmarshalText

func (r *Reason) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

It normalizes and validates the provided text before assigning. An empty or whitespace-only input will produce reason.Empty.