Documentation ¶
Index ¶
- Constants
- Variables
- func AcceptedLanguages(r *http.Request) (languages []string)
- func Attachment(w http.ResponseWriter, r io.Reader, filename string) (err error)
- func ClientIP(r *http.Request) (clientIP string)
- func Decode(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
- func DecodeForm(r *http.Request, qp QueryParamsOption, v interface{}) (err error)
- func DecodeJSON(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
- func DecodeMultipartForm(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
- func DecodeQueryParams(r *http.Request, v interface{}) (err error)
- func DecodeResponse[T any](r *http.Response, maxMemory bytesext.Bytes) (result T, err error)
- func DecodeResponseAny(r *http.Response, maxMemory bytesext.Bytes, v interface{}) (err error)
- func DecodeXML(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
- func DoRetryable[T any](ctx context.Context, isRetryableFn errorsext.IsRetryableFn[error], ...) Result[T, error]deprecated
- func DoRetryableResponse(ctx context.Context, onRetryFn errorsext.OnRetryFn[error], ...) Result[*http.Response, error]deprecated
- func HasRetryAfter(headers http.Header) Option[time.Duration]
- func Inline(w http.ResponseWriter, r io.Reader, filename string) (err error)
- func IsNonRetryableStatusCode(code int) bool
- func IsRetryableStatusCode(code int) bool
- func JSON(w http.ResponseWriter, status int, i interface{}) error
- func JSONBytes(w http.ResponseWriter, status int, b []byte) (err error)
- func JSONP(w http.ResponseWriter, status int, i interface{}, callback string) error
- func JSONStream(w http.ResponseWriter, status int, i interface{}) error
- func QualityValue(v string, qv float32) string
- func TestDecodeResponse(t *testing.T)
- func XML(w http.ResponseWriter, status int, i interface{}) error
- func XMLBytes(w http.ResponseWriter, status int, b []byte) (err error)
- type BuildRequestFn
- type BuildRequestFn2
- type DecodeAnyFn
- type ErrRetryableStatusCode
- type ErrStatusCode
- type ErrUnexpectedResponse
- type FormDecoder
- type FormEncoder
- type IsRetryableStatusCodeFn
- type IsRetryableStatusCodeFn2
- type QueryParamsOption
- type Retryer
- func (r Retryer) Backoff(fn errorsext.BackoffFn[error]) Retryer
- func (r Retryer) Client(client *http.Client) Retryer
- func (r Retryer) DecodeFn(fn DecodeAnyFn) Retryer
- func (r Retryer) Do(ctx context.Context, fn BuildRequestFn2, v any, expectedResponseCodes ...int) error
- func (r Retryer) DoResponse(ctx context.Context, fn BuildRequestFn2, expectedResponseCodes ...int) Result[*http.Response, error]
- func (r Retryer) IsEarlyReturnFn(fn errorsext.EarlyReturnFn[error]) Retryer
- func (r Retryer) IsRetryableFn(fn errorsext.IsRetryableFn2[error]) Retryer
- func (r Retryer) IsRetryableStatusCodeFn(fn IsRetryableStatusCodeFn2) Retryer
- func (r Retryer) MaxAttempts(mode errorsext.MaxAttemptsMode, maxAttempts uint8) Retryer
- func (r Retryer) MaxBytes(i bytesext.Bytes) Retryer
- func (r Retryer) Timeout(timeout time.Duration) Retryer
Constants ¶
const ( Gzip string = "gzip" Compress string = "compress" Deflate string = "deflate" Br string = "br" Identity string = "identity" Any string = "*" )
Accept-Encoding values
const ( UTF8 string = "utf-8" ISO88591 string = "iso-8859-1" )
Charset values
const ( Age string = "Age" AltSCV string = "Alt-Svc" Accept string = "Accept" AcceptCharset string = "Accept-Charset" AcceptPatch string = "Accept-Patch" AcceptRanges string = "Accept-Ranges" AcceptedLanguage string = "Accept-Language" AcceptEncoding string = "Accept-Encoding" Authorization string = "Authorization" CrossOriginResourcePolicy string = "Cross-Origin-Resource-Policy" CacheControl string = "Cache-Control" Connection string = "Connection" ContentDisposition string = "Content-Disposition" ContentEncoding string = "Content-Encoding" ContentLength string = "Content-Length" ContentType string = "Content-Type" ContentLanguage string = "Content-Language" ContentLocation string = "Content-Location" ContentRange string = "Content-Range" Date string = "Date" DeltaBase string = "Delta-Base" ETag string = "ETag" Expires string = "Expires" Host string = "Host" IM string = "IM" IfMatch string = "If-Match" IfModifiedSince string = "If-Modified-Since" IfNoneMatch string = "If-None-Match" IfRange string = "If-Range" IfUnmodifiedSince string = "If-Unmodified-Since" KeepAlive string = "Keep-Alive" LastModified string = "Last-Modified" Link string = "Link" Pragma string = "Pragma" ProxyAuthenticate string = "Proxy-Authenticate" ProxyAuthorization string = "Proxy-Authorization" PublicKeyPins string = "Public-Key-Pins" RetryAfter string = "Retry-After" Referer string = "Referer" Server string = "Server" SetCookie string = "Set-Cookie" StrictTransportSecurity string = "Strict-Transport-Security" Trailer string = "Trailer" TK string = "Tk" TransferEncoding string = "Transfer-Encoding" Location string = "Location" Upgrade string = "Upgrade" Vary string = "Vary" Via string = "Via" Warning string = "Warning" WWWAuthenticate string = "WWW-Authenticate" XForwardedFor string = "X-Forwarded-For" XForwardedHost string = "X-Forwarded-Host" XForwardedProto string = "X-Forwarded-Proto" XRealIP string = "X-Real-Ip" XContentTypeOptions string = "X-Content-Type-Options" XFrameOptions string = "X-Frame-Options" XXSSProtection string = "X-XSS-Protection" XDNSPrefetchControl string = "X-DNS-Prefetch-Control" Allow string = "Allow" Origin string = "Origin" AccessControlAllowOrigin string = "Access-Control-Allow-Origin" AccessControlAllowCredentials string = "Access-Control-Allow-Credentials" AccessControlAllowHeaders string = "Access-Control-Allow-Headers" AccessControlAllowMethods string = "Access-Control-Allow-Methods" AccessControlExposeHeaders string = "Access-Control-Expose-Headers" AccessControlMaxAge string = "Access-Control-Max-Age" AccessControlRequestHeaders string = "Access-Control-Request-Headers" AccessControlRequestMethod string = "Access-Control-Request-Method" TimingAllowOrigin string = "Timing-Allow-Origin" UserAgent string = "User-Agent" )
HTTP Header keys
const ( ApplicationJSONNoCharset string = "application/json" ApplicationJSON string = ApplicationJSONNoCharset + charsetUTF8 ApplicationJavaScript string = "application/javascript" ApplicationXMLNoCharset string = "application/xml" ApplicationXML string = ApplicationXMLNoCharset + charsetUTF8 ApplicationForm string = "application/x-www-form-urlencoded" ApplicationProtobuf string = "application/protobuf" ApplicationMsgpack string = "application/msgpack" ApplicationWasm string = "application/wasm" ApplicationPDF string = "application/pdf" ApplicationOctetStream string = "application/octet-stream" TextHTMLNoCharset = "text/html" TextHTML string = TextHTMLNoCharset + charsetUTF8 TextPlainNoCharset = "text/plain" TextPlain string = TextPlainNoCharset + charsetUTF8 TextMarkdownNoCharset string = "text/markdown" TextMarkdown string = TextMarkdownNoCharset + charsetUTF8 TextCSSNoCharset string = "text/css" TextCSS string = TextCSSNoCharset + charsetUTF8 TextCSV string = "text/csv" ImagePNG string = "image/png" ImageGIF string = "image/gif" ImageSVG string = "image/svg+xml" ImageJPEG string = "image/jpeg" MultipartForm string = "multipart/form-data" )
Mime Type values for the Content-Type HTTP header
const (
// QualityValueFormat is a format string helper for Quality Values
QualityValueFormat = "%s;q=%1.3g"
)
Variables ¶
var ( // DefaultFormDecoder of this package, which is configurable DefaultFormDecoder FormDecoder = form.NewDecoder() // DefaultFormEncoder of this package, which is configurable DefaultFormEncoder FormEncoder = form.NewEncoder() )
Functions ¶
func AcceptedLanguages ¶
AcceptedLanguages returns an array of accepted languages denoted by the Accept-Language header sent by the browser
func Attachment ¶
Attachment is a helper method for returning an attachment file to be downloaded, if you with to open inline see function Inline
func ClientIP ¶
ClientIP implements the best effort algorithm to return the real client IP, it parses X-Real-IP and X-Forwarded-For in order to work properly with reverse-proxies such us: nginx or haproxy.
func Decode ¶
func Decode(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
Decode takes the request and attempts to discover its content type via the http headers and then decode the request body into the provided struct. Example if header was "application/json" would decode using json.NewDecoder(ioext.LimitReader(r.Body, maxBytes)).Decode(v).
This default to parsing query params if includeQueryParams=true and no other content type matches.
NOTE: when includeQueryParams=true query params will be parsed and included eg. route /user?test=true 'test' is added to parsed XML and replaces any values that may have been present
func DecodeForm ¶
func DecodeForm(r *http.Request, qp QueryParamsOption, v interface{}) (err error)
DecodeForm parses the requests form data into the provided struct.
The Content-Type and http method are not checked.
NOTE: when QueryParamsOption=QueryParams the query params will be parsed and included eg. route /user?test=true 'test' is added to parsed Form.
func DecodeJSON ¶
func DecodeJSON(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
DecodeJSON decodes the request body into the provided struct and limits the request size via an ioext.LimitReader using the maxBytes param.
The Content-Type e.g. "application/json" and http method are not checked.
NOTE: when includeQueryParams=true query params will be parsed and included eg. route /user?test=true 'test' is added to parsed JSON and replaces any values that may have been present
func DecodeMultipartForm ¶
func DecodeMultipartForm(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
DecodeMultipartForm parses the requests form data into the provided struct.
The Content-Type and http method are not checked.
NOTE: when includeQueryParams=true query params will be parsed and included eg. route /user?test=true 'test' is added to parsed MultipartForm.
func DecodeQueryParams ¶
DecodeQueryParams takes the URL Query params flag.
func DecodeResponse ¶ added in v5.17.0
DecodeResponse takes the response and attempts to discover its content type via the http headers and then decode the request body into the provided type.
Example if header was "application/json" would decode using json.NewDecoder(ioext.LimitReader(r.Body, maxBytes)).Decode(v).
func DecodeResponseAny ¶ added in v5.29.0
DecodeResponseAny takes the response and attempts to discover its content type via the http headers and then decode the request body into the provided type.
Example if header was "application/json" would decode using json.NewDecoder(ioext.LimitReader(r.Body, maxBytes)).Decode(v).
func DecodeXML ¶
func DecodeXML(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
DecodeXML decodes the request body into the provided struct and limits the request size via an ioext.LimitReader using the maxBytes param.
The Content-Type e.g. "application/xml" and http method are not checked.
NOTE: when includeQueryParams=true query params will be parsed and included eg. route /user?test=true 'test' is added to parsed XML and replaces any values that may have been present
func DoRetryable
deprecated
added in
v5.17.0
func DoRetryable[T any](ctx context.Context, isRetryableFn errorsext.IsRetryableFn[error], onRetryFn errorsext.OnRetryFn[error], isRetryableStatusCode IsRetryableStatusCodeFn, client *http.Client, expectedResponseCode int, maxMemory bytesext.Bytes, buildFn BuildRequestFn) Result[T, error]
DoRetryable will execute the provided functions code and automatically retry before returning the result.
This function currently supports decoding the following automatically based on the response Content-Type with Gzip supported: - JSON - XML
Deprecated: use `httpext.Retrier` instead which corrects design issues with the current implementation.
func DoRetryableResponse
deprecated
added in
v5.17.0
func DoRetryableResponse(ctx context.Context, onRetryFn errorsext.OnRetryFn[error], isRetryableStatusCode IsRetryableStatusCodeFn, client *http.Client, buildFn BuildRequestFn) Result[*http.Response, error]
DoRetryableResponse will execute the provided functions code and automatically retry before returning the *http.Response.
Deprecated: use `httpext.Retrier` instead which corrects design issues with the current implementation.
func HasRetryAfter ¶ added in v5.29.0
HasRetryAfter parses the Retry-After header and returns the duration if possible.
func Inline ¶
Inline is a helper method for returning a file inline to be rendered/opened by the browser
func IsNonRetryableStatusCode ¶ added in v5.29.0
IsNonRetryableStatusCode returns true if the provided status code should generally not be retryable.
func IsRetryableStatusCode ¶ added in v5.4.0
IsRetryableStatusCode returns true if the provided status code is considered retryable.
func JSON ¶
func JSON(w http.ResponseWriter, status int, i interface{}) error
JSON marshals provided interface + returns JSON + status code
func JSONBytes ¶
func JSONBytes(w http.ResponseWriter, status int, b []byte) (err error)
JSONBytes returns provided JSON response with status code
func JSONP ¶
func JSONP(w http.ResponseWriter, status int, i interface{}, callback string) error
JSONP sends a JSONP response with status code and uses `callback` to construct the JSONP payload.
func JSONStream ¶ added in v5.2.0
func JSONStream(w http.ResponseWriter, status int, i interface{}) error
JSONStream uses json.Encoder to stream the JSON response body.
This differs from the JSON helper which unmarshalls into memory first allowing the capture of JSON encoding errors.
func QualityValue ¶
QualityValue accepts a values to add/concatenate a quality values to and the quality values itself.
func TestDecodeResponse ¶ added in v5.17.0
Types ¶
type BuildRequestFn ¶ added in v5.17.0
BuildRequestFn is a function used to rebuild an HTTP request for use in retryable code.
type BuildRequestFn2 ¶ added in v5.29.0
BuildRequestFn2 is a function used to rebuild an HTTP request for use in retryable code.
type DecodeAnyFn ¶ added in v5.29.0
type DecodeAnyFn func(ctx context.Context, resp *http.Response, maxMemory bytesext.Bytes, v any) error
DecodeAnyFn is a function used to decode the response body into the desired type.
type ErrRetryableStatusCode ¶ added in v5.17.0
ErrRetryableStatusCode can be used to indicate a retryable HTTP status code was encountered as an error.
func (ErrRetryableStatusCode) Error ¶ added in v5.17.0
func (e ErrRetryableStatusCode) Error() string
type ErrStatusCode ¶ added in v5.29.0
type ErrStatusCode struct { // StatusCode is the HTTP response status code that was encountered. StatusCode int // IsRetryableStatusCode indicates if the status code is considered retryable. IsRetryableStatusCode bool // Headers contains the headers from the HTTP response. Headers http.Header // Body is the optional body of the HTTP response. Body []byte }
ErrStatusCode can be used to treat/indicate a status code as an error and ability to indicate if it is retryable.
func (ErrStatusCode) Error ¶ added in v5.29.0
func (e ErrStatusCode) Error() string
Error returns the error message for the status code.
func (ErrStatusCode) IsRetryable ¶ added in v5.29.0
func (e ErrStatusCode) IsRetryable() bool
IsRetryable returns if the provided status code is considered retryable.
type ErrUnexpectedResponse ¶ added in v5.17.1
ErrUnexpectedResponse can be used to indicate an unexpected response was encountered as an error and provide access to the *http.Response.
func (ErrUnexpectedResponse) Error ¶ added in v5.17.1
func (e ErrUnexpectedResponse) Error() string
type FormDecoder ¶
FormDecoder is the type used for decoding a form for use
type FormEncoder ¶ added in v5.1.0
FormEncoder is the type used for encoding form data
type IsRetryableStatusCodeFn ¶ added in v5.17.0
IsRetryableStatusCodeFn is a function used to determine if the provided status code is considered retryable.
type IsRetryableStatusCodeFn2 ¶ added in v5.29.0
IsRetryableStatusCodeFn2 is a function used to determine if the provided status code is considered retryable.
type QueryParamsOption ¶
type QueryParamsOption uint8
QueryParamsOption represents the options for including query parameters during Decode helper functions
const ( QueryParams QueryParamsOption = iota NoQueryParams )
QueryParamsOption's
type Retryer ¶ added in v5.29.0
type Retryer struct {
// contains filtered or unexported fields
}
Retryer is used to retry any fallible operation.
The `Retryer` is designed to be stateless and reusable. Configuration is also copy and so a base `Retryer` can be used and changed for one-off requests eg. changing max attempts resulting in a new `Retrier` for that request.
func NewRetryer ¶ added in v5.29.0
func NewRetryer() Retryer
NewRetryer returns a new `Retryer` with sane default values.
The default values are:
- `IsRetryableFn` uses the existing `errorsext.IsRetryableHTTP` function.
- `MaxAttemptsMode` is `MaxAttemptsNonRetryableReset`.
- `MaxAttempts` is 5.
- `BackoffFn` will sleep for 200ms or is successful `Retry-After` header can be parsed. It's recommended to use exponential backoff for production with a quick copy-paste-modify of the default function
- `Timeout` is 0.
- `IsRetryableStatusCodeFn` is set to the existing `IsRetryableStatusCode` function.
- `IsEarlyReturnFn` is set to check if the error is an `ErrStatusCode` and if the status code is non-retryable.
- `Client` is set to `http.DefaultClient`.
- `MaxBytes` is set to 2MiB.
- `DecodeAnyFn` is set to the existing `DecodeResponseAny` function that supports JSON and XML.
WARNING: The default functions may receive enhancements or fixes in the future which could change their behavior, however every attempt will be made to maintain backwards compatibility or made additive-only if possible.
func (Retryer) DecodeFn ¶ added in v5.29.0
func (r Retryer) DecodeFn(fn DecodeAnyFn) Retryer
DecodeFn sets the decode function for the `Retryer`.
func (Retryer) Do ¶ added in v5.29.0
func (r Retryer) Do(ctx context.Context, fn BuildRequestFn2, v any, expectedResponseCodes ...int) error
Do will execute the provided functions code and automatically retry using the provided retry function decoding the response body into the desired type `v`, which must be passed as mutable.
func (Retryer) DoResponse ¶ added in v5.29.0
func (r Retryer) DoResponse(ctx context.Context, fn BuildRequestFn2, expectedResponseCodes ...int) Result[*http.Response, error]
DoResponse will execute the provided functions code and automatically retry before returning the *http.Response based on HTTP status code, if defined, and can be used when processing of the response body may not be necessary or something custom is required.
NOTE: it is up to the caller to close the response body if a successful request is made.
func (Retryer) IsEarlyReturnFn ¶ added in v5.29.0
func (r Retryer) IsEarlyReturnFn(fn errorsext.EarlyReturnFn[error]) Retryer
IsEarlyReturnFn sets the `EarlyReturnFn` for the `Retryer`.
func (Retryer) IsRetryableFn ¶ added in v5.29.0
func (r Retryer) IsRetryableFn(fn errorsext.IsRetryableFn2[error]) Retryer
IsRetryableFn sets the `IsRetryableFn` for the `Retryer`.
func (Retryer) IsRetryableStatusCodeFn ¶ added in v5.29.0
func (r Retryer) IsRetryableStatusCodeFn(fn IsRetryableStatusCodeFn2) Retryer
IsRetryableStatusCodeFn is called to determine if the status code is retryable.
func (Retryer) MaxAttempts ¶ added in v5.29.0
func (r Retryer) MaxAttempts(mode errorsext.MaxAttemptsMode, maxAttempts uint8) Retryer
MaxAttempts sets the maximum number of attempts for the `Retryer`.
NOTE: Max attempts is optional and if not set will retry indefinitely on retryable errors.