Cache

Cache middleware for Fiber that intercepts responses and stores the body, Content-Type, and status code under a deterministic key derived from request dimensions. Special thanks to @codemicro for contributing this middleware to Fiber core.

By default, cached responses expire after five minutes and the middleware stores up to 1 MB of response bodies.

Request directives

• Cache-Control: no-cache returns the latest response while still caching it, so the status is always miss.
• Cache-Control: no-store skips caching and always forwards a fresh response.

If the response includes a Cache-Control: max-age directive, its value sets the cache entry's expiration.

Cacheable status codes

The middleware caches these RFC 7231 status codes:

• 200: OK
• 203: Non-Authoritative Information
• 204: No Content
• 206: Partial Content
• 300: Multiple Choices
• 301: Moved Permanently
• 404: Not Found
• 405: Method Not Allowed
• 410: Gone
• 414: URI Too Long
• 501: Not Implemented

Responses with other status codes result in an unreachable cache status.

For more about cacheable status codes and RFC 7231, see:

• Cacheable - MDN Web Docs

• RFC7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

Signatures

func New(config ...Config) fiber.Handler

Examples

Import the middleware package:

import (
    "github.com/gofiber/fiber/v3"
    "github.com/gofiber/fiber/v3/middleware/cache"
    "github.com/gofiber/utils/v2"
)

Once your Fiber app is initialized, register the middleware:

// Initialize default config
app.Use(cache.New())

// Or extend the config for customization
app.Use(cache.New(cache.Config{
    Next: func(c fiber.Ctx) bool {
        return fiber.Query[bool](c, "noCache")
    },
    Expiration: 30 * time.Minute,
    DisableCacheControl: true,
}))

Customize expiration and cache key behavior:

app.Use(cache.New(cache.Config{
    ExpirationGenerator: func(c fiber.Ctx, cfg *cache.Config) time.Duration {
        newCacheTime, _ := strconv.Atoi(c.GetRespHeader("Cache-Time", "600"))
        return time.Second * time.Duration(newCacheTime)
    },
    // Optional: fully custom key
    KeyGenerator: func(c fiber.Ctx) string {
        return utils.CopyString(c.Path()) + "|tenant=" + c.Get("X-Tenant-ID")
    },
}))

app.Get("/", func(c fiber.Ctx) error {
    c.Response().Header.Add("Cache-Time", "6000")
    return c.SendString("hi")
})

Use CacheInvalidator to invalidate entries programmatically:

app.Use(cache.New(cache.Config{
    CacheInvalidator: func(c fiber.Ctx) bool {
        return fiber.Query[bool](c, "invalidateCache")
    },
}))

CacheInvalidator defines custom invalidation rules. Return true to bypass the cache. In the example above, setting the invalidateCache query parameter to true invalidates the entry.

Cache keys are masked in logs and error messages by default. Set DisableValueRedaction to true if you explicitly need the raw key for debugging.

Default cache key behavior (safe by default)

By default, cache keys include:

• request method (partitioned internally by the middleware),
• request path,
• canonicalized query string (enabled unless DisableQueryKeys is true),
• representation-driving request headers (accept, accept-encoding, accept-language).

This prevents common collisions from path-only keys (for example, /?id=1 vs /?id=2) while keeping fragmentation bounded.

The middleware does not include request body/form values in the default cache key.

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.

Config

Default Config

var ConfigDefault = Config{
    Next:         nil,
    Expiration:   5 * time.Minute,
    CacheHeader:  "X-Cache",
    DisableCacheControl: false,
    CacheInvalidator: nil,
    DisableValueRedaction: false,
    KeyGenerator: nil, // uses structured default key generator
    DisableQueryKeys: false,
    KeyHeaders: []string{
        fiber.HeaderAccept,
        fiber.HeaderAcceptEncoding,
        fiber.HeaderAcceptLanguage,
    },
    KeyCookies: nil,
    Methods: []string{fiber.MethodGet, fiber.MethodHead},
    DisableVaryHeaders: false,
    ExpirationGenerator:  nil,
    StoreResponseHeaders: false,
    Storage:              nil,
    MaxBytes:             1 * 1024 * 1024,
}