cache

README

cache (This is a community driven project)

English | 中文

This is a middleware for hertz.

Hertz middleware for cache response management with multi-backend support:

• memory
• redis

This repo is forked from gin-cache and adapted for hertz.

Usage

Start using it

Download and install it:

go get github.com/hertz-contrib/cache

Import it in your code:

import "github.com/hertz-contrib/cache"

Basic Examples

memory

package main

import (
    "context"
    "fmt"
    "net/http"
    "sync/atomic"
    "time"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/cache"
    "github.com/hertz-contrib/cache/persist"
)

func main() {
    h := server.New()

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

    var cacheHitCount, cacheMissCount int32

    h.Use(cache.NewCacheByRequestURI(
        memoryStore,
        2*time.Second,
        cache.WithOnHitCache(func(ctx context.Context, c *app.RequestContext) {
            atomic.AddInt32(&cacheHitCount, 1)
        }),
        cache.WithOnMissCache(func(ctx context.Context, c *app.RequestContext) {
            atomic.AddInt32(&cacheMissCount, 1)
        }),
    ))
    h.GET("/hello", func(ctx context.Context, c *app.RequestContext) {
        c.String(http.StatusOK, "hello world")
    })
    h.GET("/get_hit_count", func(ctx context.Context, c *app.RequestContext) {
        c.String(200, fmt.Sprintf("total hit count: %d", cacheHitCount))
    })
    h.GET("/get_miss_count", func(ctx context.Context, c *app.RequestContext) {
        c.String(200, fmt.Sprintf("total miss count: %d", cacheMissCount))
    })

    h.Spin()
}

redis

package main

import (
    "context"
    "net/http"
    "time"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/go-redis/redis/v8"
    "github.com/hertz-contrib/cache"
    "github.com/hertz-contrib/cache/persist"
)

func main() {
    h := server.New()

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

    h.Use(cache.NewCacheByRequestURI(redisStore, 2*time.Second))
    h.GET("/hello", func(ctx context.Context, c *app.RequestContext) {
        c.String(http.StatusOK, "hello world")
    })
    h.Spin()
}

License

This project is under Apache License. See the LICENSE-APACHE file for the full license text.

Documentation

Index

• func NewCache(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, ...) app.HandlerFunc
• func NewCacheByRequestPath(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, ...) app.HandlerFunc
• func NewCacheByRequestURI(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, ...) app.HandlerFunc
• func NewCacheByRequestURIWithIgnoreQueryOrder(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, ...) app.HandlerFunc
• type BeforeReplyWithCacheCallback
• type GetCacheStrategyByRequest
• type OnHitCacheCallback
• type OnMissCacheCallback
• type OnShareSingleFlightCallback
• type Option
  • func WithBeforeReplyWithCache(cb BeforeReplyWithCacheCallback) Option
  • func WithCacheStrategyByRequest(getGetCacheStrategyByRequest GetCacheStrategyByRequest) 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
  • func WithoutHeader(b bool) Option
• type Options
  • func (o *Options) Apply(opts []Option)
• type ResponseCache
• type Strategy

Functions

func NewCache

func NewCache(
	defaultCacheStore persist.CacheStore,
	defaultExpire time.Duration,
	opts ...Option,
) app.HandlerFunc

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

func NewCacheByRequestPath

func NewCacheByRequestPath(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, opts ...Option) app.HandlerFunc

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

func NewCacheByRequestURI

func NewCacheByRequestURI(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, opts ...Option) app.HandlerFunc

NewCacheByRequestURI a shortcut function for caching response by uri

func NewCacheByRequestURIWithIgnoreQueryOrder

func NewCacheByRequestURIWithIgnoreQueryOrder(defaultCacheStore persist.CacheStore, defaultExpire time.Duration, opts ...Option) app.HandlerFunc

NewCacheByRequestURIWithIgnoreQueryOrder a shortcut function for caching response by uri and ignore query param order.

Types

type BeforeReplyWithCacheCallback

type BeforeReplyWithCacheCallback func(c *app.RequestContext, cache *ResponseCache)

type GetCacheStrategyByRequest

type GetCacheStrategyByRequest func(ctx context.Context, c *app.RequestContext) (bool, Strategy)

GetCacheStrategyByRequest User can use 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 OnHitCacheCallback

type OnHitCacheCallback app.HandlerFunc

OnHitCacheCallback define the callback when use cache

type OnMissCacheCallback

type OnMissCacheCallback app.HandlerFunc

OnMissCacheCallback define the callback when use cache

type OnShareSingleFlightCallback

type OnShareSingleFlightCallback func(ctx context.Context, c *app.RequestContext)

OnShareSingleFlightCallback define the callback when share the singleFlight result

type Option

type Option struct {
	F func(o *Options)
}

Option represents the optional 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 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.

func WithoutHeader

func WithoutHeader(b bool) Option

type Options

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

Options contains all options

func (*Options) Apply

func (o *Options) Apply(opts []Option)

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