echo-http-cache

This is a high performance Golang HTTP middleware for server-side application layer caching, ideal for REST APIs, using Echo framework. It is simple, superfast, thread safe and gives the possibility to choose the adapter (memory, Redis).

Getting Started

Installation (Go Modules)

go get github.com/coinpaprika/echo-http-cache

Usage

Full example is available at example can be run by:

go run ./example/main.go

Example of use with the memory adapter:

package main

import (
	"log"
	"net/http"
	"time"

	cache "github.com/coinpaprika/echo-http-cache"
	"github.com/coinpaprika/echo-http-cache/adapter/memory"
	"github.com/labstack/echo/v4"
)

func main() {
	memoryAdapter, err := memory.NewAdapter(
		// after reaching the capacity, items are not cached 
		// until the next cleaning goroutine makes the space
		// this is a protection against cache pollution attacks
		memory.WithCapacity(10_000),  
	) 
	if err != nil {
		log.Fatal(err)
	}

	cacheClient, err := cache.NewClient(
		cache.ClientWithAdapter(memoryAdapter),
		cache.ClientWithTTL(10*time.Minute),
		cache.ClientWithRefreshKey("opn"),
	)
	if err != nil {
		log.Fatal(err)
	}

	e := echo.New()
	e.Use(cacheClient.Middleware())
	e.GET("/", func(c echo.Context) error {
		return c.String(http.StatusOK, "OK")
	})
	e.Start(":8080")
}

Notes on caching behaviour:

• Only responses with a status below 400 are cached, and only when the handler returned no error and the whole body was written to the client. A timeout or a client that disconnects mid-response therefore never leaves an empty or truncated body in the cache.
• ClientWithRefreshKey is optional. When it is not set, no query parameter can evict a cache entry; in particular an empty-named parameter (?=) is treated as an ordinary URL.

Example of Client initialization with REDIS adapter:

import (
    "github.com/coinpaprika/echo-http-cache"
    "github.com/coinpaprika/echo-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"),
    )
...

Example of Client initialization with disk based adapter using diskv:

import (
    "github.com/coinpaprika/echo-http-cache"
    "github.com/coinpaprika/echo-http-cache/adapter/disk"
)

...
    cacheClient := cache.NewClient(
        // leave empty for default directory './cache'. Directory will be created if not exist.
        cache.ClientWithAdapter(disk.NewAdapter(disk.WithDirectory("./tmp/cache"), disk.WithMaxMemorySize(50_000_000))), 
        cache.ClientWithTTL(10 * time.Minute),
        cache.ClientWithRefreshKey("opn"),
    )

Adapters selection guide

Memory

• local environments
• high cache hit ratio
• production single & multi node environments
• short-lived objects < 3min
• cheap underlying operations' avg(exec time) < 300ms
• low number of entries: < 1M & < 1Gb in size
• memory safe (when used with WithCapacity option)

Disk

• SSD disks
• high cache hit ratio
• production single & multi node environments
• short-lived to medium-lived objects < 12hr
• cheap underlying operations' avg(exec time) < 300ms
• always memory safe, disk space is used extensively
• some entries are cached in memory for performance - controlled by WithMaxMemorySize() settings, default 100Mb
• large number of entries > 1M & > 1 Gb in size (up to full size of a disk)

Redis

• production multi node environments
• low to high cache hit ratio
• short-lived to long-lived objects > 10 min
• expensive underlying operations' avg(exec time) > 300ms, benefit from sharing across multi nodes
• large number of entries > 1M & >1 Gb in size (up to full size of a disk)

License

echo-http-cache is released under the MIT License.

Forked from:

• victorspringer/http-cache
• SporkHubr/echo-http-cache