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 ¶
- Variables
- func ValidateHostname(hostname string) error
- type ConfigPattern
- type Context
- func (v *Context) Enter(title string, args ...any)
- func (v *Context) Error(err error)
- func (v *Context) Errorf(format string, args ...any)
- func (v *Context) Exit()
- func (v *Context) Finalize() error
- func (v *Context) SetFile(path string)
- func (v *Context) Warning(err error)
- func (v *Context) Warningf(format string, args ...any)
- type Error
- type Func
- type RuleSet
- type Severity
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 ¶
ValidateHostname returns an error if the given string is not a valid RFC1123 hostname.
Types ¶
type ConfigPattern ¶
ConfigPattern is a pair of pattern.Pattern of config sets and paths that the service is responsible for validating.
type Context ¶
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 ¶
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) Errorf ¶
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 ¶
Finalize returns *Error if some validation errors were recorded.
Returns nil otherwise.
func (*Context) SetFile ¶
SetFile records that what follows is errors for this particular file.
Changing the file resets the current element (see Enter/Exit).
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) ToValidationResultMsgs ¶
func (e *Error) ToValidationResultMsgs(ctx context.Context) []*configpb.ValidationResult_Message
ToValidationResultMsgs converts `Error` to a slice of `configpb.ValidationResult.Message`s.
func (*Error) WithSeverity ¶
WithSeverity returns a multi-error with errors of a given severity only.
type Func ¶
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 ¶
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 ¶
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).
Source Files