From b0e5dcc5b716c0e4c7965f39e0db475483978c2c Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Sat, 16 Aug 2025 00:51:14 -0400
Subject: [PATCH] First draft at a varlink protocol for inside derivations

---
 src/libstore/derivation-builder.varlink | 80 +++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 src/libstore/derivation-builder.varlink

diff --git a/src/libstore/derivation-builder.varlink b/src/libstore/derivation-builder.varlink
new file mode 100644
index 00000000000..5afebff8727
--- /dev/null
+++ b/src/libstore/derivation-builder.varlink
@@ -0,0 +1,80 @@
+# For the derivation builder insider to communicate with Nix
+interface org.nix.derivation-builder
+
+type DerivationOutput (
+  # Note, not needed for floating content-addressing derivations.
+  path: ?string,
+  method: ?string,
+  hashAlgo: ?string,
+  hash: ?string
+)
+
+type Derivation (
+  name: string,
+  outputs: [string]DerivationOutput,
+  # TODO, combine both types in to just "sources"
+  inputSrcs: []string,
+  # Approximate typing
+  inputDrvs: [string]object,
+  system: string,
+  builder: string,
+  args: []string,
+  env: [string]string,
+  # Intentionally freeform, as the point of this is being extensible.
+  # Implementations should reject what they don't understand.
+  options: ?[string]object
+)
+
+# Add a file to the store.
+#
+# Parameters:
+# - name: file name
+# - method: content addressing method ("sha256", etc.)
+# - fd: file descriptor number to read from
+#
+# Returns:
+# - path: resulting store path
+#
+# The references should be scanned based on the starting possible
+# reference set of all derivation inputs, and all previously-added store
+# objects. (Ever sucessfull add, this possible reference set grows one
+# bigger.)
+#
+# This also requires a file descriptor to be sent which refers to the
+# actual data to be added. I am not sure if it is possible to write this
+# in the IDL since it is an extension (in systemd's usage of Varlink),
+# and not Varlink proper. (Opened
+# https://github.com/systemd/systemd/issues/38595 for this question.)
+method AddToStore(
+  name: string,
+  method: string,
+  #descriptor: int
+) -> (path: string)
+
+# Add a derivation to the store.
+# Parameters:
+# - derivation: derivation in JSON format
+# Returns:
+# - path: store path of the derivation (in format)
+method AddDerivation(derivation: Derivation) -> (path: string)
+
+# Submit an output, associating an output with a store object.
+#
+# Parameters:
+# - name: name of the output
+# - path: path of the store object (must already exist in store)
+#
+# The idea is derivations should add and submit their outputs one at a
+# time. This allows a few things:
+#
+# 1. Interesting pipeling. If something downstream just needs e.g. a
+# "dev" or "headers" output, it need not block on waiting for the other
+# outputs of the upstream derivation.
+#
+# 2. Content addressing doesn't require Nix-side rewriting. Instead, it
+# is the responsibilty of the builder to add outputs in reference order,
+# and arrange for the store paths that resulted from earlier adds being
+# used in later adds. This takes would be a very hard problem to solver
+# in "build system space", and punts it back to userspace, where
+# arbitrary strategies can be employed.
+method SubmitOutput(name: string, path: string) -> ()