Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(wordpress): WP-aware alerting — site down/up → channels + events (#27)

Juan Deniseca7cd276700
diff --git a/backend/app/services/environment_health_service.py b/backend/app/services/environment_health_service.py
index 8fcdc6d4..e3e3456b 100644
--- a/backend/app/services/environment_health_service.py
+++ b/backend/app/services/environment_health_service.py
@@ -85,12 +85,14 @@ class EnvironmentHealthService:
else:
overall = 'unknown'
- # Update site record
+ # Update site record (capture prior status first to detect transitions)
+ previous_status = site.health_status
site.health_status = overall
site.last_health_check = datetime.utcnow()
db.session.commit()
- # Emit event for workflow triggers on unhealthy status
+ # Emit event for workflow triggers on every failing poll (back-compat for
+ # existing event-trigger workflows keyed on 'health_check_failed').
if overall in ('unhealthy', 'degraded'):
try:
from app.services.workflow_engine import WorkflowEventBus
@@ -102,6 +104,11 @@ class EnvironmentHealthService:
except Exception:
pass
+ # Alert the configured channels + fan out a wordpress.site_down/up catalog
+ # event ONLY on a health-state transition, so an autonomous poller does not
+ # spam. Best-effort — never breaks the health check.
+ cls._notify_health_transition(site, previous_status, overall, checks)
+
return {
'success': True,
'site_id': site_id,
@@ -110,6 +117,79 @@ class EnvironmentHealthService:
'checked_at': datetime.utcnow().isoformat(),
}
+ # Health states treated as an outage for alerting purposes.
+ _DOWN_STATES = ('unhealthy', 'degraded')
+
+ @classmethod
+ def _notify_health_transition(cls, site, previous, overall, checks):
+ """On a health-state TRANSITION (edge-triggered), alert the configured
+ notification channels and fan out a wordpress.site_down/up catalog event.
+ Edge-triggering (not every failing poll) IS the dedup: a continuously
+ down site fires a single down alert, and a single up alert on recovery.
+ Best-effort — never raises into check_health.
+ """
+ was_down = previous in cls._DOWN_STATES
+ is_down = overall in cls._DOWN_STATES
+ if is_down and not was_down:
+ cls._dispatch_health_alert(site, overall, checks, recovered=False)
+ elif overall == 'healthy' and was_down:
+ cls._dispatch_health_alert(site, overall, checks, recovered=True)
+
+ @classmethod
+ def _dispatch_health_alert(cls, site, overall, checks, recovered):
+ """Send a one-shot health alert to notification channels (off-thread,
+ since send_all does blocking HTTP/SMTP) and emit the matching catalog
+ event for outbound webhook subscribers. Down alerts use critical/warning
+ (delivered by default channels); recovery uses 'info' (delivered only to
+ channels that opt into 'info')."""
+ site_name = site.application.name if site.application else f'site {site.id}'
+ if recovered:
+ event_type = 'wordpress.site_up'
+ severity = 'info'
+ message = f'WordPress site "{site_name}" recovered (status: {overall}).'
+ else:
+ event_type = 'wordpress.site_down'
+ severity = 'critical' if overall == 'unhealthy' else 'warning'
+ failed = [name for name, c in checks.items() if c.get('status') == 'unhealthy']
+ detail = (', '.join(failed) + ' check failed') if failed else overall
+ message = f'WordPress site "{site_name}" is down ({detail}).'
+
+ payload = {
+ 'event': event_type,
+ 'site_id': site.id,
+ 'site_name': site_name,
+ 'overall_status': overall,
+ 'checks': checks,
+ 'timestamp': datetime.utcnow().isoformat(),
+ }
+
+ # Outbound webhook subscribers (fast: queues deliveries, threads the HTTP).
+ try:
+ from app.services.event_service import EventService
+ EventService.emit(event_type, payload)
+ except Exception:
+ pass
+
+ # Notification channels — off-thread because send_all does blocking
+ # HTTP/SMTP per channel and must not stall the health check.
+ def _send():
+ try:
+ from app.services.notification_service import NotificationService
+ NotificationService.send_all([{
+ 'type': event_type,
+ 'severity': severity,
+ 'message': message,
+ 'value': overall,
+ 'threshold': 'healthy',
+ }])
+ except Exception:
+ pass
+ try:
+ import threading
+ threading.Thread(target=_send, daemon=True, name='wp-health-alert').start()
+ except Exception:
+ pass
+
@classmethod
def check_all_project_health(cls, production_site_id: int) -> Dict:
"""Check health for all environments in a project.
diff --git a/backend/app/services/event_service.py b/backend/app/services/event_service.py
index 9acf7dee..bdf3859d 100644
--- a/backend/app/services/event_service.py
+++ b/backend/app/services/event_service.py
@@ -53,6 +53,8 @@ EVENT_CATALOG = [
{'type': 'domain.deleted', 'category': 'Domains', 'description': 'A domain was deleted'},
{'type': 'api_key.created', 'category': 'API', 'description': 'An API key was created'},
{'type': 'api_key.revoked', 'category': 'API', 'description': 'An API key was revoked'},
+ {'type': 'wordpress.site_down', 'category': 'WordPress', 'description': 'A WordPress site failed its health check'},
+ {'type': 'wordpress.site_up', 'category': 'WordPress', 'description': 'A WordPress site recovered after a failed health check'},
]
diff --git a/docs/WORDPRESS_ROADMAP.md b/docs/WORDPRESS_ROADMAP.md
index 363468e8..08809d52 100644
--- a/docs/WORDPRESS_ROADMAP.md
+++ b/docs/WORDPRESS_ROADMAP.md
@@ -241,11 +241,12 @@ The headline value of a managed platform, and the most net-new — but it leans
- **Reuse:** `EnvironmentHealthService`, `status_page_service`, `uptime_service`.
- **Done when:** A managed site appears on a status page with a real uptime % and auto-incidents.
-### #27 — WP-aware alerting `[M]` 🟡
+### #27 — WP-aware alerting `[M]` 🟡 — ✅ Done (site down/recovered → channels + catalog event, edge-triggered; error-spike deferred to #25)
- **Today:** Multi-channel `notification_service` (email/Slack/Discord/Telegram/webhook) exists; the `WorkflowEventBus` `health_check_failed` hook exists; neither knows about WordPress sites.
- **Do:** Add WP alert rules (site down / health failed / error spike) routed through `notification_service` via the event bus.
- **Reuse:** `notification_service`, `WorkflowEventBus`.
- **Done when:** A site outage or error spike pings the configured channel.
+- **Landed:** `EnvironmentHealthService.check_health` now captures the prior `health_status` and, **on a state TRANSITION only** (edge-triggered — a continuously-down site fires a single down alert, recovery fires a single up alert, so an autonomous poller never spams), routes a WP health alert through three sinks: (1) the existing `WorkflowEventBus.emit('health_check_failed')` hook is **preserved** (still fires every failing poll for back-compat with event-trigger workflows); (2) **NEW** — `NotificationService.send_all` dispatches to every enabled channel (Discord/Slack/Telegram/email/generic), `unhealthy→critical` / `degraded→warning` (delivered by default channels) and recovery→`info` (delivered only to channels that opt into `info`); fired **off-thread** because `send_all` does blocking HTTP/SMTP and must not stall the health check; (3) **NEW** — `wordpress.site_down` / `wordpress.site_up` added to `EVENT_CATALOG` and emitted via `EventService`, so user webhook subscriptions (incl. a `wordpress.*` wildcard) deliver with HMAC + retry, and the events auto-appear in the event-subscription UI (`GET …/events` returns the catalog). **No schema/migration and no frontend** — channel delivery is governed by the existing Notifications settings; this also seeds **#35**'s WP lifecycle-event registry. *(Deferred: the "error spike" rule needs the per-site error metrics that **#25** will provide — revisit once #25 lands. Alerts are most useful once **#26**'s server-side scheduler runs `check_health` autonomously; today health only runs while the #6 card is open.)*
---