parcel

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 1, 2022 License: Apache-2.0 Imports: 6 Imported by: 0

README

parcel

HTTP rendering/binding library for Go

Getting Started

Add to your project

go get github.com/jaredhughes1012/parcel

Usage

Parcel uses renderers/binders globally based on the type of data received. When binding from sources, this detection is done using the "Content-Type" header of the source request or response. When rendering to a target, this uses the type of data passed in for rendering (e.g. text/plain for strings, application/json for structs)

All renderers/binders for a given data type can be modified globally using the corresponding Set method. For example, to change from a json renderer to another type

func Example() {
  parcel.SetObjectRenderer(anothertype.Renderer{})
}

Custom binders/renderers can be created simply by implementing the Renderer or Binder interfaces. Simply pass your custom renderer or binder into one of these global setters to use it globally.

Parcel also supports adding HTTP response data to errors and automatically rendering those errors. By default parcel formats error bodies as JSON objects but plain text can be used as well. These wrapped errors include a status which is automatically set on the response.

Examples

Bind JSON data from Request
type Example struct {
  Field string `json:"field"`
}

func sampleHandler(w http.ResponseWriter, r *http.Request) {
  var data Example
  if err := parcel.BindRequest(r, &data); err != nil {
    parcel.RenderErrorResponse(w, err) // Parcel will return correct http status based on error type
  }
}
Bind text data from Request
func sampleHandler(w http.ResponseWriter, r *http.Request) {
  var data string

  // Parcel will automatically validate text content by using a string receiver
  if err := parcel.BindRequest(r, &data); err != nil {
    parcel.RenderErrorResponse(w, err)
  }
}
Render JSON to response
type Example struct {
  Field string `json:"field"`
}

func sampleHandler(w http.ResponseWriter, r *http.Request) {
  data := Example {
    Field: "test"
  }

  if err := parcel.RenderResponse(w, &data); err != nil {
    parcel.RenderErrorResponse(w, err)
  }
}
Render text to response

func sampleHandler(w http.ResponseWriter, r *http.Request) {
  data := "This will be rendered as text"

  // no need to use a pointer when rendering text
  if err := parcel.RenderResponse(w, data); err != nil {
    parcel.RenderErrorResponse(w, err)
  }
}
Create HTTP error and respond with it

func sampleHandler(w http.ResponseWriter, r *http.Request) {
  err := httperror.New(http.StatusNotFound, "Resource not found")

  // This will set the HTTP response to NotFound(404)
  parcel.RenderErrorResponse(w, err)
}
Wrap existing error with HTTP response

func sampleHandler(w http.ResponseWriter, r *http.Request) {
  err := functionThatFailed()

  // This will set the HTTP response to Conflict(409)
  parcel.RenderErrorResponse(w, httperror.Wrap(http.StatusConflict, err))
}
Render error not wrapped by parcel

func sampleHandler(w http.ResponseWriter, r *http.Request) {
  err := functionThatFailed()

  // This will set the HTTP response to InternalServerError(500)
  parcel.RenderErrorResponse(w, err)
}
Set Global Renderers and Binders
func setHandlers() {
  parcel.SetTextBinder(somepackage.Binder{})
  // This binder will only be used for requests with the mime type "application/sometype"
  parcel.SetObjectBinder("application/sometype", somepackage.Binder{})

  parcel.SetTextRenderer(somepackage.Renderer{})
  parcel.SetObjectRenderer(somepackage.Renderer{})
  parcel.SetErrorRenderer(somepackage.Renderer{})
}

Documentation

Overview

http rendering and binding library, including support for error rendering

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BindFromRequest

func BindFromRequest(r *http.Request, target interface{}) error

Binds data from the request to the given target. Will use a text binder if the target is a string pointer, or an object binder otherwise

func BindFromResponse

func BindFromResponse(r *http.Response, target interface{}) error

Binds data from the request to the given target. Will use a text binder if the target is a string pointer, or an object binder otherwise

func NewRequest

func NewRequest(method, u string, data interface{}) (*http.Request, error)

Creates a new HTTP request and renders the given data into it. Will use the configured text renderer for string data or the configured object renderer for any other data

func RenderErrorResponse

func RenderErrorResponse(w http.ResponseWriter, err error)

Renders an error into an HTTP response. Uses JSON formatting by default but can be configured to use any renderer. Will use the status of any HTTP error or InternalServerError(500) if the error is not an http error

func RenderResponse

func RenderResponse(w http.ResponseWriter, status int, data interface{}) error

Renders data from the given data into an HTTP response. Will use the configured text renderer for string data or the configured object renderer for any other data

func SetErrorRenderer

func SetErrorRenderer(r Renderer)

Sets the default renderer for any error responses

func SetObjectBinder

func SetObjectBinder(contentType string, b Binder)

Sets the default binder for any object responses of the given content type

func SetObjectRenderer

func SetObjectRenderer(r Renderer)

Sets the default renderer for any object responses

func SetTextBinder

func SetTextBinder(b Binder)

Sets the default renderer for any plain text responses

func SetTextRenderer

func SetTextRenderer(r Renderer)

Sets the default renderer for any plain text responses

Types

type Binder

type Binder interface {
	// Binds data from an HTTP request into a destination
	BindFromRequest(r *http.Request, target interface{}) error

	// Binds data from an HTTP response into a destination
	BindFromResponse(r *http.Response, target interface{}) error
}

Handles binding data from a source to a destination

type Renderer

type Renderer interface {
	// Renders data to an HTTP response writer
	RenderResponse(w http.ResponseWriter, status int, data interface{}) error

	// Creates a new HTTP request and renders data to the body of the request
	NewRequest(method, destination string, data interface{}) (*http.Request, error)

	// Renders an error to an HTTP response
	RenderErrorResponse(w http.ResponseWriter, err error)
}

Renders data from a source to a destination

Directories

Path Synopsis
Built in parcel formatting for JSON
Built in parcel formatting for JSON
Built in parcel formatting for plain text
Built in parcel formatting for plain text

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL