From ec0f17a7ad84e8362536d89cd7246cb18f8720c2 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 14:52:18 +1000 Subject: [PATCH] feat(update): let every host binary report its version, and refuse skew The updater is component-driven: it compares the daemon and agent versions and acts only when they differ, so a host whose individual binaries disagree looks healthy. Carina ran a hand-installed archie-messaging 1.35.0 against a 1.30.0 state store and crash-looped on an RPC the older store does not serve, while the updater reported "no approved component changes; nothing to install". The reason a comparison was impossible: three of the six host binaries carried no version at all. archie-ui, archie-messaging and archie-playbooks did not link internal/app/archied, so the release ldflags never reached them; the gateway and state store linked the variable but exposed no flag. Only archied could say what it was. - internal/buildinfo carries Version, stamped by all three build sites: the zip, install.sh, and the updater itself. - Every host binary answers -version (" "). archied's existing two-line output is unchanged, because something parses it. - archie-update-install reads each installed binary before it can report "nothing to install" and refuses, naming every binary that disagrees with the daemon's version; after an install it verifies the same set against the release it just installed, so a binary the release did not rebuild is skew rather than success. - TestDistZipShipsEveryHostCommand pins stamping across the three build sites and requires each cmd/ to report, so a seventh command cannot arrive unstamped. --- .github/workflows/deploy.yml | 2 +- cmd/archie-gateway/main.go | 3 + cmd/archie-messaging/main.go | 3 + cmd/archie-playbooks/main.go | 6 ++ cmd/archie-state-store/main.go | 3 + deploy_workflow_test.go | 20 +++++ install.sh | 4 + internal/buildinfo/buildinfo.go | 37 ++++++++ internal/releaseupdate/install_script_test.go | 85 +++++++++++++++++-- scripts/archie-update-install | 41 +++++++++ 10 files changed, 197 insertions(+), 7 deletions(-) create mode 100644 internal/buildinfo/buildinfo.go diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index aa9c27a8b..ca041d415 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -254,7 +254,7 @@ jobs: # ran on with a dead Telegram bot and no error anywhere # (archie-core-1c01). TestDistZipShipsEveryHostCommand fails if this # list and the copy list below stop matching the commands in cmd/. - ldflags="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" + ldflags="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${{ steps.version.outputs.version }}" mkdir -p dist for cmd in archied archie-gateway archie-state-store archie-ui archie-messaging archie-playbooks; do go build -ldflags "$ldflags" -o "dist/$cmd" "./cmd/$cmd" diff --git a/cmd/archie-gateway/main.go b/cmd/archie-gateway/main.go index d0a94f303..ca2d3aa12 100644 --- a/cmd/archie-gateway/main.go +++ b/cmd/archie-gateway/main.go @@ -10,6 +10,7 @@ import ( "syscall" "github.com/samcharles93/archie-core/internal/app/archied" + "github.com/samcharles93/archie-core/internal/buildinfo" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" ) @@ -17,11 +18,13 @@ func main() { os.Exit(run()) } func run() int { var options archied.GatewayOptions + showVersion := buildinfo.RegisterVersionFlag("archie-gateway") flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory") flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory") flag.StringVar(&options.Listen, "listen", "", "gateway gRPC listen address (defaults to [services.gateway].listen, else 127.0.0.1:8585)") flag.StringVar(&options.Token, "token", "", "Bearer [REDACTED] required for a non-loopback listener (defaults to [services.gateway].target_token)") flag.Parse() + showVersion() ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() if err := archied.RunGateway(ctx, options); err != nil { diff --git a/cmd/archie-messaging/main.go b/cmd/archie-messaging/main.go index 57c36fa56..d6a6d0cdf 100644 --- a/cmd/archie-messaging/main.go +++ b/cmd/archie-messaging/main.go @@ -11,6 +11,7 @@ import ( "syscall" "github.com/samcharles93/archie-core/internal/app/archiemessaging" + "github.com/samcharles93/archie-core/internal/buildinfo" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" ) @@ -18,6 +19,7 @@ func main() { os.Exit(run()) } func run() int { var options archiemessaging.Options + showVersion := buildinfo.RegisterVersionFlag("archie-messaging") flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory") flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory") flag.StringVar(&options.Gateway.Target, "gateway-target", "", "archie-gateway gRPC address (defaults to [services.gateway].target, else 127.0.0.1:8585)") @@ -27,6 +29,7 @@ func run() int { flag.DurationVar(&options.DependencyTimeout, "dependency-timeout", 0, "readiness probe timeout (default 5s)") flag.DurationVar(&options.ShutdownTimeout, "shutdown-timeout", 0, "shutdown timeout (default 5s)") flag.Parse() + showVersion() ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() diff --git a/cmd/archie-playbooks/main.go b/cmd/archie-playbooks/main.go index 55762b7a0..19086245b 100644 --- a/cmd/archie-playbooks/main.go +++ b/cmd/archie-playbooks/main.go @@ -22,6 +22,7 @@ import ( "os" "github.com/samcharles93/archie-core/internal/app/archieplaybooks" + "github.com/samcharles93/archie-core/internal/buildinfo" ) func main() { @@ -36,6 +37,11 @@ func run(args []string, stderr io.Writer) int { "lint": runLint, } + if len(args) > 0 && (args[0] == "-version" || args[0] == "--version") { + buildinfo.Print("archie-playbooks") + return 0 + } + if len(args) == 0 { fmt.Fprintln(stderr, "usage: archie-playbooks [args]") fmt.Fprintln(stderr, "commands:") diff --git a/cmd/archie-state-store/main.go b/cmd/archie-state-store/main.go index be0b23077..c664fa746 100644 --- a/cmd/archie-state-store/main.go +++ b/cmd/archie-state-store/main.go @@ -18,6 +18,7 @@ import ( "syscall" "github.com/samcharles93/archie-core/internal/app/archied" + "github.com/samcharles93/archie-core/internal/buildinfo" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" ) @@ -32,6 +33,7 @@ func run() int { return runRecovery(args, os.Stdout, os.Stderr) } var options archied.StateStoreOptions + showVersion := buildinfo.RegisterVersionFlag("archie-state-store") flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory") flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory") flag.StringVar(&options.Listen, "listen", "", "state store gRPC listen address (defaults to [services.state].listen, else 127.0.0.1:9090)") @@ -42,6 +44,7 @@ func run() int { flag.PrintDefaults() } flag.Parse() + showVersion() ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() if err := archied.RunStateStore(ctx, options); err != nil { diff --git a/deploy_workflow_test.go b/deploy_workflow_test.go index 4bb9fabd0..6a32f1a46 100644 --- a/deploy_workflow_test.go +++ b/deploy_workflow_test.go @@ -152,6 +152,26 @@ func TestDistZipShipsEveryHostCommand(t *testing.T) { // The installer now REFUSES an update when a service unit is missing and // tells the operator to create it from this runbook, so a service the // runbook never shows is a dead end rather than a documentation gap. + // Stamping is its own list, and a third build site made it three: the zip, + // install.sh and the updater each build the host binaries. A binary that + // cannot say what it is cannot be compared (archie-core-k94o), so a seventh + // command added unstamped fails here rather than waiting to be noticed. + for name, source := range map[string]string{ + "deploy.yml": workflow, + "install.sh": installSh, + "archie-update-install": installer, + } { + if !strings.Contains(source, "internal/buildinfo.Version=") { + t.Errorf("%s does not stamp internal/buildinfo.Version", name) + } + } + for _, command := range wantBinaries { + main := readDeploymentFile(t, filepath.Join("cmd", command, "main.go")) + if !strings.Contains(main, "buildinfo") { + t.Errorf("cmd/%s/main.go has no way to report its version", command) + } + } + // The installer writes the units, so the runbook no longer carries their // contents; it must still name each unit, or an operator cannot find one to // inspect or override. diff --git a/install.sh b/install.sh index 54f82e4e7..491384881 100755 --- a/install.sh +++ b/install.sh @@ -174,6 +174,10 @@ echo "==> Building native archie binaries..." LDFLAGS="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${GATEWAY_VERSION}" LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion=${RUNTIME_VERSION}" LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" + # Every host binary carries the release it was built from, so the updater can + # ask each installed binary what it is (archie-core-k94o). + LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${GATEWAY_VERSION}" + LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${RUNTIME_VERSION}" # archied does not run alone: the State Store owns archie.db, the Gateway # serves the chat contract, the dashboard is its own process, and the # Messaging Service owns the chat channels. Building only archied leaves it diff --git a/internal/buildinfo/buildinfo.go b/internal/buildinfo/buildinfo.go new file mode 100644 index 000000000..beff9a338 --- /dev/null +++ b/internal/buildinfo/buildinfo.go @@ -0,0 +1,37 @@ +// Package buildinfo carries the release version stamped into every host +// binary. The updater asks each installed binary what it is, rather than +// trusting one component's word for a whole install whose binaries may have +// been replaced by hand (archie-core-k94o). +package buildinfo + +import ( + "flag" + "fmt" + "os" +) + +// Version and Runtime are stamped per release with +// -X github.com/samcharles93/archie-core/internal/buildinfo.Version=. +// The unstamped value is "dev", which is itself informative: a binary built +// outside a release says so rather than guessing. +var ( + Version = "dev" + Runtime = "dev" +) + +// Print writes the machine-readable "name version" line the updater reads. +func Print(name string) { + fmt.Printf("%s %s\n", name, Version) +} + +// RegisterVersionFlag adds -version to the standard flag set. Call the returned +// function after flag.Parse to print and exit when it was set. +func RegisterVersionFlag(name string) func() { + show := flag.Bool("version", false, "print the version and exit") + return func() { + if *show { + Print(name) + os.Exit(0) + } + } +} diff --git a/internal/releaseupdate/install_script_test.go b/internal/releaseupdate/install_script_test.go index 316069666..467d772c6 100644 --- a/internal/releaseupdate/install_script_test.go +++ b/internal/releaseupdate/install_script_test.go @@ -348,6 +348,14 @@ func runUpdateInstallWithConfig(t *testing.T, environment map[string]string, con // only way to test the coverage guard against the stale list it exists for is to // change that text -- which is exactly the state the guard must catch. func runUpdateInstallEdited(t *testing.T, environment map[string]string, configBody string, edit func(string) string, wantErr bool) (Result, []string, string) { + t.Helper() + return runUpdateInstallFull(t, environment, configBody, nil, edit, wantErr) +} + +// runUpdateInstallFull is runUpdateInstallEdited with control over the versions +// already installed in the bin directory, so a skewed host can be built on +// purpose (archie-core-k94o). +func runUpdateInstallFull(t *testing.T, environment map[string]string, configBody string, installed map[string]string, edit func(string) string, wantErr bool) (Result, []string, string) { t.Helper() ctx := t.Context() @@ -366,10 +374,16 @@ func runUpdateInstallEdited(t *testing.T, environment map[string]string, configB if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil { t.Fatal(err) } - for _, name := range []string{"archied", "archie-agent"} { - if err := os.WriteFile(filepath.Join(binDir, name), []byte("old "+name), 0o755); err != nil { - t.Fatal(err) - } + previousVersion := environment["ARCHIE_UPDATE_DAEMON_PREVIOUS"] + if previousVersion == "" { + previousVersion = "dev" + } + writeFakeBinary(t, binDir, "archied", previousVersion) + if err := os.WriteFile(filepath.Join(binDir, "archie-agent"), []byte("old archie-agent"), 0o755); err != nil { + t.Fatal(err) + } + for name, version := range installed { + writeFakeBinary(t, binDir, name, version) } writeFakeCommand(t, fakeDir, "git", ` printf '%s\n' "git $*" >> "$ARCHIE_TEST_CALLS" @@ -399,12 +413,24 @@ if [ "$1" = "run" ]; then exit 0 fi out="" +name="" +version="dev" while [ "$#" -gt 0 ]; do - if [ "$1" = "-o" ]; then out="$2"; break; fi + if [ "$1" = "-o" ]; then out="$2"; fi + case "$1" in + ./cmd/*) name="${1#./cmd/}" ;; + *buildinfo.Version=*) + version="${1##*buildinfo.Version=}" + version="${version%% *}" + ;; + esac shift done mkdir -p "$(dirname "$out")" -printf 'built\n' > "$out" +# The installed binary must answer -version the way a real one does, or the +# updater's skew check cannot read it. +printf '#!/usr/bin/env bash\necho "%s %s"\n' "$name" "$version" > "$out" +chmod 755 "$out" `) writeFakeCommand(t, fakeDir, "docker", ` printf '%s\n' "docker $*" >> "$ARCHIE_TEST_CALLS" @@ -522,6 +548,14 @@ fi return result, calls, string(output) } +func writeFakeBinary(t *testing.T, dir, name, version string) { + t.Helper() + body := "#!/usr/bin/env bash\necho " + strconv.Quote(name+" "+version) + "\n" + if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o755); err != nil { + t.Fatal(err) + } +} + func writeFakeCommand(t *testing.T, dir, name, body string) { t.Helper() if err := os.MkdirAll(dir, 0o755); err != nil { @@ -720,6 +754,45 @@ func TestUpdateInstallRefusesWhenTheServiceListOmitsAHostUnit(t *testing.T) { assertCallAbsent(t, calls, "install -m755") } +// Carina's actual pair (archie-core-k94o): archie-messaging 1.35.0 beside an +// archie-state-store 1.30.0, the daemon at 1.30.0, and nothing approved to +// install. The component-driven updater reported only "nothing to install" +// while the two disagreed; now it reads each installed binary and names them. +func TestUpdateInstallRefusesWhenInstalledBinariesDisagree(t *testing.T) { + _, calls, output := runUpdateInstallFull(t, map[string]string{ + "ARCHIE_UPDATE_DAEMON_PREVIOUS": "1.30.0", + "ARCHIE_UPDATE_AGENT_PREVIOUS": "1.30.0", + }, "[containers]\nimage = 'registry.example/archie-agent:stable'\n", map[string]string{ + "archie-messaging": "1.35.0", + "archie-state-store": "1.30.0", + }, nil, true) + + if !strings.Contains(output, "archie-messaging=1.35.0") { + t.Errorf("refusal must name the skewed binary and its version; output = %q", output) + } + if strings.Contains(output, "archie-state-store=") { + t.Errorf("refusal named a binary that agrees; output = %q", output) + } + assertCallAbsent(t, calls, "go build") + assertCallAbsent(t, calls, "install -m755") + t.Logf("refusal output:\n%s", strings.TrimSpace(output)) +} + +// A binary built outside a release reports "dev"; on a released host that is +// skew too, and it must be named rather than read as agreement. +func TestUpdateInstallRefusesAnUnstampedBinary(t *testing.T) { + _, _, output := runUpdateInstallFull(t, map[string]string{ + "ARCHIE_UPDATE_DAEMON_PREVIOUS": "1.30.0", + "ARCHIE_UPDATE_AGENT_PREVIOUS": "1.30.0", + }, "[containers]\nimage = 'registry.example/archie-agent:stable'\n", map[string]string{ + "archie-ui": "dev", + }, nil, true) + + if !strings.Contains(output, "archie-ui=dev") { + t.Errorf("refusal must name the unstamped binary; output = %q", output) + } +} + // The deployment is several processes, so the watchdog must cycle all of them, // and in dependency order: the State Store owns archie.db and everything dials // it, so it starts first and stops last (archie-core-hbqk). diff --git a/scripts/archie-update-install b/scripts/archie-update-install index e4130056a..4f61c0f83 100755 --- a/scripts/archie-update-install +++ b/scripts/archie-update-install @@ -117,7 +117,38 @@ if [ -n "$RT_TARGET" ] && [ "$RT_TARGET" != "$PREV_RT" ]; then components="${components:+$components,}agent" fi +# Per-binary skew is a different question from the unit set, and the one the +# updater could not answer (archie-core-k94o): it is component-driven, so a host +# whose individual binaries disagree -- a hand-installed outlier beside an +# otherwise current install -- looks healthy, because "no approved component +# changes" short-circuits before any binary is read. Ask every installed binary +# what it is and refuse, named, rather than reporting the install current. +verify_installed_versions() { + reference="$1" + problems="" + for cmd in $GATEWAY_BINARIES; do + [ -f "$BIN_DIR/$cmd" ] || continue + reported="$("$BIN_DIR/$cmd" -version 2>/dev/null | awk -v want="$cmd" '$1 == want { print $2; exit }')" + [ -n "$reported" ] || reported="unknown" + if [ "$reported" != "$reference" ]; then + problems="${problems:+$problems }$cmd=$reported" + fi + done + if [ -n "$problems" ]; then + echo "refusing: installed binaries disagree with $reference: $problems" >&2 + echo "each host binary must report the release it was built from; reinstall the outliers from archied/v$reference, or approve an update that rebuilds them" >&2 + return 1 + fi +} + if [ -z "$components" ]; then + reference="$PREV_GW" + if [ -z "$reference" ]; then + reference="$("$BIN_DIR/archied" -version 2>/dev/null | awk '$1 == "archied" { print $2; exit }')" + fi + if [ -n "$reference" ] && ! verify_installed_versions "$reference"; then + exit 1 + fi echo '==> no approved component changes; nothing to install' echo 'ARCHIE_UPDATE_RESULT {"previous":{},"installed":{},"components":[],"restart_requested":false}' exit 0 @@ -243,6 +274,10 @@ if [[ ",$components," == *,daemon,* ]]; then ldflags="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=$GW" ldflags="$ldflags -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion=$RT" ldflags="$ldflags -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" + # The updater is a build site too: without this stamp its own outputs would + # report "dev" and fail the skew check it just installed. + ldflags="$ldflags -X github.com/samcharles93/archie-core/internal/buildinfo.Version=$GW" + ldflags="$ldflags -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=$RT" for cmd in $GATEWAY_BINARIES; do [ -d "./cmd/$cmd" ] || continue echo "==> building $cmd $GW" @@ -264,6 +299,12 @@ if [[ ",$components," == *,daemon,* ]]; then for cmd in $built; do install -m755 "$tmp/$cmd" "$BIN_DIR/$cmd" done + + # Every installed binary must now report the release just installed; a binary + # this release did not rebuild is skew, not success. + if ! verify_installed_versions "$GW"; then + exit 1 + fi fi if [[ ",$components," == *,agent,* ]]; then # Independent versioning: the agent tag usually points at a different