Nginx proxy_cache_revalidate: Enabling Conditional Requests for Expired Cache Items

In Nginx reverse proxy configurations, the proxy_cache_revalidate directive in ngx_http_proxy_module configures how Nginx refreshes expired items in the cache by enabling conditional requests to the proxied server.

What proxy_cache_revalidate Does

According to the official ngx_http_proxy_module documentation, proxy_cache_revalidate enables the revalidation of expired cache items using conditional requests. It uses two header fields when making these requests:

• If-Modified-Since
• If-None-Match

Directive Syntax and Context Scope

The documentation defines the syntax, default setting, context, and version availability for proxy_cache_revalidate as follows:

Because the directive defaults to off, conditional revalidation must be set to on in the configuration where caching is active.

Client Header Handling When Caching Is Enabled

According to the ngx_http_proxy_module documentation, if caching is enabled, the following header fields from the original client request are not passed to the proxied server:

• If-Modified-Since
• If-Unmodified-Since
• If-None-Match
• If-Match
• Range
• If-Range

Tracking Cache and Upstream State

Nginx upstream variables track request processing and cache status. As documented in the ngx_http_upstream_module documentation, the $upstream_cache_status variable records the status of accessing a response cache (introduced in version 0.8.3). Documented status values include MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED, and HIT. In addition, $upstream_bytes_received (introduced in version 1.11.4) records the number of bytes received from an upstream server.

Configuration Example

To enable cache revalidation within a location block alongside a defined upstream group and cache path:

http {
    proxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

    upstream backend {
        server backend1.example.com;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://backend;
            proxy_cache cache_zone;
            proxy_cache_revalidate on;
        }
    }
}

In this configuration, proxy_cache_path defines the cache zone, upstream backend defines the upstream server group, and proxy_pass http://backend; targets that group. Enabling proxy_cache_revalidate on; instructs Nginx to send conditional requests with If-Modified-Since and If-None-Match headers when refreshing expired items stored in cache_zone.

Research Method and Limitations

This answer was prepared solely from the supplied public source excerpts for ngx_http_proxy_module and ngx_http_upstream_module. Material limitations include truncated documentation excerpts in the provided text and unavailable competing coverage. Unseen text, downstream 304 response translation details, and unevidenced operational requirements on upstream responses are omitted.