Self-Updater Mechanism
Relevant source files
The following files were used as context for generating this wiki page:
The Self-Updater Mechanism provides a structured workflow for detecting, downloading, and applying updates to the Infrahub toolset binaries. It enables the application to check against the GitHub Releases API, compare versions, and perform an in-place replacement of the running binary across multiple operating systems and architectures.
This mechanism is designed for operational safety by requiring user confirmation before applying updates and utilizing checksum verification to ensure the integrity of downloaded artifacts.
Architecture and Workflow
The updater follows a linear progression from version detection to binary replacement. The process involves four primary phases: discovery, selection, verification, and application.
Update Flow Overview
The following diagram illustrates the sequence of operations performed during a self-update request.
The workflow ensures that the system only proceeds with updates that are compatible with the host's operating system and architecture.
Sources: src/internal/updater/updater.go, src/internal/updater/install.go
Version Discovery and Selection
The updater interacts with the GitHub API to retrieve release information. It targets the opsmill/infrahub-backup repository to find available tags and associated assets.
- Remote Fetching: The system retrieves the latest releases using the GitHub API. It focuses on identifying semantic version tags (e.g.,
v1.2.3). - Version Comparison: The updater compares the
currentVersionof the running binary against thelatestVersionfound on GitHub. - Architecture Matching: It filters release assets based on the host's
runtime.GOOS(e.g., linux, darwin, windows) andruntime.GOARCH(e.g., amd64, arm64).
GitHub Asset Structures
| Field | Description | Source |
|---|---|---|
TagName | The version string associated with the release (e.g., v1.0.1). | src/internal/updater/github.go:25 |
Assets | A list of downloadable files, including binaries and checksum files. | src/internal/updater/github.go:26 |
BrowserDownloadURL | The direct link to download a specific asset. | src/internal/updater/github.go:19 |
Sources: src/internal/updater/github.go:15-30, src/internal/updater/updater.go:40-60
Download and Integrity Verification
Once a compatible asset is identified and the user provides consent, the updater begins the retrieval process.
- Binary Retrieval: The updater downloads the specific binary for the host platform to a temporary location.
- Checksum Retrieval: It concurrently downloads a
checksums.txtfile containing SHA256 hashes for all release assets. - Integrity Validation: The system calculates the SHA256 hash of the downloaded binary and compares it against the expected hash found in the checksum file. If the hashes do not match, the process terminates to prevent the execution of corrupted or malicious code.
Sources: src/internal/updater/install.go:45-80, src/internal/updater/apply.go:10-25
Binary Application
The application phase handles the replacement of the existing executable file. This process is OS-specific due to how different kernels handle open file handles for running processes.
- In-Place Replacement: On Unix-like systems, the updater typically renames or moves the new binary over the old one.
- Permission Preservation: The updater ensures that the execution permissions of the original binary are mirrored on the new binary.
- Rollback Strategy: If the replacement fails (e.g., due to permission errors or disk space issues), the updater attempts to maintain the original binary's functionality.
The sequence ensures that the binary is fully written and verified before the original file is modified.
Sources: src/internal/updater/apply.go:30-55, src/internal/updater/install.go:85-100
Configuration and Implementation Details
The updater utilizes a Proceed function to handle interactive user prompts, allowing users to opt-out of an update before any changes are made to the filesystem.
Key Functions
| Function | Action | Path |
|---|---|---|
CheckForUpdate | Compares versions and returns the latest release if an update is available. | src/internal/updater/updater.go:35 |
DownloadAsset | Handles HTTP requests to fetch binary data from GitHub. | src/internal/updater/install.go:50 |
VerifyChecksum | Validates the downloaded file against the provided SHA256 hash. | src/internal/updater/apply.go:15 |
ApplyUpdate | Replaces the current executable with the new binary. | src/internal/updater/apply.go:40 |
Sources: src/internal/updater/updater.go, src/internal/updater/install.go, src/internal/updater/apply.go
Conclusion
The Self-Updater Mechanism provides a safe and efficient way to keep the Infrahub toolset current. By combining GitHub API integration with architecture-aware asset selection and strict checksum verification, it minimizes the risks associated with manual binary updates. The requirement for user confirmation ensures that updates occur only when intended by the operator.