Merge pull request NixOS#15006 from roberth/doc-nix-cache-info

doc: add nix-cache-info format documentation

Author: edolstra

doc/manual/source/SUMMARY.md.in

@@ -135,6 +135,7 @@
   - [Serving Tarball Flakes](protocols/tarball-fetcher.md)
   - [Store Path Specification](protocols/store-path.md)
   - [Nix Archive (NAR) Format](protocols/nix-archive/index.md)
+  - [Nix Cache Info Format](protocols/nix-cache-info.md)
   - [Derivation "ATerm" file format](protocols/derivation-aterm.md)
   - [Nix32 Encoding](protocols/nix32.md)
 - [C API](c-api.md)

doc/manual/source/package-management/binary-cache-substituter.md

@@ -19,17 +19,16 @@ whatever port you like:
 $ nix-serve -p 8080
 ```
 
-To check whether it works, try the following on the client:
+To check whether it works, try fetching the [`nix-cache-info`](@docroot@/protocols/nix-cache-info.md) file on the client:
 
 ```console
 $ curl http://avalon:8080/nix-cache-info
+StoreDir: /nix/store
+WantMassQuery: 1
+Priority: 30
 ```
 
-which should print something like:
-
-    StoreDir: /nix/store
-    WantMassQuery: 1
-    Priority: 30
+When writing to a binary cache (e.g., with [`nix copy`](@docroot@/command-ref/new-cli/nix3-copy.md)), Nix creates [`nix-cache-info`](@docroot@/protocols/nix-cache-info.md) automatically if it doesn't exist.
 
 On the client side, you can tell Nix to use your binary cache using
 `--substituters`, e.g.:

doc/manual/source/protocols/nix-cache-info.md

@@ -0,0 +1,55 @@
+# Nix Cache Info Format
+
+The `nix-cache-info` file is a metadata file at the root of a [binary cache](@docroot@/package-management/binary-cache-substituter.md) (e.g., `https://cache.example.com/nix-cache-info`).
+
+MIME type: `text/x-nix-cache-info`
+
+## Format
+
+Line-based key-value format:
+
+```
+Key: value
+```
+
+Leading and trailing whitespace is trimmed from values.
+Lines without a colon are ignored.
+Unknown keys are silently ignored.
+
+## Fields
+
+### `StoreDir`
+
+The Nix store directory path that this cache was built for (e.g., `/nix/store`).
+
+If present, Nix verifies that this matches the client's store directory:
+
+```
+error: binary cache 'https://example.com' is for Nix stores with prefix '/nix/store', not '/home/user/nix/store'
+```
+
+### `WantMassQuery`
+
+`1` or `0`. Sets the default for [`want-mass-query`](@docroot@/store/types/http-binary-cache-store.md#store-http-binary-cache-store-want-mass-query).
+
+### `Priority`
+
+Integer. Sets the default for [`priority`](@docroot@/store/types/http-binary-cache-store.md#store-http-binary-cache-store-priority).
+
+## Example
+
+```
+StoreDir: /nix/store
+WantMassQuery: 1
+Priority: 30
+```
+
+## Caching Behavior
+
+Nix caches `nix-cache-info` in the [cache directory](@docroot@/command-ref/env-common.md#env-NIX_CACHE_HOME) with a 7-day TTL.
+
+## See Also
+
+- [HTTP Binary Cache Store](@docroot@/store/types/http-binary-cache-store.md)
+- [Serving a Nix store via HTTP](@docroot@/package-management/binary-cache-substituter.md)
+- [`substituters`](@docroot@/command-ref/conf-file.md#conf-substituters)