Awesome
nvelope - http endpoint helpers in an nject world
Install:
go get github.com/muir/nvelope
Prior to nject version 0.2.0, this was part of that repo. As of release 0.2.0, GenerateDecoder no longer depends upon gorilla/mux. Some additional effort is now required to extract data from path/route variables and the pre-defined decoders DecodeJSON and DecodeXML have been removed.
Nvelope provides pre-defined handlers for basic endpoint tasks. When used in combination with npoint or nape, all that's left is the business logic. It is based upon nject.
An Example
type ExampleRequestBundle struct {
Request PostBodyModel `nvelope:"model"`
With string `nvelope:"path,name=with"`
Parameters int64 `nvelope:"path,name=parameters"`
Friends []int `nvelope:"query,name=friends"`
ContentType string `nvelope:"header,name=Content-Type"`
}
func Service(router *mux.Router) {
service := nape.RegisterServiceWithMux("example", router)
service.RegisterEndpoint("/some/path",
nvelope.LoggerFromStd(log.Default()),
nvelope.InjectWriter,
nvelope.EncodeJSON,
nvelope.CatchPanic,
nvelope.Nil204,
nvelope.ReadBody,
DecodeJSON,
func (req ExampleRequestBundle) (nvelope.Response, error) {
....
},
).Methods("POST")
}
Typical chain
A typical endpoint wrapping chan contains some or all of the following.
Create a logger
This is an option step that is recommended if you're using request-specific
loggers. The encoding provider can uses a logger that implements the
nvelope.BasicLogger
interface. nvelope.LoggerFromStd
can create
an nvelope.BasicLogger
from the "log" logger. nvelope.NoLogger
provides
a nvelope.BasicLogger
that does nothing.
Deferred Writer
Use nvelope.InjectWriter
to create a *DeferredWriter
. A *DeferredWriter
is a
useful enchancement to http.ResponseWriter
that allows the output to be reset and
allows headers to be set at any time. The cost of a *DeferredWriter
is that
the output is buffered and copied.
Marshal response
We need the request encoder this early in the framework so that it can marshal error responses.
A JSON marshaller is provided: nvelope.EncodeJSON
. Other
response encoders can be created with nvelope.MakeResponseEncoder
.
Catch panics
Have the endpoint return a 500 when there is a panic.
nvelope.SetErrorOnPanic()
is a function that can be deferred to
notice a panic and create a useful error. In an injection
chain, use nvelope.CatchPanic
.
Return 204 for nil responses
Use an extra injector to trigger a 204 response for nil content instead
of having the encoder handle nil specially. nvelope.Nil204
does this.
Grab the request body
The request body is more convieniently handled as a []byte . This is also
one place where API enforcement can be done. The type nvelope.Body
is provided by
nvelope.ReadBody
via injection to any provider that wants it.
Validate response
This is a user-provided optional step that can be used to double-check that what is being sent matches the API defintion.
The nvalid package provides a function to generate a response validator from Swagger.
Decode the request body
The request body needs to be unpacked with an unmarshaller of some kind.
nvelope.GenerateDecoder
creates decoders that examine the injection chain
looking for models that are consumed but not provided. If it finds any,
it examines those models for struct tags that indicate that nvelope should
create and fill the model.
If so, it generates a provider that fills the model from the request. This includes filling fields for the main decoded request body and also includes filling fields from URL path elements, URL query parameters, and HTTP headers.
nvelope.DecodeJSON
and nvelope.DecodeXML
are pre-defined for
convience.
Validate the request
This is an optional step, provided by the user of nvelope
, that
should return nject.TerminalError
if the request is not valid. Other
validation can happen later, but this is good place to enforce API compliance.
The nvalid package provides a function
to generate an input validator from Swagger.
Actually handle the request
At this point the request model has been decoded. The other input parameters (from headers, path, and query parameters) have been decoded. The input model may have been validated.
The response will automatically be encoded. The endpoint handler returns the
response and and error. If there is an error, it will trigger an appropriate
return. Use nvelope.ReturnCode
to set the return code if returning an error.