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, handler))

Implemented

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

Todo

• Offline operation
• Size constraints on memory/disk cache and cache eviction
• Correctly handle mixture of HTTP1.0 clients and 1.1 upstreams
• More detail in Via header
• Support for weak entities with If-Match and If-None-Match
• Invalidation based on Content-Location and request method
• Better handling of duplicate headers and CacheControl values

Caveats

• Conditional requests are never cached, this includes Range requests

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
• type Cache
  • func NewDiskCache(dir string) (Cache, error)
  • func NewMemoryCache() Cache
  • func NewVFSCache(fs vfs.VFS) Cache
• 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) IsNonErrorStatus() bool
  • 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) RemovePrivateHeaders()
  • func (r *Resource) Status() int
  • func (r *Resource) Via() string
• 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

Types

type Cache

type Cache interface {
	Header(key string) (Header, error)
	Store(res *Resource, keys ...string) error
	Retrieve(key string) (*Resource, error)
	Invalidate(keys ...string)
	Freshen(res *Resource, keys ...string) error
}

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 NewVFSCache

func NewVFSCache(fs vfs.VFS) Cache

NewCache returns a cache backend off the provided VFS

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

func (r *Resource) IsNonErrorStatus() bool

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

func (r *Resource) RemovePrivateHeaders()

func (*Resource) Status

func (r *Resource) Status() int

func (*Resource) Via

func (r *Resource) Via() string

type Validator

type Validator struct {
	Handler http.Handler
}

func (*Validator) Validate

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