clserve

Documentation

Overview

Package clserve provides buffered HTTP response serving to support error handling

Index

• Variables
• func Handle[C context.Context](hdlf func(C, http.ResponseWriter, *http.Request) error, os ...Option[C]) http.HandlerFunc
• type ContextBuilderFunc
• type ErrorHandlerFunc
• type NoContextErrorHandlerFunc
• type Option
  • func WithBufferLimit[C context.Context](v int) Option[C]
  • func WithContextBuilder[C context.Context](f ContextBuilderFunc[C]) Option[C]
  • func WithContextErrorHandling[C context.Context](f ErrorHandlerFunc[C]) Option[C]
  • func WithErrorHandling[C context.Context](f NoContextErrorHandlerFunc) Option[C]
  • func WithPanicHandler[C context.Context](f PanicHandlerFunc[C]) Option[C]
• type PanicHandlerFunc
• type ResponseBuffer
  • func NewBufferResponse(resp http.ResponseWriter, limit int) *ResponseBuffer
  • func (w *ResponseBuffer) FlushError() error
  • func (w *ResponseBuffer) Free()
  • func (w *ResponseBuffer) Header() http.Header
  • func (w *ResponseBuffer) ImplicitFlush() error
  • func (w *ResponseBuffer) Reset() error
  • func (w *ResponseBuffer) Unwrap() http.ResponseWriter
  • func (w *ResponseBuffer) Write(buf []byte) (int, error)
  • func (w *ResponseBuffer) WriteHeader(statusCode int)

Variables

var (
	// ErrBufferFull is returned when the write call will cause the buffer to be filled beyond its limit.
	ErrBufferFull = errors.New("buffer is full")

	// ErrAlreadyFlushed is returned when the buffer is reset even though a handler already flushed the data
	// to the underlying writer.
	ErrAlreadyFlushed = errors.New("already flushed")
)

var ErrContextBuilderRequired = errors.New("context builder required")

ErrContextBuilderRequired is thrown when the context cannot be cased from context.Context.

Functions

func Handle

func Handle[C context.Context](
	hdlf func(C, http.ResponseWriter, *http.Request) error, os ...Option[C],
) http.HandlerFunc

Handle takes a handler function with a customizable context that is able to return an error. To support this the response is buffered until the handler is done. If an error occurs the buffer is discarded and a full replacement response can be formulated. The underlying buffer is re-used between requests for improved performance.

Types

type ContextBuilderFunc

type ContextBuilderFunc[C context.Context] func(r *http.Request) (C, error)

ContextBuilderFunc describes the signature of a context builder.

type ErrorHandlerFunc

type ErrorHandlerFunc[C context.Context] func(c C, w http.ResponseWriter, r *http.Request, err error)

ErrorHandlerFunc can be configured across handlers to standardize how handling errors are handled.

type NoContextErrorHandlerFunc

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

NoContextErrorHandlerFunc can be configured across handlers to standardize how handling errors in case context building has failed.

type Option

type Option[C context.Context] func(*opts[C])

Option allows for customization of the (buffered) handling logic.

func WithBufferLimit

func WithBufferLimit[C context.Context](v int) Option[C]

WithBufferLimit allows limiting the buffered writer (if it buffered). This can protect against buffered response writers taking up too much memory per response.

func WithContextBuilder

func WithContextBuilder[C context.Context](f ContextBuilderFunc[C]) Option[C]

WithContextBuilder customizes how a request is turned into a context for the handlers. The builder func is not provided a ResponseWriter to force the user to not write anything as the buffer will not be reset when an error is returned.

func WithContextErrorHandling

func WithContextErrorHandling[C context.Context](f ErrorHandlerFunc[C]) Option[C]

WithContextErrorHandling allows for custom logic to handle the error returned from the Handler in case there is a context available. By default the handle just calls the non-context ErrorHandler. It allows full customization of the error response (including headers and status code) but the error might be due to a failture to reset the buffer or because writing to the underlying ResponseWriter has failed. In those cases it might not be possible to guarantee a complete error response can be returned.

func WithErrorHandling

func WithErrorHandling[C context.Context](f NoContextErrorHandlerFunc) Option[C]

WithErrorHandling allows for custom error handling in case there is no context available. This happens when the context builder has failed for some reason.

func WithPanicHandler

func WithPanicHandler[C context.Context](f PanicHandlerFunc[C]) Option[C]

WithPanicHandler configures how exeptions in the handling function are caught. By default, the recovered panic is send to the error handler but it can be customized for example to provide custom logging. Additionally the panic handler can be set to nil to disable recovering of panics altogether. This can be done because it is also common to have middleware recover any panics, which has the advantage being able to catch panics in the middleware chain as well.

Panics in the context builder are not caught by this logic and should be taken care of in the context builder itself. But panics in error handling with a context are caught by this handler.

type PanicHandlerFunc

type PanicHandlerFunc[C context.Context] func(c C, w http.ResponseWriter, r *http.Request, v any, e ErrorHandlerFunc[C])

PanicHandlerFunc can be configured across handlers to standardize how panics are handled.

type ResponseBuffer

type ResponseBuffer struct {
	// contains filtered or unexported fields
}

ResponseBuffer is a http.ResponseWriter implementation that buffers writes up to configurable amount of bytes. This allows the implementation of handlers that can error halfway and return a completely different response instead of what was written before the error occurred.

func NewBufferResponse

func NewBufferResponse(resp http.ResponseWriter, limit int) *ResponseBuffer

NewBufferResponse inits a buffered response writer. It has a configurable limit after which the writing will return an error. This is to protect unchecked handlers from claiming too much memory. Limit can be set to -1 to disable this check.

func (*ResponseBuffer) FlushError

func (w *ResponseBuffer) FlushError() error

FlushError any buffered bytes to the underlying response writer and resets the buffer. After flush has been called the response data should be considered sent and in-transport to the client.

func (*ResponseBuffer) Free

func (w *ResponseBuffer) Free()

Free resets all members of the ResponseBuffer and puts it back in the sync pool to allow it to be re-used for a possible next initilization. It should be called after the handling has completed and the buffer should not be used after.

func (*ResponseBuffer) Header

func (w *ResponseBuffer) Header() http.Header

Header allows users to modify the headers (and trailers) sent to the client. The headers are not actually flushed to the underlying writer until a write or flush is being triggered.

func (*ResponseBuffer) ImplicitFlush

func (w *ResponseBuffer) ImplicitFlush() error

ImplicitFlush flushes data to the underlying writer without calling .Flush on it by proxy. This is provided separately from FlushError to allow for emulating the original ResponseWriter behaviour more correctly.

func (*ResponseBuffer) Reset

func (w *ResponseBuffer) Reset() error

Reset provides the differentiating feature from a regular ResponseWriter: it allows changing the response completely even if some data has been written already. This behaviour cannot be guaranteed if flush has been called explicitly. In that case it will return ErrAlreadyFlushed.

func (*ResponseBuffer) Unwrap

func (w *ResponseBuffer) Unwrap() http.ResponseWriter

Unwrap returns the underlying response writer. This is expected by the http.ResponseController to allow it to call appropriate optional interface implementations.

func (*ResponseBuffer) Write

func (w *ResponseBuffer) Write(buf []byte) (int, error)

Write appends the contents of p to the buffered response, growing the internal buffer as needed. If the write will cause the buffer be larger then the configure limit it will return ErrBufferFull.

func (*ResponseBuffer) WriteHeader

func (w *ResponseBuffer) WriteHeader(statusCode int)

WriteHeader will cause headers to be flushed to the underlying writer while calling WriteHeader on the underlying writer with the given status code.