Skip to content

Home Information - Your home, your data, organized.

Python
6.5 KB
Raw Blame
import logging
import threading
from typing import Any, Dict, Optional

from asgiref.sync import sync_to_async

from hi.apps.common.singleton import Singleton
from hi.apps.control.models import Controller
from hi.apps.entity.models import EntityState
from hi.apps.sense.models import Sensor

from .transient_models import IntegrationKey

logger = logging.getLogger(__name__)


class IntegrationMetadataCache( Singleton ):
    """Process-wide, lazily-warmed cache of EntityState metadata that
    integration converters need at value-translation time.

    Polling loops are hot paths and the inbound/outbound converters need
    per-entity metadata on every call. Caching avoids per-call DB queries;
    the underlying fields are set at creation and rarely change, so a
    process-lifetime cache with no active invalidation is the right
    trade-off -- the workaround for the rare edit is a process restart.

    Keyed by ``IntegrationKey``; each entry is a dict with a ``units`` key
    (the EntityState.units string, or None when the EntityState has no
    units).

    Concurrency: bulk-warmup and lazy single-row fills take the write
    lock; reads of an already-populated entry are unlocked (CPython dict
    reads are atomic for our access pattern).
    """

    def __init_singleton__(self):
        self._cache : Dict[ IntegrationKey, Dict[str, Any] ] = {}
        self._lock = threading.Lock()
        self._warmed = False
        return

    def get_entry(
            self, integration_key : IntegrationKey,
    ) -> Dict[str, Any]:
        """Return the cached metadata dict for ``integration_key``. Triggers
        a single bulk warmup on first use; entities created after warmup are
        filled lazily on miss. Sync API -- use ``get_entry_async`` from async
        contexts to avoid Django's SynchronousOnlyOperation guard."""
        if not self._warmed:
            self._warmup()
        entry = self._cache.get( integration_key )
        if entry is not None:
            return entry
        return self._lazy_fill( integration_key )

    async def get_entry_async(
            self, integration_key : IntegrationKey,
    ) -> Dict[str, Any]:
        """Async variant of ``get_entry``. After warmup, reads are pure-Python
        dict accesses and the sync_to_async hop is essentially free; before
        warm and on lazy-fill misses, the DB lookup happens in a thread pool
        so it's safe to call from async contexts."""
        if self._warmed and integration_key in self._cache:
            return self._cache[ integration_key ]
        return await sync_to_async(
            self.get_entry, thread_sensitive=True,
        )( integration_key )

    def _warmup(self):
        """One-shot bulk load of every known integration_key.

        Assumes any Sensor/Controller pair sharing an
        ``integration_key`` references the same EntityState (enforced
        by ``HiModelHelper``; ``integration_id`` namespacing prevents
        cross-integration collisions). Sensor entries win on overlap;
        a warning fires if the Controller's entry would have
        disagreed -- canary for invariant violations."""
        with self._lock:
            if self._warmed:
                return
            for sensor in Sensor.objects.select_related( 'entity_state' ).all():
                key = sensor.integration_key
                if key is None:
                    continue
                self._cache[ key ] = self._build_entry( sensor.entity_state )
            for controller in Controller.objects.select_related( 'entity_state' ).all():
                key = controller.integration_key
                if key is None:
                    continue
                controller_entry = self._build_entry( controller.entity_state )
                existing = self._cache.get( key )
                if existing is None:
                    self._cache[ key ] = controller_entry
                    continue
                if existing != controller_entry:
                    logger.warning(
                        f'IntegrationMetadataCache invariant violated for '
                        f'{key}: divergent Sensor/Controller metadata '
                        f'({existing} vs {controller_entry}). See class docs.'
                    )
            self._warmed = True

    def invalidate(self):
        """Drop all cached entries and reset the warmup flag. The next
        ``get_entry`` triggers a fresh bulk warmup. Call after any operation
        that creates, refreshes, or removes EntityStates with integration_keys.

        Necessary because ``_lazy_fill`` caches ``{'units': None}`` on miss to
        keep the polling-loop hot path free of repeat DB queries. Without
        invalidation, a poll that races an in-progress import pins a bad entry
        for the lifetime of the process -- visible as raw, unconverted values
        for any new unit-bearing EntityState (a wrong-by-~88F temperature
        reading, most obviously)."""
        with self._lock:
            self._cache.clear()
            self._warmed = False

    def _lazy_fill(
            self, integration_key : IntegrationKey,
    ) -> Dict[str, Any]:
        """Single-row fill on a post-warmup miss (entity created
        after warmup). Falls back to an empty entry when the key
        resolves to nothing so subsequent misses don't re-query."""
        entity_state = self._lookup_entity_state( integration_key )
        entry = (
            self._build_entry( entity_state )
            if entity_state is not None
            else { 'units': None }
        )
        with self._lock:
            self._cache.setdefault( integration_key, entry )
        return self._cache[ integration_key ]

    @staticmethod
    def _lookup_entity_state(
            integration_key : IntegrationKey,
    ) -> Optional[ EntityState ]:
        try:
            return Sensor.objects.select_related( 'entity_state' ).get(
                integration_id = integration_key.integration_id,
                integration_name = integration_key.integration_name,
            ).entity_state
        except Sensor.DoesNotExist:
            pass
        try:
            return Controller.objects.select_related( 'entity_state' ).get(
                integration_id = integration_key.integration_id,
                integration_name = integration_key.integration_name,
            ).entity_state
        except Controller.DoesNotExist:
            return None

    @staticmethod
    def _build_entry( entity_state : EntityState ) -> Dict[str, Any]:
        return {
            'units': entity_state.units or None,
        }