Skip to content

Home Information - Your home, your data, organized.

Python
15.9 KB
Raw Blame
"""
Operations on entities with respect to their integration attachment.

This module holds mutating operations (disconnect, preserve, detach) that
act on Entity instances relative to the integration that owns them. These
are distinct from the read-only analytical methods on EntityUserDataDetector.

EventDefinition cleanup is integration-scoped: only EventDefinition rows
whose own ``integration_id`` matches are removed; user-owned EventDefinitions
referencing the entity's states are intentionally left alone. See
``EventDefinitionOperations`` for the full policy.
"""

import logging
from typing import Dict, Iterable, List, Optional, Set

from django.db import transaction

from hi.apps.attribute.enums import AttributeType
from hi.apps.entity.models import Entity, EntityState, EntityStateDelegation
from hi.apps.sense.models import Sensor
from hi.apps.control.models import Controller

from hi.integrations.event_definition_operations import EventDefinitionOperations
from hi.integrations.transient_models import IntegrationKey, IntegrationRemovalSummary

from hi.integrations.connector.sync_result import IntegrationSyncResult
from hi.integrations.connector.user_data_detector import EntityUserDataDetector

logger = logging.getLogger(__name__)


class EntityIntegrationOperations:

    @staticmethod
    def collect_removal_closure( initial_entity_ids : Iterable[int] ) -> Set[int]:
        """
        Expand a set of entity IDs to include delegate entities that would
        be orphaned by the removal.

        Pure graph operation over EntityStateDelegation:

          - From each entity already in the closure, find delegates reached
            via that entity's EntityStates' delegations.
          - A delegate is added only when *every* entity that delegates to
            it is already in the closure (otherwise the delegate is still
            serving a non-removed entity and must remain).
          - Iterates until no new entities are added (handles chained and
            diamond-shaped delegations; cycles are bounded by the visited set).

        This function is integration-agnostic -- callers pass whatever seed
        set defines the explicit removal scope.
        """
        closure : Set[int] = set(initial_entity_ids)
        if not closure:
            return closure

        while True:
            candidate_ids = set(
                EntityStateDelegation.objects.filter(
                    entity_state__entity_id__in = closure,
                ).exclude(
                    delegate_entity_id__in = closure,
                ).values_list( 'delegate_entity_id', flat = True )
            )
            if not candidate_ids:
                break

            # Bulk-query then group in Python to avoid O(passes x candidates) DB hits.
            principals_by_candidate : Dict[int, Set[int]] = {}
            for delegate_id, principal_id in EntityStateDelegation.objects.filter(
                    delegate_entity_id__in = candidate_ids,
            ).values_list( 'delegate_entity_id', 'entity_state__entity_id' ):
                principals_by_candidate.setdefault( delegate_id, set() ).add( principal_id )

            added_this_pass = {
                candidate_id
                for candidate_id, principal_ids in principals_by_candidate.items()
                if principal_ids and principal_ids.issubset( closure )
            }

            if not added_this_pass:
                break
            closure |= added_this_pass

        return closure

    @staticmethod
    def get_removal_entity_ids( integration_id : str ) -> Set[int]:
        """
        Return the full set of entity IDs that a Remove of the given
        integration should target: every actively-attached
        (EXTERNAL) entity for the integration, plus any delegate
        entities that would be orphaned by their removal. Imported /
        detached rows for the same integration are HI-owned and
        outside the removal scope.
        """
        seed = set(
            Entity.objects.external_for(
                integration_id = integration_id,
            ).values_list( 'id', flat = True )
        )
        return EntityIntegrationOperations.collect_removal_closure( seed )

    @classmethod
    def remove_entities_with_closure(
            cls,
            seed_entity_ids    : Iterable[int],
            integration_name   : str,
            preserve_user_data : bool                              = True,
            result             : Optional[IntegrationSyncResult]   = None ):
        """Canonical removal for integration-owned entities.

        Walks ``collect_removal_closure(seed_entity_ids)`` so every delegate
        entity that would be orphaned by the removal (e.g., the Area
        auto-created when a camera was placed in a view) is included. Each
        entity in the closure is handled per ``preserve_user_data``:

          * ``True`` (SAFE pattern): entities carrying operator-added
            attributes are detached from the integration (active integration
            identity cleared, previous identity recorded for the auto-
            reconnect path); others are hard-deleted.

          * ``False`` (DELETE ALL pattern): every entity in the closure is
            hard-deleted, including those with user-added data.

        When ``result`` is provided, each closure entity's name is appended
        to either ``result.removed_list`` (hard-delete branch) or
        ``result.detached_list`` (preserve branch) -- never both. The
        preserve branch also adds its diagnostic note to ``result.info_list``.

        Each entity in the closure is classified by its *own* user data,
        independent of the seed's classification. This produces the right
        outcome in the camera-preserved / Area-no-user-data corner: an
        auto-created Area's display purpose depends on the principal's live
        state, which the preserve path removes -- so deleting the
        now-purposeless Area is correct even when its principal is being kept.
        """
        closure_ids = cls.collect_removal_closure( seed_entity_ids )
        for entity in Entity.objects.filter( id__in = closure_ids ):
            if preserve_user_data and EntityUserDataDetector.has_user_created_attributes( entity ):
                # preserve_with_user_data appends to result.detached_list
                # itself; nothing to record here on this branch.
                cls.preserve_with_user_data(
                    entity = entity,
                    integration_name = integration_name,
                    result = result,
                )
            else:
                if result is not None:
                    result.removed_list.append( entity.name )
                # Django's DB-level CASCADE from Entity.delete() reaches
                # EventClause / ControlAction (the children) but stops
                # there -- the parent EventDefinition row is never
                # touched. Delete integration-owned EventDefinitions
                # for this entity first, then let CASCADE handle the
                # rest of the entity graph.
                EventDefinitionOperations.delete_for_entity( entity )
                entity.delete()
        return

    @staticmethod
    def summarize_for_removal( integration_id : str ) -> IntegrationRemovalSummary:
        """
        Classify the entities attached to the integration: total (including
        orphan-after-removal delegates) and how many carry user-created data.
        Used to populate the policy choice in the operator confirmation
        dialogs (retain user-data items vs delete).

        This is a policy classification, not the actual dropped set. For
        Refresh, the dropped set is decided at sync execution against fresh
        upstream -- the operator's choice expresses the policy that applies
        if drops include user-data items.
        """
        target_ids = EntityIntegrationOperations.get_removal_entity_ids(
            integration_id = integration_id,
        )
        total_count = 0
        user_data_count = 0
        for entity in Entity.objects.filter( id__in = target_ids ):
            total_count += 1
            if EntityUserDataDetector.has_user_created_attributes( entity ):
                user_data_count += 1
        return IntegrationRemovalSummary(
            total_count = total_count,
            user_data_count = user_data_count,
        )

    @classmethod
    def find_reconnect_candidates(
            cls,
            integration_id : str,
            upstream_keys  : Iterable[ IntegrationKey ],
            result         : Optional[ IntegrationSyncResult ] = None,
    ) -> Dict[ IntegrationKey, Entity ]:
        """
        Auto-reconnect candidate lookup. Pure read.

        Given a set of upstream IntegrationKeys that the synchronizer's
        primary-match step did NOT match, return a map of
        ``upstream_key -> matching disconnected entity`` for every key that
        uniquely aligns with a disconnected entity's
        ``previous_integration_id`` / ``previous_integration_name``.

        Ambiguous matches (multiple disconnected entities sharing the same
        previous identity) are dropped from the result map; the contract is
        to leave the duplicate for the user to resolve via merge, since the
        system has no basis to pick one side over the other. A WARNING is
        logged and a breadcrumb is appended to ``result.info_list`` (when
        provided) for each ambiguous case.

        The per-entity reconnect mutations and converter dispatch are
        deliberately not performed here -- each integration's converter has a
        different signature and callers also want to enrich ``result`` with
        their own messages.

        Single batched DB query -- O(1) round trips regardless of how many
        upstream keys are passed.
        """
        upstream_keys = list( upstream_keys )
        if not upstream_keys:
            return {}

        upstream_keys_by_name : Dict[ str, IntegrationKey ] = {
            key.integration_name: key for key in upstream_keys
        }

        candidate_entities = Entity.objects.detached_for(
            integration_id = integration_id,
        ).filter(
            previous_integration_name__in = list( upstream_keys_by_name.keys() ),
        )

        candidates_by_name : Dict[ str, List[ Entity ] ] = {}
        for entity in candidate_entities:
            candidates_by_name.setdefault(
                entity.previous_integration_name, [],
            ).append( entity )

        reconnect_map : Dict[ IntegrationKey, Entity ] = {}
        for previous_name, entities in candidates_by_name.items():
            upstream_key = upstream_keys_by_name.get( previous_name )
            # Defensive: the IN-filter guarantees previous_name is in
            # the dict, but a corrupted row could slip through.
            if upstream_key is None:
                continue

            if len( entities ) > 1:
                ambiguity_message = (
                    f'Auto-reconnect skipped for {integration_id} item '
                    f'"{previous_name}": {len(entities)} disconnected '
                    f'entities share that previous identity. Resolve via '
                    f'merge.'
                )
                logger.warning( ambiguity_message )
                if result is not None:
                    result.info_list.append( ambiguity_message )
                continue

            reconnect_map[ upstream_key ] = entities[0]

        return reconnect_map

    @staticmethod
    def preserve_with_user_data( entity           : Entity,
                                 integration_name : str,
                                 result           : Optional[IntegrationSyncResult] = None ):
        """
        Preserve an entity with user-created data by disconnecting it from
        its integration and removing only integration-related components
        (sensors, controllers, orphaned states, integration-owned attributes,
        integration-owned EventDefinitions). The entity's previous integration
        identity is recorded on the entity so the auto-reconnect path can
        recognize it if the same upstream key reappears later. The detached
        state is signaled structurally: ``integration_id`` becomes NULL and
        ``previous_integration_id`` carries the prior identity.

        Integration-owned EventDefinitions are deleted first inside the atomic
        block, before the entity-state and controller deletions that would
        otherwise leave dangling parent rows (CASCADE reaches the children but
        not the parents). User-owned EventDefinitions (``integration_id IS NULL``)
        referencing this entity's states are intentionally NOT touched.

        Args:
            entity: The Entity to preserve.
            integration_name: Name of the integration (used in result messages).
            result: Optional IntegrationSyncResult to append a status
                message to.
        """
        original_name = entity.name

        sensor_ids_to_remove = EntityUserDataDetector.get_integration_related_sensors(entity)
        controller_ids_to_remove = EntityUserDataDetector.get_integration_related_controllers(entity)

        orphaned_state_ids = EntityUserDataDetector.get_orphaned_entity_states(
            entity, sensor_ids_to_remove, controller_ids_to_remove
        )

        with transaction.atomic():
            EventDefinitionOperations.delete_for_entity( entity )

            if sensor_ids_to_remove:
                removed_sensor_count = Sensor.objects.filter(
                    id__in=sensor_ids_to_remove
                ).delete()[0]
                logger.debug(f'Removed {removed_sensor_count} integration sensors for {entity}')

            if controller_ids_to_remove:
                removed_controller_count = Controller.objects.filter(
                    id__in=controller_ids_to_remove
                ).delete()[0]
                logger.debug(f'Removed {removed_controller_count} integration controllers for {entity}')

            if orphaned_state_ids:
                removed_state_count = EntityState.objects.filter(
                    id__in=orphaned_state_ids
                ).delete()[0]
                logger.debug(f'Removed {removed_state_count} orphaned entity states for {entity}')

            # Drop integration-created attributes, keep user-added ones. Provenance
            # is in attribute_type_str: PREDEFINED is system-created, CUSTOM is
            # user-added. queryset.delete() intentionally bypasses the
            # SoftDeleteAttributeModel.delete() override -- integration attributes
            # should not accumulate as soft-deleted rows.
            removed_attr_count = entity.attributes.exclude(
                attribute_type_str=str(AttributeType.CUSTOM),
            ).delete()[0]
            if removed_attr_count:
                logger.debug(f'Removed {removed_attr_count} integration attributes for {entity}')

            entity.previous_integration_key = entity.integration_key
            entity.integration_key = None

            # Restore user-management flags. Integration converters typically set
            # these to False to lock the entity against user changes; on detach
            # the entity is no longer integration-managed.
            entity.can_user_delete = True
            entity.allow_internal_attributes = True

            # has_video_stream: the backing sensor was deleted, so the capability
            # is genuinely lost. is_disabled: the general capability gate that
            # keeps a detached entity out of capability-driven enumerations.
            entity.has_video_stream = False
            entity.is_disabled = True

            entity.save()

        if result is not None:
            # detached_list surfaces in the operator-visible summary;
            # info_list carries the diagnostic note for the details view.
            result.detached_list.append( entity.name )
            result.info_list.append(
                f'Preserved {integration_name} item "{original_name}" with user data; '
                f'detached from integration.'
            )