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 ("<name> <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.
This commit is contained in:
sam committed 2026-09-22 14:52:18 +10:00
1 parent 3902b7ecbc
commit 70ea9b2a44
10 files changed
+197 -7

No files matched your search

+1 -1
View File
@@ -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"
+3
View File
@@ -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 {
+3
View File
@@ -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()
+6
View File
@@ -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 <command> [args]")
fmt.Fprintln(stderr, "commands:")
+3
View File
@@ -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 {
+20
View File
@@ -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.
+4
View File
@@ -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
+37
View File
@@ -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=<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)
}
}
}
+79 -6
View File
@@ -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).
+41
View File
@@ -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