Package transport

import "bitbucket.org/atlassian/transport"

Overview
Index

Overview

Index

func New(opts ...Option) *http.Transport
func NewHeader(provider HeaderProvider) func(http.RoundTripper) http.RoundTripper
func NewHedger(backoffPolicy BackoffPolicy) func(http.RoundTripper) http.RoundTripper
func NewRetrier(backoffPolicy BackoffPolicy, retryPolicies ...RetryPolicy) func(http.RoundTripper) http.RoundTripper
func OptionDefaultTransport(t *http.Transport) *http.Transport
type BackoffPolicy
func NewFixedBackoffPolicy(wait time.Duration) BackoffPolicy
func NewPercentJitteredBackoffPolicy(wrapped BackoffPolicy, jitterPercent float64) BackoffPolicy
type Backoffer
type Chain
func (c Chain) Apply(base http.RoundTripper) http.RoundTripper
func (c Chain) ApplyFactory(base Factory) Factory
type Decorator
type Factory
func NewFactory(opts ...Option) Factory
func NewRecyclerFactory(factory Factory, opts ...RecycleOption) Factory
func NewRotatorFactory(factory Factory, opts ...RotatorOption) Factory
type FixedBackoffer
func (b *FixedBackoffer) Backoff(*http.Request, *http.Response, error) time.Duration
type Header
func (c *Header) RoundTrip(r *http.Request) (*http.Response, error)
type HeaderProvider
type Hedger
func (c *Hedger) RoundTrip(r *http.Request) (*http.Response, error)
type LimitedRetrier
func (r *LimitedRetrier) Request(req *http.Request) *http.Request
func (r *LimitedRetrier) Retry(req *http.Request, resp *http.Response, e error) bool
type Option
func OptionDial(dial func(network, addr string) (net.Conn, error)) Option
func OptionDialContext(dialCtx func(ctx context.Context, network, addr string) (net.Conn, error)) Option
func OptionDialTLS(dial func(network, addr string) (net.Conn, error)) Option
func OptionDisableCompression(disabled bool) Option
func OptionDisableKeepAlives(disabled bool) Option
func OptionExpectContinueTimeout(timeout time.Duration) Option
func OptionIdleConnTimeout(timeout time.Duration) Option
func OptionMaxIdleConns(max int) Option
func OptionMaxIdleConnsPerHost(max int) Option
func OptionMaxResponseHeaderBytes(max int64) Option
func OptionProxy(proxy func(*http.Request) (*url.URL, error)) Option
func OptionProxyConnectHeader(header http.Header) Option
func OptionResponseHeaderTimeout(timeout time.Duration) Option
func OptionTLSClientConfig(config *tls.Config) Option
func OptionTLSHandshakeTimeout(timeout time.Duration) Option
func OptionTLSNextProto(next map[string]func(authority string, c *tls.Conn) http.RoundTripper) Option
type PercentJitteredBackoffer
func (b *PercentJitteredBackoffer) Backoff(r *http.Request, response *http.Response, e error) time.Duration
type RecycleOption
func RecycleOptionChannel(signal chan struct{}) RecycleOption
func RecycleOptionMaxUsage(max int) RecycleOption
func RecycleOptionTTL(ttl time.Duration) RecycleOption
func RecycleOptionTTLJitter(jitter time.Duration) RecycleOption
type Recycler
func NewRecycler(factory Factory, opts ...RecycleOption) *Recycler
func (c *Recycler) RoundTrip(r *http.Request) (*http.Response, error)
type Requester
type Retrier
type Retry
func (c *Retry) RoundTrip(r *http.Request) (*http.Response, error)
type RetryPolicy
func NewLimitedRetryPolicy(limit int, policies ...RetryPolicy) RetryPolicy
func NewStatusCodeRetryPolicy(codes ...int) RetryPolicy
func NewTimeoutRetryPolicy(timeout time.Duration) RetryPolicy
type Rotator
func NewRotator(factory Factory, opts ...RotatorOption) *Rotator
func (c *Rotator) RoundTrip(r *http.Request) (*http.Response, error)
type RotatorOption
func RotatorOptionInstances(number int) RotatorOption
type RoundTripperFunc
func (d RoundTripperFunc) RoundTrip(r *http.Request) (*http.Response, error)
type StatusCodeRetrier
func (r *StatusCodeRetrier) Retry(req *http.Request, resp *http.Response, e error) bool
type TimeoutRetrier
func (r *TimeoutRetrier) Request(req *http.Request) *http.Request
func (r *TimeoutRetrier) Retry(req *http.Request, resp *http.Response, e error) bool

Package files

decorator.go func.go header.go hedger.go recycle.go retry.go rotate.go transport.go

func New

func New(opts ...Option) *http.Transport

New applies the given options to a Transport and returns it.

func NewHeader

func NewHeader(provider HeaderProvider) func(http.RoundTripper) http.RoundTripper

NewHeader wraps a transport in order to include custom headers.

func NewHedger

func NewHedger(backoffPolicy BackoffPolicy) func(http.RoundTripper) http.RoundTripper

NewHedger configures a RoundTripper decorator to perform some number of hedged requests.

func NewRetrier

func NewRetrier(backoffPolicy BackoffPolicy, retryPolicies ...RetryPolicy) func(http.RoundTripper) http.RoundTripper

NewRetrier configures a RoundTripper decorator to perform some number of retries.

func OptionDefaultTransport

func OptionDefaultTransport(t *http.Transport) *http.Transport

OptionDefaultTransport configures a transport to match the http.DefaultTransport.

type BackoffPolicy

BackoffPolicy is a factory that generates a Backoffer.

type BackoffPolicy func() Backoffer

func NewFixedBackoffPolicy

func NewFixedBackoffPolicy(wait time.Duration) BackoffPolicy

NewFixedBackoffPolicy generates a BackoffPolicy that always returns the same value.

func NewPercentJitteredBackoffPolicy

func NewPercentJitteredBackoffPolicy(wrapped BackoffPolicy, jitterPercent float64) BackoffPolicy

NewPercentJitteredBackoffPolicy wraps any backoff policy and applies a percentage based jitter to the original policy's value. The percentage float should be between 0 and 1. The jitter will be applied as a positive and negative value equally.

type Backoffer

Backoffer determines how much time to wait in between automated retires.

type Backoffer interface {
    Backoff(*http.Request, *http.Response, error) time.Duration
}

type Chain

Chain is an ordered collection of Decorators.

type Chain []Decorator

func (Chain) Apply

func (c Chain) Apply(base http.RoundTripper) http.RoundTripper

Apply wraps the given RoundTripper with the Decorator chain.

func (Chain) ApplyFactory

func (c Chain) ApplyFactory(base Factory) Factory

ApplyFactory wraps the given Factory such that all new instances produced will be decorated with the contents of the chain.

type Decorator

Decorator is a named type for any function that takes a RoundTripper and returns a RoundTripper.

type Decorator func(http.RoundTripper) http.RoundTripper

type Factory

Factory is any function that takes no arguments and returns a Transport.

type Factory func() http.RoundTripper

func NewFactory

func NewFactory(opts ...Option) Factory

NewFactory returns a Factory that is bound to the given Option set.

func NewRecyclerFactory

func NewRecyclerFactory(factory Factory, opts ...RecycleOption) Factory

NewRecyclerFactory is a counterpart for NewRecycler that generates a Factory function for use with other decorators.

func NewRotatorFactory

func NewRotatorFactory(factory Factory, opts ...RotatorOption) Factory

NewRotatorFactory is a counterpart for NewRotator that generates a Factory function for use with other decorators.

type FixedBackoffer

FixedBackoffer signals the client to wait for a static amount of time.

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

func (*FixedBackoffer) Backoff

func (b *FixedBackoffer) Backoff(*http.Request, *http.Response, error) time.Duration

Backoff for a static amount of time.

Header is a decorator that injects a header value into every request.

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

func (c *Header) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip annotates the outgoing request and calls the wrapped Client.

type HeaderProvider

HeaderProvider is mapping function that generates the required header name and value from an outgoing request.

type HeaderProvider func(*http.Request) (headerName string, headerValue string)

type Hedger

Hedger is a wrapper that fans out a new request at each time interval defined by the backoff policy, and returns the first response received. For latency-based retries, this will often be a better approach than a "stop-and-retry" policy (such as the TimeoutRetrier). The hedging decorator allows for a worst case request to take up to a maximum configurable timeout, while pessimistically creating new requests before the timeout is reached.

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

func (*Hedger) RoundTrip

func (c *Hedger) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip executes a new request at each time interval defined by the backoff policy, and returns the first response received.

type LimitedRetrier

LimitedRetrier wraps a series of retry policies in a hard upper limit.

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

func (*LimitedRetrier) Request

func (r *LimitedRetrier) Request(req *http.Request) *http.Request

Request implements Requester by calling the wrapped Request methods where needed.

func (*LimitedRetrier) Retry

func (r *LimitedRetrier) Retry(req *http.Request, resp *http.Response, e error) bool

Retry the request based on the wrapped policies until the limit is reached. Once the limit is reached then this method always returns false.

type Option

Option is a function that either modifies or generates a new Transport.

type Option func(*http.Transport) *http.Transport

func OptionDial

func OptionDial(dial func(network, addr string) (net.Conn, error)) Option

OptionDial installs a custom Dial configuration in the Transport.

func OptionDialContext

func OptionDialContext(dialCtx func(ctx context.Context, network, addr string) (net.Conn, error)) Option

OptionDialContext installs a custom DialContext configuration in the Transport.

func OptionDialTLS

func OptionDialTLS(dial func(network, addr string) (net.Conn, error)) Option

OptionDialTLS installs a custom DialTLS configuration in the Transport.

func OptionDisableCompression

func OptionDisableCompression(disabled bool) Option

OptionDisableCompression installs a custom DisableCompression option in the Transport.

func OptionDisableKeepAlives

func OptionDisableKeepAlives(disabled bool) Option

OptionDisableKeepAlives installs a custom DisableKeepAlives option in the Transport.

func OptionExpectContinueTimeout

func OptionExpectContinueTimeout(timeout time.Duration) Option

OptionExpectContinueTimeout installs a custom ExpectContinueTimeout option in the Transport.

func OptionIdleConnTimeout

func OptionIdleConnTimeout(timeout time.Duration) Option

OptionIdleConnTimeout installs a custom IdleConnTimeout option in the Transport.

func OptionMaxIdleConns

func OptionMaxIdleConns(max int) Option

OptionMaxIdleConns installs a custom MaxIdleConns option in the Transport.

func OptionMaxIdleConnsPerHost

func OptionMaxIdleConnsPerHost(max int) Option

OptionMaxIdleConnsPerHost installs a custom MaxIdleConnsPerHost option in the Transport.

func OptionMaxResponseHeaderBytes

func OptionMaxResponseHeaderBytes(max int64) Option

OptionMaxResponseHeaderBytes installs a custom MaxResponseHeaderBytes option in the Transport.

func OptionProxy

func OptionProxy(proxy func(*http.Request) (*url.URL, error)) Option

OptionProxy installs a custom Proxy configuration in the Transport.

func OptionProxyConnectHeader

func OptionProxyConnectHeader(header http.Header) Option

OptionProxyConnectHeader installs a custom ProxyConnectHeader option in the Transport.

func OptionResponseHeaderTimeout

func OptionResponseHeaderTimeout(timeout time.Duration) Option

OptionResponseHeaderTimeout installs a custom ResponseHeaderTimeout option in the Transport.

func OptionTLSClientConfig

func OptionTLSClientConfig(config *tls.Config) Option

OptionTLSClientConfig installs a custom TLSClientConfig in the Transport.

func OptionTLSHandshakeTimeout

func OptionTLSHandshakeTimeout(timeout time.Duration) Option

OptionTLSHandshakeTimeout installs a custom TLSHandshakeTimeout in the Transport.

func OptionTLSNextProto

func OptionTLSNextProto(next map[string]func(authority string, c *tls.Conn) http.RoundTripper) Option

OptionTLSNextProto installs a custom TLSNextProto option in the Transport.

type PercentJitteredBackoffer

PercentJitteredBackoffer adjusts the backoff time by a random amount within N percent of the duration to help with thundering herds.

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

func (*PercentJitteredBackoffer) Backoff

func (b *PercentJitteredBackoffer) Backoff(r *http.Request, response *http.Response, e error) time.Duration

Backoff for a jittered amount.

type RecycleOption

RecycleOption is a configuration for the Recycler decorator

type RecycleOption func(*Recycler) *Recycler

func RecycleOptionChannel

func RecycleOptionChannel(signal chan struct{}) RecycleOption

RecycleOptionChannel configures the recycler to rotate based on input from a channel.

func RecycleOptionMaxUsage

func RecycleOptionMaxUsage(max int) RecycleOption

RecycleOptionMaxUsage configures the recycler to rotate Transports after a number of uses.

func RecycleOptionTTL

func RecycleOptionTTL(ttl time.Duration) RecycleOption

RecycleOptionTTL configures the recycler to rotate Transports on an interval.

func RecycleOptionTTLJitter

func RecycleOptionTTLJitter(jitter time.Duration) RecycleOption

RecycleOptionTTLJitter adds a randomised jitter to the TTL that is plus or minus the duration value given.

type Recycler

Recycler is a decorator that discards and regenerates the transport after a given set of triggers.

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

func NewRecycler

func NewRecycler(factory Factory, opts ...RecycleOption) *Recycler

NewRecycler uses the given factory as a source and recycles the transport based on the options given.

func (*Recycler) RoundTrip

func (c *Recycler) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip applies the discard and regenerate policy.

type Requester

Requester can be implemented if the Retrier needs to manipulate the request or request context before it is executed.

type Requester interface {
    Request(*http.Request) *http.Request
}

type Retrier

Retrier determines whether or not the transport will automatically retry a request.

type Retrier interface {
    Retry(*http.Request, *http.Response, error) bool
}

type Retry

Retry is a wrapper for applying various retry policies to requests.

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

func (*Retry) RoundTrip

func (c *Retry) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip executes a request and applies one or more retry policies.

type RetryPolicy

RetryPolicy is a factory that generates a Retrier.

type RetryPolicy func() Retrier

func NewLimitedRetryPolicy

func NewLimitedRetryPolicy(limit int, policies ...RetryPolicy) RetryPolicy

NewLimitedRetryPolicy wraps a series of retry policies in an upper limit.

func NewStatusCodeRetryPolicy

func NewStatusCodeRetryPolicy(codes ...int) RetryPolicy

NewStatusCodeRetryPolicy generates a RetryPolicy that retries on specified status codes in the HTTP response.

func NewTimeoutRetryPolicy

func NewTimeoutRetryPolicy(timeout time.Duration) RetryPolicy

NewTimeoutRetryPolicy generates a RetryPolicy that ends a request after a given timeout duration and tries again.

type Rotator

Rotator contains multiple instances of a RoundTripper and rotates through them per-request. This is useful when dealing with HTTP/2 in situations where more than one TCP connection per host is required.

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

func NewRotator

func NewRotator(factory Factory, opts ...RotatorOption) *Rotator

NewRotator uses the given factory as a source and generates a number of instances based on the options given. The instances are called in a naive, round-robin manner.

func (*Rotator) RoundTrip

func (c *Rotator) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip round-robins the outgoing requests against all of the internal instances.

type RotatorOption

RotatorOption is a configuration for the Rotator decorator

type RotatorOption func(*Rotator) *Rotator

func RotatorOptionInstances

func RotatorOptionInstances(number int) RotatorOption

RotatorOptionInstances configurs a rotator with the number of internal RoundTripper instances it should maintain for the rotation.

type RoundTripperFunc

RoundTripperFunc is modelled after the http.HandlerFunc and converts a function matching the RoundTrip signature to a RoundTripper implementation.

type RoundTripperFunc func(r *http.Request) (*http.Response, error)

func (RoundTripperFunc) RoundTrip

func (d RoundTripperFunc) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip calls the wrapped function.

type StatusCodeRetrier

StatusCodeRetrier retries based on HTTP status codes.

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

func (*StatusCodeRetrier) Retry

func (r *StatusCodeRetrier) Retry(req *http.Request, resp *http.Response, e error) bool

Retry the request if the response has a valid code that matches on of the codes given in the retry set.

type TimeoutRetrier

TimeoutRetrier applies a timeout to requests and retries if the request took longer than the timeout duration.

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

func (*TimeoutRetrier) Request

func (r *TimeoutRetrier) Request(req *http.Request) *http.Request

Request adds a timeout to the request context.

func (*TimeoutRetrier) Retry

func (r *TimeoutRetrier) Retry(req *http.Request, resp *http.Response, e error) bool

Retry the request if the context exceeded the deadline.

bitbucket.org/atlassian/transport

transport