36 lines
2.1 KiB
Markdown
36 lines
2.1 KiB
Markdown
# alerts
|
|
|
|
## Purpose
|
|
|
|
Delivers user-facing notifications for events the rule engine has flagged. Provides Web Push (VAPID) delivery to registered browsers and phones, PIN hashing/verification for arm/disarm flows, and a smart-profile matcher that selects recipients based on household state and time-of-day windows. Every alert attempt is logged through `vigilar.alerts` logger; the main supervisor attaches a dedicated syslog handler to that logger so alerts leave an OS-level audit trail.
|
|
|
|
## Key files
|
|
|
|
- `vigilar/alerts/sender.py` — `send_alert`, `build_notification`, VAPID Web Push dispatcher; reads `push_subscriptions` and writes `alert_log`
|
|
- `vigilar/alerts/profiles.py` — smart alert profile matcher (household state + time windows)
|
|
- `vigilar/alerts/pin.py` — PBKDF2-SHA256 PIN hashing and constant-time verification
|
|
|
|
## MQTT topics
|
|
|
|
**Subscribes:** none directly. `alerts` is not a standalone subsystem process; it is invoked synchronously from the events processor when a rule action fires.
|
|
**Publishes:** No MQTT publishers found at time of writing. The events processor publishes `vigilar/system/alert` on behalf of alert actions.
|
|
|
|
## Database tables
|
|
|
|
- `alert_log` — one row per delivery attempt (channel + status + error)
|
|
- `push_subscriptions` — VAPID Web Push subscriptions, read to fan out a notification; stale entries are removed via `delete_push_subscription`
|
|
|
|
## Depends on
|
|
|
|
- `events` — `send_alert` is called from `EventProcessor._execute_action` for `alert_all` / `push_and_record`
|
|
- `storage` — reads `push_subscriptions`, writes `alert_log`
|
|
|
|
## Consumed by
|
|
|
|
- Phones and browsers — receive Web Push notifications via VAPID
|
|
- `web` — the `system` blueprint manages push subscription registration and PIN verification
|
|
|
|
## Notes
|
|
|
|
The `vigilar.alerts` logger gets a syslog handler installed by the supervisor (`vigilar/main.py`) so that every alert emission is mirrored into the host's syslog as an out-of-band audit trail, independent of SQLite. PIN verification uses `hmac.compare_digest` to avoid timing leaks. The smart-profile matcher honours `household_state` and HH:MM time windows (including windows that wrap past midnight).
|