feat(alerts): give plugins an alerts surface

Each plugin gets its own shallow copy of the server app, so a surface a
plugin publishes on its own copy is invisible to the others. The
subsystem lives in core for that reason, and app.alerts delegates to the
one manager, attributing each raise and clear to the plugin.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UmEL91uGc7sNotczyGihFx

Author: mairas

packages/server-api/src/alertsapi.ts

@@ -0,0 +1,123 @@
+import type {
+  Alert,
+  AlertPriority,
+  HistoryEntry,
+  RaiseAlertRequest,
+  TransitionResult
+} from './typebox/alerts-schemas'
+import type { Context, Path } from '.'
+
+export type {
+  Alert,
+  AlertPriority,
+  AlertState,
+  RaiseAlertRequest,
+  TransitionResult,
+  HistoryEntry as AlertHistoryEntry
+} from './typebox/alerts-schemas'
+
+/**
+ * Query against the alert audit trail.
+ *
+ * @category Alerts API
+ */
+export interface AlertHistoryQuery {
+  /** Earliest entry to return, as an ISO 8601 timestamp */
+  from?: string
+  /** Latest entry to return, as an ISO 8601 timestamp */
+  to?: string
+  /** Only entries belonging to this alert */
+  alertId?: string
+  /** Only entries about this alert path */
+  path?: Path
+  /** Only entries about alerts in this context */
+  context?: Context
+  /** Only these kinds of event */
+  eventType?: HistoryEntry['eventType'] | HistoryEntry['eventType'][]
+  /** Maximum entries to return */
+  limit?: number
+  /** Entries to skip */
+  offset?: number
+}
+
+/**
+ * Which alerts to list.
+ *
+ * @category Alerts API
+ */
+export interface AlertFilter {
+  state?: Alert['state'] | Alert['state'][]
+  priority?: AlertPriority | AlertPriority[]
+  group?: string
+  stale?: boolean
+}
+
+/**
+ * Plugin interface to the alerts subsystem.
+ *
+ * The server owns alert lifecycle: a plugin describes a condition and the
+ * server decides what state the alert is in. Raising an alert on a path that
+ * already has one updates that alert rather than creating a second.
+ *
+ * @category Alerts API
+ */
+export interface AlertsApi {
+  /**
+   * Raise an alert, or update the alert already on that path.
+   *
+   * @example
+   * ```typescript
+   * await app.alerts.raise({
+   *   path: 'propulsion.port.oilPressureLow',
+   *   priority: 'alarm',
+   *   message: 'Oil pressure low'
+   * })
+   * ```
+   */
+  raise(request: RaiseAlertRequest): Promise<Alert>
+
+  /**
+   * Acknowledge an alert.
+   *
+   * The audit trail records the plugin as the actor; a plugin cannot
+   * acknowledge on behalf of a name it chooses.
+   */
+  acknowledge(alertId: string): Promise<TransitionResult>
+
+  /**
+   * Silence an alert for `durationSeconds`, or for the configured maximum.
+   * The maximum is shorter for an emergency.
+   */
+  silence(alertId: string, durationSeconds?: number): Promise<Alert>
+
+  /** Silence every active alert. */
+  silenceAll(): Promise<void>
+
+  /** Raise an alert to a higher priority. */
+  escalate(alertId: string, priority: AlertPriority): Promise<Alert>
+
+  /**
+   * Report that the condition ended. Whether the alert resolves or waits for
+   * acknowledgment depends on its priority and whether it latches.
+   */
+  clearCondition(alertId: string): Promise<TransitionResult>
+
+  /** The active alerts, optionally filtered. */
+  list(filter?: AlertFilter): Alert[]
+
+  /** One active alert, or null. */
+  get(alertId: string): Alert | null
+
+  /** The active alert on a path, or null. */
+  getByPath(path: Path, context?: Context): Alert | null
+
+  /** The audit trail. */
+  history(
+    query?: AlertHistoryQuery
+  ): Promise<{ entries: HistoryEntry[]; total: number }>
+}
+
+/** @category Alerts API */
+export interface WithAlertsApi {
+  alerts: AlertsApi
+}

packages/server-api/src/index.ts

@@ -25,6 +25,7 @@ export * as history from './history'
 export * as typebox from './typebox'
 /** @category Notifications API */
 export * from './notificationsapi'
+export * from './alertsapi'
 export { FullSignalK, SourceMetaEntry } from './fullsignalk'
 export { getSourceId, fillIdentity, fillIdentityField } from './sourceutil'
 

packages/server-api/src/serverapi.ts

@@ -9,7 +9,8 @@ import {
   Delta,
   MetaValue,
   WithResourcesApi,
-  WithNotificationsApi
+  WithNotificationsApi,
+  WithAlertsApi
 } from '.'
 import { RadarProviderRegistry, WithRadarApi } from './radarapi'
 import { CourseApi } from './course'
@@ -88,6 +89,7 @@ export interface ServerAPI
     WithFeatures,
     CourseApi,
     WithNotificationsApi,
+    WithAlertsApi,
     SelfIdentity {
   /**
    * Returns the entry for the provided path starting from `vessels.self` in the full data model.

src/interfaces/plugins.ts

@@ -43,6 +43,10 @@ import {
   NotificationId,
   AlarmRaiseOptions,
   AlarmUpdateOptions,
+  AlertFilter,
+  AlertHistoryQuery,
+  AlertPriority,
+  RaiseAlertRequest,
   AccessScopedRouter,
   PluginRouter,
   RouteAccessLevel,
@@ -1036,6 +1040,30 @@ module.exports = (theApp: any) => {
       return courseApi.activeRoute(dest)
     }
 
+    // Each plugin gets its own shallow copy of `app`, so a surface one plugin
+    // attaches to its own copy is invisible to every other plugin. The alerts
+    // subsystem lives in core for exactly that reason.
+    appCopy.alerts = {
+      raise: (request: RaiseAlertRequest) =>
+        app.alertsApi.raise(request, plugin.id as SourceRef),
+      // Attributed to the plugin, not to a name the plugin picked: the audit
+      // trail has to say who acted, and a plugin is what acted.
+      acknowledge: (alertId: string) =>
+        app.alertsApi.acknowledge(alertId, plugin.id),
+      silence: (alertId: string, durationSeconds?: number) =>
+        app.alertsApi.silence(alertId, durationSeconds),
+      silenceAll: () => app.alertsApi.silenceAll(),
+      escalate: (alertId: string, priority: AlertPriority) =>
+        app.alertsApi.escalate(alertId, priority),
+      clearCondition: (alertId: string) =>
+        app.alertsApi.clearCondition(alertId, plugin.id as SourceRef),
+      list: (filter?: AlertFilter) => app.alertsApi.list(filter),
+      get: (alertId: string) => app.alertsApi.get(alertId),
+      getByPath: (path: Path, context?: Context) =>
+        app.alertsApi.getByPath(path, context),
+      history: (query?: AlertHistoryQuery) => app.alertsApi.history(query)
+    }
+
     appCopy.notifications = {
       list: () => app.notificationApi.list(),
       getId: (id: NotificationId) => app.notificationApi.getId(id),
@@ -1050,6 +1078,7 @@ module.exports = (theApp: any) => {
       acknowledge: (id: NotificationId) => app.notificationApi.acknowledge(id),
       acknowledgeAll: () => app.notificationApi.acknowledgeAll()
     }
+    delete (appCopy as any).alertsApi // expose only the plugin-specific methods
     delete (appCopy as any).notificationApi // expose only the plugin-specific methods
 
     try {

test/api/alerts/pluginApi.test.ts

@@ -0,0 +1,121 @@
+import { expect } from 'chai'
+import * as fs from 'fs'
+import * as path from 'path'
+import { freeport } from '../../ts-servertestutilities'
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const Server = require('../../../dist/')
+
+const CONFIG_DIR = path.join(__dirname, '..', '..', 'plugin-test-config')
+
+/**
+ * Two plugins, two copies of `app`, one alert subsystem.
+ *
+ * A plugin that attaches an API to its own `app` copy is invisible to every
+ * other plugin — the failure this subsystem is in core to avoid. These plugins
+ * only raise; the surface reaching them at all is the assertion.
+ */
+/** Only what this suite uses of a started server. */
+interface RunningServer {
+  start: () => Promise<unknown>
+  stop: () => Promise<unknown>
+}
+
+/** An alert as the list endpoint serves it. */
+interface ListedAlert {
+  path: string
+  $source: string
+  message: string
+}
+
+/** How long to wait for both plugins to have raised before giving up. */
+const RAISE_DEADLINE_MS = 20_000
+
+const POLL_INTERVAL_MS = 25
+
+describe('alerts plugin API', function () {
+  let server: RunningServer
+  let url: string
+
+  async function listAlerts(): Promise<ListedAlert[]> {
+    const response = await fetch(`${url}/signalk/v2/api/alerts`)
+    if (!response.ok) {
+      throw new Error(
+        `GET /signalk/v2/api/alerts answered ${String(response.status)}: ` +
+          `${await response.text()}`
+      )
+    }
+    return (await response.json()) as ListedAlert[]
+  }
+
+  /**
+   * Wait until both plugins' alerts are in the active set.
+   *
+   * The plugin loader does not await `start()`, so there is no event to hang
+   * this on; the active set is the only thing that says the raises landed.
+   */
+  async function bothPluginsHaveRaised(): Promise<void> {
+    const deadline = Date.now() + RAISE_DEADLINE_MS
+    for (;;) {
+      const paths = new Set((await listAlerts()).map((alert) => alert.path))
+      if (
+        paths.has('test.plugina.condition') &&
+        paths.has('test.pluginb.condition')
+      ) {
+        return
+      }
+      if (Date.now() > deadline) {
+        throw new Error(
+          `Neither plugin raised within ${String(RAISE_DEADLINE_MS)}ms; ` +
+            `the active set holds ${[...paths].join(', ') || 'nothing'}.`
+        )
+      }
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS))
+    }
+  }
+
+  before(async function () {
+    // The store survives a run, so a stale alert from an earlier one would
+    // let this pass without the plugins raising anything.
+    fs.rmSync(path.join(CONFIG_DIR, 'serverState', 'alerts'), {
+      recursive: true,
+      force: true
+    })
+    process.env.SIGNALK_NODE_CONFIG_DIR = CONFIG_DIR
+    const port = await freeport()
+    url = `http://127.0.0.1:${port}`
+    server = new Server({ config: { settings: { port } } })
+    await server.start()
+    // The plugin loader does not await start(), so the raises land some time
+    // after the server answers. A fixed wait is a bet on how long that takes.
+    await bothPluginsHaveRaised()
+  })
+
+  after(async function () {
+    await server.stop()
+    delete process.env.SIGNALK_NODE_CONFIG_DIR
+    // The boot writes these into the shared fixture directory; they are
+    // runtime state, not fixtures.
+    for (const artefact of ['settings.json', 'priorities.json']) {
+      fs.rmSync(path.join(CONFIG_DIR, artefact), { force: true })
+    }
+    fs.rmSync(path.join(CONFIG_DIR, 'serverState', 'alerts'), {
+      recursive: true,
+      force: true
+    })
+  })
+
+  it('gives every plugin a working surface, each alert attributed to its plugin', async function () {
+    const alerts = await listAlerts()
+
+    const raised = Object.fromEntries(
+      alerts.map((alert) => [alert.path, alert])
+    )
+    expect(Object.keys(raised)).to.include.members([
+      'test.plugina.condition',
+      'test.pluginb.condition'
+    ])
+    expect(raised['test.plugina.condition'].$source).to.equal('alertsplugin-a')
+    expect(raised['test.pluginb.condition'].$source).to.equal('alertsplugin-b')
+  })
+})