kitcache

README

kitcache

kitcache is an endpoint response caching framework and implementation to be used with the go-kit framework.

Usage

To cache a go-kit endpoint in with this framework:

1. implement a RequestFunnel for the endpoint's request value to create cache keys

type UserProfileRequest struct {
	UserId uint64
	RequestId string
}

type UserProfileResponse struct {}

type UserProfileCacheFunnel struct {}
func (f *UserProfileCacheFunnel) Hash(requestIface interface{}) ([]byte,
	error) {
	request := requestIface.(*UserProfileRequest)
	hashValue := fmt.Sprintf("%v", request.UserId)
	return []byte(hashValue), nil
}
...
funnel := &UserProfileCacheFunnel{}

1. implement a RequestMarshaler for the endpoint's request values or use the provided gob-based marshaler

func responseAllocator() interface{} {
	return &UserProfileResponse{}
}
...
marshaler := marshal.NewGobMarshaler(exampleStructAllocator)

1. implement a cache or use the built-in ccache-based cache

backingCache := cache.NewInMemoryCache(10, 10*time.Hour)

1. wrap the endpoint to be cached

serviceEndpoint := BuildUserProfileEndpoint()
endpointCache, cacheCreateErr := kitcache.NewEndpointCache(serviceEndpoint,
	backingCache, marshaler, funnel)

// use this in the place of serviceEndpoint to use the cache
cachedEndpoint := endpointCache.Endpoint()

1. (optional) Invalidate cached items

cacheLine := []byte()
cacheInvalidator := endpointCache.Invalidator()
cacheInvalidator.Invalidate(cacheLine)

Documentation

Index

• Constants
• Variables
• type Cache
• type EndpointCache
  • func NewEndpointCache(wrapped endpoint.Endpoint, cache Cache, marshaler ResponseMarshaler, ...) (EndpointCache, error)
• type Invalidator
• type RequestFunnel
• type ResponseMarshaler
• type V1ConstructorOption
  • func V1WithMaximumItems(maximumItems uint64) V1ConstructorOption

Constants

const (
	// DefaultMaxCachedUnits is the default number of unit which the cache will
	// store.
	//
	// 1 unit == 1 item
	DefaultMaxCachedUnits = 5000
)

Variables

var (
	// ErrorCacheMiss is returned if the item could not be found in the cache
	ErrorCacheMiss = errors.New("cached item not available")
)

Types

type Cache

type Cache interface {
	// Get attempts to fetch a cached item by its key. If not found,
	// nil and ErrorCacheMiss will be returned
	Get([]byte) (interface{}, error)

	// Put takes a cache key and item to cache and emplaces it under the key
	// provided. If the item exists, then it is overwritten
	Put([]byte, interface{}) error

	// Invalidate removes an item from the cache.
	Invalidate([]byte) error
}

Cache is the interface the backing cache implementation must satisfy to be used by kitcache

type EndpointCache

type EndpointCache interface {
	// Invalidator fetches a goroutine-safe Invalidator to remove items from
	// the cache
	Invalidator() Invalidator

	// Endpoint will generate an endpoint which will utilize the cache and call
	// the wrapped endpoint on cache misses
	Endpoint() endpoint.Endpoint

	// Hits returns how many times the cache successfully satisfied a request
	// from the cache only
	Hits() uint64

	// Misses returns how many times a request was processed without having been
	// previously cached
	Misses() uint64

	//ResetStatistics reset the hits & misses counters
	ResetStatistics()
}

EndpointCache is the basic unit of the kitcache library. It will cache responses serviced by the wrapped endpoint

func NewEndpointCache

func NewEndpointCache(wrapped endpoint.Endpoint, cache Cache,
	marshaler ResponseMarshaler, funnel RequestFunnel,
	opts ...V1ConstructorOption) (
	EndpointCache, error)

NewEndpointCache wraps an endpoint with a cache

type Invalidator

type Invalidator interface {
	// Invalidate will remove the provided cache key from the underlying cache.
	// It returns the error encountered while removing the a cached object
	Invalidate([]byte) error
}

Invalidator is used to remove cached items

type RequestFunnel

type RequestFunnel interface {
	// Hash should take a request provided to the cached endpoint and produces
	// a key under which the item should be cached
	Hash(interface{}) ([]byte, error)
}

RequestFunnel facilitates converting a request into a key used in the cache

type ResponseMarshaler

type ResponseMarshaler interface {

	// Marshal saves the provided empty interface to a byte array and can
	// provide an error if unsuccessful
	Marshal(interface{}) ([]byte, error)

	// Unmarshal loads the provided bytes into an object viable to be served in
	// place of the cache forwarding a request to the wrapped Endpoint.
	Unmarshal([]byte) (interface{}, error)
}

ResponseMarshaler will marshal a request object to and from the cache

type V1ConstructorOption

type V1ConstructorOption func(i *v1Cache) error

V1ConstructorOption is used by the cache implementation for optional parameters

func V1WithMaximumItems

func V1WithMaximumItems(maximumItems uint64) V1ConstructorOption

V1WithMaximumItems sets the maximum items which the cache will hold