feat: flux-op publishes a result atomically

An operation writes into a staging directory and is moved into place only on
success, so a failed command, a killed container and a power cut all leave the
caller's data exactly as it was.

Publishing swaps rather than deleting first. rename(2) refuses a non-empty
directory as its target and cannot replace a file with a directory at all, so mv
alone has to remove the existing entry before renaming - and a crash in that
window loses the destination outright while its replacement sits under a staging
name. Moving the old entry aside makes both steps atomic; the worst a crash
leaves is the previous data under .flux-old-*, which a startup sweep restores.

The swap is applied to every existing destination rather than branching on entry
type. The branch is where the file-replaced-by-directory case was missed, and
the smoke tests now cover all four combinations.

Living in the image means one container does the work and the publish, so the
two decisions cannot drift apart. Operands are positional parameters and are
never interpolated into a command string.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: MorningLightMountain713

.github/workflows/build.yml

@@ -72,6 +72,54 @@ jobs:
           '
           echo "ok - cp -a -T does not nest"
 
+          # flux-op's contract: the destination changes only on success, and it
+          # changes atomically whatever the two entry types are. rename(2) cannot
+          # replace a file with a directory (or the reverse) at all, and refuses
+          # a non-empty directory target - which is why publishing goes through a
+          # swap rather than a delete-then-rename, and why every combination is
+          # covered here rather than just the common one.
+          op() {
+            local label="$1" script="$2"
+            if docker run --rm flux-volume-tools:test sh -c "$script" >/dev/null 2>&1; then
+              echo "ok - $label"
+            else
+              echo "FAIL - $label"
+              exit 1
+            fi
+          }
+
+          op "a failed command leaves the destination untouched" '
+            mkdir -p /w && echo original > /w/dest
+            flux-op /w/.flux-op-1 /w/dest -- false 2>/dev/null && exit 1
+            grep -qx original /w/dest'
+
+          op "a directory replaces an existing file" '
+            mkdir -p /w/src && echo new > /w/src/f && echo original > /w/dest
+            flux-op /w/.flux-op-2 /w/dest -- cp -a -T /w/src /w/.flux-op-2
+            grep -qx new /w/dest/f'
+
+          op "a directory replaces an existing directory, and does not merge into it" '
+            mkdir -p /w/src /w/dest && echo new > /w/src/f && echo old > /w/dest/keep
+            flux-op /w/.flux-op-3 /w/dest -- cp -a -T /w/src /w/.flux-op-3
+            grep -qx new /w/dest/f
+            test ! -e /w/dest/keep'
+
+          op "a file replaces an existing directory" '
+            mkdir -p /w && echo new > /w/src && mkdir -p /w/dest && echo old > /w/dest/keep
+            flux-op /w/.flux-op-4 /w/dest -- cp -a -T /w/src /w/.flux-op-4
+            grep -qx new /w/dest'
+
+          op "a new destination leaves no staging or swap directory behind" '
+            mkdir -p /w/src && echo new > /w/src/f
+            flux-op /w/.flux-op-5 /w/dest -- cp -a -T /w/src /w/.flux-op-5
+            grep -qx new /w/dest/f
+            test -z "$(ls -A /w | grep flux- || true)"'
+
+          op "--mkdir creates the staging directory for commands that need one" '
+            mkdir -p /w/src && echo x > /w/src/f && tar -cf /w/a.tar -C /w src
+            flux-op --mkdir /w/.flux-op-6 /w/out -- tar -xf /w/a.tar -C /w/.flux-op-6
+            grep -qx x /w/out/src/f'
+
   publish:
     needs: smoke-test
     if: github.event_name != 'pull_request'

Dockerfile

@@ -22,6 +22,13 @@ FROM alpine:3.24
 # -T, so this one is about predictable behaviour rather than a missing flag.
 RUN apk add --no-cache coreutils tar unzip
 
+# Runs a command into a staging directory and publishes the result with an atomic
+# rename, so an operation that fails, is cancelled, or is interrupted by a power
+# cut leaves the caller's data exactly as it was. Living in the image means one
+# container does the work AND the publish - see the script for why that matters.
+COPY flux-op /usr/local/bin/flux-op
+RUN chmod 0755 /usr/local/bin/flux-op
+
 # No default command by design: the executor always supplies argv, and an accidental
 # `docker run` of this image should do nothing.
 ENTRYPOINT []

README.md

@@ -50,6 +50,42 @@ routing filesystem work through Docker adds no new privilege — whereas running
 `sudo cp` on the host requires sudoers rules that the planned demotion of FluxOS to
 an unprivileged system user is meant to remove.
 
+## `flux-op` — publishing a result atomically
+
+```
+flux-op [--mkdir] <staging> <destination> -- <command> [args...]
+```
+
+The command writes into `<staging>`, never into `<destination>`. Only on success
+is the result moved into place. A command that fails, a container that is killed,
+and a node that loses power all leave `<destination>` exactly as it was.
+
+Publishing goes through a swap — move the old entry aside, move the new one in,
+delete the old — rather than a delete-then-rename. `rename(2)` refuses a
+non-empty directory as its target and cannot replace a file with a directory at
+all, so `mv` alone would have to delete first, and a crash in that window loses
+the destination outright. Both renames in the swap are atomic, so the worst a
+crash leaves is the previous data under `.flux-old-*`.
+
+Leftovers are named for a startup sweep to recognise:
+
+| Left behind | Means | Recovery |
+|---|---|---|
+| `.flux-op-*` | the operation never completed | delete; nobody is waiting for it |
+| `.flux-old-*`, destination missing | crash mid-swap | rename it back |
+| `.flux-old-*`, destination present | the swap completed | delete |
+
+This is **atomic visibility, not durability.** You will never see a half-written
+result at the destination path. A power cut seconds after a copy can still leave
+files whose contents had not reached disk — that is true of `cp` on Linux
+generally and is not something this changes.
+
+It lives in the image rather than in the caller so one container does the work
+*and* the publish: the "did it succeed" and "put it in place" decisions cannot
+drift apart, and no second container spawn is needed per operation. Operands
+arrive as positional parameters and are never interpolated into a command
+string.
+
 ## Contract
 
 The image guarantees these binaries, with GNU / Info-ZIP semantics:

flux-op

@@ -0,0 +1,72 @@
+#!/bin/sh
+# Run one file operation and publish its result atomically.
+#
+#   flux-op [--mkdir] <staging> <destination> -- <command> [args...]
+#
+# The command writes into <staging>, never into <destination>. Only if it
+# succeeds is the result moved into place. A command that fails, a container
+# that is killed, and a node that loses power all leave <destination> exactly as
+# it was, with the incomplete work parked under a name the startup sweep
+# recognises.
+#
+# This lives in the image rather than in the caller so that one container does
+# the work AND the publish: the "did it succeed" and "put it in place" decisions
+# cannot drift apart, and a second container spawn is not needed per operation.
+#
+# Operands arrive as positional parameters and are never interpolated into a
+# command string - "$@" runs the command with its argv intact, so there is no
+# shell parsing of anything the caller supplied.
+set -eu
+
+make_staging=0
+if [ "${1:-}" = "--mkdir" ]; then
+  make_staging=1
+  shift
+fi
+
+if [ "$#" -lt 4 ]; then
+  echo "flux-op: usage: flux-op [--mkdir] <staging> <destination> -- <command> [args...]" >&2
+  exit 2
+fi
+
+staging=$1
+destination=$2
+shift 2
+
+if [ "$1" != "--" ]; then
+  echo "flux-op: expected -- before the command" >&2
+  exit 2
+fi
+shift
+
+# Only the commands that need an existing directory to write into (tar -C, for
+# one) ask for this. A file copy must NOT have it: cp -T refuses to overwrite a
+# directory with a non-directory.
+if [ "$make_staging" -eq 1 ]; then
+  mkdir -p "$staging"
+fi
+
+"$@"
+
+# A destination that does not exist is one atomic rename and nothing to clean up.
+#
+# Replacing one that DOES exist cannot be a single rename in the general case.
+# rename(2) refuses a non-empty directory as its target, and refuses to replace a
+# file with a directory (or the reverse) at all - so `mv` would have to delete
+# the existing entry first, and a crash in that window loses the destination
+# outright while the replacement sits under a staging name nobody recognises.
+#
+# Moving the old entry aside first avoids the window whatever the two types are.
+# Both renames are atomic, so the worst a crash leaves is the old data under
+# .flux-old-*, which the startup sweep renames back when it finds the
+# destination missing. Uniform rather than branching on type: the branch is
+# where the file-replaced-by-directory case was originally missed.
+if [ ! -e "$destination" ] && [ ! -L "$destination" ]; then
+  mv -T "$staging" "$destination"
+else
+  staging_base=$(basename "$staging")
+  old="$(dirname "$staging")/.flux-old-${staging_base#.flux-op-}"
+  mv -T "$destination" "$old"
+  mv -T "$staging" "$destination"
+  rm -rf "$old"
+fi