feat(itch): update detection and safe updates for installed games (#1665)

## Summary

Adds update detection for installed itch.io games. This is PR4 of the
itch.io store rework (browse, filters, game page and collections are
merged; Linux support is #1589). Butler patching comes later as an
add-on pack. Updates here download the full build.

## What changed

- `ItchUpdates` (new): compares each installed itch game with the
uploads itch lists for it (`GET /games/{id}/uploads`), using what the
install already saves: `installVersion` (the upload's `updated_at`) plus
`gameId`, `downloadKeyId` and `uploadId` in `extra`.
- The installed upload is still listed and has a later `updated_at`: an
update.
- The installed upload is gone: the newest Windows upload is offered as
a replaced build.
- An install without an `uploadId` compares the newest Windows upload's
date.
- An unknown installed version, or no answer from itch, never reports an
update.
- The check walks installed games one at a time, one second apart, and
logs `itch.io: checked <n> installed games, <m> with updates`. It runs
when the itch tab opens (at most every 6 hours) and from the new button.
A game itch did not answer for keeps its last result. Results are cached
in the itch preferences until the update is installed or the account
signs out.
- Library: games with an update show an "Update" label on their tile and
row. A Check for updates button in the Library header (itch tab only)
runs the check on demand, shows progress, and ends with a toast:
"Updates available: N" or "Up to date".
- Game page: an Update button appears for installed itch games with an
update. A replaced build asks first and names the new file. A plain
newer build updates directly.
- Safe updates: an update never extracts into the live game. The archive
is unpacked into `.droiddeck-update` inside the game folder, and the new
build must contain an executable before any game file is touched. A
failed or cancelled download or extraction removes the staging folder
and leaves the game as it was. Then `ItchStaging.merge` moves the staged
files into place with renames inside one folder. A staged file replaces
the file with the same path, directories are merged, and anything the
new build doesn't contain (saves, settings, install record, launcher,
art) stays. The install record is marked updating just before the move,
so an interruption there is resumable.
- New strings `stores_itch_updates_found` and
`stores_itch_update_replaced` in all 33 locales. The button label, toast
and dialog buttons reuse existing strings.
- `docs/development/itch-updates.md` describes the feature.

## Notes

- One extra copy of the build's size must be free while an update runs.
- Files the developer removed in the new version stay in the game
folder, because everything the new build doesn't contain is kept.
- The final rename step is not an all-or-nothing swap. A crash or power
loss inside it leaves the game marked updating and resumable.
- The update reruns the normal install over the game's own folder and
storage location.

## Tests

- `ItchUpdatesTest` (Robolectric, like the other itch tests): newer,
same and older stamps, replaced upload falling back to the newest
Windows build, unknown installed version, no answer, an install without
an upload id, and the cache round trip.
- `ItchStagingTest`: new files replace old ones, other files stay, and a
file replacing a directory and the other way round.
- Not run on a device or compiled locally; relying on CI. The controller
focus behaviour of the new buttons is untested.
This commit is contained in:
Kurt Himebauch authored and GitHub committed 2026-10-28 09:36:19 -04:00
commit 8f6b2a4123
46 files changed
+656 -26

No files matched your search

+44
View File
@@ -0,0 +1,44 @@
# itch.io updates
An installed itch game is checked against the uploads itch lists for it. A game with an update shows an
Update label on its Library tile and an Update button on its game page. A Check for updates button sits
in the top right of an installed itch game's page, next to the delete button, and checks that game only.
## Detection
The install record (`.droiddeck-store.json`) keeps three things from the install: the upload's
`updated_at` as `installVersion`, and `gameId`, `downloadKeyId` and `uploadId` in `extra`.
`ItchUpdates.evaluate` compares them with `GET /games/<id>/uploads`:
- the installed upload is still listed and its `updated_at` is later: an update to the same upload;
- the installed upload is gone: the newest Windows upload is offered as a replaced build;
- an install without an `uploadId` compares the newest Windows upload's stamp;
- an unknown installed version or no answer from itch never reports an update.
The automatic check walks the installed itch games one at a time, one second apart, and logs
`itch.io: checked <n> installed games, <m> with updates`. It runs when the itch tab opens, at most every
six hours. The button on a game page checks only that game, at any time, answers with a toast ("Update
available", "Up to date" or "Sync failed") and logs `itch.io: checked <title>, ...`. A game itch did not answer for keeps its last
result, and the six-hour clock only advances after a fully answered pass. Results are kept in the itch
preferences until the update is installed or the account signs out.
## Installing
The Update button reruns the normal install over the game's own folder, keeping its storage location.
For a replaced build the game page asks first and names the new file.
An update never extracts into the live game. The download goes to the scratch folder, as for any
install, and the archive is unpacked into `.droiddeck-update` inside the game folder. The new build is
checked there (an executable must be found) before a single game file is touched. A failed or cancelled
download or extraction removes the staging folder and leaves the game as it was.
Only then does `ItchStaging.merge` move the staged files into place, which are renames inside one
folder: a staged file replaces the file with the same path, directories are merged, and anything the new
build does not contain (saves, settings, the install record, launcher and art) stays. The install record
is marked updating just before the move, so an interruption in that short step is resumable, and the
finished record carries the new `installVersion` and `uploadId`. Free space for one extra copy of the
build is needed while the update runs.
A cancel that arrives before the files are moved in stops the update and removes the staging folder. Once
the move has started the update is past the point of no return: it finishes and writes the new record, so
a cancel during that short step cannot leave new files under an old record.