Documentation
ΒΆ
Overview ΒΆ
Package httpclient is a small HTTP client for talking to JSON APIs.
Build a client with New and a few options, then send requests with the methods on *Client. The default content type, sent and accepted, is JSON.
c := httpclient.New(
httpclient.BaseURL("https://api.example.com/v1"),
httpclient.Timeout(30*time.Second),
httpclient.PersistentRequestOptions(
httpclient.RequestAuthorizationBearer(token),
),
)
Reading responses ΒΆ
There are two ways to get a typed value back, and they differ only in where the value lives.
BindJSON returns a new value. There is no destination pointer to get wrong:
weather, err := c.BindJSON[Weather](ctx, http.MethodGet, "/current", nil)
ReadJSON fills a value you already hold, which is what you want for a long-lived field or a pooled struct:
var weather Weather err := c.ReadJSON(ctx, &weather, http.MethodGet, "/current", nil)
Both close the response body for you. An empty response body is reported as io.EOF, which IsErrEmptyJSON also recognises, because several APIs answer a successful write with no content.
Call is for endpoints whose success body carries nothing: it reports failure through the status alone and drains the body.
A response status of 400 or above returns an APIError. Read it with GetError, GetErrorCode, or decode its body with the generic BindError.
Owning the response body ΒΆ
Do, JSON, Form and Uploader.Upload hand you the *http.Response with its body still open. Closing it is your job, and DrainResponseBody is the way to do it so the connection can be reused. The BindXXX and ReadXXX methods and WriteTo do it for you.
Options ΒΆ
Client options, passed to New or Clone:
BaseURL, Timeout, DialTimeout, Transport, Handler, OAuth2, PersistentRequestOptions, RateLimit, RateLimitPerMinute, RateLimitFor, RateLimitForPerMinute, RateLimiter, RateLimiterFor, Retry, RedactQueryParams, RedactHeaders, JSONOptions, JSONMarshalOptions, JSONUnmarshalOptions, Debug, NoOption
Request options, passed to any request method:
RequestHeader, RequestAuthorization, RequestAuthorizationBearer, RequestQuery, RequestParam, RequestRateLimit, ClientTrace
Requirements ΒΆ
Go 1.27 or newer. The package uses generic methods and encoding/json/v2, so it does not build under GOEXPERIMENT=nojsonv2.
Index ΒΆ
- Variables
- func Bind[T any](resp *http.Response, opts ...json.Options) (T, error)
- func BindError[T any](err error, opts ...json.Options) (T, error)
- func BindResponse(resp *http.Response, dest any, opts ...json.Options) errordeprecated
- func DecodeError(err error, destPtr any, opts ...json.Options) error
- func DrainResponseBody(resp *http.Response) error
- func GetErrorCode(err error) int
- func RedactURL(u *url.URL, keys ...string) string
- func RegisterRequestHandler(reqHandlers ...RequestHandler)
- type APIError
- type Client
- func (c *Client) BindJSON[T any](ctx context.Context, method, urlpath string, payload any, ...) (T, error)
- func (c *Client) BindPlain[T PlainText](ctx context.Context, method, urlpath string, payload any, ...) (T, error)
- func (c *Client) Call(ctx context.Context, method, urlpath string, payload any, ...) error
- func (c *Client) Clone(opts ...Option) *Client
- func (c *Client) Do(ctx context.Context, method, urlpath string, payload any, ...) (*http.Response, error)
- func (c *Client) DrainResponseBody(resp *http.Response) error
- func (c *Client) Form(ctx context.Context, method, urlpath string, formValues url.Values, ...) (*http.Response, error)
- func (c *Client) GetPlainUnquote(ctx context.Context, method, urlpath string, payload any, ...) (string, error)
- func (c *Client) JSON(ctx context.Context, method, urlpath string, payload any, ...) (*http.Response, error)
- func (c *Client) NewUploader() *Uploader
- func (c *Client) ReadJSON(ctx context.Context, dest any, method, urlpath string, payload any, ...) error
- func (c *Client) ReadPlain(ctx context.Context, dest any, method, urlpath string, payload any, ...) error
- func (c *Client) RegisterRequestHandler(reqHandlers ...RequestHandler)
- func (c *Client) WriteTo(ctx context.Context, dest io.Writer, method, urlpath string, payload any, ...) (int64, error)
- type DebugLogger
- type Limiter
- type Option
- func BaseURL(uri string) Option
- func Debug(logger DebugLogger) Option
- func DialTimeout(timeout time.Duration) Option
- func Handler(h http.Handler) Option
- func JSONMarshalOptions(opts ...json.Options) Option
- func JSONOptions(opts ...json.Options) Option
- func JSONUnmarshalOptions(opts ...json.Options) Option
- func OAuth2(src oauth2.TokenSource) Option
- func PersistentRequestOptions(reqOpts ...RequestOption) Option
- func RateLimit(requestsPerSecond int) Option
- func RateLimitFor(key string, requestsPerSecond int) Option
- func RateLimitForPerMinute(key string, requestsPerMinute int) Option
- func RateLimitPerMinute(requestsPerMinute int) Option
- func RateLimiter(l Limiter) Option
- func RateLimiterFor(key string, l Limiter) Option
- func RedactHeaders(names ...string) Option
- func RedactQueryParams(keys ...string) Option
- func Retry(policy RetryPolicy) Option
- func Timeout(timeout time.Duration) Option
- func Transport(rt http.RoundTripper) Option
- type PlainText
- type RequestHandler
- type RequestOption
- func ClientTrace(clientTrace *httptrace.ClientTrace) RequestOption
- func RequestAuthorization(value string) RequestOption
- func RequestAuthorizationBearer(accessToken string) RequestOption
- func RequestHeader(overridePrev bool, key string, values ...string) RequestOption
- func RequestParam(key string, values ...string) RequestOption
- func RequestQuery(query url.Values) RequestOption
- func RequestRateLimit(key string) RequestOption
- type RetryPolicy
- type Uploader
- func (u *Uploader) AddField(key, value string) error
- func (u *Uploader) AddFile(key, filename string) error
- func (u *Uploader) AddFileSource(key, filename string, source io.Reader) error
- func (u *Uploader) Upload(ctx context.Context, method, urlpath string, opts ...RequestOption) (*http.Response, error)
Constants ΒΆ
This section is empty.
Variables ΒΆ
var ErrUploaderClosed = errors.New("httpclient: uploader already used, build a new one")
ErrUploaderClosed is returned when an Uploader is used for a second upload. Upload closes the multipart writer, so the collected body cannot be extended or resent. Build a new Uploader per request.
var IsErrEmptyJSON = func(err error) bool { if err == nil { return false } if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) { return true } // encoding/json/v2 reports a truncated or absent value syntactically. var syntacticErr *jsontext.SyntacticError if errors.As(err, &syntacticErr) { return syntacticErr.ByteOffset == 0 || errors.Is(syntacticErr.Err, io.ErrUnexpectedEOF) } // encoding/json v1 error, still reachable through a custom decoder. var syntaxErr *jsonv1.SyntaxError if errors.As(err, &syntaxErr) { return syntaxErr.Offset == 0 && syntaxErr.Error() == "unexpected end of JSON input" } errMsg := err.Error() return strings.Contains(errMsg, "readObjectStart: expect {") || strings.Contains(errMsg, "readArrayStart: expect [") }
IsErrEmptyJSON reports whether the given "err" is caused by a Client.ReadJSON or Client.BindJSON call when the response body was empty or didn't start with { or [.
It is a variable so that it can be replaced when a third-party JSON package reports empty input differently.
var NoOption = func(c *Client) { c.opts = c.opts[:0] }
NoOption is a helper function that clears the previous options in the chain. See the Client.Clone method.
Functions ΒΆ
func Bind ΒΆ added in v0.1.0
Bind decodes an already-received response into a new T, choosing the decoder from the response's Content-Type header. Closing the response body is up to the caller.
The optional "opts" are the encoding/json/v2 options for a JSON body. They replace the package default of encoding/json.DefaultOptionsV1(), they are not merged with it.
It is the generic form of BindResponse.
func BindError ΒΆ added in v0.1.0
BindError decodes the JSON body carried by the APIError inside "err" into a new T.
problem, decodeErr := httpclient.BindError[ProblemDetails](err)
It returns the original "err" untouched when "err" does not carry an APIError, so a caller can tell "not an API error" apart from "an API error I could not decode".
The optional "opts" are the encoding/json/v2 options for the body. They replace the package default of encoding/json.DefaultOptionsV1().
func BindResponse
deprecated
BindResponse consumes the response's body and binds the result to the "dest" pointer, closing the response's body is up to the caller.
The optional "opts" are the encoding/json/v2 options for a JSON body. They replace the package default of encoding/json.DefaultOptionsV1().
Deprecated: use the generic Bind instead, which cannot be handed a value of the wrong kind.
func DecodeError ΒΆ
DecodeError binds a json error to the "destPtr".
The optional "opts" are the encoding/json/v2 options for the body. They replace the package default of encoding/json.DefaultOptionsV1().
Prefer the generic BindError, which returns the decoded value.
func DrainResponseBody ΒΆ added in v0.0.3
DrainResponseBody drains the response body and closes it, allowing the transport to reuse TCP connections. A nil response or a nil body is a no-op.
func GetErrorCode ΒΆ
GetErrorCode reads an error, which should be a type of APIError, and returns its status code.
It returns zero when "err" is nil, is not an APIError, or carries no response. Check for zero before using the result as a status code.
func RedactURL ΒΆ added in v0.1.0
RedactURL returns the string form of "u" with the values of the given query parameter names replaced by "REDACTED", and any userinfo password masked. The input is not modified.
func RegisterRequestHandler ΒΆ
func RegisterRequestHandler(reqHandlers ...RequestHandler)
RegisterRequestHandler registers one or more request handlers to be ran before and after of each request on all newly created HTTP Clients. Useful for HTTP Client 3rd-party libraries e.g. on init register a custom request-response lifecycle logging.
Types ΒΆ
type APIError ΒΆ
type APIError struct {
Response *http.Response
// Body is the raw response body, already read and closed.
Body jsonv1.RawMessage
// URL is the request URL as it should be displayed, with the values of any
// query parameters registered through RedactQueryParams replaced by "REDACTED".
// Empty when the error was built by the package-level ExtractError.
URL string
// ReadErr holds the error that stopped the body from being read in full,
// if there was one. Body then holds whatever arrived before it.
ReadErr error
}
APIError errors that may return from the Client.
func ExtractError ΒΆ
ExtractError returns the response wrapped inside an APIError. It reads and closes the response body.
func GetError ΒΆ
GetError reports whether the given "err" is, or wraps, an APIError.
It reports false for an APIError carrying no response, so that callers can read apiErr.Response without a nil check.
func (APIError) Code ΒΆ added in v0.1.0
Code returns the response status code, or zero when the error carries no response. Unlike GetErrorCode it never panics on a zero APIError.
func (APIError) Error ΒΆ
Error implements the standard error type.
It reads "URL: 404 Not Found: body", skipping each part that is missing. Server code builds APIError values too, without a live round trip behind them, so Response, its Request and the Body may each be nil: an error with a body and no response renders the body alone, the zero value renders "".
type Client ΒΆ
type Client struct {
HTTPClient *http.Client
// BaseURL prepends to all requests.
BaseURL string
// A list of persistent request options.
PersistentRequestOptions []RequestOption
// contains filtered or unexported fields
}
A Client is an HTTP client. Initialize with the New package-level function.
func New ΒΆ
New returns a new HTTP Client. Available options:
- BaseURL
- Timeout
- DialTimeout
- Transport
- Handler
- PersistentRequestOptions
- RateLimit, RateLimitPerMinute, RateLimiter
- RateLimitFor, RateLimitForPerMinute, RateLimiterFor
- Retry
- OAuth2
- RedactQueryParams, RedactHeaders
- JSONOptions, JSONMarshalOptions, JSONUnmarshalOptions
- Debug
Look the Client.Do/JSON/... methods to send requests, the Client.BindXXX methods to receive typed responses, the Client.ReadXXX methods to fill a value you already hold and Client.Call for endpoints whose body carries nothing.
The default content type to send and receive data is JSON.
func (*Client) BindJSON ΒΆ added in v0.1.0
func (c *Client) BindJSON[T any](ctx context.Context, method, urlpath string, payload any, opts ...RequestOption) (T, error)
BindJSON sends the request and decodes the JSON response body into a new T.
It is the generic form of Client.ReadJSON: there is no destination pointer to get wrong, and the zero T comes back alongside any error.
weather, err := c.BindJSON[Weather](ctx, http.MethodGet, "/current.json", nil)
A response status >= 400 returns an APIError. An empty response body returns io.EOF, which IsErrEmptyJSON also recognises. The response body is closed before this method returns.
func (*Client) BindPlain ΒΆ added in v0.1.0
func (c *Client) BindPlain[T PlainText](ctx context.Context, method, urlpath string, payload any, opts ...RequestOption) (T, error)
BindPlain sends the request and reads the response body as plain text into a new T.
token, err := c.BindPlain[string](ctx, http.MethodGet, "/token", nil) count, err := c.BindPlain[int](ctx, http.MethodGet, "/count", nil)
A response status >= 400 returns an APIError. The response body is closed before this method returns.
func (*Client) Call ΒΆ added in v0.2.0
func (c *Client) Call(ctx context.Context, method, urlpath string, payload any, opts ...RequestOption) error
Call sends the request and reports failure through the response status only: a status of 400 or above returns an APIError, anything else succeeds and the body is drained. Use it for endpoints whose success body carries nothing.
It is ReadJSON with a nil destination: a non-nil payload is sent as JSON.
func (*Client) Clone ΒΆ added in v0.0.5
Clone returns a new Client with the same options as the original. If you want to override the options from the base "c" Client, use the NoOption variable as the 1st argument.
The clone carries its own request handler list, and it builds its own limiters for the rates given to RateLimit, RateLimitPerMinute, RateLimitFor and RateLimitForPerMinute, so parent and clone do not share those budgets.
A Limiter handed to RateLimiter or RateLimiterFor is the exception. Clone replays the options and that option carries the instance you passed, so the clone shares the limiter, and the budget, with its parent.
func (*Client) Do ΒΆ
func (c *Client) Do(ctx context.Context, method, urlpath string, payload any, opts ...RequestOption) (*http.Response, error)
Do sends an HTTP request and returns an HTTP response.
The payload can be:
- io.Reader
- raw []byte
- JSON raw message
- string
- url.Values
- struct (JSON).
If method is empty then it defaults to "GET". The final variadic, optional input argument sets the custom request options to use before the request.
Closing the returned response body is up to the caller, see Client.DrainResponseBody. The Client.BindXXX and Client.ReadXXX methods do that for you.
Any HTTP returned error will be of type APIError or a timeout error if the given context was canceled.
func (*Client) DrainResponseBody ΒΆ
DrainResponseBody drains the response body and closes it, allowing the transport to reuse TCP connections. It's automatically called by the Client.BindXXX and Client.ReadXXX methods.
func (*Client) Form ΒΆ
func (c *Client) Form(ctx context.Context, method, urlpath string, formValues url.Values, opts ...RequestOption) (*http.Response, error)
Form writes form data to the server.
Closing the returned response body is up to the caller, see Client.DrainResponseBody.
func (*Client) GetPlainUnquote ΒΆ
func (c *Client) GetPlainUnquote(ctx context.Context, method, urlpath string, payload any, opts ...RequestOption) (string, error)
GetPlainUnquote reads the response body as raw text and tries to unquote it, useful when the remote server sends a single key as a value but due to a backend mistake it sends it as JSON (quoted) instead of plain text.
func (*Client) JSON ΒΆ
func (c *Client) JSON(ctx context.Context, method, urlpath string, payload any, opts ...RequestOption) (*http.Response, error)
JSON writes data as JSON to the server.
Closing the returned response body is up to the caller, see Client.DrainResponseBody.
func (*Client) NewUploader ΒΆ
NewUploader returns a structure which is responsible for sending file and form data to the server.
func (*Client) ReadJSON ΒΆ
func (c *Client) ReadJSON(ctx context.Context, dest any, method, urlpath string, payload any, opts ...RequestOption) error
ReadJSON binds "dest" to the response's body. After this call, the response body reader is closed.
"dest" must be a non-nil pointer, or nil to discard the body. Prefer Client.BindJSON, which cannot be given the wrong kind of value.
If the response status code is >= 400 then it returns an APIError. If the response body is expected empty sometimes, you can omit the error through IsErrEmptyJSON or errors.Is(err, io.EOF).
func (*Client) ReadPlain ΒΆ
func (c *Client) ReadPlain(ctx context.Context, dest any, method, urlpath string, payload any, opts ...RequestOption) error
ReadPlain is like ReadJSON but it accepts a pointer to a string, byte slice or integer and it reads the body as plain text.
Prefer Client.BindPlain.
func (*Client) RegisterRequestHandler ΒΆ
func (c *Client) RegisterRequestHandler(reqHandlers ...RequestHandler)
RegisterRequestHandler registers one or more request handlers to be ran before and after of each new request.
Request handler's BeginRequest method run after each request constructed and right before sent to the server.
Request handler's EndRequest method run after response each received and right before methods return back to the caller.
Any request handlers MUST be set right after the Client's initialization.
func (*Client) WriteTo ΒΆ
func (c *Client) WriteTo(ctx context.Context, dest io.Writer, method, urlpath string, payload any, opts ...RequestOption) (int64, error)
WriteTo reads the response and then copies its data to the "dest" writer. If the "dest" is a type of HTTP response writer then it writes the content-type and content-length of the original request.
Returns the amount of bytes written to "dest".
type DebugLogger ΒΆ
A DebugLogger receives the request and response dumps of the Debug option. Most loggers satisfy it as written, for example *golog.Logger.
var DefaultDebugLogger DebugLogger = stdDebugLogger{}
DefaultDebugLogger is what Debug uses when handed a nil logger. It prints through the standard log package, so log.SetOutput and log.SetFlags apply.
type Limiter ΒΆ added in v0.1.1
A Limiter blocks until the next request may be sent, or until the ctx ends.
The *Limiter of golang.org/x/time/rate satisfies this as written, and NewRateLimiter returns one. An implementation must be safe for concurrent use: the Client waits on it from every goroutine sending through the Client, and a Limiter shared between Clients is waited on by all of them.
func NewRateLimiter ΒΆ added in v0.1.1
NewRateLimiter returns a Limiter that allows requestsPerSecond requests per second, with a burst of the same size. Hand it to RateLimiter or RateLimiterFor to give several Clients one budget.
A value of zero or less returns nil, which disables limiting.
The result is the Limiter interface rather than the concrete type on purpose. A nil *rate.Limiter returned as itself would arrive inside a non-nil interface and panic on the first Wait.
func NewRateLimiterPerMinute ΒΆ added in v0.1.1
NewRateLimiterPerMinute is NewRateLimiter expressed per minute. The burst is the whole minute's worth, so a minute of requests may leave at once.
A value of zero or less returns nil, which disables limiting.
type Option ΒΆ
type Option = func(*Client)
func BaseURL ΒΆ
BaseURL registers the base URL of this client. All of its methods will prepend this url.
func Debug ΒΆ
func Debug(logger DebugLogger) Option
Debug enables the client's debug logger. It fires right before request is created and right after a response from the server is received.
Example Output for request:
[DBUG] 2022/03/01 21:54 HTTP Client: POST / HTTP/1.1
Host: 127.0.0.1:50948
User-Agent: Go-http-client/1.1
Content-Length: 22
Accept: application/json
Content-Type: application/json
Accept-Encoding: gzip
{"firstname":"Makis"}
Example Output for response:
[DBUG] 2022/03/01 21:54 HTTP Client: HTTP/1.1 200 OK
Content-Length: 27
Content-Type: application/json; charset=utf-8
Date: Tue, 01 Mar 2022 19:54:03 GMT
{
"firstname": "Makis"
}
Values of query parameters registered through RedactQueryParams, and the credentials of any Authorization header, are replaced by "REDACTED" in the output.
A nil logger uses DefaultDebugLogger, the standard log package.
func DialTimeout ΒΆ added in v0.0.9
DialTimeout specifies a time limit for creating connections by this Client. It is the maximum amount of time a dial will wait for a connect to complete. If the connection establishing process takes longer than this value, the dial will be cancelled.
The timeout includes name resolution, if required. When using TCP, and the host in the address parameter resolves to multiple IP addresses, the timeout is spread over each consecutive dial, such that each is given an appropriate fraction of the time to connect.
It sets the dialer of the Client's *http.Transport, cloning http.DefaultTransport when the Client has no transport yet, so proxy settings and pool defaults are kept. A Client whose transport is not an *http.Transport, such as one built by the Handler option, is left alone.
func Handler ΒΆ
Handler specifies an http.Handler instance which can be tested using this Client.
It registers a custom HTTP client transport which allows "fake calls" to the "h" server. Use it for testing.
It replaces the Client's transport, so a DialTimeout given before it has no effect and one given after it is ignored.
The response is recorded in full before the Client sees a byte, so a streaming handler (Server-Sent Events, chunked output) or a mid-response cancellation cannot be exercised through it. For those cases use the Transport option with an httptest.NewTestServer.
func JSONMarshalOptions ΒΆ added in v0.2.0
JSONMarshalOptions sets the encoding/json/v2 options used to encode request payloads, leaving the decoding set alone. Options given replace the marshal default, none restores it.
It exists for policies that differ by direction, such as jsontext.AllowInvalidUTF8(true) on the way out while decoding stays strict.
func JSONOptions ΒΆ added in v0.1.0
JSONOptions sets the encoding/json/v2 options this Client uses both to encode request payloads and to decode response bodies.
The default is encoding/json.DefaultOptionsV1(), which reproduces the behaviour of the original encoding/json package: case-insensitive field matching, duplicate object names allowed, lenient RFC 3339 parsing and so on. Pass your own options to tighten that up, for example:
httpclient.JSONOptions(json.RejectUnknownMembers(true))
Options given here replace the default set, they are not merged with it. Join them yourself with json.JoinOptions if you want both. No options restores the default.
To configure one direction only, see JSONMarshalOptions and JSONUnmarshalOptions.
func JSONUnmarshalOptions ΒΆ added in v0.2.0
JSONUnmarshalOptions sets the encoding/json/v2 options used to decode response bodies through Client.BindJSON and Client.ReadJSON, leaving the encoding set alone. Options given replace the unmarshal default, none restores it.
func OAuth2 ΒΆ added in v0.2.0
func OAuth2(src oauth2.TokenSource) Option
OAuth2 sends every request with a token obtained from "src", by wrapping the Client's current transport in an oauth2.Transport (http.DefaultTransport when there is none yet). Tokens are cached and refreshed through oauth2.ReuseTokenSource.
Usage with a static token:
c := httpclient.New(httpclient.OAuth2(oauth2.StaticTokenSource(&oauth2.Token{AccessToken: token})))
Or with a configuration that refreshes tokens on its own:
config := &oauth2.Config{...}
src := config.TokenSource(context.Background(), &oauth2.Token{...})
c := httpclient.New(httpclient.OAuth2(src))
Order matters: give Transport, Handler or DialTimeout before OAuth2, since it wraps whatever transport is set at that point. A DialTimeout given after it finds an *oauth2.Transport and does nothing.
The Authorization header is added inside the transport, after the Debug handler has dumped the request, so Debug output never shows the token.
func PersistentRequestOptions ΒΆ
func PersistentRequestOptions(reqOpts ...RequestOption) Option
PersistentRequestOptions adds one or more persistent request options that all requests made by this Client will respect.
func RateLimit ΒΆ
RateLimit configures how many requests per second this Client may send. Every attempt, including each retry, waits on the limiter.
The Client builds the limiter, so a Clone builds its own and the two do not share a budget. Use RateLimiter to give several Clients one limiter you own.
A value of zero or less disables rate limiting.
func RateLimitFor ΒΆ added in v0.1.0
RateLimitFor registers a named rate limiter on this Client, on top of any client-wide one. Requests select it with the RequestRateLimit request option, so several endpoints can carry their own budget:
c := httpclient.New(
httpclient.RateLimit(20), // the whole API.
httpclient.RateLimitFor("search", 2), // this endpoint only.
)
c.ReadJSON(ctx, &v, "GET", "/search", nil, httpclient.RequestRateLimit("search"))
The limiter belongs to the Client, so every call sharing the key shares the budget. A Clone builds its own, it does not share the parent's. Use RateLimiterFor to give several Clients one limiter you own.
A value of zero or less removes the named limiter.
func RateLimitForPerMinute ΒΆ added in v0.1.0
RateLimitForPerMinute is RateLimitFor expressed per minute.
func RateLimitPerMinute ΒΆ added in v0.0.11
RateLimitPerMinute configures how many requests per minute this Client may send.
A value of zero or less disables rate limiting.
func RateLimiter ΒΆ added in v0.1.1
RateLimiter sets a Limiter you own as this Client's client-wide limiter, in place of the one RateLimit would build. Clients given the same Limiter share one budget, which is what an upstream quota counted per IP address rather than per client asks for:
// The host allows 20 requests per second, whoever is asking. var hostLimiter = httpclient.NewRateLimiter(20) content := httpclient.New( httpclient.BaseURL(host+"/rest"), httpclient.RateLimiter(hostLimiter), ) catalogue := httpclient.New( httpclient.BaseURL(host), httpclient.RateLimiter(hostLimiter), )
Unlike RateLimit, a Clone shares the limiter with its parent rather than building its own: Clone replays the options and this one carries the very instance you passed.
A nil Limiter disables limiting, clearing anything set earlier in the chain. The Limiter's error is returned as it came, so a context error stays comparable with errors.Is.
func RateLimiterFor ΒΆ added in v0.1.1
RateLimiterFor registers a Limiter you own under a name, in place of the one RateLimitFor would build. Requests select it with RequestRateLimit, and every Client given the same Limiter shares the budget behind that name, even when they register it under different names.
As with RateLimiter, a Clone shares the limiter rather than building its own.
A nil Limiter removes the named limiter.
func RedactHeaders ΒΆ added in v0.1.0
RedactHeaders registers extra request and response header names whose values are replaced by "REDACTED" in Debug output. Authorization, Proxy-Authorization, Cookie and Set-Cookie are always redacted.
func RedactQueryParams ΒΆ added in v0.1.0
RedactQueryParams registers query parameter names (e.g. "apiKey", "token") whose values must never appear in APIError messages or in Debug output.
The request itself is not modified; only rendered text is scrubbed.
Request bodies are never scrubbed. Do not send a secret in a body and expect Debug to hide it.
func Retry ΒΆ added in v0.1.0
func Retry(policy RetryPolicy) Option
Retry enables automatic retries according to the given policy. A policy with MaxAttempts below 2 disables retrying.
func Timeout ΒΆ
Timeout specifies a time limit for requests made by this Client. The timeout includes connection time, any redirects, and reading the response body. A Timeout of zero means no timeout.
There is no default: without this option a request runs until the server answers or the context is done. Set one for anything talking to the internet.
func Transport ΒΆ added in v0.1.0
func Transport(rt http.RoundTripper) Option
Transport sets the http.RoundTripper the Client sends through.
Use it to plug in an instrumented transport, a recorded one, or the transport of an httptest.NewTestServer, whose in-memory network the default transport cannot reach:
srv := httptest.NewTestServer(t, mux) c := httpclient.New(httpclient.BaseURL(srv.URL), httpclient.Transport(srv.Client().Transport))
Transport, DialTimeout and Handler all write the same field. The last one given wins, except that DialTimeout only adjusts an *http.Transport.
type PlainText ΒΆ added in v0.1.0
PlainText lists the Go types Client.BindPlain can produce from a plain text response body.
type RequestHandler ΒΆ
type RequestHandler interface {
BeginRequest(context.Context, *http.Request) error
EndRequest(context.Context, *http.Response, error) error
}
RequestHandler can be set to each Client instance and it should be responsible to handle the begin and end states of each request. Its BeginRequest fires right before the client talks to the server and its EndRequest fires right after the client receives a response from the server.
A non-nil error from either one stops the call and is returned to the caller. An EndRequest handler that returns the error it was given, wrapped or not, is treated as passing it through rather than as a failure of its own.
type RequestOption ΒΆ
RequestOption declares the type of option one can pass to the Do methods (JSON, Form, ReadJSON, BindJSON...). Request options run before the request is sent.
func ClientTrace ΒΆ added in v0.0.4
func ClientTrace(clientTrace *httptrace.ClientTrace) RequestOption
ClientTrace adds a client trace to the request.
func RequestAuthorization ΒΆ
func RequestAuthorization(value string) RequestOption
RequestAuthorization sets an Authorization request header. Note that we could do the same with a Transport RoundTrip too.
func RequestAuthorizationBearer ΒΆ
func RequestAuthorizationBearer(accessToken string) RequestOption
RequestAuthorizationBearer sets an Authorization: Bearer $token request header.
func RequestHeader ΒΆ
func RequestHeader(overridePrev bool, key string, values ...string) RequestOption
RequestHeader adds or sets (if overridePrev is true) a header to the request.
func RequestParam ΒΆ
func RequestParam(key string, values ...string) RequestOption
RequestParam sets a single URL query parameter to the request.
func RequestQuery ΒΆ
func RequestQuery(query url.Values) RequestOption
RequestQuery adds a set of URL query parameters to the request.
func RequestRateLimit ΒΆ added in v0.0.11
func RequestRateLimit(key string) RequestOption
RequestRateLimit makes the request wait on the named limiter registered with RateLimitFor, RateLimitForPerMinute or RateLimiterFor. The wait happens on every attempt, retries included.
An unknown key is a no-op, so a request option can be registered before the limiter it names. A request carries one key; the last option to set it wins.
type RetryPolicy ΒΆ added in v0.1.0
type RetryPolicy struct {
// MaxAttempts is the total number of attempts including the first one.
// Values below 2 disable retrying.
MaxAttempts int
// InitialBackoff is the wait before the second attempt. Defaults to 500ms.
InitialBackoff time.Duration
// MaxBackoff caps the exponential backoff. Defaults to 10s.
MaxBackoff time.Duration
// Multiplier grows the backoff on each attempt. Defaults to 2.
Multiplier float64
// Jitter, when true, randomises each wait in [0, backoff].
Jitter bool
// StatusCodes lists the response status codes that trigger a retry.
// Defaults to 429, 502, 503 and 504.
StatusCodes []int
// RetryOn, when set, replaces the built-in decision (StatusCodes and
// transport-error rules). It receives the request, the response (nil on a
// transport error) and the error (nil on a received response).
RetryOn func(req *http.Request, resp *http.Response, err error) bool
// MaxRetryAfter caps the wait requested by a Retry-After response header.
// Defaults to MaxBackoff. A Retry-After header, when present and valid,
// takes precedence over the exponential backoff.
MaxRetryAfter time.Duration
// RetryNonIdempotent allows retrying POST, PATCH and other non-idempotent
// methods after a transport error. Retries on a received response status
// are always allowed, since the server did process the request.
RetryNonIdempotent bool
// OnRetry, when set, is called right before each wait with the attempt number
// that just failed (1-based), its request, response, error and the wait duration.
OnRetry func(attempt int, req *http.Request, resp *http.Response, err error, wait time.Duration)
}
RetryPolicy configures automatic retries of failed requests. Register it with the Retry client option.
A request is retried when the transport returned an error (network failure, timeout) and the method is idempotent (or RetryNonIdempotent is set), or when the response status code is one of StatusCodes. Requests whose context is done are never retried. Bodies are replayed through http.Request.GetBody, which the standard library provides for the buffered payloads Do accepts ([]byte, string, url.Values, JSON-encoded structs); a raw io.Reader payload is sent once.
Every attempt waits on the client's rate limiter and is visible to the registered request handlers, so debug output shows the failed attempts too.
type Uploader ΒΆ
Uploader holds the necessary information for upload requests.
Look the Client.NewUploader method.
func (*Uploader) AddFileSource ΒΆ
AddFileSource adds a form file to the uploader with the given key.