Add experimental server alerts and webhook notifications

Server-side alerting for Docker/container/stack health with Discord,
Slack, Teams, ntfy, Gotify, Telegram, and generic webhooks. Settings
tab, client cache, and backup/restore coverage; marked experimental.

server/core/audit.js

@@ -24,6 +24,14 @@ const AUDIT_METHODS = new Set([
   'recreateContainer',
   'upsertSchedule',
   'deleteSchedule',
+  'updateAlertsConfig',
+  'exportAlertsConfig',
+  'upsertAlertChannel',
+  'deleteAlertChannel',
+  'upsertAlertRule',
+  'deleteAlertRule',
+  'testAlertChannel',
+  'fireManualAlert',
   'removeImage',
   'removeStack',
   'deployStack',

server/handlers/alerts.js

@@ -0,0 +1,110 @@
+/**
+ * RPC handlers for the server alerting / webhook system.
+ */
+import * as validation from '../utils/validation.js'
+import {
+  getAlertsConfig,
+  getAlertsConfigRaw,
+  updateAlertsConfig,
+  upsertAlertChannel,
+  deleteAlertChannel,
+  upsertAlertRule,
+  deleteAlertRule,
+  listAlertHistory,
+  getAlertsStatus,
+  testAlertChannel,
+  fireManualAlert,
+  getAlertsFilePath,
+  ALERT_CHANNEL_TYPES,
+  ALERT_RULE_KINDS,
+  ALERT_SEVERITIES,
+} from '../services/alerts.js'
+
+export function registerAlertHandlers(session) {
+  session.respond('getAlertsConfig', async () => {
+    return {
+      success: true,
+      config: getAlertsConfig(),
+      meta: {
+        channelTypes: ALERT_CHANNEL_TYPES,
+        ruleKinds: ALERT_RULE_KINDS,
+        severities: ALERT_SEVERITIES,
+      },
+    }
+  })
+
+  /**
+   * Admin-only full export including webhook secrets — for backup / client cache.
+   */
+  session.respond('exportAlertsConfig', async () => {
+    return {
+      success: true,
+      config: getAlertsConfigRaw(),
+      path: getAlertsFilePath(),
+      exportedAt: new Date().toISOString(),
+    }
+  })
+
+  session.respond('getAlertsStatus', async () => {
+    return { success: true, status: getAlertsStatus() }
+  })
+
+  session.respond('listAlertHistory', async (args = {}) => {
+    const limit = Math.max(1, Math.min(200, Number(args.limit) || 50))
+    return { success: true, history: listAlertHistory(limit) }
+  })
+
+  session.respond('updateAlertsConfig', async (args = {}) => {
+    const replace = Boolean(args.replace)
+    const partial = args.config && typeof args.config === 'object' ? args.config : args
+    const config = updateAlertsConfig(partial, { replace })
+    return { success: true, config }
+  })
+
+  session.respond('upsertAlertChannel', async (args = {}) => {
+    const channel = upsertAlertChannel(args.channel || args)
+    return { success: true, channel }
+  })
+
+  session.respond('deleteAlertChannel', async (args = {}) => {
+    const id = validation.sanitizeString(args.id || '', 64)
+    if (!id) throw Object.assign(new Error('id required'), { code: 'INVALID_ARGS' })
+    const ok = deleteAlertChannel(id)
+    if (!ok) throw Object.assign(new Error('Channel not found'), { code: 'NOT_FOUND' })
+    return { success: true, id, deleted: true }
+  })
+
+  session.respond('upsertAlertRule', async (args = {}) => {
+    const rule = upsertAlertRule(args.rule || args)
+    return { success: true, rule }
+  })
+
+  session.respond('deleteAlertRule', async (args = {}) => {
+    const id = validation.sanitizeString(args.id || '', 64)
+    if (!id) throw Object.assign(new Error('id required'), { code: 'INVALID_ARGS' })
+    const ok = deleteAlertRule(id)
+    if (!ok) throw Object.assign(new Error('Rule not found'), { code: 'NOT_FOUND' })
+    return { success: true, id, deleted: true }
+  })
+
+  session.respond('testAlertChannel', async (args = {}) => {
+    const id = validation.sanitizeString(args.id || args.channelId || '', 64)
+    if (!id) throw Object.assign(new Error('id required'), { code: 'INVALID_ARGS' })
+    const result = await testAlertChannel(id)
+    return { success: true, ...result }
+  })
+
+  session.respond('fireManualAlert', async (args = {}) => {
+    const title = validation.sanitizeString(args.title || '', 200)
+    if (!title) throw Object.assign(new Error('title required'), { code: 'INVALID_ARGS' })
+    const record = await fireManualAlert({
+      title,
+      message: validation.sanitizeString(args.message || '', 2000),
+      severity: args.severity,
+      details: args.details,
+    })
+    return { success: true, record }
+  })
+}
+
+export default { registerAlertHandlers }

server/rpc/register.js

@@ -20,6 +20,7 @@ import { registerRegistryHandlers } from '../handlers/registry.js'
 import { registerBinaryStreamHandlers } from './binary-stream.js'
 import { registerSuggestionHandlers } from '../handlers/suggestions.js'
 import { registerTunnelHandlers } from '../handlers/tunnels.js'
+import { registerAlertHandlers } from '../handlers/alerts.js'
 
 /**
  * @param {import('./session.js').PeerSession} session
@@ -27,6 +28,7 @@ import { registerTunnelHandlers } from '../handlers/tunnels.js'
 export function registerAllHandlers(session) {
   registerHandshake(session)
   registerSystemHandlers(session)
+  registerAlertHandlers(session)
   registerContainerHandlers(session)
   registerImageHandlers(session)
   registerNetworkHandlers(session)

server/server.js

@@ -25,6 +25,7 @@ import {
   restoreTunnelsFromDisk,
 } from './services/holesail-tunnels.js'
 import { restoreSchedules } from './services/schedules.js'
+import { startAlerts, stopAlerts } from './services/alerts.js'
 import { docker } from './services/docker.js'
 import logger from './utils/logger.js'
 import { isSwarmEnabled } from './handlers/swarm.js'
@@ -157,6 +158,11 @@ if (!dockerStatus.ok) {
 
 startDockerEventStream()
 startStatsBroadcast()
+try {
+  startAlerts()
+} catch (err) {
+  log.warn('Alerts engine failed to start', { error: err.message })
+}
 
 if (isHolesailEnabled()) {
   restoreTunnelsFromDisk()
@@ -186,6 +192,11 @@ async function shutdown(signal = 'shutdown') {
 
   stopStatsBroadcast()
   stopDockerEventStream()
+  try {
+    stopAlerts()
+  } catch {
+    // ignore
+  }
 
   try {
     await closeAllTunnels()

server/services/events.js

@@ -6,6 +6,7 @@ import { docker, extractVolumesList } from './docker.js'
 import { peers } from '../core/peer-registry.js'
 import { Pushes } from '../../shared/protocol.js'
 import { broadcastContainers } from '../handlers/containers.js'
+import { onDockerEvent } from './alerts.js'
 import logger from '../utils/logger.js'
 
 let dockerEventStream = null
@@ -93,6 +94,13 @@ async function openEventStream() {
             data: event,
           })
 
+          // Server-side alerting (webhooks) — independent of connected clients
+          try {
+            onDockerEvent(event)
+          } catch (e) {
+            logger.debug('alerts onDockerEvent error', { error: e?.message })
+          }
+
           // Do not rebroadcast the full list on every exec_*/health_status event —
           // that thrashed clients (rows flicker / disappear on each refresh).
           if (event.Type === 'container') {