Skip to content

feat(update): tell the user why an OS update was not offered - #916

Open
arunoruto wants to merge 1 commit into
armada-os:mainfrom
arunoruto:feat/update-status
Open

arunoruto wants to merge 1 commit into
armada-os:mainfrom
arunoruto:feat/update-status

Conversation

@arunoruto

Copy link
Copy Markdown
Contributor

Related: #785, #328.

Problem

My Retroid Pocket 6 stayed on the 20261010 beta image for weeks after newer builds were published. Game Mode → Settings → System → Check for updates kept saying there were no updates. The reason was only in the journal:

$ journalctl -t armada-update -n 20
Nov 15 12:09:01 armada armada-update[40025]: could not inspect update target ghcr.io/armada-os/armada:beta
Nov 15 12:09:01 armada armada-update[40026]: Could not inspect the update target
...
Nov 17 20:38:55 armada armada-update[5878]: update does not fit: 6354919334 bytes needed plus 2147483648 bytes reserved; 2716225536 bytes available
Nov 17 20:38:55 armada armada-update[5879]: Not enough free space for the update

/var was 98% full (92 G partition), and nothing in the UI said so.

Steam's update protocol has two answers: exit 0 for an available update or a successful install, and exit 7 for no update. armada-update sends every failure through fail(), which logs and exits 7, so Steam reports "no updates" when space runs out, when the registry is unreachable, when the metadata is incomplete, when bootc or the target is missing, and when bootc switch or bootc upgrade fails. That last case is how the rpm-ostree layering error in #785 stays hidden. Since full storage can also break boot (#328), a visible low-space warning helps outside of updates too.

Changes

armada-update now writes the result of every check and apply run to /var/lib/armada/update-status.json:

{"time": 1794960981, "mode": "check", "result": "no_space",
 "target": "ghcr.io/armada-os/armada:testing", "version": "20261116.298ad1a",
 "needed_bytes": 1426703945, "reserve_bytes": 64424509440, "available_bytes": 12489785344}

result is one of available, up_to_date, staged, no_space, remote_unreachable, bad_metadata, apply_failed or error. The file is replaced atomically, and if the write fails the exit code stays the same. Exit codes and stdout are unchanged, so Steam sees no difference. Steam starts the updater through pkexec (/usr/bin/steamos-polkit-helpers/steamos-update), so both modes run as r/lib/armada. The Armada Control backend reads and validates the file in get_update_sto part of the config, so the Settings tab needs no extra call.
In the frontend, Settings shows an "Update Blocked" line under "OS Versios a failure, for example "Free up 5.8 GB of storage to install the nextArmada update." The amount includes the OSTree reserve and is rounded up. A toast appears after every blocked check, including a manual "Check for updates", and once per session while the update stays blocked. The first poll runs 30 s after Stm drops toasts sent during startup. remote_unreachable only shows inSettings, since a short network outage shouldn't pop up a toast. The strings are translated for en, pt-BR, pt-PT and zh-CN.

Open questions

  • Is /var/lib/armada/update-status.json a good place, or would you prefer /run? /run is cleared on reboot, which may fit a "last check" result better.
  • Should apply_failed include bootc's last error line, such as the rpm-om OS update silently stuck: Steam says "up to date" when the deployment has rpm-ostree layered packages #785, so the UI can show it? For now the message points to journalctl-t armada-update.
  • The plugin could instead read journalctl -t armada-update -o json and no shell changes. That diff would be smaller, but it depends on log textthat can change at any time, so I chose the status file.

Testing

  • tests/desktop-update-test.py has new cases that check the recorded result for available, no_space (check and apply), remote_unreachable, up_to_date and staged (check and
    apply), and that an unwritable status path leaves the exit code and output.sh, update-migration-test.shandupdate-progress-test.sh` stillpass.
  • In decky/armada-control, npm test passes with 52 tests, including ttest.tswith the numbers from my journal, and the i18n parity check.npm run build` succeeds.
  • On a Retroid Pocket 6 (20261109, beta), I ran the scripts from /tmp w
    • The real check exited 7 and wrote {"result": "up_to_date", "target": "ghcr.io/armada-os/armada:beta", "version": "20261109.dfed5d6"}.
    • For no_space, a test copy checked the testing channel with the resexited 7, logged the usual "update does not fit" lines and wrote the status JSON shown above.
    • With the plugin build installed, Settings showed "Update Blocked: Frest appeared 30 s after Decky started and again after a new check.

Steam only knows exit 0 and 7, so every updater failure (not enough
space, registry unreachable, bootc failing) shows up as "no updates".

armada-update now records the result of each check and apply run in
/var/lib/armada/update-status.json without changing exit codes or
output. Armada Control reads it, shows an "Update Blocked" line in
Settings and toasts after every blocked check and once per session.
Network failures only show in Settings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant