The proxy_cache_use_stale directive in Nginx allows precise control over serving cached content during updates or backend errors. This feature ensures a seamless user experience by enabling the server to deliver stale cache during cache purging or temporary backend issues.
Example:
location / {
proxy_pass http://backend_server;
proxy_cache my_cache;
# Serve stale content while updating and on specific errors
proxy_cache_use_stale updating timeout;
# Other proxy settings
}- updating: When set to updating, Nginx will serve stale content if it is in the process of updating the cache with a new version of the content from the backend.
- timeout: Specifies additional conditions under which Nginx should serve stale content.
In this example, Nginx will serve stale content if the backend server times out (timeout).
All options
The proxy_cache_use_stale directive in Nginx supports several options to define the conditions under which Nginx should serve stale content. Here is a list of the available options:
- off: Disables serving stale content. Fresh content will always be requested from the backend server.
- error: Serves stale content if there is an error while connecting to the backend server.
- timeout: Serves stale content if there is a timeout while trying to connect to the backend server.
- invalid_header: Serves stale content if the response from the backend server has an invalid header.
- updating: Serves stale content while the cache is being updated with a new version of the content from the backend.
- stale: Always serves stale content, regardless of the state of the cache or the backend server.
- http_500: Serves stale content if the backend server responds with an HTTP status code 500 (Internal Server Error).
- http_502: Serves stale content if the backend server responds with an HTTP status code 502 (Bad Gateway).
- http_503: Serves stale content if the backend server responds with an HTTP status code 503 (Service Unavailable).
- http_504: Serves stale content if the backend server responds with an HTTP status code 504 (Gateway Timeout).
- http_403: Serves stale content if the backend server responds with an HTTP status code 403 (Forbidden).
- http_404: Serves stale content if the backend server responds with an HTTP status code 404 (Not Found).
You can use these options in various combinations to create a custom strategy for serving stale content based on specific conditions that align with your application's requirements. For example:
proxy_cache_use_stale updating http_500 timeout;
In this example, Nginx will serve stale content during cache updates (updating), if the backend responds with a 500 Internal Server Error (http_500), or if there is a timeout (timeout). Adjust the options based on your desired behavior and error-handling strategy.
Use cases:
1. Cache updating:
During cache updating, when a new version of the content is being fetched from the backend, Nginx can serve the stale content to users to avoid disruptions in service.
2. Temporary backend issues:
In case of temporary issues with the backend server (e.g., the backend server is temporarily unreachable or returns an error), Nginx can serve stale content to maintain a seamless user experience.
3. Reducing load on backend:
Serving stale content during peak traffic or when there is a sudden surge in requests can help reduce the load on the backend server.
4. Failover handling:
When using Nginx in a load-balanced environment, serving stale content can act as a failover mechanism if one of the backend servers is temporarily unavailable.
While proxy_cache_use_stale provides a solution for maintaining service continuity during cache updates or temporary backend issues, it's essential to carefully consider its usage based on the specific requirements and characteristics of your application. Adjust the conditions according to your application's behavior and user experience goals.