From 104baef503df3afcd09615d9b014923696e9ecf9 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 4 Dec 2023 09:42:04 -0500
Subject: [PATCH] Document the connection initialization process

---
 src/hydra-queue-runner/build-remote.cc | 16 ++++++++++++----
 src/hydra-queue-runner/state.hh        |  2 +-
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/src/hydra-queue-runner/build-remote.cc b/src/hydra-queue-runner/build-remote.cc
index 032c2733..baf35d86 100644
--- a/src/hydra-queue-runner/build-remote.cc
+++ b/src/hydra-queue-runner/build-remote.cc
@@ -195,6 +195,12 @@ static std::pair<Path, AutoCloseFD> openLogFile(const std::string & logDir, cons
     return {std::move(logFile), std::move(logFD)};
 }
 
+/**
+ * @param conn is not fully initialized; it is this functions job to set
+ * the `remoteVersion` field after the handshake is completed.
+ * Therefore, no `ServeProto::Serialize` functions can be used until
+ * that field is set.
+ */
 static void handshake(Machine::Connection & conn, unsigned int repeats)
 {
     conn.to << SERVE_MAGIC_1 << 0x206;
@@ -204,6 +210,7 @@ static void handshake(Machine::Connection & conn, unsigned int repeats)
     if (magic != SERVE_MAGIC_2)
         throw Error("protocol mismatch with ‘nix-store --serve’ on ‘%1%’", conn.machine->sshName);
     conn.remoteVersion = readInt(conn.from);
+    // Now `conn` is initialized.
     if (GET_PROTOCOL_MAJOR(conn.remoteVersion) != 0x200)
         throw Error("unsupported ‘nix-store --serve’ protocol version on ‘%1%’", conn.machine->sshName);
     if (GET_PROTOCOL_MINOR(conn.remoteVersion) < 3 && repeats > 0)
@@ -512,10 +519,11 @@ void State::buildRemote(ref<Store> destStore,
                process. Meh. */
         });
 
-        Machine::Connection conn;
-        conn.from = child.from.get();
-        conn.to = child.to.get();
-        conn.machine = machine;
+        Machine::Connection conn {
+            .from = child.from.get(),
+            .to = child.to.get(),
+            .machine = machine,
+        };
 
         Finally updateStats([&]() {
             bytesReceived += conn.from.read;
diff --git a/src/hydra-queue-runner/state.hh b/src/hydra-queue-runner/state.hh
index 03923917..6359063a 100644
--- a/src/hydra-queue-runner/state.hh
+++ b/src/hydra-queue-runner/state.hh
@@ -303,8 +303,8 @@ struct Machine
 
     // A connection to a machine
     struct Connection {
-        nix::FdSink to;
         nix::FdSource from;
+        nix::FdSink to;
         nix::ServeProto::Version remoteVersion;
 
         // Backpointer to the machine