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

    View Source
    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.

      View Source
      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
                                                  )