client

Documentation

Overview

Package client provides support for sending requests defined by the request package.

Client is a default implementation of the request.Sender interface. Client is based on the standard net/http package and contains retry and tracing/telemetry support. It is easy to implement your custom HTTP client, by implementing request.Sender interface.

Index

• Constants
• func ContextRetryAttempt(ctx context.Context) (int, bool)
• func DefaultTransport() http.RoundTripper
• func HTTP2Transport() http.RoundTripper
• type Client
  • func New() Client
  • func NewMockedClient() (Client, *httpmock.MockTransport)
  • func NewTestClient() Client
  • func (c Client) AndTrace(fn trace.Factory) Client
  • func (c Client) Send(ctx context.Context, reqDef request.HTTPRequest) (res *http.Response, result any, err error)
  • func (c Client) Tracer() otelTrace.Tracer
  • func (c Client) WithBaseURL(baseURLStr string) Client
  • func (c Client) WithHeader(key, value string) Client
  • func (c Client) WithHeaders(headers map[string]string) Client
  • func (c Client) WithRetry(retry RetryConfig) Client
  • func (c Client) WithTelemetry(tracerProvider otelTrace.TracerProvider, ...) Client
  • func (c Client) WithTransport(transport http.RoundTripper) Client
  • func (c Client) WithUserAgent(v string) Client
• type ContextKey
• type DurationSeconds
  • func (d DurationSeconds) MarshalJSON() ([]byte, error)
  • func (d DurationSeconds) String() string
  • func (d *DurationSeconds) UnmarshalJSON(data []byte) (err error)
• type RetryCondition
  • func DefaultRetryCondition() RetryCondition
• type RetryConfig
  • func DefaultRetry() RetryConfig
  • func TestingRetry() RetryConfig
  • func (c RetryConfig) NewBackoff() backoff.BackOff

Constants

const (
	ContentTypeApplicationJSON       = "application/json"
	ContentTypeApplicationJSONRegexp = `^application/([a-zA-Z0-9\.\-]+\+)?json$`
)

const DialTimeout = 3 * time.Second

DialTimeout specifies the default maximum connection initialization time.

const HTTP2PingTimeout = 3 * time.Second

HTTP2PingTimeout is the timeout after which the connection will be closed if a response to Ping is not received.

const HTTP2ReadIdleTimeout = 3 * time.Second

HTTP2ReadIdleTimeout is the timeout after which a health check using ping frame will be carried out.

const HTTP2WriteByteTimeout = 3 * time.Second

HTTP2WriteByteTimeout is the timeout after which the connection will be closed no data can be written to it.

const KeepAlive = 10 * time.Second

KeepAlive specifies the default interval between keep-alive probes.

const MaxConnectionsPerHost = 32

MaxConnectionsPerHost specifies the default maximum number of open connections to a host.

const MaxIdleConnections = 128

MaxIdleConnections specifies the default maximum number of open connections at all.

const RequestTimeout = 30 * time.Second

RequestTimeout - default request timeout.

const ResponseHeaderTimeout = 20 * time.Second

ResponseHeaderTimeout specifies the default amount of time to wait for a server's response headers.

const RetriesCount = 5

RetriesCount - default retries count.

const (
	RetryAttemptContextKey = ContextKey("retryAttempt")
)

const RetryWaitTimeMax = 3 * time.Second

RetryWaitTimeMax - default maximum retry interval.

const RetryWaitTimeStart = 100 * time.Millisecond

RetryWaitTimeStart - default retry interval.

const TLSHandshakeTimeout = 5 * time.Second

TLSHandshakeTimeout specifies the default timeout of TLS handshake.

Functions

func ContextRetryAttempt

func ContextRetryAttempt(ctx context.Context) (int, bool)

func DefaultTransport

func DefaultTransport() http.RoundTripper

DefaultTransport is the default Client transport with reasonable limits.

func HTTP2Transport

func HTTP2Transport() http.RoundTripper

HTTP2Transport forces HTTP2 protocol.

Types

type Client

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

Client is a default and configurable implementation of the Sender interface by Go native http.Client. It supports retry and tracing/telemetry.

func New

func New() Client

New creates new HTTP Client.

func NewMockedClient

func NewMockedClient() (Client, *httpmock.MockTransport)

NewMockedClient creates the Client with mocked HTTP transport.

func NewTestClient

func NewTestClient() Client

NewTestClient creates the Client for tests.

If the TEST_HTTP_CLIENT_VERBOSE environment variable is set to "true", then all HTTP requests and responses are dumped to stdout.

Output may contain unmasked tokens, do not use it in production!

func (Client) AndTrace

func (c Client) AndTrace(fn trace.Factory) Client

AndTrace returns a clone of the Client with Trace hooks added. The last registered hook is executed first.

func (Client) Send

func (c Client) Send(ctx context.Context, reqDef request.HTTPRequest) (res *http.Response, result any, err error)

Send method sends HTTP request and returns HTTP response, it implements the Sender interface.

func (Client) Tracer

func (c Client) Tracer() otelTrace.Tracer

Tracer returns registered tracer, if any.

func (Client) WithBaseURL

func (c Client) WithBaseURL(baseURLStr string) Client

WithBaseURL returns a clone of the Client with base url set.

func (Client) WithHeader

func (c Client) WithHeader(key, value string) Client

WithHeader returns a clone of the Client with common header set.

func (Client) WithHeaders

func (c Client) WithHeaders(headers map[string]string) Client

WithHeaders returns a clone of the Client with common headers set.

func (Client) WithRetry

func (c Client) WithRetry(retry RetryConfig) Client

WithRetry returns a clone of the Client with retry config set.

func (Client) WithTelemetry

func (c Client) WithTelemetry(tracerProvider otelTrace.TracerProvider, meterProvider otelMetric.MeterProvider, opts ...otel.Option) Client

WithTelemetry enables OpenTelemetry tracing and metrics.

func (Client) WithTransport

func (c Client) WithTransport(transport http.RoundTripper) Client

WithTransport returns a clone of the Client with a HTTP transport set.

func (Client) WithUserAgent

func (c Client) WithUserAgent(v string) Client

WithUserAgent returns a clone of the Client with user agent set.

type ContextKey

type ContextKey string

type DurationSeconds

type DurationSeconds time.Duration

DurationSeconds is time.Duration encoded/decoded as number of seconds.

func (DurationSeconds) MarshalJSON

func (d DurationSeconds) MarshalJSON() ([]byte, error)

MarshalJSON implements JSON encoding.

func (DurationSeconds) String

func (d DurationSeconds) String() string

func (*DurationSeconds) UnmarshalJSON

func (d *DurationSeconds) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON implements JSON decoding.

type RetryCondition

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

RetryCondition defines which responses should retry.

func DefaultRetryCondition

func DefaultRetryCondition() RetryCondition

DefaultRetryCondition retries on common network and HTTP errors.

type RetryConfig

type RetryConfig struct {
	Condition           RetryCondition
	Count               int
	TotalRequestTimeout time.Duration
	WaitTimeStart       time.Duration
	WaitTimeMax         time.Duration
}

RetryConfig configures Client retries.

func DefaultRetry

func DefaultRetry() RetryConfig

DefaultRetry returns a default RetryConfig.

func TestingRetry

func TestingRetry() RetryConfig

TestingRetry - fast retry for use in tests.

func (RetryConfig) NewBackoff

func (c RetryConfig) NewBackoff() backoff.BackOff

NewBackoff returns an exponential backoff for HTTP retries.