diff options
| -rw-r--r-- | doc/package-notes.xml | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/doc/package-notes.xml b/doc/package-notes.xml index 12d81ae29bff..54f3079d5541 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> |