observer

Documentation

Overview

Package observer provides validators and modifiers for configuration values.

Installed validators: ISO3166Alpha2, country_codes2, ISO3166Alpha3, country_codes3, ISO4217, currency3, Locale, locale, ISO693Alpha2, language2, ISO693Alpha3, language3, uuid, uuid3, uuid4, uuid5, url, int, float, bool, utf8, utf8_digit, utf8_letter, utf8_letter_numeric, notempty, not_empty, notemptytrimspace, not_empty_trim_space, hexadecimal, hexcolor and any custom validator added via function RegisterValidator.

Installed modifiers: upper, lower, trim, title, base64_encode, base64_decode, hex_encode, hex_decode, sha256, gzip, gunzip, AES-GCM encrypt/decrypt and any custom modifier added via function RegisterModifier.

The list of validators and modifiers will be extended. Please suggest new ones.

Other encryption algorithms are getting later added.

Note: When using sha256 the fully qualified path gets prefixed to the value.

To enabled HTTP handler or protobuf you must set build tags on the CLI. Supported build tags are:

• `json` for JSON encoding and decoding.
• `proto` for protocol buffers encoding and registration of modifiers via proto services, includes `json`.
• `http` to enable registration of modifiers via HTTP handlers.
• `csall` for all features.

Index

• func MustNewAESGCM(eventType uint8, eo *AESGCMOptions) config.Observer
• func MustNewModifier(data ModifierArg) config.Observer
• func MustNewValidator(data ValidatorArg) config.Observer
• func NewAESGCM(eventType uint8, eo *AESGCMOptions) (config.Observer, error)
• func NewModifier(data ModifierArg) (config.Observer, error)
• func NewValidator(data ValidatorArg) (config.Observer, error)
• func RegisterFactory(typeName string, fn FactoryFunc)
• func RegisterModifier(typeName string, h ModifierFn)
• func RegisterValidator(typeName string, vfn ValidateFn)
• type AESGCMOptions
• type FactoryFunc
• type ModifierArg
• type ModifierFn
• type ValidateFn
• type ValidateMinMaxInt
  • func NewValidateMinMaxInt(minMax ...int64) (*ValidateMinMaxInt, error)
  • func (v ValidateMinMaxInt) Observe(p config.Path, rawData []byte, found bool) (rawData2 []byte, err error)
• type ValidatorArg

Functions

func MustNewAESGCM

func MustNewAESGCM(eventType uint8, eo *AESGCMOptions) config.Observer

MustNewAESGCM same as NewAESGCM but panics on error.

func MustNewModifier

func MustNewModifier(data ModifierArg) config.Observer

MustNewModifier same as NewModifier but panics on error.

func MustNewValidator

func MustNewValidator(data ValidatorArg) config.Observer

MustNewValidator same as NewValidator but panics on error.

func NewAESGCM

func NewAESGCM(eventType uint8, eo *AESGCMOptions) (config.Observer, error)

NewAESGCM creates a new observer which can encrypt or decrypt a value with the AES-GCM mode. Only two events are supported: config.EventOnBeforeSet for encryption and config.EventOnAfterGet for decryption. For security reasons this function cannot be accessed via JSON or protocol buffers.

func NewModifier

func NewModifier(data ModifierArg) (config.Observer, error)

NewModifier creates a new type specific modifier.

func NewValidator

func NewValidator(data ValidatorArg) (config.Observer, error)

NewValidator creates a new type specific validator.

func RegisterFactory

func RegisterFactory(typeName string, fn FactoryFunc)

RegisterFactory adds a custom observer factory to the global registry. A custom observer can be accessed via Configuration.MakeObserver or via RegisterWithJSON. FactoryFunc can be anything, validation or modification, logging, etc.

func RegisterModifier

func RegisterModifier(typeName string, h ModifierFn)

RegisterModifier adds a new modification function to the global registry and might overwrite previously set entries. Access to the global registry can be achieved via function NewModifier.

func RegisterValidator

func RegisterValidator(typeName string, vfn ValidateFn)

RegisterValidator adds a custom string validation function to the global registry for later use with function NewValidator. Adding an entry with an already existing `typeName` overwrites the previous validator. `typeName` will be handled case-sensitive.

Types

type AESGCMOptions

type AESGCMOptions struct {
	// The key argument should be the AES key, either 16, 24, or 32 bytes to
	// select AES-128, AES-192, or AES-256. If empty, a random key will be
	// generated and discarded once the service gets shut down.
	Key string
	// KeyEnvironmentVariableName defines the name of the environment variable
	// which contains the key used for encryption and decryption.
	KeyEnvironmentVariableName   string
	Nonce                        []byte // max 12 bytes
	NonceEnvironmentVariableName string
}

AESGCMOptions sets the Key and Nonce from this struct or from environment variables.

type FactoryFunc

type FactoryFunc func(data []byte) (config.Observer, error)

FactoryFunc allows to implement a custom observer which gets created based on the input data. The function gets called in Configuration.MakeObserver or in RegisterWithJSON. Input data can be raw JSON or YAML or XML.

type ModifierArg

type ModifierArg struct {
	// Funcs defines a list of function names. Currently supported: upper,
	// lower, trim, title, base64_encode, base64_decode, sha256 (must one time
	// be registered in hashpool package), gzip, gunzip. Additional all other
	// custom modifier functions registered via RegisterModifier are
	// supported.
	Funcs []string `json:"funcs,omitempty"`
}

ModifierArg defines the modifiers to use to alter a string received from the config.Service.

type ModifierFn

type ModifierFn func(config.Path, []byte) ([]byte, error)

ModifierFn defines the function signature for altering the data.

type ValidateFn

type ValidateFn func(string) bool

ValidateFn function signature for a validator.

type ValidateMinMaxInt

type ValidateMinMaxInt struct {
	Conditions []int64 `json:"conditions,omitempty"`
	// PartialValidation if true only one of min/max pairs must be valid.
	PartialValidation bool `json:"partial_validation,omitempty"`
}

ValidateMinMaxInt validates if a value is between or in range of min and max. Provide the field Conditions as a balanced slice where value n defines min and n+1 the max value. For JSON handling, see sub-package `json`.

func NewValidateMinMaxInt

func NewValidateMinMaxInt(minMax ...int64) (*ValidateMinMaxInt, error)

NewValidateMinMaxInt creates a new observer to check if a value is contained between min and max values. Argument MinMax must be balanced slice.

func (ValidateMinMaxInt) Observe

func (v ValidateMinMaxInt) Observe(p config.Path, rawData []byte, found bool) (rawData2 []byte, err error)

Observe runs the validation process.

type ValidatorArg

type ValidatorArg struct {
	// Funcs sets the list of validator functions which can be:
	// "ISO3166Alpha2","country_codes2" for two letter country codes,
	// "ISO3166Alpha3","country_codes3" for three letter country codes,
	// "ISO4217" for three letter currency codes,
	// "Locale" for locale codes,
	// "ISO693Alpha2" for two letter language codes,
	// "ISO693Alpha3" for three letter language codes.
	// "uuid" for any UUID.
	// "uuid3" for UUID version 3.
	// "uuid4" for UUID version 4.
	// "uuid5" for UUID version 5.
	// "url" for URLs
	// "int" for integers
	// "float" for floating point numbers
	// "bool" for boolean values
	// "not_empty" to proof values is not empty
	// "not_empty_trim_space" to proof that values with trimmed white spaces are not empty
	// "custom" for any custom checking if the value is contained in the
	// AdditionalAllowedValues map.
	// Additional all other custom validator functions registered via
	// RegisterValidator are supported.
	Funcs []string `json:"funcs,omitempty"`
	// PartialValidation if true only one of the Configurations must return true /
	// match the string.
	PartialValidation bool `json:"partial_validation,omitempty"`
	// Insecure enables printing in case of errors the values used in a
	// validation function. This might and will leak sensitive information.
	Insecure bool `json:"insecure,omitempty"`
	// CSVComma one character to separate the input data. If empty the
	// validation process does not know to validate CSV.
	CSVComma string `json:"csv_comma,omitempty"`
	// AdditionalAllowedValues can be optionally or solely defined to add more
	// allowed values than Configurations field defines or if Configurations equals
	// "Custom" then AdditionalAllowedValues must have values.
	AdditionalAllowedValues []string `json:"additional_allowed_values,omitempty"`
}

ValidatorArg gets used as argument to function NewValidator to create a new validation observer implementing various checks. Working on CSV data is supported to validate each CSV entity. ValidatorArg implements JSON encoding/decoding for creating new observer via HTTP or protocol buffers.