cache

README

gin-cache

English | 🇨🇳中文

A high performance gin middleware to cache http response. Compared to gin-contrib/cache. It has a huge performance improvement.

Feature

• Has a huge performance improvement compared to gin-contrib/cache.
• Cache http response in local memory or Redis.
• Offer a way to custom the cache strategy by per request.
• Use singleflight to avoid cache breakdown problem.
• Only Cache 2xx HTTP Response.

How To Use

Install

go get -u github.com/aeroideaservices/gin-cache

Example

Cache In Local Memory

package main

import (
	"time"

	"github.com/aeroideaservices/gin-cache"
	"github.com/aeroideaservices/gin-cache/persist"
	"github.com/gin-gonic/gin"
)

func main() {
	app := gin.New()

	memoryStore := persist.NewMemoryStore(1 * time.Minute)

	app.GET("/hello",
		cache.CacheByRequestURI(memoryStore, 2*time.Second),
		func(c *gin.Context) {
			c.String(200, "hello world")
		},
	)

	if err := app.Run(":8080"); err != nil {
		panic(err)
	}
}

Cache In Redis

package main

import (
	"time"

	"github.com/aeroideaservices/gin-cache"
	"github.com/aeroideaservices/gin-cache/persist"
	"github.com/gin-gonic/gin"
	"github.com/go-redis/redis/v8"
)

func main() {
	app := gin.New()

	redisStore := persist.NewRedisStore(redis.NewClient(&redis.Options{
		Network: "tcp",
		Addr:    "127.0.0.1:6379",
	}))

	app.GET("/hello",
		cache.CacheByRequestURI(redisStore, 2*time.Second),
		func(c *gin.Context) {
			c.String(200, "hello world")
		},
	)
	if err := app.Run(":8080"); err != nil {
		panic(err)
	}
}

Benchmark

wrk -c 500 -d 1m -t 5 http://127.0.0.1:8080/hello

MemoryStore

RedisStore

Documentation

Index

• func Cache(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, ...) gin.HandlerFunc
• func CacheByRequestBody(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, ...) gin.HandlerFunc
• func CacheByRequestPath(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, ...) gin.HandlerFunc
• func CacheByRequestURI(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, ...) gin.HandlerFunc
• type BeforeReplyWithCacheCallback
• type Config
• type Discard
  • func (l Discard) Errorf(string, ...interface{})
• type GetCacheStrategyByRequest
• type Logger
• type OnHitCacheCallback
• type OnMissCacheCallback
• type OnShareSingleFlightCallback
• type Option
  • func IgnoreQueryOrder() Option
  • func WithBeforeReplyWithCache(cb BeforeReplyWithCacheCallback) Option
  • func WithCacheStrategyByRequest(getGetCacheStrategyByRequest GetCacheStrategyByRequest) Option
  • func WithLogger(l Logger) Option
  • func WithOnHitCache(cb OnHitCacheCallback) Option
  • func WithOnMissCache(cb OnMissCacheCallback) Option
  • func WithOnShareSingleFlight(cb OnShareSingleFlightCallback) Option
  • func WithPrefixKey(prefix string) Option
  • func WithSingleFlightForgetTimeout(forgetTimeout time.Duration) Option
• type ResponseCache
• type Strategy

Functions

func Cache

func Cache(
	defaultCacheStore persist.CacheStore,
	defaultExpire time.Duration,
	opts ...Option,
) gin.HandlerFunc

Cache user must pass getCacheKey to describe the way to generate cache key

func CacheByRequestBody

func CacheByRequestBody(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, opts ...Option) gin.HandlerFunc

CacheByRequestBody a shortcut function for caching response by request body

func CacheByRequestPath

func CacheByRequestPath(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, opts ...Option) gin.HandlerFunc

CacheByRequestPath a shortcut function for caching response by url path, means will discard the query params

func CacheByRequestURI

func CacheByRequestURI(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, opts ...Option) gin.HandlerFunc

CacheByRequestURI a shortcut function for caching response by uri

Types

type BeforeReplyWithCacheCallback

type BeforeReplyWithCacheCallback func(c *gin.Context, cache *ResponseCache)

type Config

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

Config contains all options

type Discard

type Discard struct {
}

Discard the default logger that will discard all logs of gin-cache

func (Discard) Errorf

func (l Discard) Errorf(string, ...interface{})

Errorf will output the log at error level

type GetCacheStrategyByRequest

type GetCacheStrategyByRequest func(c *gin.Context) (bool, Strategy)

GetCacheStrategyByRequest User can this function to design custom cache strategy by request. The first return value bool means whether this request should be cached. The second return value Strategy determine the special strategy by this request.

type Logger

type Logger interface {
	Errorf(string, ...interface{})
}

Logger define the logger interface

type OnHitCacheCallback

type OnHitCacheCallback func(c *gin.Context)

OnHitCacheCallback define the callback when use cache

type OnMissCacheCallback

type OnMissCacheCallback func(c *gin.Context)

OnMissCacheCallback define the callback when use cache

type OnShareSingleFlightCallback

type OnShareSingleFlightCallback func(c *gin.Context)

OnShareSingleFlightCallback define the callback when share the singleflight result

type Option

type Option func(c *Config)

Option represents the optional function.

func IgnoreQueryOrder

func IgnoreQueryOrder() Option

IgnoreQueryOrder will ignore the queries order in url when generate cache key . This option only takes effect in CacheByRequestURI function

func WithBeforeReplyWithCache

func WithBeforeReplyWithCache(cb BeforeReplyWithCacheCallback) Option

WithBeforeReplyWithCache will be called before replying with cache.

func WithCacheStrategyByRequest

func WithCacheStrategyByRequest(getGetCacheStrategyByRequest GetCacheStrategyByRequest) Option

WithCacheStrategyByRequest set up the custom strategy by per request

func WithLogger

func WithLogger(l Logger) Option

WithLogger set the custom logger

func WithOnHitCache

func WithOnHitCache(cb OnHitCacheCallback) Option

WithOnHitCache will be called when cache hit.

func WithOnMissCache

func WithOnMissCache(cb OnMissCacheCallback) Option

WithOnMissCache will be called when cache miss.

func WithOnShareSingleFlight

func WithOnShareSingleFlight(cb OnShareSingleFlightCallback) Option

WithOnShareSingleFlight will be called when share the singleflight result

func WithPrefixKey

func WithPrefixKey(prefix string) Option

WithPrefixKey will prefix the key

func WithSingleFlightForgetTimeout

func WithSingleFlightForgetTimeout(forgetTimeout time.Duration) Option

WithSingleFlightForgetTimeout to reduce the impact of long tail requests. singleflight.Forget will be called after the timeout has reached for each backend request when timeout is greater than zero.

type ResponseCache

type ResponseCache struct {
	Status int
	Header http.Header
	Data   []byte
}

ResponseCache record the http response cache

type Strategy

type Strategy struct {
	CacheKey string

	// CacheStore if nil, use default cache store instead
	CacheStore persist.CacheStore

	// CacheDuration
	CacheDuration time.Duration
}

Strategy the cache strategy