validator

README

dfuse Validator Library

This repository contains all common stuff around validation handling across our various services

Philosophy

We started using govalidator for our validation needs.

This library is based on rules which are plain string identifier backed by a corresponding registered function that validates the input. When you when to validate a request query parameters or JSON payload, you can define a set of rules which is simply a map[string][]string{} where the key is the field/parameter to validate while the value is the set of rules identifier you would like to validate the field against.

Most of the rules accepts string for query parameters and typed value for JSON payload. The govalidator has a bunch of predefined rules also already integrated. See govalidator pre-defined rules set.

The package aims at providing a quick API to validate either the query parameters of a request validator.ValidateQueryParams or the JSON body payload received validator.ValidateJSONBody.

The package also includes a bunch of predefined rules useful across all our projects, most of them related to blockchain ecosystem.

In the rules set, a function ending with Factory means it's used to create a validator.Rule function which is parameterized by the parameters received by the factory function. For example, the EOSNamesRulesFactory is used to create a Rule function exploding a list of eos.Name based on a separator sep and with a maximum count of maxCount.

eosNamesListRule := validator.EOSNamesRulesFactory("|", 10)

Usage

To efficiently used pre-defined rules inside validator as a string, you must register them through a central location (func init() in a validators.go in the package is probably the most common place).

func init() {
    govalidator.AddCustomRule("eos.blockNum", validator.EOSBlockNumRule)
    govalidator.AddCustomRule("eos.name", validator.EOSNameRule)
    govalidator.AddCustomRule("eos.accountsList", validator.EOSNamesListRuleFactory("|", 10))
}

You can then pass them as string in your rules set when validating query parameters:

errors := validator.ValidateQueryParams(r, govalidator.MapData{
    "account":   []string{"required", "eos.name"},
    "block_num": []string{"eos.blockNum"},
})

Validate Query Parameters

Simply pass your request and receives back url.Values object which is a simple map[string][]string where the key is the name of the offending field and the value is an array of all the error messages for this field.

errors := validator.ValidateQueryParams(r, validator.Rules{
    "account":   []string{"required", "eos.name"},
    "block_num": []string{"eos.blockNum"},
})

Validate JSON Body Payload

Similar to validator.ValidateQueryParams but you pass and extra parameters which will be the object into which the JSON payload will be deserialized in.

If the deserialization is successful, the data object will be populated with the JSON data. This holds even if the validation later failed, you still have access to the full deserialized object.

Similar to how one use json.UnmarshalJSON, you must pass a pointer to the validator.ValidateJSONBody.

You will receives back url.Values object which is a simple map[string][]string where the key is the name of the offending field and the value is an array of all the error messages for this field.

type Request struct {
    Account eos.Name `json:"account"`
}

request := Request{}
errors := validator.ValidateJSONBody(r, &request, validator.Rules{
    "account":   []string{"required", "eos.name"},
})

If the deserialization of the JSON failed altogether, validation rules are not checked. However, to denote such deserialization error, you will get an errors map containing a single entry whose key will be named _error and the values will be a single element array containing the message why the JSON deserialization failed.

Validate Struct

Can be used to validate any kind of structure. The field names are determined via the json tag if present of the field name (case sensitive) if the json tag is not present. It's also possible to use validator.TagIdentifierOption to specify an alternative tag to use instead of json.

Simply pass your struct and receives back url.Values object which is a simple map[string][]string where the key is the name of the offending field and the value is an array of all the error messages for this field.

type test struct {
    accountName string `json:account`
    blockNum    uint32 `json:block_num`
}

data := &test{
    accountName: "eosio",
    blockNum: 0,
}

errors := validator.ValidateStruct(data, validator.Rules{
    "account":   []string{"required", "eos.name"},
    "block_num": []string{"eos.blockNum"},
})

Reference

For now, not much reference documentation exists. You are invited to read the following files to get a clearer understanding of what you can do.

• api.go
• rules.go

You are specially invited to check out the unit tests which expresses most of the usage that can be made out of this library:

• api_test.go
• rules_test.go

Contributing

Issues and PR in this repo related strictly to the validator library.

Report any protocol-specific issues in their respective repositories

Please first refer to the general dfuse contribution guide, if you wish to contribute to this code base.

License

Apache 2.0

Documentation

Index

• Variables
• func CursorRule(field string, rule string, message string, value interface{}) error
• func EOSBlockNumRule(field string, rule string, message string, value interface{}) error
• func EOSExtendedNameRule(field string, rule string, message string, value interface{}) error
• func EOSNameRule(field string, rule string, message string, value interface{}) error
• func EOSTrxIDRule(field string, rule string, message string, value interface{}) error
• func ExplodeNames(input string, sep string) (names []string)
• func HexRule(field string, rule string, message string, value interface{}) error
• func HexSliceRule(field string, rule string, message string, value interface{}) error
• func IsValidExtendedName(input string) bool
• func IsValidName(input string) bool
• func ValidateJSONBody(r *http.Request, data interface{}, rules Rules, options ...Option) url.Values
• func ValidateQueryParams(r *http.Request, rules Rules, options ...Option) url.Values
• func ValidateStruct(data interface{}, rules Rules, options ...Option) url.Values
• type MessagesOption
• type Option
• type Rule
  • func DateTimeRuleFactory(layout string) Rule
  • func EOSExtendedNamesListRuleFactory(sep string, maxCount int) Rule
  • func EOSNamesListRuleFactory(sep string, maxCount int) Rule
  • func StringListRuleFactory(sep string, maxCount int, elementRule Rule) Rule
• type Rules
• type TagIdentifierOption

Variables

var HexRowRule = HexRule

Deprecated: Use `HexRule` instead

var HexRowsRule = HexSliceRule

Deprecated: Use `HexRowsRule` instead

Functions

func CursorRule

func CursorRule(field string, rule string, message string, value interface{}) error

func EOSBlockNumRule

func EOSBlockNumRule(field string, rule string, message string, value interface{}) error

func EOSExtendedNameRule

func EOSExtendedNameRule(field string, rule string, message string, value interface{}) error

func EOSNameRule

func EOSNameRule(field string, rule string, message string, value interface{}) error

func EOSTrxIDRule

func EOSTrxIDRule(field string, rule string, message string, value interface{}) error

func ExplodeNames

func ExplodeNames(input string, sep string) (names []string)

func HexRule

func HexRule(field string, rule string, message string, value interface{}) error

func HexSliceRule

func HexSliceRule(field string, rule string, message string, value interface{}) error

func IsValidExtendedName

func IsValidExtendedName(input string) bool

func IsValidName

func IsValidName(input string) bool

FIXME: Use eso-go IsValidName once merged, not perfect Regex for now, 13 characters if present is restricted to a different subset

func ValidateJSONBody

func ValidateJSONBody(r *http.Request, data interface{}, rules Rules, options ...Option) url.Values

func ValidateQueryParams

func ValidateQueryParams(r *http.Request, rules Rules, options ...Option) url.Values

func ValidateStruct

func ValidateStruct(data interface{}, rules Rules, options ...Option) url.Values

Types

type MessagesOption

type MessagesOption map[string][]string

MessagesOption represents the set of messages to return explicitely for each validation, defaults to `nil` when undefined (predefined messages are used).

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option represents an option that can be set on the validator to alter it's behavior

type Rule

type Rule func(field string, rule string, message string, value interface{}) error

func DateTimeRuleFactory

func DateTimeRuleFactory(layout string) Rule

func EOSExtendedNamesListRuleFactory

func EOSExtendedNamesListRuleFactory(sep string, maxCount int) Rule

func EOSNamesListRuleFactory

func EOSNamesListRuleFactory(sep string, maxCount int) Rule

func StringListRuleFactory

func StringListRuleFactory(sep string, maxCount int, elementRule Rule) Rule

type Rules

type Rules map[string][]string

Rules represents the set of validation to perform for each path of the struct.

type TagIdentifierOption

type TagIdentifierOption string

TagIdentifierOption represents the tag to use when inspecting a struct to determine the field name, defaults to `json` when undefined.