heta

README

heta - HTTP middleware and utility functions

Documentation

Overview

Package heta provides http middleware and utility functions.

Index

• Variables
• func Attachment(w http.ResponseWriter, code int, filename string, content io.Reader, ...)
• func Blob(w http.ResponseWriter, code int, data []byte)
• func Documentation(name string, spec []byte) http.Handler
• func File(w http.ResponseWriter, code int, filename string, content io.Reader, ...)
• func GetError(r *http.Request) error
• func GetRealIP(r *http.Request) net.IP
• func GetStatus(r *http.Request) int
• func HTML(w http.ResponseWriter, code int, body []byte)
• func HTMLTemplate(w http.ResponseWriter, code int, tmpl *htmltemplate.Template, data any)
• func JSON(w http.ResponseWriter, code int, body any)
• func NoContent(w http.ResponseWriter, code int)
• func Profiler() http.Handler
• func RealIP(next http.Handler) http.Handler
• func SetError(r *http.Request, err error)
• func SetStatus(r *http.Request, status int)
• func Stream(w http.ResponseWriter, code int, content io.Reader)
• func StripPrefix(prefix string) func(http.Handler) http.Handler
• func Text(w http.ResponseWriter, code int, body []byte)
• func TextTemplate(w http.ResponseWriter, code int, tmpl *texttemplate.Template, data any)
• func WithError(next http.Handler) http.Handler
• func WithStatus(next http.Handler) http.Handler
• func WithValue(key, val any) func(next http.Handler) http.Handler
• func XML(w http.ResponseWriter, code int, body any)
• func XMLWithHeader(w http.ResponseWriter, code int, body any)
• type Middleware
  • func CatchStatus(code int, handler http.HandlerFunc) Middleware
  • func Chain(middlewares ...Middleware) Middleware
  • func MethodNotAllowed(handler http.HandlerFunc) Middleware
  • func NotFound(handler http.HandlerFunc) Middleware
  • func RemoveStatusCatchers(handler http.HandlerFunc) Middleware
  • func Timeout(timeout time.Duration) Middleware
  • func TimeoutCause(timeout time.Duration, cause error) Middleware

Variables

var EncodeJSONFunc = func(w io.Writer, v any) {
	enc := json.NewEncoder(w)
	enc.SetEscapeHTML(true)
	enc.Encode(v)
}

EncodeJSONFunc allows customization of JSON marshaling. Default: "encoding/json.Marshal" with enabled HTML escaping.

Functions

func Attachment

func Attachment(w http.ResponseWriter, code int, filename string, content io.Reader, size int64)

Attachment writes content as an attachment with the given filename and with the given status code. If size is not zero, sets Content-Length. If Content-Type is not set, tries to determine it from the extension of filename and content itself, falling back to "application/octet-stream" if it is unable to determine a valid MIME type, and sets Content-Type to the resulting MIME type. NOTE: It is recommended to use http.ServeContent instead of this function.

func Blob

func Blob(w http.ResponseWriter, code int, data []byte)

Blob writes data with the given status code. and Content-Type set to "application/octet-stream". Also sets Content-Length to the length of data.

func Documentation

func Documentation(name string, spec []byte) http.Handler

Documentation returns http handler that provides OpenAPI reference page using Scalar.

func File

func File(w http.ResponseWriter, code int, filename string, content io.Reader, size int64)

File writes content as is with the given status code. If size is not zero, sets Content-Length. If Content-Type is not set, tries to determine it from the extension of filename and content itself, falling back to "application/octet-stream" if it is unable to determine a valid MIME type, and sets Content-Type to the resulting MIME type. NOTE: It is recommended to use http.ServeContent instead of this function.

func GetError

func GetError(r *http.Request) error

GetError retrieves the error stored in the request context. Panics if the error container was not initialized by WithError middleware.

func GetRealIP

func GetRealIP(r *http.Request) net.IP

GetRealIP tries to extract real ip from X-Forward-For and X-Real-IP headers, fallbacks to http.Request's RemoteAddr if those headers are not present or contain invalid data.

func GetStatus

func GetStatus(r *http.Request) int

GetStatus retrieves the HTTP status code stored in the request context. Panics if the status container was not initialized by WithStatus middleware.

func HTML

func HTML(w http.ResponseWriter, code int, body []byte)

HTML writes body with the given status code and Content-Type set to "text/html; charset=utf-8". Also sets Content-Length to the size of body.

func HTMLTemplate

func HTMLTemplate(w http.ResponseWriter, code int, tmpl *htmltemplate.Template, data any)

HTMLTemplate executes html template tmpl with data and writes the output with the given status code and Content-Type set to "text/html; charset=utf-8".

func JSON

func JSON(w http.ResponseWriter, code int, body any)

JSON encodes body as json and writes the output with the given status code and Content-Type set to "application/json".

func NoContent

func NoContent(w http.ResponseWriter, code int)

NoContent writes http headers with the given status code.

func Profiler

func Profiler() http.Handler

Profiler returns http handler that provides /pprof routes.

func RealIP

func RealIP(next http.Handler) http.Handler

RealIP is a middleware that sets a http.Request's RemoteAddr to the results of parsing either the X-Real-IP or the X-Forwarded-For headers (in that order) if those headers are present and contain valid data.

func SetError

func SetError(r *http.Request, err error)

SetError stores an error in the request context for later retrieval. Panics if the error container was not initialized by WithError middleware.

func SetStatus

func SetStatus(r *http.Request, status int)

SetStatus stores an HTTP status code in the request context for later retrieval. Panics if the status container was not initialized by WithStatus middleware.

func Stream

func Stream(w http.ResponseWriter, code int, content io.Reader)

Stream writes content as is with the given status code. and Content-Type set to "application/octet-stream".

func StripPrefix

func StripPrefix(prefix string) func(http.Handler) http.Handler

StripPrefix is a middleware that will strip the provided prefix from the request path before handing the request over to the next handler.

func Text

func Text(w http.ResponseWriter, code int, body []byte)

Text writes body with the given status code and Content-Type set to "text/plain; charset=utf-8". Also sets Content-Length to the size of body.

func TextTemplate

func TextTemplate(w http.ResponseWriter, code int, tmpl *texttemplate.Template, data any)

TextTemplate executes text template tmpl with data and writes the output with the given status code and Content-Type set to "text/plain; charset=utf-8".

func WithError

func WithError(next http.Handler) http.Handler

WithError middleware injects an error container into the request context. This allows downstream handlers to store and retrieve errors across the request chain.

func WithStatus

func WithStatus(next http.Handler) http.Handler

WithStatus middleware injects a status code storage container into the request context. This allows downstream handlers to store and retrieve HTTP status codes across the request chain.

func WithValue

func WithValue(key, val any) func(next http.Handler) http.Handler

WithValue is a middleware that sets a given key/value in a context chain.

func XML

func XML(w http.ResponseWriter, code int, body any)

XML encodes body as xml and writes the output with the given status code and Content-Type set to "application/xml; charset=utf-8".

func XMLWithHeader

func XMLWithHeader(w http.ResponseWriter, code int, body any)

XMLWithHeader encodes body as xml with <?xml> header and writes the output with the given status code and Content-Type set to "application/xml; charset=utf-8".

Types

type Middleware

type Middleware func(next http.Handler) http.Handler

func CatchStatus

func CatchStatus(code int, handler http.HandlerFunc) Middleware

CatchStatus is a middleware that allows to catch status codes written to http.ResponseWriter and handle them.

func Chain

func Chain(middlewares ...Middleware) Middleware

Chain returns a new middleware that is the result of chaining multiple middlewares.

func MethodNotAllowed

func MethodNotAllowed(handler http.HandlerFunc) Middleware

MethodNotAllowed is a middleware that allows to catch http.StatusMethodNotAllowed codes written to http.ResponseWriter and handle them.

func NotFound

func NotFound(handler http.HandlerFunc) Middleware

NotFound is a middleware that allows to catch http.StatusNotFound codes written to http.ResponseWriter and handle them.

func RemoveStatusCatchers

func RemoveStatusCatchers(handler http.HandlerFunc) Middleware

RemoveStatusCatchers is a middleware that removes wrappers around the original http.ResponseWriter that were added by NotFound, MethodNotAllowed and CatchStatus middlewares.

func Timeout

func Timeout(timeout time.Duration) Middleware

Timeout is a middleware that will cancel request's context after the specified duration.

func TimeoutCause

func TimeoutCause(timeout time.Duration, cause error) Middleware

TimeoutCause is a middleware that will cancel request's context with the given cause after the specified duration.