cache

README

http-cache

This is a high performance Golang HTTP middleware for server-side application layer caching, ideal for REST APIs.

It is simple, super fast, thread safe and gives the possibility to choose the adapter (memory, Redis, DynamoDB etc).

The memory adapter minimizes GC overhead to near zero and supports some options of caching algorithms (LRU, MRU, LFU, MFU). This way, it is able to store plenty of gigabytes of responses, keeping great performance and being free of leaks.

Getting Started

Installation

go get github.com/victorspringer/http-cache

Usage

This is an example of use with the memory adapter:

package main

import (
    "fmt"
    "net/http"
    "os"
    "time"
    
    "github.com/victorspringer/http-cache"
    "github.com/victorspringer/http-cache/adapter/memory"
)

func example(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Ok"))
}

func main() {
    memcached, err := memory.NewAdapter(
        memory.AdapterWithAlgorithm(memory.LRU),
        memory.AdapterWithCapacity(10000000),
    )
    if err != nil {
        fmt.Println(err)
        os.Exit(1)
    }

    cacheClient, err := cache.NewClient(
        cache.ClientWithAdapter(memcached),
        cache.ClientWithTTL(10 * time.Minute),
        cache.ClientWithRefreshKey("opn"),
    )
    if err != nil {
        fmt.Println(err)
        os.Exit(1)
    }

    handler := http.HandlerFunc(example)

    http.Handle("/", cacheClient.Middleware(handler))
    http.ListenAndServe(":8080", nil)
}

Example of Client initialization with Redis adapter:

import (
    "github.com/victorspringer/http-cache"
    "github.com/victorspringer/http-cache/adapter/redis"
)

...

    ringOpt := &redis.RingOptions{
        Addrs: map[string]string{
            "server": ":6379",
        },
    }
    cacheClient := cache.NewClient(
        cache.ClientWithAdapter(redis.NewAdapter(ringOpt)),
        cache.ClientWithTTL(10 * time.Minute),
        cache.ClientWithRefreshKey("opn"),
    )

...

Benchmarks

The benchmarks were based on allegro/bigache tests and used to compare it with the http-cache memory adapter.
The tests were run using an Intel i5-2410M with 8GB RAM on Arch Linux 64bits.
The results are shown below:

Writes and Reads

cd adapter/memory/benchmark
go test -bench=. -benchtime=10s ./... -timeout 30m

BenchmarkHTTPCacheMamoryAdapterSet-4             5000000     343 ns/op    172 B/op    1 allocs/op
BenchmarkBigCacheSet-4                           3000000     507 ns/op    535 B/op    1 allocs/op
BenchmarkHTTPCacheMamoryAdapterGet-4            20000000     146 ns/op      0 B/op    0 allocs/op
BenchmarkBigCacheGet-4                           3000000     343 ns/op    120 B/op    3 allocs/op
BenchmarkHTTPCacheMamoryAdapterSetParallel-4    10000000     223 ns/op    172 B/op    1 allocs/op
BenchmarkBigCacheSetParallel-4                  10000000     291 ns/op    661 B/op    1 allocs/op
BenchmarkHTTPCacheMemoryAdapterGetParallel-4    50000000    56.1 ns/op      0 B/op    0 allocs/op
BenchmarkBigCacheGetParallel-4                  10000000     163 ns/op    120 B/op    3 allocs/op

http-cache writes are slightly faster and reads are much more faster.

Garbage Collection Pause Time

cache=http-cache go run benchmark_gc_overhead.go

Number of entries:  20000000
GC pause for http-cache memory adapter:  2.445617ms

cache=bigcache go run benchmark_gc_overhead.go

Number of entries:  20000000
GC pause for bigcache:  7.43339ms

http-cache memory adapter takes way less GC pause time, that means smaller GC overhead.

Roadmap

• Make it compliant with RFC7234
• Add middleware configuration (cacheable status codes, request methods etc)
• Develop gRPC middleware
• Develop Badger adapter
• Develop DynamoDB adapter
• Develop MongoDB adapter

Godoc Reference

• http-cache
• Memory adapter
• Redis adapter

License

http-cache is released under the MIT License.

Documentation

Index

• type Adapter
• type Client
  • func NewClient(opts ...ClientOption) (*Client, error)
  • func (c *Client) Exists(uri string) bool
  • func (c *Client) GeneratePrefixAndKey(r *http.Request) (prefix, key string)
  • func (c *Client) Middleware(next http.Handler) http.Handler
  • func (c *Client) PutItemToCache(next http.Handler, r *http.Request, prefix, key string) (result *http.Response, value []byte)
  • func (c *Client) Release(uri string)
  • func (c *Client) ReleaseIfStartsWith(uri string)
  • func (c *Client) ReleaseURI(uri string)
• type ClientOption
  • func ClientWithAdapter(a Adapter) ClientOption
  • func ClientWithLogger(logger *log.Logger) ClientOption
  • func ClientWithRefreshKey(refreshKey string) ClientOption
  • func ClientWithTTL(ttl time.Duration) ClientOption
• type Response
  • func BytesToResponse(b []byte) Response
  • func (r Response) Bytes() []byte

Types

type Adapter

type Adapter interface {
	// Get retrieves the cached response by a given key. It also
	// returns true or false, whether it exists or not.
	Get(prefix, key string) ([]byte, bool)

	Exists(prefix, key string) bool

	Set(prefix, key string, response []byte)

	// Release frees cache for a given key.
	Release(prefix, key string)

	ReleasePrefix(prefix string)
	ReleaseIfStartsWith(key string)
}

Adapter interface for HTTP cache middleware client.

type Client

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

Client data structure for HTTP cache middleware.

func NewClient

func NewClient(opts ...ClientOption) (*Client, error)

NewClient initializes the cache HTTP middleware client with the given options.

func (*Client) Exists

func (c *Client) Exists(uri string) bool

Exists ...

func (*Client) GeneratePrefixAndKey

func (c *Client) GeneratePrefixAndKey(r *http.Request) (prefix, key string)

GeneratePrefixAndKey ...

func (*Client) Middleware

func (c *Client) Middleware(next http.Handler) http.Handler

Middleware is the HTTP cache middleware handler.

func (*Client) PutItemToCache

func (c *Client) PutItemToCache(next http.Handler, r *http.Request, prefix, key string) (result *http.Response, value []byte)

PutItemToCache ...

func (*Client) Release

func (c *Client) Release(uri string)

Release ...

func (*Client) ReleaseIfStartsWith

func (c *Client) ReleaseIfStartsWith(uri string)

ReleaseIfStartsWith ...

func (*Client) ReleaseURI

func (c *Client) ReleaseURI(uri string)

ReleaseURI ...

type ClientOption

type ClientOption func(c *Client) error

ClientOption is used to set Client settings.

func ClientWithAdapter

func ClientWithAdapter(a Adapter) ClientOption

ClientWithAdapter sets the adapter type for the HTTP cache middleware client.

func ClientWithLogger

func ClientWithLogger(logger *log.Logger) ClientOption

ClientWithLogger ...

func ClientWithRefreshKey

func ClientWithRefreshKey(refreshKey string) ClientOption

ClientWithRefreshKey sets the parameter key used to free a request cached response. Optional setting.

func ClientWithTTL

func ClientWithTTL(ttl time.Duration) ClientOption

ClientWithTTL sets how long each response is going to be cached.

type Response

type Response struct {
	// Value is the cached response value.
	Value []byte

	// Header is the cached response header.
	Header http.Header

	// Expiration is the cached response expiration date.
	Expiration time.Time

	// LastAccess is the last date a cached response was accessed.
	// Used by LRU and MRU algorithms.
	LastAccess time.Time

	// Frequency is the count of times a cached response is accessed.
	// Used for LFU and MFU algorithms.
	Frequency int

	CachedAt time.Time
}

Response is the cached response data structure.

func BytesToResponse

func BytesToResponse(b []byte) Response

BytesToResponse converts bytes array into Response data structure.

func (Response) Bytes

func (r Response) Bytes() []byte

Bytes converts Response data structure into bytes array.