Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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(options CacheMetricsOptions) CacheMetrics
NewCacheMetrics returns CacheMetrics that measure the total cache attempts and the cache hits (both as Counters).
type CacheMetricsOptions ¶ added in v0.5.0
type CacheMetricsOptions struct {
// Namespace to prepend to the metric name
Namespace string
// Subsystem to prepend to the metric name
Subsystem string
// ConstLabels to add to the metric
ConstLabels prometheus.Labels
// GetPath returns the path to use in the metric's path label. Can be used to reduce metric cardinality when many paths are cached.
GetPath func(r *http.Request) string
}
CacheMetricsOptions provides configuration options for NewCacheMetrics
type CacheOptions ¶ added in v0.5.0
type CacheOptions struct {
// CacheTable determines which requests are cached and for how long. If empty, all requests are cached.
CacheTable
// DefaultExpiration defines how long requests are cached when CacheTable is empty.
DefaultExpiration time.Duration
// CleanupInterval defines how often the cache is scrubbed (i.e. when stale requests are removed).
// If zero, stale requests are never removed.
CleanupInterval time.Duration
// GetKey returns the cache key for a request. By default, the request's method and path are used.
GetKey func(*http.Request) string
// Metrics contains the Prometheus metrics for the cache. The caller must register the requests with a Prometheus registry.
// If nil, no metrics are collected.
CacheMetrics
}
CacheOptions contains configuration options for a caching roundTripper.
type CacheTable ¶
type CacheTable []*CacheTableEntry
CacheTable defines which responses are cached. If table is empty, all responses will be cached.
var DefaultCacheTable CacheTable
DefaultCacheTable caches all requests.
type CacheTableEntry ¶
type CacheTableEntry struct {
// Path is the URL Path for requests whose responses should be cached. If blank, all paths will 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(options CacheOptions) Option
WithCache creates a RoundTripper that caches the HTTP responses. See CacheOptions for the available options.
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 WithLimiter ¶
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 request 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 ¶
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.
Source Files
Directories