nvelope

func BadRequest ¶

func BadRequest(err error) error

BadRequest annotates an error has giving 400 HTTP return code

func Forbidden ¶

func Forbidden(err error) error

Forbidden annotates an error has giving 403 HTTP return code

func GenerateDecoder ¶

func GenerateDecoder(
	genOpts ...DecodeInputsGeneratorOpt,
) interface{}

GenerateDecoder injects a special provider that uses nject.GenerateFromInjectionChain to examine the injection chain to see if there are any models that are used but never provided. If so, it looks at the struct tags in the models to see if they are tagged for filling with the decoder. If so, a provider is created that injects the missing model into the dependency chain. The intended use for this is to have an endpoint handler receive the deocded request body.

Major warning: the endpoint handler must receive the request model as a field inside a model, not as a standalone model.

The following tags are recognized:

`nvelope:"model"` causes the POST or PUT body to be decoded using a decoder like json.Unmarshal.

`nvelope:"path,name=xxx"` causes part of the URL path to be extracted and written to the tagged field.

`nvelope:"query,name=xxx"` causes the named URL query parameters to be extracted and written to the tagged field.

`nvelope:"header,name=xxx"` causes the named HTTP header to be extracted and written to the tagged field.

`nvelope:"cookie,name=xxx"` cause the named HTTP cookie to be extracted and writted to the tagged field.

Path, query, header, and cookie support options described in https://swagger.io/docs/specification/serialization/ for controlling how to serialize. The following are supported as appropriate.

explode=true			# default for query, header
explode=false			# default for path
delimiter=comma			# default
delimiter=space			# query parameters only
delimiter=pipe			# query parameters only
allowReserved=false		# default
allowReserved=true		# query parameters only
form=false			# default
form=true			# cookies only
content=application/json	# specifies that the value should be decoded with JSON
content=application/xml		# specifies that the value should be decoded with XML
content=application/yaml	# specifies that the value should be decoded with YAML
content=text/yaml		# specifies that the value should be decoded with YAML
deepObject=false		# default
deepObject=true			# required for query object

"style=label" and "style=matrix" are NOT yet supported for path parameters.

For query parameters filling maps and structs, the only the following combinations are supported:

deepObject=true
deepObject=false,explode=false

When filling embedded structs from query, or header, parameters, using explode=false or deepObject=true, tagging struct members is optional. Tag them with their name or with "-" if you do not want them filled.

type Fillme struct {
	Embedded struct {
		IntValue    int                     // will get filled by key "IntValue"
		FloatValue  float64 `nvelope:"-"`   // will not get filled
		StringValue string  `nvelope:"bob"` // will get filled by key "bob"
	} `nvelope:"query,name=embedded,explode=false"`
}

"deepObject=true" is only supported for maps and structs and only for query parameters.

Use "explode=true" combined with setting a "content" when you have a map to a struct or a slice of structs and each value will be encoded in JSON/XML independently. If the entire map is encoded, then use "explode=false".

GenerateDecoder uses https://pkg.go.dev/github.com/muir/reflectutils#MakeStringSetter to unpack strings into struct fields. That provides support for time.Duration and anything that implements encoding.TextUnmarshaler or flag.Value. Additional custom decoders can be registered with https://pkg.go.dev/github.com/muir/reflectutils#RegisterStringSetter .

There are a couple of example decoders defined in https://github.com/muir/nape and also https://github.com/muir/nchi .

func GetReturnCode ¶

func GetReturnCode(err error) int

GetReturnCode turns an error into an HTTP response code.

func LoggerFromStd ¶

func LoggerFromStd(log StdLogger) func() BasicLogger

LoggerFromStd creates a

func MakeResponseEncoder ¶

func MakeResponseEncoder(
	name string,
	encoderFuncArgs ...ResponseEncoderFuncArg,
) nject.Provider

MakeResponseEncoder generates an nject Provider to encode API responses.

The generated provider is a wrapper that invokes the rest of the handler injection chain and expect to receive as return values an Response and and error. If the error is not nil, then the response becomes the error.

If more than one encoder is configurured, then MakeResponseEncoder will default to the first one specified in its functional arguments.

func MiddlewareBaseWriter ¶

func MiddlewareBaseWriter(m ...func(http.HandlerFunc) http.HandlerFunc) nject.Provider

MiddlewareBaseWriter acts as a translator. In the Go world, there are a bunch of packages that expect to use the wrapping

func(http.HandlerFunc) http.HandlerFunc

pattern. The func(http.HandlerFunc) http.HandlerFunc pattern is harder to use and not as expressive as the patterns supported by npoint and nvelope, but there may be code written with the func(http.HandlerFunc) http.HandlerFunc pattern that you want to use with npoint and nvelope.

MiddlewareBaseWriter converts existing func(http.HandlerFunc) http.HandlerFunc functions so that they're compatible with nject. Because Middleware may wrap http.ResponseWriter, it should be used earlier in the injection chain than InjectWriter so that InjectWriter gets the already-wrapped http.ResponseWriter. Use MiddlewareBaseWriter if you suspect that the middleware you're wrapping replaces the writer.

func MiddlewareDeferredWriter ¶

func MiddlewareDeferredWriter(m ...func(http.HandlerFunc) http.HandlerFunc) nject.Provider

MiddlewareDeferredWriter acts as a translator. In the Go world, there are a bunch of packages that expect to use the wrapping

func(http.HandlerFunc) http.HandlerFunc

pattern. The func(http.HandlerFunc) http.HandlerFunc pattern is harder to use and not as expressive as the patterns supported by npoint and nvelope, but there may be code written with the func(http.HandlerFunc) http.HandlerFunc pattern that you want to use with npoint and nvelope.

MiddlewareDeferredWriter converts existing func(http.HandlerFunc) http.HandlerFunc functions so that they're compatible with nject. MiddlewareDeferredWriter injects a DeferredWriter into the the func(http.HandlerFunc) http.HandlerFunc handler chain. If the chain replaces the writer, there will be two writers in play at once and results may be inconsistent. MiddlewareDeferredWriter must be used after InjectWriter. Use MiddlewareDeferredWriter if you know that the middleware you're wrapping does not replace the writer.

func MiddlewareHandlerBaseWriter ¶

func MiddlewareHandlerBaseWriter(m ...func(http.Handler) http.Handler) nject.Provider

MiddlewareHandlerBaseWriter acts as a translator. In the Go world, there are a bunch of packages that expect to use the wrapping

func(http.Handler) http.Handler

pattern. The func(http.HandlerFunc) http.HandlerFunc pattern is harder to use and not as expressive as the patterns supported by npoint and nvelope, but there may be code written with the func(http.HandlerFunc) http.HandlerFunc pattern that you want to use with npoint and nvelope.

MiddlewareHandlerBaseWriter converts existing func(http.Handler) http.Handler functions so that they're compatible with nject. Because Middleware may wrap http.ResponseWriter, it should be used earlier in the injection chain than InjectWriter so that InjectWriter gets the already-wrapped http.ResponseWriter. Use MiddlewareBaseWriter if you suspect that the middleware you're wrapping replaces the writer.

func MiddlewareHandlerDeferredWriter ¶

func MiddlewareHandlerDeferredWriter(m ...func(http.Handler) http.Handler) nject.Provider

MiddlewareHandlerDeferredWriter acts as a translator. In the Go world, there are a bunch of packages that expect to use the wrapping

func(http.Handler) http.Handler

pattern. The func(http.Handler) http.Handler pattern is harder to use and not as expressive as the patterns supported by npoint and nvelope, but there may be code written with the func(http.Handler) http.Handler pattern that you want to use with npoint and nvelope.

MiddlewareHandlerDeferredWriter converts existing func(http.Handler) http.Handler functions so that they're compatible with nject. MiddlewareHandlerDeferredWriter injects a DeferredWriter into the the func(http.Handler) http.Handler handler chain. If the chain replaces the writer, there will be two writers in play at once and results may be inconsistent. MiddlewareHandlerDeferredWriter must be used after InjectWriter. Use MiddlewareHandlerDeferredWriter if you know that the middleware you're wrapping does not replace the writer.

func NotFound ¶

func NotFound(err error) error

NotFound annotates an error has giving 404 HTTP return code

func RecoverInterface ¶

func RecoverInterface(err error) interface{}

RecoverInterface returns the interface{} that recover() originally provided. Or it returns nil if the error isn't a from a panic recovery. This works only in conjunction with SetErrorOnPanic() and CatchPanic.

func RecoverStack ¶

func RecoverStack(err error) string

RecoverStack returns the stack from when recover() originally caught the panic. Or it returns "" if the error isn't a from a panic recovery. This works only in conjunction with SetErrorOnPanic() and CatchPanic.

package main

import (
	"fmt"

	"github.com/muir/nvelope"
)

func main() {
	f := func(i int) (err error) {
		defer nvelope.SetErrorOnPanic(&err, nvelope.NoLogger())
		return func() error {
			switch i {
			case 0:
				panic("zero")
			case 1:
				return fmt.Errorf("a one")
			default:
				return nil
			}
		}()
	}
	err := f(0)
	fmt.Println(err)
	stack := nvelope.RecoverStack(err)
	fmt.Println(len(stack) > 1000)
}

Output:

panic: zero
true

func ReturnCode ¶

func ReturnCode(err error, code int) error

ReturnCode associates an HTTP return code with a error. if err is nil, then nil is returned.

func SetErrorOnPanic ¶

func SetErrorOnPanic(ep *error, log BasicLogger)

SetErrorOnPanic should be called as a defer. It sets an error value if there is a panic.

func Unauthorized ¶

func Unauthorized(err error) error

Unauthorized annotates an error has giving 401 HTTP return code