jsonware

README

See documentation at http://godoc.org/github.com/aarondl/jsonware

Documentation

Overview

Package jsonware has a middleware setup for doing RESTful reqeuests with net/http. It makes it easy to unobtrusively serialize and deserialize json in a type safe manner, and handle errors from the internal handlers including logging.

Index

• func Log(logger io.Writer)
• type Err
  • func (e Err) Error() string
• type JSONHandler
  • func Handler(fn interface{}) *JSONHandler
  • func (j *JSONHandler) Log(logger io.Writer) *JSONHandler
  • func (j JSONHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

Functions

func Log

func Log(logger io.Writer)

Log sets the global logger for cloaked errors. Not safe for use by multiple goroutines, do this before your http server has been started.

Types

type Err

type Err struct {
	Status int
	Err    error
	Reason interface{}
}

Err can be used in a JSONHandler to override the error mechanism in JSONHandler's ServeHTTP method. If a status is set it will obey it, otherwise it will assume 200 OK. The error message will be relayed to the client. If you wish to use a general server error, simply return error from the handler.

func handler(w http.ResponseWriter, r *http.Request) (interface{}, error) {
	return nil, nil // No response from ServeHTTP, use w to create one.
}

func handler(w http.ResponseWriter, r *http.Request) (interface{}, error) {
	return nil, errors.New("hi") // 500 Response with cloaked+logged error.
}

func handler(w http.ResponseWriter, r *http.Request) (interface{}, error) {
	return nil, Err{Err: errors.New("hi")} // 200 Response with error output to client
}

func handler(w http.ResponseWriter, r *http.Request) (interface{}, error) {
	return nil, Err{Status: 400, Err: errors.New("hi")} // 400 Response with error output to client
}

func handler(w http.ResponseWriter, r *http.Request) (interface{}, error) {
	return nil, Err{
		Status: 400,
		Err: errors.New("hi")
		Reason: []string{"anything", "serializable", "to", "json"},
	} // 400 Response with error output to client
}

func (Err) Error

func (e Err) Error() string

Error returns Error() from the internal error.

type JSONHandler

type JSONHandler struct {
	// contains filtered or unexported fields
}

JSONHandler handles json api endpoint restful requests. It can be constructed by passing a suitable function into the JSON function.

Error handling is handled differently depending on whether or not Err was used to report the error. See Err documentation to understand how to control error handling.

Cloaked errors are handled by reporting a generic error to the client and logging the error locally. The log can be set globally via jsonware.Log() or on each individual handler as an override by the .Log() function there.

// Register a JSONHandler.
http.Handle("/", Handler(myHandler).Log(myLogger))

func Handler

func Handler(fn interface{}) *JSONHandler

Handler changes a function into a JSONHandler. Acceptable forms of the input function:

GET/DELETE (Note: all variant return types also work with POST/PUT/PATCH)
func Fn(w http.ResponseWriter, r *http.Request) (interface{}, error)
func Fn(w http.ResponseWriter, r *http.Request) (*MyStruct, error)
func Fn(w http.ResponseWriter, r *http.Request) ([]*MyStruct, error)
func Fn(w http.ResponseWriter, r *http.Request) (map[string]*MyStruct, error)

POST/PUT/PATCH
func Fn(w http.ResponseWriter, r *http.Request, m *MyStruct) (interface{}, error)
func Fn(w http.ResponseWriter, r *http.Request, m []*MyStruct) (interface{}, error)
func Fn(w http.ResponseWriter, r *http.Request, m map[string]*MyStruct) (interface{}, error)

func (*JSONHandler) Log

func (j *JSONHandler) Log(logger io.Writer) *JSONHandler

Log sets the JSONHandler's logging io.Writer for writing out cloaked errors.

func (JSONHandler) ServeHTTP

func (j JSONHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves an http response, see JSONHandler documentation for details.