httpext

package
v5.29.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 4, 2024 License: Apache-2.0, MIT Imports: 27 Imported by: 11

Documentation

Index

Constants

View Source 
const (
	Gzip     string = "gzip"
	Compress string = "compress"
	Deflate  string = "deflate"
	Br       string = "br"
	Identity string = "identity"
	Any      string = "*"
)

Accept-Encoding values

View Source 
const (
	UTF8     string = "utf-8"
	ISO88591 string = "iso-8859-1"
)

Charset values

View Source 
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

View Source 
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

View Source 
const (
	// QualityValueFormat is a format string helper for Quality Values
	QualityValueFormat = "%s;q=%1.3g"
)

Variables

View Source 
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 

func AcceptedLanguages(r *http.Request) (languages []string)

AcceptedLanguages returns an array of accepted languages denoted by the Accept-Language header sent by the browser

func Attachment 

func Attachment(w http.ResponseWriter, r io.Reader, filename string) (err error)

Attachment is a helper method for returning an attachment file to be downloaded, if you with to open inline see function Inline

func ClientIP 

func ClientIP(r *http.Request) (clientIP string)

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 

func DecodeQueryParams(r *http.Request, v interface{}) (err error)

DecodeQueryParams takes the URL Query params flag.

func DecodeResponse added in v5.17.0 

func DecodeResponse[T any](r *http.Response, maxMemory bytesext.Bytes) (result T, err error)

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 

func DecodeResponseAny(r *http.Response, maxMemory bytesext.Bytes, v interface{}) (err error)

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 

func HasRetryAfter(headers http.Header) Option[time.Duration]

HasRetryAfter parses the Retry-After header and returns the duration if possible.

func Inline 

func Inline(w http.ResponseWriter, r io.Reader, filename string) (err error)

Inline is a helper method for returning a file inline to be rendered/opened by the browser

func IsNonRetryableStatusCode added in v5.29.0 

func IsNonRetryableStatusCode(code int) bool

IsNonRetryableStatusCode returns true if the provided status code should generally not be retryable.

func IsRetryableStatusCode added in v5.4.0 

func IsRetryableStatusCode(code int) bool

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 

func QualityValue(v string, qv float32) string

QualityValue accepts a values to add/concatenate a quality values to and the quality values itself.

func TestDecodeResponse added in v5.17.0 

func TestDecodeResponse(t *testing.T)

func XML 

func XML(w http.ResponseWriter, status int, i interface{}) error

XML marshals provided interface + returns XML + status code

func XMLBytes 

func XMLBytes(w http.ResponseWriter, status int, b []byte) (err error)

XMLBytes returns provided XML response with status code

Types

type BuildRequestFn added in v5.17.0 

type BuildRequestFn func(ctx context.Context) (*http.Request, error)

BuildRequestFn is a function used to rebuild an HTTP request for use in retryable code.

type BuildRequestFn2 added in v5.29.0 

type BuildRequestFn2 func(ctx context.Context) Result[*http.Request, error]

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 

type ErrRetryableStatusCode struct {
	Response *http.Response
}

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 

type ErrUnexpectedResponse struct {
	Response *http.Response
}

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 

type FormDecoder interface {
	Decode(interface{}, url.Values) error
}

FormDecoder is the type used for decoding a form for use

type FormEncoder added in v5.1.0 

type FormEncoder interface {
	Encode(interface{}) (url.Values, error)
}

FormEncoder is the type used for encoding form data

type IsRetryableStatusCodeFn added in v5.17.0 

type IsRetryableStatusCodeFn func(code int) bool

IsRetryableStatusCodeFn is a function used to determine if the provided status code is considered retryable.

type IsRetryableStatusCodeFn2 added in v5.29.0 

type IsRetryableStatusCodeFn2 func(ctx context.Context, code int) bool

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) Backoff added in v5.29.0 

func (r Retryer) Backoff(fn errorsext.BackoffFn[error]) Retryer

Backoff sets the backoff function for the `Retryer`.

func (Retryer) Client added in v5.29.0 

func (r Retryer) Client(client *http.Client) Retryer

Client sets the `http.Client` for the `Retryer`.

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.

func (Retryer) MaxBytes added in v5.29.0 

func (r Retryer) MaxBytes(i bytesext.Bytes) Retryer

MaxBytes sets the maximum memory to use when decoding the response body including: - upon unexpected status codes. - when decoding the response body. - when draining the response body before closing allowing connection re-use.

func (Retryer) Timeout added in v5.29.0 

func (r Retryer) Timeout(timeout time.Duration) Retryer

Timeout sets the timeout for the `Retryer`. This is the timeout per `RetyableFn` attempt and not the entirety of the `Retryer` execution.

A timeout of 0 will disable the timeout and is the default.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.