TheWitness
f1eef20a25
- tests/bootstrap-unit.php: stop stubbing validateRequestVars() globally; monitor_controller.php declares it unconditionally, so the stub caused a Cannot redeclare fatal once a test loaded plugin source via loadPluginSource()/monitor_test_load(). - .github/workflows/plugin-ci-workflow.yml: add coverage: pcov to the setup-php step so the Pest --coverage-clover report has a driver to run against. - Document the PHP 8.2 floor (matrix is already 8.2-8.4) in copilot-instructions.md, the php-developer agent, and the hexagonal-monitor ADR, replacing stale PHP 8.1 references now that PHP 8.1 is no longer tested. - Verified apache2/libapache2-mod-php do not need to be re-added to the Install System Dependencies step: apache2 ships preinstalled on the ubuntu-latest runner image and shivammathur/setup-php configures the matching Apache PHP module for the selected matrix version.
3.1 KiB
ADR-0001: Migrate Monitor toward a hexagonal architecture
Status: Proposed
Context
Monitor currently combines Cacti hook registration, HTTP request handling,
session state, dashboard rendering, raw SQL construction, poller execution,
notification policy, email delivery, and persistence in a small number of
procedural files. It also stores monitoring configuration in Cacti's shared
host table and directly reads optional plugin tables such as Threshold and
Syslog.
This makes it difficult to test monitoring behavior independently, evolve state transitions safely, prevent duplicate background work, or maintain a stable extension boundary while keeping compatibility with Cacti 1.2.
Decision
Monitor will be migrated incrementally to a hexagonal architecture while preserving the current Cacti 1.2 hooks, UI routes, device fields, and notification behavior during the compatibility period.
The target contains the following responsibilities:
- Domain: monitoring profiles, observations, incidents, acknowledgements, notification attempts, and saved dashboard definitions.
- Application services: evaluate a monitoring cycle, reconcile uptime and reboots, dispatch notifications, query a dashboard, and acknowledge or mute an incident.
- Ports: device-status source, threshold-status source, monitor repository, dashboard repository, notification gateway, authorization policy, clock, and worker lease.
- Adapters: Cacti host/Threshold/Syslog APIs, MySQL, Cacti mailer, Cacti poller hook, and the existing Monitor web UI.
Domain code must not access request variables, sessions, globals, SQL, the filesystem, or Cacti helper functions. New code targets PHP 8.2, the baseline this repository's CI tests against.
State and delivery rules
Availability, latency breach, Threshold trigger, acknowledgement, and user UI mute state are separate concepts. A monitoring incident has an explicit lifecycle; a notification attempt and confirmed delivery are distinct records. Only a lease-owning worker may evaluate a cycle or dispatch its notifications.
Migration plan
- Add pure value objects and policy functions with characterization tests.
- Put Cacti host, Threshold, notification, and authorization access behind adapters used by new application services.
- Introduce plugin-owned profile, incident, and notification-attempt storage;
mirror existing
host.monitor_*fields through a compatibility adapter. - Move the poller script to a lease-aware evaluation and delivery workflow.
- Move saved dashboard URL state to a versioned dashboard definition, then deprecate legacy direct SQL and request/session coupling.
Consequences
- Existing hooks and database fields remain supported during migration rather than requiring a flag-day rewrite.
- New behavior gains unit, integration, and end-to-end test seams.
- Cacti and optional plugin dependencies become replaceable adapters rather than hidden global dependencies.
- The migration requires explicit schema/version compatibility and a published deprecation timeline before legacy paths are removed.