urlvalues

README

urlvalues

Go package for strict decoding of url.Values to given struct.

WARNING: This package is experimental, API will change!

Strict validation rules

• (optional) error on unknown param
  • including param matching real, but not qualified enough field name:
    • struct without .field (TODO in case custom handler not registered)
    • map without [key]
• error on array overflow
  • array with out-of-bound [index]
  • too many params for array field
• error on scalar overflow
  • multiple values for non-slice/array field
  • multiple values for same array[index] or map[key] (in case this array/map doesn't have values of slice/array type)
• error on no values for non-pointer/slice/array field tagged form:"…,required"
• panic on unknown form:"" tag option

Benchmark

• Small/Large means size of struct.
• Failure means failed strict validation and skipped form.Decoder.Decode().
• Loose means without strict validation, i.e. just form.Decoder.Decode().

BenchmarkSmallFailure      	 1000000	      1224 ns/op	     944 B/op	      10 allocs/op
BenchmarkSmallSuccess      	 1000000	      1540 ns/op	     592 B/op	       9 allocs/op
BenchmarkSmallSuccessLoose 	 3000000	       524 ns/op	     448 B/op	       5 allocs/op
BenchmarkLargeFailure      	   50000	     33754 ns/op	    5557 B/op	      45 allocs/op
BenchmarkLargeSuccess      	   10000	    419697 ns/op	  817797 B/op	      77 allocs/op
BenchmarkLargeSuccessLoose 	   10000	    381430 ns/op	  814318 B/op	      50 allocs/op

Documentation

Overview

Package urlvalues implements strict decoding of url.Values to given struct.

WARNING: This package is experimental, API will change!

It is safe for concurrent use by multiple goroutines.

Strict validation rules

• (optional) error on unknown param
• including param matching real, but not qualified enough field name:
• struct without .field (TODO in case custom handler not registered)
• map without [key]
• error on array overflow
• array with out-of-bound [index]
• too many params for array field
• error on scalar overflow
• multiple values for non-slice/array field
• multiple values for same `array[index]` or `map[key]` (in case this array/map doesn't have values of slice/array type)
• error on no values for non-pointer/slice/array field tagged `form:"…,required"`
• panic on unknown `form:""` tag option

Index

• type Errs
  • func (errs Errs) Any() (pattern string)
  • func (errs Errs) Error() string
• type StrictDecoder
  • func NewStrictDecoder(opts ...StrictDecoderOption) *StrictDecoder
  • func (d *StrictDecoder) Decode(v interface{}, values url.Values) error
• type StrictDecoderOption
  • func IgnoreUnknown() StrictDecoderOption
  • func MaxArraySize(size uint) StrictDecoderOption
  • func Mode(mode form.Mode) StrictDecoderOption
  • func TagName(tagName string) StrictDecoderOption

Types

type Errs

type Errs struct{ url.Values }

Errs contain Decode errors.

Errs key can be "-" or pattern for corresponding Decode param values key.

Key "-" will contain all keys from Decode param values which are not correspond to any of Decode param v field and thus can't be decoded. This key won't exists if IgnoreUnknown option is used.

Pattern is same as values key with map key names replaced with [key] and array/slice indices replaced with [idx]. Example: if Decode was called with this key in values

FieldA.MapField[something].SliceOfSliceField[42][1].FieldB

then related key in Errs will be

FieldA.MapField[key].SliceOfSliceField[idx][idx].FieldB

func (Errs) Any

func (errs Errs) Any() (pattern string)

Any returns one of available errors or empty string if there are no errors.

func (Errs) Error

func (errs Errs) Error() string

Error return all errors at once using errs.Encode.

This is suitable for debugging but not for production error message.

type StrictDecoder

type StrictDecoder struct {
	// contains filtered or unexported fields
}

StrictDecoder wraps https://godoc.org/github.com/go-playground/form#Decoder to add strict validation of url.Values and normalize returned errors.

Differences from wrapped form.Decoder:

• Decoding to field with interface type is not supported.
• To make field required (meaning url.Values must contain any value for this field, including empty string) tag field with: `form:"…,required"`

func NewStrictDecoder

func NewStrictDecoder(opts ...StrictDecoderOption) *StrictDecoder

NewStrictDecoder returns new StrictDecoder.

It's recommended to create one instance (for each opts) and reuse it to enable caching.

func (*StrictDecoder) Decode

func (d *StrictDecoder) Decode(v interface{}, values url.Values) error

Decode will decode values to v (which must be a pointer to a struct).

It'll normalize form.Decoder panics and errors and return nil or Errs. It will panic if called with wrong v, but never panics on wrong values.

type StrictDecoderOption

type StrictDecoderOption func(*StrictDecoder)

StrictDecoderOption is for internal use only and exported just to make golint happy.

func IgnoreUnknown

func IgnoreUnknown() StrictDecoderOption

IgnoreUnknown return an option for NewStrictDecoder.

With this option Decode won't return errors related to unknown keys in url.Values.

func MaxArraySize

func MaxArraySize(size uint) StrictDecoderOption

MaxArraySize return an option for NewStrictDecoder.

See https://godoc.org/github.com/go-playground/form#Decoder.SetMaxArraySize

func Mode

func Mode(mode form.Mode) StrictDecoderOption

Mode return an option for NewStrictDecoder.

See https://godoc.org/github.com/go-playground/form#Decoder.SetMode

func TagName

func TagName(tagName string) StrictDecoderOption

TagName return an option for NewStrictDecoder.

See https://godoc.org/github.com/go-playground/form#Decoder.SetTagName