Skip to content

Home Information - Your home, your data, organized.

Python
17.9 KB
Raw Blame
"""
Per-integration sync-check state, and the integration-agnostic delta
primitive used to compute it.

A periodic background probe surfaces a "needs-sync" signal when an
integration's HI representation has drifted from upstream. The probe
never modifies entities -- the user always chooses when to invoke
Refresh. Per-integration probe logic lives in each
``IntegrationConnector.check_needs_sync()`` override, which returns
a ``SyncDelta``; sync-check rides on the same opt-in surface as full
sync (an integration without a synchronizer naturally opts out of
the periodic drift check too). The framework monitor wraps the
returned delta into a ``SyncCheckResult`` (delta + timestamp +
summary) and caches it. The cache entry is the *last known state of
the check*, not a "warning flag" -- a successful Refresh records a
zero-delta result with a current timestamp so the UI can show
"verified up to date at HH:MM".

State is stored via ``django.core.cache`` (Redis-backed in
production); no DB model. Frozen dataclasses pickle cleanly through
the cache backend, so no custom serialization is needed; the cache
TTL bounds the impact of any class rename.
"""

import logging
from dataclasses import dataclass, field
from datetime import datetime
from typing import Optional, Set

from django.core.cache import cache

from hi.apps.alert.alarm import AlarmSignature
from hi.apps.alert.enums import AlarmLevel, AlarmSource
import hi.apps.common.datetimeproxy as datetimeproxy
from hi.apps.common.enums import LabeledEnum

from hi.integrations.transient_models import IntegrationKey

logger = logging.getLogger(__name__)


class SyncCheckOutcome( LabeledEnum ):
    """
    Per-integration result classification used by the framework
    monitor's bookkeeping. Not user-facing -- this drives the cycle's
    summary log line, not the UI banner.
    """
    OPTED_OUT  = ( 'Opted Out'  , 'Integration does not implement sync-check.' )
    IN_SYNC    = ( 'In Sync'    , 'Upstream and HI match as of this check.' )
    NEEDS_SYNC = ( 'Needs Sync' , 'Upstream has changes not yet imported.' )
    ERROR      = ( 'Error'      , 'The probe failed; the cycle continues.' )


@dataclass(frozen=True)
class SyncDelta:
    """
    Result of comparing two integration-key sets -- what the
    synchronizer's ``check_needs_sync()`` returns. Integration-
    agnostic; the convention is that ``added`` contains keys upstream
    but not in HI, and ``removed`` contains keys in HI but not
    upstream. Update detection (key-present-on-both-sides but content
    changed) is not modeled.

    Both sets contain ``IntegrationKey`` instances so comparison and
    hashing automatically apply the canonical normalization
    (``IntegrationKey.__post_init__``) -- the same canonicalization
    that produced the stored ``entity.integration_key`` values. The
    probe never has to know about the normalization rule.
    """
    added   : Set[ IntegrationKey ] = field( default_factory = set )
    removed : Set[ IntegrationKey ] = field( default_factory = set )

    @property
    def added_count(self) -> int:
        return len( self.added )

    @property
    def removed_count(self) -> int:
        return len( self.removed )

    @property
    def needs_sync(self) -> bool:
        return bool( self.added or self.removed )


@dataclass(frozen=True)
class SyncCheckResult:
    """
    Cached state for one integration: the most recent ``SyncDelta``
    plus when the check ran and a short human-readable summary for
    the UI. Always present after the first cycle (or after a
    successful Refresh) -- even when nothing has drifted, the
    zero-delta result records "verified up to date at HH:MM".
    """
    delta             : SyncDelta
    last_checked_at   : datetime
    summary_message   : str

    @property
    def needs_sync(self) -> bool:
        return self.delta.needs_sync


class IntegrationSyncCheck:
    """
    Namespace for the sync-check primitives: cache access, the
    optional set-comparison helper, and the result builders. Class
    methods rather than module-level functions so call sites carry
    the ``IntegrationSyncCheck.`` prefix and group naturally.
    """
    
    INTERVAL_SECS = 4 * 60 * 60

    # Ceiling on the post-acknowledgement nag window: once a user
    # dismisses the needs-sync alert, suppression lasts at most this
    # long before another needs-sync alarm can re-surface. The
    # expected case is shorter -- when the integration syncs back to
    # clean, the producer dispatches ``AlertManager.clear_alarms`` and
    # the dedup anchor drops immediately. Twenty-four hours balances
    # letting the operator defer within their workday against
    # reminding them the next time they sit down at the console.
    NAG_INTERVAL_SECS = 24 * 60 * 60

    _CACHE_TTL_SECS = INTERVAL_SECS * 2
    _CACHE_KEY_PREFIX = 'integrations:sync_check:'

    @classmethod
    def _cache_key( cls, integration_id : str ) -> str:
        return f'{cls._CACHE_KEY_PREFIX}{integration_id}'

    @staticmethod
    def compute_delta( upstream_keys : Set[ IntegrationKey ],
                       current_keys  : Set[ IntegrationKey ] ) -> SyncDelta:
        """
        Pure utility for integrations whose check reduces to comparing
        a set of upstream IntegrationKeys against a set of HI
        IntegrationKeys. Most integrations call this from inside
        their ``check_needs_sync()``; integrations with non-set
        semantics can build a ``SyncDelta`` directly.

        Set arithmetic on ``IntegrationKey`` instances picks up the
        canonical normalization automatically (via the dataclass's
        ``__hash__`` / ``__eq__``), so the probe never has to know
        about the normalization rule. Callers feed already-filtered
        sets so the counts match what Refresh would actually act on,
        not what the upstream raw response contains.
        """
        return SyncDelta(
            added   = set( upstream_keys ) - set( current_keys ),
            removed = set( current_keys )  - set( upstream_keys ),
        )

    @classmethod
    def get_state( cls, integration_id : str ) -> Optional[ SyncCheckResult ]:
        """Return the most recent cached result, or None if no probe
        has written one (or the entry has expired).

        Tolerates unreadable cache entries. The cached value is a
        pickled dataclass, which means a class rename, module move,
        or shape change can make existing entries fail to deserialize
        in-place. Without a guard, every read of a stale entry would
        propagate the unpickle exception out through the manage page.
        Catch broadly, evict the bad key so the next request runs
        clean, and degrade to a cache miss -- the next probe cycle (or
        a successful Refresh) writes fresh state."""
        if not integration_id:
            return None
        cache_key = cls._cache_key( integration_id )
        try:
            return cache.get( cache_key )
        except Exception as e:
            logger.warning(
                f'sync-check cache entry unreadable for {integration_id}: '
                f'{e}; evicting and treating as miss'
            )
            try:
                cache.delete( cache_key )
            except Exception:
                pass
            return None

    @classmethod
    def set_state( cls,
                   integration_id : str,
                   result         : SyncCheckResult ) -> None:
        """Write a probe result to the cache. The TTL is bounded so a
        stopped monitor cannot leave forever-old state visible. Fires
        a transition alarm when the recorded state moves from
        no-prior / in-sync to needs-sync (see ``_should_alarm``);
        in-progress drift does not re-alarm cycle after cycle.

        Concurrency: this is a read-modify-write on the cache without
        a lock. The two writers (the framework monitor's probe cycle
        and ``record_sync_complete`` via the synchronizer's post-sync
        hook) can run concurrently if a user-triggered Refresh
        overlaps a probe cycle. Duplicate-direction races (both
        writers see ``prior=clean`` and call ``_fire_needs_sync_alarm``)
        collapse to a single alert via ``AlertManager``'s
        signature-based dedup. Opposite-direction races have a small
        bad window: probe reads ``prior=clean``, computes
        needs_sync; Refresh writes in_sync and calls
        ``_clear_needs_sync_alert``; probe then fires the (now-stale)
        alarm. The resolution path will not re-fire (cache reads
        in_sync), so the alert sits in the queue until
        ``NAG_INTERVAL_SECS`` lifetime expiry -- the exact failure
        mode the producer-side clear is meant to eliminate. The
        window is small enough and the operator-visible impact (a
        dismissable nuisance alert that resolves on its own within
        24h) light enough that we accept it rather than add a Redis
        lock that would trade real cache-backend portability risk
        (LocMemCache in tests) for a marginal UX win."""
        if not integration_id:
            return
        prior = cls.get_state( integration_id )
        cache.set(
            cls._cache_key( integration_id ),
            result,
            timeout = cls._CACHE_TTL_SECS,
        )
        logger.debug(
            f'sync-check state recorded for {integration_id}: '
            f'needs_sync={result.needs_sync} '
            f'added={result.delta.added_count} '
            f'removed={result.delta.removed_count}'
        )
        if cls._should_alarm( prior = prior, current = result ):
            # Alarm delivery failures must not break the cache write
            # -- the probe state is already persisted; the next
            # clear->set transition will re-attempt notification.
            try:
                cls._fire_needs_sync_alarm(
                    integration_id = integration_id,
                    result = result,
                )
            except Exception as e:
                logger.warning(
                    f'Failed to fire needs-sync alarm for '
                    f'{integration_id}: {e}'
                )
        elif cls._should_clear_alarm( prior = prior, current = result ):
            # Drop any pending needs-sync alert immediately on
            # convergence rather than waiting out the
            # ``NAG_INTERVAL_SECS`` post-ack suppression window.
            # Failure here must not mask the cache write -- the next
            # resolution event will retry.
            try:
                cls._clear_needs_sync_alert( integration_id = integration_id )
            except Exception as e:
                logger.warning(
                    f'Failed to clear needs-sync alert for '
                    f'{integration_id}: {e}'
                )

    @staticmethod
    def _should_alarm( prior   : Optional[ SyncCheckResult ],
                       current : SyncCheckResult ) -> bool:
        """Notification gate. Fires only on the clear -> needs-sync
        transition: prior was None (first probe / cache expired) or
        in-sync, AND current reports needs-sync. Drift that persists
        across cycles (needs-sync -> needs-sync) does not re-alarm --
        the user has already been told. Refresh-induced
        needs-sync -> in-sync transitions are handled by
        ``_should_clear_alarm``."""
        if not current.needs_sync:
            return False
        if prior is None:
            return True
        return not prior.needs_sync

    @staticmethod
    def _should_clear_alarm( prior   : Optional[ SyncCheckResult ],
                             current : SyncCheckResult ) -> bool:
        """Resolution gate. Fires only on the needs-sync -> in-sync
        transition: prior reported needs-sync, AND current reports
        in-sync. No-prior -> in-sync needs no clear (no alert was
        queued). Sustained in-sync (in-sync -> in-sync) is a no-op,
        as is any transition that ends in needs-sync."""
        if current.needs_sync:
            return False
        if prior is None:
            return False
        return prior.needs_sync

    @classmethod
    def _needs_sync_alarm_signature( cls, integration_id : str ):
        """Single source of truth for the (source, type, level) identity
        of the needs-sync alarm, shared by the fire and clear paths so
        the clear is guaranteed to match what was queued."""
        return AlarmSignature(
            alarm_source = AlarmSource.INTEGRATION,
            alarm_type   = f'integrations.needs_sync.{integration_id}',
            alarm_level  = AlarmLevel.INFO,
        )

    @classmethod
    def _fire_needs_sync_alarm( cls,
                                integration_id : str,
                                result         : SyncCheckResult ) -> None:
        """Construct and queue an INFO-level alarm for a transition
        into the needs-sync state. Per-integration unique signature so
        two integrations both reporting drift surface as two distinct
        alerts. Lifetime is ``NAG_INTERVAL_SECS`` -- the post-ack
        suppression ceiling if the operator dismisses and the drift
        persists."""
        from hi.apps.alert.alarm import Alarm
        from hi.apps.alert.alert_manager import AlertManager
        from hi.apps.security.enums import SecurityLevel
        from hi.apps.sense.transient_models import SensorResponse

        from hi.integrations.transient_models import IntegrationKey

        signature = cls._needs_sync_alarm_signature( integration_id )
        alarm_integration_key = IntegrationKey(
            integration_id = 'integrations',
            integration_name = f'needs_sync.{integration_id}',
        )
        sensor_response = SensorResponse(
            integration_key = alarm_integration_key,
            value = 'NEEDS_SYNC',
            timestamp = result.last_checked_at,
            sensor = None,
            detail_attrs = {
                'Added'        : str( result.delta.added_count ),
                'Removed'      : str( result.delta.removed_count ),
                'Last Checked' : result.last_checked_at.strftime(
                    '%Y-%m-%d %H:%M:%S',
                ),
            },
            has_event_video_clip = False,
        )
        alarm = Alarm(
            alarm_source = signature.alarm_source,
            alarm_type = signature.alarm_type,
            alarm_level = signature.alarm_level,
            title = result.summary_message,
            sensor_response_list = [ sensor_response ],
            security_level = SecurityLevel.OFF,
            alarm_lifetime_secs = cls.NAG_INTERVAL_SECS,
            timestamp = datetimeproxy.now(),
        )
        AlertManager().upsert_alarm( alarm )

    @classmethod
    def _clear_needs_sync_alert( cls, integration_id : str ) -> None:
        """Drop any pending needs-sync alert for this integration so
        the operator's queue returns to clean immediately on
        convergence."""
        from hi.apps.alert.alert_manager import AlertManager
        signature = cls._needs_sync_alarm_signature( integration_id )
        AlertManager().clear_alarms( signature = signature )

    @classmethod
    def clear_state( cls, integration_id : str ) -> None:
        """Drop the cached state entirely. Used on integration removal;
        post-Refresh uses ``record_sync_complete`` instead so the UI
        keeps a "verified at HH:MM" indicator rather than going dark.
        """
        if not integration_id:
            return
        cache.delete( cls._cache_key( integration_id ) )
        logger.debug( f'sync-check state cleared for {integration_id}' )

    @classmethod
    def record_sync_complete( cls,
                              integration_id    : str,
                              integration_label : str ) -> None:
        """Called after a successful Refresh: the integration is by
        definition in sync, so we write a zero-delta result with a
        current timestamp. UI surfaces the verified state and the
        next probe cycle naturally re-confirms or detects new drift.
        """
        cls.set_state(
            integration_id = integration_id,
            result = cls.build_result(
                delta = SyncDelta(),
                integration_label = integration_label,
            ),
        )

    @classmethod
    def build_result( cls,
                      delta             : SyncDelta,
                      integration_label : str,
                      last_checked_at   : Optional[ datetime ] = None,
                      ) -> SyncCheckResult:
        """Wrap a ``SyncDelta`` into a ``SyncCheckResult`` with a
        sensible default summary message and timestamp. The framework
        monitor calls this with the delta returned from each
        synchronizer's ``check_needs_sync()``.
        """
        if last_checked_at is None:
            last_checked_at = datetimeproxy.now()
        return SyncCheckResult(
            delta = delta,
            last_checked_at = last_checked_at,
            summary_message = cls._summary_message(
                delta = delta,
                integration_label = integration_label,
            ),
        )

    @staticmethod
    def _summary_message( delta             : SyncDelta,
                          integration_label : str ) -> str:
        """Pure-information summary of the most recent check. The
        update-check call-to-action is rendered as a real link by
        the manage-page banner template (so clicking it opens the
        pre-sync modal); it is intentionally not embedded in this
        string. The same string flows into the sidebar tooltip,
        where a "click here" suffix would be misleading."""
        if not delta.needs_sync:
            return f'{integration_label} is up to date.'
        pieces = []
        if delta.added_count:
            noun = 'item' if delta.added_count == 1 else 'items'
            pieces.append( f'{delta.added_count} new {noun} upstream' )
        if delta.removed_count:
            noun = 'item' if delta.removed_count == 1 else 'items'
            pieces.append( f'{delta.removed_count} {noun} removed upstream' )
        return f'{integration_label}: {", ".join(pieces)}.'