httpcache

README

httpcache

Package httpcache provides a http.RoundTripper wrapper implementation that works as a mostly RFC 7234 compliant cached client 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).

Parent repo state

This project isn't actively maintained, per author:

it works for what I, and seemingly others, want to do with it, and I consider it "done". That said, if you find any issues, please open a Pull Request and I will >try to review it. Any changes now that change the public API won't be considered.

Fork change notes

This fork implements the following changes:

• All backend implementations are omitted in this package, thus deleted
• Added a debug mode to diagnose cache behavior and invalidations
• Changed the API to the following: NewCachedClient(c Cache, client *http.Client, markCached bool, debug bool) Doer This allows to treat the cache client instance as a wrapped http.Client implementation and use it accordingly

License

• MIT License

Documentation

Overview

Package httpcache provides a http.RoundTripper wrapper implementation that works as a mostly RFC-compliant cached client 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
• func CachedResponse(c Cache, req *http.Request) (resp *http.Response, err error)
• func Date(respHeaders http.Header) (date time.Time, err error)
• type Cache
• type CacheOptions
• type CachedClient
  • func (cc *CachedClient) Do(req *http.Request) (resp *http.Response, err error)
• type ClientOptions
• type Doer
  • func NewCachedClient(client *http.Client, c Cache, options CacheOptions) Doer
  • func NewMapCachedClient(client *http.Client) Doer
• type MemoryCache
  • func NewMemoryCache() *MemoryCache
  • func (mc *MemoryCache) Delete(key string)
  • func (mc *MemoryCache) Get(key string) (resp []byte, ok bool)
  • func (mc *MemoryCache) Set(key string, resp []byte, ttl int)

Constants

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

Variables

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

ErrNoDateHeader indicates that the HTTP headers contained no Date header.

Functions

func CachedResponse

func CachedResponse(c Cache, req *http.Request) (resp *http.Response, err error)

CachedResponse returns the cached http.Response for req if present, and nil otherwise.

func Date

func Date(respHeaders http.Header) (date time.Time, err error)

Date parses and returns the value of the Date header.

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 for a given key, with a TTL for supporting implementations
	Set(key string, responseBytes []byte, ttl int)
	// Delete removes the value associated with the key
	Delete(key string)
}

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

type CacheOptions

type CacheOptions struct {
	TTL int
	// If true, responses returned from the cache will be given an extra header, X-From-Cache
	MarkCachedResponses bool
	Debug               bool
}

type CachedClient

type CachedClient struct {
	Transport http.RoundTripper
	Cache     Cache
	Options   CacheOptions
}

CachedClient 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 (*CachedClient) Do

func (cc *CachedClient) Do(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.

type ClientOptions

type ClientOptions struct {
}

type Doer

type Doer interface {
	Do(req *http.Request) (*http.Response, error)
}

A Doer interface abstracts the http.Client request execution from the client implementation

func NewCachedClient

func NewCachedClient(client *http.Client, c Cache, options CacheOptions) Doer

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

func NewMapCachedClient

func NewMapCachedClient(client *http.Client) Doer

NewMemoryCachedClient returns a new Transport using the in-memory map cache implementation

type MemoryCache

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

MemoryCache is an implementation 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 (mc *MemoryCache) Delete(key string)

Delete removes key from the cache

func (*MemoryCache) Get

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

Get returns the []byte representation of the response and true if present, false if not

func (*MemoryCache) Set

func (mc *MemoryCache) Set(key string, resp []byte, ttl int)

Set saves response resp to the cache with key