httpcache

README

httpcache

httpcache provides an rfc7234 compliant golang http.Handler.

Example

This example if from the included CLI, it runs a caching proxy on http://localhost:8080.

proxy := &httputil.ReverseProxy{
    Director: func(r *http.Request) {
    },
}

handler := httpcache.NewHandler(httpcache.NewMemoryCache(), proxy)
handler.Shared = true

log.Printf("proxy listening on http://%s", listen)
log.Fatal(http.ListenAndServe(listen, proxy))

Implemented

• All of rfc7234, except those listed below
• Disk and Memory storage
• Apache-like logging via httplog package

Todo

• Caching of conditional requests
• Handling Authorization header correctly (currently uncacheable)
• Handle Cache-Control directives that can be limited to certain headers
• Offline operation
• LRU metadata, cache eviction
• Size constraints on memory/disk cache
• Edge cases around handling chunked upstream responses and HTTP/1.0 clients
• Proper handling of Via header
• Respect max-age headers in Requests
• Support for weak entities with If-Match and If-None-Match
• Invalidation based on Content-Location

Testing

Tests are currently conducted via the test suite and verified via the CoAdvisor tool.

Reading List

• http://httpwg.github.io/specs/rfc7234.html
• https://www.mnot.net/blog/2011/07/11/what_proxies_must_do
• https://www.mnot.net/blog/2014/06/07/rfc2616_is_dead

Documentation

Index

• Constants
• Variables
• func Debugf(format string, args ...interface{})
• func Errorf(format string, args ...interface{})
• func Fatal(args ...interface{})
• func Fatalf(format string, args ...interface{})
• type Cache
  • func NewCache(fs vfs.VFS) *Cache
  • func NewDiskCache(dir string) (*Cache, error)
  • func NewMemoryCache() *Cache
  • func (c *Cache) Freshen(res *Resource, keys ...string) error
  • func (c *Cache) Header(key string) (Header, error)
  • func (c *Cache) Invalidate(keys ...string)
  • func (c *Cache) Retrieve(key string) (*Resource, error)
  • func (c *Cache) Store(res *Resource, keys ...string) error
• type CacheControl
  • func ParseCacheControl(input string) (CacheControl, error)
  • func ParseCacheControlHeaders(h http.Header) (CacheControl, error)
  • func (cc CacheControl) Add(key, val string)
  • func (cc CacheControl) Duration(key string) (time.Duration, error)
  • func (cc CacheControl) Get(key string) (string, bool)
  • func (cc CacheControl) Has(key string) bool
  • func (cc CacheControl) String() string
• type Handler
  • func NewHandler(cache *Cache, upstream http.Handler) *Handler
  • func (h *Handler) ServeHTTP(rw http.ResponseWriter, r *http.Request)
• type Header
• type Key
  • func NewKey(method string, u *url.URL, h http.Header) Key
  • func NewRequestKey(r *http.Request) Key
  • func (k Key) ForMethod(method string) Key
  • func (k Key) String() string
  • func (k Key) Vary(varyHeader string, r *http.Request) Key
• type ReadSeekCloser
• type Resource
  • func NewResource(statusCode int, body ReadSeekCloser, hdrs http.Header) *Resource
  • func NewResourceBytes(statusCode int, b []byte, hdrs http.Header) *Resource
  • func (r *Resource) Age() (time.Duration, error)
  • func (r *Resource) DateAfter(d time.Time) bool
  • func (r *Resource) Expires() (time.Time, error)
  • func (r *Resource) HasExplicitExpiration() bool
  • func (r *Resource) HasValidators() bool
  • func (r *Resource) Header() http.Header
  • func (r *Resource) HeuristicFreshness() time.Duration
  • func (r *Resource) IsStale() bool
  • func (r *Resource) LastModified() time.Time
  • func (r *Resource) MarkStale()
  • func (r *Resource) MaxAge(shared bool) (time.Duration, error)
  • func (r *Resource) MustValidate(shared bool) bool
  • func (r *Resource) Status() int
  • func (r *Resource) Via() string
  • func (r *Resource) Warnings() ([]string, error)
• type Validator
  • func (v *Validator) Validate(req *http.Request, res *Resource) bool

Constants

const (
	CacheHeader     = "X-Cache"
	ProxyDateHeader = "Proxy-Date"
)

const (
	CacheControlHeader = "Cache-Control"
)

Variables

var Clock = func() time.Time {
	return time.Now().UTC()
}

var DebugLogging = false

var ErrNotFoundInCache = errors.New("Not found in cache")

Returned when a resource doesn't exist

var Writes sync.WaitGroup

Functions

func Debugf

func Debugf(format string, args ...interface{})

func Errorf

func Errorf(format string, args ...interface{})

func Fatal

func Fatal(args ...interface{})

func Fatalf

func Fatalf(format string, args ...interface{})

Types

type Cache

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

Cache provides a storage mechanism for cached Resources

func NewCache

func NewCache(fs vfs.VFS) *Cache

NewCache returns a Cache backed off the provided VFS

func NewDiskCache

func NewDiskCache(dir string) (*Cache, error)

NewDiskCache returns a disk-backed cache

func NewMemoryCache

func NewMemoryCache() *Cache

NewMemoryCache returns an ephemeral cache in memory

func (*Cache) Freshen

func (c *Cache) Freshen(res *Resource, keys ...string) error

func (*Cache) Header

func (c *Cache) Header(key string) (Header, error)

Retrieve the Status and Headers for a given key path

func (*Cache) Invalidate

func (c *Cache) Invalidate(keys ...string)

func (*Cache) Retrieve

func (c *Cache) Retrieve(key string) (*Resource, error)

Retrieve returns a cached Resource for the given key

func (*Cache) Store

func (c *Cache) Store(res *Resource, keys ...string) error

Store a resource against a number of keys

type CacheControl

type CacheControl map[string][]string

func ParseCacheControl

func ParseCacheControl(input string) (CacheControl, error)

func ParseCacheControlHeaders

func ParseCacheControlHeaders(h http.Header) (CacheControl, error)

func (CacheControl) Add

func (cc CacheControl) Add(key, val string)

func (CacheControl) Duration

func (cc CacheControl) Duration(key string) (time.Duration, error)

func (CacheControl) Get

func (cc CacheControl) Get(key string) (string, bool)

func (CacheControl) Has

func (cc CacheControl) Has(key string) bool

func (CacheControl) String

func (cc CacheControl) String() string

type Handler

type Handler struct {
	Shared bool
	// contains filtered or unexported fields
}

func NewHandler

func NewHandler(cache *Cache, upstream http.Handler) *Handler

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(rw http.ResponseWriter, r *http.Request)

type Header

type Header struct {
	http.Header
	StatusCode int
}

type Key

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

Key represents a unique identifier for a resource in the cache

func NewKey

func NewKey(method string, u *url.URL, h http.Header) Key

NewKey returns a new Key instance

func NewRequestKey

func NewRequestKey(r *http.Request) Key

RequestKey generates a Key for a request

func (Key) ForMethod

func (k Key) ForMethod(method string) Key

ForKey returns a new Key with a given method

func (Key) String

func (k Key) String() string

func (Key) Vary

func (k Key) Vary(varyHeader string, r *http.Request) Key

Vary returns a Key that is varied on particular headers in a http.Request

type ReadSeekCloser

type ReadSeekCloser interface {
	io.Reader
	io.Seeker
	io.Closer
}

type Resource

type Resource struct {
	ReadSeekCloser
	RequestTime, ResponseTime time.Time
	// contains filtered or unexported fields
}

func NewResource

func NewResource(statusCode int, body ReadSeekCloser, hdrs http.Header) *Resource

func NewResourceBytes

func NewResourceBytes(statusCode int, b []byte, hdrs http.Header) *Resource

func (*Resource) Age

func (r *Resource) Age() (time.Duration, error)

Calculate the age of the resource

func (*Resource) DateAfter

func (r *Resource) DateAfter(d time.Time) bool

func (*Resource) Expires

func (r *Resource) Expires() (time.Time, error)

func (*Resource) HasExplicitExpiration

func (r *Resource) HasExplicitExpiration() bool

func (*Resource) HasValidators

func (r *Resource) HasValidators() bool

func (*Resource) Header

func (r *Resource) Header() http.Header

func (*Resource) HeuristicFreshness

func (r *Resource) HeuristicFreshness() time.Duration

func (*Resource) IsStale

func (r *Resource) IsStale() bool

func (*Resource) LastModified

func (r *Resource) LastModified() time.Time

func (*Resource) MarkStale

func (r *Resource) MarkStale()

func (*Resource) MaxAge

func (r *Resource) MaxAge(shared bool) (time.Duration, error)

func (*Resource) MustValidate

func (r *Resource) MustValidate(shared bool) bool

func (*Resource) Status

func (r *Resource) Status() int

func (*Resource) Via

func (r *Resource) Via() string

func (*Resource) Warnings

func (r *Resource) Warnings() ([]string, error)

type Validator

type Validator struct {
	Handler http.Handler
}

func (*Validator) Validate

func (v *Validator) Validate(req *http.Request, res *Resource) bool