README
¶
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 ¶
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.
Functions ¶
This section is empty.
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 CacheControl ¶ added in v0.8.0
CacheControl is a map of the cache-control directives to their values (or "" if no value).
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
// CanStore is an optional func that when set, is called to determine if a response
// can be stored in the cache.
// If not set, a default implementation is used that checks for 'no-store' in
// the request and response cache-control headers.
//
// Note that this does not imply that the response will be cached, only that it is
// allowed to be cached. The ShouldCache func is called after this to make the final decision.
CanStore func(reqCacheControl, respCacheControl CacheControl) (canStore 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()
// contains filtered or unexported fields
}
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 ¶
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.
Source Files