web

README

Helpers for implementing http.Handlers

Response Handlers

Using respond.WithRequest() we compute our options and PreferredContentType() tells one how to encode the data.

Content Negotiation

QualityList

The QualityList parser allows choosing the best option during Content Negotiation, e.g. accepted Content-Types.

BestQuality

qlist offers two helpers to choose the best option from a QualityList and a list of supported options, BestQuality() and BestQualityWithIdentity(). Identity is an special option we consider unless it's explicitly forbidden.

BestEncoding

qlist.BestEncoding() is a special case of BestQualityWithIdentity() using the Accept header, and falling back to "identity" as magic type.

See also

• Accept
• Content Negotiation
• Quality Values

Documentation

Overview

Package web contains helpers for web handlers

Index

• func ErrorText(code int) string
• func HandleError(rw http.ResponseWriter, req *http.Request, err error)
• func WithErrorHandler(ctx context.Context, h ErrorHandlerFunc) context.Context
• type Error
• type ErrorHandlerFunc
  • func ErrorHandler(ctx context.Context) (ErrorHandlerFunc, bool)
• type HTTPError
  • func NewHTTPError(code int, err error, note string) *HTTPError
  • func NewHTTPErrorf(code int, err error, format string, args ...any) *HTTPError
  • func (err *HTTPError) AddHeader(key, value string)
  • func (err *HTTPError) DeleteHeader(key string)
  • func (err *HTTPError) Error() string
  • func (err *HTTPError) Header() http.Header
  • func (err *HTTPError) ServeHTTP(rw http.ResponseWriter, req *http.Request)
  • func (err *HTTPError) SetHeader(key, value string)
  • func (err *HTTPError) Status() int
  • func (err *HTTPError) Unwrap() error
• type Handler
• type HandlerFunc
  • func (fn HandlerFunc) ServeHTTP(rw http.ResponseWriter, req *http.Request)
  • func (fn HandlerFunc) TryServeHTTP(rw http.ResponseWriter, req *http.Request) error

Functions

func ErrorText

func ErrorText(code int) string

ErrorText returns the title corresponding to a given HTTP Status code

func HandleError

func HandleError(rw http.ResponseWriter, req *http.Request, err error)

HandleError attempts to call the ErrorHandler set for the content, otherwise it serves the error directly using its own ServeHTTP if defined or HTTPError if not.

func WithErrorHandler

func WithErrorHandler(ctx context.Context, h ErrorHandlerFunc) context.Context

WithErrorHandler attaches an ErrorHandler function to a context for later retrieval

Types

type Error

type Error interface {
	Error() string
	Status() int
}

Error is an error that knows its HTTP Status Code

type ErrorHandlerFunc

type ErrorHandlerFunc func(http.ResponseWriter, *http.Request, error)

ErrorHandlerFunc is the signature of a function used as ErrorHandler

func ErrorHandler

func ErrorHandler(ctx context.Context) (ErrorHandlerFunc, bool)

ErrorHandler attempts to pull an ErrorHandler from the context.Context

type HTTPError

type HTTPError struct {
	Err  error
	Code int
	Hdr  http.Header
}

HTTPError extends core.WrappedError with HTTP Status Code

func NewHTTPError

func NewHTTPError(code int, err error, note string) *HTTPError

NewHTTPError creates a new HTTPError with a given StatusCode and optional cause and annotation

func NewHTTPErrorf

func NewHTTPErrorf(code int, err error, format string, args ...any) *HTTPError

NewHTTPErrorf creates a new HTTPError with a given StatusCode and optional cause and formatted annotation

func (*HTTPError) AddHeader

func (err *HTTPError) AddHeader(key, value string)

AddHeader appends a value to an HTTP header entry of the HTTPError

func (*HTTPError) DeleteHeader

func (err *HTTPError) DeleteHeader(key string)

DeleteHeader removes a header key from the HTTPError if present

func (*HTTPError) Error

func (err *HTTPError) Error() string

func (*HTTPError) Header

func (err *HTTPError) Header() http.Header

Header returns a http.Header attached to this error for custom fields

func (*HTTPError) ServeHTTP

func (err *HTTPError) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP is a very primitive handler that will try to pass the error to a [middleware.ErrorHandlerFunc] provided via the request's context.Context

func (*HTTPError) SetHeader

func (err *HTTPError) SetHeader(key, value string)

SetHeader sets the value of a header key of the HTTPError

func (*HTTPError) Status

func (err *HTTPError) Status() int

Status returns the StatusCode associated with the Error

func (*HTTPError) Unwrap

func (err *HTTPError) Unwrap() error

type Handler

type Handler interface {
	TryServeHTTP(http.ResponseWriter, *http.Request) error
}

A Handler is like http.Handler but doesn't render or handle errors by itself.

type HandlerFunc

type HandlerFunc func(http.ResponseWriter, *http.Request) error

HandlerFunc is a function that implements http.Handler and our Handler. HandleError will be called when using the http.Handler interface and the function returns an error.

func (HandlerFunc) ServeHTTP

func (fn HandlerFunc) ServeHTTP(rw http.ResponseWriter, req *http.Request)

func (HandlerFunc) TryServeHTTP

func (fn HandlerFunc) TryServeHTTP(rw http.ResponseWriter, req *http.Request) error

TryServeHTTP implements the Handler interface.