Added stale directives

For edge cases and better cache hit ratio of unsupporting browsers

Author: dvershinin

README.md

@@ -5,6 +5,19 @@
 
 This tiny NGINX module can help improve caching of your public static assets, by setting far future expiration with `immutable` attribute.
 
+## Intended audience
+
+Websites and frameworks which rely on the cache-busting pattern:
+
+* static resources include version/hashes in their URLs, while never modifying the resources
+* when necessary, updating the resources with newer versions that have new version-numbers/hashes, 
+so that their URLs are different
+
+Popular frameworks which use cache-busting:
+
+* Magento 2
+* Include your own here! 
+
 ## Synopsis
 
 ```
@@ -21,38 +34,73 @@ will yield the following HTTP headers:
 
 ```
 ...
-Cache-Control: public,max-age=31536000,immutable
+Cache-Control: public,max-age=31536000,stale-while-revalidate=31536000,stale-if-error=31536000,immutable
 Expires: Thu, 31 Dec 2037 23:55:55 GMT 
 ...
 ```
 
 How it's different to `expires max;`:
 
-* Sets `immutable` attribute, e.g. `Cache-Control: public,max-age=31536000,immutable` for improved caching
+* Sets `immutable` attribute, e.g. `Cache-Control: public,max-age=31536000,immutable` for improved caching. 
+That is 1 year and not 10 years, see why below.
 * Sends `Expires` only when it's really necessary, e.g. when a client is requesting resources over `HTTP/1.0`
 * Sets `public` attribute to ensure the assets can be cached by public caches, which is typically a desired thing.
 
-Thus, in most cases, `immutable on;` can be used as a better alternative to `expires max;`.
+Due to the [lacking support of `immutable`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#browser_compatibility) in Chromium-based browsers, 
+we also add `stale-while-revalidate=31536000,stale-if-error=31536000` which helps to improve cache hit-ratio in edge cases. 
+Use of these directives allows serving cached responses beyond their cache lifetime, which is forever in case of immutable resources.
+
+Thus, in most cases, `immutable on;` can be used as a better alternative to `expires max;` to implement the cache-busting pattern.
+
+### Why 31536000 seconds (1 year?)
+
+The [RFC](https://www.ietf.org/rfc/rfc2616.txt) defines to use one year to make a response as "never expires":
+
+> To mark a response as “never expires,” an origin server sends an
+> Expires date approximately one year from the time the response is
+> sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one
+> year in the future.
+
+More details in [the article](https://ashton.codes/set-cache-control-max-age-1-year/).
 
 ## Installation 
 
-### CentOS/RHEL 6, 7, 8; Amazon Linux 2; Fedora Linux
+GetPageSpeed provides packaging of the `nginx-module-immutable` in its repositories, as part of its [NGINX Extras](https://nginx-extras.getpagespeed.com/) package collection.
 
-    sudo yum -y install https://extras.getpagespeed.com/release-latest.rpm
-    sudo yum -y install nginx-module-immutable
+The follow operating systems are supported:
+
+* RedHat Enterprise Linux 6, 7, 8, 9
+* CentOS 6, 7, 8, 9
+* AlmaLinux 8, 9
+* Rocky Linux 8, 9
+* Amazon Linux 2
+* Fedora Linux, the 2 most recent releases 
+
+The installation requires a [subscription](https://www.getpagespeed.com/repo-subscribe) for all the operating systems listed, except Fedora Linux, for which it is free.
+
+### How to install
+
+For any OS listed above, installation steps are the same:
+
+```bash```
+sudo yum -y install https://extras.getpagespeed.com/release-latest.rpm
+sudo yum -y install nginx-module-immutable
+```
 
 Follow the installation prompt to import GPG public key that is used for verifying packages.
 
 Then add the following at the top of your `/etc/nginx/nginx.conf`:
 
-    load_module modules/ngx_http_immutable_module.so;
+```nginx
+load_module modules/ngx_http_immutable_module.so;
+```
 
 ## Example: Magento 2 production configuration
 
 Provided that your store runs in production mode, you have already compiled all the assets.
 This [sample config](https://github.com/magento/magento2/blob/2.3.4/nginx.conf.sample#L103-L134) can be optimized to:
 
-```
+```nginx
 location /static/ {
     immutable on;
 
@@ -75,7 +123,7 @@ location /static/ {
 
 When used together with [`ngx_security_headers`](https://github.com/GetPageSpeed/ngx_security_headers), it can be simplified further:
 
-```
+```nginx
 security_headers on;
 
 location /static/ {

src/ngx_http_immutable.c

@@ -185,8 +185,8 @@ ngx_http_immutable_filter(ngx_http_request_t *r)
         }
 #endif
 
-        /* 10 years */
-        ngx_str_set(&cc->value, "public,max-age=31536000,immutable");
+        /* 1 year is the maximum allowed by spec */
+        ngx_str_set(&cc->value, "public,max-age=31536000,stale-while-revalidate=31536000,stale-if-error=31536000,immutable");
     }
 
     /* proceed to the next handler in chain */

t/cc.t

@@ -16,5 +16,5 @@ __DATA__
 --- response_body
 hello world
 --- response_headers
-Cache-Control: public,max-age=31536000,immutable
+Cache-Control: public,max-age=31536000,stale-while-revalidate=31536000,stale-if-error=31536000,immutable