docs: More documentation of nix daemon protocol r/8373

Uses `Set` to mark that the given list is actually a set.
The format on stream is no different from `List` but is nice to
know.

Best effort document string formats.

Documents default values for fields not used in old protocol
versions.

Document handshake, AddMultipleToStore format, Export format and
Import paths format.

Change-Id: I6cbe4c7de3770cc5caafc26229f99a07353ee3e2
Reviewed-on: https://cl.tvl.fyi/c/depot/+/11984
Reviewed-by: flokli <flokli@flokli.de>
Tested-by: BuildkiteCI
Autosubmit: Brian Olsen <me@griff.name>

1 files changed, 22 insertions, 20 deletions

diff --git a/tvix/docs/src/nix-daemon/logging.md b/tvix/docs/src/nix-daemon/logging.md
index 70fe0882fa6d..c2828b13c21a 100644
--- a/tvix/docs/src/nix-daemon/logging.md
+++ b/tvix/docs/src/nix-daemon/logging.md
@@ -13,20 +13,21 @@ While not in this state between request reading and response sending all
 messages and activities are buffered until next time the logger can send data.
 
 The logging messages supported are:
-- `STDERR_LAST`
-- `STDERR_ERROR`
-- `STDERR_NEXT`
-- `STDERR_READ`
-- `STDERR_WRITE`
-- `STDERR_START_ACTIVITY`
-- `STDERR_STOP_ACTIVITY`
-- `STDERR_RESULT`
+- [`STDERR_LAST`](#stderr_last)
+- [`STDERR_ERROR`](#stderr_error)
+- [`STDERR_NEXT`](#stderr_next)
+- [`STDERR_READ`](#stderr_read)
+- [`STDERR_WRITE`](#stderr_write)
+- [`STDERR_START_ACTIVITY`](#stderr_start_activity)
+- [`STDERR_STOP_ACTIVITY`](#stderr_stop_activity)
+- [`STDERR_RESULT`](#stderr_result)
 
 
 ### `STDERR_LAST`
 Marks the end of the logs, normal processing can resume.
 
-- 0x616c7473 :: [UInt64][se-UInt64] (hardcoded)
+- 0x616c7473 :: [UInt64][se-UInt64] (hardcoded, 'alts' in ASCII)
+
 
 ### `STDERR_ERROR`
 This also marks the end of this log "session" and so it
@@ -34,20 +35,20 @@ has the same effect as `STDERR_LAST`.
 On the client the error is thrown as an exception and no response is read.
 
 #### If protocol version is 1.26 or newer
-- 0x63787470 :: [UInt64][se-UInt64] (hardcoded)
+- 0x63787470 :: [UInt64][se-UInt64] (hardcoded, 'cxtp' in ASCII)
 - error :: [Error][se-Error]
 
 #### If protocol version is older than 1.26
-- 0x63787470 :: [UInt64][se-UInt64] (hardcoded)
-- msg :: [String][se-String]
+- 0x63787470 :: [UInt64][se-UInt64] (hardcoded, 'cxtp' in ASCII)
+- msg :: [String][se-String] (If logger is JSON, invalid UTF-8 is replaced with U+FFFD)
 - exitStatus :: [Int][se-Int]
 
 
 ### `STDERR_NEXT`
 Normal string log message.
 
-- 0x6f6c6d67 :: [UInt64][se-UInt64] (hardcoded)
-- msg :: [String][se-String]
+- 0x6f6c6d67 :: [UInt64][se-UInt64] (hardcoded, 'olmg' in ASCII)
+- msg :: [String][se-String] (If logger is JSON, invalid UTF-8 is replaced with U+FFFD)
 
 
 ### `STDERR_READ`
@@ -56,15 +57,17 @@ It works by sending a desired buffer length and then on the receiver stream it
 reads bytes buffer of that length. If it receives 0 bytes it sees this as an
 unexpected EOF.
 
-- 0x64617461 :: [UInt64][se-UInt64] (hardcoded)
+- 0x64617461 :: [UInt64][se-UInt64] (hardcoded, 'data' in ASCII)
 - desiredLen :: [Size][se-Size]
 
+
 ### `STDERR_WRITE`
 Writer interface used by ExportPath. Simply writes a buffer.
 
 - 0x64617416 :: [UInt64][se-UInt64] (hardcoded)
 - buffer :: [Bytes][se-Bytes]
 
+
 ### `STDERR_START_ACTIVITY`
 Begins an activity. In other tracing frameworks this would be called a span.
 
@@ -73,11 +76,11 @@ versions of the protocol instead of sending an `STDERR_START_ACTIVITY`
 the level is checked against enabled logging level and the text field is
 sent as a simple log message with `STDERR_NEXT`.
 
-- 0x53545254 :: [UInt64][se-UInt64] (hardcoded)
+- 0x53545254 :: [UInt64][se-UInt64] (hardcoded, 'STRT' in ASCII)
 - act :: [UInt64][se-UInt64]
 - level :: [Verbosity][se-Verbosity]
 - type :: [ActivityType][se-ActivityType]
-- text :: [String][se-String]
+- text :: [String][se-String] (If logger is JSON, invalid UTF-8 is replaced with U+FFFD)
 - fields :: [List][se-List] of [Field][se-Field]
 - parent :: [UInt64][se-UInt64]
 
@@ -92,7 +95,7 @@ Just sends `ActivityId`.
 Implemented in protocol 1.20. When backwards compatible with older versions of
 the protocol and this message would have been sent it is instead ignored.
 
-- 0x53544f50 :: [UInt64][se-UInt64] (hardcoded)
+- 0x53544f50 :: [UInt64][se-UInt64] (hardcoded, 'STOP' in ASCII)
 
 
 ### `STDERR_RESULT`
@@ -101,14 +104,13 @@ Sends results for a given activity.
 Implemented in protocol 1.20. When backwards compatible with older versions of
 the protocol and this message would have been sent it is instead ignored.
 
-- 0x52534c54 :: [UInt64][se-UInt64] (hardcoded)
+- 0x52534c54 :: [UInt64][se-UInt64] (hardcoded, 'RSLT' in ASCII)
 - act :: [UInt64][se-UInt64]
 - type :: [ResultType][se-ResultType]
 - fields :: [List][se-List] of [Field][se-Field]
 
 
 
-
 [se-UInt64]: ./serialization.md#uint64
 [se-Int]: ./serialization.md#int
 [se-Size]: ./serialization.md#size