26 Commits
Author SHA1 Message Date
james.maesandClaude Fable 5.2 e26116e075 perf: scheduled jobs and the signal queue issue far fewer statements
maven / build (push) Successful in 2m25s
build / maven (push) Successful in 2m25s
The alerts jobs run every 15 to 60 seconds, so their statement count is a
host's constant database load. StatementBudgetTest counts the statements of
each job and polled request and fails when they grow with the rows held.
Measured with the same scenarios before (0.1.0-RC.18) and after:

- alertsEscalateAndRemind, 50 open alerts, nothing due: 452 -> 1. It reads
  only alerts a reminder or an escalation policy can apply to, decides from
  the row and the reference tables, and takes the per-alert transaction only
  when something may be due. An alert with nothing due is not written, so
  timedNotificationCheckedAt is the last attempt, not the last tick.
- alertsEvaluateMonitors: 20 monitors not due 5 -> 2 (due monitors selected
  in SQL, upkeep in one read); 20 due clean monitors 185 -> 84; a per-record
  monitor refreshing 10 alerts 205 -> 120.
- alertsDeliverNotifications: idle 9 -> 7; 60 pending deliveries in 2 groups
  317 -> 22; the purge runs hourly instead of every tick.
- Queued producer signals are recorded in batches: 200 resolves for alerts
  that are not open plus 50 heartbeats 369 -> about 33. A repeated raise of
  an open alert 17 -> 10.

AlertsReferenceCache holds alert types, groups, escalation policies, steps
and enabled mutes in a core Memoization registered with core ClusterCaches.
A record-change listener clears a table on every node (ClusterBus) when it
is written through QQQ; entries expire after 60 seconds; a table over 2,000
rows is not held. A type's openCount and lastRaisedAt are engine counters:
they do not clear the cache and are no longer record-audited.

Changeset 55 adds ix_alerts_alert_flapping for the upkeep read.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 15:39:02 -06:00
james.maesandClaude Opus 5.5 489663a946 feat(ui-api): extension for QQQ UI API 1.6.0 (operationIds, BasicErrorResponseV1, QQQ 4.1.0-RC.14)
Regenerated against UI API 1.6.0: every operation has an operationId and
the standard error responses (BasicErrorResponseV1: error, code, message,
fieldErrors, traceId); the extension's own error schema is kept but
deprecated; hand-written error bodies go through QJavalinUtils so they carry
code/message/traceId. Extension MINOR bumped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 11:43:36 -05:00
james.maesandClaude Opus 5.5 50e1b52a4d feat(help): ship the Alerts help bundle through QQQ help bundles (419 entries, coverage gate)
Host-neutral text (kof22-specific facts removed), registered with
HelpBundles in the producer, gated by HelpBundleAssertions. Replaces the
temporary AlertsHelp loader.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 20:01:53 -05:00
james.maes ff177bd021 Merge pull request #36 from QRun-IO/feature/tables-populated-defaults
Every Alerts table used, seeded or explained; setup card and help
2026-10-14 17:31:48 -05:00
james.maesandClaude Opus 5.5 5c545dc8e1 fix(routing): review findings on owner team, sync and default channels
- coverage is decided by scope and severity, so a subscription with fewer events
  still counts; follow-ups go to the owner team only after it was told of the raise
- the first-visit type sync is best effort and never breaks the bell
- default channels keep the bell and replace only the built-in email choice
- KIND_SETUP in AlertsHome.kinds(); help marker reworded

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 17:23:04 -05:00
james.maesandClaude Opus 5.5 35c3b00d6f fix(defaults): empty rollback, rollback test, include order
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 17:13:22 -05:00
james.maesandClaude Opus 5.5 4077e8a725 feat: starter defaults, setup card and table help so no config table starts empty
Adds alerts-defaults.changelog.sql (in-app and email channels, alerts and other
groups; insert-only, guarded, tested through real Liquibase), a help bundle for
the app and every table, a Setup card on the home, guardrail tests, and docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 16:52:48 -05:00
james.maesandClaude Opus 5.5 411a8ff604 Merge origin/develop into feature/notification-preferences-section; pin QQQ 4.1.0-RC.7
Keeps develop's per-user Slack delivery, escalation and mute work; the
in_app_min_severity changeset moves to qbit-alerts:29; the Notifications
preferences section gains Slack per category; pause also skips non-security
Slack; the summary schema carries preferencesSection (alerts extension 1.1.0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 16:36:00 -05:00
james.maes ebfb71c910 Merge remote-tracking branch 'origin/develop' into feature/quiet-hours-digests
# Conflicts:
#	CHANGELOG.md
#	README.md
#	src/main/java/com/kingsrook/qbits/alerts/engine/AlertRouter.java
#	src/main/java/com/kingsrook/qbits/alerts/metadata/AlertsProcessesMetaDataProducer.java
#	src/main/java/com/kingsrook/qbits/alerts/processes/AlertsScheduledSteps.java
#	src/main/resources/db/liquibase/qbit-alerts/alerts.changelog.sql
#	src/test/java/com/kingsrook/qbits/alerts/AlertsQBitProducerTest.java
2026-10-14 11:12:39 -05:00
james.maesandClaude Opus 5.5 8c6e4dadfa feat(routing): apply quiet hours, user pause and digests
Quiet hours, digest hour and pause were editable in My Alert Settings
but never applied, and DIGEST_HOURLY / DIGEST_DAILY subscriptions sent
immediately.

- The router suppresses push deliveries (email, lists, webhooks) to a
  user during their quiet hours (time zone, windows across midnight,
  quiet days; severities at or above quietBypassSeverity, default
  CRITICAL, break through) as QUIET_HOURS, and while paused as
  USER_PAUSED. The in-app bell is never suppressed by either. A channel
  below its minimum severity is now logged as MIN_SEVERITY.
- Digest subscriptions queue DIGEST deliveries per user/channel and
  window. The hidden hourly alertsSendDigests job sends one grouped
  message per window (hourly, or daily at the user's digest hour in
  their time zone) through the existing email path or one in-app
  notification, rechecks visibility, skips empty digests and never
  sends a window twice. Failed or oversized windows stay visible.
- Changeset 27 adds the durable digest dispatch columns.

Refs #27

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 11:02:08 -05:00
james.maes e2c5181782 Merge remote-tracking branch 'origin/develop' into feature/reminders-escalation
# Conflicts:
#	src/main/resources/db/liquibase/qbit-alerts/alerts.changelog.sql
#	src/test/java/com/kingsrook/qbits/alerts/AlertsQBitProducerTest.java
2026-10-14 10:54:01 -05:00
james.maesandClaude Opus 5.5 28664d7d8b feat(engine): reminders and escalation policies
reminderIntervalMinutes was stored but never read, escalationLevel was
always 0 and nothing raised ESCALATED or REMINDER.

- Reminders: an open, unacknowledged, unsnoozed, unmuted alert sends a
  REMINDER through the normal router every reminderIntervalMinutes of
  its type (CRITICAL defaults to 60, explicit 0 turns it off).
- Escalation policies (design table 14): alerts_escalation_policy and
  alerts_escalation_step (step list on the policy record), linked from
  alert types and groups (type wins). A hidden scheduled job notifies
  each step's USER, TEAM or CHANNEL target as ESCALATED when the alert
  reaches the step's age, records an ESCALATED event and the level,
  then repeats the last step every repeatAfterMinutes up to maxRepeats.
  Acknowledge, snooze, resolve and mute stop both; a reopen resets.
  Idempotent within a minute.
- EXPIRED stays reserved and is no longer offered as a resolution.

Changesets 23-26 (21-22 are taken by the team-sources PR).

Refs #27

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 10:52:29 -05:00
james.maesandClaude Opus 5.5 ea5f67933a feat(routing): resolve ROLE and IdP Group teams; per-alert mutes
Team member sources ROLE and IDP_GROUP were stored but never resolved,
so only manual members were notified. A host can now register an
AlertAudienceResolver (AlertsQBitConfig.withAudienceResolver); team
expansion merges its users with manual members, de-duplicated, bounded
by maxAudienceSize, and every user still passes the visibility check.
Without a resolver those sources resolve to nobody, the router logs it
and the team screen says so.

The per-alert Mute action muted the whole alert type, and RECORD-scope
mutes never matched because no record id reached the matcher. Mute now
mutes only that alert (new ALERT scope on type + dedup key), RECORD
mutes compare the stored scopeRecordId, and "Mute this alert type" is a
separate, clearly labelled action. Changesets 21-22 add
alerts_mute.scope_record_id and widen scope_value.

Refs #27

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 10:46:38 -05:00
james.maesandClaude Opus 5.5 b08e729728 refactor(email): use qbit-email's public api package; no G1 allow-list
Moves the optional email integration from qbit-email internals to
com.kingsrook.qbits.email.api (qbit-email 0.1.0-RC.2) with identical
behaviour, and moves to qbit-build-parent 2.1.1, whose default G1
allow-lists include qbit-email's API (QRun-IO/qbit-bom#12), so the
per-repo allow-lists are gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 10:20:27 -05:00
james.maesandClaude Opus 5.5 5515c4c2bc Merge develop into feature/email-qbit
Keeps develop's changes and re-applies the optional qbit-email 0.1.0-RC.1
delivery on top (adapted to develop's refactors; guardrail allow-lists
for the optional integration where the build parent enforces them).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 08:19:02 -05:00
james.maesandClaude Opus 5.5 3d56ccc403 feat(routing): fan record alerts out to followers via core RecordFollowers
An alert about a record now also reaches the record's followers, from
core RecordFollowers.get(instance, ref, FollowEvent.ALERT) (QRun-IO/qqq#1164,
QQQ 4.1.0-RC.6). Followers are deduplicated with existing recipients by
user and channel. They must pass the source-record permission and lock
checks, and they get the same preferences and suppression as any other
recipient. With no provider registered, routing is unchanged. There is no
dependency on qbit-collaboration, and the #1164 stand-in marker is gone.

Also adopt qbit-build-parent 2.1.0 with the guardrails enforced and strict
raw-route mode. Comments that only used the word "stand-in" are reworded.

Refs #16 (architecture review QRun-IO/qqq#1150, finding F12).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 07:43:46 -05:00
james.maesandClaude Opus 5.5 8004089b47 feat(email): send alert, notification and digest email through qbit-email when installed
Phase (d) of QRun-IO/qbit-email docs/DESIGN.md section 11. qbit-email is an
optional dependency (0.1.0-SNAPSHOT until its first RC) used through one
adapter class behind a classpath and instance guard; without it the
existing behaviour is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 23:12:34 -05:00
james.maesandClaude Opus 5.5 60b68cf722 refactor(notifications): deliver core QAlerts.notify; delete the spi stand-in
Core 4.1.0-RC.6 ships user notifications (QAlerts.notify,
NotificationSignal and friends; QRun-IO/qqq#1125). The qbit's sink now
implements core's notify path, so a QAlerts.notify from any qbit reaches
the notification queue, inbox, channels, quiet hours and preferences.
The rest of the stand-in package com.kingsrook.qbits.alerts.spi goes
(NotificationSignal, NotificationAudience, NotificationCategory,
NotificationSeverity, AlertLink, package-info), and so does
AlertsRuntime.sink().

Breaking for anything that used com.kingsrook.qbits.alerts.spi; its only
consumer, qbit-easypost-tracking, moved to core in #16 there.

Closes #15 (architecture review QRun-IO/qqq#1150, F3 and F12).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 20:34:22 -05:00
james.maesandClaude Opus 5.5 2692f8b1dc feat(api): alerts UI routes as spec'd extension endpoints; webhook to /qqq/hooks; follow via collaboration
#13: the six inbox and record-panel routes move from the raw
AlertsRouteProvider onto a MiddlewareSpecExtension "alerts" (prefix
/alerts). Paths are unchanged. The committed fragment
openapi/qqq-v1/alerts.yaml is checked by a contract test, and the server
tests run in strict mode. Additive fields let Next stop hard-coding
alerts names: the summary has inboxHref, and inbox items and panel
alerts have actions with process names and hrefs.

#14: the Alertmanager webhook moves to POST /qqq/hooks/alerts/alertmanager.
The old /qqq/v1 path is an opt-in deprecated alias (legacyAlertmanagerPath,
default off; it needs non-strict mode). The alias sends Deprecation and
Sunset headers and logs a warning per call.

#16: POST /alerts/record-panel/watch is removed; collaboration owns
following a record. The record panel reports follow.available when the
collaboration extension is registered. Existing record-scoped watch
subscriptions stay readable and are deprecated. Follower fan-out waits for
core RecordFollowersProviderInterface (STAND-IN(core=QRun-IO/qqq#1164,
removeBy=4.1.0-RC.7)).

The checkstyle header template now matches the short Apache header that
the sources already use. The core baseline becomes 4.1.0-RC.6.

Closes #13, closes #14, closes #16 (architecture review QRun-IO/qqq#1150,
F2, F7, F12, F20).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 20:18:36 -05:00
james.maesandClaude Opus 5.5 63bdc9313d feat(preferences): Notifications section in user Preferences
Registers a core Preferences section 'notifications' backed by
alerts_user_preference, alerts_notification_preference and the user's own
alerts_subscription rows: pause, digest time and time zone, alert email and
in-app switches, per-category in-app/email settings (security can't be
muted) and per-subscription overrides. Adds in_app_min_severity
(changeset qbit-alerts:21), honours it for in-app delivery, and skips
non-security emails while paused. The inbox summary returns
preferencesSection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 19:35:29 -05:00
james.maesandClaude Opus 5.5 cb3d206e0f refactor(alerts): use core QAlerts and WebhookSigner from QQQ 4.1.0-RC.5
Bump the core baseline to 4.1.0-RC.5 and delete the alert-side copies in
the spi package. The qbit now registers its sink in core's
AlertsInstanceMetaData, so core QAlerts.raise/resolve/heartbeat from any
host qbit reaches it. The alertsQBitStandIn name is gone.

The notification types (NotificationSignal and friends) and
AlertsRuntime.sink().notify stay, binary compatible, for the released
qbit-easypost-tracking. They are tagged
STAND-IN(core=QRun-IO/qqq#1125, removeBy=4.1.0-RC.6).

StandardWebhookSigner delegates to core WebhookSigner. The wire format is
unchanged. Legacy secrets shorter than core's 16-byte minimum are
zero-padded, which gives an identical HMAC-SHA256.

Refs #15 (architecture review QRun-IO/qqq#1150, F3 and F11).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 19:31:16 -05:00
james.maesandClaude Opus 5.5 65fa558ed5 feat(notifications): security, share and release notices, email digests, home line; harden links (phases d, e)
- AlertsNotices: newSignIn, apiKeyCreated, apiKeyExpiring (deduped per
  key), permissionChanged, shared, release.
- NotificationEmailer: opt-in email per user and category, IMMEDIATE (at
  or above a minimum severity) or DAILY_DIGEST at the user's digest hour
  and time zone; inert without a messaging provider; ALERT not emailed
  here; SECURITY emails carry no body. Runs in the delivery job.
- Alerts home: a link-only Notifications line for authors.
- safeLink refuses backslashes, whitespace, control characters, a second
  leading slash, and anything but https with a host (open-redirect fix
  from security review); the table customizer uses it on save.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 10:15:05 -05:00
james.maesandClaude Opus 5.5 4a94a23314 feat(notifications): user notifications, recipients, audiences and the bell API (phase a)
- alerts_notification (user notifications), alerts_notification_recipient
  (one row per user, read/dismissed) and alerts_notification_preference
  (per-category mute and email settings), with entities, changelog and
  test DDL.
- The delivery log becomes alerts_delivery and alerts_inbox_item is
  retired (guarded changesets 16-17); in-app alert delivery writes ALERT
  notifications and recipient rows.
- Audiences resolved at send time (all users, roles, permission, users)
  through a pluggable user directory; record actions Preview audience,
  Send now, Schedule and Retract; scheduled sends and retention purge in
  the delivery job.
- Bell API: summary with banners, a paged page endpoint with filters,
  read, unread and dismiss; alerts_recipient security key and
  alerts.notification.admin.
- NotificationSignal / NotificationAudience in the SPI stand-in, and the
  sink's notify.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 10:03:47 -05:00
james.maesandClaude Opus 5.5 050c141c6b feat: external channels (Slack, Teams, signed webhook, PagerDuty, Alertmanager) and Alertmanager ingest (P4)
- SLACK (Incoming Webhook, Block Kit), TEAMS (Workflows webhook, Adaptive
  Card), WEBHOOK (Standard Webhooks signature via a stand-in for core's
  WebhookSigner, QRun-IO/qqq#1109), PAGERDUTY (Events API v2 trigger /
  acknowledge / resolve, dedup_key = type:key), ALERTMANAGER sink
  (/api/v2/alerts, qqq_* labels, qqq_origin guard, endsAt on resolve)
- shared HTTP rules: https only unless allowInsecureHttp, 10 s timeout,
  2xx sent, 408/425/429/5xx retry, other 4xx permanent; URLs (secrets for
  Slack and Teams) never appear in errors
- AlertMessage carries one structured, redacted entry per alert
- POST /qqq/v1/alerts/ingest/alertmanager: bearer token by secret
  reference (off without one), firing/resolved to raise/resolve, EXTERNAL
  prometheus.* types with notifications off, loop guard

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 17:23:03 -05:00
james.maesandClaude Opus 5.5 45c7b4fb8f feat: alerts tables, engine, monitors, in-app and email delivery, Alerts home and bell API (P1-P3)
Implements phases P1 to P3 of the Alerts design (QRun-IO/qqq#1090):
- 15 alerts_* tables with the Liquibase changelog, record security
  (alerts_user / alerts_permission / alerts_readable_table keys) and a
  write guard so alerts change only through the engine and record actions
- the state machine: dedup, refresh, severity changes, snooze, resolve,
  reopen window, flapping, quiet-period auto-resolve, maintenance windows
- monitors: TABLE_QUERY, AGGREGATE, HEARTBEAT, PROCESS_FAILED, CODE, with
  the full-state diff, forMinutes, timeouts, CHECK_FAILED meta-alert and
  seeded monitors
- routing with scopes, teams, the bootstrap rule, recipient visibility and
  logged suppression reasons; in-app, email and email-list channels; a
  channel SPI; retries to DEAD and channel health; redaction
- record actions as streamed ETL processes; hidden scheduled processes
- the Alerts app home, AlertSummaryLoader, and /qqq/v1/alerts routes for
  the Next UI bell and record panel

The core producer SPI (QRun-IO/qqq#1108) is not released yet, so its types
are a stand-in in the spi package, marked for replacement.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 16:57:39 -05:00
james.maesandClaude Opus 5.5 0e10190158 chore: bootstrap qbit-alerts with the QRun qbit repository standard
Maven scaffold (qbit-build-parent 2.0.0, com.kingsrook.qbits, <revision>
versioning, qqq 4.1.0-RC.4 BOM, JaCoCo gate), QBit config and producer,
CircleCI qqq-orb pipeline, and the standard repository files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 14:41:27 -05:00