Documentation
¶
Index ¶
- Constants
- Variables
- func Accept(contentType string) func(rq *http.Request) error
- func AcceptJSON() func(rq *http.Request) error
- func AcceptStatus(statusCodes ...int) func(*http.Request) error
- func BearerToken(fn func(context.Context) (string, error)) func(*http.Request) error
- func Body(data []byte) func(*http.Request) error
- func ContentType(s string) func(*http.Request) error
- func Header(k, v string) func(*http.Request) error
- func JSONBody(v any) func(*http.Request) error
- func MaxRetries(n uint) func(*http.Request) error
- func MultipartFormDataFromMap[K comparable, V any](m map[K]V, opts ...func(multipart.Options)) func(*http.Request) error
- func NonCanonicalHeader(k, v string) func(*http.Request) error
- func Query(params map[string]any) func(*http.Request) error
- func QueryP(k string, v any) func(*http.Request) error
- func RawQuery(s string) func(*http.Request) error
- func ResponseBodyRequired() func(*http.Request) error
- func StreamResponse() func(*http.Request)
Constants ¶
const AcceptStatusHeader = "X-Blugnu-Http-Accept-Status"
canonical casing avoids go-staticcheck flagging the constant with SA1008
const MaxRetriesHeader = "X-Blugnu-Http-Max-Retries"
canonical casing avoids go-staticcheck flagging the constant with SA1008
const ResponseBodyRequiredHeader = "X-Blugnu-Http-Response-Body-Required"
canonical casing avoids go-staticcheck flagging the constant with SA1008
const StreamResponseHeader = "X-Blugnu-Http-Stream-Response"
canonical casing avoids go-staticcheck flagging the constant with SA1008
Variables ¶
var ( ErrInvalidJSON = errors.New("invalid json") ErrMarshallingJSON = errors.New("error marshalling json") ErrSetBoundary = errors.New("SetBoundary error") ErrTooManyArguments = errors.New("too many arguments") ErrInvalidQuery = errors.New("invalid query") )
var ErrCopyFailed = errors.New("copy() operation failed or was incomplete")
ErrCopyFailed is the error returned by the Body() RequestOption if the supplied byte slice cannot be completely copied to the request.Body.
Functions ¶
func AcceptJSON ¶
Accept sets the canonical Accept header with a value of "application/json"
func BearerToken ¶
BearerToken sets a canonical Authorisation header with a BearerToken value, using the result of a provided function.
The token value is not supplied directly; instead, the provided function will be called to obtain a token, or an error if a token is not available.
func Body ¶
Body sets the body of a request to the contents of a supplied byte slice and the ContentLength to the length of the slice.
request.ErrCopyFailed is returned if the provided slice cannot be completely copied to the request Body.
func ContentType ¶
ContentType sets the canonical Content-Type header on a request.
func Header ¶
Header sets the value of a canonical header.
Canonical header keys are normalised; normalising a non-canonical header may result in unintended changes to the case of the key.
To set a non-canonical header use RawHeader() instead.
Example:
// sets the canonical "Content-Type" header
Header("content-type", "application/json")
func JSONBody ¶
JSONBody sets the body of a request to the contents of a supplied value marshalled as JSON. A Content-Type header is added with the value application/json. The ContentLength is also set to the length of the JSON encoded bytes.
func MaxRetries ¶
MaxRetries configures a maximum number of retries on a specific request. If set, this overrides any MaxRetries that may be configured on the client used to make the request.
e.g. if the client is configured with MaxRetries == 5 and a request is submitted with MaxRetries == 3, then at most 4 attempts will be made: the initial request and at most 3 retry attempts
func MultipartFormDataFromMap ¶
func MultipartFormDataFromMap[K comparable, V any]( m map[K]V, opts ...func(multipart.Options), ) func(*http.Request) error
MultipartFormDataFromMap configures a multipart form data body by mapping the items in a map to the parts of the form data.
A map must be provided together with a function to provide the field id, filename and content bytes of each part, given the key and value of an item in the map (or an error if a valid part is unable to be derived).
The parts are added in order of map keys, after those keys have been sorted.
func NonCanonicalHeader ¶
NonCanonicalHeader sets the value of a header without canonicalising the key.
When setting a NonCanonicalHeader() the key is applied exactly as-specified; this may be important for non-canonical keys but is undesirable for canonical headers.
If setting a canonical header, use Header() instead.
Example:
// sets a non-canonical "sessionid" header
NonCanonicalHeader("sessionid", id)
func Query ¶
Query adds all key-value pairs in a supplied map to the query of a request.
Keys are url encoded before being added to the query. If any value is nil the corresponding key is added to the query with no value:
request.Query(map[string]any{"foo", nil}) -> ?foo
If the value is not nil it also is url encoded before being added to the query:
request.Query(map[string]any{"foo", true}) -> ?foo=true
request.Query(map[string]any{"foo", "subkey:value"}) -> ?foo=subkey%3Avalue
The order of the keys in the resulting query is not guaranteed as a result of map iteration order being undefined in Go. If key order is important then QueryP should be called to add each key-value pair individually in the desired order.
func QueryP ¶
QueryP adds a single key-value pair (or Param) to the query of a request.
The key is url encoded before being added to the query. If the value is nil the key is added to the query with no value:
request.QueryP("foo", nil) -> ?foo
If the value is not nil it is url encoded before being added to the query:
request.QueryP("foo", true) -> ?foo=true
request.QueryP("'a map'", "key=value") -> ?%27a+map%27=key%3Dvalue
func RawQuery ¶
RawQuery sets the query string of a request. Any existing query string will be overwritten.
The string is expected to be a valid, url encoded string.
func ResponseBodyRequired ¶
ResponseBodyRequired establishes that a non-empty response body is expected in response to this request. If the response provides an empty body the client will return an http.ErrNoResponseBody error, together with the response
func StreamResponse ¶
StreamResponse adds a request header indicating that the client expects to stream the response body. The header is removed
If specified, the usual reading of the response body prior to returning the response to the caller is skipped.
Types ¶
This section is empty.
Source Files