3 unstable releases
0.2.1 | Aug 5, 2024 |
---|---|
0.2.0 | Aug 2, 2024 |
0.1.0 | Mar 12, 2024 |
#1321 in Network programming
67 downloads per month
Used in mock-omaha-server
535KB
11K
SLoC
Omaha Client Library
Updated: 2024-08
This is a platform- and product-agnostic implementation of the client end of the Omaha Protocol protocol for signaling that updates are available to a device or application.
Overview
Design Goals
- Features: All protocol features needed by a device that wishes to use the Omaha protocol for update management.
- Correct Operation at Scale: When used at scale, there are behaviors that must be implemented to ensure that global synchronization does not occur, and if some outside action causes a large number of clients to synchronize, they need to quickly de-synchronize.
- Testability: Full-coverage of both normal and abnormal use-cases via unit-tests.
- Modularity: Clear separation of modules for testability and portability via Rust Traits.
- Sepration of concerns: The state machine for the protocol, and the policy that governs it, are wholly separate for testabilty.
High Level Design
This is a general overview of the major conceptual components of the library:
The omaha client library provides for these main pieces:
- An App struct which is used to define the thing that needs update checks.
- The State Machine for the protocol.
and the definitions (via Traits) for an implementor using the library to provide the following:
- The Policy for the
StateMachine
to use when it needs to make decisions. - The PolicyEngine which gathers the system data that the
Policy
needs to make decisions for theStateMachine
. - The Installer for performing installations / updates.
- The Observer for providing library users with state and progress.
This split allows the implementor of a binary or update-check service to focus on the platform- and
product-specific aspects of the Policy
, Installer
, etc.
The relationships between the StateMachine
and the other components is as follows:
State Machine and Policy:
The StateMachine
asks the Policy
various questions, such as "is it time to check for an
update?" or “can an update be installed right now?”.
The Policy
implementation itself is stateless, self
-less, and idempotent. It MUST NOT track any
state of its own, and repeated questions with the same arguments MUST have the same answer.
Policy Engine and the Policy itself
The Policy
answers questions, but to do so, it often needs data from the system (e.g. the current
time). The Policy
can't gather any data itself. All the information that it uses to base its
decisions on comes to it from the PolicyEngine
, which is the intermediary between the
StateMachine
and the Policy
.
The PolicyEngine
takes the arguments passed to it from the StateMachine
, adds the data that it
needs to gather (called PolicyData
), or the state that it's been tracking, and calls upon the
Policy
to make a decision which is returned to the StateMachine
.
While the Policy
is stateless, the PolicyEngine
almost certainly is not, but only acts to gather
and hold state that it can pass to the Policy
via PolicyData
.
State Machine and Installer:
The StateMachine
instructs the Installer
to perform an update and the Installer
provides
progress and status notifications back to the StateMachine
as the update is downloaded and
applied. When complete, the StateMachine
may signal the Installer
to reboot.
State Machine and Installer (InstallationPlan)
The StateMachine
takes the Omaha response, and after parsing/validating it from a protocol point
of view, hands it off to the Installer
to create an InstallPlan for performing the update that was
contained in the response.
StateMachine
The StateMachine
has two parts:
- An outer loop which initiates regular checks for updates.
- An inner process flow which performs the requisite requests to Omaha to propertly check for, and provide feedback on, an update.
The process flow is:
Tasks that are fully synchronous (and internal to the StateMachine
) are in blue, with the tasks
that require asynchronous operation in red. Error-path transitions are in red, success-path
transitions are in green, and the transitions that are taken for both error and success cases are in
black.
There are a number of “don’t care” tasks, specifically around the reporting of events and errors to
Omaha. These are “best effort” actions that are taken, and a response waited for, but if no
response comes, or it’s malformed, the StateMachine
doesn’t take different action from the success
case, does not retry, and continues on to the next task.
The error cases on the left involve the emitting of local status messages, and an ending of the protocol, without needing to signal Omaha of that fact. These are cases where an update check cannot be performed at this time, or the update check itself fails (at the transport layer), or the response says there is no update to be performed.
The error cases on the right involve a need to be reported to Omaha. They are, in order: a
malformed response from Omaha, a response and InstallPlan
that cannot be performed based on the
current PolicyData
or a Policy
decision, or an error during the performing of an update.
Testing and development
This repository comes with a "hello world" example to demonstrate how the library can be used in programs. More details about the example can be found in its own README.md.
This repository also contains a mock server implementation of the omaha protocol which can be used for end-to-end testing of programs including the http request/response schemes. The mock server is described in its own README.md, including a canonical example how the hello world example can be run against the mock server.
Dependencies
~10–18MB
~243K SLoC