Configuration: HTTP cache

This page documents the cache directive for configuring Ferron’s in-memory HTTP response cache. The cache stores complete GET response representations, serves HEAD from cached GET metadata, follows standard HTTP caching semantics by default, and understands a subset of LiteSpeed Cache response headers for LSCache-aware applications.

The cache applies to final HTTP responses produced by static file serving, reverse proxying, and other response stages.

cache

{
    cache {
        max_entries 2048
    }
}

example.com {
    cache {
        max_response_size 1048576
        litespeed_override_cache_control false
        vary Accept-Encoding Accept-Language
        vary_cookies lang ab_bucket
        ignore Set-Cookie
    }

    location /admin {
        cache false
    }
}

At HTTP host scope, cache can be written either as a block or as a boolean flag. Block form enables caching for that scope and configures nested directives. Boolean form is useful when you want to enable or disable inherited caching without changing any nested settings.

Global cache block

Use the global cache { ... } block to configure shared cache capacity and named cache zones.

Configuration example:

{
    cache {
        max_entries 4096
        zone "shared_assets" {
            max_entries 8192
        }
    }
}

HTTP host cache block

Use the HTTP host cache { ... } block to enable caching and tune how responses are stored for that host or matching location.

Configuration example:

example.com {
    cache {
        max_response_size 2097152
        litespeed_override_cache_control
        emit_litespeed_headers
        vary Accept-Encoding Accept-Language
        vary_cookies lang ab_bucket
        ignore Set-Cookie
    }
}

Boolean cache form

purge_propagation block

Use the purge_propagation { ... } block inside a host cache { ... } block to propagate cache purges to other instances via an external control-plane service. When enabled, Ferron sends a webhook POST to the control-plane whenever a local purge occurs (via PURGE method or X-LiteSpeed-Purge header). The control-plane then broadcasts PURGE requests to all other registered edge instances.

Configuration example:

example.com {
    cache {
        purge_method
        purge_allowed_ips "10.0.0.0/8"
        purge_propagation {
            control_plane_url "http://control-plane:9090/cache/purge"
            shared_secret "my-secret"
            node_id "edge-1"
        }
    }
}

Behavior

Cache eligibility

• Only GET and HEAD requests perform cache lookups.
• HEAD requests reuse cached GET representations and return only headers.
• Non-GET responses are not stored, but they may still trigger LSCache-compatible purge headers.
• Responses with Vary: * are never stored.
• Built-in error responses generated after the main HTTP pipeline are not currently stored.

Cache zones

Cache zones determine which hosts share a physical cache store. There are three zone types:

• Global zone — when a global cache { max_entries = N } block exists (without explicit zone blocks), all hosts share a single cache store by default.
• Named zone — explicitly defined at global scope via zone "name" { max_entries = N }. Multiple hostnames can reference the same named zone.
• Per-host zone — each hostname gets its own independent cache store. Used when no global zone exists and the host does not specify an explicit zone directive.

Global zone (default when a global cache block exists):

{
    cache {
        max_entries 4096
    }
}

example.com {
    cache
}

www.example.com {
    cache
}

In this configuration, both example.com and www.example.com share the same 4096-entry cache store. No explicit zone directive is needed — the global cache block establishes a global zone.

Named zones:

{
    cache {
        max_entries 4096
        zone "shared_assets" {
            max_entries 8192
        }
    }
}

example.com {
    cache {
        zone "shared_assets"
    }
}

www.example.com {
    cache {
        zone "shared_assets"
    }
}

Both hosts share the 8192-entry shared_assets zone.

Opting out of the global zone:

If a global zone exists but a host should have its own isolated cache, use zone with a unique name, or simply specify max_entries in the host block:

{
    cache {
        max_entries 4096
    }
}

example.com {
    cache  # uses global zone
}

admin.example.com {
    cache {
        max_entries 2048  # implicitly creates a per-host zone
    }
}

Here admin.example.com gets its own 2048-entry cache, while example.com shares the global 4096-entry store.

Zone resolution follows this order:

1. Named zone — if the host specifies zone "name", the named zone’s CacheStore is used. Capacity comes from the global zone "name" { max_entries = N } definition.
2. Host-level max_entries — if the host specifies max_entries in its cache block (without zone), an implicit per-host zone is created with that capacity. This overrides the global zone.
3. Global zone — if no zone or host-level max_entries is specified and a global cache { max_entries = N } block exists (without explicit zone blocks), the global CacheStore is used. All hosts without an explicit zone share this store.
4. Per-host zone — if none of the above apply, the hostname is used as the zone ID. Capacity comes from the host-level or global max_entries.

PURGE method cache invalidation

When the purge_method subdirective is enabled, Ferron accepts the PURGE HTTP method for cache invalidation. A PURGE request to a specific URL removes all cached entries (both public and private) matching that URL, causing subsequent requests to fetch fresh content.

Security:

PURGE requests must be either:

• Authenticated via HTTP basic authentication (the basic_auth directive), or
• Originating from an IP address matching the purge_allowed_ips list.

If neither condition is met, Ferron returns a 403 Forbidden response. This ensures that cache purging is never accidentally left unsecured.

Example using trusted IP list:

example.com {
    cache {
        purge_method
        purge_allowed_ips "127.0.0.1" "10.0.0.0/8"
    }
}

Example using basic authentication:

example.com {
    cache {
        purge_method
    }
    basic_auth {
        users {
            user "$argon2id$..."
        }
    }
}

Example request:

PURGE /blog/post-123 HTTP/1.1
Host: example.com

Public and private cache behavior

• Public responses containing Set-Cookie are not stored.
• Private responses are partitioned by client context. Ferron currently uses the client IP address, the authenticated username when available, and detected private cookies.
• If Ferron cannot determine a narrower private cookie set, it falls back to all request cookies for the private cache key.

Stale-while-revalidate

When an upstream response includes the stale-while-revalidate directive in its Cache-Control header, Ferron extends the usable lifetime of the cached entry beyond its max-age. The behavior differs depending on concurrent request patterns:

• Leader request — the first request to encounter the expired entry becomes the leader and revalidates synchronously with the upstream. It receives a fresh response that replaces the cache entry.
• Follower requests — concurrent requests that arrive while the leader is revalidating are served the stale cached response immediately.

This ensures that one request still contacts the upstream for fresh content — no background tasks are involved — while other concurrent requests avoid waiting for revalidation.

The stale-while-revalidate duration is taken from the origin’s Cache-Control header. For example:

Cache-Control: public, max-age=60, stale-while-revalidate=3600

This caches the response for 60 seconds, then allows stale serving for up to 3600 seconds after expiry.

When Ferron serves a stale response via this mechanism, the Cache-Status response header includes detail=stale-while-revalidate:

Cache-Status: FerronCache; hit; detail=stale-while-revalidate,public; age=120

Interaction with must-revalidate and proxy-revalidate

Per RFC 9111, responses with must-revalidate or proxy-revalidate directives (or s-maxage, which implies proxy-revalidate) are never served stale, even within a stale-while-revalidate window. When either directive is present, Ferron treats the entry as strictly fresh-or-miss — it will either revalidate or return a miss rather than serving stale content.

Stale-if-error

When an upstream response includes the stale-if-error directive in its Cache-Control header, Ferron can serve the stale cached response when revalidation fails with a 5xx server error:

Cache-Control: public, max-age=300, stale-if-error=3600

This caches the response for 300 seconds, then allows stale serving on upstream errors for up to 3600 seconds after expiry.

How it works:

1. A request triggers revalidation (e.g., the cached entry has expired, or the client sent Cache-Control: max-age=0).
2. Ferron contacts the upstream, which returns a 5xx status code.
3. If a valid stale entry with stale-if-error exists, Ferron serves the stale response with a Cache-Status header containing detail=stale-while-revalidate.
4. If no stale entry exists or the stale-if-error window has elapsed, Ferron returns the 5xx error to the client.

This provides resilience against transient backend failures by falling back to previously cached content.

LSCache-compatible response headers

When the cache module is enabled, Ferron understands the following response headers from upstream applications and origin handlers:

Cache purge propagation

When purge_propagation is configured, Ferron participates in multi-instance cache invalidation through an external control-plane service. The propagation flow works as follows:

1. Local purge occurs — either via a PURGE HTTP method request or an X-LiteSpeed-Purge response header from the upstream.
2. Webhook sent — Ferron sends an HTTP POST to the configured control_plane_url with a JSON body containing the purged path and the originating node ID.
3. Control-plane broadcasts — the external control-plane sends PURGE requests to all other registered edge instances, excluding the origin.
4. Edges receive purges — other edges receive PURGE requests with an X-Purge-Source: propagation header and execute the purge locally without re-propagating.

Webhook protocol (edge to control-plane):

POST /cache/purge HTTP/1.1
Host: control-plane:9090
Content-Type: application/json
X-Purge-Secret: <shared_secret>

{
  "path": "/blog/post-123",
  "origin": "edge-1"
}

Broadcast protocol (control-plane to edge):

PURGE /blog/post-123 HTTP/1.1
Host: edge-2:80
X-Purge-Source: propagation

Loop prevention:

Ferron uses two mechanisms to prevent infinite purge loops:

• X-Purge-Source: propagation header — when an edge receives a PURGE request with this header, it executes the purge locally but does not forward it to the control-plane. This prevents re-propagation loops.
• Origin exclusion — the control-plane removes the originating node (identified by the origin field in the webhook payload) from its broadcast list, preventing the origin from receiving its own purge back.

Control-plane requirements:

The external control-plane service must:

1. Accept POST requests at the configured URL with a JSON body containing path and origin fields.
2. Authenticate requests using the X-Purge-Secret header.
3. Maintain a list of registered edge instance URLs.
4. Send PURGE requests to all registered edges except the origin, including an X-Purge-Source: propagation header.

Ferron does not include a built-in control-plane — operators can implement one using any HTTP framework or use an existing cache coordination service.

Observability

Metrics

The cache module emits the following metrics:

The ferron.cache.zone attribute identifies which cache zone the request belongs to. It is set to "global" for the shared global zone, the zone name for named zones, or the hostname for per-host zones.

Logs

• DEBUG — logged when Ferron skips cache storage because X-LiteSpeed-Vary: value=... is not supported yet.
• DEBUG — logged when Ferron skips cache storage because the response body exceeds cache.max_response_size.
• DEBUG — logged when Ferron performs a purge through X-LiteSpeed-Purge.
• DEBUG — logged when Ferron performs a purge through PURGE HTTP method.
• DEBUG — logged when Ferron receives an LSCache stale purge marker and falls back to a hard purge.
• WARN — logged when outbound purge propagation to the control-plane fails.

Structured logs

Access log fields

The cache module contributes the following fields to the HTTP access log line:

Trace spans

The cache stage sets the following attributes on its ferron.stage.cache span:

Best practices

The following best-practice checks are reported by ferron doctor for directives on this page.

• litespeed_override_cache_control — This makes LiteSpeed cache headers override standard HTTP cache policy. Enable only for applications that require LiteSpeed-compatible semantics.
• ignore_request_cache_control — When enabled, request-based cache control (e.g., Cache-Control) is ignored in favor of the configured cache policy.
• purge_method without access control — Cache purging enabled without purge_allowed_ips or basic_auth in the same scope allows unauthenticated cache invalidation.
• purge_allowed_ips with wildcard — Allowing every source address for cache purging should be restricted to trusted operators or internal networks.
• control_plane_url without shared_secret — Purge propagation configured without a shared secret allows any source to trigger cache purges across all edge instances.
• control_plane_url using HTTP — Purge webhooks sent over unencrypted HTTP expose the shared secret and purge payloads. Use HTTPS in production environments.