improve cache handler, embracing #2210 too

cache/cache.go

@@ -46,8 +46,25 @@ func WithKey(key string) context.Handler {
 	}
 }
 
+// DefaultMaxAge is a function which returns the
+// `context#MaxAge` as time.Duration.
+// It's the default expiration function for the cache handler.
+var DefaultMaxAge = func(ctx *context.Context) time.Duration {
+	return time.Duration(ctx.MaxAge()) * time.Second
+}
+
+// MaxAge is a shortcut to set a simple duration as a MaxAgeFunc.
+//
+// Usage:
+// app.Get("/", cache.Cache(cache.MaxAge(1*time.Minute), mainHandler)
+func MaxAge(dur time.Duration) client.MaxAgeFunc {
+	return func(*context.Context) time.Duration {
+		return dur
+	}
+}
+
 // Cache accepts the cache expiration duration.
-// If the "expiration" input argument is invalid, <=2 seconds,
+// If the "maxAgeFunc" input argument is nil,
 // then expiration is taken by the "cache-control's maxage" header.
 // Returns a Handler structure which you can use to customize cache further.
 //
@@ -57,8 +74,12 @@ func WithKey(key string) context.Handler {
 // may be more suited to your needs.
 //
 // You can add validators with this function.
-func Cache(expiration time.Duration) *client.Handler {
-	return client.NewHandler(expiration)
+func Cache(maxAgeFunc client.MaxAgeFunc) *client.Handler {
+	if maxAgeFunc == nil {
+		maxAgeFunc = DefaultMaxAge
+	}
+
+	return client.NewHandler(maxAgeFunc)
 }
 
 // Handler like `Cache` but returns an Iris Handler to be used as a middleware.
@@ -66,6 +87,10 @@ func Cache(expiration time.Duration) *client.Handler {
 //
 // Examples can be found at: https://github.com/kataras/iris/tree/main/_examples/response-writer/cache
 func Handler(expiration time.Duration) context.Handler {
-	h := Cache(expiration).ServeHTTP
+	maxAgeFunc := func(*context.Context) time.Duration {
+		return expiration
+	}
+
+	h := Cache(maxAgeFunc).ServeHTTP
 	return h
 }

cache/cache_test.go

@@ -162,10 +162,10 @@ func TestCacheValidator(t *testing.T) {
 		ctx.Write([]byte(expectedBodyStr))
 	}
 
-	validCache := cache.Cache(cacheDuration)
-	app.Get("/", validCache.ServeHTTP, h)
+	validCache := cache.Handler(cacheDuration)
+	app.Get("/", validCache, h)
 
-	managedCache := cache.Cache(cacheDuration)
+	managedCache := cache.Cache(cache.MaxAge(cacheDuration))
 	managedCache.AddRule(rule.Validator([]rule.PreValidator{
 		func(ctx *context.Context) bool {
 			// should always invalid for cache, don't bother to go to try to get or set cache
@@ -173,7 +173,7 @@ func TestCacheValidator(t *testing.T) {
 		},
 	}, nil))
 
-	managedCache2 := cache.Cache(cacheDuration)
+	managedCache2 := cache.Cache(cache.MaxAge(cacheDuration))
 	managedCache2.AddRule(rule.Validator(nil,
 		[]rule.PostValidator{
 			func(ctx *context.Context) bool {
@@ -183,7 +183,7 @@ func TestCacheValidator(t *testing.T) {
 		},
 	))
 
-	app.Get("/valid", validCache.ServeHTTP, h)
+	app.Get("/valid", validCache, h)
 
 	app.Get("/invalid", managedCache.ServeHTTP, h)
 	app.Get("/invalid2", managedCache2.ServeHTTP, func(ctx *context.Context) {

cache/client/handler.go

@@ -1,8 +1,8 @@
 package client
 
 import (
+	"net/http"
 	"strings"
-	"sync"
 	"time"
 
 	"github.com/kataras/iris/v12/cache/client/rule"
@@ -23,19 +23,23 @@ type Handler struct {
 	// See more at ruleset.go
 	rule rule.Rule
 	// when expires.
-	expiration time.Duration
+	maxAgeFunc MaxAgeFunc
 	// entries the memory cache stored responses.
-	entries map[string]*entry.Entry
-	mu      sync.RWMutex
+	entryPool  *entry.Pool
+	entryStore entry.Store
 }
 
+type MaxAgeFunc func(*context.Context) time.Duration
+
 // NewHandler returns a new cached handler for the "bodyHandler"
 // which expires every "expiration".
-func NewHandler(expiration time.Duration) *Handler {
+func NewHandler(maxAgeFunc MaxAgeFunc) *Handler {
 	return &Handler{
 		rule:       DefaultRuleSet,
-		expiration: expiration,
-		entries:    make(map[string]*entry.Entry),
+		maxAgeFunc: maxAgeFunc,
+
+		entryPool:  entry.NewPool(),
+		entryStore: entry.NewMemStore(),
 	}
 }
 
@@ -64,14 +68,20 @@ func (h *Handler) AddRule(r rule.Rule) *Handler {
 	return h
 }
 
-var emptyHandler = func(ctx *context.Context) {
-	ctx.StopWithText(500, "cache: empty body handler")
+// Store sets a custom store for this handler.
+func (h *Handler) Store(store entry.Store) *Handler {
+	h.entryStore = store
+	return h
 }
 
-func parseLifeChanger(ctx *context.Context) entry.LifeChanger {
-	return func() time.Duration {
-		return time.Duration(ctx.MaxAge()) * time.Second
-	}
+// MaxAge customizes the expiration duration for this handler.
+func (h *Handler) MaxAge(fn MaxAgeFunc) *Handler {
+	h.maxAgeFunc = fn
+	return h
+}
+
+var emptyHandler = func(ctx *context.Context) {
+	ctx.StopWithText(500, "cache: empty body handler")
 }
 
 const entryKeyContextKey = "iris.cache.server.entry.key"
@@ -133,33 +143,10 @@ func (h *Handler) ServeHTTP(ctx *context.Context) {
 		return
 	}
 
-	var (
-		response *entry.Response
-		valid    = false
-		// unique per subdomains and paths with different url query.
-		key = getOrSetKey(ctx)
-	)
+	key := getOrSetKey(ctx) // unique per subdomains and paths with different url query.
 
-	h.mu.RLock()
-	e, found := h.entries[key]
-	h.mu.RUnlock()
-
-	if found {
-		// the entry is here, .Response will give us
-		// if it's expired or no
-		response, valid = e.Response()
-	} else {
-		// create the entry now.
-		// fmt.Printf("create new cache entry\n")
-		// fmt.Printf("key: %s\n", key)
-
-		e = entry.NewEntry(h.expiration)
-		h.mu.Lock()
-		h.entries[key] = e
-		h.mu.Unlock()
-	}
-
-	if !valid {
+	e := h.entryStore.Get(key)
+	if e == nil {
 		// if it's expired, then execute the original handler
 		// with our custom response recorder response writer
 		// because the net/http doesn't give us
@@ -182,30 +169,61 @@ func (h *Handler) ServeHTTP(ctx *context.Context) {
 			return
 		}
 
-		// check for an expiration time if the
-		// given expiration was not valid then check for GetMaxAge &
-		// update the response & release the recorder
-		e.Reset(
-			recorder.StatusCode(),
-			recorder.Header(),
-			body,
-			parseLifeChanger(ctx),
-		)
-
 		// fmt.Printf("reset cache entry\n")
 		// fmt.Printf("key: %s\n", key)
 		// fmt.Printf("content type: %s\n", recorder.Header().Get(cfg.ContentTypeHeader))
 		// fmt.Printf("body len: %d\n", len(body))
+
+		r := entry.NewResponse(recorder.StatusCode(), recorder.Header(), body)
+		e = h.entryPool.Acquire(h.maxAgeFunc(ctx), r, func() {
+			h.entryStore.Delete(key)
+		})
+
+		h.entryStore.Set(key, e)
 		return
 	}
 
 	// if it's valid then just write the cached results
-	entry.CopyHeaders(ctx.ResponseWriter().Header(), response.Headers())
+	r := e.Response()
+	// if !ok {
+	// 	// it shouldn't be happen because if it's not valid (= expired)
+	// 	// then it shouldn't be found on the store, we return as it is, the body was written.
+	// 	return
+	// }
+
+	copyHeaders(ctx.ResponseWriter().Header(), r.Headers())
 	ctx.SetLastModified(e.LastModified)
-	ctx.StatusCode(response.StatusCode())
-	ctx.Write(response.Body())
+	ctx.StatusCode(r.StatusCode())
+	ctx.Write(r.Body())
 
 	// fmt.Printf("key: %s\n", key)
 	// fmt.Printf("write content type: %s\n", response.Headers()["ContentType"])
 	// fmt.Printf("write body len: %d\n", len(response.Body()))
 }
+
+func copyHeaders(dst, src http.Header) {
+	// Clone returns a copy of h or nil if h is nil.
+	if src == nil {
+		return
+	}
+
+	// Find total number of values.
+	nv := 0
+	for _, vv := range src {
+		nv += len(vv)
+	}
+
+	sv := make([]string, nv) // shared backing array for headers' values
+	for k, vv := range src {
+		if vv == nil {
+			// Preserve nil values. ReverseProxy distinguishes
+			// between nil and zero-length header values.
+			dst[k] = nil
+			continue
+		}
+
+		n := copy(sv, vv)
+		dst[k] = sv[:n:n]
+		sv = sv[n:]
+	}
+}

cache/entry/entry.go

@@ -3,15 +3,14 @@ package entry
 import (
 	"time"
 
-	"github.com/kataras/iris/v12/cache/cfg"
+	"github.com/kataras/iris/v12/core/memstore"
 )
 
 // Entry is the cache entry
 // contains the expiration datetime and the response
 type Entry struct {
-	life time.Duration
 	// ExpiresAt is the time which this cache will not be available
-	expiresAt time.Time
+	lifeTime *memstore.LifeTime
 
 	// when `Reset` this value is reseting to time.Now(),
 	// it's used to send the "Last-Modified" header,
@@ -25,104 +24,30 @@ type Entry struct {
 	// of store map
 }
 
-// NewEntry returns a new cache entry
-// it doesn't sets the expiresAt & the response
-// because these are setting each time on Reset
-func NewEntry(duration time.Duration) *Entry {
-	// if given duration is not <=0 (which means finds from the headers)
-	// then we should check for the MinimumCacheDuration here
-	if duration >= 0 && duration < cfg.MinimumCacheDuration {
-		duration = cfg.MinimumCacheDuration
-	}
-
-	return &Entry{
-		life:     duration,
-		response: &Response{},
-	}
+// reset called each time a new entry is acquired from the pool.
+func (e *Entry) reset(lt *memstore.LifeTime, r *Response) {
+	e.response = r
+	e.LastModified = lt.Begun
 }
 
-// Response gets the cache response contents
-// if it's valid returns them with a true value
-// otherwise returns nil, false
-func (e *Entry) Response() (*Response, bool) {
-	if !e.valid() {
-		// it has been expired
-		return nil, false
-	}
-	return e.response, true
+// Response returns the cached response as it's.
+func (e *Entry) Response() *Response {
+	return e.response
 }
 
-// valid returns true if this entry's response is still valid
-// or false if the expiration time passed
-func (e *Entry) valid() bool {
-	return !time.Now().After(e.expiresAt)
-}
+// // Response gets the cache response contents
+// // if it's valid returns them with a true value
+// // otherwise returns nil, false
+// func (e *Entry) Response() (*Response, bool) {
+// 	if !e.isValid() {
+// 		// it has been expired
+// 		return nil, false
+// 	}
+// 	return e.response, true
+// }
 
-// LifeChanger is the function which returns
-// a duration which will be compared with the current
-// entry's (cache life)  duration
-// and execute the LifeChanger func
-// to set the new life time
-type LifeChanger func() time.Duration
-
-// ChangeLifetime modifies the life field
-// which is the life duration of the cached response
-// of this cache entry
-//
-// useful when we find a max-age header from the handler
-func (e *Entry) ChangeLifetime(fdur LifeChanger) {
-	if e.life < cfg.MinimumCacheDuration {
-		newLifetime := fdur()
-		if newLifetime > e.life {
-			e.life = newLifetime
-		} else {
-			// if even the new lifetime is less than MinimumCacheDuration
-			// then change set it explicitly here
-			e.life = cfg.MinimumCacheDuration
-		}
-	}
-}
-
-// CopyHeaders clones headers "src" to "dst" .
-func CopyHeaders(dst map[string][]string, src map[string][]string) {
-	if dst == nil || src == nil {
-		return
-	}
-
-	for k, vv := range src {
-		v := make([]string, len(vv))
-		copy(v, vv)
-		dst[k] = v
-	}
-}
-
-// Reset called each time the entry is expired
-// and the handler calls this after the original handler executed
-// to re-set the response with the new handler's content result
-func (e *Entry) Reset(statusCode int, headers map[string][]string,
-	body []byte, lifeChanger LifeChanger) {
-	if e.response == nil {
-		e.response = &Response{}
-	}
-	if statusCode > 0 {
-		e.response.statusCode = statusCode
-	}
-
-	if len(headers) > 0 {
-		newHeaders := make(map[string][]string, len(headers))
-		CopyHeaders(newHeaders, headers)
-		e.response.headers = newHeaders
-	}
-
-	e.response.body = make([]byte, len(body))
-	copy(e.response.body, body)
-	// check if a given life changer provided
-	// and if it does then execute the change life time
-	if lifeChanger != nil {
-		e.ChangeLifetime(lifeChanger)
-	}
-
-	now := time.Now()
-	e.expiresAt = now.Add(e.life)
-	e.LastModified = now
-}
+// // isValid reports whether this entry's response is still valid or expired.
+// // If the entry exists in the store then it should be valid anyways.
+// func (e *Entry) isValid() bool {
+// 	return !e.lifeTime.HasExpired()
+// }

cache/entry/pool.go

@@ -0,0 +1,69 @@
+package entry
+
+import (
+	"sync"
+	"time"
+
+	"github.com/kataras/iris/v12/cache/cfg"
+	"github.com/kataras/iris/v12/core/memstore"
+)
+
+// Pool is the context pool, it's used inside router and the framework by itself.
+type Pool struct {
+	pool *sync.Pool
+}
+
+// NewPool creates and returns a new context pool.
+func NewPool() *Pool {
+	return &Pool{pool: &sync.Pool{New: func() any { return &Entry{} }}}
+}
+
+// func NewPool(newFunc func() any) *Pool {
+// 	return &Pool{pool: &sync.Pool{New: newFunc}}
+// }
+
+// Acquire returns an Entry from pool.
+// See Release.
+func (c *Pool) Acquire(lifeDuration time.Duration, r *Response, onExpire func()) *Entry {
+	// If the given duration is not <=0 (which means finds from the headers)
+	// then we should check for the MinimumCacheDuration here
+	if lifeDuration >= 0 && lifeDuration < cfg.MinimumCacheDuration {
+		lifeDuration = cfg.MinimumCacheDuration
+	}
+
+	e := c.pool.Get().(*Entry)
+
+	lt := memstore.NewLifeTime()
+	lt.Begin(lifeDuration, func() {
+		onExpire()
+		c.release(e)
+	})
+
+	e.reset(lt, r)
+	return e
+}
+
+// Release puts an Entry back to its pull, this function releases its resources.
+// See Acquire.
+func (c *Pool) release(e *Entry) {
+	e.response.body = nil
+	e.response.headers = nil
+	e.response.statusCode = 0
+	e.response = nil
+
+	// do not call it, it contains a lock too, release is controlled only inside the Acquire itself when the entry is expired.
+	// if e.lifeTime != nil {
+	// 	e.lifeTime.ExpireNow() // stop any opening timers if force released.
+	// }
+
+	c.pool.Put(e)
+}
+
+// Release can be called by custom stores to release an entry.
+func (c *Pool) Release(e *Entry) {
+	if e.lifeTime != nil {
+		e.lifeTime.ExpireNow() // stop any opening timers if force released.
+	}
+
+	c.release(e)
+}

cache/entry/response.go

@@ -1,6 +1,9 @@
 package entry
 
-import "net/http"
+import (
+	"io"
+	"net/http"
+)
 
 // Response is the cached response will be send to the clients
 // its fields set at runtime on each of the non-cached executions
@@ -15,11 +18,28 @@ type Response struct {
 	headers http.Header
 }
 
+// NewResponse returns a new cached Response.
+func NewResponse(statusCode int, headers http.Header, body []byte) *Response {
+	r := new(Response)
+
+	r.SetStatusCode(statusCode)
+	r.SetHeaders(headers)
+	r.SetBody(body)
+
+	return r
+}
+
+// SetStatusCode sets a valid status code.
+func (r *Response) SetStatusCode(statusCode int) {
+	if statusCode <= 0 {
+		statusCode = http.StatusOK
+	}
+
+	r.statusCode = statusCode
+}
+
 // StatusCode returns a valid status code.
 func (r *Response) StatusCode() int {
-	if r.statusCode <= 0 {
-		r.statusCode = 200
-	}
 	return r.statusCode
 }
 
@@ -31,12 +51,39 @@ func (r *Response) StatusCode() int {
 // 	return r.contentType
 // }
 
+// SetHeaders sets a clone of headers of the cached response.
+func (r *Response) SetHeaders(h http.Header) {
+	r.headers = h.Clone()
+}
+
 // Headers returns the total headers of the cached response.
 func (r *Response) Headers() http.Header {
 	return r.headers
 }
 
+// SetBody consumes "b" and sets the body of the cached response.
+func (r *Response) SetBody(body []byte) {
+	r.body = make([]byte, len(body))
+	copy(r.body, body)
+}
+
 // Body returns contents will be served by the cache handler.
 func (r *Response) Body() []byte {
 	return r.body
 }
+
+// Read implements the io.Reader interface.
+func (r *Response) Read(b []byte) (int, error) {
+	if len(r.body) == 0 {
+		return 0, io.EOF
+	}
+
+	n := copy(b, r.body)
+	r.body = r.body[n:]
+	return n, nil
+}
+
+// Bytes returns a copy of the cached response body.
+func (r *Response) Bytes() []byte {
+	return append([]byte(nil), r.body...)
+}

cache/entry/store.go

@@ -0,0 +1,52 @@
+package entry
+
+import (
+	"sync"
+)
+
+// Store is the interface which is responsible to store the cache entries.
+type Store interface {
+	// Get returns an entry based on its key.
+	Get(key string) *Entry
+	// Set sets an entry based on its key.
+	Set(key string, e *Entry)
+	// Delete deletes an entry based on its key.
+	Delete(key string)
+}
+
+// memStore is the default in-memory store for the cache entries.
+type memStore struct {
+	entries map[string]*Entry
+	mu      sync.RWMutex
+}
+
+var _ Store = (*memStore)(nil)
+
+// NewMemStore returns a new in-memory store for the cache entries.
+func NewMemStore() Store {
+	return &memStore{
+		entries: make(map[string]*Entry),
+	}
+}
+
+// Get returns an entry based on its key.
+func (s *memStore) Get(key string) *Entry {
+	s.mu.RLock()
+	e := s.entries[key]
+	s.mu.RUnlock()
+	return e
+}
+
+// Set sets an entry based on its key.
+func (s *memStore) Set(key string, e *Entry) {
+	s.mu.Lock()
+	s.entries[key] = e
+	s.mu.Unlock()
+}
+
+// Delete deletes an entry based on its key.
+func (s *memStore) Delete(key string) {
+	s.mu.Lock()
+	delete(s.entries, key)
+	s.mu.Unlock()
+}

cache/entry/util.go

@@ -1,24 +0,0 @@
-package entry
-
-import (
-	"regexp"
-	"strconv"
-)
-
-var maxAgeExp = regexp.MustCompile(`maxage=(\d+)`)
-
-// ParseMaxAge parses the max age from the receiver parameter, "cache-control" header
-// returns seconds as int64
-// if header not found or parse failed then it returns -1
-func ParseMaxAge(header string) int64 {
-	if header == "" {
-		return -1
-	}
-	m := maxAgeExp.FindStringSubmatch(header)
-	if len(m) == 2 {
-		if v, err := strconv.Atoi(m[1]); err == nil {
-			return int64(v)
-		}
-	}
-	return -1
-}