roundtripper

Documentation

Index

• func New(options ...Option) http.RoundTripper
• type CacheMetrics
  • func NewCacheMetrics(namespace, subsystem, application string) CacheMetrics
• type CacheTable
• type CacheTableEntry
• type Option
  • func WithCache(table CacheTable, defaultExpiry, cleanupInterval time.Duration) Option
  • func WithInflightMetrics(m metrics.InFlightMetrics) Option
  • func WithInstrumentedCache(table CacheTable, defaultExpiry, cleanupInterval time.Duration, ...) Option
  • func WithInstrumentedRoundTripper(m metrics.RequestMetrics) Option
  • func WithLimiter(maxParallel int64) Option
  • func WithRequestMetrics(m metrics.RequestMetrics) Option
  • func WithRoundTripper(roundTripper http.RoundTripper) Option
• type RoundTripperFunc
  • func (f RoundTripperFunc) RoundTrip(req *http.Request) (*http.Response, error)

Functions

func New

func New(options ...Option) http.RoundTripper

New returns a RoundTripper that implements the behaviour as specified by the different Option parameters. New will construct a cascading roundTripper in the order of the provided options. E.g.

r := New(WithRequestMetrics(...), WithCache(...))

returns a roundTripper that measures the client metrics, and then attempts to get the response from cache. Metrics are therefor captured for cached and non-cached responses. On the other hand:

r := New(WithCache(...), WithRequestMetrics(...))

first attempts to get the response from cache, and failing that, performs real call, recording its http metrics. Metrics will therefore only be captured for real http calls.

New makes no attempt to sanitize the order of the provided options. E.g. WithRoundTripper does not cascade to a next roundTripper; it directly performs the http call using the provided transport. Therefore, if we create the following RoundTripper:

r := New(WithRoundTripper(...), WithRequestMetrics(...))

the WithRequestMetrics option will not be used at all.

If no options are provided, or the final option isn't WithRoundTripper, the http call is done using http.DefaultTransport.

Types

type CacheMetrics

type CacheMetrics interface {
	Measure(r *http.Request, found bool)
	prometheus.Collector
}

func NewCacheMetrics

func NewCacheMetrics(namespace, subsystem, application string) CacheMetrics

type CacheTable

type CacheTable []*CacheTableEntry

CacheTable holds the endpoints that should be cached. If table is empty, all responses will be cached.

var DefaultCacheTable CacheTable

DefaultCacheTable is a CacheTable that caches all requests.

type CacheTableEntry

type CacheTableEntry struct {
	// Path is the URL Path for requests whose responses should be cached.
	// Can be a literal path, or a regular expression. In the latter case, set IsRegExp to true
	Path string
	// Methods is the list of HTTP Methods for which requests the response should be cached.
	// If empty, requests for any method will be cached.
	Methods []string
	// IsRegExp indicates if the Path is a regular expression.
	// CacheTableEntry will panic if Path does not contain a valid regular expression.
	IsRegExp bool
	// Expiry indicates how long a response should be cached.
	Expiry time.Duration
	// contains filtered or unexported fields
}

CacheTableEntry contains a single endpoint that should be cached. If the Path is a regular expression, IsRegExp must be true.

type Option

type Option func(current http.RoundTripper) http.RoundTripper

Option is a function that can be passed to New to specify the behaviour of the RoundTripper. See WithMetrics, WithCache, etc. for examples.

func WithCache

func WithCache(table CacheTable, defaultExpiry, cleanupInterval time.Duration) Option

WithCache creates a RoundTripper that caches the HTTP responses. table determines the caching behaviour per target path. If table is empty, all responses are cached for defaultExpiry amount of time. If table is not empty, only requests that match an entry in the table are cached, for the amount of time specified in the table's entry.

Expired entries are periodically removed from the cache as per CleanupInterval. If CleanupInterval is zero, expired entries will never be removed.

func WithInflightMetrics

func WithInflightMetrics(m metrics.InFlightMetrics) Option

WithInflightMetrics creates a http.RoundTripper that measures outstanding requests. The caller must register the metrics with a Prometheus registry.

func WithInstrumentedCache

func WithInstrumentedCache(table CacheTable, defaultExpiry, cleanupInterval time.Duration, metrics CacheMetrics) Option

WithInstrumentedCache causes RoundTripper to cache the HTTP responses, as WithCache. Additionally, it measures how often the cache was consulted and hit as Prometheus metrics.

namespace and subsystem are prepended to the metric names, e.g. api_errors_total will be called foo_bar_api_errors_total if namespace and subsystem are set to foo and bar respectively. Application will be set in the metrics' application label.

If namespace, subsystem and application are blank, the call is equivalent to calling WithCache, i.e. no metrics are created.

func WithInstrumentedRoundTripper

func WithInstrumentedRoundTripper(m metrics.RequestMetrics) Option

WithInstrumentedRoundTripper creates a http.RoundTripper that records requests metrics to the provided metrics.RequestMetrics. The caller must register the metrics with a Prometheus registry.

deprecated: use WithRequestMetrics instead.

func WithLimiter

func WithLimiter(maxParallel int64) Option

WithLimiter creates a RoundTripper that limits the number concurrent http requests to maxParallel.

func WithRequestMetrics

func WithRequestMetrics(m metrics.RequestMetrics) Option

WithRequestMetrics creates a http.RoundTripper that measures requests count and duration. The caller must register the metrics with a Prometheus registry.

func WithRoundTripper

func WithRoundTripper(roundTripper http.RoundTripper) Option

WithRoundTripper specifies the http.RoundTripper to make the final http client call. If no WithRoundTripper is provided, RoundTripper defaults to http.DefaultTransport. Providing a nil roundTripper causes RoundTripper to panic.

type RoundTripperFunc

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

The RoundTripperFunc type is an adapter to allow the use of ordinary functions as HTTP roundTrippers. If f is a function with the appropriate signature, RoundTripperFunc(f) is a roundTripper that calls f.

func (RoundTripperFunc) RoundTrip

func (f RoundTripperFunc) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip calls f(req)