v0.26.0

[antybubbs]

Kaya v0.26.0 Release Notes

Kaya v0.26.0 introduces the Notification Centre, optional PWA Web Push, durable background delivery, more resilient IP/WAN monitoring, quieter Pi-hole HA recovery reporting, and automatic versioned database migrations.

Notification Centre

• A new notification inbox provides retained, per-user operational history with unread counts, dismissal, filtering, and links back to the affected Kaya module.
• Users can manage notification preferences and registered Push devices from their profile. Administrators can control framework-wide channels, retention, event-category policy, cooldowns, and whether users may customise their own preferences.
• In-application notifications are enabled by default. Push and email remain disabled until an administrator enables and configures them.
• Initial production publishers cover IP/WAN host outage and recovery, failed Kaya-managed backup jobs, notification worker failures, and Pi-hole HA node, cluster, sync, failover, and failback events.
• Recipient selection respects active accounts and module allocation. Active administrators receive infrastructure-wide events, while resource-specific access remains enforced by the destination route.
• Duplicate polling and repeated reconciliation do not create notification storms. Active conditions retain one incident identity and recovery resolves the matching condition.

PWA Web Push

• Administrators can generate, rotate, enable, disable, test, and delete VAPID keys from Site Administration → Notifications.
• Kaya validates generated key pairs with the production Web Push library and encrypts UI-managed private keys using the installation ENCRYPTION_KEY.
• Deployments may instead provide VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, and VAPID_SUBJECT. Deployment-managed values take precedence and incomplete or invalid configuration fails closed.
• Push permission is requested only after a user explicitly enables it for the current device. Kaya includes guidance for installing the PWA and enabling Push on supported iPhone and iPad versions.
• Signing out revokes that account's device subscriptions. Disabling a user also revokes their active subscriptions; rotating or deleting keys revokes subscriptions tied to the old key.
• Push delivery validates approved HTTPS browser-push endpoints, public DNS resolution, redirects, payload routes, and response limits. Subscription endpoints and key material are never returned in normal device APIs or diagnostic output.

Durable delivery and diagnostics

• Operational state changes and their notification outbox work are committed together. Browser sessions, open pages, and provider availability are no longer required for event creation.
• In-app history is created before optional Push or email delivery. Provider failures cannot remove history or roll back a completed monitoring, backup, or HA action.
• Delivery uses bounded retries and explicit states for queued work, provider acceptance, temporary failure, expired subscriptions, cancellation, and retry exhaustion.
• Dedicated outbox, delivery, and reconciliation workers expose heartbeats, restart counts, queue age, retry state, and quarantined work in the administrator Delivery Health view.
• A failed reconciliation item is isolated from other monitored resources, retried with backoff, and quarantined for administrator review rather than silently dropped.
• Administrator diagnostics exercise the same durable pipeline as production events and report safe stage counts and correlation references without exposing addresses, subscription endpoints, keys, or provider payloads.

IP/WAN Monitor

• Monitor ordering now persists per user across the dashboard and authenticated Wallboard. Reordering either view updates one shared preference; new monitors append automatically and deleted monitors are ignored.
• Reset layout restores canonical monitor ordering without changing unrelated Wallboard display settings.
• Saved monitor-order input is type-checked, size-limited, restricted to existing monitor IDs, and committed transactionally.
• Every changed derived state now has a retained transition linked to the observation that caused it. Scheduled checks and Check now use the same transition and notification path.
• Offline incidents and their notification outbox entries commit atomically. Startup and periodic reconciliation restore only genuinely missing active incidents and resolve stale ones without duplicating history.
• The monitoring scheduler is supervised by an independent watchdog. Unexpected task exit or stale heartbeat is diagnosed, reported, and restarted without cancelling the rest of the scheduler.
• Administrator-only, non-cacheable scheduler diagnostics expose safe liveness information such as task state, heartbeat, pending count, observations, and restart state.

Pi-hole High Availability

• Pi-hole HA now publishes central notifications for cluster degradation and recovery, node unreachability, automatic-sync failure, controlled failover/failback lifecycle stages, and verified automatic failover completion.
• Notification persistence and provider delivery are isolated from service movement: notification failure cannot reverse a verified failover or failback.
• Failover history includes redacted per-channel delivery counts for diagnosis without storing subscription endpoints or provider responses.
• Routine configuration comparisons no longer invalidate the last successful current-generation sync. A healthy standby remains STANDBY_READY through PENDING, RUNNING, and IN_SYNC background checks.
• Starting a routine sync does not reset the recovery stability timer or create repeated recovery synchronising, verifying, and standby-ready Activity events.
• Supported configuration drift still invalidates readiness when it is actually observed. After guarded synchronisation and stability verification, the node returns once to STANDBY_READY.
• Active synchronisation and verification windows are no longer shown as a red Recovery state appears stale warning while recent progress is present. The warning remains available after five minutes without meaningful progress.

Versioned database migrations

Kaya now uses Alembic for versioned database migrations. Existing SQLite installations are not recreated and should not require users to rebuild their database.

On the first upgrade, Kaya validates the database, creates a verified timestamped backup under /app/data/backups, runs the retained historical compatibility path where required, validates the resulting schema, and records the baseline revision. Migration runs before user traffic and background services start.

Pre-Alembic upgrades use targeted schema validation and a verified SQLite API backup. A slow PRAGMA quick_check no longer blocks routine startup or masquerades as corruption; strict quick-check diagnostics remain available from the database CLI. If backup, compatibility, or migration validation fails, Kaya aborts startup and reports the recovery location in its logs.

Docker now allows a 120-second startup grace period before health-check failures count, while genuine startup failures still become unhealthy. Administrators can inspect the current revision with alembic -c /app/alembic.ini current inside the container. See Administrator Database Upgrades for recovery guidance.

Interface and documentation

• Values calculated in powers of 1,024 are now labelled KiB, MiB, GiB, and TiB.
• The README now provides a fuller capability guide across Kaya's dashboard, infrastructure, networking, security, documentation, remote access, administration, and deployment features.
• New notification documentation covers setup, user enablement, Web Push, privacy, retention, backup and restore, delivery semantics, diagnostics, and troubleshooting.

Upgrade notes

• Pull and start the new Kaya image normally. Required database backup and migration work runs automatically; routine upgrades require no manual Alembic commands.
• Preserve /app/data and review available disk space before upgrading. Migration backups and notification records may contain sensitive application data and must remain protected.
• Preserve the original ENCRYPTION_KEY separately from database backups. UI-managed VAPID private keys and Push subscriptions cannot be recovered from a restored database without it.
• Web Push requires a secure HTTPS browser context, except for browser-supported localhost development. Reverse proxies must forward the real scheme through Kaya's trusted-proxy configuration.
• All three deployment-managed VAPID values must be supplied together and valid. Correct or remove an incomplete set before starting Kaya.
• Kaya supports one application process per SQLite database. Multiple application replicas sharing one SQLite file remain unsupported.
• Existing notification preferences, Push configuration, subscriptions, history, and monitor ordering are preserved when their corresponding channel or view is disabled.

Security and privacy

• Notification APIs enforce authentication, active-session checks, role or module access, CSRF protection for browser mutations, object-scoped reads, and bounded input validation.
• Sensitive Vault and Secure Send event families use generic safe notification text because Push content may appear on a locked device. A notification never grants access to its destination.
• VAPID private keys and Push subscriptions are encrypted at rest. Secrets, endpoints, provider response bodies, and sensitive payload fields are excluded from logs, audits, diagnostics, and operation history.
• Push endpoint validation constrains outbound requests to supported browser providers over HTTPS port 443, rejects private or non-public resolution, and refuses redirects.
• Background worker and operational-event failures remain observable through durable, redacted records without weakening the underlying monitoring, backup, or HA safety controls.

---

This discussion was created from the release v0.26.0.