render

README

render

render errors as response meta.

Documentation

Index

• Constants
• Variables
• func Err(w http.ResponseWriter, r *http.Request, err error, opts ...Option) error
• func Get(rp *Response, key any) (any, bool)
• func OK(w http.ResponseWriter, r *http.Request, data interface{}, opts ...Option) error
• type ContentType
  • func GetRenderByName(name string) ContentType
  • func Negotiate(r *http.Request) ContentType
  • func (ct ContentType) Err(w http.ResponseWriter, r *http.Request, err error, opts ...Option) error
  • func (ct ContentType) Header() []string
  • func (ct ContentType) OK(w http.ResponseWriter, r *http.Request, data interface{}, opts ...Option) error
  • func (ct ContentType) Ready() bool
  • func (ct ContentType) Render(w http.ResponseWriter, rp interface{}, opts ...Option) error
• type Negotiater
• type Option
• type Render
• type RenderFunc
  • func (rf RenderFunc) Render(w http.ResponseWriter, data interface{}, opts ...Option) error
• type Response
  • func (rp *Response) Body() any
  • func (rp *Response) Header() http.Header
  • func (rp *Response) Status() int
• type ResponseInterface
  • func NewResponse(data any, opts ...ResponseOption) ResponseInterface
• type ResponseOption
  • func WithError(err error) ResponseOption
  • func WithKV(k, v any) ResponseOption
  • func WithTemplate(tmpl string) ResponseOption
• type ResponseTransformer

Constants

const (
	// ContentTypeHeader `Content-Type` header name
	ContentTypeHeader = "Content-Type"

	// AcceptHeader `Accept` header name
	AcceptHeader = "Accept"

	// TemplateHeader custom `X-Render-Template` header name, used to specify the render template,
	// can be used as request header and response header
	TemplateHeader = "X-Render-Template"
)

const DefaultNegotiaterName = ""

DefaultNegotiaterName default negotiater name

Variables

var (
	// Renders the renders registry, it's aim to store third party renders,
	// note, that's no need to store the `Response` render like JSON, HTML, ...
	Renders = inithook.NewMap[ContentType, Render]()

	// ContentTypes used to store the mapping of the name to `ContentType`
	ContentTypes = inithook.NewMap[string, ContentType]()

	// Negotiaters the negotiaters registry, now only the DefaultNegotiaterName used
	Negotiaters = inithook.NewMap[string, Negotiater]()
)

var (
	// R is abbr. of GetRenderByName
	R = GetRenderByName

	// N is abbr. of Negotiate
	N = Negotiate
)

var (
	// E is abbr. of `WithError`
	E = WithError

	// KV is abbr. of `WithKV`
	KV = WithKV

	// T is abbr. of `WithTemplate`
	T = WithTemplate
)

var Transformers = inithook.NewMap[string, ResponseTransformer]()

Transformers defines the ResponseTransformer registry, key is the transformer name

Functions

func Err

func Err(w http.ResponseWriter, r *http.Request, err error, opts ...Option) error

Err is shortcut for JSON.Err

func Get

func Get(rp *Response, key any) (any, bool)

Get used to get value specified by key from Response's Extension or error's values if found, return the value and true, otherwise return nil and false

func OK

func OK(w http.ResponseWriter, r *http.Request, data interface{}, opts ...Option) error

OK is shortcut for JSON.OK

Types

type ContentType

type ContentType string

ContentType defines the content type render

const (
	// JSON content type render for json
	JSON ContentType = "application/json; charset=utf-8"

	// JSONASCII content type render for json arcii
	JSONASCII ContentType = "application/json"

	// JSONP content type render for jsonp
	JSONP ContentType = "application/javascript; charset=utf-8"

	// HTML content type render for html
	HTML ContentType = "text/html; charset=utf-8"

	// Text content type render for text
	Text ContentType = "text/plain; charset=utf-8"

	PROTOBUF ContentType = "application/x-protobuf"

	// Binary content type render for binary
	Binary ContentType = "application/octet-stream"

	// YAML content type render for yaml
	YAML ContentType = "application/x-yaml; charset=utf-8"

	// TOML content type render for toml
	TOML ContentType = "application/toml; charset=utf-8"

	// MSGPACK content type render for msgpack
	MSGPACK ContentType = "application/msgpack; charset=utf-8"

	// XML content type render for xml
	XML ContentType = "application/xml; charset=utf-8"

	// XHTML content type render for xhtml
	XHTML ContentType = "application/xhtml+xml; charset=utf-8"
)

func GetRenderByName

func GetRenderByName(name string) ContentType

GetRenderByName returns the content type for name

func Negotiate

func Negotiate(r *http.Request) ContentType

Negotiate used to select the response content-type according to http request, default to `JSON` The default behavior can be changed, e.g.

    import "github.com/timewasted/go-accept-headers"

    type AcceptNegotiater struct{}

    func (n AcceptNegotiater) Negotiate(acceptHeader string, ctypes ...string) (ctype string, err error) {
    	   return accept.Parse(acceptHeader).Negotiate(ctypes...)
    }

    func init(){
	       _ = render.Negotiaters.Set(ctx, render.DefaultNegotiaterName, AcceptNegotiater{})
    }

func (ContentType) Err

func (ct ContentType) Err(w http.ResponseWriter, r *http.Request, err error, opts ...Option) error

func (ContentType) Header

func (ct ContentType) Header() []string

Header returns header value slice of content type

func (ContentType) OK

func (ct ContentType) OK(w http.ResponseWriter, r *http.Request, data interface{}, opts ...Option) error

OK do render for success with data as result, and automatic select template with `*http.Request`

func (ContentType) Ready

func (ct ContentType) Ready() bool

func (ContentType) Render

func (ct ContentType) Render(w http.ResponseWriter, rp interface{}, opts ...Option) error

Render implement `Render` interface, mainly used to extra suppport `ResponseInterface`

type Negotiater

type Negotiater interface {
	Negotiate(acceptHeader string, ctypes ...string) (ctype string, err error)
}

Negotiater used to negotiate content type between client accepts and server supports

type Option

type Option func(any)

Option used to support the `Render` with dynamic parameters, e.g., jsonp, html, ...

type Render

type Render interface {
	Render(http.ResponseWriter, interface{}, ...Option) error
}

Redner defines method to render any to http response writer

type RenderFunc

type RenderFunc func(http.ResponseWriter, interface{}, ...Option) error

RenderFunc defines the function that implement Render

func (RenderFunc) Render

func (rf RenderFunc) Render(w http.ResponseWriter, data interface{}, opts ...Option) error

type Response

type Response struct {
	errors.MetaError
	Data      any
	Extension map[any]any
	Template  string
	// contains filtered or unexported fields
}

Response aims to provide a widely applicable `ResponseInterface` implementation, it's made up the following elements:

- Data: any object that will be rendered by concrete render, e.g. gin/render.JSON, unrolled/render.XML, ... - MetaError: contributes the response meta from the error(include all values it carries), use `WithError`(E) to specify - Extension: any kvs used to extend the `Response`, use `WithKV`(KV) to specify - Template: used to specify the variant of `Response`, use `WithTemplate`(T) to specify

See tests for more details.

func (*Response) Body

func (rp *Response) Body() any

Body implement `ResponseInterface` as default

func (*Response) Header

func (rp *Response) Header() http.Header

Header implement `ResponseInterface` as default

func (*Response) Status

func (rp *Response) Status() int

Status implement `ResponseInterface` as default

type ResponseInterface

type ResponseInterface interface {
	// Status returns http status
	Status() int

	// Header returns http headers
	Header() http.Header

	// Body returns the http body
	Body() any
}

ResponseInterface defines http response interface

func NewResponse

func NewResponse(data any, opts ...ResponseOption) ResponseInterface

NewResponse creates a new *Response instance and returns it or it's variant as `ResponseInterface`

type ResponseOption

type ResponseOption func(*Response)

ResponseOption `Response` creation option func

func WithError

func WithError(err error) ResponseOption

WithError used to specify `MetaError` of `Response`

func WithKV

func WithKV(k, v any) ResponseOption

WithKV used to specify `Extension` elements of `Response`

func WithTemplate

func WithTemplate(tmpl string) ResponseOption

WithTemplate used to specify the returned `Response` variant

type ResponseTransformer

type ResponseTransformer func(*Response) ResponseInterface

ResponseTransformer used to transform `*Response` to it's variant