Poll target versions and download in stages with resume and backoff #53

Summary

Ask the server for each channel's target version and download updates safely and resumably.

Problem / intent

Devices sit on unreliable links. Downloads must resume, retries must back off, and nothing listed by an unauthenticated manifest may be written before it is checked.

Proposed solution

Poll target versions at a configured interval. For directory-based channels, download the manifest and its signature first and fetch the listed files only after verification of the manifest passes; for a single-bundle image channel, download the whole bundle. Resume with HTTP Range into a staging directory; never follow symlinks or write outside it. Retry with exponential backoff, an upper bound and random jitter. Re-check the target just before switching and abandon the update if it changed.

• Depends on: Persist per-channel update state atomically and resume after reboot #50; verification hooks from Verify detached CMS signatures against an on-device trust root and revocation list #54 and Validate manifest channel, version floor, upgrade path, file paths and hashes #55
• Can proceed in parallel with: Apply one channel at a time, run trials and promote safe versions #51, Keep a version floor, a local blocklist and unacknowledged results #52, Periodic health checks with warm-up and application-supplied probes #59

Contract

• The supervisor queries targets every update.poll_interval_s through the application-supplied source (Define the interfaces for the three update channels #1). The query carries the results not yet acknowledged; the answer's frozen list, timed-out list and acknowledgement go to Keep a version floor, a local blocklist and unacknowledged results #52.
• No querying, downloading or switching while the application reports that the device is not yet registered for service, or is retired. Updates start once the device is in normal service.
• Download locations come from the server's answer; the library never builds them. Files listed in a manifest are resolved relative to the manifest's location.
• Downloads use the device's TLS client certificate, the same one the application uses. The application renews it; the supervisor reloads it when the file changes.
• Directory channels: fetch the manifest and its signature first. Fetch the listed files only after the signature check (Verify detached CMS signatures against an on-device trust root and revocation list #54) and the channel, version and path checks (Validate manifest channel, version floor, upgrade path, file paths and hashes #55) pass.
• Image channel: fetch the single bundle; its verification and install are Image channel through RAUC: verify, install, reboot, mark good, roll back #58.
• Each version is staged in its own directory under the configured staging path. An interrupted download resumes from where it stopped with an HTTP Range request. Writes never follow symbolic links and never land outside that directory.
• Retry: wait update.retry_initial_s after the first failure and double the interval after each further failure, up to update.retry_max_backoff_s. Each actual wait is a random value between half and all of the current interval. A successful query or download resets the interval to update.retry_initial_s.
• Just before switching, query the target again. If it is no longer this version, abandon the update: the current version stays, and this download's staged files are deleted at once.
• The staged files of an abandoned or rejected download are deleted at once. At boot, staged files that are no longer needed are deleted.
• update.poll_interval_s, update.retry_initial_s and update.retry_max_backoff_s come from configuration.
• Open: how the application reports to the library that the device is not in normal service.
• Open: the directory layout under the staging path.
• Open: the HTTP client used for queries and downloads.

Acceptance criteria

• Unit test against a fake server: a directory channel requests the manifest and signature first, requests no listed file when a manifest check fails, and requests the listed files after the checks pass
• Unit test against a fake server: the image channel requests one bundle and nothing else
• Unit test: after an interrupted transfer, the next request carries a Range header starting at the bytes already staged, and the completed file matches the source
• Unit test: a symbolic link placed in the staging directory is not followed, and nothing is written outside it
• Unit test with a fake clock and a seeded random source: waits start at update.retry_initial_s, double, stop growing at update.retry_max_backoff_s, each fall between half and all of the interval, and reset after a success
• Unit test: when the re-check returns a different target, the update is abandoned, the current version is unchanged and the staged files are gone
• Unit test: a rejected download's staged files are deleted at once; at start-up, staged files that do not belong to an in-progress target are deleted
• Unit test: while the application reports that the device is not in normal service, the fake server receives no query or download request
• Unit test: queries are sent every update.poll_interval_s and carry the unacknowledged results
• 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