doc: Explain the nginx ETag patch

https://github.com/NixOS/nixpkgs/issues/25485

1 files changed, 48 insertions, 0 deletions

diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index 12d81ae29bf..54f3079d554 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -918,4 +918,52 @@ citrix_receiver.override {
    </para>
   </section>
  </section>
+ <section xml:id="sec-nginx">
+  <title>Nginx</title>
+
+  <para>
+    <link xlink:href="https://nginx.org/">Nginx</link> is a
+    reverse proxy and lightweight webserver.
+  </para>
+
+  <section xml:id="sec-nginx-etag">
+   <title>ETags on static files served from the Nix store</title>
+
+   <para>
+     HTTP has a couple different mechanisms for caching to prevent
+     clients from having to download the same content repeatedly
+     if a resource has not changed since the last time it was requested.
+     When nginx is used as a server for static files, it implements
+     the caching mechanism based on the
+     <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified"><literal>Last-Modified</literal></link>
+     response header automatically; unfortunately, it works by using
+     filesystem timestamps to determine the value of the
+     <literal>Last-Modified</literal> header. This doesn't give the
+     desired behavior when the file is in the Nix store, because all
+     file timestamps are set to 0 (for reasons related to build
+     reproducibility).
+   </para>
+
+   <para>
+     Fortunately, HTTP supports an alternative (and more effective)
+     caching mechanism: the
+    <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag"><literal>ETag</literal></link>
+    response header. The value of the <literal>ETag</literal> header
+    specifies some identifier for the particular content that the
+    server is sending (e.g. a hash). When a client makes a second
+    request for the same resource, it sends that value back in an
+    <literal>If-None-Match</literal> header. If the ETag value is
+    unchanged, then the server does not need to resend the content.
+   </para>
+
+   <para>
+    As of NixOS 19.09, the nginx package in Nixpkgs is patched such
+    that when nginx serves a file out of <filename>/nix/store</filename>,
+    the hash in the store path is used as the <literal>ETag</literal>
+    header in the HTTP response, thus providing proper caching functionality.
+    This happens automatically; you do not need to do modify any
+    configuration to get this behavior.
+   </para>
+  </section>
+ </section>
 </chapter>