ring

README

ring

A Go library that provides interfaces and adapters that help compose HTTP handler implementations.

Documentation

Overview

Package ring provides interfaces and adapters that help compose http.Handler implementations.

Index

• type Binder
• type Controller
• type ErrorHandler
• type HTMLRenderer
  • func (renderer HTMLRenderer[T]) Render(w http.ResponseWriter, value T) error
• type Handler
  • func NewHandler[Req, Res any](opts *HandlerOptions[Req, Res]) *Handler[Req, Res]
  • func (handler *Handler[Req, Res]) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandlerOptions
• type HeaderBinder
  • func (HeaderBinder[T]) Bind(r *http.Request, value T) error
• type HeaderRenderer
  • func (HeaderRenderer[T]) Render(w http.ResponseWriter, value T) error
• type JSONBinder
  • func (binder *JSONBinder[T]) Bind(r *http.Request, value T) error
• type JSONRenderer
  • func (renderer *JSONRenderer[T]) Render(w http.ResponseWriter, value T) error
• type MultipartFormBinder
  • func (binder *MultipartFormBinder[T]) Bind(r *http.Request, model T) error
• type QueryStringBinder
  • func (binder *QueryStringBinder[T]) Bind(r *http.Request, model T) error
• type Renderer
• type SSERenderer
  • func (renderer *SSERenderer[T]) Render(w http.ResponseWriter, ch <-chan T) error
• type TextRenderer
  • func (renderer TextRenderer[T]) Render(w http.ResponseWriter, value T) error
• type URLEncodedFormBinder
  • func (binder *URLEncodedFormBinder[T]) Bind(r *http.Request, model T) error

Types

type Binder

type Binder[T any] interface {
	Bind(r *http.Request, model T) error
}

A Binder binds the http.Request to the given model

type Controller

type Controller[Req, Res any] interface {
	Execute(context.Context, Req) (Res, error)
}

A Controller handles the incoming request model, and returns a response model or error.

type ErrorHandler

type ErrorHandler interface {
	Handle(w http.ResponseWriter, err error)
}

ErrorHandler provides a global error filter for all handlers

type HTMLRenderer

type HTMLRenderer[T any] struct {
	// The template collection
	*template.Template

	// The name of the target template
	Name string
	// Set to true to re-parse the target template before rendering. This is
	// useful when nesting template layouts.
	Reparse bool
	// Source must be included when reparsing targets, otherwith the renderer
	// will panic
	Source fs.FS
}

HTMLRenderer renders the provided model to the response body as HTML using the named template.

See [template.Template] for more rendering details

func (HTMLRenderer[T]) Render

func (renderer HTMLRenderer[T]) Render(w http.ResponseWriter, value T) error

Render implements Renderer.

type Handler

type Handler[Req, Res any] struct {
	// contains filtered or unexported fields
}

Handler composes a Binder, Controller, and Renderer to implement a http.Handler

func NewHandler

func NewHandler[Req, Res any](opts *HandlerOptions[Req, Res]) *Handler[Req, Res]

NewHandler creates a Handler with the provided opts

func (*Handler[Req, Res]) ServeHTTP

func (handler *Handler[Req, Res]) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler

type HandlerOptions

type HandlerOptions[Req, Res any] struct {
	Controller   Controller[Req, Res]
	Binder       Binder[Req]
	Renderer     Renderer[Res]
	ErrorHandler ErrorHandler
}

HandlerOptions provide the required dependencies for a Handler

type HeaderBinder

type HeaderBinder[T any] struct{}

HeaderBinder binds the request headers to the provided model using the \`header:""\` struct tag.

See httpheader.Decode for more decoding details.

func (HeaderBinder[T]) Bind

func (HeaderBinder[T]) Bind(r *http.Request, value T) error

Bind implements Binder.

type HeaderRenderer

type HeaderRenderer[T any] struct{}

HeaderRenderer renders the provided model to the response headers using the \`header:""\` struct tag. Headers are merged into the pre-existing header map present in the http.ResponseWriter.

See httpheader.Encode for more encoding details.

func (HeaderRenderer[T]) Render

func (HeaderRenderer[T]) Render(w http.ResponseWriter, value T) error

Render implements Renderer.

type JSONBinder

type JSONBinder[T any] struct {
	// Whether to error on unknown fields
	DisallowUnknownFields bool
}

JSONBinder binds a JSON request body to the provided model type.

See json.Encoder for more decoding details.

func (*JSONBinder[T]) Bind

func (binder *JSONBinder[T]) Bind(r *http.Request, value T) error

Bind implements Binder.

type JSONRenderer

type JSONRenderer[T any] struct {
	// See [json.Indent]
	Prefix string
	// See [json.Indent]
	Indent string
	// By default, [json.Encoder] escapes certain HTML characters. Set this
	// to true to disable this behavior.
	UnescapeHTML bool
}

JSONRenderer renders the provided model type to response body as a JSON string.

See json.Decoder for more decoding details.

func (*JSONRenderer[T]) Render

func (renderer *JSONRenderer[T]) Render(w http.ResponseWriter, value T) error

Render implements Renderer

type MultipartFormBinder

type MultipartFormBinder[T any] struct {
	MaxMemory int64
}

MultipartFormBinder parses the request body as "multipart/form-data", and binds it to the provided model using the \`multipart:""\` struct tag.

See mapstructure.Decoder for more decoding details.

func (*MultipartFormBinder[T]) Bind

func (binder *MultipartFormBinder[T]) Bind(r *http.Request, model T) error

Bind implements Binder.

type QueryStringBinder

type QueryStringBinder[T any] struct {
	Options *qs.UnmarshalOptions
}

QueryStringBinder binds the request URL query string to the provided model using the \`qs:""\` struct tag.

See qs.QSUnmarshaler for more decoding details.

func (*QueryStringBinder[T]) Bind

func (binder *QueryStringBinder[T]) Bind(r *http.Request, model T) error

Bind implements Binder.

type Renderer

type Renderer[T any] interface {
	Render(w http.ResponseWriter, model T) error
}

A Renderer renders the given model to the response body

type SSERenderer

type SSERenderer[T any] struct {
	// Serializes the model to a string
	TextMarshaler func(T) ([]byte, error)
}

SSERenderer renders a channel of model data to the response body as a server-sent event stream.

func (*SSERenderer[T]) Render

func (renderer *SSERenderer[T]) Render(w http.ResponseWriter, ch <-chan T) error

Render implements Renderer.

type TextRenderer

type TextRenderer[T any] struct {
	// The template collection
	*template.Template

	// The name of the target template
	Name string
	// Set to true to re-parse the target template before rendering. This is
	// useful when nesting template layouts.
	Reparse bool
	// Source must be included when reparsing targets, otherwith the renderer
	// will panic
	Source fs.FS
}

TextRenderer renders the provided model to the response body as text using the named template.

See [template.Template] for more rendering details.

func (TextRenderer[T]) Render

func (renderer TextRenderer[T]) Render(w http.ResponseWriter, value T) error

Render implements Renderer.

type URLEncodedFormBinder

type URLEncodedFormBinder[T any] struct {
	Options *qs.UnmarshalOptions
}

URLEncodedFormBinder parses the request body as "application/x-www-formurlencoded", and binds it to the provided model using the \`qs:""\` struct tag.

See qs.QSUnmarshaler for more decoding details

func (*URLEncodedFormBinder[T]) Bind

func (binder *URLEncodedFormBinder[T]) Bind(r *http.Request, model T) error

Bind implements Binder.