Atomic directory switch and rollback for directory-based channels #57

Summary

Switch and roll back application and model versions atomically by directory.

Problem / intent

A half-switched application or model must never run.

Proposed solution

Each version lives in its own directory; a current symlink is replaced by rename. After a model switch, notify the application to reload; after an application switch, restart it through the service manager. Roll back to the most recent safe version; when a rollback breaks the compatibility matrix, return all channels to the last all-safe combination. When no retained version is compatible, keep the channel stopped and report it. After a version is confirmed, delete version directories older than the previous one.

• Depends on: Persist per-channel update state atomically and resume after reboot #50, Check the compatibility matrix at verification, at boot and after rollback #56
• Can proceed in parallel with: Image channel through RAUC: verify, install, reboot, mark good, roll back #58, Periodic health checks with warm-up and application-supplied probes #59

Contract

Layout and switch:

• Each version of a directory-based channel lives in its own version directory; a current symlink points at the active one.
• A switch creates a temporary symlink to the new version directory, then renames it over current. After a power loss at any point, current points at either the old or the new version.
• After a model switch the application is notified to reload the model. After an application switch the application is restarted through the service manager (systemd).

Retention and removal:

• Each channel keeps its current and previous versions; during a trial that means at most three: the version in trial, the previous one and the one before it.
• After a new version is confirmed, version directories older than the previous version are deleted.
• A rolled-back version's directory is deleted as soon as the rollback is complete and the version is on the blocklist (Keep a version floor, a local blocklist and unacknowledged results #52), without waiting for the next version to be confirmed.

Rollback:

• A rollback points current at the channel's most recent safe version, which is not necessarily the previous one, and restarts the application. It uses the locally retained, previously verified version: nothing is downloaded and the version floor does not apply.
• The device records the most recent combination in which every channel was safe. When the compatibility check (Check the compatibility matrix at verification, at boot and after rollback #56) fails after a rollback, the other channels also return to that combination, with result rolled_back_dependency.
• When no retained version is compatible, the channel is not started and reports rejected_incompatible; it stays stopped until a compatible version has been delivered and switched in.
• Open: how the application is notified to reload the model
• Open: the naming of version directories and of the temporary symlink
• Open: where the most recent all-safe combination is recorded

Acceptance criteria

• Unit test in a temporary directory: after a switch, current resolves to the new version directory, and the switch went through a temporary symlink renamed over current
• Unit test: stopping the switch after the temporary symlink is created and before the rename leaves current on the old version
• Unit test with a fake service manager and a fake application: a model switch sends a reload notification; an application switch restarts the application
• Unit test: when the safe version is older than the previous version, a rollback points current at the safe version
• Unit test: when the compatibility check fails after a rollback, the other channels return to the most recent all-safe combination and rolled_back_dependency is recorded
• Unit test: with no compatible retained version, the channel is not started and rejected_incompatible is recorded
• Unit test: after a confirmation, only the current and previous version directories remain
• Unit test: a rolled-back version's directory is deleted once the rollback is complete and the version is on the blocklist
• Each Open item above is defined in the pull request and documented in the repository
• No deployment-specific content (organisation, site, equipment model, point table, register map or data sample) in code, tests or docs
• make verify passes

Area

• area:update — Update channels, artifact delivery, atomic switch and rollback