Documentation
¶
Overview ¶
Package validation provides structured error primitives plus a small rule-based API for accumulating validation failures.
An Error captures a single failure as a (Subject, Field, Message) triple, where Subject identifies the thing being validated (e.g. a hostname or certificate CN), Field names the attribute that failed, and Message describes the failure in human-readable form. Errors aggregates multiple Error values into a single error while remaining compatible with errors.Is, errors.As, and errors.Join via its Unwrap method.
Higher-level validation is expressed by passing a list of Rule values to Validate, typically constructed via Field and the built-in Check functions (Required, Unique, IsHostPort). Validate accumulates every rule's output into one Errors value and stamps the supplied subject onto entries that don't already carry one.
Conditional logic is expressed with the When family of combinators: When guards Checks on a value-aware predicate, WhenFn guards Checks on a value-free predicate (closing over outer state), and WhenRules guards an entire block of Rules. Nested struct validation is expressed with Nested, which embeds a child's Validator (anything with Validate() error) as a Rule and stamps a subject onto entries the child left unattributed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Check ¶
Check verifies a single value of type V. A nil return means valid.
func IsHostPort ¶
IsHostPort validates that s is syntactically a host:port pair. The check is purely lexical: no DNS lookup, no /etc/services port resolution. Both "host:port" and ":port" (listen-on-all-interfaces) forms are valid, and the port must be a decimal integer in [0, 65535]. Port 0 is accepted because it is a valid listener form meaning "let the OS pick".
func Required ¶
func Required[V comparable]() Check[V]
Required rejects the zero value of V. Note that this means Required[bool]() rejects false; reach for a different check when false is a meaningful value.
func Unique ¶
func Unique[V comparable]() Check[[]V]
Unique rejects a slice containing two or more equal elements. The error message names the first duplicate encountered.
type Error ¶
type Error struct {
Subject string // identifier of the thing being validated (e.g. a hostname or cert CN)
Field string // attribute or property that failed (e.g. "expiry", "key_type")
Message string // human-readable description of the failure
}
Error is a single validation failure for a named subject and field.
type Errors ¶
type Errors []Error
Errors is a collection of Error values.
type Rule ¶
type Rule func() Errors
Rule produces zero or more validation errors when run.
func Children ¶
Children is the slice counterpart to Nested: it validates each element of items with validate, prefixing a "name[i]" segment onto the resulting subjects to build a dotted path (e.g. "classes[0].subjects[1]"). Empty subjects become the segment; already-set ones are prefixed into a path. The per-element validate is supplied explicitly rather than via the Validator interface, so callers can thread external context by closing over it - for example Children("classes", c.Classes, func(x *Class) error { return x.validate(ctx) }). A nil or empty slice yields no entries and never calls validate.
func Field ¶
Field builds a Rule that runs every Check[V] against value and turns any failure into validation.Errors entries. The returned Errors have their Field stamped with name, unless the check returned a validation.Error or validation.Errors with Field already set, in which case the existing value is preserved.
func Nested ¶
Nested embeds the result of v.Validate as a Rule, prefixing subject onto each entry to build a dotted path. An entry the child left unattributed gets Subject set to subject; an entry the child already attributed gets its Subject prefixed (subject + "." + child), so deeper nesting composes into a path like "classes[0].subjects[1]". A nil error from v yields no entries, an empty subject leaves entries unchanged, and any non-validation error is wrapped as a single entry whose Message is err.Error() and whose Subject is subject.
Source Files