luci: Index | Files

package validation

import ""

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.


Package Files

doc.go handler.go net_util.go rules.go validation.go

func InstallHandlers Uses

func InstallHandlers(r *router.Router, base router.MiddlewareChain, rules *RuleSet)

InstallHandlers installs the metadata and validation handlers that use the given validation rules.

It does not implement any authentication checks, thus the passed in router.MiddlewareChain should implement any necessary authentication checks.

func ValidateHostname Uses

func ValidateHostname(hostname string) error

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

type ConfigPattern Uses

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

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

type Context Uses

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 Uses

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 Uses

func (v *Context) Error(err error)

Error records the given error as a validation error.

func (*Context) Errorf Uses

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

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

func (*Context) Exit Uses

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 Uses

func (v *Context) Finalize() error

Finalize returns *Error if some validation errors were recorded.

Returns nil otherwise.

func (*Context) SetFile Uses

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).

type Error Uses

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

Error is an error with details of failed validation.

Returned by Context.Finalize().

func (*Error) Error Uses

func (v *Error) Error() string

Error makes *Error implement 'error' interface.

type Func Uses

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

Func performs the actual config validation and stores the associated results in the validation.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 Uses

type RuleSet struct {
    // contains filtered or unexported fields

RuleSet is a helper for building Validator from a set of rules: each rule specifies a pattern for config set 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.

var Rules RuleSet

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

Individual packages may register vars and rules there during init() time.

func (*RuleSet) Add Uses

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

Add registers a validation function for given configSet and path patterns.

The pattern may contain placeholders (e.g. "${appid}") that will be resolved before the actual validation starts. All such placeholder variables must be registered prior to adding rules that reference them (or 'Add' will panic).

'Add' will also try to validate the patterns by substituting all placeholders in them with empty strings and trying to render the resulting pattern. It will panic if the pattern is invalid.

func (*RuleSet) ConfigPatterns Uses

func (r *RuleSet) ConfigPatterns(c 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.

func (*RuleSet) RegisterVar Uses

func (r *RuleSet) RegisterVar(name string, value func(context.Context) (string, error))

RegisterVar registers a placeholder that can be used in patterns as ${name}.

Such placeholder is rendered into an actual value via the given callback before the validation starts. The value of the placeholder is injected into the pattern string as is. So for example if the pattern is 'regex:...', the placeholder value can be a chunk of regexp.

The primary use case for this mechanism is too allow to register rule patterns that depend on not-yet known values during init() time.

Panics if such variable is already registered.

func (*RuleSet) ValidateConfig Uses

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.

Package validation imports 13 packages (graph) and is imported by 45 packages. Updated 2019-10-17. Refresh now. Tools for package owners.