83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# ADR-008: Binary Delta Delivery
|
|
|
|
## Context
|
|
|
|
A device may need a large artifact even though much of its content is already present in the installed version. Transferring the complete artifact can be expensive or slow on a constrained connection.
|
|
|
|
A binary delta encodes the changes needed to reconstruct a new artifact from a particular source artifact:
|
|
|
|
```text
|
|
Artifact A + Delta A-to-B = Artifact B
|
|
```
|
|
|
|
This educational example considers a known source version, a validated target artifact, and a device with enough resources to reconstruct the target. It addresses delivery cost rather than the choice of update unit.
|
|
|
|
## Decision
|
|
|
|
Use binary delta delivery when measured savings in transfer size or download time justify the added generation, reconstruction, and maintenance work.
|
|
|
|
Keep the complete target artifact available as an alternative delivery path. Reconstruct and verify the intended target before activation, using the preparation and recovery mechanisms selected for that update unit.
|
|
|
|
## Decision Drivers
|
|
|
|
- Network traffic or download time is a significant constraint.
|
|
- Consecutive artifacts contain enough unchanged content to make deltas worthwhile.
|
|
- The expected source content is available on the device.
|
|
- The device can afford reconstruction time and temporary storage.
|
|
- The release process can maintain a bounded set of supported source-to-target transitions.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- Less data may need to cross the network.
|
|
- Large artifacts can become more practical to deliver over slow links.
|
|
- The target release remains the same artifact regardless of how it is delivered.
|
|
|
|
### Negative
|
|
|
|
- Deltas must be generated and tested for supported starting versions.
|
|
- A missing or modified source can prevent reconstruction.
|
|
- Reconstruction consumes device resources and may offset some download-time savings.
|
|
- The delivery system must handle devices that cannot use the available delta.
|
|
|
|
## Special Considerations
|
|
|
|
### Delivery Is Separate from the Release Unit
|
|
|
|
An image delivered through a delta is still an image release. The complete-system reasoning in [ADR-004](ADR-004-full-system-image-updates.md) remains relevant even when fewer bytes are transferred.
|
|
|
|
Deltas can also apply to other artifacts. They do not establish component independence, atomic activation, or rollback by themselves.
|
|
|
|
### Supported Starting Versions
|
|
|
|
A delta from A to C is not interchangeable with a delta from B to C. Maintaining every possible transition may cost more than the saved traffic.
|
|
|
|
A release process can provide deltas for common starting versions and use the complete artifact for others. When a full transfer is temporarily impractical, the update can be deferred rather than applying a delta to the wrong source.
|
|
|
|
### Verification and Recovery
|
|
|
|
The reconstructed artifact must match the intended, authenticated target. A smaller transfer does not reduce the need to verify what will be installed.
|
|
|
|
A failed reconstruction should leave the working version available. The chosen installation mechanism determines how this is achieved; delta delivery does not supply that protection on its own.
|
|
|
|
### Measure Representative Releases
|
|
|
|
Savings depend on how artifacts change and how they are built and encoded. A small source-code edit does not necessarily produce a small binary delta.
|
|
|
|
Compare complete delivery and delta delivery using representative releases, including reconstruction cost and the number of older versions that remain supported.
|
|
|
|
## Applicability
|
|
|
|
This approach fits systems where delivery cost is material and artifacts retain substantial unchanged content between releases.
|
|
|
|
Prefer complete delivery when artifacts are small, connections are inexpensive, source versions are unpredictable, or reconstruction and maintenance costs outweigh the saving.
|
|
|
|
## Alternatives Considered
|
|
|
|
- Complete, optionally compressed artifact delivery keeps the transfer path simpler.
|
|
- Smaller independent release units can reduce traffic when component lifecycles justify them; see [ADR-007](ADR-007-independent-application-updates.md).
|
|
- [Versioned filesystem trees](ADR-009-versioned-filesystem-trees.md) can reuse content through a different storage and deployment model.
|
|
|
|
Content reuse need not always use a precomputed source-to-target delta. For an implementation example of block reuse with a full image available, see [RAUC's adaptive update documentation](https://rauc.readthedocs.io/en/latest/advanced.html#adaptive-updates). This is a related mechanism, not the specific delta model selected here.
|