runtime

README

Generator Runtime

Environment based configuration

• MAX_PAGE_SIZE default: 100

  • MaxPageSize describes the max. valid value for the page size query parameter of a request with pagination

• MIN_PAGE_SIZE default: 1

  • MinPageSize describes the min. valid value for the page size query parameter of a request with pagination

• DEFAULT_PAGE_SIZE default: 50

  • DefaultPageSize describes the default value, if there is no page size present in the request

Documentation

Overview

Package runtime contains functions for marshalling, error handling, parameter parsing and validation. These functions are used by the generator to implement the different request handlers.

Index

• Constants
• Variables
• func Marshal(w http.ResponseWriter, data interface{}, code int)
• func Scan(str string, data interface{}) (int, error)
• func ScanParameters(w http.ResponseWriter, r *http.Request, parameters ...*ScanParameter) bool
• func Unmarshal(w http.ResponseWriter, r *http.Request, data interface{}) bool
• func UnmarshalMany(w http.ResponseWriter, r *http.Request, t reflect.Type) (bool, []interface{})
• func ValidateParameters(w http.ResponseWriter, r *http.Request, data interface{}) bool
• func ValidateRequest(w http.ResponseWriter, r *http.Request, data interface{}) bool
• func ValidateStruct(w http.ResponseWriter, r *http.Request, data interface{}, source string) bool
• func WriteError(w http.ResponseWriter, code int, err error)
• type ColumnMapper
• type Error
  • func (e Error) Error() string
• type Errors
  • func (e Errors) Error() string
• type MapMapper
  • func NewMapMapper(mapping map[string]string) *MapMapper
  • func (m *MapMapper) Map(value string) (string, bool)
• type ScanIn
• type ScanParameter
  • func (p *ScanParameter) BuildInvalidValueError(typ reflect.Type, data string) error
• type UrlQueryParameters
  • func ReadURLQueryParameters(r *http.Request, mapper ColumnMapper, sanitizer ValueSanitizer) (*UrlQueryParameters, error)
  • func (u *UrlQueryParameters) AddToQuery(query *orm.Query) *orm.Query
• type ValueSanitizer
  • func NewComposableSanitizer(mapping map[string]ValueSanitizer) ValueSanitizer
  • func NewDatetimeSanitizer() ValueSanitizer
  • func NewDecimalSanitizer() ValueSanitizer
  • func NewIntSanitizer() ValueSanitizer
  • func NewNoopSanitizer() ValueSanitizer
  • func NewUUIDSanitizer() ValueSanitizer
• Bugs

Constants

const JSONAPIContentType = "application/vnd.api+json"

JSONAPIContentType is the content type required for jsonapi based requests and responses

Variables

var (
	ErrInvalidFieldname = errors.New("invalid fieldName, not registered in sanitizer")
)

Functions

func Marshal

func Marshal(w http.ResponseWriter, data interface{}, code int)

Marshal the given data and writes them into the response writer, sets the content-type and code as well

func Scan

func Scan(str string, data interface{}) (int, error)

Scan works like fmt.Sscan except for strings and decimals, they are directly assigned

func ScanParameters

func ScanParameters(w http.ResponseWriter, r *http.Request, parameters ...*ScanParameter) bool

ScanParameters scans the request using the given path parameter objects in case an error is encountered a 400 along with a jsonapi errors object is sent to the ResponseWriter and false is returned. Returns true if all values were scanned successfully. The used scanning function is fmt.Sscan

func Unmarshal

func Unmarshal(w http.ResponseWriter, r *http.Request, data interface{}) bool

Unmarshal processes the request content and fills passed data struct with the correct jsonapi content. After un-marshaling the struct will be validated with specified go-validator struct tags. In case of an error, an jsonapi error message will be directly send to the client

func UnmarshalMany

func UnmarshalMany(w http.ResponseWriter, r *http.Request, t reflect.Type) (bool, []interface{})

UnmarshalMany processes the request content that has an array of objects and fills passed data struct with the correct jsonapi content. After un-marshaling the struct will be validated with specified go-validator struct tags. In case of an error, an jsonapi error message will be directly send to the client

func ValidateParameters

func ValidateParameters(w http.ResponseWriter, r *http.Request, data interface{}) bool

ValidateParameters checks the given struct and returns true if the struct is valid according to the specification (declared with go-validator struct tags) In case of an error, an jsonapi error message will be directly send to the client

func ValidateRequest

func ValidateRequest(w http.ResponseWriter, r *http.Request, data interface{}) bool

ValidateRequest checks the given struct and returns true if the struct is valid according to the specification (declared with go-validator struct tags) In case of an error, an jsonapi error message will be directly send to the client

func ValidateStruct

func ValidateStruct(w http.ResponseWriter, r *http.Request, data interface{}, source string) bool

ValidateStruct checks the given struct and returns true if the struct is valid according to the specification (declared with go-validator struct tags) In case of an error, an jsonapi error message will be directly send to the client The passed source is the source for validation errors (e.g. pointer for data or parameter)

func WriteError

func WriteError(w http.ResponseWriter, code int, err error)

WriteError writes a jsonapi error message to the client

Types

type ColumnMapper

type ColumnMapper interface {
	// Map maps the value, this function decides if the value is allowed and translates it to a database column name,
	// the function returns the database column name and a bool that indicates that the value is allowed and mapped
	Map(value string) (string, bool)
}

ColumnMapper maps the name of a filter or sorting parameter to a database column name

type Error

type Error struct {
	// ID is a unique identifier for this particular occurrence of a problem.
	ID string `json:"id,omitempty"`

	// Title is a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
	Title string `json:"title,omitempty"`

	// Detail is a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
	Detail string `json:"detail,omitempty"`

	// Status is the HTTP status code applicable to this problem, expressed as a string value.
	Status string `json:"status,omitempty"`

	// Code is an application-specific error code, expressed as a string value.
	Code string `json:"code,omitempty"`

	// Source an object containing references to the source of the error, optionally including any of the following members:
	Source *map[string]interface{} `json:"source,omitempty"`

	// Meta is an object containing non-standard meta-information about the error.
	Meta *map[string]interface{} `json:"meta,omitempty"`
}

Error objects provide additional information about problems encountered while performing an operation.

func (Error) Error

func (e Error) Error() string

Error implements the error interface

type Errors

type Errors []*Error

Errors is a list of errors

func (Errors) Error

func (e Errors) Error() string

Error implements the error interface

type MapMapper

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

MapMapper is a very easy ColumnMapper implementation based on a map which contains all allowed values and maps them with a map

func NewMapMapper

func NewMapMapper(mapping map[string]string) *MapMapper

NewMapMapper returns a MapMapper for a specific map

func (*MapMapper) Map

func (m *MapMapper) Map(value string) (string, bool)

Map returns the mapped value and if it is valid based on a map

type ScanIn

type ScanIn int

ScanIn help to avoid missuse using iota for the possible values

const (
	// ScanInPath hints the scanner to scan the input
	ScanInPath ScanIn = iota
	// ScanInQuery hints the scanner to scan the request url query
	ScanInQuery
	// ScanInHeader ints the scanner to scan the request header
	ScanInHeader
)

type ScanParameter

type ScanParameter struct {
	// Data contains the reference to the parameter, that should
	// be scanned to
	Data interface{}
	// Where the data can be found for scanning
	Location ScanIn
	// Input must contain the value data if location is in ScanInPath
	Input string
	// Name of the query variable
	Name string
}

ScanParameter configured the ScanParameters function

func (*ScanParameter) BuildInvalidValueError

func (p *ScanParameter) BuildInvalidValueError(typ reflect.Type, data string) error

BuildInvalidValueError build a new error, using the passed type and data

type UrlQueryParameters

type UrlQueryParameters struct {
	HasPagination bool
	PageNr        int
	PageSize      int
	Order         []string
	Filter        map[string][]interface{}
}

UrlQueryParameters contains all information that is needed for pagination, sorting and filtering. It is not depending on orm.Query

func ReadURLQueryParameters

func ReadURLQueryParameters(r *http.Request, mapper ColumnMapper, sanitizer ValueSanitizer) (*UrlQueryParameters, error)

ReadURLQueryParameters reads sorting, filter and pagination from requests and return a UrlQueryParameters object, even if any errors occur. The returned error combines all errors of pagination, filter and sorting.

func (*UrlQueryParameters) AddToQuery

func (u *UrlQueryParameters) AddToQuery(query *orm.Query) *orm.Query

AddToQuery adds filter, sorting and pagination to a orm.Query

type ValueSanitizer

type ValueSanitizer interface {
	// SanitizeValue should sanitize a value, that should be in the column fieldName
	SanitizeValue(fieldName string, value string) (interface{}, error)
}

ValueSanitizer should sanitize query parameter values, the implementation should validate the value and transform it to the right type.

func NewComposableSanitizer

func NewComposableSanitizer(mapping map[string]ValueSanitizer) ValueSanitizer

func NewDatetimeSanitizer

func NewDatetimeSanitizer() ValueSanitizer

func NewDecimalSanitizer

func NewDecimalSanitizer() ValueSanitizer

func NewIntSanitizer

func NewIntSanitizer() ValueSanitizer

func NewNoopSanitizer

func NewNoopSanitizer() ValueSanitizer

func NewUUIDSanitizer

func NewUUIDSanitizer() ValueSanitizer

Notes

Bugs

• the govalidation error has no reference to the original StructField. That makes it impossible to generate correct pointers. Since the actual data structure and the incoming JSON are very different, fork and add struct field tags. Add custom tag and use a custom tag to produce correct source pointer/parameter. https://github.com/pace/bricks/issues/10