From 8101e7a45f7bcf1c5144eae956594122aabf2565 Mon Sep 17 00:00:00 2001
From: Florian Klink <flokli@flokli.de>
Date: Mon, 24 Mar 2025 13:50:11 +0000
Subject: [PATCH] docs(reference/nix-daemon-protocol): migrate

This moves the daemon protocol reference to the "Reference" section in
our new docs.

It also updates them a bit, we now use `{{< relref "path/to/file.md" >}}`
to refer to other files, and fixes the (previously broken) references
in handshake.md.

Change-Id: I114e40622dc504e7a5f75946895900e797a1e722
Reviewed-on: https://cl.snix.dev/c/snix/+/30273
Autosubmit: Florian Klink <flokli@flokli.de>
Tested-by: besadii
Reviewed-by: Brian Olsen <brian@maven-group.org>
---
 snix/docs/src/SUMMARY.md                      |  6 --
 snix/docs/src/nix-daemon/handshake.md         | 32 --------
 web/content/docs/reference/_index.md          |  2 +-
 .../reference/nix-daemon-protocol/_index.md   | 11 +++
 .../nix-daemon-protocol}/changelog.md         | 19 +++++
 .../nix-daemon-protocol/handshake.md          | 49 ++++++++++++
 .../reference/nix-daemon-protocol/intro.md    | 20 +++--
 .../reference/nix-daemon-protocol}/logging.md | 12 ++-
 .../nix-daemon-protocol}/operations.md        | 80 +++++++++++--------
 .../nix-daemon-protocol}/serialization.md     | 13 +++
 10 files changed, 165 insertions(+), 79 deletions(-)
 delete mode 100644 snix/docs/src/nix-daemon/handshake.md
 create mode 100644 web/content/docs/reference/nix-daemon-protocol/_index.md
 rename {snix/docs/src/nix-daemon => web/content/docs/reference/nix-daemon-protocol}/changelog.md (96%)
 create mode 100644 web/content/docs/reference/nix-daemon-protocol/handshake.md
 rename snix/docs/src/nix-daemon/index.md => web/content/docs/reference/nix-daemon-protocol/intro.md (50%)
 rename {snix/docs/src/nix-daemon => web/content/docs/reference/nix-daemon-protocol}/logging.md (96%)
 rename {snix/docs/src/nix-daemon => web/content/docs/reference/nix-daemon-protocol}/operations.md (90%)
 rename {snix/docs/src/nix-daemon => web/content/docs/reference/nix-daemon-protocol}/serialization.md (98%)

diff --git a/snix/docs/src/SUMMARY.md b/snix/docs/src/SUMMARY.md
index 40d44965e..2cb82d266 100644
--- a/snix/docs/src/SUMMARY.md
+++ b/snix/docs/src/SUMMARY.md
@@ -28,9 +28,3 @@
 - [Specification of the Nix Language](./language-spec.md)
 - [Nix language version history](./lang-version.md)
 - [Value Pointer Equality](./value-pointer-equality.md)
-- [Daemon Protocol](./nix-daemon/index.md)
-  - [Handshake](./nix-daemon/handshake.md)
-  - [Logging](./nix-daemon/logging.md)
-  - [Operations](./nix-daemon/operations.md)
-  - [Serialization](./nix-daemon/serialization.md)
-  - [Changelog](./nix-daemon/changelog.md)
diff --git a/snix/docs/src/nix-daemon/handshake.md b/snix/docs/src/nix-daemon/handshake.md
deleted file mode 100644
index a706ca367..000000000
--- a/snix/docs/src/nix-daemon/handshake.md
+++ /dev/null
@@ -1,32 +0,0 @@
-
-
-## client -> server
-- 0x6e697863 :: [Int](#int) (hardcoded, 'nixc' in ASCII)
-
-## client <- server
-- 0x6478696f :: [Int](#int) (hardcoded, 'dxio' in ASCII)
-- protocolVersion :: [Int](#int)
-
-## client -> server
-- clientVersion :: [Int](#int)
-
-### If clientVersion is 1.14 or later
-- sendCpu :: [Bool](#bool) (hardcoded to false in client)
-#### If sendCpu is true
-- cpuAffinity :: [Int](#int) (obsolete and ignored)
-
-### If clientVersion is 1.11 or later
-- reserveSpace :: [Bool](#bool) (obsolete, ignored and set to false)
-
-
-## client <- server
-
-### If clientVersion is 1.33 or later
-- nixVersion :: String
-
-### If clientVersion is 1.35 or later
-- trusted :: OptTrusted
-
-## client <- server
-- send logs
-- [operation](./operations.md) :: Int
diff --git a/web/content/docs/reference/_index.md b/web/content/docs/reference/_index.md
index 428e4a65c..75e2083b4 100644
--- a/web/content/docs/reference/_index.md
+++ b/web/content/docs/reference/_index.md
@@ -5,7 +5,7 @@ summary: ""
 date: 2023-09-07T16:12:37+02:00
 lastmod: 2023-09-07T16:12:37+02:00
 draft: false
-weight: 900
+weight: 50
 toc: true
 sidebar:
   collapsed: true
diff --git a/web/content/docs/reference/nix-daemon-protocol/_index.md b/web/content/docs/reference/nix-daemon-protocol/_index.md
new file mode 100644
index 000000000..3492d9ea3
--- /dev/null
+++ b/web/content/docs/reference/nix-daemon-protocol/_index.md
@@ -0,0 +1,11 @@
+---
+title: Nix Daemon Protocol
+slug: nix-daemon-protocol
+description: ""
+summary: ""
+date: 2025-03-24T13:10:37+02:00
+lastmod: 2025-03-24T13:10:37+02:00
+draft: false
+weight: 50
+toc: true
+---
diff --git a/snix/docs/src/nix-daemon/changelog.md b/web/content/docs/reference/nix-daemon-protocol/changelog.md
similarity index 96%
rename from snix/docs/src/nix-daemon/changelog.md
rename to web/content/docs/reference/nix-daemon-protocol/changelog.md
index 4cc1ccbbd..3460376a7 100644
--- a/snix/docs/src/nix-daemon/changelog.md
+++ b/web/content/docs/reference/nix-daemon-protocol/changelog.md
@@ -1,4 +1,21 @@
+---
+title: Changelog
+slug: Changelog
+description: ""
+summary: ""
+date: 2025-03-24T13:10:37+02:00
+lastmod: 2025-03-24T13:10:37+02:00
+draft: false
+weight: 55
+toc: true
+---
 
+This page tracks the different protocol versions and corresponding Nix versions,
+as well as when certain [Operations][operations] have been introduced or
+deprecated.
+
+Different "function signatures" are tracked on the [Operations][operations] page
+as well.
 
 ## Nix version protocol
 
@@ -200,3 +217,5 @@ Protocol version that ends with * was bumped while adding that operation. Otherw
 [f3441e6122]: https://github.com/NixOS/nix/commit/f3441e6122
 [f92c9a0ac5]: https://github.com/NixOS/nix/commit/f92c9a0ac5
 [fe1f34fa60]: https://github.com/NixOS/nix/commit/fe1f34fa60
+
+[operations]: {{< relref "operations.md" >}}
diff --git a/web/content/docs/reference/nix-daemon-protocol/handshake.md b/web/content/docs/reference/nix-daemon-protocol/handshake.md
new file mode 100644
index 000000000..d541530ff
--- /dev/null
+++ b/web/content/docs/reference/nix-daemon-protocol/handshake.md
@@ -0,0 +1,49 @@
+---
+title: Handshake
+slug: handshake
+description: ""
+summary: ""
+date: 2025-03-24T13:10:37+02:00
+lastmod: 2025-03-24T13:10:37+02:00
+draft: false
+weight: 51
+toc: true
+---
+
+When connecting, the handshake sequence documented below must be performed, so
+client and server can agree on a protocol version to use and exchange some
+parameters.
+
+## client -> server
+- 0x6e697863 :: [Int](#se-Int) (hardcoded, 'nixc' in ASCII)
+
+## client <- server
+- 0x6478696f :: [Int](#se-Int) (hardcoded, 'dxio' in ASCII)
+- protocolVersion :: [Int](#se-Int)
+
+## client -> server
+- clientVersion :: [Int](#se-Int)
+
+### If clientVersion is 1.14 or later
+- sendCpu :: [Bool](#se-Bool) (hardcoded to false in client)
+#### If sendCpu is true
+- cpuAffinity :: [Int](#se-Int) (obsolete and ignored)
+
+### If clientVersion is 1.11 or later
+- reserveSpace :: [Bool](#se-Bool) (obsolete, ignored and set to false)
+
+
+## client <- server
+
+### If clientVersion is 1.33 or later
+- nixVersion :: String
+
+### If clientVersion is 1.35 or later
+- trusted :: OptTrusted
+
+## client <- server
+- send logs
+- [operation]({{< relref "operations.md" >}}) :: [Int](#se-Int)
+
+[se-Int]: {{< relref "serialization.md" >}}#int
+[se-Bool]: {{< relref "serialization.md" >}}#bool
diff --git a/snix/docs/src/nix-daemon/index.md b/web/content/docs/reference/nix-daemon-protocol/intro.md
similarity index 50%
rename from snix/docs/src/nix-daemon/index.md
rename to web/content/docs/reference/nix-daemon-protocol/intro.md
index e47c20151..9925c3b5d 100644
--- a/snix/docs/src/nix-daemon/index.md
+++ b/web/content/docs/reference/nix-daemon-protocol/intro.md
@@ -1,15 +1,25 @@
-# Nix Daemon Protocol
+---
+title: Intro
+slug: Intro
+description: ""
+summary: ""
+date: 2025-03-24T13:10:37+02:00
+lastmod: 2025-03-24T13:10:37+02:00
+draft: false
+weight: 50
+toc: true
+---
 
 The Nix Daemon protocol is what's used to communicate with the `nix-daemon`,
 either on the local system (in which case the communication happens via a Unix
 domain socket), or with a remote Nix (in which this is tunneled over SSH).
 
-It uses a custom binary format which isn't too documented. The subpages here
-collect serve as an in-depth detail about some of the inner workings, data types
-etc.
+It uses a custom binary format which isn't too documented. This reference here
+aims to serve as an in-depth documentation about some of the inner workings,
+data types etc.
 
 A first implementation of this exists in
 [griff/Nix.rs](https://github.com/griff/Nix.rs/tree/main).
 
 Work is underway to port / factor this out into reusable building blocks into
-the [nix-compat] crate.
+the [nix-compat](https://snix.dev//rustdoc/nix_compat/index.html) crate.
diff --git a/snix/docs/src/nix-daemon/logging.md b/web/content/docs/reference/nix-daemon-protocol/logging.md
similarity index 96%
rename from snix/docs/src/nix-daemon/logging.md
rename to web/content/docs/reference/nix-daemon-protocol/logging.md
index 885748848..8243a7c44 100644
--- a/snix/docs/src/nix-daemon/logging.md
+++ b/web/content/docs/reference/nix-daemon-protocol/logging.md
@@ -1,4 +1,14 @@
-# Logging
+---
+title: Logging
+slug: logging
+description: ""
+summary: ""
+date: 2025-03-24T13:10:37+02:00
+lastmod: 2025-03-24T13:10:37+02:00
+draft: false
+weight: 54
+toc: true
+---
 
 Because the daemon protocol only has one sender stream and one receiver stream
 logging messages need to be carefully interleaved with requests and responses.
diff --git a/snix/docs/src/nix-daemon/operations.md b/web/content/docs/reference/nix-daemon-protocol/operations.md
similarity index 90%
rename from snix/docs/src/nix-daemon/operations.md
rename to web/content/docs/reference/nix-daemon-protocol/operations.md
index f80aa36b0..7a4090cfc 100644
--- a/snix/docs/src/nix-daemon/operations.md
+++ b/web/content/docs/reference/nix-daemon-protocol/operations.md
@@ -1,5 +1,17 @@
+---
+title: Operations
+slug: operations
+description: ""
+summary: ""
+date: 2025-03-24T13:10:37+02:00
+lastmod: 2025-03-24T13:10:37+02:00
+draft: false
+weight: 53
+toc: true
+---
 
-# TOC
+These page describes the different operations a client can request, as well as
+its expected input and output types.
 
 | Operation                                                   | Id |
 | ----------------------------------------------------------- | -- |
@@ -869,36 +881,36 @@ gcRoot :: [Path][se-Path]
 
 
 
-[se-Int]: ./serialization.md#int
-[se-UInt8]: ./serialization.md#uint8
-[se-UInt64]: ./serialization.md#uint64
-[se-Bool]: ./serialization.md#bool
-[se-Bool64]: ./serialization.md#bool64
-[se-Time]: ./serialization.md#time
-[se-FileIngestionMethod]: ./serialization.md#fileingestionmethod
-[se-BuildMode]: ./serialization.md#buildmode
-[se-Verbosity]: ./serialization.md#verbosity
-[se-GCAction]: ./serialization.md#gcaction
-[se-Bytes]: ./serialization.md#bytes
-[se-String]: ./serialization.md#string
-[se-StorePath]: ./serialization.md#storepath
-[se-BaseStorePath]: ./serialization.md#basestorepath
-[se-OptStorePath]: ./serialization.md#optstorepath
-[se-ContentAddressMethodWithAlgo]: ./serialization.md#contentaddressmethodwithalgo
-[se-OptContentAddress]: ./serialization.md#optcontentaddress
-[se-DerivedPath]: ./serialization.md#derivedpath
-[se-DrvOutput]: ./serialization.md#drvoutput
-[se-Realisation]: ./serialization.md#realisation
-[se-List]: ./serialization.md#list-of-x
-[se-Set]: ./serialization.md#set-of-x
-[se-Map]: ./serialization.md#map-of-x-to-y
-[se-SubstitutablePathInfo]: ./serialization.md#substitutablepathinfo
-[se-ValidPathInfo]: ./serialization.md#validpathinfo
-[se-UnkeyedValidPathInfo]: ./serialization.md#unkeyedvalidpathinfo
-[se-BuildResult]: ./serialization.md#buildmode
-[se-KeyedBuildResult]: ./serialization.md#keyedbuildresult
-[se-BasicDerivation]: ./serialization.md#basicderivation
-[se-Framed]: ./serialization.md#framed
-[se-AddMultipleToStore]: ./serialization.md#addmultipletostore-format
-[se-ExportFormat]: ./serialization.md#export-path-format
-[se-ImportPaths]: ./serialization.md#import-paths-format
+[se-Int]: {{< relref "serialization.md" >}}#int
+[se-UInt8]: {{< relref "serialization.md" >}}#uint8
+[se-UInt64]: {{< relref "serialization.md" >}}#uint64
+[se-Bool]: {{< relref "serialization.md" >}}#bool
+[se-Bool64]: {{< relref "serialization.md" >}}#bool64
+[se-Time]: {{< relref "serialization.md" >}}#time
+[se-FileIngestionMethod]: {{< relref "serialization.md" >}}#fileingestionmethod
+[se-BuildMode]: {{< relref "serialization.md" >}}#buildmode
+[se-Verbosity]: {{< relref "serialization.md" >}}#verbosity
+[se-GCAction]: {{< relref "serialization.md" >}}#gcaction
+[se-Bytes]: {{< relref "serialization.md" >}}#bytes
+[se-String]: {{< relref "serialization.md" >}}#string
+[se-StorePath]: {{< relref "serialization.md" >}}#storepath
+[se-BaseStorePath]: {{< relref "serialization.md" >}}#basestorepath
+[se-OptStorePath]: {{< relref "serialization.md" >}}#optstorepath
+[se-ContentAddressMethodWithAlgo]: {{< relref "serialization.md" >}}#contentaddressmethodwithalgo
+[se-OptContentAddress]: {{< relref "serialization.md" >}}#optcontentaddress
+[se-DerivedPath]: {{< relref "serialization.md" >}}#derivedpath
+[se-DrvOutput]: {{< relref "serialization.md" >}}#drvoutput
+[se-Realisation]: {{< relref "serialization.md" >}}#realisation
+[se-List]: {{< relref "serialization.md" >}}#list-of-x
+[se-Set]: {{< relref "serialization.md" >}}#set-of-x
+[se-Map]: {{< relref "serialization.md" >}}#map-of-x-to-y
+[se-SubstitutablePathInfo]: {{< relref "serialization.md" >}}#substitutablepathinfo
+[se-ValidPathInfo]: {{< relref "serialization.md" >}}#validpathinfo
+[se-UnkeyedValidPathInfo]: {{< relref "serialization.md" >}}#unkeyedvalidpathinfo
+[se-BuildResult]: {{< relref "serialization.md" >}}#buildmode
+[se-KeyedBuildResult]: {{< relref "serialization.md" >}}#keyedbuildresult
+[se-BasicDerivation]: {{< relref "serialization.md" >}}#basicderivation
+[se-Framed]: {{< relref "serialization.md" >}}#framed
+[se-AddMultipleToStore]: {{< relref "serialization.md" >}}#addmultipletostore-format
+[se-ExportFormat]: {{< relref "serialization.md" >}}#export-path-format
+[se-ImportPaths]: {{< relref "serialization.md" >}}#import-paths-format
diff --git a/snix/docs/src/nix-daemon/serialization.md b/web/content/docs/reference/nix-daemon-protocol/serialization.md
similarity index 98%
rename from snix/docs/src/nix-daemon/serialization.md
rename to web/content/docs/reference/nix-daemon-protocol/serialization.md
index 4d165456d..1d2155514 100644
--- a/snix/docs/src/nix-daemon/serialization.md
+++ b/web/content/docs/reference/nix-daemon-protocol/serialization.md
@@ -1,3 +1,16 @@
+---
+title: Types
+slug: types
+description: ""
+summary: ""
+date: 2025-03-24T13:10:37+02:00
+lastmod: 2025-03-24T13:10:37+02:00
+draft: false
+weight: 52
+toc: true
+---
+
+This describes how certain types are serialized to the wire format.
 
 ### UInt64
 Little endian byte order