validation

Documentation

Overview

Package validation provides a unified document validation interface for use within the Constellation CLI.

It validates documents that specify a set of constraints on their content.

Index

• type Constraint
  • func All[T comparable](s []T, c func(i int, v T) *Constraint) *Constraint
  • func And(errStrat ErrStrategy, constraints ...*Constraint) *Constraint
  • func CIDR(s string) *Constraint
  • func DNSName(s string) *Constraint
  • func Empty[T comparable](s T) *Constraint
  • func EmptySlice[T comparable](s []T) *Constraint
  • func Equal[T comparable](s T, t T) *Constraint
  • func IPAddress(s string) *Constraint
  • func IfNotNil[T comparable](s *T, c func() *Constraint) *Constraint
  • func MatchRegex(s string, regex string) *Constraint
  • func NotEmpty[T comparable](s T) *Constraint
  • func NotEmptySlice[T comparable](s []T) *Constraint
  • func NotEqual[T comparable](s T, t T) *Constraint
  • func OneOf[T comparable](s T, p []T) *Constraint
  • func Or(constraints ...*Constraint) *Constraint
  • func (c *Constraint) WithFieldTrace(doc any, field any) *Constraint
  • func (c *Constraint) WithMapFieldTrace(doc any, field any, mapKey string) *Constraint
• type ErrStrategy
• type TreeError
  • func NewErrorTree(err error) *TreeError
  • func (e *TreeError) Error() string
  • func (e *TreeError) Unwrap() error
• type Validatable
• type ValidateOptions
• type Validator
  • func NewValidator() *Validator
  • func (v *Validator) Validate(doc Validatable, opts ValidateOptions) error

Types

type Constraint

type Constraint struct {
	// Satisfied returns no error if the constraint is satisfied.
	// Otherwise, it returns the reason why the constraint is not satisfied,
	// possibly including its child errors, i.e., errors returned by constraints
	// that are embedded in this constraint.
	Satisfied func() *TreeError
}

Constraint is a constraint on a document or a field of a document.

func All

func All[T comparable](s []T, c func(i int, v T) *Constraint) *Constraint

All is a constraint that checks if all elements of s satisfy the constraint c. The constraint should be parametric in regards to the index of the element in s, as well as the element itself.

func And

func And(errStrat ErrStrategy, constraints ...*Constraint) *Constraint

And groups multiple constraints in an "and" relation and fails according to the given strategy.

func CIDR

func CIDR(s string) *Constraint

CIDR is a constraint that checks if s is a valid CIDR.

func DNSName

func DNSName(s string) *Constraint

DNSName is a constraint that checks if s is a valid DNS name.

func Empty

func Empty[T comparable](s T) *Constraint

Empty is a constraint that checks if s is empty.

func EmptySlice

func EmptySlice[T comparable](s []T) *Constraint

EmptySlice is a constraint that checks if s is an empty slice.

func Equal

func Equal[T comparable](s T, t T) *Constraint

Equal is a constraint that checks if s is equal to t.

func IPAddress

func IPAddress(s string) *Constraint

IPAddress is a constraint that checks if s is a valid IP address.

func IfNotNil

func IfNotNil[T comparable](s *T, c func() *Constraint) *Constraint

IfNotNil evaluates a constraint if and only if s is not nil.

func MatchRegex

func MatchRegex(s string, regex string) *Constraint

MatchRegex is a constraint that if s matches regex.

func NotEmpty

func NotEmpty[T comparable](s T) *Constraint

NotEmpty is a constraint that checks if s is not empty.

func NotEmptySlice

func NotEmptySlice[T comparable](s []T) *Constraint

NotEmptySlice is a constraint that checks if slice s is not empty.

func NotEqual

func NotEqual[T comparable](s T, t T) *Constraint

NotEqual is a constraint that checks if s is not equal to t.

func OneOf

func OneOf[T comparable](s T, p []T) *Constraint

OneOf is a constraint that s is in the set of values p.

func Or

func Or(constraints ...*Constraint) *Constraint

Or groups multiple constraints in an "or" relation.

func (*Constraint) WithFieldTrace

func (c *Constraint) WithFieldTrace(doc any, field any) *Constraint

WithFieldTrace adds a well-formatted trace to the field to the error message shown when the constraint is not satisfied. Both "doc" and "field" must be pointers:

• "doc" must be a pointer to the top level document
• "field" must be a pointer to the field to be validated

Example for a non-pointer field:

Equal(d.IntField, 42).WithFieldTrace(d, &d.IntField)

Example for a pointer field:

NotEmpty(d.StrPtrField).WithFieldTrace(d, d.StrPtrField)

Due to Go's addressability limititations regarding maps, if a map field is to be validated, WithMapFieldTrace must be used instead of WithFieldTrace.

func (*Constraint) WithMapFieldTrace

func (c *Constraint) WithMapFieldTrace(doc any, field any, mapKey string) *Constraint

WithMapFieldTrace adds a well-formatted trace to the map field to the error message shown when the constraint is not satisfied. Both "doc" and "field" must be pointers:

• "doc" must be a pointer to the top level document
• "field" must be a pointer to the map containing the field to be validated
• "mapKey" must be the key of the field to be validated in the map pointed to by "field"

Example:

Equal(d.IntField, 42).WithMapFieldTrace(d, &d.MapField, mapKey)

For non-map fields, WithFieldTrace should be used instead of WithMapFieldTrace.

type ErrStrategy

type ErrStrategy int

ErrStrategy is the strategy to use when encountering an error during validation.

const (
	// EvaluateAll continues evaluating all constraints even if one is not satisfied.
	EvaluateAll ErrStrategy = iota
	// FailFast stops validation on the first error.
	FailFast
)

type TreeError

type TreeError struct {
	// contains filtered or unexported fields
}

TreeError is returned when a document is not valid. It contains the path to the field that failed validation, the error that occurred, as well as a list of child errors, as one constraint can embed multiple other constraints, e.g. in an OR.

func NewErrorTree

func NewErrorTree(err error) *TreeError

NewErrorTree creates a new error tree from the given error.

func (*TreeError) Error

func (e *TreeError) Error() string

Error implements the error interface.

func (*TreeError) Unwrap

func (e *TreeError) Unwrap() error

Unwrap implements the error interface.

type Validatable

type Validatable interface {
	Constraints() []*Constraint
}

Validatable is implemented by documents that can be validated. It returns a list of constraints that must be satisfied for the document to be valid.

type ValidateOptions

type ValidateOptions struct {
	// ErrStrategy is the strategy to use when encountering an error during validation.
	ErrStrategy ErrStrategy
	// OverrideConstraints overrides the constraints to use for validation.
	// If nil, the constraints returned by the document are used.
	OverrideConstraints func() []*Constraint
}

ValidateOptions are the options to use when validating a document.

type Validator

type Validator struct{}

Validator validates documents.

func NewValidator

func NewValidator() *Validator

NewValidator creates a new Validator.

func (*Validator) Validate

func (v *Validator) Validate(doc Validatable, opts ValidateOptions) error

Validate validates a document using the given options.