README
¶
httprequest
-- import "github.com/juju/httprequest"
Package httprequest provides functionality for unmarshaling HTTP request parameters into a struct type.
Usage
func Unmarshal
func Unmarshal(p Params, x interface{}) error
Unmarshal takes values from given parameters and fills out fields in x, which must be a pointer to a struct.
Tags on the struct's fields determine where each field is filled in from. Similar to encoding/json and other encoding packages, the tag holds a comma-separated list. The first item in the list is an alternative name for the field (the field name itself will be used if this is empty). The next item specifies where the field is filled in from. It may be:
"path" - the field is taken from a parameter in p.PathVar
with a matching field name.
"form" - the field is taken from the given name in p.Form
(note that this covers both URL query parameters and
POST form parameters)
"body" - the field is filled in by parsing the request body
as JSON.
For path and form parameters, the field will be filled out from the field in p.PathVar or p.Form using one of the following methods (in descending order of preference):
-
if the type is string, it will be set from the first value.
-
if the type is []string, it will be filled out using all values for that field
(allowed only for form)
-
if the type implements encoding.TextUnmarshaler, its UnmarshalText method will be used
-
otherwise fmt.Sscan will be used to set the value.
type Params
type Params struct {
*http.Request
PathVar httprouter.Params
}
Params holds request parameters that can be unmarshaled into a struct.
Documentation
¶
Overview ¶
Package httprequest provides functionality for unmarshaling HTTP request parameters into a struct type.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrUnmarshal = errgo.New("httprequest unmarshal error") ErrBadUnmarshalType = errgo.New("httprequest bad unmarshal type") )
Functions ¶
func ToHTTP ¶
func ToHTTP(h httprouter.Handle) http.Handler
ToHTTP converts an httprouter.Handle into an http.Handler. It will pass no path variables to h.
func Unmarshal ¶
Unmarshal takes values from given parameters and fills out fields in x, which must be a pointer to a struct.
Tags on the struct's fields determine where each field is filled in from. Similar to encoding/json and other encoding packages, the tag holds a comma-separated list. The first item in the list is an alternative name for the field (the field name itself will be used if this is empty). The next item specifies where the field is filled in from. It may be:
"path" - the field is taken from a parameter in p.PathVar with a matching field name. "form" - the field is taken from the given name in p.Form (note that this covers both URL query parameters and POST form parameters) "body" - the field is filled in by parsing the request body as JSON.
For path and form parameters, the field will be filled out from the field in p.PathVar or p.Form using one of the following methods (in descending order of preference):
- if the type is string, it will be set from the first value.
- if the type is []string, it will be filled out using all values for that field (allowed only for form)
- if the type implements encoding.TextUnmarshaler, its UnmarshalText method will be used
- otherwise fmt.Sscan will be used to set the value.
When the unmarshaling fails, Unmarshal returns an error with an ErrUnmarshal cause. If the type of x is inappropriate, it returns an error with an ErrBadUnmarshalType cause.
Types ¶
type ErrorHandler ¶
type ErrorHandler func(http.ResponseWriter, Params) error
ErrorHandler is like httprouter.Handle except it returns an error which may be returned as the error body of the response. An ErrorHandler function should not itself write to the ResponseWriter if it returns an error.
type ErrorMapper ¶
ErrorMapper holds a function that can convert a Go error into a form that can be returned as a JSON body from an HTTP request. The httpStatus value reports the desired HTTP status.
func (ErrorMapper) Handle ¶
func (e ErrorMapper) Handle(f interface{}) httprouter.Handle
Handle converts a function into an httprouter.Handle. The argument f must be a function of one of the following three forms, where ArgT must be a struct type acceptable to Unmarshal and ResultT is a type that can be marshaled as JSON:
func(w http.ResponseWriter, p Params, arg *ArgT) func(w http.ResponseWriter, p Params, arg *ArgT) error func(header http.Header, p Params, arg *ArgT) (ResultT, error)
When processing a call to the returned handler, the provided parameters are unmarshaled into a new ArgT value using Unmarshal, then f is called with this value. If the unmarshaling fails, f will not be called and the unmarshal error will be written as a JSON response.
If an error is returned from f, it is passed through the error mapper before writing as a JSON response.
In the third form, when no error is returned, the result is written as a JSON response with status http.StatusOK.
Handle will panic if the provided function is not in one of the above forms.
func (ErrorMapper) HandleErrors ¶
func (e ErrorMapper) HandleErrors(handle ErrorHandler) httprouter.Handle
HandleErrors returns a handler that passes any non-nil error returned by handle through the error mapper and writes it as a JSON response.
func (ErrorMapper) HandleJSON ¶
func (e ErrorMapper) HandleJSON(handle JSONHandler) httprouter.Handle
HandleJSON returns a handler that writes the return value of handle as a JSON response. If handle returns an error, it is passed through the error mapper.
func (ErrorMapper) WriteError ¶
func (e ErrorMapper) WriteError(w http.ResponseWriter, err error)
WriteError writes an error to a ResponseWriter and sets the HTTP status code.
type JSONHandler ¶
JSONHandler is like httprouter.Handle except that it returns a body (to be converted to JSON) and an error. The Header parameter can be used to set custom headers on the response.
Source Files