http

package
v1.62.2 Latest Latest
Warning

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

 Go to latest Published: Apr 24, 2024 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

  • Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors. All rights reserved.

  • SPDX-License-Identifier: Apache-2.0

  • Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors. All rights reserved.

  • SPDX-License-Identifier: Apache-2.0

  • Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors. All rights reserved.

  • SPDX-License-Identifier: Apache-2.0

Package http provides a familiar HTTP client interface with various implementations in order to answer common use cases: e.g. need for a robust client (performs retries on server errors with different retry policies depending on configuration), for a fast client which leverages connection pools. For the robust client, it is possible to set its configuration fully but this package also come with a set of preset configuration to answer most usecases e.g. to create a client which performs exponential backoff and listens to `Retry-After` headers, the following can be done: robustClient := NewConfigurableRetryableClient(DefaultRobustHTTPClientConfigurationWithExponentialBackOff()) resp, err := robustClient.Get("https://somehost.com") Whereas to create a client which will only perform 4 retries without backoff, the following can be done: retriableClient := NewConfigurableRetryableClient(DefaultRobustHTTPClientConfiguration()) resp, err := retriableClient.Get("https://somehost.com") It is a thin wrapper over some hashicorp implementations and hence over the standard net/http client library. This makes the client implementations very easy to drop into existing programs in lieu of standard library default client.

  • Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors. All rights reserved.

  • SPDX-License-Identifier: Apache-2.0

  • Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors. All rights reserved.

  • SPDX-License-Identifier: Apache-2.0

  • Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors. All rights reserved.

  • SPDX-License-Identifier: Apache-2.0

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RetryOnError added in v1.34.0 

func RetryOnError(ctx context.Context, logger logr.Logger, retryPolicy *RetryPolicyConfiguration, fn func() error, msgOnRetry string, retriableErr ...error) error

RetryOnError allows the caller to retry fn when the error returned by fn is retriable as in of the type specified by retriableErr. backoff defines the maximum retries and the wait interval between two retries.

Types

type BasicRetryPolicy added in v1.6.0 

type BasicRetryPolicy struct {
	RetryWaitPolicy
}

BasicRetryPolicy defines a basic retry policy i.e. it only waits a constant `min` amount of time between attempts. If enabled, it also looks at the `Retry-After` header in the case of 429/503 HTTP errors (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After).

func (*BasicRetryPolicy) Apply added in v1.6.0 

func (p *BasicRetryPolicy) Apply(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration

type ExponentialBackoffPolicy added in v1.6.0 

type ExponentialBackoffPolicy struct {
	RetryWaitPolicy
}

ExponentialBackoffPolicy defines an exponential backoff retry policy. It is exactly the same as retryablehttp.DefaultBackoff although the `Retry-After` header is checked differently to accept dates as well as time.

func (*ExponentialBackoffPolicy) Apply added in v1.6.0 

func (p *ExponentialBackoffPolicy) Apply(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration

type GenericClient added in v1.7.0 

type GenericClient struct {
	// contains filtered or unexported fields
}

GenericClient is an HTTP client similar to http.Client (in fact, entirely based on it), but with extended capabilities (e.g. Options, Delete and Put methods are defined) to cover most methods defined in HTTP.

func (*GenericClient) Close added in v1.7.0 

func (c *GenericClient) Close() error

func (*GenericClient) Delete added in v1.7.0 

func (c *GenericClient) Delete(url string) (*http.Response, error)

func (*GenericClient) Do added in v1.7.0 

func (c *GenericClient) Do(req *http.Request) (*http.Response, error)

func (*GenericClient) Get added in v1.7.0 

func (c *GenericClient) Get(url string) (*http.Response, error)

func (*GenericClient) Head added in v1.7.0 

func (c *GenericClient) Head(url string) (*http.Response, error)

func (*GenericClient) Options added in v1.7.0 

func (c *GenericClient) Options(url string) (*http.Response, error)

func (*GenericClient) Post added in v1.7.0 

func (c *GenericClient) Post(url, contentType string, rawBody interface{}) (*http.Response, error)

func (*GenericClient) PostForm added in v1.7.0 

func (c *GenericClient) PostForm(url string, data url.Values) (*http.Response, error)

func (*GenericClient) Put added in v1.7.0 

func (c *GenericClient) Put(url string, rawBody interface{}) (*http.Response, error)

func (*GenericClient) StandardClient added in v1.7.0 

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

type HTTPClientConfiguration added in v1.2.0 

type HTTPClientConfiguration struct {
	// MaxConnsPerHost optionally limits the total number of
	// connections per host, including connections in the dialing,
	// active, and idle states. On limit violation, dials will block.
	//
	// Zero means no limit.
	MaxConnsPerHost int `mapstructure:"max_connections_per_host"`
	// MaxIdleConns controls the maximum number of idle (keep-alive)
	// connections across all hosts. Zero means no limit.
	MaxIdleConns int `mapstructure:"max_idle_connections"`
	// MaxIdleConnsPerHost, if non-zero, controls the maximum idle
	// (keep-alive) connections to keep per-host. If zero,
	// DefaultMaxIdleConnsPerHost is used.
	MaxIdleConnsPerHost int `mapstructure:"max_idle_connections_per_host"`
	// IdleConnTimeout is the maximum amount of time an idle
	// (keep-alive) connection will remain idle before closing
	// itself.
	// Zero means no limit.
	IdleConnTimeout time.Duration `mapstructure:"timeout_idle_connection"`
	// TLSHandshakeTimeout specifies the maximum amount of time waiting to
	// wait for a TLS handshake. Zero means no timeout.
	TLSHandshakeTimeout time.Duration `mapstructure:"timeout_tls_handshake"`
	// ExpectContinueTimeout, if non-zero, specifies the amount of
	// time to wait for a server's first response headers after fully
	// writing the request headers if the request has an
	// "Expect: 100-continue" header. Zero means no timeout and
	// causes the body to be sent immediately, without
	// waiting for the server to approve.
	// This time does not include the time to send the request header.
	ExpectContinueTimeout time.Duration `mapstructure:"timeout_expect_continue"`
	// RetryPolicy defines the retry policy to use for the retryable client
	RetryPolicy RetryPolicyConfiguration `mapstructure:"retry_policy"`
}

HTTPClientConfiguration defines the client configuration. It can be used to tweak low level transport parameters in order to adapt the client to your usecase. If unsure about the values to set, use the DefaultHTTPClientConfiguration or FastHTTPClientConfiguration depending on what flow you are dealing with.

func DefaultHTTPClientConfiguration added in v1.2.0 

func DefaultHTTPClientConfiguration() *HTTPClientConfiguration

DefaultHTTPClientConfiguration uses default values similar to https://github.com/hashicorp/go-cleanhttp/blob/6d9e2ac5d828e5f8594b97f88c4bde14a67bb6d2/cleanhttp.go#L23 Similar default values to http.DefaultTransport

func DefaultRobustHTTPClientConfiguration added in v1.6.0 

func DefaultRobustHTTPClientConfiguration() *HTTPClientConfiguration

DefaultRobustHTTPClientConfiguration is similar to DefaultHTTPClientConfiguration but performs basic retry policy on failure.

func DefaultRobustHTTPClientConfigurationWithExponentialBackOff added in v1.6.0 

func DefaultRobustHTTPClientConfigurationWithExponentialBackOff() *HTTPClientConfiguration

DefaultRobustHTTPClientConfigurationWithExponentialBackOff is similar to DefaultHTTPClientConfiguration but performs exponential backoff.

func DefaultRobustHTTPClientConfigurationWithLinearBackOff added in v1.6.0 

func DefaultRobustHTTPClientConfigurationWithLinearBackOff() *HTTPClientConfiguration

DefaultRobustHTTPClientConfigurationWithLinearBackOff is similar to DefaultHTTPClientConfiguration but performs linear backoff.

func DefaultRobustHTTPClientConfigurationWithRetryAfter added in v1.6.0 

func DefaultRobustHTTPClientConfigurationWithRetryAfter() *HTTPClientConfiguration

DefaultRobustHTTPClientConfigurationWithRetryAfter is similar to DefaultRobustHTTPClientConfiguration but considers `Retry-After` header.

func FastHTTPClientConfiguration added in v1.2.0 

func FastHTTPClientConfiguration() *HTTPClientConfiguration

FastHTTPClientConfiguration uses parameter values similar to https://github.com/valyala/fasthttp/blob/81fc96827033a5ee92d8a098ab1cdb9827e1eb8d/client.go the configuration was designed for some high performance edge cases: handle thousands of small to medium requests per seconds and a consistent low millisecond response time. It is, for example, used for checking authentication/authorisation.

func (*HTTPClientConfiguration) Validate added in v1.2.0 

func (cfg *HTTPClientConfiguration) Validate() error

type IClient 

type IClient interface {
	io.Closer
	// Get is a convenience helper for doing simple GET requests.
	Get(url string) (*http.Response, error)
	// Head is a convenience method for doing simple HEAD requests.
	Head(url string) (*http.Response, error)
	// Post is a convenience method for doing simple POST requests.
	Post(url, contentType string, body interface{}) (*http.Response, error)
	// PostForm is a convenience method for doing simple POST operations using
	// pre-filled url.Values form data.
	PostForm(url string, data url.Values) (*http.Response, error)
	// StandardClient returns a standard library *http.Client with a custom Transport layer.
	StandardClient() *http.Client
	// Put performs a PUT request.
	Put(url string, body interface{}) (*http.Response, error)
	// Delete performs a DELETE request.
	Delete(url string) (*http.Response, error)
	// Options performs an OPTIONS request.
	Options(url string) (*http.Response, error)
	// Do performs a generic request.
	Do(req *http.Request) (*http.Response, error)
}

IClient defines an HTTP client similar to http.Client but without shared state with other clients used in the same program. See https://github.com/hashicorp/go-cleanhttp for more details.

func NewConfigurableRetryableClient added in v1.2.0 

func NewConfigurableRetryableClient(cfg *HTTPClientConfiguration) IClient

NewConfigurableRetryableClient creates a new http client which will retry failed requests according to the retry configuration (e.g. no retry, basic retry policy, exponential backoff).

func NewConfigurableRetryableClientFromClient added in v1.57.0 

func NewConfigurableRetryableClientFromClient(cfg *HTTPClientConfiguration, client *http.Client) IClient

NewConfigurableRetryableClientFromClient creates a new http client which will retry failed requests according to the retry configuration (e.g. no retry, basic retry policy, exponential backoff). It also takes a custom client if you need an authenticated client

func NewConfigurableRetryableClientWithLogger added in v1.6.0 

func NewConfigurableRetryableClientWithLogger(cfg *HTTPClientConfiguration, logger logr.Logger) IClient

NewConfigurableRetryableClientWithLogger creates a new http client which will retry failed requests according to the retry configuration (e.g. no retry, basic retry policy, exponential backoff). It is also possible to supply a logger for debug purposes

func NewConfigurableRetryableClientWithLoggerFromClient added in v1.57.0 

func NewConfigurableRetryableClientWithLoggerFromClient(cfg *HTTPClientConfiguration, logger logr.Logger, client *http.Client) IClient

NewConfigurableRetryableClientWithLoggerFromClient creates a new http client which will retry failed requests according to the retry configuration (e.g. no retry, basic retry policy, exponential backoff). It is also possible to supply a logger for debug purposes as well as a custom client if you need an authenticated client

func NewConfigurableRetryableOauthClient added in v1.57.0 

func NewConfigurableRetryableOauthClient(cfg *HTTPClientConfiguration, token string) IClient

NewConfigurableRetryableOauthClient creates a new http client which will retry failed requests according to the retry configuration (e.g. no retry, basic retry policy, exponential backoff) with the authorisation header set to token

func NewConfigurableRetryableOauthClientWithLogger added in v1.57.0 

func NewConfigurableRetryableOauthClientWithLogger(cfg *HTTPClientConfiguration, logger logr.Logger, token string) IClient

NewConfigurableRetryableOauthClientWithLogger creates a new http client which will retry failed requests according to the retry configuration (e.g. no retry, basic retry policy, exponential backoff) with the authorisation header set to token It is also possible to supply a logger for debug purposes

func NewConfigurableRetryableOauthClientWithToken added in v1.57.0 

func NewConfigurableRetryableOauthClientWithToken(cfg *HTTPClientConfiguration, t *oauth2.Token) IClient

NewConfigurableRetryableOauthClientWithToken creates a new http client with an authorisation token which will retry based on the configuration. It takes a full oauth2.Token to give more configuration for the token

func NewConfigurableRetryableOauthClientWithTokenAndLogger added in v1.57.0 

func NewConfigurableRetryableOauthClientWithTokenAndLogger(cfg *HTTPClientConfiguration, logger logr.Logger, t *oauth2.Token) IClient

NewConfigurableRetryableOauthClientWithToken creates a new http client with an authorisation token which will retry based on the configuration. It takes a logger to allow for debugging. It takes a full oauth2.Token to give more configuration for the token

func NewDefaultPooledClient added in v1.2.0 

func NewDefaultPooledClient() IClient

NewDefaultPooledClient returns a new HTTP client with similar default values to http.Client, but with a shared Transport.

func NewFastPooledClient added in v1.2.0 

func NewFastPooledClient() IClient

NewFastPooledClient returns a new HTTP client with similar default values to fast http client https://github.com/valyala/fasthttp.

func NewGenericClient added in v1.7.0 

func NewGenericClient(rawClient *http.Client) IClient

NewGenericClient returns a new HTTP client (GenericClient) based on a standard library client implementation. If the raw client is not provided, it will default to the plain HTTP client (See NewPlainHTTPClient).

func NewPlainHTTPClient added in v1.7.0 

func NewPlainHTTPClient() IClient

NewPlainHTTPClient creates an HTTP client similar to http.DefaultClient but with extended methods and no shared state.

func NewPooledClient added in v1.2.0 

func NewPooledClient(cfg *HTTPClientConfiguration) IClient

NewPooledClient returns a new HTTP client using the configuration passed as argument. Do not use this function for transient clients as it can leak file descriptors over time. Only use this for clients that will be re-used for the same host(s).

func NewRetryableClient 

func NewRetryableClient() IClient

NewRetryableClient creates a new http client which will retry failed requests with exponential backoff. It is based on `retryablehttp` default client

func NewRetryableOauthClient added in v1.57.0 

func NewRetryableOauthClient(token string) IClient

NewRetryableOauthClient creates a new http client with an authorisation token which will retry failed requests with exponential backoff.

func NewRetryableOauthClientWithToken added in v1.57.0 

func NewRetryableOauthClientWithToken(t *oauth2.Token) IClient

NewRetryableOauthClientWithToken creates a new http client with an authorisation token which will retry failed requests with exponential backoff. It takes a full oauth2.Token to give more configuration for the token

type IRetryWaitPolicy added in v1.6.0 

type IRetryWaitPolicy interface {
	// Apply determines the amount of time to wait before the next retry attempt.
	// the time will be comprised between the `min` and `max` value unless other information are retrieved from the server response e.g. `Retry-After` header.
	Apply(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration
}

IRetryWaitPolicy defines the policy which specifies how much wait/sleep should happen between retry attempts.

func BackOffPolicyFactory added in v1.6.0 

func BackOffPolicyFactory(cfg *RetryPolicyConfiguration) (policy IRetryWaitPolicy)

BackOffPolicyFactory generates a backoff policy based on configuration.

func NewBasicRetryPolicy added in v1.6.0 

func NewBasicRetryPolicy(cfg *RetryPolicyConfiguration) IRetryWaitPolicy

NewBasicRetryPolicy creates a BasicRetryPolicy.

func NewExponentialBackoffPolicy added in v1.6.0 

func NewExponentialBackoffPolicy(cfg *RetryPolicyConfiguration) IRetryWaitPolicy

NewExponentialBackoffPolicy creates a ExponentialBackoffPolicy.

func NewLinearBackoffPolicy added in v1.6.0 

func NewLinearBackoffPolicy(cfg *RetryPolicyConfiguration) IRetryWaitPolicy

NewLinearBackoffPolicy creates a LinearBackoffPolicy.

type LinearBackoffPolicy added in v1.6.0 

type LinearBackoffPolicy struct {
	RetryWaitPolicy
}

LinearBackoffPolicy defines a linear backoff retry policy based on the attempt number and with jitter to prevent a thundering herd. It is similar to retryablehttp.LinearJitterBackoff but if enabled, it also looks at the `Retry-After` header in the case of 429/503 HTTP errors (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After).

func (*LinearBackoffPolicy) Apply added in v1.6.0 

func (p *LinearBackoffPolicy) Apply(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration

type PooledClient added in v1.2.0 

type PooledClient struct {
	GenericClient
}

PooledClient is an HTTP client similar to http.Client, but with a shared Transport and different configuration values. It is based on https://github.com/hashicorp/go-cleanhttp which ensures the client configuration is only set for the current use case and not the whole project (i.e. no global variable)

type RetryPolicyConfiguration added in v1.6.0 

type RetryPolicyConfiguration = retry.RetryPolicyConfiguration

RetryPolicyConfiguration was moved to the `retry` module. Nonetheless, it was redefined here to avoid breaking changes

func DefaultBasicRetryPolicyConfiguration added in v1.6.0 

func DefaultBasicRetryPolicyConfiguration() *RetryPolicyConfiguration

DefaultBasicRetryPolicyConfiguration defines a configuration for basic retries i.e. retrying straight after a failure for maximum 4 attempts.

func DefaultExponentialBackoffRetryPolicyConfiguration added in v1.6.0 

func DefaultExponentialBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration

DefaultExponentialBackoffRetryPolicyConfiguration defines a configuration for retries with exponential backoff.

func DefaultLinearBackoffRetryPolicyConfiguration added in v1.6.0 

func DefaultLinearBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration

DefaultLinearBackoffRetryPolicyConfiguration defines a configuration for retries with linear backoff.

func DefaultNoRetryPolicyConfiguration added in v1.6.0 

func DefaultNoRetryPolicyConfiguration() *RetryPolicyConfiguration

DefaultNoRetryPolicyConfiguration defines a configuration for no retry being performed.

func DefaultRobustRetryPolicyConfiguration added in v1.6.0 

func DefaultRobustRetryPolicyConfiguration() *RetryPolicyConfiguration

DefaultRobustRetryPolicyConfiguration defines a configuration for basic retries but considering any `Retry-After` being returned by server.

type RetryWaitPolicy added in v1.6.0 

type RetryWaitPolicy struct {
	ConsiderRetryAfter bool
}

RetryWaitPolicy defines an `abstract` retry wait policy

func NewRetryWaitPolicy added in v1.6.0 

func NewRetryWaitPolicy(cfg *RetryPolicyConfiguration) *RetryWaitPolicy

NewRetryWaitPolicy creates an generic RetryWaitPolicy based on configuration.

type RetryableClient 

type RetryableClient struct {
	// contains filtered or unexported fields
}

RetryableClient is an http client which will retry failed requests according to the retry configuration.

func (*RetryableClient) Close added in v1.2.0 

func (c *RetryableClient) Close() error

func (*RetryableClient) Delete 

func (c *RetryableClient) Delete(url string) (*http.Response, error)

func (*RetryableClient) Do 

func (c *RetryableClient) Do(req *http.Request) (*http.Response, error)

func (*RetryableClient) Get 

func (c *RetryableClient) Get(url string) (*http.Response, error)

func (*RetryableClient) Head 

func (c *RetryableClient) Head(url string) (*http.Response, error)

func (*RetryableClient) Options added in v1.7.0 

func (c *RetryableClient) Options(url string) (*http.Response, error)

func (*RetryableClient) Post 

func (c *RetryableClient) Post(url, contentType string, body interface{}) (*http.Response, error)

func (*RetryableClient) PostForm 

func (c *RetryableClient) PostForm(url string, data url.Values) (*http.Response, error)

func (*RetryableClient) Put 

func (c *RetryableClient) Put(url string, body interface{}) (*http.Response, error)

func (*RetryableClient) StandardClient 

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

Source Files

View all Source files

Directories

Path Synopsis
* Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors.
 * Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors.

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.