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

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
• func Marshal(w http.ResponseWriter, data interface{}, code int)
• 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 Decimal
  • func DecimalFrom(d decimal.Decimal) Decimal
  • func (d Decimal) Decode() decimal.Decimal
• 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 QueryOption
  • func FilterFromRequest(r *http.Request, modelMapping ColumnMapper, sanitizer ValueSanitizer) (QueryOption, error)
  • func FilterPagingSortingFromRequest(r *http.Request, modelMapping ColumnMapper, sanitizer ValueSanitizer) (QueryOption, error)
  • func PaginationFromRequest(r *http.Request) (QueryOption, error)
  • func SortingFromRequest(r *http.Request, modelMapping ColumnMapper) (QueryOption, error)
• type ScanIn
• type ScanParameter
• type ValueSanitizer
• Bugs

Constants

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

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

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 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 Decimal

type Decimal string

func DecimalFrom

func DecimalFrom(d decimal.Decimal) Decimal

func (Decimal) Decode

func (d Decimal) Decode() decimal.Decimal

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 QueryOption

type QueryOption func(query *orm.Query) *orm.Query

QueryOption is a function that applies an option (like sorting, filter or pagination) to a database query

func FilterFromRequest

func FilterFromRequest(r *http.Request, modelMapping ColumnMapper, sanitizer ValueSanitizer) (QueryOption, error)

FilterFromRequest adds filter to a query based on the request query parameter filter[name]=val1,val2 results in name IN (val1, val2), filter[name]=val results in name=val Database model and response type may differ, so the mapper allows to map the name of field from the request to a database column name and the sanitizer allows to correct type of the value and sanitize it. Will always return a QueryOptions function with all valid filters (can be a nop) if any filter are invalid a error with a list of all invalid filters is returned

func FilterPagingSortingFromRequest

func FilterPagingSortingFromRequest(r *http.Request, modelMapping ColumnMapper, sanitizer ValueSanitizer) (QueryOption, error)

FilterPagingSortingFromRequest adds filter, sorting and pagination to a query based on the request query parameters this function combines filter, sorting and pagination because in most of the cases they are all needed.

func PaginationFromRequest

func PaginationFromRequest(r *http.Request) (QueryOption, error)

PaginationFromRequest extracts pagination query parameter and returns a function that adds the pagination to a query

func SortingFromRequest

func SortingFromRequest(r *http.Request, modelMapping ColumnMapper) (QueryOption, error)

SortingFromRequest adds sorting to query based on the request query parameter Database model and response type may differ, so the mapper allows to map the name of field from the request to a database column name returns a (possible nop) queryOption, even if any sorting parameter was invalid The error contains a list of all invalid parameters. Invalid parameters are not added to the query.

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

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.

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