Update Manager: state machine, checks and background jobs
The full update chain: registration, check, the download-and-prepare state machine, activation steps, health check, settings, the two background jobs and the permission keys.
The Update Manager controls the installation's update process, connected to the central release server. The controller is thin: the logic lives in the update service library, the SQL in the system/update and system/migrate models. Permissions are requested through a helper that calls canAction, so the automatic extractor shows no keys, but the keys are actually checked.
Data model
Table names carry the installation's own prefix in the database.
| Table | Role |
|---|---|
update_config | server, channel, automatic mode, window, interval, backup target, registration (ID, secret, key version), last check result |
update_run | update and backup runs with a state machine |
update_log | log lines per run |
update_backup | backups (dump + code zip), verification state |
migration | history of versioned migrations |
Process
- Registration (
update.register): installation ID + one-time code to the server's register endpoint; the returned secret, key version, channel and operating model are stored. In local mode (this installation is the release server) through local transport. - Check (
update.check): signed request with ETag support; classificationup_to_date,available,not_allowed,unreachable,revoked,unregistered. No package is downloaded. - Preparation (
update.start,update.advance,update.cancel): one run at a time; the state machine advances in 15-second slices:authorize→download(resumable, at most 3 attempts per token) →verify(manifest signature, size, SHA-256, PHP and framework requirements, minimum previous version) →stage(unpack into the staging directory, tree check) →preflight(drift, syntax, dependencies, writability, twice the free space) →backup→ready. Without approval:waiting_approval. Cancel only before activation, deleting staging and partial download. - Activation (
update.approve): maintenance mode with 30-minute self-expiry; waits at most 60 s for the running scheduler worker (otherwisewaiting_window); installs the current version's recovery tool, web recovery for 24 hours; differential backup; versioned migrations from the staging tree (on error the code is not swapped); schema compatibility measurement; directory swap with two renames (previous tree underprevious/); vendor sync; OPcache and template cache cleared. - Health check: HTTP probe to the catalog endpoint
api/update.healthwith a one-time token; if the server cannot reach itself,verify_pending, confirmed by the next admin page load. Faulty new code is swapped back automatically if the schema is additive. - Success: installed version raised, notification, report to the server;
previous/keeps at most 2 trees,failed/at most 1.update.retryreruns failed versioned migrations.
Background jobs
| Job | Behaviour |
|---|---|
update_check | system level, always on; skipped on unregistered installations; forced check; without an active run it picks up central requests (install only if central installation is allowed, otherwise prepare and wait for approval); notifies once about a new version; in patch mode starts the eligible, licensed PATCH step. Rescheduling: interval + 0–59 minutes derived from the installation ID + 0–9 random minutes. |
update_apply | event job: advances the active run without waiting for the worker lock; if not final, requeues itself after 1 minute, or after 15 minutes while waiting for approval or the window, with duplicate protection. |
Settings and validation
update.save: server URL (https:// only), channel (stable, beta, dev), automatic mode (off, patch), window (HH:MM-HH:MM), interval 1–168 hours, accept direct deployment, accept central install requests, backup target (local, gdrive + account + folder), backups kept 1–20, notification e-mail. Error keys: error_value, error_window, error_backup_gdrive, error_https. Google accounts are loaded only with the settings permission.
Permissions
| Key | Class | Opens |
|---|---|---|
list | SYSTEM | page, status, runs, backups, migrations |
check | SYSTEM | check |
download | SUBSCRIPTION | preparation; advance and cancel with download or install |
install | SYSTEM | install, approve, retry |
settings, register | SYSTEM | settings, registration |
debug | SYSTEM | not read by the templates; no effective use can be determined |
No content scope: installation-level technical data. Token, manifest, signature and internal backup state are never sent out with run data. The central server ties downloading to the system/update + download function permission of the client's users and an active subscription.
Known limitations
The full chain has been tested on a real database with local transport; it has not yet run on a live central server with a real signing key, HTTPS transport and a real Drive archive.