render

README

chi/render

The render sub-package helps manage HTTP request / response payloads.

Every well-designed, robust and maintainable Web Service / REST API also needs well-defined request and response payloads. Together with the endpoint handlers, the request and response payloads make up the contract between your server and the clients calling on it.

Typically in a REST API application, you will have your data models (objects/structs) that hold lower-level runtime application state, and at times you need to assemble, decorate, hide or transform the representation before responding to a client. That server output (response payload) structure, is also likely the input structure to another handler on the server.

This is where render comes in - offering a few simple helpers and interfaces to provide a simple pattern for managing payload encoding and decoding.

We've also combined it with some helpers for responding to content types and parsing request bodies. Please have a look at the rest example which uses the latest chi/render sub-pkg.

All feedback is welcome, thank you!

Documentation

Index

• Constants
• Variables
• func Bind(r *http.Request, v Binder) error
• func Data(w http.ResponseWriter, r *http.Request, v []byte)
• func DecodeJSON(r io.Reader, v interface{}) error
• func DecodeXML(r io.Reader, v interface{}) error
• func DefaultDecoder(r *http.Request, v interface{}) error
• func DefaultResponder(w http.ResponseWriter, r *http.Request, v interface{})
• func HTML(w http.ResponseWriter, r *http.Request, v string)
• func JSON(w http.ResponseWriter, r *http.Request, v interface{})
• func NoContent(w http.ResponseWriter, r *http.Request)
• func PlainText(w http.ResponseWriter, r *http.Request, v string)
• func Render(w http.ResponseWriter, r *http.Request, v Renderer) error
• func RenderList(w http.ResponseWriter, r *http.Request, l []Renderer) error
• func SetContentType(contentType ContentType) func(next http.Handler) http.Handler
• func Status(r *http.Request, status int)
• func XML(w http.ResponseWriter, r *http.Request, v interface{})
• type Binder
• type ContentType
  • func GetAcceptedContentType(r *http.Request) ContentType
  • func GetContentType(s string) ContentType
  • func GetRequestContentType(r *http.Request) ContentType
• type M
• type Renderer

Constants

const (
	ContentTypeUnknown = iota
	ContentTypePlainText
	ContentTypeHTML
	ContentTypeJSON
	ContentTypeXML
	ContentTypeForm
	ContentTypeEventStream
)

ContentTypes handled by this package.

Variables

var (
	ContentTypeCtxKey = &contextKey{"ContentType"}
)

var Decode = DefaultDecoder

Decode is a package-level variable set to our default Decoder. We do this because it allows you to set render.Decode to another function with the same function signature, while also utilizing the render.Decoder() function itself. Effectively, allowing you to easily add your own logic to the package defaults. For example, maybe you want to impose a limit on the number of bytes allowed to be read from the request body.

var Respond = DefaultResponder

Respond is a package-level variable set to our default Responder. We do this because it allows you to set render.Respond to another function with the same function signature, while also utilizing the render.Responder() function itself. Effectively, allowing you to easily add your own logic to the package defaults. For example, maybe you want to test if v is an error and respond differently, or log something before you respond.

var StatusCtxKey = &contextKey{"Status"}

StatusCtxKey is a context key to record a future HTTP response status code.

Functions

func Bind

func Bind(r *http.Request, v Binder) error

Bind decodes a request body and executes the Binder method of the payload structure.

func Data

func Data(w http.ResponseWriter, r *http.Request, v []byte)

Data writes raw bytes to the response, setting the Content-Type as application/octet-stream.

func DecodeJSON

func DecodeJSON(r io.Reader, v interface{}) error

func DecodeXML

func DecodeXML(r io.Reader, v interface{}) error

func DefaultDecoder

func DefaultDecoder(r *http.Request, v interface{}) error

func DefaultResponder

func DefaultResponder(w http.ResponseWriter, r *http.Request, v interface{})

Respond handles streaming JSON and XML responses, automatically setting the Content-Type based on request headers. It will default to a JSON response.

func HTML

func HTML(w http.ResponseWriter, r *http.Request, v string)

HTML writes a string to the response, setting the Content-Type as text/html.

func JSON

func JSON(w http.ResponseWriter, r *http.Request, v interface{})

JSON marshals 'v' to JSON, automatically escaping HTML and setting the Content-Type as application/json.

func NoContent

func NoContent(w http.ResponseWriter, r *http.Request)

NoContent returns a HTTP 204 "No Content" response.

func PlainText

func PlainText(w http.ResponseWriter, r *http.Request, v string)

PlainText writes a string to the response, setting the Content-Type as text/plain.

func Render

func Render(w http.ResponseWriter, r *http.Request, v Renderer) error

Render renders a single payload and respond to the client request.

func RenderList

func RenderList(w http.ResponseWriter, r *http.Request, l []Renderer) error

RenderList renders a slice of payloads and responds to the client request.

func SetContentType

func SetContentType(contentType ContentType) func(next http.Handler) http.Handler

SetContentType is a middleware that forces response Content-Type.

func Status

func Status(r *http.Request, status int)

Status sets a HTTP response status code hint into request context at any point during the request life-cycle. Before the Responder sends its response header it will check the StatusCtxKey

func XML

func XML(w http.ResponseWriter, r *http.Request, v interface{})

XML marshals 'v' to JSON, setting the Content-Type as application/xml. It will automatically prepend a generic XML header (see encoding/xml.Header) if one is not found in the first 100 bytes of 'v'.

Types

type Binder

type Binder interface {
	Bind(r *http.Request) error
}

Binder interface for managing request payloads.

type ContentType

type ContentType int

ContentType is an enumeration of common HTTP content types.

func GetAcceptedContentType

func GetAcceptedContentType(r *http.Request) ContentType

func GetContentType

func GetContentType(s string) ContentType

func GetRequestContentType

func GetRequestContentType(r *http.Request) ContentType

GetRequestContentType is a helper function that returns ContentType based on context or request headers.

type M

type M map[string]interface{}

M is a convenience alias for quickly building a map structure that is going out to a responder. Just a short-hand.

type Renderer

type Renderer interface {
	Render(w http.ResponseWriter, r *http.Request) error
}

Renderer interface for managing response payloads.