cache

README

go-http-cache

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

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.

Important

This is a hard fork of @victorspinger's http-cache package. Differences include:

• Removing the memory/redis adapter and the benchmark package so there are no external dependencies.
• Ensuring that all the response headers from the previous response are assigned to the HTTP recorder.
• Update client.Middleware method to return http.HandlerFunc.
• Storing the HTTP status code in the cached Response and checking for and issuing HTTP redirect responses where appropriate.

Getting Started

Installation

go get github.com/aaronland/go-http-cache

Usage

This is an example of use with the memory adapter:

package main

import (
    "fmt"
    "net/http"
    "os"
    "time"
    
    "github.com/aaronland/go-http-cache"
    "github.com/aaronland/go-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)
}

Godoc Reference

• http-cache
• Memory adapter

License

http-cache is released under the MIT License.

Documentation

Index

• func KeyAsString(key uint64) string
• type Adapter
• type Client
  • func NewClient(opts ...ClientOption) (*Client, error)
  • func (c *Client) Middleware(next http.Handler) http.HandlerFunc
• type ClientOption
  • func ClientWithAdapter(a Adapter) ClientOption
  • func ClientWithMethods(methods []string) ClientOption
  • func ClientWithRefreshKey(refreshKey string) ClientOption
  • func ClientWithTTL(ttl time.Duration) ClientOption
• type Response
  • func BytesToResponse(b []byte) Response
  • func (r Response) Bytes() []byte

Functions

func KeyAsString

func KeyAsString(key uint64) string

KeyAsString can be used by adapters to convert the cache key from uint64 to string.

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(key uint64) ([]byte, bool)

	// Set caches a response for a given key until an expiration date.
	Set(key uint64, response []byte, expiration time.Time)

	// Release frees cache for a given key.
	Release(key uint64)
}

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

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

Middleware is the HTTP cache middleware handler.

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 ClientWithMethods

func ClientWithMethods(methods []string) ClientOption

ClientWithMethods sets the acceptable HTTP methods to be cached. Optional setting. If not set, default is "GET".

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

	// StatusCode is the HTTP status code of the original request.
	StatusCode int

	// 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
}

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.