bee

Documentation

Overview

Package bee provides a simple HTTP handler with functionality that is inconvenient to implement in middleware.

It provides two primary features. First, is easier error handling. Handlers can return errors which will be handled by a list of error handlers that will be called when an error occurs. Second, it automatically sets the ETag header based on the digest of the response body.

These features may seem entirely unrelated but they are both related because the response body must be buffered in its entirety. For error handling an error may occur after some of the response has been written and the response needs to be replaced. For ETag the response body must be buffered so that the digest can be calculated and set in the headers.

Index

• func ParseParams(r *http.Request) (map[string]any, error)
• type ErrorHandler
• type HandlerBuilder
  • func (hb *HandlerBuilder[T]) New(...) http.Handler

Functions

func ParseParams

func ParseParams(r *http.Request) (map[string]any, error)

ParseParams parses the request parameters from the Chi route parameters, the URL query string, and the request body. The request body can be parsed for application/json, application/x-www-form-urlencoded, and multipart/form-data.

When the request is URL encoded, the parameters are parsed as follows:

• foo=bar -> map[string]any{"foo": "bar"}
• foo[]=bar -> map[string]any{"foo": []string{"bar"}}
• foo[]=bar&foo[]baz -> map[string]any{"foo": []string{"bar", "baz"}}
• foo[bar]=baz -> {"foo": {"bar": "baz"}}
• foo[bar][]=baz&foo[bar][]=qux -> {"foo": {"bar": []string{"baz", "qux"}}}

Types

type ErrorHandler

type ErrorHandler func(w http.ResponseWriter, r *http.Request, err error) (bool, error)

type HandlerBuilder

type HandlerBuilder[T any] struct {
	// Key used to get the env from the request context. If nil then a zero value T is passed as the env to the handler.
	CtxKeyEnv any

	// ParseParams builds the parameters to pass to the handler function. If nil then the package ParseParams function is
	// used.
	ParseParams func(*http.Request) (map[string]any, error)

	// ErrorHandlers are called one at a time until one returns true. If none return true or one returns an error then a
	// generic HTTP 500 error is returned.
	ErrorHandlers []ErrorHandler

	// ETagDigestFilter is used to filter out parts of the response body that should not be included in the automatic ETag
	// digest. This is useful for filtering out dynamic content such as CSRF tokens. If nil then the entire response body
	// is used.
	ETagDigestFilter *regexp.Regexp
}

HandlerBuilder is used to build Handlers with shared functionality. HandlerBuilder must not be mutated after any methods have been called.

func (*HandlerBuilder[T]) New

func (hb *HandlerBuilder[T]) New(fn func(ctx context.Context, w http.ResponseWriter, r *http.Request, env T, params map[string]any) error) http.Handler

New returns a new http.Handler that calls fn. If fn returns an error then the error is passed to the ErrorHandlers.