stampede, big upgrade with support for pluggable cache backend

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        go-version: [1.22.x,1.23.x,1.24.x]
+        go-version: [1.23.x,1.24.x]
         os: [ubuntu-latest, macos-latest]
 
     runs-on: ${{ matrix.os }}

README.md

@@ -6,16 +6,18 @@ Prevents cache stampede https://en.wikipedia.org/wiki/Cache_stampede by only run
 single data fetch operation per expired / missing key regardless of number of requests to that key.
 
 
-## Example 1: HTTP Middleware
+## Example: HTTP Middleware
 
 ```go
 import (
+	"log/slog"
 	"net/http"
 	"time"
 
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/go-chi/stampede"
+	memcache "github.com/goware/cachestore-mem"
 )
 
 func main() {
@@ -27,9 +29,17 @@ func main() {
 		w.Write([]byte("index"))
 	})
 
-	cached := stampede.Handler(slog.Default(), 512, 1 * time.Second)
+	cache, err := memcache.NewBackend(1000)
+	if err != nil {
+		panic(err)
+	}
+
+	cacheMiddleware := stampede.Handler(
+		slog.Default(), cache, 5*time.Second,
+		stampede.WithHTTPCacheKeyRequestHeaders([]string{"AuthorizatioN"}),
+	)
 
-	r.With(cached).Get("/cached", func(w http.ResponseWriter, r *http.Request) {
+	r.With(cacheMiddleware).Get("/cached", func(w http.ResponseWriter, r *http.Request) {
 		// processing..
 		time.Sleep(1 * time.Second)
 
@@ -42,37 +52,6 @@ func main() {
 ```
 
 
-## Example 2: Raw
-
-```go
-import (
-	"net/http"
-
-	"github.com/go-chi/stampede"
-)
-
-var (
-	reqCache = stampede.NewCache(512, 5*time.Second, 10*time.Second)
-)
-
-func handler(w http.ResponseWriter, r *http.Request) {	
-	data, err := reqCache.Get(r.Context(), r.URL.Path, fetchData)
-	if err != nil {	
-		w.WriteHeader(503)
-		return	
-	}
-
-	w.Write(data.([]byte))
-}
-
-func fetchData(ctx context.Context) (interface{}, error) {
-	// fetch from remote source.. or compute/render..
-	data := []byte("some response data")
-
-	return data, nil	
-}
-```
-
 ## Notes
 
 * Requests passed through the stampede handler will be batched into a single request
@@ -87,7 +66,8 @@ prevent a stampede scenario on your handler.
 * *Security note:* response headers will be the same for all requests, so make sure
 to not include anything sensitive or user specific. In the case you require user-specific
 stampede handlers, make sure you pass a custom `keyFunc` to the `stampede.Handler` and
-split the cache by an account's id.
+split the cache by an account's id. NOTE: we do avoid caching response headers
+for CORS, set-cookie and x-ratelimit.
 
 See [example](_example/with_key.go) for a variety of examples.
 

_example/go.mod

@@ -1,20 +1,22 @@
 module example
 
-go 1.22
+go 1.23.0
 
-toolchain go1.24.1
+toolchain go1.24.2
 
 replace github.com/go-chi/stampede => ../
 
 require (
 	github.com/go-chi/chi/v5 v5.0.11
 	github.com/go-chi/stampede v0.5.1
+	github.com/goware/cachestore-mem v0.2.1
+	github.com/goware/cachestore2 v0.12.2
 )
 
 require (
+	github.com/elastic/go-freelru v0.16.0 // indirect
 	github.com/goware/singleflight v0.3.0 // indirect
-	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
 	github.com/zeebo/xxh3 v1.0.2 // indirect
-	golang.org/x/sys v0.30.0 // indirect
+	golang.org/x/sys v0.32.0 // indirect
 )

_example/go.sum

@@ -1,24 +1,28 @@
-github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/elastic/go-freelru v0.16.0 h1:gG2HJ1WXN2tNl5/p40JS/l59HjvjRhjyAa+oFTRArYs=
+github.com/elastic/go-freelru v0.16.0/go.mod h1:bSdWT4M0lW79K8QbX6XY2heQYSCqD7THoYf82pT/H3I=
 github.com/go-chi/chi/v5 v5.0.11 h1:BnpYbFZ3T3S1WMpD79r7R5ThWX40TaFB7L31Y8xqSwA=
 github.com/go-chi/chi/v5 v5.0.11/go.mod h1:DslCQbL2OYiznFReuXYUmQ2hGd1aDpCnlMNITLSKoi8=
-github.com/go-chi/cors v1.2.1 h1:xEC8UT3Rlp2QuWNEr4Fs/c2EAGVKBwy/1vHx3bppil4=
-github.com/go-chi/cors v1.2.1/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
+github.com/goware/cachestore-mem v0.2.1 h1:8ZIFtzpoFlwnPUKuGeazhuV2qzR4Bk7UslEGyXRZp9E=
+github.com/goware/cachestore-mem v0.2.1/go.mod h1:0WU95kEa8kmuYSsqOC/fXg/cGVqj5rsTzjUpQgaJHmw=
+github.com/goware/cachestore2 v0.12.2 h1:04YGXkMwbH1xe82siCO7iaPhetntRABN5fWhBKEzduY=
+github.com/goware/cachestore2 v0.12.2/go.mod h1:PR+lXK8UXa/wjKB7mpIj6HtRhC7vbcRXx4b5F1Av/ik=
 github.com/goware/singleflight v0.3.0 h1:b+OM844fuHzanOlE84WeI+G8YMksUY636v0bdcAfnHE=
 github.com/goware/singleflight v0.3.0/go.mod h1:vcmu9KY0BS9WbA3Pn+WOdUQlwT1CPZJm1Fgaz2l88Dc=
-github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
-github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
 github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/testify v1.5.1 h1:nOGnQDM7FYENwehXlg/kFVnos3rEvtKTjRvOWSzb6H4=
-github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
 github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
 github.com/zeebo/xxh3 v1.0.2 h1:xZmwmqxHZA8AI603jOQ0tMqmBr9lPeFwGg6d+xy9DC0=
 github.com/zeebo/xxh3 v1.0.2/go.mod h1:5NWz9Sef7zIDm2JHfFlcQvNekmcEl9ekUZQQKCYaDcA=
-golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
-golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-gopkg.in/yaml.v2 v2.2.2 h1:ZCJp+EgiOT7lHqUV2J862kp8Qj64Jo6az82+3Td9dZw=
-gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+golang.org/x/sync v0.12.0 h1:MHc5BpPuC30uJk597Ri8TV3CNZcTLu6B6z4lJy+g6Jw=
+golang.org/x/sync v0.12.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/sys v0.32.0 h1:s77OFDvIQeibCmezSnk/q6iAfkdiQaJi4VzroCFrN20=
+golang.org/x/sys v0.32.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

_example/simple/main.go

@@ -8,6 +8,7 @@ import (
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/go-chi/stampede"
+	memcache "github.com/goware/cachestore-mem"
 )
 
 func main() {
@@ -19,9 +20,17 @@ func main() {
 		w.Write([]byte("index"))
 	})
 
-	cached := stampede.Handler(slog.Default(), 512, 1*time.Second)
+	cache, err := memcache.NewBackend(1000)
+	if err != nil {
+		panic(err)
+	}
 
-	r.With(cached).Get("/cached", func(w http.ResponseWriter, r *http.Request) {
+	cacheMiddleware := stampede.Handler(
+		slog.Default(), cache, 5*time.Second,
+		stampede.WithHTTPCacheKeyRequestHeaders([]string{"AuthorizatioN"}),
+	)
+
+	r.With(cacheMiddleware).Get("/cached", func(w http.ResponseWriter, r *http.Request) {
 		// processing..
 		time.Sleep(1 * time.Second)
 

_example/with-key/main.go

@@ -9,6 +9,7 @@ import (
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/go-chi/stampede"
+	memcache "github.com/goware/cachestore-mem"
 )
 
 // Example 1: Make two parallel requests:
@@ -67,14 +68,23 @@ func main() {
 		w.Write([]byte("index"))
 	})
 
+	cache, err := memcache.NewBackend(1000)
+	if err != nil {
+		panic(err)
+	}
+
 	// Include anything user specific, e.g. Authorization Token
-	customKeyFunc := func(r *http.Request) (uint64, error) {
+	customCacheKeyFunc := func(r *http.Request) (uint64, error) {
 		token := r.Header.Get("Authorization")
 		return stampede.StringToHash(r.Method, strings.ToLower(strings.ToLower(token))), nil
 	}
-	cached := stampede.HandlerWithKey(slog.Default(), 512, 1*time.Second, customKeyFunc)
 
-	r.With(cached).Get("/me", func(w http.ResponseWriter, r *http.Request) {
+	cacheMiddleware := stampede.HandlerWithKey(
+		slog.Default(), cache, 5*time.Second, customCacheKeyFunc,
+		stampede.WithHTTPCacheKeyRequestBody(false),
+	)
+
+	r.With(cacheMiddleware).Get("/me", func(w http.ResponseWriter, r *http.Request) {
 		// processing..
 		time.Sleep(3 * time.Second)
 

go.mod

@@ -1,21 +1,21 @@
 module github.com/go-chi/stampede
 
-go 1.22
+go 1.23.0
 
-toolchain go1.24.1
+toolchain go1.24.2
 
 require (
 	github.com/go-chi/cors v1.2.1
+	github.com/goware/cachestore2 v0.12.2
 	github.com/goware/singleflight v0.3.0
-	github.com/hashicorp/golang-lru/v2 v2.0.7
-	github.com/stretchr/testify v1.5.1
+	github.com/stretchr/testify v1.10.0
 	github.com/zeebo/xxh3 v1.0.2
 )
 
 require (
-	github.com/davecgh/go-spew v1.1.0 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	golang.org/x/sys v0.30.0 // indirect
-	gopkg.in/yaml.v2 v2.2.2 // indirect
+	golang.org/x/sys v0.32.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,25 +1,24 @@
-github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/go-chi/cors v1.2.1 h1:xEC8UT3Rlp2QuWNEr4Fs/c2EAGVKBwy/1vHx3bppil4=
 github.com/go-chi/cors v1.2.1/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
+github.com/goware/cachestore2 v0.12.2 h1:04YGXkMwbH1xe82siCO7iaPhetntRABN5fWhBKEzduY=
+github.com/goware/cachestore2 v0.12.2/go.mod h1:PR+lXK8UXa/wjKB7mpIj6HtRhC7vbcRXx4b5F1Av/ik=
 github.com/goware/singleflight v0.3.0 h1:b+OM844fuHzanOlE84WeI+G8YMksUY636v0bdcAfnHE=
 github.com/goware/singleflight v0.3.0/go.mod h1:vcmu9KY0BS9WbA3Pn+WOdUQlwT1CPZJm1Fgaz2l88Dc=
-github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
-github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
 github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/testify v1.5.1 h1:nOGnQDM7FYENwehXlg/kFVnos3rEvtKTjRvOWSzb6H4=
-github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
 github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
 github.com/zeebo/xxh3 v1.0.2 h1:xZmwmqxHZA8AI603jOQ0tMqmBr9lPeFwGg6d+xy9DC0=
 github.com/zeebo/xxh3 v1.0.2/go.mod h1:5NWz9Sef7zIDm2JHfFlcQvNekmcEl9ekUZQQKCYaDcA=
-golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
-golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.32.0 h1:s77OFDvIQeibCmezSnk/q6iAfkdiQaJi4VzroCFrN20=
+golang.org/x/sys v0.32.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v2 v2.2.2 h1:ZCJp+EgiOT7lHqUV2J862kp8Qj64Jo6az82+3Td9dZw=
-gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=