http

Documentation

Index

• Constants
• func NewServer(lifecycle fx.Lifecycle, shutdown fx.Shutdowner, logger *zerolog.Logger, ...) chi.Router
• func ServerRequestParser[ServerRequest any](handler ServerRequestHandler[ServerRequest]) http.HandlerFunc
• type Cookie
• type CookieServerResponse
  • func (c CookieServerResponse) Render(writer http.ResponseWriter) error
• type Handler
• type HandlerFunc
• type Header
• type KeyValue
• type KeyValues
• type Request
• type ResponseWriter
• type ServerConfig
• type ServerErrorResponse
  • func (e ServerErrorResponse) Error() string
  • func (e ServerErrorResponse) MarshalZerologObject(event *zerolog.Event)
  • func (e ServerErrorResponse) Render(writer http.ResponseWriter) error
• type ServerJsonResponse
  • func (r ServerJsonResponse) Render(writer http.ResponseWriter) error
• type ServerRequestHandler
• type ServerResponse
• type ServerResponseFunc
  • func (fn ServerResponseFunc) Render(writer http.ResponseWriter) error
• type Status
  • func (s Status) String() string

Constants

const (
	StatusContinue           = Status(100) // RFC 9110, 15.2.1
	StatusSwitchingProtocols = Status(101) // RFC 9110, 15.2.2
	StatusProcessing         = Status(102) // RFC 2518, 10.1
	StatusEarlyHints         = Status(103) // RFC 8297

	StatusOK                   = Status(200) // RFC 9110, 15.3.1
	StatusCreated              = Status(201) // RFC 9110, 15.3.2
	StatusAccepted             = Status(202) // RFC 9110, 15.3.3
	StatusNonAuthoritativeInfo = Status(203) // RFC 9110, 15.3.4
	StatusNoContent            = Status(204) // RFC 9110, 15.3.5
	StatusResetContent         = Status(205) // RFC 9110, 15.3.6
	StatusPartialContent       = Status(206) // RFC 9110, 15.3.7
	StatusMultiStatus          = Status(207) // RFC 4918, 11.1
	StatusAlreadyReported      = Status(208) // RFC 5842, 7.1
	StatusIMUsed               = Status(226) // RFC 3229, 10.4.1

	StatusMultipleChoices  = Status(300) // RFC 9110, 15.4.1
	StatusMovedPermanently = Status(301) // RFC 9110, 15.4.2
	StatusFound            = Status(302) // RFC 9110, 15.4.3
	StatusSeeOther         = Status(303) // RFC 9110, 15.4.4
	StatusNotModified      = Status(304) // RFC 9110, 15.4.5
	StatusUseProxy         = Status(305) // RFC 9110, 15.4.6

	StatusTemporaryRedirect = Status(307) // RFC 9110, 15.4.8
	StatusPermanentRedirect = Status(308) // RFC 9110, 15.4.9

	StatusBadRequest                   = Status(400) // RFC 9110, 15.5.1
	StatusUnauthorized                 = Status(401) // RFC 9110, 15.5.2
	StatusPaymentRequired              = Status(402) // RFC 9110, 15.5.3
	StatusForbidden                    = Status(403) // RFC 9110, 15.5.4
	StatusNotFound                     = Status(404) // RFC 9110, 15.5.5
	StatusMethodNotAllowed             = Status(405) // RFC 9110, 15.5.6
	StatusNotAcceptable                = Status(406) // RFC 9110, 15.5.7
	StatusProxyAuthRequired            = Status(407) // RFC 9110, 15.5.8
	StatusRequestTimeout               = Status(408) // RFC 9110, 15.5.9
	StatusConflict                     = Status(409) // RFC 9110, 15.5.10
	StatusGone                         = Status(410) // RFC 9110, 15.5.11
	StatusLengthRequired               = Status(411) // RFC 9110, 15.5.12
	StatusPreconditionFailed           = Status(412) // RFC 9110, 15.5.13
	StatusRequestEntityTooLarge        = Status(413) // RFC 9110, 15.5.14
	StatusRequestURITooLong            = Status(414) // RFC 9110, 15.5.15
	StatusUnsupportedMediaType         = Status(415) // RFC 9110, 15.5.16
	StatusRequestedRangeNotSatisfiable = Status(416) // RFC 9110, 15.5.17
	StatusExpectationFailed            = Status(417) // RFC 9110, 15.5.18
	StatusTeapot                       = Status(418) // RFC 9110, 15.5.19 (Unused)
	StatusMisdirectedRequest           = Status(421) // RFC 9110, 15.5.20
	StatusUnprocessableEntity          = Status(422) // RFC 9110, 15.5.21
	StatusLocked                       = Status(423) // RFC 4918, 11.3
	StatusFailedDependency             = Status(424) // RFC 4918, 11.4
	StatusTooEarly                     = Status(425) // RFC 8470, 5.2.
	StatusUpgradeRequired              = Status(426) // RFC 9110, 15.5.22
	StatusPreconditionRequired         = Status(428) // RFC 6585, 3
	StatusTooManyRequests              = Status(429) // RFC 6585, 4
	StatusRequestHeaderFieldsTooLarge  = Status(431) // RFC 6585, 5
	StatusUnavailableForLegalReasons   = Status(451) // RFC 7725, 3

	StatusInternalServerError           = Status(500) // RFC 9110, 15.6.1
	StatusNotImplemented                = Status(501) // RFC 9110, 15.6.2
	StatusBadGateway                    = Status(502) // RFC 9110, 15.6.3
	StatusServiceUnavailable            = Status(503) // RFC 9110, 15.6.4
	StatusGatewayTimeout                = Status(504) // RFC 9110, 15.6.5
	StatusHTTPVersionNotSupported       = Status(505) // RFC 9110, 15.6.6
	StatusVariantAlsoNegotiates         = Status(506) // RFC 2295, 8.1
	StatusInsufficientStorage           = Status(507) // RFC 4918, 11.5
	StatusLoopDetected                  = Status(508) // RFC 5842, 7.2
	StatusNotExtended                   = Status(510) // RFC 2774, 7
	StatusNetworkAuthenticationRequired = Status(511) // RFC 6585, 6
)

HTTP status codes as registered with IANA. See: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

Functions

func NewServer

func NewServer(
	lifecycle fx.Lifecycle,
	shutdown fx.Shutdowner,
	logger *zerolog.Logger,
	config *ServerConfig,
) chi.Router

func ServerRequestParser

func ServerRequestParser[ServerRequest any](handler ServerRequestHandler[ServerRequest]) http.HandlerFunc

ServerRequestParser parses an HTTP request and populates a struct using field tags to map request data to struct fields.

Tags are applied in the order listed below, from lowest to highest priority. If multiple tags are present on the same field and more than one value is available in the request, the value from the higher-priority tag is used (e.g., `form` overrides `query`).

Supported tags:

• `header`: If the tag value is not empty, the tag value must match the normalized HTTP header name. If the tag value is empty, the field must be of type http.Header, and only one field with this tag is allowed per struct.

• `cookie`: If the tag value is not empty, the tag value must match the cookie name, and the field must be of type *http.Cookie. If the tag value is empty, the field must be of type []*http.Cookie, and only one field with this tag is allowed per struct.

• `query`: If the tag value is not empty, the tag value must match the query parameter name. If the tag value is empty, the field must be of type KeyValues, and only one field with this tag is allowed per struct.

• `url`: If the tag value is not empty, the tag value must match a named segment in the URL path. If the tag value is empty, the field must be of type KeyValue, and only one field with this tag is allowed per struct.

• `form`: If the tag value is not empty, the tag value must match the form parameter name. If the tag value is empty, the field must be of type KeyValues, and only one field with this tag is allowed per struct.

• `json`: The tag value must be empty. Only one field with this tag is allowed per struct. The request body is unmarshalled into this field using `encoding/json`. Any type validation is handled by the JSON unmarshalling process.

• `multipart`: The tag value must be empty. Only one field with this tag is allowed per struct. The field must be of type multipart.Reader.

• `body`: Only one field with this tag is allowed per struct. The field must be of type io.ReadCloser. If the tag value is not empty, the tag value must be a semicolon-separated list of accepted Content-Types, and if `form`, `json` or `multipart` tag exists, the list must not contain those types. If the tag value is empty, the field will be mapped if no other body type are matched.

Types

type Cookie

type Cookie = http.Cookie

type CookieServerResponse

type CookieServerResponse struct {
	Inner   ServerResponse
	Cookies []http.Cookie
}

func (CookieServerResponse) Render

func (c CookieServerResponse) Render(writer http.ResponseWriter) error

type Handler

type Handler = http.Handler

type HandlerFunc

type HandlerFunc = http.HandlerFunc

type Header

type Header = http.Header

type KeyValue

type KeyValue = map[string]string

type KeyValues

type KeyValues = map[string][]string

type Request

type Request = http.Request

type ResponseWriter

type ResponseWriter = http.ResponseWriter

type ServerConfig

type ServerConfig struct {
	Port              uint16 `env:"HTTP_SERVER_PORT" validate:"required"`
	ReadHeaderTimeout uint32 `env:"HTTP_SERVER_READ_HEADER_TIMEOUT" validate:"min=0,max=60" default:"5"`
	IdleTimeout       uint32 `env:"HTTP_SERVER_IDLE_TIMEOUT" validate:"min=0,max=3600" default:"60"`
	MaxHeaderBytes    uint32 `env:"HTTP_SERVER_MAX_HEADER_BYTES" validate:"min=0,max=65536" default:"4096"`
	ShutdownOnError   bool   `env:"HTTP_SERVER_SHUTDOWN_ON_ERROR" default:"true"`
}

type ServerErrorResponse

type ServerErrorResponse struct {
	Status Status
	Cause  error
}

func (ServerErrorResponse) Error

func (e ServerErrorResponse) Error() string

func (ServerErrorResponse) MarshalZerologObject

func (e ServerErrorResponse) MarshalZerologObject(event *zerolog.Event)

func (ServerErrorResponse) Render

func (e ServerErrorResponse) Render(writer http.ResponseWriter) error

type ServerJsonResponse

type ServerJsonResponse struct {
	Status   int
	Response any
}

func (ServerJsonResponse) Render

func (r ServerJsonResponse) Render(writer http.ResponseWriter) error

type ServerRequestHandler

type ServerRequestHandler[ServerRequest any] func(ctx context.Context, request *ServerRequest) ServerResponse

type ServerResponse

type ServerResponse interface {
	Render(writer http.ResponseWriter) error
}

type ServerResponseFunc

type ServerResponseFunc func(writer http.ResponseWriter) error

func (ServerResponseFunc) Render

func (fn ServerResponseFunc) Render(writer http.ResponseWriter) error

type Status

type Status int

func (Status) String

func (s Status) String() string

String returns a text for the HTTP status code. It returns the empty string if the code is unknown.