Nginx proxy_cache_lock: Request Collapsing and Lock Lifecycle Directives

Nginx Cache Population and the Role of proxy_cache_lock

When populating a new cache element, concurrent requests can place unnecessary demand on upstream servers. According to the Nginx ngx_http_proxy_module documentation, the proxy_cache_lock directive minimizes accesses to proxied servers during this initial population process.

The directive is configured with proxy_cache_lock on | off; in the http, server, and location contexts, with a default setting of off. It was introduced in Nginx version 1.1.12. When enabled, only one request at a time is permitted to populate a new cache element identified by the proxy_cache_key directive by forwarding a request to the proxied server.

Request Collapsing and Waiting Behavior

When proxy_cache_lock is set to on, other requests matching the same cache element do not forward to the upstream server immediately. Instead, they wait for either of two events:

• A response appears in the cache.
• The cache lock for that element is released.

Waiting requests remain held up to the duration set by the proxy_cache_lock_timeout directive. The cache element itself is determined by proxy_cache_key. Syntax: proxy_cache_key string; in the http, server, and location contexts. By default, proxy_cache_key is set to $scheme$proxy_host$request_uri, and documentation notes its default evaluation is close to $scheme$proxy_host$uri$is_args$args.

Controlling Lock Lifecycles with proxy_cache_lock_timeout and proxy_cache_lock_age

Nginx provides two directives to govern how long requests wait and when additional upstream requests can be sent:

• proxy_cache_lock_timeout: Sets the timeout for proxy_cache_lock. Syntax: proxy_cache_lock_timeout time;. Default: 5s. Context: http, server, location. This directive appeared in version 1.1.12. When the timeout expires, the waiting request is passed to the proxied server; however, its response will not be cached. (Before version 1.7.8, the response could be cached.)
• proxy_cache_lock_age: Sets a time limit on in-flight population requests. Syntax: proxy_cache_lock_age time;. Default: 5s. Context: http, server, location. This directive appeared in version 1.7.8. If the last request sent to the proxied server to populate a new cache element has not completed within the specified time, one more request may be passed to the proxied server.

Related Cache Revalidation and Stale Directives

The module includes additional directives that manage stale cache handling and background updates:

• proxy_cache_use_stale: Governs when a stale cached response can be used during communication with the proxied server (such as error, timeout, invalid_header, or updating). The updating parameter permits using a stale cached response while an entry is actively updating, minimizing accesses to proxied servers during refreshes. Default: off. Context: http, server, location.
• proxy_cache_revalidate: Enables revalidation of expired cache items using conditional requests with If-Modified-Since and If-None-Match header fields. Syntax: proxy_cache_revalidate on | off;. Default: off. Context: http, server, location. This directive appeared in version 1.5.7.

Research Method and Limitations

This technical summary was prepared exclusively from supplied public documentation excerpts for Nginx’s ngx_http_proxy_module and an excerpt from DigitalOcean. In the supplied excerpt at character 7849, the proxy_cache_key directive is explicitly listed with Context: http , server , location, resolving prior verification checks. The DigitalOcean excerpt contained only general promotional text without technical details on cache locking directives. The primary documentation excerpt contained truncated boundaries; however, all stated directives, syntax forms, defaults, contexts, version histories, and timeout behaviors are explicitly supported by the visible primary text. This overview does not describe unstated directive parameters, third-party modules, or empirical operational benchmarks.