codec

Documentation

Index

• Constants
• Variables
• type Codec
• type Error
  • func (e *Error) Error() string
• type FieldAnnotations
  • func ExtractFieldAnnotations(sField *mapping.StructField, tag string) FieldAnnotations
• type LinkOptions
• type LinkType
• type MarshalOptions
• type Meta
• type ModelMarshaler
• type ModelUnmarshaler
• type MultiError
  • func (m MultiError) Error() string
  • func (m MultiError) Status() int
• type PaginationLinks
• type ParameterExtractor
• type ParameterParser
• type Payload
• type PayloadMarshaler
• type PayloadUnmarshaler
• type UnmarshalOptions

Constants

const ISO8601TimeFormat = "2006-01-02T15:04:05Z"

ISO8601TimeFormat is the time formatting for the ISO 8601.

const StructTag = "codec"

StructTag is a constant used as a tag that defines models codecs.

Variables

var (
	// ErrCodec is a general codec error.
	ErrCodec = errors.New("codec")
	// ErrMarshal is an error with marshaling.
	ErrMarshal = errors.Wrap(ErrCodec, "marshal")
	// ErrMarshalPayload is an error of marshaling payload.
	ErrMarshalPayload = errors.Wrap(ErrMarshal, "payload")

	// ErrUnmarshal is an error related to unmarshaling process.
	ErrUnmarshal = errors.Wrap(ErrCodec, "unmarshal")
	// ErrUnmarshalDocument is an error related to unmarshaling invalid document,
	ErrUnmarshalDocument = errors.Wrap(ErrUnmarshal, "document")
	// ErrUnmarshalFieldValue is an error related to unmarshaling field value.
	ErrUnmarshalFieldValue = errors.Wrap(ErrUnmarshal, "field value")
	// ErrUnmarshalFieldName is an error related t unmarshaling field name
	ErrUnmarshalFieldName = errors.Wrap(ErrUnmarshal, "field name")
)

Types

type Codec

type Codec interface {
	// MarshalErrors marshals given errors.
	MarshalErrors(w io.Writer, errors ...*Error) error
	// UnmarshalErrors unmarshal provided errors.
	UnmarshalErrors(r io.Reader) (MultiError, error)
	// MimeType returns the mime type that this codec is defined for.
	MimeType() string
}

Codec is an interface used to marshal and unmarshal data, payload and errors in some encoding type.

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 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"`
	// Meta is an object containing non-standard meta-information about the error.
	Meta Meta `json:"meta,omitempty"`
}

Error is the error structure used for used for codec processes. More info can be found at: 'https://jsonapi.org/format/#errors'

func (*Error) Error

func (e *Error) Error() string

type FieldAnnotations

type FieldAnnotations struct {
	Name        string
	IsHidden    bool
	IsOmitEmpty bool
	Custom      []*mapping.FieldTag
}

FieldAnnotations is structure that is extracted from the given sField codec specific annotation.

func ExtractFieldAnnotations

func ExtractFieldAnnotations(sField *mapping.StructField, tag string) FieldAnnotations

ExtractFieldAnnotations extracts codec specific tags.

type LinkOptions

type LinkOptions struct {
	// Type defines link type.
	Type LinkType
	// BaseURL should be the common base url for all the links.
	BaseURL string
	// Collection is the link root collection name.
	Collection string
	// RootID is the root collection primary value.
	RootID string
	// RelatedField is the related field name used in the relationship link type.
	RelationField string
}

LinkOptions contains link options required for marshaling codec data.

type LinkType

type LinkType int

LinkType is the link type used for marshaling.

const (
	NoLink LinkType = iota
	ResourceLink
	RelatedLink
	RelationshipLink
)

Link type enumerators.

type MarshalOptions

type MarshalOptions struct {
	Link         LinkOptions
	SingleResult bool
}

MarshalOptions is a structure that contains marshaling information.

type Meta

type Meta map[string]interface{}

Meta is used to represent a `meta` object. http://jsonapi.org/format/#document-meta

type ModelMarshaler

type ModelMarshaler interface {
	// MarshalModels marshal provided models into given codec encoding type. The function should
	// simply encode only provided models without any additional payload like metadata.
	MarshalModels(models []mapping.Model, options MarshalOptions) ([]byte, error)
}

ModelMarshaler is an interface that allows to marshal provided models.

type ModelUnmarshaler

type ModelUnmarshaler interface {
	// UnmarshalModels unmarshals provided data into mapping.Model slice. The data should simply be only encoded models.
	UnmarshalModels(data []byte, options UnmarshalOptions) ([]mapping.Model, error)
}

ModelUnmarshaler is an interface that allows to unmarshal provided models of given model struct.

type MultiError

type MultiError []*Error

MultiError is an error composed of multiple single errors.

func (MultiError) Error

func (m MultiError) Error() string

func (MultiError) Status

func (m MultiError) Status() int

Status gets the most significant api error status.

type PaginationLinks

type PaginationLinks struct {
	// Self should be just a query too
	Self  string `json:"self,omitempty"`
	First string `json:"first,omitempty"`
	Prev  string `json:"prev,omitempty"`
	Next  string `json:"next,omitempty"`
	Last  string `json:"last,omitempty"`

	Total int64 `json:"total"`
}

PaginationLinks is the structure that contain options for the pagination links. https://jsonapi.org/examples/#pagination

type ParameterExtractor

type ParameterExtractor interface {
	ExtractParameters(c *controller.Controller, q *query.Scope) (query.Parameters, error)
}

ParameterExtractor is an interface that extracts query parameters from given scope.

type ParameterParser

type ParameterParser interface {
	ParseParameters(c *controller.Controller, q *query.Scope, parameters query.Parameters) error
}

ParameterParser is an interface that parses parameters in given codec format.

type Payload

type Payload struct {
	// Payload defined model structure.
	ModelStruct *mapping.ModelStruct
	// Data contains models data.
	Data []mapping.Model
	// FieldSets is the index based field sets that maps it's indexes with the data.
	FieldSets []mapping.FieldSet
	// Meta is an object containing non-standard meta-information about the error.
	Meta Meta
	// IncludedRelations is the information about included relations in the payload.
	IncludedRelations []*query.IncludedRelation
	// Options are the options for the codecs how to treat the payload.
	PaginationLinks *PaginationLinks
	// MarshalLinks are the links used to marshal for specific codecs.
	MarshalLinks LinkOptions
	// MarshalSingularFormat marshals single model in a singular format for given codec.
	MarshalSingularFormat bool
}

Payload is the default structure used by codecs to marshal and unmarshal.

type PayloadMarshaler

type PayloadMarshaler interface {
	MarshalPayload(w io.Writer, payload *Payload) error
}

PayloadMarshaler is the interface used to marshal payload into provided writer..

type PayloadUnmarshaler

type PayloadUnmarshaler interface {
	UnmarshalPayload(r io.Reader, options UnmarshalOptions) (*Payload, error)
}

PayloadUnmarshaler is the interface used to unmarshal payload from given reader for provided codec type.

type UnmarshalOptions

type UnmarshalOptions struct {
	StrictUnmarshal   bool
	IncludedRelations []*query.IncludedRelation
	ModelStruct       *mapping.ModelStruct
}

UnmarshalOptions is the structure that contains unmarshal options.