gum

Documentation

Index

• func AssertFromRequest[T FromRequest[T]]() T
• func Extract[T any](r *http.Request) (T, error)
• func Handler(f any) http.Handler
• func Register[T any](fn Extractor[T])
• type ContentLength
• type ContentType
• type ContextValue
  • func (ContextValue[T]) FromRequest(r *http.Request) (ContextValue[T], error)
• type Extractor
  • func ContextValueExtractor[T any]() Extractor[T]
• type Form
• type FormValues
  • func (FormValues[T]) FromRequest(r *http.Request) (FormValues[T], error)
• type FromRequest
• type Host
• type JSON
  • func (JSON[T]) FromRequest(r *http.Request) (JSON[T], error)
• type Logger
  • func (l Logger) Close() error
  • func (l Logger) FromRequest(r *http.Request) (Logger, error)
• type Method
• type Middleware
  • func ProvideContextValue[T any](value T) Middleware
• type MultipartFormMaxMemory
• type Option
  • func (Option[T]) FromRequest(r *http.Request) (Option[T], error)
  • func (o Option[T]) Get() (T, bool)
  • func (o Option[T]) GetOr(fallbackValue T) T
  • func (o Option[T]) GetOrZero() T
• type PathValues
  • func (PathValues[T]) FromRequest(r *http.Request) (PathValues[T], error)
• type PostForm
• type PostFormValues
  • func (PostFormValues[T]) FromRequest(r *http.Request) (PostFormValues[T], error)
• type Query
• type QueryValues
  • func (QueryValues[T]) FromRequest(r *http.Request) (QueryValues[T], error)
• type RawBody
• type Try
  • func (Try[T]) FromRequest(r *http.Request) (Try[T], error)
  • func (o Try[T]) Get() (T, error)

Functions

func AssertFromRequest

func AssertFromRequest[T FromRequest[T]]() T

AssertFromRequest asserts that the FromRequest interface is correctly implemented for the given type T.

You can use it as a compile time check with a static variable or in an init function:

// static variable
var _ = AssertFromRequest[JSON[any]]()

func init() {
  AssertFromRequest[JSON[any]]()
}

func Extract

func Extract[T any](r *http.Request) (T, error)

Extract extracts a value of type T from the http.Request. T must either implement the FromRequest interface, or have an Extractor registered using the Register function.

TODO document error, maybe panic

func Handler

func Handler(f any) http.Handler

Handler adapts a gum handler into an http.Handler. If for any of the handlers parameters cannot be provided by any registered Extractor, nor it implements FromRequest, a panic is raised immediately.

The provided handler function must have either

• no return type
• a single error value
• a single value that implements http.Handler
• a value that implements http.Handler and an error value

func Register

func Register[T any](fn Extractor[T])

Register registers an Extractor function for the given T. An already existing registration for T will be replaced. This method is threadsafe.

Types

type ContentLength

type ContentLength int64

ContentLength is the value of the http.Request.ContentLength field. Only available if the value requests value is not negative.

type ContentType

type ContentType string

ContentType holds the value of the requests Content-Type header.

type ContextValue

type ContextValue[T any] struct {
	Value T
}

ContextValue uses the type T as the key to lookup a value of type T in the requests context.Context. Use WithContextValue to get a http.Handler middleware that injects a value into the context.Context

func (ContextValue[T]) FromRequest

func (ContextValue[T]) FromRequest(r *http.Request) (ContextValue[T], error)

type Extractor

type Extractor[T any] func(r *http.Request) (T, error)

Extractor extracts a T from a request. This should be used for non generic types. Implement FromRequest for type T if T itself is generic.

func ContextValueExtractor

func ContextValueExtractor[T any]() Extractor[T]

ContextValueExtractor returns a gum.Extractor that extracts a value of type T from the context.Context that was previous provided using ProvideContextValue.

type Form

type Form struct {
	url.Values
}

Form contains the requests http.Request.Form as url.Values

type FormValues

type FormValues[T any] struct {
	Value T
}

FormValues parses the form parameters to a struct T. Works the same as QueryValues just for the requests Form

func (FormValues[T]) FromRequest

func (FormValues[T]) FromRequest(r *http.Request) (FormValues[T], error)

type FromRequest

type FromRequest[T any] interface {
	// FromRequest creates a new instance of T.
	//
	// It should be seen as a static method and only be implemented
	// on the type T itself, e.g. for a type Foo:
	//
	//   func (Foo) FromRequest(*http.Request) (Foo, error) {
	//     return "foo", nil
	//   }
	FromRequest(r *http.Request) (T, error)
}

FromRequest defines a method that extracts a T from a http.Request. See FromRequest.FromRequest for more details. I would like to Type it as FromRequest[T FromRequest[T]], but that is not possible as of the time of writing.

type Host

type Host string

Host is the value of the http.Request.Host field

type JSON

type JSON[T any] struct {
	Value T
}

JSON parses the requests body as json

func (JSON[T]) FromRequest

func (JSON[T]) FromRequest(r *http.Request) (JSON[T], error)

type Logger

type Logger struct {
	*slog.Logger
	// contains filtered or unexported fields
}

func (Logger) Close

func (l Logger) Close() error

func (Logger) FromRequest

func (l Logger) FromRequest(r *http.Request) (Logger, error)

type Method

type Method string

Method is the value of the http.Request.Method field, e.g. GET, POST, etc

type Middleware

type Middleware = func(delegate http.Handler) http.Handler

func ProvideContextValue

func ProvideContextValue[T any](value T) Middleware

ProvideContextValue provides a Middleware that injects a value of type T into the requests context. The value can later be extracted by using ContextValue.

type MultipartFormMaxMemory

type MultipartFormMaxMemory int64

type Option

type Option[T any] struct {
	Value T
	IsSet bool
}

Option is similar to Try, it just swallows any error.

func (Option[T]) FromRequest

func (Option[T]) FromRequest(r *http.Request) (Option[T], error)

func (Option[T]) Get

func (o Option[T]) Get() (T, bool)

Get gets the Option value and a boolean flag to test if the value is set.

func (Option[T]) GetOr

func (o Option[T]) GetOr(fallbackValue T) T

GetOr returns the value in this Option if it exists and falls back to the provided fallback value otherwise

func (Option[T]) GetOrZero

func (o Option[T]) GetOrZero() T

GetOrZero calls GetOr with a zero T value

type PathValues

type PathValues[T any] struct {
	Value T
}

PathValues parses the path parameters to a struct T

func (PathValues[T]) FromRequest

func (PathValues[T]) FromRequest(r *http.Request) (PathValues[T], error)

type PostForm

type PostForm struct {
	url.Values
}

PostForm contains the requests parsed http.Request.PostForm as url.Values

type PostFormValues

type PostFormValues[T any] struct {
	Value T
}

PostFormValues parses the form parameters to a struct T. Works the same as QueryValues just for the requests PostForm

func (PostFormValues[T]) FromRequest

func (PostFormValues[T]) FromRequest(r *http.Request) (PostFormValues[T], error)

type Query

type Query struct {
	url.Values
}

Query contains the requests query values as url.Values

type QueryValues

type QueryValues[T any] struct {
	Value T
}

QueryValues parses the query parameters to a struct T. It supports multiple definitions of the same parameter for slices.

func (QueryValues[T]) FromRequest

func (QueryValues[T]) FromRequest(r *http.Request) (QueryValues[T], error)

type RawBody

type RawBody []byte

RawBody is a byte slice holding the content of the requests http.Request.Body field.

type Try

type Try[T any] struct {
	Value T
	Error error
}

Try tries to extract a T from the request but will not fail the request processing if extraction fails. A Try has either the Value or the Error field set.

func (Try[T]) FromRequest

func (Try[T]) FromRequest(r *http.Request) (Try[T], error)

func (Try[T]) Get

func (o Try[T]) Get() (T, error)

Get gets the Try value and its error