Ref #03. Refactoring.
This commit is contained in:
deeaitch committed
1 parent
13a88b7270
commit
931efeabc7
4 files changed
+11
-178
No files matched your search
@@ -14,7 +14,7 @@ The request identifies the device, for example by serial number, and includes re
|
||||
|
||||
Checking for updates does not automatically start installation. The device can show “Updates available” and wait for an operator, or proceed according to its automatic update settings.
|
||||
|
||||
Use scheduled checks and allow a local operator to request a check. Apply connection preferences, such as Wi-Fi-only access, to the relevant checks and downloads.
|
||||
For devices with regular power cycles, check once at power-on when a suitable connection is available. Allow a local operator to request a check as well. Devices that run continuously can use scheduled checks. Apply connection preferences, such as Wi-Fi-only access, to the relevant checks and downloads.
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
@@ -30,16 +30,15 @@ Use scheduled checks and allow a local operator to request a check. Apply connec
|
||||
|
||||
- The basic exchange is simple: the device asks and the server responds.
|
||||
- No permanent connection is needed to discover updates.
|
||||
- Scheduled and operator-triggered checks use the same mechanism.
|
||||
- Power-on, scheduled, and operator-triggered checks use the same mechanism.
|
||||
- An offline device can check when it reconnects.
|
||||
- Finding an update and deciding when to install it remain separate steps.
|
||||
|
||||
### Negative
|
||||
|
||||
- A device may not discover a release until its next check.
|
||||
- Frequent checks create traffic even when no update is available.
|
||||
- For continuously running devices, power-on checks alone are insufficient if updates need to be discovered during operation. Scheduled or manual checks are needed.
|
||||
- If frequent scheduled checks are used, they create traffic even when no update is available.
|
||||
- Large groups of devices need staggered checks and retry delays to avoid contacting the server at the same time.
|
||||
- The server cannot make an offline device check immediately.
|
||||
|
||||
## Special Considerations
|
||||
|
||||
@@ -61,7 +60,9 @@ A serial number identifies a device; it is not a secret or proof of identity. Wh
|
||||
|
||||
### Connection and Operator Preferences
|
||||
|
||||
A device may check automatically after connecting to Wi-Fi, at a scheduled interval, or when an operator selects “Check for updates.” Downloading a large image and restarting the device can have their own conditions.
|
||||
For a device that is powered on for each work session, a single check at startup may be enough. If updates are installed only outside normal work, discovering a release during that work may offer little benefit.
|
||||
|
||||
A device that stays on continuously needs another trigger, such as a scheduled or operator-requested check. Downloading a large image and restarting the device can have their own conditions.
|
||||
|
||||
For example, the device can discover an update now, download it later over Wi-Fi, and ask the operator before restarting. A request to check does not have to mean permission to perform every later step.
|
||||
|
||||
@@ -69,7 +70,9 @@ For example, the device can discover an update now, download it later over Wi-Fi
|
||||
|
||||
If the server is unreachable, keep the current software running and retry later. An unsuccessful check means the device could not obtain current information; it does not mean that no updates exist.
|
||||
|
||||
Once an update has been selected, [ADR-012](ADR-012-device-controlled-update-execution.md) describes how the device can manage installation, activation, and recovery without a continuous server connection.
|
||||
### After Download
|
||||
|
||||
When an update is approved and all required files and verification information are available, the device can manage installation, activation, and recovery locally. For devices that can check their essential functions locally, these steps need not depend on a continuous server connection. The device saves its progress and reports the result when connectivity returns.
|
||||
|
||||
## Applicability
|
||||
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
# ADR-012: Device-Controlled Update Execution
|
||||
|
||||
## Context
|
||||
|
||||
A remotely deployed embedded Linux device may lose its connection after learning about an available update or preparing it for installation. The server controls which releases are available to the device, but cannot always stay in contact throughout the update.
|
||||
|
||||
[ADR-011](ADR-011-device-initiated-update-checks.md) describes how the device checks for updates. Once an update has been selected and approved, a separate question remains: who controls the steps needed to complete it?
|
||||
|
||||
The device can evaluate local operating conditions and has a locally available activation and recovery mechanism. Its essential post-update health checks can be evaluated without contacting the deployment service.
|
||||
|
||||
The architectural question is which participant controls execution once the device has accepted an update assignment. Requiring a remote command for every step would make progress and recovery depend on continued connectivity.
|
||||
|
||||
## Decision
|
||||
|
||||
Let the backend manage release assignment and fleet deployment policy. Let the device coordinate the local execution of an accepted update within that authorization and its local operating policy.
|
||||
|
||||
After the required content and verification information are available, local activation, health acceptance, and recovery must not require a live connection to the deployment service.
|
||||
|
||||
Keep enough durable local state to reconcile an interrupted operation with installation and boot state. Report progress and the resulting software state when connectivity permits. Treat backend knowledge as a potentially delayed observation of the device.
|
||||
|
||||
This decision assigns responsibility to the device as a whole. It does not require the userspace update manager to handle failures that occur before it can run.
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
- Connectivity may disappear during an update.
|
||||
- Local conditions determine when disruptive operations are permissible.
|
||||
- A candidate that fails to boot cannot rely on its own update agent for recovery.
|
||||
- Loss of reporting connectivity should not alone invalidate a locally healthy release.
|
||||
- Operators need to distinguish intended deployment state from observed device state.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Server-Controlled Execution of Every Step
|
||||
|
||||
The server authorizes each transition separately, including activation and confirmation.
|
||||
|
||||
This provides tighter online coordination, but a communication outage can leave an operation waiting for a command. It does not remove the need for local handling of boot failures or interrupted writes. It is less suitable for the assumed connectivity model.
|
||||
|
||||
### Local Execution with Mandatory Remote Acceptance
|
||||
|
||||
The device installs and boots independently but requires the backend to accept the candidate before confirmation.
|
||||
|
||||
This can be appropriate when external service behavior is part of release acceptance. For a device that can check its essential functions locally, this would make acceptance of an otherwise healthy update depend on network availability. Such a design also needs an explicit timeout and recovery policy for unavailable remote acceptance.
|
||||
|
||||
### Fully Autonomous Release Selection
|
||||
|
||||
The device selects any compatible authorized release without a backend assignment.
|
||||
|
||||
This can fit simpler products, but does not provide the server control over release availability assumed here. Local execution autonomy does not imply authority to select arbitrary releases.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Prepared updates can complete or recover during a backend outage.
|
||||
- Local operational constraints can delay activation without a remote command round trip.
|
||||
- Boot failure handling remains available independently of the deployment service.
|
||||
- Requested and observed software states have explicit meanings.
|
||||
|
||||
### Negative
|
||||
|
||||
- The device needs durable execution state and interruption handling.
|
||||
- Backend status may remain uncertain until the device reconnects.
|
||||
- Remote cancellation cannot take effect immediately on an offline device.
|
||||
- Backend and device policies need clear precedence and reconciliation rules.
|
||||
|
||||
## Notes
|
||||
|
||||
The implementation must define when an assignment is accepted, any expiry or cancellation rules, and the points at which an operation may safely be stopped. A backend cancellation cannot undo an activation that already occurred while the device was offline.
|
||||
|
||||
Repeated assignments and repeated reports must be reconciled with the operation identity and actual device state. They must not blindly repeat destructive installation steps.
|
||||
|
||||
This decision does not choose polling, push notifications, storage layout, or the boot failure detection mechanism. It assumes those mechanisms can support the stated local responsibilities; later chapters must establish how.
|
||||
|
||||
## Applicability
|
||||
|
||||
This choice fits devices whose local health can be assessed offline and whose recovery must remain available during communication failures.
|
||||
|
||||
Consider external acceptance when successful operation fundamentally depends on a remote system. Specify how to distinguish failure of the candidate from failure of that system or the network.
|
||||
@@ -1,88 +0,0 @@
|
||||
# ADR-012: Separate Update Management from Installation
|
||||
|
||||
* **Status:** Proposed
|
||||
* **Date:** 2026-09-21
|
||||
|
||||
## Context
|
||||
|
||||
This educational example considers a device with product-specific update conditions and an installation mechanism that already understands its artifact format. The device may later need more than one mechanism, such as a system image installer and an application package manager.
|
||||
|
||||
Product policy includes when updates are allowed, which local conditions must hold, and how installation relates to activation and health assessment. Installation requires different knowledge: how to validate and prepare a particular artifact and what state remains after interruption.
|
||||
|
||||
[ADR-005](ADR-005-package-based-updates.md) introduces this distinction for package-based updates. This decision applies the same reasoning to the wider device architecture.
|
||||
|
||||
## Decision
|
||||
|
||||
Separate update coordination and product policy from artifact-specific installation responsibilities.
|
||||
|
||||
The update manager evaluates assignments and local conditions, coordinates execution, and tracks the overall operation. The installer owns the artifact-specific operations it implements and reports their results and recoverable state.
|
||||
|
||||
Assign downloading, verification, activation, and recovery integration explicitly according to the selected mechanism. Reuse capabilities already provided by the installer or framework. Do not introduce a second coordinator where an existing framework already fulfills the required management role.
|
||||
|
||||
This is a logical separation. The roles may be modules in one program, existing framework components, or separate processes.
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
- Product operating policy should be understandable independently of artifact-writing code.
|
||||
- Existing installers should retain responsibility for the operations they support.
|
||||
- An installer completing its work does not necessarily mean that the new software is active or healthy.
|
||||
- Interruption handling requires accurate information from the component that performs the operation.
|
||||
- Multiple update channels need coordinated access to resources and activation.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Put All Product Policy in the Installer
|
||||
|
||||
One component evaluates operating conditions, installs artifacts, activates software, and reports the outcome.
|
||||
|
||||
This can be sufficient for a small product with one mechanism. In the assumed system, embedding policy into installation code makes it harder to reuse that policy across update channels or change the mechanism independently.
|
||||
|
||||
### Let the Backend Coordinate Installer Commands Directly
|
||||
|
||||
The backend issues low-level commands while the device exposes installation operations.
|
||||
|
||||
This shifts coordination away from local operating state and makes communication failures part of the execution path. It also leaves the device needing local protection against unsafe commands and interrupted operations. [ADR-011](ADR-011-device-controlled-update-execution.md) discusses the execution boundary.
|
||||
|
||||
### Introduce a Universal Installer Interface Immediately
|
||||
|
||||
Every mechanism is hidden behind an identical install-and-rollback interface.
|
||||
|
||||
This appears to simplify coordination but can obscure meaningful differences: a package operation may modify a live filesystem, while an image installer may prepare an inactive target. Recovery guarantees are not interchangeable. Define interfaces around actual requirements and capabilities rather than assuming all mechanisms behave alike.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Product policy has an explicit owner.
|
||||
- Existing installation and verification capabilities can be reused.
|
||||
- Different update channels can participate in a coordinated operation.
|
||||
- Installation completion remains distinct from activation and health acceptance.
|
||||
|
||||
### Negative
|
||||
|
||||
- The boundary needs a defined contract for progress, errors, and interrupted operations.
|
||||
- Manager and installer state can diverge after a crash and must be reconciled.
|
||||
- A generic interface may need mechanism-specific capabilities or restrictions.
|
||||
- Separate processes, if used, introduce communication and permission management costs.
|
||||
|
||||
## Notes
|
||||
|
||||
For each integration, establish:
|
||||
|
||||
- how an operation is identified and its current state queried;
|
||||
- which component retrieves content and performs each required verification;
|
||||
- whether installation prepares an inactive candidate or changes running software;
|
||||
- what “completed” means and what remains before activation;
|
||||
- whether retry, cancellation, and recovery are supported at each stage;
|
||||
- which component owns activation and confirmation;
|
||||
- how concurrent operations are prevented from conflicting.
|
||||
|
||||
The manager must not infer that installation failed solely because its connection to the installer was lost. It must inspect or reconcile the actual state before retrying.
|
||||
|
||||
Likewise, the manager cannot promise rollback merely because an installer exposes a downgrade command. Software, persistent data, and compatibility requirements determine whether recovery is possible.
|
||||
|
||||
## Applicability
|
||||
|
||||
This separation is useful when product policy is substantial, when existing installation tools are reused, or when several update channels need coordination.
|
||||
|
||||
A small single-purpose updater may implement both responsibilities together. Preserve clear ownership without adding processes or abstraction layers solely to match the diagram.
|
||||
Reference in new issue
Block a user