httpcache

Documentation

Overview

Package httpcache provides a caching http.RoundTripper that sits beneath the providers: they use an ordinary *http.Client and never manage caching themselves. Cacheable GET responses are memoised for the run and concurrent identical requests are coalesced, so a hundred markers pointing at the same upstream cause a single round trip. Cache hits make no network call at all, which is also the most effective way to stay within an API's rate limit.

The cache is keyed by method, URL, and Authorization, and stores full responses including their validators (ETag, Last-Modified), leaving room for a disk-backed Store and conditional revalidation behind the same seam.

Index

• func New(opts ...Option) *http.Client
• type Entry
• type MemStore
  • func NewMemStore() *MemStore
  • func (m *MemStore) Get(key string) (*Entry, bool)
  • func (m *MemStore) Set(key string, entry *Entry)
• type Option
  • func WithStore(s Store) Option
  • func WithTimeout(d time.Duration) Option
  • func WithTransport(rt http.RoundTripper) Option
• type Store
• type Transport
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

Functions

func New

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

New returns an *http.Client whose transport caches and coalesces GET requests. Providers use the returned client like any other and remain unaware of the cache.

Types

type Entry

type Entry struct {
	Status int
	Header http.Header
	Body   []byte
}

Entry is a cached HTTP response, buffered so it can be replayed any number of times. The Header is retained in full, so the validators a future conditional-request store needs (ETag, Last-Modified) are already present.

type MemStore

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

MemStore is a concurrency-safe, in-memory Store. It lives for as long as the transport that holds it, which for a CLI run means the whole run.

func NewMemStore

func NewMemStore() *MemStore

NewMemStore returns an empty in-memory store.

func (*MemStore) Get

func (m *MemStore) Get(key string) (*Entry, bool)

Get returns the entry for key, if present.

func (*MemStore) Set

func (m *MemStore) Set(key string, entry *Entry)

Set stores entry under key.

type Option

type Option func(*config)

Option configures the client returned by New.

func WithStore

func WithStore(s Store) Option

WithStore sets the cache backend (default: an in-memory MemStore). This is the seam for a disk-backed, cross-run store.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the client's total per-request timeout.

func WithTransport

func WithTransport(rt http.RoundTripper) Option

WithTransport sets the underlying transport the cache wraps on a miss. Compose a rate-limit-aware transport here so cache hits never consume rate limit.

type Store

type Store interface {
	Get(key string) (*Entry, bool)
	Set(key string, entry *Entry)
}

Store is the cache backend behind the transport. The default is in-memory and run-scoped; a disk-backed store for cross-run reuse can be supplied via WithStore without any change to providers or the transport.

type Transport

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

Transport is the caching http.RoundTripper. Non-GET requests pass straight through; GET requests are served from the store when present, and otherwise fetched once - concurrent identical fetches share a single round trip.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.