Document `Cache-Control`

h5bp/web_performance/cache-control.conf

@@ -2,14 +2,38 @@
 # | Cache Control                                                      |
 # ----------------------------------------------------------------------
 
-# Serve resources with appropriate cache control.
+# Serve resources with appropriate cache control directives.
 #
 # The `Cache-Control` header field holds directives (instructions) that control
 # caching in browsers and shared caches (e.g. Proxies, CDNs).
+# Its use targets web performances improvement by specifying the expected
+# client and network caches behaviors.
+#
+# The usable cache directives are listed here:
+# https://www.iana.org/assignments/http-cache-directives/http-cache-directives.xml
+#
+# The cache directives are documented here:
+# https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#response_directives
+#
+# (!) Enable and configure this configuration with care.
+#     Default values should embrace conformance for static files and simple
+#     apps, but cache control definition at backend level is highly preferred.
+#     Incorrect directives can lead to data leaks, or can degrade performances.
+#
+#     More specifically, in-depth understanding on `public` vs `private`
+#     directives meanings is highly recommended. A resource with `public` will
+#     be cached by shared caches like CDN, even if a user session is active.
+#
+# (*) The directive `no-cache` is defined by Nginx `expires` when set on
+#     `epoch`. This ensure a correct value enforcement whenever `Cache-Control`
+#     configuration is used or not.
+#     To avoid value duplication on `Cache-Control`, the directive is skipped
+#     here.
 #
 # https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
 # https://www.rfc-editor.org/rfc/rfc9111.html
 # https://www.rfc-editor.org/rfc/rfc8246.html
+# https://www.rfc-editor.org/rfc/rfc5861.html
 # https://www.iana.org/assignments/http-cache-directives/http-cache-directives.xml
 # https://cache-tests.fyi/
 

nginx.conf

@@ -112,7 +112,7 @@ http {
 
     # Manifest files
     ~*application/manifest\+json      "public";
-    ~*text/cache-manifest             ""; # `no-cache` set by `expire`
+    ~*text/cache-manifest             ""; # `no-cache` (*)
 
     # Assets
     ~*image/svg\+xml                  "public, immutable, stale-while-revalidate";
@@ -126,8 +126,8 @@ http {
     ~*text/calendar                   "private, must-revalidate";
 
     # Data
-    ~*json                            ""; # `no-cache` set by `expire`
-    ~*xml                             ""; # `no-cache` set by `expire`
+    ~*json                            ""; # `no-cache` (*)
+    ~*xml                             ""; # `no-cache` (*)
   }
 
   # Add X-Frame-Options for HTML documents.