bug: harden cache middleware key generation and restore Methods config

- Restore configurable Methods field (default: GET, HEAD) to replace hardcoded method check, with uppercase normalization and nil vs empty-slice semantics (nil = default, [] = disable caching)
- Fix escapeKeyDelimiters fast-path bug: backslash was not checked, allowing collisions between literal "\p" and escaped "|"
- Fix path delimiter injection: escape pipe/colon/backslash in request path before boundKeySegment to prevent crafted paths from manipulating cache key structure
- Optimize canonicalQueryString: add single-param fast path (skips url.ParseQuery/sort) and use sync.Pool for output buffer
- Simplify string conversions: replace utils.CopyString(utils.UnsafeString(buf)) with string(buf) and utils.UnsafeBytes(boundKeySegment(...)) with direct string append
- Add comprehensive tests: Methods config (POST caching, bypass, empty-slice, lowercase normalization), escapeKeyDelimiters unit regression test with collision-pair verification
- Update docs: Methods field in config table, default config, and migration guide

Author: ReneWerner87

docs/middleware/cache.md

@@ -120,7 +120,7 @@ This prevents common collisions from path-only keys (for example, `/?id=1` vs `/
 
 The middleware **does not include request body/form values in the default cache key**.
 
-Cache lookup/storage is only applied for `GET` and `HEAD` requests. Other HTTP methods always bypass the cache middleware.
+Cache lookup/storage is applied only for `GET` and `HEAD` requests by default. Other HTTP methods bypass the cache middleware. You can change this via the `Methods` config field.
 
 If a response sets `Vary`, request lookup/storage is also partitioned by those header values unless `DisableVaryHeaders` is `true`. Responses with `Vary: *` remain uncacheable.
 
@@ -138,6 +138,7 @@ If a response sets `Vary`, request lookup/storage is also partitioned by those h
 | DisableQueryKeys     | `bool`                                         | Disables canonicalized query params in keys. | `false` |
 | KeyHeaders           | `[]string`                                     | Header allow-list used for key partitioning. Names are normalized case-insensitively and sorted. Use `[]string{}` to disable header-based partitioning. | `[]string{"accept","accept-encoding","accept-language"}` |
 | KeyCookies           | `[]string`                                     | Optional cookie allow-list for key partitioning. Explicit opt-in only; names remain case-sensitive. | `nil` |
+| Methods              | `[]string`                                     | HTTP methods eligible for caching. Requests whose method is not in this list bypass the cache. | `[]string{fiber.MethodGet, fiber.MethodHead}` |
 | DisableVaryHeaders   | `bool`                                         | Disables response `Vary` dimensions in cache lookup/storage partitioning. | `false` |
 | ExpirationGenerator  | `func(fiber.Ctx, *cache.Config) time.Duration` | ExpirationGenerator allows you to generate custom expiration keys based on the request.                                                                                                                                                                                                                        | `nil`                                                            |
 | Storage              | `fiber.Storage`                                | Storage is used to store the state of the middleware.                                                                                                                                                                                                                                                            | In-memory store                                                  |
@@ -162,6 +163,7 @@ var ConfigDefault = Config{
         fiber.HeaderAcceptLanguage,
     },
     KeyCookies: nil,
+    Methods: []string{fiber.MethodGet, fiber.MethodHead},
     DisableVaryHeaders: false,
     ExpirationGenerator:  nil,
     StoreResponseHeaders: false,

docs/whats_new.md

@@ -1369,7 +1369,7 @@ Cache keys are now redacted in logs and error messages by default, and a `Disabl
 
 The default cache key strategy was also hardened. Instead of path-only behavior, keys now use structured request dimensions: method partitioning, path, canonical query string, and selected representation headers (`Accept`, `Accept-Encoding`, `Accept-Language`). This avoids collisions such as `/items?id=1` vs `/items?id=2` while keeping key generation deterministic. New config fields were added for explicit control: `DisableQueryKeys`, `KeyHeaders`, `KeyCookies`, and `DisableVaryHeaders`.
 
-As a security/performance default, request body/form values are not part of the default cache key. Cache handling is limited to `GET` and `HEAD` requests.
+As a security/performance default, request body/form values are not part of the default cache key. Cache handling is limited to `GET` and `HEAD` requests by default, configurable via the `Methods` field.
 
 :::note
 The deprecated `Store` and `Key` options have been removed in v3. Use `Storage` and `KeyGenerator` instead.
@@ -2890,6 +2890,7 @@ To restore v2 behavior:
 
 Additional v3 cache key options:
 
+- `Methods`: HTTP methods eligible for caching (default `GET`, `HEAD`)
 - `DisableQueryKeys`: disable canonicalized query args in keys (default `false`)
 - `KeyHeaders`: request header allow-list for key partitioning
 - `KeyCookies`: explicit cookie allow-list for key partitioning

middleware/cache/cache.go

@@ -10,6 +10,7 @@ import (
 	"fmt"
 	"math"
 	"net/url"
+	"slices"
 	"sort"
 	"strings"
 	"sync"
@@ -253,8 +254,8 @@ func New(config ...Config) fiber.Handler {
 
 		requestMethod := c.Method()
 
-		// Cache only GET and HEAD requests.
-		if requestMethod != fiber.MethodGet && requestMethod != fiber.MethodHead {
+		// Only cache methods listed in cfg.Methods (default: GET, HEAD).
+		if !slices.Contains(cfg.Methods, requestMethod) {
 			c.Set(cfg.CacheHeader, cacheUnreachable)
 			return c.Next()
 		}
@@ -1284,7 +1285,8 @@ func defaultKeyGenerator(c fiber.Ctx, cfg *Config) string {
 	}
 
 	buf := (*bufPtr)[:0]
-	buf = append(buf, boundKeySegment(c.Path())...)
+	// Escape delimiters in path to prevent crafted paths from injecting key structure
+	buf = append(buf, boundKeySegment(escapeKeyDelimiters(c.Path()))...)
 
 	if !cfg.DisableQueryKeys {
 		buf = append(buf, '|', 'q', '=')
@@ -1301,7 +1303,7 @@ func defaultKeyGenerator(c fiber.Ctx, cfg *Config) string {
 		buf = append(buf, canonicalCookieSubset(c, cfg.KeyCookies)...)
 	}
 
-	result := utils.CopyString(utils.UnsafeString(buf))
+	result := string(buf)
 
 	// Reset buffer and return to pool, but discard if it grew too large
 	// to prevent pool from retaining oversized buffers
@@ -1314,17 +1316,24 @@ func defaultKeyGenerator(c fiber.Ctx, cfg *Config) string {
 }
 
 func canonicalQueryString(uri *fasthttp.URI) string {
-	query := utils.CopyString(utils.UnsafeString(uri.QueryString()))
-	if query == "" {
+	raw := uri.QueryString()
+	if len(raw) == 0 {
 		return ""
 	}
 
-	// Pre-scan query string to detect excessive parameters before expensive parsing
-	// This prevents DoS via url.ParseQuery allocating large maps/slices
+	query := utils.CopyString(utils.UnsafeString(raw))
+
+	// Pre-scan query string to detect excessive parameters before expensive parsing.
+	// This prevents DoS via url.ParseQuery allocating large maps/slices.
 	if len(query) > maxQueryBufferSize {
 		return boundKeySegment(query)
 	}
 
+	// Fast path: single key=value pair needs no parsing or sorting
+	if strings.IndexByte(query, '&') < 0 {
+		return boundKeySegment(query)
+	}
+
 	// Quick count of potential parameters (ampersands + 1)
 	paramCount := 1
 	for i := 0; i < len(query); i++ {
@@ -1357,10 +1366,15 @@ func canonicalQueryString(uri *fasthttp.URI) string {
 	}
 	sort.Strings(keys)
 
-	// Use a bounded buffer to prevent excessive memory allocation during URL escaping
-	// URL escaping can expand strings up to 3x (each byte -> %XX)
-	initialCap := min(len(query)*2, maxQueryBufferSize/2)
-	buf := make([]byte, 0, initialCap)
+	// Use pooled buffer to prevent excessive memory allocation during URL escaping.
+	// URL escaping can expand strings up to 3x (each byte -> %XX).
+	v := keyBufferPool.Get()
+	bufPtr, ok := v.(*[]byte)
+	if !ok || bufPtr == nil {
+		b := make([]byte, 0, defaultKeyBufferCap)
+		bufPtr = &b
+	}
+	buf := (*bufPtr)[:0]
 
 	for _, key := range keys {
 		values := parsed[key]
@@ -1370,12 +1384,15 @@ func canonicalQueryString(uri *fasthttp.URI) string {
 				buf = append(buf, '&')
 			}
 
-			// Check buffer size before appending to prevent unbounded growth
 			escapedKey := url.QueryEscape(key)
 			escapedValue := url.QueryEscape(value)
 
-			// If buffer would exceed safe limits, hash the entire query
+			// Check buffer size before appending to prevent unbounded growth
 			if len(buf)+len(escapedKey)+len(escapedValue)+2 > maxQueryBufferSize {
+				if cap(buf) <= defaultKeyBufferCap*4 {
+					*bufPtr = buf
+					keyBufferPool.Put(bufPtr)
+				}
 				return boundKeySegment(query)
 			}
 
@@ -1385,7 +1402,15 @@ func canonicalQueryString(uri *fasthttp.URI) string {
 		}
 	}
 
-	return boundKeySegment(utils.CopyString(utils.UnsafeString(buf)))
+	result := boundKeySegment(string(buf))
+
+	// Return buffer to pool if not oversized
+	if cap(buf) <= defaultKeyBufferCap*4 {
+		*bufPtr = buf
+		keyBufferPool.Put(bufPtr)
+	}
+
+	return result
 }
 
 func canonicalHeaderSubset(header *fasthttp.RequestHeader, names []string) string {
@@ -1404,10 +1429,10 @@ func canonicalHeaderSubset(header *fasthttp.RequestHeader, names []string) strin
 		headerValue := header.Peek(name)
 		// Escape value to prevent delimiter injection
 		escapedValue := escapeKeyDelimiters(utils.UnsafeString(headerValue))
-		buf = append(buf, utils.UnsafeBytes(boundKeySegment(escapedValue))...)
+		buf = append(buf, boundKeySegment(escapedValue)...)
 	}
 
-	return utils.CopyString(utils.UnsafeString(buf))
+	return string(buf)
 }
 
 func canonicalCookieSubset(c fiber.Ctx, names []string) string {
@@ -1426,17 +1451,17 @@ func canonicalCookieSubset(c fiber.Ctx, names []string) string {
 		cookieValue := c.Cookies(name)
 		// Escape value to prevent delimiter injection
 		escapedValue := escapeKeyDelimiters(cookieValue)
-		buf = append(buf, utils.UnsafeBytes(boundKeySegment(escapedValue))...)
+		buf = append(buf, boundKeySegment(escapedValue)...)
 	}
 
-	return utils.CopyString(utils.UnsafeString(buf))
+	return string(buf)
 }
 
-// escapeKeyDelimiters escapes pipe and colon characters used as delimiters in cache keys
+// escapeKeyDelimiters escapes pipe, colon, and backslash characters used as delimiters in cache keys
 // to prevent injection attacks where crafted values could collide with different inputs
 func escapeKeyDelimiters(s string) string {
-	// Fast path: no delimiters to escape
-	if !strings.ContainsAny(s, "|:") {
+	// Fast path: no characters to escape
+	if !strings.ContainsAny(s, "|:\\") {
 		return s
 	}
 

middleware/cache/cache_security_test.go

@@ -539,3 +539,59 @@ func Test_Cache_Security_DelimiterCollisionPrevention(t *testing.T) {
 		seen[resp] = true
 	}
 }
+
+// Test_Cache_Security_EscapeKeyDelimiters_Unit is a direct regression test for the
+// escapeKeyDelimiters function, ensuring backslashes are escaped to prevent collisions
+// between e.g. a literal "a\pb" and the escaped form of "a|b" → "a\pb".
+func Test_Cache_Security_EscapeKeyDelimiters_Unit(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		input    string
+		expected string
+	}{
+		// Fast path: no special characters
+		{"hello", "hello"},
+		{"", ""},
+		{"foo/bar?baz=1", "foo/bar?baz=1"},
+		// Pipe escaping
+		{"a|b", "a\\pb"},
+		// Colon escaping
+		{"a:b", "a\\cb"},
+		// Backslash escaping (regression: fast path must also check for \)
+		{"a\\b", "a\\\\b"},
+		// Backslash-pipe sequence must not collide with escaped pipe
+		{"a\\pb", "a\\\\pb"}, // literal \p → \\p (differs from escaped | → \p)
+		{"a\\cb", "a\\\\cb"}, // literal \c → \\c (differs from escaped : → \c)
+		// Mixed delimiters
+		{"k|v:w\\x", "k\\pv\\cw\\\\x"},
+		// Multiple consecutive
+		{"||", "\\p\\p"},
+		{"::", "\\c\\c"},
+		{"\\\\", "\\\\\\\\"},
+	}
+
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("escape_%q", tt.input), func(t *testing.T) {
+			t.Parallel()
+			result := escapeKeyDelimiters(tt.input)
+			require.Equal(t, tt.expected, result, "escapeKeyDelimiters(%q)", tt.input)
+		})
+	}
+
+	// Verify no collisions between pairs that would collide without backslash escaping
+	collisionPairs := [][2]string{
+		{"a\\pb", "a|b"}, // literal \p vs escaped |
+		{"a\\cb", "a:b"}, // literal \c vs escaped :
+		{"\\\\", "\\"},   // double backslash vs single
+		{"x\\py", "x|y"},
+	}
+	for _, pair := range collisionPairs {
+		t.Run(fmt.Sprintf("no_collision_%q_vs_%q", pair[0], pair[1]), func(t *testing.T) {
+			t.Parallel()
+			a := escapeKeyDelimiters(pair[0])
+			b := escapeKeyDelimiters(pair[1])
+			require.NotEqual(t, a, b, "escapeKeyDelimiters(%q) must differ from escapeKeyDelimiters(%q)", pair[0], pair[1])
+		})
+	}
+}

middleware/cache/cache_test.go

@@ -964,6 +964,118 @@ func Test_Cache_Post(t *testing.T) {
 	require.Equal(t, "3:12345", string(body))
 }
 
+func Test_Cache_CustomMethods(t *testing.T) {
+	t.Parallel()
+
+	t.Run("POST cached when in Methods", func(t *testing.T) {
+		t.Parallel()
+		app := fiber.New()
+		app.Use(New(Config{
+			Methods: []string{fiber.MethodGet, fiber.MethodHead, fiber.MethodPost},
+		}))
+
+		var count atomic.Int32
+		app.Post("/", func(c fiber.Ctx) error {
+			current := count.Add(1)
+			return c.SendString(strconv.Itoa(int(current)))
+		})
+
+		// First POST — cache miss
+		resp, err := app.Test(httptest.NewRequest(fiber.MethodPost, "/", http.NoBody))
+		require.NoError(t, err)
+		body, err := io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		require.Equal(t, cacheMiss, resp.Header.Get("X-Cache"))
+		require.Equal(t, "1", string(body))
+
+		// Second POST — cache hit
+		resp, err = app.Test(httptest.NewRequest(fiber.MethodPost, "/", http.NoBody))
+		require.NoError(t, err)
+		body, err = io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		require.Equal(t, cacheHit, resp.Header.Get("X-Cache"))
+		require.Equal(t, "1", string(body))
+	})
+
+	t.Run("unconfigured method bypasses cache", func(t *testing.T) {
+		t.Parallel()
+		app := fiber.New()
+		app.Use(New(Config{
+			Methods: []string{fiber.MethodGet},
+		}))
+
+		var count atomic.Int32
+		app.Put("/", func(c fiber.Ctx) error {
+			current := count.Add(1)
+			return c.SendString(strconv.Itoa(int(current)))
+		})
+
+		// PUT not in Methods — always bypasses cache
+		resp, err := app.Test(httptest.NewRequest(fiber.MethodPut, "/", http.NoBody))
+		require.NoError(t, err)
+		require.Equal(t, cacheUnreachable, resp.Header.Get("X-Cache"))
+		require.Equal(t, int32(1), count.Load())
+
+		resp, err = app.Test(httptest.NewRequest(fiber.MethodPut, "/", http.NoBody))
+		require.NoError(t, err)
+		require.Equal(t, cacheUnreachable, resp.Header.Get("X-Cache"))
+		require.Equal(t, int32(2), count.Load(), "handler must be called on every bypass")
+	})
+
+	t.Run("empty Methods slice disables caching", func(t *testing.T) {
+		t.Parallel()
+		app := fiber.New()
+		app.Use(New(Config{
+			Methods: []string{},
+		}))
+
+		var count atomic.Int32
+		app.Get("/", func(c fiber.Ctx) error {
+			current := count.Add(1)
+			return c.SendString(strconv.Itoa(int(current)))
+		})
+
+		// Even GET bypasses cache when Methods is explicitly empty
+		resp, err := app.Test(httptest.NewRequest(fiber.MethodGet, "/", http.NoBody))
+		require.NoError(t, err)
+		require.Equal(t, cacheUnreachable, resp.Header.Get("X-Cache"))
+
+		resp, err = app.Test(httptest.NewRequest(fiber.MethodGet, "/", http.NoBody))
+		require.NoError(t, err)
+		require.Equal(t, cacheUnreachable, resp.Header.Get("X-Cache"))
+		require.Equal(t, int32(2), count.Load(), "handler must be called each time with empty Methods")
+	})
+
+	t.Run("lowercase method names are normalized", func(t *testing.T) {
+		t.Parallel()
+		app := fiber.New()
+		app.Use(New(Config{
+			Methods: []string{"get", "post"},
+		}))
+
+		var count atomic.Int32
+		app.Get("/", func(c fiber.Ctx) error {
+			current := count.Add(1)
+			return c.SendString(strconv.Itoa(int(current)))
+		})
+
+		// "get" should be normalized to "GET" and match
+		resp, err := app.Test(httptest.NewRequest(fiber.MethodGet, "/", http.NoBody))
+		require.NoError(t, err)
+		body, err := io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		require.Equal(t, cacheMiss, resp.Header.Get("X-Cache"))
+		require.Equal(t, "1", string(body))
+
+		resp, err = app.Test(httptest.NewRequest(fiber.MethodGet, "/", http.NoBody))
+		require.NoError(t, err)
+		body, err = io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		require.Equal(t, cacheHit, resp.Header.Get("X-Cache"))
+		require.Equal(t, "1", string(body))
+	})
+}
+
 func Test_Cache_DefaultKeyDimensions(t *testing.T) {
 	t.Parallel()