httpcache

README

This is a fork of gregjones/httpcache.

License

• MIT License

Documentation

Overview

Package httpcache provides a http.RoundTripper implementation that works as a mostly RFC-compliant cache for http responses.

It is only suitable for use as a 'private' cache (i.e. for a web-browser or an API-client and not for a shared proxy).

Index

• Constants
• Variables
• type Cache
• type Transport
  • func (t *Transport) RoundTrip(req *http.Request) (resp *http.Response, err error)

Constants

const (

	// XFromCache is the header added to responses that are returned from the cache
	XFromCache = "X-From-Cache"

	// XETag1 is the key for the first eTag value.
	XETag1 = xEtags + "1"

	// XETag2 is the key for the second eTag value.
	// Note that in the cache, XETag1 and XETag2 will always be the same.
	// In the Response returned from Response, XETag1 will be the cached value (old) and
	// XETag2 will be the eTag value from the server (new).
	XETag2 = xEtags + "2"
)

Variables

var ErrNoDateHeader = errors.New("no Date header")

ErrNoDateHeader indicates that the HTTP headers contained no Date header.

Types

type Cache

type Cache interface {
	// Get returns the []byte representation of a cached response and a bool
	// set to set to false if the key is not found or the value is stale.
	Get(key string) (responseBytes []byte, ok bool)
	// Set stores the []byte representation of a response against a key
	Set(key string, responseBytes []byte)
	// Delete removes the value associated with the key
	Delete(key string)
}

A Cache interface is used by the Transport to store and retrieve responses.

type Transport

type Transport struct {
	// The RoundTripper interface actually used to make requests
	// If nil, http.DefaultTransport is used
	Transport http.RoundTripper

	// The Cache interface used to store and retrieve responses.
	Cache Cache

	// If true, responses returned from the cache will be given an extra header, X-From-Cache
	MarkCachedResponses bool

	// if EnableETagPair is true, the Transport will store the pair of eTags in the response header.
	// These are stored in the X-Etags-1 and X-Etags-2 headers.
	// If these are different, the response has been modified.
	// If the server does not return an eTag, the MD5 hash of the response body is used.
	EnableETagPair bool

	// CacheKey is an optional func that returns the key to use to store the response.
	// An empty string signals that this request should not be cached.
	CacheKey func(req *http.Request) string

	// AlwaysUseCachedResponse is an optional func that when it returns true
	// a successful response from the cache will be returned without connecting to the server.
	AlwaysUseCachedResponse func(req *http.Request, key string) bool

	// ShouldCache is an optional func that when it returns false, the response will not be cached.
	ShouldCache func(req *http.Request, resp *http.Response, key string) bool

	// Around is an optional func.
	// If set, the Transport will call Around at the start of RoundTrip
	// and defer the returned func until the end of RoundTrip.
	// Typically used to implement a lock that is held for the duration of the RoundTrip.
	Around func(req *http.Request, key string) func()
}

Transport is an implementation of http.RoundTripper that will return values from a cache where possible (avoiding a network request) and will additionally add validators (etag/if-modified-since) to repeated requests allowing servers to return 304 / Not Modified

func (*Transport) RoundTrip

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

RoundTrip takes a Request and returns a Response

If there is a fresh Response already in cache, then it will be returned without connecting to the server.

If there is a stale Response, then any validators it contains will be set on the new request to give the server a chance to respond with NotModified. If this happens, then the cached Response will be returned.