fsylvain/RenewCMS
1
1 Fork 0
Code Issues Pull Requests Packages Projects Releases 19 Wiki Activity

feat: restart to apply update, privileged helper, rollback

Browse Source
This commit is contained in:
fsylvain committed 2026-10-01 21:36:40 +02:00
1 parent 70460e4170
commit 54e8fd5fed
63 files changed
+8635 -164
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

features/updates_restart_helper.feature
+508
View File
@@ -0,0 +1,508 @@
Feature: Updates part 3: Restart, the privileged helper and rollback
As the owner of a RenewCMS site
I want one Restart button that installs the staged release, or just restarts the site, and puts the old version back if the new one does not come up
So that I can update from the browser while the app itself stays unprivileged and sandboxed
Background:
Given slices 1 to 3 of Updates ship in one release
And the app never gains privileges: the documented systemd unit keeps ProtectSystem=strict and only the data directory writable
And only the helper runs as root; it is the same binary, started as "renewcms apply-update" by a oneshot systemd service
And the data directory is the directory that holds DB_FILE; no new env var is added
And the files in the data directory are:
update-restart-request.json (marker, written by the app):
{"kind":"update"|"restart","tag" (update only),"requested_at" RFC3339 UTC,"requested_by" user_id};
update-result.json (written by the helper):
{"outcome":"running"|"succeeded"|"rolled_back"|"failed","kind","tag","from_version","started_at","finished_at"};
update-helper.json (status file, written by enable-browser-updates):
{"version":1,"service","binary","data_dir","installed_at"};
update-running.json (written by the server at every startup):
{"version","pid","started_at"}
And the marker is written atomically (temp file in the data directory, then rename) and deleted by the helper after reading it
And the technical reason of a failure goes to the log or journal only, never into a file the app serves or a response
And the domain package internal/domain/update (stdlib only) gains these interfaces, each faked in tests:
RestartRequestStore (write, read, delete the marker),
ResultStore (read, write and delete the result),
RunningInfoStore (the server writes update-running.json; the helper reads it),
HelperFilesystem (lstat, open with no-follow, read, create-exclusive, copy, rename, remove, chmod, make a fresh private
temp directory, all of them symlink-aware),
ServiceControl (restart and status of the systemd service),
HealthChecker (GET http://127.0.0.1:<port>/healthz, true on 200),
Clock
And the helper logic depends only on those interfaces and on update.SignatureVerifier from slice 2 with the embedded release.pub
And O_NOFOLLOW and lstat behaviour sit behind HelperFilesystem so the logic is tested on any OS; the real adapter is Linux-only
(build-tagged) and is covered by the manual systemd checklist
And RequestRestartUseCase and the extended GetUpdateStatusUseCase depend only on domain interfaces; handlers in
api/handlers/update receive them through NewHandler; only api/dependecyInjection.go builds the adapters
And POST /v1/system/update/restart is mounted in NewSystemRouter behind jwtauth.Verifier, jwtauth.Authenticator,
RequireCurrentToken, RequireVerifiedUser and RequireOwner; there is no limiter
And its optional JSON body is {"kind":"update"|"restart"}, bound to a request struct with
validate:"omitempty,oneof=update restart" and checked by validator.Validate.Struct; an empty body is allowed
And the checks on POST run in this order: no cookie or stale token (401), unverified (403), not owner (403),
malformed body or invalid kind (400), can_apply false (409), job downloading or verifying (409), a restart already pending
or running (409), kind that does not match the state (409), marker write error (500), then 202
And with no body the server picks by state: job "ready" gives kind "update", anything else kind "restart"
And the kind given must match: "update" needs a job "ready"; "restart" needs no job "ready"; otherwise 409 and nothing is written
And POST download and POST restart delete update-result.json before they start a new job or write a marker
And the 202 body is the status JSON with state "restarting" and started_at equal to the marker's requested_at (server clock)
And errors are plain text from http.Error and carry no path or technical detail
And GET /v1/system/update has no side effects; it keeps the 12 keys of slice 1 and gains exactly one key, "finished_at":
the result's finished_at (RFC3339 UTC) whenever a result file exists, otherwise null, whatever the state
And state is one of idle, downloading, verifying, ready, restarting, succeeded, failed, derived from the files by one rule:
marker present, or result "running" younger than 5 minutes: "restarting";
result "running" older than 5 minutes and no marker: "failed", error "install";
result "succeeded", kind "update", tag equal to the running version: "succeeded";
result "succeeded" for kind "restart", or kind "update" whose tag is no longer the running version: "idle";
result "rolled_back": "failed", error "rolled_back";
result "failed": "failed", error "install";
otherwise the slice 2 job state; a missing or corrupt result file counts as no result
And a result persists and is read the same on every GET until POST download or POST restart deletes it
And error is null, "download", "verification", "rolled_back" or "install"
And GET /healthz is unchanged: body "ok", no version header
And the server writes update-running.json at every startup, after the listener is bound and before it serves, atomically; a write error
is logged and is not fatal
And the helper judges a restart by two things: GET /healthz answers 200 AND update-running.json holds the expected version AND it is
NEW: its pid differs from the pid read before the restart, or its started_at is later than the instant the restart command
was issued; a stale file with the old pid or started_at never counts
And main gains a minimal dispatcher before the normal start: the subcommands enable-browser-updates, disable-browser-updates and
apply-update run their own code and never read .env, open the database or listen; "--version" and the normal start are unchanged
And the new subcommands never write a secret value or an env value into a unit file
Scenario: Request an update restart, happy path
Given the owner, can_apply true and a job "ready" for "v2.3.0-beta"
When the owner sends POST /v1/system/update/restart with no body, or with {"kind":"update"}
Then the status is 202 and the body is the status JSON with state "restarting"
And the marker holds kind "update", tag "v2.3.0-beta", requested_by the owner's user_id and requested_at
And update-result.json was deleted first
And the running binary, the staged files and the database are unchanged by the app
And GET reports state "restarting" for any verified user
Scenario: Request a plain restart
Given the owner, can_apply true and no job "ready"
When the owner sends POST /v1/system/update/restart with no body, or with {"kind":"restart"}
Then the status is 202, the marker holds kind "restart" and no tag, and GET reports state "restarting"
Scenario Outline: The kind must match the state
Given the owner, can_apply true and <state>
When the owner sends POST /v1/system/update/restart with {"kind":"<kind>"}
Then the status is 409, no marker is written, the result file and the job are untouched
Examples:
| state | kind |
| no job "ready" (idle) | update |
| a job "failed" | update |
| a job "ready" | restart |
Scenario: Restart site never installs an update another owner just made ready
Given owner A opened the Plain restart dialog while the job was idle
And owner B then made a job "ready"
When owner A confirms and the SPA sends {"kind":"restart"}
Then the status is 409, nothing is installed and the staged files are untouched
And the SPA reloads the card and shows "Ready to install"
Scenario Outline: A bad body is a 400
Given the owner and can_apply true
When the owner sends POST /v1/system/update/restart with <body>
Then the status is 400 with a plain text body and no marker is written
Examples:
| body |
| {"kind":"upgrade"} |
| {"kind":""} |
| {"kind":7} |
| {"kind":"update" |
| not json |
Scenario Outline: POST is guarded like the other system routes
When <caller> sends POST /v1/system/update/restart
Then the status is <status> and no marker is written and no result is deleted
Examples:
| caller | status | body |
| no jwt cookie | 401 | the existing 401 text |
| a stale token version | 401 | the existing 401 text |
| an unverified owner | 403 | the existing unverified text |
| an admin | 403 | apperr.OwnerRequiredErrorMessage |
Scenario Outline: Restart is refused with 409
Given the owner and <condition>
When the owner sends POST /v1/system/update/restart
Then the status is 409, the existing marker, result and job are untouched and no new marker is written
Examples:
| condition |
| can_apply is false (no update-helper.json) |
| the job state is downloading |
| the job state is verifying |
| a marker is already pending |
| the result file reads "running" (helper at work) |
Scenario: Two restarts at once write one marker
When two owners send POST /v1/system/update/restart concurrently
Then exactly one answers 202 and the other 409 and one marker exists
Scenario: The marker cannot be written
Given the data directory is not writable, or a directory sits where the marker file goes
When the owner sends POST /v1/system/update/restart
Then the status is 500 with a plain text body without paths, no marker exists and the job record is untouched
Scenario Outline: GET derives the state from the files and never changes them
Given <files>
When any verified user sends GET /v1/system/update twice
Then both answers are identical, state is <state>, error is <error> and finished_at is <finished>
And no file in the data directory changed
Examples:
| files | state | error | finished |
| a marker is present | restarting | null | null |
| result "running" written 30 s ago | restarting | null | null |
| result "running" written 6 minutes ago, no marker | failed | "install" | its value |
| result "succeeded", kind "update", tag equal to the running version | succeeded | null | its value |
| result "succeeded", kind "update", tag older than the running one | idle | null | its value |
| result "succeeded", kind "restart" | idle | null | its value |
| result "rolled_back" | failed | "rolled_back" | its value |
| result "failed" | failed | "install" | its value |
| no marker, no result | idle | null | null |
| a corrupt result file | idle | null | null |
Scenario: The result lives until the next job
Given a result "rolled_back"
When the owner sends POST /v1/system/update/download and the job reaches "ready"
Then the result file was deleted by the POST, GET reports state "ready", error null and finished_at null
And GET /v1/system/update still has exactly the 12 keys of slice 1 plus finished_at
Scenario: After a successful update the status is consistent
Given a result "succeeded" for "v2.3.0-beta" and the running version "v2.3.0-beta"
Then GET reports state "succeeded", available false, current "v2.3.0-beta" and finished_at set
Scenario: The server writes update-running.json at startup
When the server starts with version "v2.3.0-beta"
Then update-running.json holds {"version":"v2.3.0-beta","pid":<its pid>,"started_at":<now>} written atomically
And it is written after the listener is bound and before requests are served
And a write error is logged and the server still starts
And a second start replaces the file with the new pid and started_at
And the file is not served by any route
Scenario: Healthz is unchanged
When a client sends GET /healthz
Then the status is 200, the body is "ok" and there is no version header, and the route stays public
Scenario Outline: The command dispatcher
When the binary is run with "<args>" and an empty environment
Then <outcome>
Examples:
| args | outcome |
| --version | it prints the version, exits 0 (unchanged from slice 2) |
| enable-browser-updates | it runs the installer, never reads .env or opens the database |
| disable-browser-updates | it runs the uninstaller, never reads .env or opens the database |
| apply-update | it runs the helper, never reads .env or opens the database |
| no arguments | the normal server start |
| an unknown subcommand | a usage message on stderr and a non-zero exit, the server is not started |
Scenario Outline: enable-browser-updates refuses when it cannot work
Given <situation>
When "renewcms enable-browser-updates" runs
Then it exits non-zero with the clear message "<message>" and writes nothing
Examples:
| situation | message |
| the OS is not Linux | Browser updates need Linux with systemd. |
| Linux without systemd (no /run/systemd/system) | Browser updates need systemd, which this machine is not running. |
| not run as root | Run this command as root, for example with sudo. |
| no unit for the service and no flags | Could not find the RenewCMS service. Pass --service, --binary and --data-dir. |
| the data directory cannot be resolved | Could not find the data directory. Pass --data-dir. |
Scenario: enable-browser-updates installs the units
Given systemd on Linux, root, and an existing renewcms.service with ExecStart=/opt/renewcms/renewcms and ReadWritePaths=/var/lib/renewcms
When "renewcms enable-browser-updates" runs
Then it reads the service name, binary path and data directory from the unit, with --service, --binary and --data-dir overriding them
And it writes renewcms-update.path (PathExists= the marker) and renewcms-update.service (Type=oneshot, User=root,
ExecStart=<binary> apply-update with the service, binary, data directory and port as flags)
And the port comes from --port, else from PORT in the service's environment file, else 8080
And it runs daemon-reload and enables and starts the path unit
And it writes update-helper.json last, so can_apply becomes true only when everything else worked
And no secret and no environment value is written into either unit
And it prints what it installed and how to undo it
Scenario: enable-browser-updates is idempotent
Given it ran once
When it runs again, including after the binary path or service name changed
Then the units and the status file are rewritten to the current values, no duplicate unit exists and the exit is 0
Scenario: enable-browser-updates undoes its own partial work
Given writing the second unit, daemon-reload or enable fails
Then the first unit is removed, update-helper.json is not written and the exit is non-zero with the reason
Scenario: disable-browser-updates
Given browser updates are enabled
When "renewcms disable-browser-updates" runs
Then the path unit is stopped and disabled, both unit files and update-helper.json are removed, daemon-reload runs
And the marker and result files, the staged files and backups are left in place
And running it again, or where it was never enabled, exits 0 with a message
And can_apply reads false afterwards
Scenario: apply-update, a plain restart
Given a marker of kind "restart" and update-running.json with pid 100 and started_at T0
When the helper runs
Then it reads the marker without following symlinks, deletes it, and writes the result "running" with started_at
And it records the current update-running.json, restarts the service once and polls until /healthz answers 200
and update-running.json is new (pid differs from 100, or started_at is later than the restart instant)
And it then writes "succeeded" with kind "restart" and finished_at
And the binary and the staged files are untouched
Scenario Outline: A stale running file never counts as success
Given a marker and update-running.json that <staleness> while /healthz answers 200
When the helper polls
Then it keeps polling and it is not declared succeeded or rolled back until a new file appears or 60 s pass
Examples:
| staleness |
| still holds the old pid and old started_at |
| holds the target version but the old pid and an old started_at |
| is missing |
| is corrupt |
| holds the old version with a new pid (for an update) |
Scenario: apply-update, an update, happy path
Given a marker of kind "update" for "v2.3.0-beta" and a staged binary, checksums.txt and checksums.txt.sig under updates/v2.3.0-beta/
When the helper runs
Then it creates a fresh root-owned temp directory with mode 0700 and copies the staged files into it, opening each original with no-follow
And it verifies the signature of the COPIED checksums.txt with the embedded public key
And it verifies the SHA-256 of the COPIED binary against its checksums.txt line, ignoring the earlier job record
And it copies the current binary to <name>.previous, replacing an older .previous
And it writes the verified copy to a temp file in the binary's directory (mode 0755), checks that it still hashes to the verified value,
and installs it with an atomic rename; the original staged path is never installed
And it restarts the service and polls /healthz and update-running.json for up to 60 s
And when /healthz answers 200 and update-running.json is new and holds "v2.3.0-beta" it writes "succeeded", success being declared on the
first matching poll
And it removes the temp directory and updates/v2.3.0-beta/
And the marker was deleted before any other step ran
Scenario Outline: apply-update refuses an untrusted staged binary
Given a marker of kind "update" and <fault>
When the helper runs
Then the current binary is not touched, no .previous is written and the service is not restarted
And it writes "failed", logs the technical reason only, and removes the temp directory and updates/<tag>/
Examples:
| fault |
| the binary was changed after the job verified it |
| checksums.txt was changed |
| the signature is from a different key or is missing |
| checksums.txt has no line for the asset |
| the staged binary is missing |
Scenario Outline: apply-update refuses symlinks
Given a marker of kind "update" and <symlink>
When the helper runs
Then it never reads through the link, the current binary is untouched, there is no .previous and no restart
And it writes "failed" and logs which path was a symlink
And whatever the link pointed to is not read, copied, written or removed
Examples:
| symlink |
| the marker itself is a symlink |
| <data>/updates is a symlink to another directory |
| <data>/updates/<tag> is a symlink to another directory |
| the staged binary is a symlink to /usr/bin/something |
| checksums.txt is a symlink |
| checksums.txt.sig is a symlink |
| a symlink is placed at the result path or at a temp file name |
Scenario: A symlinked marker is removed, not followed
Given the marker is a symlink to a file outside the data directory
When the helper runs
Then the link itself is unlinked, the target is untouched, and the result is "failed"
Scenario: A file swapped after verification is not installed
Given the staged binary is verified and a fake attacker replaces the original staged path with other bytes right after the copy step
When the helper installs
Then the installed bytes equal the verified copy's bytes and not the swapped bytes
And the same holds for a swap during the .previous copy and the final rename
And a swap of the temp file in the binary's directory before the rename is caught by the re-hash and ends as "failed" with the binary untouched
Scenario: Result and temp files are written without following links
Given the service user placed a symlink at update-result.json or at a predictable temp name in the data directory
When the helper writes its result
Then it creates a temp file with create-exclusive and no-follow, then renames it over the result, and the link target is untouched
Scenario Outline: apply-update distrusts the marker
Given a marker whose tag is <tag>
When the helper runs
Then it writes "failed", the binary is untouched, the service is not restarted and nothing outside <data>/updates is read
Examples:
| tag |
| ../../etc/passwd |
| v2.3.0-beta/../../x |
| an empty string |
| v2.1.0-beta (older than the running version) |
| not-a-version |
Scenario Outline: apply-update rolls back when the new version does not come up
Given an update marker and <fault> after the new binary was installed and the service restarted
When the helper runs
Then within the 60 s window it restores <name>.previous over the binary atomically and restarts the service again
And it polls until /healthz answers 200 and a NEW update-running.json holds the old version
And it writes "rolled_back" with from_version and tag and removes the temp directory and the staged files
Examples:
| fault |
| /healthz never answers within 60 s |
| /healthz answers but update-running.json stays old |
| update-running.json holds another version |
| the service restart command fails |
Scenario Outline: apply-update failures around the swap
Given an update marker and <fault>
Then <outcome>
Examples:
| fault | outcome |
| copying to .previous fails | the binary is untouched, the service not restarted, result "failed" |
| the atomic install fails | .previous and the old binary are intact, no restart, result "failed" |
| the rollback restore itself fails | result "failed", logged loudly, exit non-zero |
| the old version never returns after rollback | result "failed" (not "rolled_back"), exit non-zero |
Scenario: The result is always written
Given any marker and any outcome, including a panic in the helper
Then update-result.json holds outcome, kind, tag, from_version, started_at and finished_at, written atomically
And a "running" record exists from the moment the marker was read until the outcome replaces it
Scenario: Only the helper runs with privilege
Then the app has no code that execs systemctl, writes outside the data directory or reads the units
And the oneshot service and path unit contain no environment secrets
Scenario: Settings, owner, Restart buttons (route /settings)
Given the owner and can_apply true
Then with state "ready" the Restart button (power, primary) is enabled and opens the Install dialog
And with state "idle" (Up to date or Check failed) the Restart button (power, secondary) is enabled and opens the Plain restart dialog
And with state "downloading", "verifying" or "restarting" Restart is disabled or absent as the card draws it
And with can_apply false (Not prepared) or the admin view no Restart is rendered
And the slice 2 disabled Restart in Ready to install is now enabled and has a handler
And the SPA sends {"kind":"update"} from the Install dialog and {"kind":"restart"} from the Plain restart dialog, always
Scenario: Settings, Restart: confirm (Install dialog)
When the owner presses Restart in Ready to install
Then a dialog titled "Restart to finish the update?" shows "RenewCMS will install version 2.3.0-beta and restart. Your site will be unavailable for about 10 seconds. This page reloads on its own when the site is back. Save anything you're editing first."
And its buttons are "Restart later" and "Restart now", the confirm is neutral, not red
And focus moves to the first button, Escape and "Restart later" close it and focus returns to Restart
And no request is sent until "Restart now"
Scenario: Settings, Plain restart: confirm
When the owner presses Restart with no update waiting
Then a dialog titled "Restart the site?" shows "Your site will be unavailable for about 10 seconds. This page reloads on its own when the site is back. Save anything you're editing first."
And its buttons are "Cancel" and "Restart site", with the same focus and Escape behaviour
Scenario: Settings, Restart: request failed
Given the confirm button is pressed and POST /v1/system/update/restart answers 500 or never reaches the server
Then the dialog stays open (install or plain) with the error "Couldn't start the restart. Nothing was changed and your site is still running. Try again in a moment."
And the confirm button is enabled again, no overlay shows and nothing is stored in sessionStorage
Scenario: Settings, this tab remembers that it started the restart
Given POST /v1/system/update/restart answers 202 with started_at "S"
Then sessionStorage holds one entry with the kind and "S" (the server's started_at), and no other storage is written
And the overlay shows
Scenario: Settings, Restarting to install
Given POST /v1/system/update/restart answers 202 for an update
Then a full-page region with role "status" shows, titled "Installing version 2.3.0-beta" with
"Your site is restarting with the new version. This takes about 10 seconds. This page reloads on its own when the site is back." and a moving bar
And it is announced once as "Installing version 2.3.0-beta. Your site is restarting."
And the overlay survives failing requests and the Offline banner state is ignored while it shows
And it polls GET /healthz and GET /v1/system/update every second, tolerating network errors and non-200 answers
Scenario: Settings, Plain restart: restarting
Given POST /v1/system/update/restart answers 202 for a plain restart
Then the overlay shows "Restarting your site" / "This takes about 10 seconds. This page reloads on its own when the site is back."
And it polls the same way
Scenario: Settings, Restarting, taking longer
Given 60 seconds pass with no answer from /healthz or from GET /v1/system/update
Then the overlay shows "Still restarting" / "This is taking longer than usual. Keep this page open. It reloads on its own when the site is back, or you can reload it now." and a "Reload page" button
And the meta reads "Started at 09:51 · 1 minute ago" (clock-sensitive)
And "Reload page" reloads the page, the overlay stays until the site answers, and the polling continues
Scenario: Settings, the overlay ends when the site answers
Given the overlay shows and /healthz answers and GET /v1/system/update answers with a state other than "restarting"
and finished_at later than the stored started_at
Then the page reloads once
And a GET answering "restarting", a GET whose finished_at is null or not later than the stored started_at, a /healthz answer without a GET
answer, and a rejected GET all keep the overlay and do not reload
Scenario: Settings, Update done (the tab that started it)
Given the page reloaded, sessionStorage holds {kind "update", started_at "S"} and GET answers state "succeeded" with finished_at later than "S"
Then the entry is cleared, focus lands on the "Updates" heading (id="updates-h") with the ring shown
And a success toast "Update installed" / "RenewCMS is now on version 2.3.0-beta." is announced
And the Version card shows the new running version and the card reads "You're on version 2.3.0-beta" /
"The update is installed and your site is running again." / "Updated today at 09:52" with a "Read the release notes" link (arrow-up-right)
Scenario: Settings, Update failed, rolled back (the tab that started it)
Given the page reloaded, sessionStorage holds {kind "update", started_at "S"} and GET answers state "failed", error "rolled_back", finished_at later than "S", running "v2.2.0-beta"
Then the entry is cleared and focus lands on "Updates"
And an error toast (stays until dismissed) with icon circle-x "The update didn't install" / "Your site is back on v2.2.0-beta." shows
And the card shows icon triangle-alert (warning) "The update didn't install" /
"RenewCMS put the previous version back, so your site is running as before. Nothing was lost." /
"What to do next: try again in a few minutes. If it fails again, ask whoever manages your server to check the update." and a "Try again" button that sends POST /v1/system/update/download
And error "install" renders the same card and toast
Scenario: Settings, Plain restart: done (the tab that started it)
Given the page reloaded, sessionStorage holds {kind "restart", started_at "S"} and GET answers state "idle" with finished_at later than "S"
Then the entry is cleared, focus lands on "Updates" and a success toast "Site restarted" / "Your site is running again." is announced
And the card is the normal Up to date card
Scenario Outline: A later visit shows the card with no toast and no focus move
Given sessionStorage has no entry, or an entry whose started_at is not earlier than finished_at, and GET answers <result>
Then the card renders for that state, no toast shows and focus does not move to "Updates"
And nothing is written to sessionStorage
Examples:
| result |
| state "succeeded", finished_at set |
| state "failed", error "rolled_back" |
| state "failed", error "install" |
| state "idle", finished_at set (plain restart) |
Scenario: Settings, another owner's tab never takes the toast
Given owner B has /settings open, with no sessionStorage entry, while GET answers "restarting" and later "succeeded"
Then owner B's page shows the overlay while "restarting" and the card afterwards, with no toast and no focus move
And owner A's tab, which holds the entry, still gets the toast and the focus
And an admin sees the admin view and no overlay
Scenario: Settings, a stale sessionStorage entry
Given an entry left behind by a restart that never finished in this tab (the tab was closed and reopened by hand)
When the page loads and GET answers a finished_at that is not later than the entry's started_at, or null
Then no toast shows, focus does not move, the entry stays until a later finished_at consumes it, and a new restart overwrites it
Scenario: Settings, 409 on Restart
Given POST /v1/system/update/restart answers 409
Then the dialog closes, nothing is stored in sessionStorage and the card reloads
And when the reload shows downloading, verifying or restarting an info toast "An update is already running" / "Another owner started it. Progress shows here." shows and the card or overlay switches to that run
And when the reload shows can_apply false the card shows "Not prepared" and no toast
And when the reload shows a different "Ready to install" or "idle" (the kind did not match) the card shows that state and no toast
Scenario: Settings, 400 on Restart
Given POST /v1/system/update/restart answers 400
Then the dialog shows the "Couldn't start the restart" text and nothing is stored in sessionStorage
Scenario: Settings, 403 role changed on Restart
Given POST /v1/system/update/restart answers 403
Then the dialog closes, an error toast "Only the owner can do this" / "Ask the owner of this site to update RenewCMS." shows and the card reloads in the admin view
Scenario: Settings, 401 on Restart
Given POST /v1/system/update/restart answers 401
Then the global handler goes to /login?redirect=/settings&reason=expired and no local copy shows
Scenario: Home banner while restarting
Given state "restarting"
Then Home shows no update banner and does not poll
Scenario: The docs gain a "Browser updates" section
Then docs/deployment.md has "Browser updates" with the one-time command "sudo renewcms enable-browser-updates", what it installs
(two units, update-helper.json), how to undo it ("sudo renewcms disable-browser-updates"), and what is and is not supported
And it lists: Linux with systemd only; not Windows, macOS, Docker or other init systems; the previous binary is kept as <name>.previous
and a database backup in backups/; an update whose new version does not come up within 60 s is rolled back automatically
And it names the files update-restart-request.json, update-result.json, update-helper.json and update-running.json
And the "How to update" link of the Not prepared card points at that section
And the sentence "the site does not update itself" in the "Update checks" section is replaced
features/updates_restart_helper.qa.md
+187
View File
@@ -0,0 +1,187 @@
# QA: Updates part 3 (restart, helper, rollback)
## Automated Go (`task test`, package `test`, black-box, no live systemd, no real SMTP, no network)
Files: `test/update_restart_http_test.go` (HTTP), `test/update_restart_usecase_test.go` (request and status use cases),
`test/update_helper_test.go` (helper logic over fakes, including rollback and hardening), `test/update_helper_install_test.go`
(enable and disable over fakes), `test/update_helper_files_test.go` (real file adapters in `t.TempDir()`),
`test/update_dispatch_test.go` (built binary).
Fakes with unique names: `fakeRestartRequestStore`, `fakeResultStore`, `fakeRunningInfoStore` (scripted per poll: absent, corrupt, stale,
new), `fakeHelperFS`, `fakeServiceControl` (records restart calls with the clock instant; can fail), `fakeHealthChecker` (scripted per poll),
`fakeClock` (advances without sleeping), `fakeUnitWriter` (records unit contents, can fail the Nth write). Reuse `fakeJobStore`,
`fakeHelperDetector`, `fakeUpdateStore`, `mockUserRepo` and the throwaway ed25519 signer from slices 1 and 2. Never read the committed `release.pub`.
`fakeHelperFS`: an in-memory tree of files, directories and symlinks with owners and modes; `lstat`, no-follow open, create-exclusive, copy,
rename, remove and a fresh private temp directory are the only operations; every call is recorded in order with its path; an operation that
would traverse a symlink without the no-follow flag follows it (so a test fails if the code forgets to refuse); it can fail the Nth
call of an operation, and it has a hook `after(op, n, mutate)` that mutates the tree after a chosen call (used to swap the original
staged file after the copy step). Tests assert the paths the helper touched stay inside the data directory, the binary directory and
its own temp directory.
HTTP setup: `validator.InitValidator()`; `jwtauth.New("HS256", []byte("test-secret"), nil)`; a fresh `chi.NewRouter()` at `/v1/system`
mirroring `NewSystemRouter` (Verifier, Authenticator, RequireCurrentToken, RequireVerifiedUser; the restart route also RequireOwner);
cookies as in `test/stale_token_invalidation_http_test.go`. Marker, result and job files go in `t.TempDir()` through the real JSON adapters,
plus the fakes where noted. Helper time is driven by `fakeClock`: no `time.Sleep`, so the 60 s window runs instantly.
### Tests the coder must update (they exist from slices 1 and 2 and will break)
- Slice 1 tests that assert GET /v1/system/update has exactly 12 keys: now 13, with `finished_at` (null when no result file).
- Slice 2 tests and Vitest specs that assert the Restart button in "Ready to install" is disabled and has no handler, that no restart
endpoint, dialog or overlay exists, and that plain Restart is not rendered: replace them with the enabled behaviour below.
- Slice 2 "Pending states for slice 3" visual entries: they become real setups.
- Any slice 2 test that builds the status use case with a result store must accept the new `ResultStore` dependency.
### HTTP and use case (Go-testable)
1. Restart, update: ready job, can_apply on. POST with no body and POST `{"kind":"update"}` give 202 with state "restarting" and
`started_at` equal to the marker's `requested_at`; the marker has kind "update", the tag, requested_by equal to the owner id; the result file
was deleted first; no other file changed; GET as an admin also reads "restarting".
2. Plain restart: idle job. No body and `{"kind":"restart"}` give 202, marker kind "restart", empty tag. Also after a failed job and after a
rolled-back result.
3. Kind mismatch: `{"kind":"update"}` with no ready job (idle, failed) and `{"kind":"restart"}` with a ready job give 409; no marker, result and job untouched.
"Restart site never installs": owner A's body `{"kind":"restart"}` after the fake job store turned "ready" gives 409, no marker, staged files untouched.
4. Bad body: `{"kind":"upgrade"}`, `{"kind":""}`, `{"kind":7}`, truncated JSON, `not json` give 400 plain text, no marker. The struct uses
`validate:"omitempty,oneof=update restart"` and goes through `validator.Validate.Struct`; an empty body and `{}` are accepted.
5. Guards: admin 403 with `apperr.OwnerRequiredErrorMessage+"\n"`; no cookie 401; stale token 401; unverified 403; none writes a marker or deletes the result.
Order: an admin with a bad body gets 403, an owner with a bad body and can_apply off gets 400, can_apply off and a kind mismatch gives 409.
6. 409 table: can_apply off, downloading, verifying, marker pending, result "running": no second marker, existing files untouched.
7. Concurrency (`-race`): two simultaneous POSTs give one 202, one 409, one marker.
8. 500: a directory where the marker goes, and a read-only temp directory (`t.Skip` that one on Windows): 500, plain text without the path, no marker,
job record unchanged.
9. State derivation, one subtest per row of the feature table. Each row calls GET twice: the two bodies are byte-identical, `state`, `error` and
`finished_at` match, and a snapshot of every file in the data directory (names, bytes, mtimes) is unchanged by the GETs (GET has no side effects).
The 5-minute boundary uses `fakeClock`. Assert exactly the 12 slice 1 keys plus `finished_at`.
10. The result lives until the next job: a "rolled_back" result, then POST download and a job reaching "ready": the result is gone,
state "ready", error null, `finished_at` null. POST restart also deletes it before writing the marker.
11. After success: result "succeeded" for the running tag gives `available` false, `current` the new version, `finished_at` set.
12. Server startup file: with the real running-info adapter in `t.TempDir()` write twice; the file has `version`, `pid` and `started_at`, the second
write replaces the first, it is written by a temp file plus rename, and a write into a missing directory returns an error that the startup code logs
(use case or startup function returns it; it does not panic). The built binary (item 15) writes it before it answers `/healthz`.
13. `/healthz` is unchanged: body "ok", no `X-RenewCMS-Version` header, public.
14. A new download after "rolled_back" gives 202 and later a "ready" with error null.
15. Dispatcher: build with `go build -tags nofrontend -ldflags "-X main.version=v9.9.9" ./cmd/server` into `t.TempDir()`; with an empty environment
`--version` prints `v9.9.9`; an unknown subcommand exits non-zero with usage and does not listen; `apply-update` and `enable-browser-updates`
run without `.env` and create no `data/` (on a non-Linux machine the latter exits non-zero with the Linux/systemd message, which covers the Windows refusal).
### Helper logic over fakes (Go-testable, no systemd)
Fixture: fake FS with the binary `/opt/renewcms/renewcms` ("old"), staged `updates/v2.3.0-beta/` binary, `checksums.txt` and `checksums.txt.sig`
signed with a throwaway key injected through the verifier constructor, a marker, running version v2.2.0-beta, `update-running.json` with pid 100 and
started_at T0.
16. Plain restart: the marker is opened no-follow and deleted first, result "running" then "succeeded", one service restart, no write to the binary.
Success needs `/healthz` 200 AND a running file that is NEW.
17. Stale running info, one subtest per row: old pid and old started_at; target version but old pid and old started_at; absent; corrupt; old version with a new pid
(for an update). Health answers 200 throughout. The helper keeps polling and is not declared succeeded or rolled back until the file turns new or the
fake clock passes 60 s. Also: a file whose started_at is later than the restart instant counts as new even with the same pid.
18. Update happy path, asserting the ORDER of fake calls: no-follow read and delete of the marker, "running", fresh 0700 temp directory, no-follow copy of the
three staged files into it, signature check on the copy, SHA-256 of the copied binary, copy of the current binary to `.previous`, temp file in the
binary's directory written from the verified copy, re-hash of that temp file, atomic rename, mode 0755, record running info, restart, polls,
"succeeded", removal of the temp directory and `updates/<tag>/`. Final FS: binary equals the new bytes, `.previous` equals the old bytes.
Success is declared on the first matching poll, not at 60 s.
19. Re-verification, one subtest each: tampered binary, tampered checksums.txt, other-key signature, missing signature, no line for the asset, missing
binary. Each: binary unchanged, no `.previous`, zero restarts, result "failed", staged dir and temp dir removed, reason in the injected logger only.
20. Symlinks, one subtest each: marker; `updates`; `updates/<tag>`; the binary; checksums.txt; checksums.txt.sig; a link at the result path; a link at a
predictable temp file name. Each: the FS records no read, write, copy or removal through the link (the targets, placed outside the allowed
directories with sentinel bytes, are unchanged), binary untouched, no `.previous`, zero restarts, result "failed", the log names the link path.
The symlinked marker case: the link itself is unlinked and the target is intact.
21. TOCTOU: with the `after` hook, replace the original staged binary with other bytes immediately after the copy step; the installed bytes equal the
verified copy's bytes. Repeat with the swap after the signature check, after the hash check, and after the `.previous` copy. A swap of the temp file
in the binary's directory between write and rename is caught by the re-hash: result "failed", binary untouched.
22. Result and temp writes: create-exclusive and no-follow, then rename; a pre-planted symlink at the result path or a temp name leaves the target intact.
23. Hostile marker tags (traversal, traversal with valid prefix, empty, older version, malformed): result "failed", zero restarts, every touched path
under the allowed directories.
24. Rollback table: health never answers (60 s of fake clock, about 60 polls at 1 s), healthy but running file stays old, other version in the running file,
restart error. Each: binary restored to "old" through an atomic rename, second restart issued, polled until a NEW running file holds the old version,
result "rolled_back" with from_version and tag, temp directory and staged dir removed.
25. Swap failures: `.previous` copy fails (binary untouched, no restart, "failed"); atomic install fails (old binary and `.previous` intact, "failed");
restore fails ("failed", error returned, loud log); old version never returns after rollback ("failed", not "rolled_back").
26. Result always written: a panic in the fake service control still leaves outcome "failed" with `finished_at`; the "running" record exists before the
first service call; writes are atomic.
27. Timestamps come from `fakeClock`; finished is not before started.
28. Enable, over fake FS, unit writer and service control: refuses non-Linux, no systemd, not root, no unit and no flags, no data directory (exact
messages); on success writes both units containing the service, binary and data directory from the parsed unit, the `PathExists=` marker line and
the port flag (`--port` over `PORT` from the env file over 8080); the units never contain `JWT_SECRET` or any value from the env file (seed the
fixture env file with `JWT_SECRET=sentinel-secret` and search both units); flags override the unit; the status file is written LAST; running it
twice gives identical files and one unit pair; each failing step leaves no status file and removes the first unit.
29. Disable: removes units and the status file, keeps marker, result, staged files and backups; idempotent; a no-op where it was never enabled;
`can_apply` reads false afterwards through the real file detector.
30. Real adapters on `t.TempDir()`: the JSON marker, result, status and running-info stores round trip; the atomic write replaces an existing file.
The Linux-only no-follow adapter has a test file with `//go:build linux` (it runs on Linux CI machines and the user's WSL2, and is skipped on Windows).
31. Review items, not Go tests: the app (handlers, use cases, `api/`) execs no `systemctl` and writes only inside the data directory;
`internal/domain/update` imports only the stdlib; use cases import no `os/exec`, `net/http`, `gorm` or adapter; the handler imports no adapter;
the real filesystem adapter is the only code that calls `syscall.O_NOFOLLOW`; no secret in the repo; no new env var; `go vet -tags nofrontend`
and `gofmt` clean; no comments.
## Automated SPA (Vitest + Vue Test Utils, `task test:web`)
Mock `useApi.request` for `GET /v1/system/update`, `POST .../restart` and `POST .../download`; mock `fetch` for `GET /healthz`. Fake timers drive the
1 s polls and the 60 s switch. Stub `window.location.reload` and use a fresh `sessionStorage` per test. No test freezes the system date and none asserts a
relative date or "09:51". Sample data: running `v2.2.0-beta`, latest `v2.3.0-beta`, `started_at` and `finished_at` as plain strings.
One test per state:
1. Restart button: ready gives primary enabled; idle gives secondary enabled; downloading, verifying, restarting give disabled; can_apply false and admin give none.
2. Install dialog: exact title, text, buttons; focus on the first button; Escape and "Restart later" close it; focus returns to Restart; no request until
"Restart now"; the confirm is neutral; the request body is `{"kind":"update"}`.
3. Plain restart dialog: exact copy, "Cancel" / "Restart site", same behaviour; the request body is `{"kind":"restart"}`.
4. Restart request failed: 500 and `NetworkError`, in both dialogs: dialog stays, the exact error text, confirm enabled again, no overlay, nothing in sessionStorage. A 400 gives the same.
5. After 202, sessionStorage holds one entry with the kind and the response's `started_at`; no localStorage write.
6. Restarting to install: overlay `role="status"`, title and text, announced once; stays mounted when `fetch` rejects; the offline banner state is ignored; polls
/healthz and GET every second.
7. Plain restart: restarting: "Restarting your site" copy.
8. Taking longer: at 60 s "Still restarting", the text, "Reload page" present; pressing it calls reload; the overlay stays.
9. Overlay end: reload once when /healthz is ok and GET gives a non-"restarting" state with `finished_at` later than the stored `started_at`; no reload on
"restarting", on `finished_at` null, on `finished_at` not later, on a rejected GET, or without a GET answer; reload is not called twice.
10. Update done (entry present, state "succeeded", later `finished_at`): entry cleared, focus on `#updates-h`, success toast "Update installed" / "RenewCMS is now on version 2.3.0-beta.", card text and the "Read the release notes" link.
11. Rolled back (error "rolled_back" and "install"): entry cleared, focus on `#updates-h`, sticky error toast, card copy, "Try again" posts download.
12. Plain restart done (state "idle", later `finished_at`, kind "restart"): toast "Site restarted" / "Your site is running again.", focus, Up to date card, entry cleared.
13. No entry, or an entry not earlier than `finished_at`: for each of succeeded, rolled_back, install and plain-restart-idle results the card renders with no toast, no
focus move and no sessionStorage write.
14. Another owner's tab: no entry, GET "restarting" then "succeeded": overlay then card, no toast, no focus move. An owner tab with an entry still gets the toast. An admin sees the
admin view, no overlay and no poll.
15. Stale entry: `finished_at` null or earlier than the entry's `started_at` gives no toast and keeps the entry; a new restart overwrites it.
16. 409: reload downloading gives the info toast and progress; reload restarting gives the toast and overlay; reload can_apply false gives Not prepared and no toast; reload "ready"
or "idle" after a kind mismatch gives that card, no toast, nothing in sessionStorage.
17. 403: error toast and the admin view; 401 shows no local copy (the global handler is mocked).
18. Home: no banner or poll while "restarting".
19. Regression: slice 2's disabled-Restart assertions are replaced; Not prepared and the admin view still have no Restart.
## Visual (`task visual:check -- settings`; desktop and mobile, light and dark; every capture within 10 %)
`web/visual/states.ts` setups are added later by the coder, with the board's sample data (v2.2.0-beta, v2.3.0-beta). Exact values come from
`docs/design/source/AppFrame.dc.html` and the "Settings" group of the Screens board; describe layout as drawn (open the frame markup for the dialog, the overlay card
and its 440 px width before judging).
- [ ] Restart: confirm (install dialog)
- [ ] Plain restart: confirm
- [ ] Restart: request failed
- [ ] Restarting to install
- [ ] Plain restart: restarting
- [ ] Update failed, rolled back (the toast only if the frame draws it)
- [ ] `skip: 'clock-sensitive'`: Update done and Plain restart: done (meta "Updated today at 09:52"), Restarting, taking longer (meta "Started at 09:51 · 1 minute ago"); their copy is covered by Vitest
- [ ] Slice 2 pending states are now real: re-run the other Settings states and confirm Ready to install with an enabled Restart is within budget
- [ ] If a capture exceeds 10 %, stop and report; do not widen the budget or add an exception without the user's approval
- [ ] Not covered by screenshots: keyboard and focus order in both dialogs, the ring on `#updates-h` after the result states, the one-time overlay announcement, the motion of the bar, the Offline banner being ignored
## Manual only (real systemd Linux: WSL2 with systemd enabled, or a VPS): CANNOT be verified automatically
The user will run these. The helper's decision logic, ordering, symlink refusal, TOCTOU defence and rollback are unit-tested over fakes (items 16 to 27), but none of the following is covered:
- [ ] On Windows or macOS `renewcms enable-browser-updates` refuses with the clear message.
- [ ] On a VPS following docs/deployment.md (service user `renewcms`, `ProtectSystem=strict`, only `/var/lib/renewcms` writable): `sudo renewcms enable-browser-updates` reads the real unit, writes
`renewcms-update.path` and `renewcms-update.service`, enables the path unit (`systemctl status` active) and writes `update-helper.json`; a second run changes nothing.
- [ ] The Settings page shows the Update button (can_apply true) after a reload.
- [ ] The path unit fires when the sandboxed app writes the marker, and the app (as `renewcms`) can write the marker and cannot write the binary, the units or anything outside the data directory.
- [ ] The server writes `update-running.json` at startup (`cat` it: version, pid, started_at) and a restart replaces it.
- [ ] Real update from a real signed release (real `release.pub` committed, `task release` signing): Update, Ready, Restart, overlay, reload on the new version, toast on the tab that started it,
`.previous` next to the binary, `renewcms --version` equals the new tag, `journalctl -u renewcms-update` shows the helper log.
- [ ] Real rollback: stage a signed release whose binary prints the right `--version` but crashes at boot; the old binary is restored within about 60 s, the card reads "The update didn't install", the toast stays.
- [ ] Plain restart: overlay, about 10 s of downtime, reload with "Site restarted".
- [ ] The real no-follow adapter on Linux: as the service user, replace `updates/<tag>` with a symlink to `/etc`, replace the staged binary with a symlink, replace the marker with a symlink, and swap the staged file during
an update (a loop that rewrites it); the helper refuses or installs only verified bytes, and nothing outside the data directory is read or changed.
- [ ] Planted symlink at `update-result.json` pointing at a root-only file: the helper does not write through it.
- [ ] Binary directory ownership, SELinux and AppArmor do not block the atomic rename, and the temp file is on the same filesystem as the binary; the helper's private temp directory is root-owned 0700 and is removed.
- [ ] A hand-written marker with another tag, as the service user: refused, binary untouched.
- [ ] `sudo renewcms disable-browser-updates` removes the units and status file; the card returns to "Not prepared"; nothing else is deleted.
- [ ] A reverse proxy (nginx or Caddy) returns 502 during the restart and the overlay survives it; `/healthz` is not cached.
- [ ] Two owners in two browsers during a restart: both show the overlay; only the tab that started it gets the toast and focus.
- [ ] Embedded SPA build (no `-tags nofrontend`) serves `/settings` with the new dialogs and overlay.
- [ ] Journal and files contain no secret, and technical reasons are only in the journal.
## Final note
Not verifiable automatically: the whole privileged path on a real systemd Linux machine (generated units, path-unit trigger from the sandboxed app, real service restart, atomic swap on a real filesystem, real rollback, O_NOFOLLOW behaviour, permissions, SELinux or AppArmor, reverse-proxy behaviour). It needs the manual test on WSL2 with systemd or a VPS, which the user will do.