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, except for QUERY requests: per RFC 10008, when QUERY is enabled via Methods the default key generator incorporates the request body so different bodies on the same URL get distinct keys.

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 (for example, adding fiber.MethodQuery). If you supply a custom KeyGenerator and enable a body-bearing method such as QUERY, make sure it incorporates c.Request().Body(), otherwise requests with the same URL but different bodies will collide.

If a response sets Vary, request lookup/storage is also partitioned by those header values unless DisableVaryHeaders is true. Responses with Vary: * remain uncacheable.

Cached redirects

300 and 301 are cacheable statuses, so a redirect can be served from the cache. Its Location is kept with the entry even when StoreResponseHeaders is off, since the status means nothing without it.

Location joins a set the entry always carries, each in a field of its own rather than in the stored header list: Content-Type, Content-Encoding, Cache-Control, Expires, ETag, Date and Age. Those are what the entry needs to be replayed and revalidated at all. StoreResponseHeaders is about every other response header, none of which is kept without it.

Header names

Response field names are matched case-insensitively, as RFC 9110 §5.1 requires, so a handler is free to write cache-control or expires in lower case under DisableHeaderNormalizing. Those values decide what they would decide either way, and the fields this middleware writes itself — Cache-Control, Age, Date, ETag, Expires — replace whatever spelling the response already carries rather than being added beside it.

Responses that are never stored

One entry is served to every client whose request matches its key, so a response that identifies a single client is not stored at all:

• A response that sets a cookie. Set-Cookie means the response has been personalized for the client that caused the miss, and the body — not just the header — is what would be replayed to everyone else. The response still reaches that client normally; only the entry is skipped, and X-Cache reads unreachable.
• A response to a request carrying Authorization, unless the response permits shared caching, per RFC 9111 §3.5.
• Cache-Control: no-store, private, no-cache, or Vary: *.

A route that genuinely wants both a cookie and a shared entry can say so with Cache-Control: public or an s-maxage — directives only a shared cache acts on, so neither is written by accident. must-revalidate and proxy-revalidate do not lift the cookie restriction, even though RFC 9111 §3.5 accepts must-revalidate for the Authorization case: that allowance holds because a revalidating cache returns to the origin and the origin re-checks the credential, and this middleware never revalidates — it serves the stored body for the whole configured Expiration.

Applications that refresh a session cookie on every response will find that most routes stop being cached — that is the point, since those responses are per-client. Set the cookie only where it changes, or mark the genuinely public routes public.

:::caution Register the cache outside any middleware that writes cookies

The check above reads the response as it stands when the cache decides to store it, which is the moment c.Next() returns to the cache middleware. A middleware registered outside the cache does its post-c.Next() work later, so a cookie it writes then is not there to be seen — the entry is stored and the next client reads the first one's body.

Fiber's own session middleware writes its cookie exactly that way, so the order matters:

app.Use(cache.New())    // correct: the cookie is written before the cache decides
app.Use(session.New())

app.Use(session.New())  // leaks: the cookie is written after the cache stored
app.Use(cache.New())

The same applies to any handler wrapper of the form err := c.Next(); c.Cookie(...); return err. Note also that a response personalized from a request cookie without setting one is cached and shared by design — use KeyCookies or Vary: Cookie to key those apart.

:::

Vary and Content-Type

A request Content-Type naming a form is folded to lower case before it is used in the cache key, so the key is the same whether it is built before or after the handler runs — the form accessors fold that header in place, and without this the entry would be stored under a key no lookup produces.

A handler on such a route therefore sees the folded media type even if it never reads a form value: on every request when KeyHeaders names Content-Type, and from the second request on when only Vary does. The boundary keeps its case, and a non-form Content-Type is left alone.

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,
}