From 58baa3f39cf06fd82106be89a143976c28b21b55 Mon Sep 17 00:00:00 2001 From: Justus K Date: Wed, 2 Dec 2020 20:14:05 +0100 Subject: [PATCH] convert nginx documentation to common mark --- doc/builders/packages/index.xml | 2 +- doc/builders/packages/nginx.section.md | 11 +++++++++++ doc/builders/packages/nginx.xml | 25 ------------------------- 3 files changed, 12 insertions(+), 26 deletions(-) create mode 100644 doc/builders/packages/nginx.section.md delete mode 100644 doc/builders/packages/nginx.xml diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml index ba59ceb016b6..44e89169629d 100644 --- a/doc/builders/packages/index.xml +++ b/doc/builders/packages/index.xml @@ -14,7 +14,7 @@ - + diff --git a/doc/builders/packages/nginx.section.md b/doc/builders/packages/nginx.section.md new file mode 100644 index 000000000000..154c21f9b369 --- /dev/null +++ b/doc/builders/packages/nginx.section.md @@ -0,0 +1,11 @@ +# Nginx {#sec-nginx} + +[Nginx](https://nginx.org) is a reverse proxy and lightweight webserver. + +## ETags on static files served from the Nix store {#sec-nginx-etag} + +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 [`Last-Modified`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) response header automatically; unfortunately, it works by using filesystem timestamps to determine the value of the `Last-Modified` 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). + +Fortunately, HTTP supports an alternative (and more effective) caching mechanism: the [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) response header. The value of the `ETag` 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 `If-None-Match` header. If the ETag value is unchanged, then the server does not need to resend the content. + +As of NixOS 19.09, the nginx package in Nixpkgs is patched such that when nginx serves a file out of `/nix/store`, the hash in the store path is used as the `ETag` 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. diff --git a/doc/builders/packages/nginx.xml b/doc/builders/packages/nginx.xml deleted file mode 100644 index 65854ba02366..000000000000 --- a/doc/builders/packages/nginx.xml +++ /dev/null @@ -1,25 +0,0 @@ -
- Nginx - - - Nginx is a reverse proxy and lightweight webserver. - - -
- ETags on static files served from the Nix store - - - 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 Last-Modified response header automatically; unfortunately, it works by using filesystem timestamps to determine the value of the Last-Modified 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). - - - - Fortunately, HTTP supports an alternative (and more effective) caching mechanism: the ETag response header. The value of the ETag 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 If-None-Match header. If the ETag value is unchanged, then the server does not need to resend the content. - - - - As of NixOS 19.09, the nginx package in Nixpkgs is patched such that when nginx serves a file out of /nix/store, the hash in the store path is used as the ETag 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. - -
-