README
¶
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, 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 Modules)
go get github.com/SporkHubr/echo-http-cache
Usage
This is an example of use with the memory adapter:
package main
import (
"fmt"
"net/http"
"os"
"time"
"github.com/SporkHubr/echo-http-cache"
"github.com/SporkHubr/echo-http-cache/adapter/memory"
"github.com/labstack/echo/v4"
)
func example(c echo.Context) {
c.String(http.StatusOk, "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)
}
router := echo.New()
router.Use(cacheClient.Middleware())
router.GET("/", example)
e.Start(":8080")
}
Example of Client initialization with Redis adapter:
import (
"github.com/SporkHubr/echo-http-cache"
"github.com/SporkHubr/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"),
)
...
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
echo-http-cache memory adapter takes way less GC pause time, that means smaller GC overhead.
Roadmap
- Make it compliant with RFC7234
- Add more middleware configuration (cacheable status codes, paths etc)
- Develop gRPC middleware
- Develop Badger adapter
- Develop DynamoDB adapter
- Develop MongoDB adapter
Godoc Reference
License
echo-http-cache is released under the MIT License.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func KeyAsString ¶
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 (client *Client) Middleware() echo.MiddlewareFunc
Middleware is the HTTP cache middleware handler.
type ClientOption ¶
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 ClientWithRestrictedPaths ¶
func ClientWithRestrictedPaths(paths []string) ClientOption
ClientWithRestrictedPaths sets the restricted HTTP paths for caching. 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
}
Response is the cached response data structure.
func BytesToResponse ¶
BytesToResponse converts bytes array into Response data structure.
Source Files
Directories