httpcache

README

httpcache

A Transport for Go's http.Client that will cache responses according to the HTTP RFC

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).

Documentation: http://godoc.org/github.com/gregjones/httpcache

License: MIT (see LICENSE.txt)

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).

'max-stale' set on a request is not currently respected. (max-age and min-fresh both are.)

Index

• Constants
• type Cache
• type MemoryCache
  • func NewMemoryCache() *MemoryCache
  • func (c *MemoryCache) Delete(key string)
  • func (c *MemoryCache) Get(key string) (resp []byte, ok bool)
  • func (c *MemoryCache) Set(key string, resp []byte)
• type Transport
  • func NewMemoryCacheTransport() *Transport
  • func NewTransport(c Cache) *Transport
  • func (t *Transport) RoundTrip(req *http.Request) (resp *http.Response, err error)

Constants

const (

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

Types

type Cache

type Cache interface {
	// Get returns the []byte representation of a cached response and a bool
	// set to true if the value isn't empty
	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 MemoryCache

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

MemoryCache is an implemtation of Cache that stores responses in an in-memory map.

func NewMemoryCache

func NewMemoryCache() *MemoryCache

NewMemoryCache returns a new Cache that will store items in an in-memory map

func (*MemoryCache) Delete

func (c *MemoryCache) Delete(key string)

func (*MemoryCache) Get

func (c *MemoryCache) Get(key string) (resp []byte, ok bool)

func (*MemoryCache) Set

func (c *MemoryCache) Set(key string, resp []byte)

type Transport

type Transport struct {
	// The RoundTripper interface actually used to make requests
	// If nil, http.DefaultTransport is used
	Transport http.RoundTripper
	Cache     Cache
	// If true, responses returned from the cache will be given an extra header, X-From-Cache
	MarkCachedResponses bool
}

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 NewMemoryCacheTransport

func NewMemoryCacheTransport() *Transport

NewMemoryCacheTransport returns a new Transport using the in-memory cache implementation

func NewTransport

func NewTransport(c Cache) *Transport

NewTransport returns a new Transport with the provided Cache implementation and MarkCachedResponses set to true

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.