retriable

Documentation

Index

• Constants
• func PropagateHeadersFromRequest(ctx context.Context, r *http.Request, headers ...string) context.Context
• func WithHeaders(ctx context.Context, headers map[string]string) context.Context
• type Client
  • func New(opts ...ClientOption) *Client
  • func (c *Client) AddHeader(header, value string) *Client
  • func (c *Client) DecodeResponse(resp *http.Response, body interface{}) (http.Header, int, error)
  • func (c *Client) Do(r *http.Request) (*http.Response, error)
  • func (c *Client) Head(ctx context.Context, hosts []string, path string) (http.Header, int, error)
  • func (c *Client) Request(ctx context.Context, method string, hosts []string, path string, ...) (http.Header, int, error)
  • func (c *Client) WithDNSServer(dns string) *Client
  • func (c *Client) WithHeaders(headers map[string]string) *Client
  • func (c *Client) WithName(name string) *Client
  • func (c *Client) WithPolicy(policy *Policy) *Client
  • func (c *Client) WithTLS(tlsConfig *tls.Config) *Client
  • func (c *Client) WithTimeout(timeout time.Duration) *Client
  • func (c *Client) WithTransport(transport http.RoundTripper) *Client
• type ClientOption
  • func WithDNSServer(dns string) ClientOption
  • func WithName(name string) ClientOption
  • func WithPolicy(policy *Policy) ClientOption
  • func WithTLS(tlsConfig *tls.Config) ClientOption
  • func WithTimeout(timeout time.Duration) ClientOption
  • func WithTransport(transport http.RoundTripper) ClientOption
• type GenericHTTP
• type Policy
  • func NewDefaultPolicy() *Policy
  • func (p *Policy) ShouldRetry(r *http.Request, resp *http.Response, err error, retries int) (bool, time.Duration, string)
• type ReaderFunc
• type Request
  • func NewRequest(method, url string, rawBody io.ReadSeeker) (*Request, error)
  • func (r *Request) AddHeader(header, value string) *Request
  • func (r *Request) WithHeaders(headers map[string]string) *Request
• type Requestor
• type ShouldRetry

Constants

const (
	// Success returned when request succeeded
	Success = "success"
	// NotFound returned when request returned 404
	NotFound = "not-found"
	// LimitExceeded returned when retry limit exceeded
	LimitExceeded = "limit-exceeded"
	// DeadlineExceeded returned when request was timed out
	DeadlineExceeded = "deadline"
	// Cancelled returned when request was cancelled
	Cancelled = "cancelled"
	// NonRetriableError returned when non-retriable error occured
	NonRetriableError = "non-retriable"
)

Functions

func PropagateHeadersFromRequest

func PropagateHeadersFromRequest(ctx context.Context, r *http.Request, headers ...string) context.Context

PropagateHeadersFromRequest will set specified headers in the context, if present in the request

func WithHeaders

func WithHeaders(ctx context.Context, headers map[string]string) context.Context

WithHeaders returns a copy of parent with the provided headers set

Types

type Client

type Client struct {
	Name   string
	Policy *Policy // Rery policy for http requests
	// contains filtered or unexported fields
}

Client is custom implementation of http.Client

func New

func New(opts ...ClientOption) *Client

New creates a new Client

func (*Client) AddHeader

func (c *Client) AddHeader(header, value string) *Client

AddHeader adds additional header to the request

func (*Client) DecodeResponse

func (c *Client) DecodeResponse(resp *http.Response, body interface{}) (http.Header, int, error)

DecodeResponse will look at the http response, and map it back to either the body parameters, or to an error [retrying rate limit errors should be done before this]

func (*Client) Do

func (c *Client) Do(r *http.Request) (*http.Response, error)

Do wraps calling an HTTP method with retries.

func (*Client) Head

func (c *Client) Head(ctx context.Context, hosts []string, path string) (http.Header, int, error)

Head makes HEAD request against the specified hosts. The supplied hosts are tried in order until one succeeds.

hosts should include all the protocol/host/port preamble, e.g. https://foo.bar:3444 path should be an absolute URI path, i.e. /foo/bar/baz

func (*Client) Request

func (c *Client) Request(ctx context.Context, method string, hosts []string, path string, requestBody interface{}, responseBody interface{}) (http.Header, int, error)

Request sends request to the specified hosts. The supplied hosts are tried in order until one succeeds. It will decode the response payload into the supplied body parameter. It returns the HTTP headers, status code, and an optional error. For responses with status codes >= 300 it will try and convert the response into a Go error. If configured, this call will apply retry logic.

hosts should include all the protocol/host/port preamble, e.g. https://foo.bar:3444 path should be an absolute URI path, i.e. /foo/bar/baz requestBody can be io.Reader, []byte, or an object to be JSON encoded responseBody can be io.Writer, or a struct to decode JSON into.

func (*Client) WithDNSServer

func (c *Client) WithDNSServer(dns string) *Client

WithDNSServer modifies DNS server. dns must be specified in <host>:<port> format

func (*Client) WithHeaders

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

WithHeaders adds additional headers to the request

func (*Client) WithName

func (c *Client) WithName(name string) *Client

WithName modifies client's name for logging purposes.

func (*Client) WithPolicy

func (c *Client) WithPolicy(policy *Policy) *Client

WithPolicy modifies retriable policy.

func (*Client) WithTLS

func (c *Client) WithTLS(tlsConfig *tls.Config) *Client

WithTLS modifies TLS configuration.

func (*Client) WithTimeout

func (c *Client) WithTimeout(timeout time.Duration) *Client

WithTimeout modifies HTTP client timeout.

func (*Client) WithTransport

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

WithTransport modifies HTTP Transport configuration.

type ClientOption

type ClientOption interface {
	// contains filtered or unexported methods
}

A ClientOption modifies the default behavior of Client.

func WithDNSServer

func WithDNSServer(dns string) ClientOption

WithDNSServer is a ClientOption that allows to use custom dns server for resolution dns server must be specified in <host>:<port> format

retriable.New(retriable.WithDNSServer(dns))

This option cannot be provided for constructors which produce result objects. Note that WithDNSServer applies changes to http client Transport object and hence if used in conjuction with WithTransport method, WithDNSServer should be called after WithTransport is called.

retriable.New(retriable.WithTransport(t).WithDNSServer(dns))

func WithName

func WithName(name string) ClientOption

WithName is a ClientOption that specifies client's name for logging purposes.

retriable.New(retriable.WithName("tlsclient"))

This option cannot be provided for constructors which produce result objects.

func WithPolicy

func WithPolicy(policy *Policy) ClientOption

WithPolicy is a ClientOption that specifies retriable policy.

retriable.New(retriable.WithPolicy(p))

This option cannot be provided for constructors which produce result objects.

func WithTLS

func WithTLS(tlsConfig *tls.Config) ClientOption

WithTLS is a ClientOption that specifies TLS configuration.

retriable.New(retriable.WithTLS(t))

This option cannot be provided for constructors which produce result objects.

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout is a ClientOption that specifies HTTP client timeout.

retriable.New(retriable.WithTimeout(t))

This option cannot be provided for constructors which produce result objects.

func WithTransport

func WithTransport(transport http.RoundTripper) ClientOption

WithTransport is a ClientOption that specifies HTTP Transport configuration.

retriable.New(retriable.WithTransport(t))

This option cannot be provided for constructors which produce result objects.

type GenericHTTP

type GenericHTTP interface {
	// Request sends request to the specified hosts.
	// The supplied hosts are tried in order until one succeeds.
	// It will decode the response payload into the supplied body parameter.
	// It returns the HTTP headers, status code, and an optional error.
	// For responses with status codes >= 300 it will try and convert the response
	// into a Go error.
	// If configured, this call will apply retry logic.
	//
	// hosts should include all the protocol/host/port preamble, e.g. https://foo.bar:3444
	// path should be an absolute URI path, i.e. /foo/bar/baz
	// requestBody can be io.Reader, []byte, or an object to be JSON encoded
	// responseBody can be io.Writer, or a struct to decode JSON into.
	Request(ctx context.Context, method string, hosts []string, path string, requestBody interface{}, responseBody interface{}) (http.Header, int, error)

	// Head makes HEAD request against the specified hosts.
	// The supplied hosts are tried in order until one succeeds.
	//
	// hosts should include all the protocol/host/port preamble, e.g. https://foo.bar:3444
	// path should be an absolute URI path, i.e. /foo/bar/baz
	Head(ctx context.Context, hosts []string, path string) (http.Header, int, error)
}

GenericHTTP defines a number of generalized HTTP request handling wrappers

type Policy

type Policy struct {

	// Retries specifies a map of HTTP Status code to ShouldRetry function,
	// 0 status code indicates a connection related error (network, TLS, DNS etc.)
	Retries map[int]ShouldRetry

	// Maximum number of retries.
	TotalRetryLimit int

	RequestTimeout time.Duration
}

Policy represents the retriable policy

func NewDefaultPolicy

func NewDefaultPolicy() *Policy

NewDefaultPolicy returns default policy

func (*Policy) ShouldRetry

func (p *Policy) ShouldRetry(r *http.Request, resp *http.Response, err error, retries int) (bool, time.Duration, string)

ShouldRetry returns if connection should be retried

type ReaderFunc

type ReaderFunc func() (io.Reader, error)

ReaderFunc is the type of function that can be given natively to NewRequest

type Request

type Request struct {

	// Embed an HTTP request directly. This makes a *Request act exactly
	// like an *http.Request so that all meta methods are supported.
	*http.Request
	// contains filtered or unexported fields
}

Request wraps the metadata needed to create HTTP requests.

func NewRequest

func NewRequest(method, url string, rawBody io.ReadSeeker) (*Request, error)

NewRequest creates a new wrapped request.

func (*Request) AddHeader

func (r *Request) AddHeader(header, value string) *Request

AddHeader adds additional header to the request

func (*Request) WithHeaders

func (r *Request) WithHeaders(headers map[string]string) *Request

WithHeaders adds additional headers to the request

type Requestor

type Requestor interface {
	Do(r *http.Request) (*http.Response, error)
}

Requestor defines interface to make HTTP calls

type ShouldRetry

type ShouldRetry func(r *http.Request, resp *http.Response, err error, retries int) (bool, time.Duration, string)

ShouldRetry specifies a policy for handling retries. It is called following each request with the response, error values returned by the http.Client and the number of already made retries. If ShouldRetry returns false, the Client stops retrying and returns the response to the caller. The Client will close any response body when retrying, but if the retriable is aborted it is up to the caller to properly close any response body before returning.