httpclient

package module
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Sep 11, 2026 License: MIT Imports: 26 Imported by: 0

README ΒΆ

HTTP Client

build status report card godocs

HTTP Client is a small HTTP client for Go, for talking to JSON APIs. Requires Go 1.27.

package main

import (
	"context"
	"net/http"
	"net/url"

	"github.com/kataras/httpclient"
)

// The BaseURL of our API client.
const BaseURL = "https://api.weatherapi.com/v1"

type (
	Options struct {
		APIKey string `json:"api_key" yaml:"APIKey" toml:"APIKey"`
	}

	Client struct {
		*httpclient.Client
	}
)

func NewClient(opts Options) *Client {
	apiKeyParameterSetter := httpclient.RequestParam("key", opts.APIKey)

	c := httpclient.New(
		httpclient.BaseURL(BaseURL),
		httpclient.PersistentRequestOptions(apiKeyParameterSetter),
	)

	return &Client{c}
}

func (c *Client) GetCurrentByCity(ctx context.Context, city string) (resp Response, err error) {
	urlpath := "/current.json"
	// ?q=Athens&aqi=no
	params := httpclient.RequestQuery(url.Values{
		"q":   []string{city},
		"aqi": []string{"no"},
	})

	err = c.Client.ReadJSON(ctx, &resp, http.MethodGet, urlpath, nil, params)
	return
}

Some of the features HTTP Client offers:

  • Typed responses through generic methods
  • Rate limits, per client, per endpoint, or one budget shared by several clients
  • Retry with backoff
  • Query parameter and header redaction in errors and debug output
  • Middleware
  • JSON (read & write)
  • Forms
  • File upload
  • Plain text
  • Debug and more...
Typed responses

BindJSON names the response type at the call site and returns it. There is no destination pointer, so there is no way to pass the wrong kind of value.

weather, err := c.BindJSON[Response](ctx, http.MethodGet, "/current.json", nil, params)

ReadJSON fills a value you already hold, which is what you want for a long-lived field or a pooled struct. Both close the response body for you.

var weather Response
err := c.ReadJSON(ctx, &weather, http.MethodGet, "/current.json", nil, params)

BindPlain[T] does the same for plain text bodies, into a string, byte slice or number. Bind[T](resp) decodes a response you already hold, choosing by Content-Type. BindError[T](err) decodes the body an APIError carries.

An empty response body comes back as io.EOF, which IsErrEmptyJSON also recognises. Several APIs answer a successful write with no content, so that is a normal outcome rather than a failure.

Who closes the 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 how to do it so the connection can be reused. The Bind and Read methods and WriteTo do it for you.

Retries

Retrying is opt-in. Pass a RetryPolicy and failed attempts are repeated with exponential backoff (a Retry-After response header wins when present). By default only network errors on idempotent methods and the 429, 502, 503 and 504 statuses are retried; buffered request bodies are replayed automatically.

c := httpclient.New(
	httpclient.BaseURL(BaseURL),
	httpclient.RateLimit(20),
	httpclient.Retry(httpclient.RetryPolicy{
		MaxAttempts:    3,
		InitialBackoff: 500 * time.Millisecond,
		MaxBackoff:     10 * time.Second,
		Jitter:         true,
	}),
)

Every attempt waits on the rate limiter and is visible to the registered request handlers, so Debug output shows the failed attempts as well.

Rate limits per endpoint

RateLimit covers the whole API. When one endpoint has a tighter budget of its own, register a named limiter and tag the calls that use it. Every call sharing the key shares the budget, retries included.

c := httpclient.New(
	httpclient.BaseURL(BaseURL),
	httpclient.RateLimit(20),             // the whole API
	httpclient.RateLimitFor("search", 2), // this endpoint
)

results, err := c.BindJSON[Results](ctx, http.MethodGet, "/search", nil,
	httpclient.RequestRateLimit("search"))

A Clone builds its own limiters rather than sharing the parent's. When you want the opposite, read on.

One budget across several clients

Sometimes one upstream quota covers more than one client. A host that allows 20 requests per second counts them per IP address, not per client, so two clients against that host with RateLimit(20) each can send 40 and have the excess dropped with no error.

Build the limiter yourself and hand the same one to both:

// The host allows 20 requests per second, whoever is asking.
var hostLimiter = httpclient.NewRateLimiter(20)

// Different path prefix, different API key, same quota.
content := httpclient.New(
	httpclient.BaseURL(host+"/rest"),
	httpclient.RateLimiter(hostLimiter),
)
catalogue := httpclient.New(
	httpclient.BaseURL(host),
	httpclient.RateLimiter(hostLimiter),
)

RateLimiterFor(key, limiter) does the same for a named limiter. Clients sharing a limiter share the budget behind it, even when they register it under different names.

This is the one case where a Clone does share: the option carries the limiter you passed, and Clone replays the options, so the clone waits on the same one. RateLimit and RateLimitFor keep building a fresh limiter per clone.

A Limiter is any type with Wait(ctx) error, so a distributed limiter of your own works here too. It has to be safe for concurrent use.

Redacting secrets

When the API key travels in the query string it would otherwise be printed by APIError.Error() and by the Debug dumps. Register the parameter names once and their values are replaced with REDACTED in all rendered text. The request itself is not modified.

c := httpclient.New(
	httpclient.BaseURL(BaseURL),
	httpclient.PersistentRequestOptions(httpclient.RequestParam("apiKey", opts.APIKey)),
	httpclient.RedactQueryParams("apiKey"),
	httpclient.Debug(golog.Default),
)

RedactHeaders adds header names to the list. Authorization, Proxy-Authorization, Cookie and Set-Cookie are always scrubbed, and a password in a URL is masked.

Request and response bodies are not scrubbed. There is no general way to find a secret inside one, so do not send a secret in a body and expect Debug to hide it.

httpclient.RedactURL(u, "apiKey") is available for your own log lines.

πŸ“– Learning HTTP Client

Installation

The only requirement is the Go Programming Language, version 1.27 or newer. The package uses generic methods and encoding/json/v2.

Create a new project
$ mkdir myapp
$ cd myapp
$ go mod init myapp
$ go get github.com/kataras/httpclient
Install on existing project
$ cd myapp
$ go get github.com/kataras/httpclient

Run

$ go mod tidy
$ go run .

Navigate through _examples folder for more.

πŸ“ License

This project is licensed under the MIT License.

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.

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, PersistentRequestOptions,
RateLimit, RateLimitPerMinute, RateLimitFor, RateLimitForPerMinute,
RateLimiter, RateLimiterFor,
Retry, RedactQueryParams, RedactHeaders, JSONOptions, 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 ΒΆ

Constants ΒΆ

This section is empty.

Variables ΒΆ

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

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

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

func Bind[T any](resp *http.Response) (T, error)

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.

It is the generic form of BindResponse.

func BindError ΒΆ added in v0.1.0

func BindError[T any](err error) (T, error)

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".

func BindResponse deprecated

func BindResponse(resp *http.Response, dest any) error

BindResponse consumes the response's body and binds the result to the "dest" pointer, closing the response's body is up to the caller.

Deprecated: use the generic Bind instead, which cannot be handed a value of the wrong kind.

func DecodeError ΒΆ

func DecodeError(err error, destPtr any) error

DecodeError binds a json error to the "destPtr".

Prefer the generic BindError, which returns the decoded value.

func DrainResponseBody ΒΆ added in v0.0.3

func DrainResponseBody(resp *http.Response) error

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 ΒΆ

func GetErrorCode(err error) int

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

func RedactURL(u *url.URL, keys ...string) string

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 ΒΆ

func ExtractError(resp *http.Response) APIError

ExtractError returns the response wrapped inside an APIError. It reads and closes the response body.

func GetError ΒΆ

func GetError(err error) (APIError, bool)

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

func (e APIError) Code() int

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 ΒΆ

func (e APIError) Error() string

Error implements the standard error type.

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 ΒΆ

func New(opts ...Option) *Client

New returns a new HTTP Client. Available options:

  • BaseURL
  • Timeout
  • DialTimeout
  • Transport
  • Handler
  • PersistentRequestOptions
  • RateLimit, RateLimitPerMinute, RateLimiter
  • RateLimitFor, RateLimitForPerMinute, RateLimiterFor
  • Retry
  • RedactQueryParams, RedactHeaders
  • JSONOptions
  • Debug

Look the Client.Do/JSON/... methods to send requests, the Client.BindXXX methods to receive typed responses and the Client.ReadXXX methods to fill a value you already hold.

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) Clone ΒΆ added in v0.0.5

func (c *Client) Clone(opts ...Option) *Client

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 ΒΆ

func (c *Client) DrainResponseBody(resp *http.Response) error

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 ΒΆ

func (c *Client) NewUploader() *Uploader

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 ΒΆ

type DebugLogger interface {
	Debugf(string, ...any)
}

type Limiter ΒΆ added in v0.1.1

type Limiter interface {
	Wait(ctx context.Context) error
}

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

func NewRateLimiter(requestsPerSecond int) Limiter

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

func NewRateLimiterPerMinute(requestsPerMinute int) Limiter

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 ΒΆ

func BaseURL(uri string) Option

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.

func DialTimeout ΒΆ added in v0.0.9

func DialTimeout(timeout time.Duration) Option

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 ΒΆ

func Handler(h http.Handler) Option

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.

func JSONOptions ΒΆ added in v0.1.0

func JSONOptions(opts ...json.Options) Option

JSONOptions sets the encoding/json/v2 options this Client uses to encode request payloads and 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.

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 ΒΆ

func RateLimit(requestsPerSecond int) Option

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

func RateLimitFor(key string, requestsPerSecond int) Option

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

func RateLimitForPerMinute(key string, requestsPerMinute int) Option

RateLimitForPerMinute is RateLimitFor expressed per minute.

func RateLimitPerMinute ΒΆ added in v0.0.11

func RateLimitPerMinute(requestsPerMinute int) Option

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

func RateLimiter(l Limiter) Option

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

func RateLimiterFor(key string, l Limiter) Option

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

func RedactHeaders(names ...string) Option

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

func RedactQueryParams(keys ...string) Option

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 ΒΆ

func Timeout(timeout time.Duration) Option

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

type PlainText interface {
	~string | ~[]byte | ~int | ~int64 | ~float64
}

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 ΒΆ

type RequestOption = func(*http.Request) error

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 ΒΆ

type Uploader struct {
	Writer *multipart.Writer
	// contains filtered or unexported fields
}

Uploader holds the necessary information for upload requests.

Look the Client.NewUploader method.

func (*Uploader) AddField ΒΆ

func (u *Uploader) AddField(key, value string) error

AddField adds a form field to the uploader with the given key.

func (*Uploader) AddFile ΒΆ

func (u *Uploader) AddFile(key, filename string) error

AddFile adds a local form file to the uploader with the given key.

func (*Uploader) AddFileSource ΒΆ

func (u *Uploader) AddFileSource(key, filename string, source io.Reader) error

AddFileSource adds a form file to the uploader with the given key.

func (*Uploader) Upload ΒΆ

func (u *Uploader) Upload(ctx context.Context, method, urlpath string, opts ...RequestOption) (*http.Response, error)

Upload sends the collected form and file data to the server.

Closing the returned response body is up to the caller, see Client.DrainResponseBody.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL