Documentation

Overview

Package validation provides helpers for performing and setting up handlers for config validation related requests from luci-config.

Package validation provides a helper for performing config validations.

Index

Constants

This section is empty.

Variables

var Rules = RuleSet{Vars: &vars.Vars}

Rules is the default validation rule set used by the process.

Individual packages may register rules here during init() time.


var SeverityTag = severityTagType{errors.NewTagKey("holds the severity")}

SeverityTag holds the severity of the given validation error.


Functions

func ValidateHostname

func ValidateHostname(hostname string) error

ValidateHostname returns an error if the given string is not a valid RFC1123 hostname.

Types

type ConfigPattern

type ConfigPattern struct {
	ConfigSet pattern.Pattern
	Path      pattern.Pattern
}

ConfigPattern is a pair of pattern.Pattern of config sets and paths that the service is responsible for validating.

type Context

type Context struct {
	Context context.Context
	// contains filtered or unexported fields
}

Context is an accumulator for validation errors.

It is passed to a function that does config validation. Such function may validate a bunch of files (using SetFile to indicate which one is processed now). Each file may have some internal nested structure. The logical path inside this structure is captured through Enter and Exit calls.

func (*Context) Enter

func (v *Context) Enter(title string, args ...interface{})

Enter descends into a sub-element when validating a nested structure.

Useful for defining context. A current path of elements shows up in validation messages.

The reverse is Exit.

func (*Context) Error

func (v *Context) Error(err error)

Error records the given error as a blocking validation error.

func (*Context) Errorf

func (v *Context) Errorf(format string, args ...interface{})

Errorf records the given format string and args as a blocking validation error.

func (*Context) Exit

func (v *Context) Exit()

Exit pops the current element we are visiting from the stack.

This is the reverse of Enter. Each Enter must have corresponding Exit. Use functions and defers to ensure this, if it's otherwise hard to track.

func (*Context) Finalize

func (v *Context) Finalize() error

Finalize returns *Error if some validation errors were recorded.

Returns nil otherwise.

func (*Context) SetFile

func (v *Context) SetFile(path string)

SetFile records that what follows is errors for this particular file.

Changing the file resets the current element (see Enter/Exit).

func (*Context) Warning

func (v *Context) Warning(err error)

Warning records the given error as a validation warning.

func (*Context) Warningf

func (v *Context) Warningf(format string, args ...interface{})

Warningf records the given format string and args as a validation warning.

type Error

type Error struct {
	// Errors is a list of individual validation errors.
	//
	// Each one is annotated with "file" string, logical path pointing to
	// the element that contains the error, and its severity. It is provided as a
	// slice of strings in "element" annotation.
	Errors errors.MultiError
}

Error is an error with details of validation issues.

Returned by Context.Finalize().

func (*Error) Error

func (e *Error) Error() string

Error makes *Error implement 'error' interface.

func (*Error) WithSeverity

func (e *Error) WithSeverity(s Severity) error

WithSeverity returns a multi-error with errors of a given severity only.

type Func

type Func func(ctx *Context, configSet, path string, content []byte) error

Func performs the actual config validation and stores the associated results in the Context.

Returns an error if the validation process itself fails due to causes unrelated to the data being validated. This will result in HTTP Internal Server Error reply, instructing the config service to retry.

type RuleSet

type RuleSet struct {
	// Vars is a set of placeholder vars that can be used in patterns.
	Vars *vars.VarSet
	// contains filtered or unexported fields
}

RuleSet is a helper for building Validator from a set of rules: each rule specifies a pattern for config sets and file names, and a validation function to apply to corresponding configs.

The primary use case is building the list of rules during init() time. Since not all information is available at that time (most crucially on GAE Standard App ID is not yet known), the rule patterns can have placeholders (such as "${appid}") that are substituted during actual config validation time via the given vars.VarSet instance.

func NewRuleSet

func NewRuleSet() *RuleSet

NewRuleSet returns a RuleSet that uses its own new VarSet.

Primarily useful in tests to create a self-contained RuleSet to avoid relying on global Rules and Vars.

func (*RuleSet) Add

func (r *RuleSet) Add(configSet, path string, cb Func)

Add registers a validation function for the config set and path patterns.

Patterns may contain placeholders (e.g. "${appid}") that will be resolved when doing the validation. All such placeholder variables must be registered in the VarSet before the rule set is used, but they may be registered after Add calls that reference them.

func (*RuleSet) ConfigPatterns

func (r *RuleSet) ConfigPatterns(ctx context.Context) ([]*ConfigPattern, error)

ConfigPatterns renders all registered config patterns and returns them.

Used by the metadata handler to notify the config service about config files we understand.

Returns an error if some config patterns can't be rendered, e.g. if they reference placeholders that weren't registered in the VarSet, or if the placeholder value can't be resolved.

func (*RuleSet) ValidateConfig

func (r *RuleSet) ValidateConfig(ctx *Context, configSet, path string, content []byte) error

ValidateConfig picks all rules matching the given file and executes their validation callbacks.

If there's no rule matching the file, the validation is skipped. If there are multiple rules that match the file, they all are used (in order of their) registration.

Returns an error if the validation process itself fails due to causes unrelated to the data being validated (e.g. config patterns can't be rendered or some validation callback fails).

type Severity

type Severity int

Severity of the validation message.

Only Blocking and Warning severities are supported.

const (
	// Blocking severity blocks config from being accepted.
	//
	// Corresponds to ValidationResponseMessage_Severity:ERROR.
	Blocking Severity = 0
	// Warning severity doesn't block config from being accepted.
	//
	// Corresponds to ValidationResponseMessage_Severity:WARNING.
	Warning Severity = 1
)