Skip to content

Fix repeating FlowView upgrade notice; whitelist config.php; run upgrade via __DIR__ - #309

Merged
TheWitness merged 4 commits into
developfrom
fix/config-php-manifest
Nov 13, 2026
Merged

TheWitness merged 4 commits into
developfrom
fix/config-php-manifest

Conversation

@TheWitness

Copy link
Copy Markdown
Member

Description

Two small, related FlowView install/upgrade fixes, plus the once-only background upgrade handling modelled on the recent plugin_mactrack work.

config.php manifest + install docs

  • config.php is created by the customer by copying config.php.dist to complete a normal install, so it is never shipped in git. It is now listed under whitelist in manifest.json, so flowview_prune_files() never touches it on upgrade and tests/bin/validate-manifest.php never requires it on disk.
  • .github/copilot-instructions.md now documents that both config.php.dist (shipped template) and the copied config.php (customer-owned) are expected on a normal install.

flowview_upgrade.php runnable from any directory

  • Changed chdir('../../') to chdir(__DIR__ . '/../../') so the CLI works when invoked from outside the Cacti root (e.g. php plugins/flowview/flowview_upgrade.php), matching flowview_process.php and run_schedule.php.

Launch the background upgrade and its notice only once

  • plugin_flowview_check_upgrade() relaunched the CLI and re-raised the "upgrading in the background" notice on every visit to a guarded page whenever the recorded plugin_config version lagged the code. A failed background upgrade never records the version, so the notice returned on every Plugins page load.
  • New flowview_launch_background_upgrade() starts the CLI only when no non-stale flowview/upgrade process is registered, and raises the notice a single time (gated by the flowview_db_upgrade_notified flag). The CLI prunes tombstoned files, clears the flag, and records the new version when it finishes; a run that crashed past its timeout is relaunched. Modelled on Cacti/plugin_mactrack#423.

Related Issue

Fixes #308

Motivation and Context

The FlowView upgrade notice repeated on every Plugins page visit when the stored version differed from INFO (e.g. after a failed background upgrade). It also required config.php to exist, yet nothing in the manifest accounted for that customer file, and flowview_upgrade.php could only be run from inside its own directory.

How Has This Been Tested?

Ran the plugin's Pest suite from a Cacti checkout with the plugin as a real directory at plugins/flowview:

  • include/vendor/bin/pest --configuration plugins/flowview/phpunit.xml — 404 passed (1960 assertions), including the new tests/Unit/FlowviewBackgroundUpgradeTest.php covering launch-once, no-relaunch-while-running, stale-run relaunch, --force, and the missing-processes-table guard.
  • php tests/bin/validate-manifest.php — passes (manifest.json 'expected' matches the plugin tree).
  • php -l on all changed PHP files — clean.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

  • My code follows the code style of this project.
  • My change requires a change to the documentation.
  • I have updated the documentation repository accordingly.

TheWitness and others added 2 commits November 13, 2026 08:47
config.php is created by the customer by copying config.php.dist to complete a normal install, so it is not shipped in git. Add it to the manifest whitelist so flowview_prune_files() never touches it on upgrade and the manifest validator never requires it on disk. Document in the copilot instructions that both config.php.dist and the copied config.php are expected on a normal install.

Also change flowview_upgrade.php to chdir(__DIR__ . /../../) so it can be run from outside the Cacti root (e.g. php plugins/flowview/flowview_upgrade.php), matching flowview_process.php and run_schedule.php.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
plugin_flowview_check_upgrade() relaunched flowview_upgrade.php and raised the
in-the-background upgrade notice on every visit to a guarded page
(plugins.php/flowview.php/index.php) whenever the recorded plugin_config
version still lagged the code. When a background upgrade failed, the version
was never recorded, so the notice came back on every Plugins page load.

Model the launcher on plugin_mactrack: a new flowview_launch_background_upgrade()
starts the CLI only when no non-stale flowview/upgrade process is registered
(flowview_background_upgrade_running() reads the processes table that the CLI
registers via register_process_start). It raises the notice a single time,
gated by the flowview_db_upgrade_notified flag. The CLI prunes tombstoned
files, clears that flag, and records the new version when it finishes, so the
hook stops relaunching it; a run that crashed past its timeout is treated as
not running and relaunched.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 13, 2026 13:58

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The upgrade flow can lose the next operator notice through a notification-flag race and block automatic recovery from a dead worker for up to 24 hours.

2 open issues
What changed in this PR

This PR addresses the repeating FlowView upgrade notice reported in #308 and improves install and upgrade handling within Cacti.

Changes:

  • Adds process-registration checks and a notification flag to limit background upgrade launches and notices, with unit coverage.
  • Makes the upgrade CLI independent of the working directory and moves file pruning into it.
  • Whitelists customer-owned config.php and documents its installation requirements.
File Description
tests/​Unit/​FlowviewBackgroundUpgradeTest.php Adds coverage for launch, notification, timeout, and force behavior.
tests/​bootstrap-unit.php Adds configurable table-existence stubs for unit tests.
setup.php Adds background upgrade launch and process-status helpers.
manifest.json Whitelists customer-owned config.php.
flowview_upgrade.php Uses a script-relative working directory, prunes files, and resets the notice flag.
CHANGELOG.md Records the upgrade and configuration fixes.
.github/​copilot-instructions.md Documents configuration ownership and manifest handling.

Review effort: Balanced

Comment thread setup.php Resolved
Comment thread setup.php Resolved
TheWitness and others added 2 commits November 13, 2026 09:22
Some plugins use config_local.php to point a data collector at a local
database instance. Like config.php it is customer-created and not shipped, so
whitelist it too, keeping upgrade pruning from touching it and the manifest
validator from requiring it on disk.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Two fixes from the PR review of the once-only background upgrade launcher:

- Persist the flowview_db_upgrade_notified flag before spawning the CLI. A
  fast-finishing child clears the flag on completion; setting it first keeps
  the web request from overwriting that write with 'on', which would have left
  the next upgrade without its operator notice.

- Probe the registered worker's PID in flowview_background_upgrade_running()
  so a crashed upgrade is recovered immediately instead of blocking relaunch
  for the rest of its 24-hour timeout. Only ESRCH proves the process exited;
  EPERM and an unavailable posix probe are treated as still running. Modeled
  on Cacti/plugin_mactrack#425.

Adds a unit test covering recovery when the registered worker PID has exited.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@sonarqubecloud

Copy link
Copy Markdown

@TheWitness
TheWitness merged commit 37c4b5b into develop Nov 13, 2026
7 checks passed
@TheWitness
TheWitness deleted the fix/config-php-manifest branch November 13, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

flowview keep poping up with Tables are being upgraded

3 participants