maurice/snix
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(reference/nix-daemon-protocol): migrate

Browse source 
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>
This commit is contained in:
Florian Klink 2025-03-24 13:50:11 +00:00 • committed by clbot
parent 76250b354f
commit 8101e7a45f
10 changed files with 165 additions and 79 deletions
Download patch file Download diff file Expand all files Collapse all files

6
snix/docs/src/SUMMARY.md
View file

@ -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)

32
snix/docs/src/nix-daemon/handshake.md
View file

@ -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

2
web/content/docs/reference/_index.md
View file

@ -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

11
web/content/docs/reference/nix-daemon-protocol/_index.md Normal file
View file

@ -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
---

19
snix/docs/src/nix-daemon/changelog.md → web/content/docs/reference/nix-daemon-protocol/changelog.md
View file

@ -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" >}}

49
web/content/docs/reference/nix-daemon-protocol/handshake.md Normal file
View file

@ -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

20
snix/docs/src/nix-daemon/index.md → web/content/docs/reference/nix-daemon-protocol/intro.md
View file

@ -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.

12
snix/docs/src/nix-daemon/logging.md → web/content/docs/reference/nix-daemon-protocol/logging.md
View file

@ -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.

80
snix/docs/src/nix-daemon/operations.md → web/content/docs/reference/nix-daemon-protocol/operations.md
View file

@ -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

13
snix/docs/src/nix-daemon/serialization.md → web/content/docs/reference/nix-daemon-protocol/serialization.md
View file

@ -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