api

Documentation

Index

• Constants
• Variables
• func ParseBasicAuth(auth string) (username, password string, ok bool)
• type Client
  • func New(opts ...Opt) (*Client, error)
  • func (c *Client) Authorization() string
  • func (c *Client) Client() *http.Client
  • func (c *Client) Clone(opts ...Opt) (*Client, error)
  • func (c *Client) Do(ctx context.Context, req *http.Request, v interface{}) (*http.Response, error)
  • func (c *Client) NewRequest(ctx context.Context, method, urlStr string, body interface{}, opts ...Opt) (*http.Request, error)
• type DurationObserver
• type ErrorResponse
  • func (e ErrorResponse) Error() string
• type Marshaler
• type NotifyFunc
• type Opt
  • func WithAdditionalHeaders(h http.Header) Opt
  • func WithAuthorization(key string) Opt
  • func WithBackoffInitialInterval(d time.Duration) Opt
  • func WithBackoffMaxElapsedTime(d time.Duration) Opt
  • func WithBackoffMaxInterval(d time.Duration) Opt
  • func WithBaseURL(rawurl string) Opt
  • func WithBasicAuth(username, password string) Opt
  • func WithDurationObserver(o DurationObserver) Opt
  • func WithHTTPClient(cli *http.Client) Opt
  • func WithInsecure(insecure bool) Opt
  • func WithLogger(l *log.Logger) Opt
  • func WithMarshaler(f Marshaler) Opt
  • func WithMaxConnsPerHost(n int) Opt
  • func WithMediaType(mt string) Opt
  • func WithNotifyFunc(f NotifyFunc) Opt
  • func WithRateLimit(hertz float64, burst int) Opt
  • func WithRateLimiter(lim RateLimiter) Opt
  • func WithRequestCounter(f RequestCounter) Opt
  • func WithRetryOn(f RetryOnFunc) Opt
  • func WithUnmarshaler(f Unmarshaler) Opt
  • func WithVerbosity(verbosity int) Opt
• type RateLimiter
• type RequestCounter
• type RetryOnFunc
  • func ReturnCode(want []int) RetryOnFunc
• type Unmarshaler

Constants

const (
	ModeInfo = iota // This is the default.
	ModeDebug
	ModeTrace
)

Logging modes.

Variables

var RetryOn429 = func(resp *http.Response, _ error) bool {
	return resp != nil && resp.StatusCode == http.StatusTooManyRequests
}

RetryOn429 retries on HTTP 429 status code only and is the default.

Functions

func ParseBasicAuth

func ParseBasicAuth(auth string) (username, password string, ok bool)

ParseBasicAuth returns the username and password from a basic authentication string and ok if there was no error.

Types

type Client

type Client struct {
	BaseURL   *url.URL // Base URL.
	UserAgent string   // User-Agent to use in HTTP request headers.
	// contains filtered or unexported fields
}

Client is a generic HTTP API Client.

func New

func New(opts ...Opt) (*Client, error)

New returns a new HTTP client instance.

func (*Client) Authorization

func (c *Client) Authorization() string

Authorization returns the raw authorization string used for HTTP calls.

func (*Client) Client

func (c *Client) Client() *http.Client

Client returns the configured HTTP client.

func (*Client) Clone

func (c *Client) Clone(opts ...Opt) (*Client, error)

Clone returns a new copy of the client with the options applied.

func (*Client) Do

func (c *Client) Do(ctx context.Context, req *http.Request, v interface{}) (*http.Response, error)

Do actually sends the request and stores the response body in v. If `v` is an `io.Writer` the contents of the response body are copied without parsing.

func (*Client) NewRequest

func (c *Client) NewRequest(ctx context.Context, method, urlStr string, body interface{}, opts ...Opt) (*http.Request, error)

NewRequest prepares a new request for sending over to the server. Specify relative urls always without the preceding slash. 'body' is encoded and sent as the request body. If body is an io.Reader its content is copied without parsing.

type DurationObserver

type DurationObserver interface {
	Start()
	ObserveDuration()
}

DurationObserver observes how long requests take. This is intended primarily for Prometheus.

type ErrorResponse

type ErrorResponse struct {
	Response *http.Response
	RawBody  []byte
}

ErrorResponse holds the response in case of an API error.

func (ErrorResponse) Error

func (e ErrorResponse) Error() string

type Marshaler

type Marshaler func(v interface{}) ([]byte, error)

Marshaler encodes API requests.

type NotifyFunc

type NotifyFunc func(error, time.Duration)

NotifyFunc gets called on each retry with the next interval before the client retries.

type Opt

type Opt func(c *Client) error

Opt is an option for the client.

func WithAdditionalHeaders

func WithAdditionalHeaders(h http.Header) Opt

WithAdditionalHeaders sets additional headers for each request. Existing headers are not overwritten.

func WithAuthorization

func WithAuthorization(key string) Opt

WithAuthorization sets the Authorization header for this client. The header is injected on each request after setting it.

func WithBackoffInitialInterval

func WithBackoffInitialInterval(d time.Duration) Opt

WithBackoffInitialInterval sets the initial backoff interval.

func WithBackoffMaxElapsedTime

func WithBackoffMaxElapsedTime(d time.Duration) Opt

WithBackoffMaxElapsedTime sets the maximum time before giving up.

func WithBackoffMaxInterval

func WithBackoffMaxInterval(d time.Duration) Opt

WithBackoffMaxInterval sets the maximum backoff interval.

func WithBaseURL

func WithBaseURL(rawurl string) Opt

WithBaseURL sets the base url for the client.

func WithBasicAuth

func WithBasicAuth(username, password string) Opt

WithBasicAuth sets basic auth headers for the request. Mutually exclusive with WithAuthorization.

func WithDurationObserver

func WithDurationObserver(o DurationObserver) Opt

WithDurationObserver sets a metric to be observed.

func WithHTTPClient

func WithHTTPClient(cli *http.Client) Opt

WithHTTPClient sets the http.Client on the API client.

func WithInsecure

func WithInsecure(insecure bool) Opt

WithInsecure controls if TLS server certs should be verified. Default is false (= secure mode, TLS will be checked).

func WithLogger

func WithLogger(l *log.Logger) Opt

WithLogger sets the logger for this client to use. Default is to log to stdout with the standard logger.

func WithMarshaler

func WithMarshaler(f Marshaler) Opt

WithMarshaler set the data marshaler for HTTP requests.

func WithMaxConnsPerHost

func WithMaxConnsPerHost(n int) Opt

WithMaxConnsPerHost limits the maximum connections opened per target host. This resets the internal HTTP client.

func WithMediaType

func WithMediaType(mt string) Opt

WithMediaType sets the content and accepted media type (Content-type and Accept headers).

func WithNotifyFunc

func WithNotifyFunc(f NotifyFunc) Opt

WithNotifyFunc sets the function to call on each request retry.

func WithRateLimit

func WithRateLimit(hertz float64, burst int) Opt

WithRateLimit sets the rate limit explicitly.

func WithRateLimiter

func WithRateLimiter(lim RateLimiter) Opt

WithRateLimiter sets an existing rate limiter on the client.

func WithRequestCounter

func WithRequestCounter(f RequestCounter) Opt

WithRequestCounter sets the request counter. All requests, even retries are counted.

func WithRetryOn

func WithRetryOn(f RetryOnFunc) Opt

WithRetryOn sets the func deciding on which status code we should retry the original request.

func WithUnmarshaler

func WithUnmarshaler(f Unmarshaler) Opt

WithUnmarshaler set the data unmarshaler for HTTP responses.

func WithVerbosity

func WithVerbosity(verbosity int) Opt

WithVerbosity sets the logging verbosity.

type RateLimiter

type RateLimiter interface {
	Wait(context.Context) error // Call should block until token is available.
}

RateLimiter rate-limits stuff.

type RequestCounter

type RequestCounter func(*http.Response)

RequestCounter counts requests. Primarily for use with Prometheus.

type RetryOnFunc

type RetryOnFunc func(*http.Response, error) bool

RetryOnFunc received an HTTP response and an error in case the request failed. If it returns true, the request is retried later based on the client's backoff policy.

func ReturnCode

func ReturnCode(want []int) RetryOnFunc

ReturnCode creates functions to use with WithRetryOn.

type Unmarshaler

type Unmarshaler func(data []byte, v interface{}) error

Unmarshaler decodes API responses.