Move chi/render sub-pkg as its own package within the go-chi org

Author: Peter Kieltyka

README.md

@@ -0,0 +1,24 @@
+# render
+
+The `render` 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](https://github.com/go-chi/chi/blob/master/_examples/rest/main.go)
+example which uses the latest chi/render sub-pkg.
+
+All feedback is welcome, thank you!
+

content_type.go

@@ -0,0 +1,84 @@
+package render
+
+import (
+	"context"
+	"net/http"
+	"strings"
+)
+
+var (
+	ContentTypeCtxKey = &contextKey{"ContentType"}
+)
+
+// ContentType is an enumeration of common HTTP content types.
+type ContentType int
+
+// ContentTypes handled by this package.
+const (
+	ContentTypeUnknown = iota
+	ContentTypePlainText
+	ContentTypeHTML
+	ContentTypeJSON
+	ContentTypeXML
+	ContentTypeForm
+	ContentTypeEventStream
+)
+
+func GetContentType(s string) ContentType {
+	s = strings.TrimSpace(strings.Split(s, ";")[0])
+	switch s {
+	case "text/plain":
+		return ContentTypePlainText
+	case "text/html", "application/xhtml+xml":
+		return ContentTypeHTML
+	case "application/json", "text/javascript":
+		return ContentTypeJSON
+	case "text/xml", "application/xml":
+		return ContentTypeXML
+	case "application/x-www-form-urlencoded":
+		return ContentTypeForm
+	case "text/event-stream":
+		return ContentTypeEventStream
+	default:
+		return ContentTypeUnknown
+	}
+}
+
+// SetContentType is a middleware that forces response Content-Type.
+func SetContentType(contentType ContentType) func(next http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		fn := func(w http.ResponseWriter, r *http.Request) {
+			r = r.WithContext(context.WithValue(r.Context(), ContentTypeCtxKey, contentType))
+			next.ServeHTTP(w, r)
+		}
+		return http.HandlerFunc(fn)
+	}
+}
+
+// GetRequestContentType is a helper function that returns ContentType based on
+// context or request headers.
+func GetRequestContentType(r *http.Request) ContentType {
+	if contentType, ok := r.Context().Value(ContentTypeCtxKey).(ContentType); ok {
+		return contentType
+	}
+	return GetContentType(r.Header.Get("Content-Type"))
+}
+
+func GetAcceptedContentType(r *http.Request) ContentType {
+	if contentType, ok := r.Context().Value(ContentTypeCtxKey).(ContentType); ok {
+		return contentType
+	}
+
+	var contentType ContentType
+
+	// Parse request Accept header.
+	fields := strings.Split(r.Header.Get("Accept"), ",")
+	if len(fields) > 0 {
+		contentType = GetContentType(strings.TrimSpace(fields[0]))
+	}
+
+	if contentType == ContentTypeUnknown {
+		contentType = ContentTypePlainText
+	}
+	return contentType
+}

decoder.go

@@ -0,0 +1,44 @@
+package render
+
+import (
+	"encoding/json"
+	"encoding/xml"
+	"errors"
+	"io"
+	"io/ioutil"
+	"net/http"
+)
+
+// 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 Decode = DefaultDecoder
+
+func DefaultDecoder(r *http.Request, v interface{}) error {
+	var err error
+
+	switch GetRequestContentType(r) {
+	case ContentTypeJSON:
+		err = DecodeJSON(r.Body, v)
+	case ContentTypeXML:
+		err = DecodeXML(r.Body, v)
+	// case ContentTypeForm: // TODO
+	default:
+		err = errors.New("render: unable to automatically decode the request content type")
+	}
+
+	return err
+}
+
+func DecodeJSON(r io.Reader, v interface{}) error {
+	defer io.Copy(ioutil.Discard, r)
+	return json.NewDecoder(r).Decode(v)
+}
+
+func DecodeXML(r io.Reader, v interface{}) error {
+	defer io.Copy(ioutil.Discard, r)
+	return xml.NewDecoder(r).Decode(v)
+}

render.go

@@ -0,0 +1,134 @@
+package render
+
+import (
+	"net/http"
+	"reflect"
+)
+
+// Renderer interface for managing response payloads.
+type Renderer interface {
+	Render(w http.ResponseWriter, r *http.Request) error
+}
+
+// Binder interface for managing request payloads.
+type Binder interface {
+	Bind(r *http.Request) error
+}
+
+// Bind decodes a request body and executes the Binder method of the
+// payload structure.
+func Bind(r *http.Request, v Binder) error {
+	if err := Decode(r, v); err != nil {
+		return err
+	}
+	return binder(r, v)
+}
+
+// Render renders a single payload and respond to the client request.
+func Render(w http.ResponseWriter, r *http.Request, v Renderer) error {
+	if err := renderer(w, r, v); err != nil {
+		return err
+	}
+	Respond(w, r, v)
+	return nil
+}
+
+// RenderList renders a slice of payloads and responds to the client request.
+func RenderList(w http.ResponseWriter, r *http.Request, l []Renderer) error {
+	for _, v := range l {
+		if err := renderer(w, r, v); err != nil {
+			return err
+		}
+	}
+	Respond(w, r, l)
+	return nil
+}
+
+// Executed top-down
+func renderer(w http.ResponseWriter, r *http.Request, v Renderer) error {
+	rv := reflect.ValueOf(v)
+	if rv.Kind() == reflect.Ptr {
+		rv = rv.Elem()
+	}
+
+	// We call it top-down.
+	if err := v.Render(w, r); err != nil {
+		return err
+	}
+
+	// We're done if the Renderer isn't a struct object
+	if rv.Kind() != reflect.Struct {
+		return nil
+	}
+
+	// For structs, we call Render on each field that implements Renderer
+	for i := 0; i < rv.NumField(); i++ {
+		f := rv.Field(i)
+		if f.Type().Implements(rendererType) {
+
+			if f.IsNil() {
+				continue
+			}
+
+			fv := f.Interface().(Renderer)
+			if err := renderer(w, r, fv); err != nil {
+				return err
+			}
+
+		}
+	}
+
+	return nil
+}
+
+// Executed bottom-up
+func binder(r *http.Request, v Binder) error {
+	rv := reflect.ValueOf(v)
+	if rv.Kind() == reflect.Ptr {
+		rv = rv.Elem()
+	}
+
+	// Call Binder on non-struct types right away
+	if rv.Kind() != reflect.Struct {
+		return v.Bind(r)
+	}
+
+	// For structs, we call Bind on each field that implements Binder
+	for i := 0; i < rv.NumField(); i++ {
+		f := rv.Field(i)
+		if f.Type().Implements(binderType) {
+
+			if f.IsNil() {
+				continue
+			}
+
+			fv := f.Interface().(Binder)
+			if err := binder(r, fv); err != nil {
+				return err
+			}
+		}
+	}
+
+	// We call it bottom-up
+	if err := v.Bind(r); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+var (
+	rendererType = reflect.TypeOf(new(Renderer)).Elem()
+	binderType   = reflect.TypeOf(new(Binder)).Elem()
+)
+
+// contextKey is a value for use with context.WithValue. It's used as
+// a pointer so it fits in an interface{} without allocation. This technique
+// for defining context keys was copied from Go 1.7's new use of context in net/http.
+type contextKey struct {
+	name string
+}
+
+func (k *contextKey) String() string {
+	return "chi render context value " + k.name
+}