Aidget's updater runs in the desktop GUI process. It checks the project's stable GitHub Releases, downloads the asset for the current platform, verifies its checksum, stages it, and replaces the installation through a platform-specific path. The main window renders the updater's snapshot; it never contacts GitHub itself.
This document describes the behavior implemented in src/update/ and
src/runtime/update.rs.
GUI setup creates one UpdateService, registers it as shared Tauri state, and
starts the launch check. The check waits five seconds so the windows and widgets
can initialize, then reads settings.toml for the GitHub token and the
automatic-download preference. If the settings cannot be read, the launch check
ends with a log message and no request.
There is no poller, scheduler, or recurring timer. After the launch check, updates are checked only when the user invokes one of the update commands. Rust debug builds skip the launch check entirely.
Every published UpdateSnapshot is emitted to the main window as
aidget://update. This is how the window learns about a launch check that was
already running before it loaded. While a download or check is active, the
window also polls update_state for progress.
build.rs sets AIDGET_BUILD_STAMP; the updater uses that stamp as the running
version. A build may replace itself only when the stamp parses as a release
version and was produced by an exact tag.
| Build | Example stamp | Self-updates |
|---|---|---|
HEAD is exactly on a tag |
v0.1.3 |
yes |
| Commits after a tag | 0.1.0-5-gabc1234 |
no |
Dirty working tree recorded by git describe |
0.1.0-dirty |
no |
No tag or usable git describe result |
0.1.0-untagged |
no |
An exact tag wins even when the tree is dirty because the release workflow checks out the tag and then writes the version into the manifests before building. A build whose stamp cannot be parsed is also treated as a source build. A semver pre-release tag is still a release build, but the update feed only offers stable releases.
Rust debug builds have an additional guard: cfg!(debug_assertions) is exposed
as UpdateSnapshot.is_debug_build and overrides the build stamp. They never
download or install, even if the executable happens to be built at a release
tag.
The About page's displayed version comes from the normal application version;
UpdateSnapshot.current contains the update-specific build stamp. The source
state, not the displayed version string, communicates that a build cannot
replace itself.
Production builds read releases from the fixed aidget-ai/aidget repository.
Tests can pass another base URL and repository through
UpdateService::for_build; there is no runtime setting for redirecting an
installed application to another repository.
The check reads GitHub's paginated releases endpoint:
GET /repos/aidget-ai/aidget/releases?per_page=100&page=N
Each response is limited to 8 MiB and has a 30-second request timeout. At most 20 pages are read. Draft releases, releases marked as pre-releases, and tags with a semver pre-release component are excluded. Invalid SemVer tags in an otherwise eligible release fail the check instead of being skipped.
Eligible releases are sorted newest-first by semver precedence. Build metadata does not affect precedence. Pagination stops after a short page, or once the current build's version has been reached; this gives release notes enough older stable releases without walking the entire feed.
A 404 whose GitHub error message is exactly Not Found means the repository
has no published release and settles as no_release. Other non-success
responses are errors. When GitHub reports a rate limit, the error includes the
wait from x-ratelimit-reset.
The configured GitHub token is used only on the releases request. It is
attached only when the URL is HTTPS on api.github.com; a token-bearing
metadata URL for any other host is refused. Asset and SHA256SUMS downloads
never receive the token. Network URLs must use HTTPS, with loopback HTTP
allowed for the local test server. Redirects are followed only while they stay
on HTTPS, with at most five hops.
UpdateSnapshot.state describes the current flow:
| State | Meaning |
|---|---|
idle |
No check has run in this process. |
checking |
A feed request is in flight. |
latest |
The newest stable release is not newer than this build. |
source |
This build cannot replace itself, including debug builds. |
no_release |
No stable release has been published. |
found |
A newer stable release exists but has not been downloaded. |
downloading |
The selected asset is being downloaded. |
ready |
A verified download is available to install. |
installing |
Replacement is running, or finished successfully and the process is about to exit. |
error |
The last step failed; error contains the reason. |
The normal transitions are:
idle
└─> checking ─> latest | source | no_release | found | error
found ─> downloading ─> ready ─> installing
error
UpdateSnapshot.staged is separate from state: it reports whether the service
currently holds a verified download. It can therefore remain true while the
state is ready with a failed-check error, or error after a failed install.
The verified file is not resumed or rediscovered after the process exits.
A successful install clears staged and leaves the state at installing until
the process exits. A failed install leaves the verified download staged so the
user can retry it.
A check that fails does not discard an already verified download. With a staged
file the state becomes ready and the snapshot carries the error; without one
it becomes error. A check that still names the staged version also settles as
ready instead of downloading it again. If the feed moves to an older version
than the staged file, that staged file is discarded as a channel regression.
The main window has one stateful action in the About version row and another
copy in the global page header outside About. The header copy is hidden on
About and in debug builds. For latest, no_release, and source, the action
shows the result for three seconds and then returns to Check for updates;
the status line continues to describe the state.
The action calls:
update_checkwhen no update is actionable. This runs the normal feed check with the saved automatic-download preference.update_applyforfound,ready, or anerrorthat still has a release. This checks the feed again with automatic downloading forced on. If the recheck yields a verifiedreadystate without an error, the verified file is installed. A newer release is downloaded and verified before installation.
A failed recheck never installs an older staged file. It leaves the verified download in place and returns its error. The Update action works even when automatic downloading is off.
The action is disabled while the state is checking, downloading, or
installing. The download label includes a percentage when the backend knows
the asset size.
settings.toml contains:
| Key | Default | Meaning |
|---|---|---|
auto_download |
true |
Start downloading as soon as a check finds a newer stable release. |
The key is part of UiPreferences and is saved with the other main-window
preferences. A missing key reads as true, and settings::ensure adds it to an
existing settings file. Changing the switch affects later checks; it does not
start a check by itself.
In a Rust debug build the switch is shown as off and disabled, but the saved preference is not changed. The manual update action and the global header action are hidden. The Release notes action remains available; opening it runs a normal feed check with automatic downloading forced off so the newest five stable release notes can be loaded.
For the selected release, the updater chooses the asset whose complete public filename exactly matches the current target. A DMG, a backup, or a similarly named file is not accepted.
Each download gets a unique temporary directory. Preparing a replacement removes
the previous staged directory. The asset is written while a SHA-256 is computed,
with a 600-second total timeout, and progress is published through done and
total.
The expected checksum comes from:
- The asset's
digestwhen it is a validsha256:<hex>value. - Otherwise, the release's
SHA256SUMSasset, matched by the complete filename.
No digest and no matching SHA256SUMS entry is an error. A checksum mismatch
removes the file and its download directory. Only a verified download becomes
staged and installable. On Windows the downloaded directory is left for the
NSIS installer after a successful install; other platforms remove it.
Stable release notes are cached at
<data-directory>/state/update/releases.json. The cache is versioned, limited
to 8 MiB, and written atomically. A missing cache is empty; a malformed cache is
a service-initialization error; an unwritable cache makes the check fail.
The cache stores:
- Up to five of the newest stable releases, with their complete bilingual bodies.
- Maintenance-only release versions separately from visible release bodies, so cached ranges can be re-filtered after the installed version changes.
- The current-to-target range for a pending or installed update.
On startup, a retained range is reused when the running build is unknown or matches either endpoint. Otherwise recent notes are filtered to the running release. After a check:
- A release build older than the latest release gets the range from its current version, exclusive, through the latest version, inclusive.
- An already-latest release build reuses a retained range ending at its version; without one, it gets its own release notes bounded below by the previous stable release.
- A source or debug build gets up to five of the newest stable releases.
Release bodies with no text are omitted. The range survives restarts so notes remain available while an update is pending and after it has been installed.
Versions marked <!-- aidget:internal-only --> remain in the cached release set
for range selection but are filtered from normal note entries. Mixed ranges keep
their user-visible releases. If the whole range is maintenance-only,
UpdateNotes.maintenanceOnly makes the dialog show one localized notice without
category headings or version badges. Retaining those versions also lets a cache
re-filter correctly after installing a middle maintenance version. Older caches
default the new fields to empty or false.
The dialog selects the interface language from the release body. English is the
text before <!-- lang:zh -->; Chinese is the text after it. Rendering stops at
the ### Installation or ### 安装说明 footer. Level-two headings become
categories, and entries from different releases are merged under the same
category. When more than one release is present, each entry carries its source
version badge.
The Markdown is converted into a restricted DOM; block quotes are sanitized before insertion. Images are reduced to their alt text. Only HTTPS links are kept clickable, and they open through the platform URL opener.
Release asset names omit the version:
| Platform | Updater asset | Manual update | Install on quit |
|---|---|---|---|
| macOS Apple Silicon | aidget-darwin-arm64.zip |
Unpack and replace the .app, then restart |
Replace the .app, then exit |
| macOS Intel | aidget-darwin-amd64.zip |
Unpack and replace the .app, then restart |
Replace the .app, then exit |
| Windows x64 | aidget-windows-amd64.exe |
Run NSIS with restart | Run NSIS without restart |
| Windows ARM64 | aidget-windows-arm64.exe |
Run NSIS with restart | Run NSIS without restart |
Linux x86_64 with dpkg |
aidget-linux-amd64.deb |
pkexec dpkg -i, then restart |
Skipped |
Linux x86_64 without dpkg, with rpm |
aidget-linux-amd64.rpm |
pkexec rpm -U, then restart |
Skipped |
Linux ARM64 with dpkg |
aidget-linux-arm64.deb |
pkexec dpkg -i, then restart |
Skipped |
Linux ARM64 without dpkg, with rpm |
aidget-linux-arm64.rpm |
pkexec rpm -U, then restart |
Skipped |
Windows and Linux select the updater for their runtime architecture. Linux
detects dpkg and rpm on PATH; dpkg wins when both exist. A platform,
architecture, or package-manager combination without an updater asset can still
check the feed, but downloading reports that the installation cannot update
itself in place.
DMGs are for manual installation only. SHA256SUMS covers every updater asset.
There is no AppImage updater asset.
The running executable is resolved through symlinks and must be inside
Contents/MacOS of an .app bundle. The parent directory is probed for
writability. The updater extracts the ZIP into .aidget-update beside the
bundle with ditto -x -k, requires an .app at the archive root, moves the old
bundle aside, moves the new one into place, and removes the previous copy after
success. If the new bundle cannot be moved into place, the old bundle is restored
before the error is returned.
Manual updates start the new executable after the replaced process exits. Installing on quit leaves the new bundle for the next launch.
The downloaded executable is Tauri's NSIS installer. A manual update launches it
with /S /UPDATE /R; current application arguments are preserved with /ARGS
after /R. Installing on quit uses /S /UPDATE and does not start the
application again. The installer stops the running application before copying,
so Aidget does not wait for replacement to finish.
The updater runs the package manager through pkexec:
pkexec <absolute-dpkg-path> -i <staged-deb>
pkexec <absolute-rpm-path> -U <staged-rpm>
The tool path is resolved before elevation so the elevated command runs the package manager selected by the application. A failed package command reports that the previous version is still installed.
Package installation is skipped during quit because the password prompt would appear while the window disappears. A manual update schedules the saved executable after the old process exits; the package manager owns binary replacement, so the saved install path remains the launch path.
For macOS and Linux manual updates, a /bin/sh helper waits for the old process
to exit, then execs the saved executable with its original arguments. Output
is appended to <home>/logs/relaunch.log under the current instance's data
directory, including a custom --home; logs/ is created automatically. Starting
the saved executable directly avoids activating another bundle with the same
identifier.
Zombies count as exited because they have released IPC. CLI/MCP parents reap GUI children on a background thread.
On Windows the NSIS installer performs the restart. If scheduling the macOS/Linux replacement fails, Aidget reports that the update is in place but must be launched manually.
Only one operation may own the update service at a time. checking,
downloading, and installing are all considered in flight. A second check
returns the active snapshot, and an install or download that cannot claim the
service returns without changing it.
Closing the last window does not exit this tray application. A quit while a
replacement is running is deferred and released after the install settles. A
failed install releases the deferred quit without retrying the same replacement.
UpdateState::installing is not the quit gate by itself because a completed
install keeps that state until the process exits; a separate in-progress flag
covers only the file-replacement window.
On macOS, Cmd+Q can reach the native exit path without an ExitRequested event.
The exit handler therefore waits for an active replacement to finish instead of
allowing the process to disappear between bundle renames. If a quit races the
install claim, the losing path also waits once the claim is visible.
At normal exit, install_on_quit installs a staged update without restarting for
macOS and Windows. It does nothing when there is no staged download, when an
install has already settled during that exit, or when Linux elevation would be
required. Installing successfully on quit means the next launch is the new
version.
The main window can call:
update_state: read the current snapshot.update_check: check the feed and download when the saved preference allows.update_apply: recheck, then download and/or install the release.
The commands are in command_names::MAIN_COMMANDS, are granted only by
capabilities/main.json, and each checks that the caller is the main window.
Widget windows, which load third-party content, cannot install updates.
UpdateSnapshot and the release-notes types are shared Rust types exported to
TypeScript with pnpm typegen. src/runtime/update.rs owns the launch check,
settings policy, event emission, quit handling, and relaunch; the window renders
the snapshot and invokes the commands.
src/update/
├── service.rs state machine, ownership guards, install hand-off
├── service/install.rs
│ per-request install outcomes and cleanup
├── snapshot.rs UpdateState and UpdateSnapshot
├── github.rs release feed, filtering, asset selection, errors
├── fetch.rs HTTP client, URL security, token scope
├── download.rs streaming download and text assets
├── stage.rs per-download directory and asset preparation
├── verify.rs digest and SHA256SUMS verification
├── notes.rs retained release notes and range selection
├── target.rs platform, architecture, package-manager selection
├── version.rs semver comparison, build stamp, tag normalization
└── install/
├── macos.rs bundle resolution, ZIP extraction, swap and rollback
├── windows.rs NSIS flags and launch
└── linux.rs dpkg/rpm through pkexec and relaunch
The launch check and Tauri wiring are in src/runtime/update.rs; the main
window's rendering and polling are in ui/src/main/update.ts and
ui/src/main/release-notes.ts.
Local checks:
pnpm install --frozen-lockfile
pnpm exec vp check
pnpm test
pnpm typegen --check
cargo fmt --check
AIDGET_CHECK_TARGET=1 cargo check --lib
cargo testThe update tests use a local mock server and cover release filtering and pagination, build eligibility, state transitions, download retries, checksum handling, asset selection, release-notes caching, the macOS bundle swap, Linux package commands, Windows installer arguments, and relaunch ordering. They do not contact GitHub.
CI compiles and tests the platform-gated paths on macOS, Windows, and Linux,
including native Windows ARM64 and Linux ARM64 runners, but the automated suite
does not perform a real NSIS installation, answer a Linux pkexec prompt, or
install from a read-only/DMG location. macOS and Windows release artifacts are
currently unsigned, so Gatekeeper or SmartScreen may still warn on first launch.
The updater has no:
- recurring check or background daemon;
- beta/stable channel selection, mirrors, or proxy settings;
- custom feed,
latest.json, or runtime repository override; - resumable download or cross-restart staging;
- Homebrew, container, or AppImage detection;
- blocked-version bookkeeping;
- bare-file replacement for
.deb,.rpm, or Windows; - rollback after a completed replacement fails to start;
- automatic installation of a Linux package during quit.