Trigger support for HA 2025.7 release, performance optimizations, doc updates (#74)

- Enhance UniFi Network Rules integration with CQRS-style operation tracking and delayed verification
- Introduced a new mechanism in `coordinator.py` to track Home Assistant initiated operations, attempting to prevent redundant refreshes.
- Added delayed verification logic in `switch.py` to ensure state consistency after operations.
- Incremented version in `manifest.json` to 3.1.0 to reflect these enhancements.
- Revised the README.md to enhance clarity on integration features and usage, including a new section on advanced automations.
- Updated the features list to provide a more detailed overview of supported rules and configurations.
- Removed the `reset_rate_limit` service from services.yaml and its implementation in system_services.py to streamline functionality.
- Remove `reset_rate_limit` service from the integration to streamline functionality and improve code clarity. Updated related imports and constants accordingly.
- Revised the README.md to clarify the limitations of the automation UI and provide updated YAML configuration examples.
- Enhanced the trigger.py file by removing unused code and improving the validation process for trigger configurations.
- Incremented the version in manifest.json to 3.1.0 to reflect these updates.
- Modified trigger.py to handle asynchronous action execution more effectively, ensuring proper task scheduling.
- Enhanced logging for trigger events to improve debugging and monitoring capabilities.
- Updated the security monitoring section to clarify notification creation for firewall policy changes.
- Added a new automation example for handling UniFi policy changes with detailed notification messages.
- Revised the VPN connection monitoring section to include a specific client reconnection automation and improved messaging for connection status notifications.

Author: sirkirby

README.md

@@ -179,4 +179,5 @@
 
 # Rate limiting and delays
 MIN_REQUEST_INTERVAL = 2.0
-STATE_VERIFICATION_SLEEP_SECONDS = 2
+STATE_VERIFICATION_SLEEP_SECONDS = 2
+SWITCH_DELAYED_VERIFICATION_SLEEP_SECONDS = 20

custom_components/unifi_network_rules/const.py

@@ -84,6 +84,11 @@ def __init__(
         self._update_in_progress = False
         self._has_data = False
 
+        # --- CQRS-style Operation Tracking ---
+        # This tracks rule_ids for operations initiated within Home Assistant
+        # to prevent the trigger from causing a redundant refresh and to prevent a potential race condition
+        self._ha_initiated_operations: Dict[str, float] = {}
+        
         # Websocket processing is now handled by trigger system
 
         # Track entities we added or removed
@@ -123,6 +128,47 @@ def __init__(
         self._consecutive_errors = 0
         self._api_errors = 0
 
+    def register_ha_initiated_operation(self, rule_id: str, timeout: int = 15) -> None:
+        """Register that a rule change was initiated from HA.
+        
+        This is called by a switch entity just before it queues an API call.
+        The trigger system will check this to avoid a redundant refresh.
+        
+        Args:
+            rule_id: The ID of the rule being changed.
+            timeout: How long (in seconds) to keep the registration active.
+        """
+        self._ha_initiated_operations[rule_id] = time.time()
+        LOGGER.debug("[CQRS] Registered HA-initiated operation for rule_id: %s", rule_id)
+        
+        # Schedule cleanup to prevent the dictionary from growing indefinitely
+        # if a corresponding websocket event never arrives.
+        async def cleanup_op(op_rule_id):
+            await asyncio.sleep(timeout)
+            if op_rule_id in self._ha_initiated_operations:
+                del self._ha_initiated_operations[op_rule_id]
+                LOGGER.debug("[CQRS] Expired and removed HA-initiated operation for rule_id: %s", op_rule_id)
+
+        self.hass.async_create_task(cleanup_op(rule_id))
+        
+    def check_and_consume_ha_initiated_operation(self, rule_id: str) -> bool:
+        """Check if a rule change was HA-initiated and consume the flag.
+        
+        This is called by the trigger system before it decides to fire a
+        refresh, to see if the change was expected.
+        
+        Args:
+            rule_id: The ID of the rule that changed.
+            
+        Returns:
+            True if the operation was initiated from HA, False otherwise.
+        """
+        if rule_id in self._ha_initiated_operations:
+            LOGGER.debug("[CQRS] Consumed HA-initiated operation for rule_id: %s. Suppressing trigger refresh.", rule_id)
+            del self._ha_initiated_operations[rule_id]
+            return True
+        return False
+
     async def _async_update_data(self) -> Dict[str, List[Any]]:
         """Fetch data from API endpoint."""
         # Use a lock to prevent concurrent updates, especially during authentication

custom_components/unifi_network_rules/coordinator.py

@@ -15,5 +15,5 @@
         "aiounifi>=82.0.0",
         "orjson>=3.8.0"
     ],
-    "version": "3.0.1"
+    "version": "3.1.0"
 }

custom_components/unifi_network_rules/manifest.json

@@ -238,10 +238,6 @@ force_remove_stale:
       selector:
         boolean:
 
-reset_rate_limit:
-  name: Reset Rate Limit
-  description: Reset the rate limiter for the UniFi API connection
-
 websocket_diagnostics:
   name: WebSocket Diagnostics
   description: Run diagnostics on the WebSocket connection and attempt to repair if needed

custom_components/unifi_network_rules/services.yaml

@@ -28,7 +28,6 @@
 from .system_services import (
     async_setup_system_services,
     async_refresh_service,
-    async_reset_rate_limit,
     async_websocket_diagnostics,
 )
 from .cleanup_services import (
@@ -49,7 +48,6 @@
     SERVICE_SAVE_TEMPLATE,
     SERVICE_FORCE_CLEANUP,
     SERVICE_FORCE_REMOVE_STALE,
-    SERVICE_RESET_RATE_LIMIT,
     SERVICE_WEBSOCKET_DIAGNOSTICS,
     SERVICE_TOGGLE_RULE,
 )
@@ -105,7 +103,6 @@ async def async_unload_services(hass: HomeAssistant) -> None:
         SERVICE_SAVE_TEMPLATE,
         SERVICE_FORCE_CLEANUP,
         SERVICE_FORCE_REMOVE_STALE,
-        SERVICE_RESET_RATE_LIMIT,
         SERVICE_WEBSOCKET_DIAGNOSTICS
     ]
 

custom_components/unifi_network_rules/services/__init__.py

@@ -10,7 +10,6 @@
 SERVICE_SAVE_TEMPLATE = "save_template"
 SERVICE_FORCE_CLEANUP = "force_cleanup"
 SERVICE_FORCE_REMOVE_STALE = "force_remove_stale"
-SERVICE_RESET_RATE_LIMIT = "reset_rate_limit"
 SERVICE_WEBSOCKET_DIAGNOSTICS = "websocket_diagnostics"
 SERVICE_TOGGLE_RULE = "toggle_rule"
 SERVICE_REFRESH_DATA = "refresh_data"

custom_components/unifi_network_rules/services/constants.py

@@ -14,7 +14,6 @@
 from .constants import (
     SERVICE_REFRESH,
     SERVICE_REFRESH_DATA,
-    SERVICE_RESET_RATE_LIMIT,
     SERVICE_WEBSOCKET_DIAGNOSTICS,
 )
 
@@ -49,22 +48,6 @@ async def async_refresh_data(hass: HomeAssistant, coordinators: Dict, call: Serv
             LOGGER.debug("Refreshing coordinator for entry %s", entry_id)
             await coordinator.async_refresh()
 
-async def async_reset_rate_limit(hass: HomeAssistant, coordinators: Dict, call: ServiceCall) -> None:
-    """Handle reset rate limit service call."""
-    # Reset rate limit for all APIs
-    for entry_data in hass.data[DOMAIN].values():
-        if "api" in entry_data:
-            api = entry_data["api"]
-            if hasattr(api, "reset_rate_limit"):
-                try:
-                    success = await api.reset_rate_limit()
-                    if success:
-                        LOGGER.info("Rate limit reset successful")
-                    else:
-                        LOGGER.warning("Rate limit reset failed")
-                except Exception as e:
-                    LOGGER.error("Error resetting rate limit: %s", e)
-
 async def async_websocket_diagnostics(hass: HomeAssistant, coordinators: Dict, call: ServiceCall) -> None:
     """Run diagnostics on WebSocket connections and try to repair if needed."""
     results = {}
@@ -213,10 +196,6 @@ async def handle_refresh(call: ServiceCall) -> None:
     async def handle_refresh_data(call: ServiceCall) -> None:
         await async_refresh_data(hass, coordinators, call)
 
-    # Handle the reset rate limit service  
-    async def handle_reset_rate_limit(call: ServiceCall) -> None:
-        await async_reset_rate_limit(hass, coordinators, call)
-        
     # Handle the websocket diagnostics service
     async def handle_websocket_diagnostics(call: ServiceCall) -> None:
         return await async_websocket_diagnostics(hass, coordinators, call)
@@ -230,10 +209,6 @@ async def handle_websocket_diagnostics(call: ServiceCall) -> None:
         DOMAIN, SERVICE_REFRESH_DATA, handle_refresh_data, schema=REFRESH_DATA_SCHEMA
     )
 
-    hass.services.async_register(
-        DOMAIN, SERVICE_RESET_RATE_LIMIT, handle_reset_rate_limit, schema=vol.Schema({})
-    )
-    
     hass.services.async_register(
         DOMAIN, SERVICE_WEBSOCKET_DIAGNOSTICS, handle_websocket_diagnostics, schema=vol.Schema({})
     ) 

custom_components/unifi_network_rules/services/system_services.py

@@ -30,7 +30,7 @@
 from aiounifi.models.wlan import Wlan
 from aiounifi.models.device import Device  # For LED toggle
 
-from .const import DOMAIN, MANUFACTURER
+from .const import DOMAIN, MANUFACTURER, SWITCH_DELAYED_VERIFICATION_SLEEP_SECONDS
 from .helpers.rule import sanitize_entity_id
 from .coordinator import UnifiRuleUpdateCoordinator
 from .helpers.rule import (
@@ -708,13 +708,14 @@ async def _async_toggle_rule(self, enable: bool) -> None:
         LOGGER.debug("Adding rule %s to pending operations queue with target state: %s", 
                    self._rule_id, enable)
 
+        # Register the operation with the coordinator to prevent redundant refreshes.
+        self.coordinator.register_ha_initiated_operation(self._rule_id)
+        
         # Define callback to handle operation completion
         async def handle_operation_complete(future):
             """Handle operation completion."""
             try:
                 success = future.result()
-                LOGGER.debug("Operation completed for rule %s with result: %s", 
-                            self._rule_id, success)
 
                 if not success:
                     # Revert optimistic state if failed
@@ -726,25 +727,23 @@ async def handle_operation_complete(future):
                     # On success, refresh the optimistic state timestamp to prevent premature clearing
                     self._optimistic_timestamp = time.time()
                     self.async_write_ha_state()
-                
-                # Request refresh to update state from backend
-                await self.coordinator.async_request_refresh()
-                
-                # Improve rapid toggling experience by reducing delay and adding direct updates
-                if success:
-                    async def delayed_verify():
-                        # Reduced wait time for faster feedback
-                        await asyncio.sleep(1)  # Reduced from 2 seconds
-                        # Request refresh first
-                        await self.coordinator.async_request_refresh()
-                        # Force a state update immediately after refresh
-                        self.async_write_ha_state()
-                        # Also notify on a dispatcher channel for anyone listening
-                        from homeassistant.helpers.dispatcher import async_dispatcher_send
-                        async_dispatcher_send(self.hass, f"{DOMAIN}_entity_update_{self._rule_id}")
-                        LOGGER.debug("Performed verification refresh for rule %s", self._rule_id)
+
+                    # --- Smart Verification Task ---
+                    # This task acts as a safety net. It waits a few seconds and then checks
+                    # if the change was confirmed by the trigger system (which consumes the
+                    # HA-initiated operation flag). If not, it forces a refresh.
+                    async def delayed_verification():
+                        await asyncio.sleep(SWITCH_DELAYED_VERIFICATION_SLEEP_SECONDS) # Wait 7 seconds for websocket event
+                        if self.coordinator.check_and_consume_ha_initiated_operation(self._rule_id):
+                            # If the flag was still present, it means the trigger system
+                            # did NOT get a websocket event. We must refresh.
+                            LOGGER.warning("Delayed verification: Trigger did not receive websocket event for %s. Forcing refresh.", self._rule_id)
+                            await self.coordinator.async_request_refresh()
+                        else:
+                            # The flag was already consumed, so the trigger worked correctly.
+                            LOGGER.debug("Delayed verification: Trigger confirmed change for %s. No refresh needed.", self._rule_id)
 
-                    asyncio.create_task(delayed_verify())
+                    self.hass.async_create_task(delayed_verification())
 
             except Exception as err:
                 # Check if this is an auth error
@@ -1423,6 +1422,9 @@ async def _async_toggle_rule(self, enable: bool) -> None:
             kill_switch_operation_id = f"{self._rule_id}_kill_switch"
             self.coordinator._pending_operations[kill_switch_operation_id] = enable
 
+        # Register the operation with the coordinator to prevent redundant refreshes.
+        self.coordinator.register_ha_initiated_operation(self._rule_id)
+        
         # Queue the toggle operation
         try:
             # Get the toggle function from the API client
@@ -1437,8 +1439,18 @@ async def handle_operation_complete(future):
                     result = future.result()
                     if result:
                         LOGGER.debug("Successfully toggled kill switch for %s", self.name)
-                        # Request a data update
-                        await self.coordinator.async_request_refresh()
+                        # --- Smart Verification Task ---
+                        # See parent class for detailed explanation of this safety net.
+                        async def delayed_verification():
+                            await asyncio.sleep(SWITCH_DELAYED_VERIFICATION_SLEEP_SECONDS)
+                            kill_switch_id = self._rule_id # The unique ID for the kill switch
+                            if self.coordinator.check_and_consume_ha_initiated_operation(kill_switch_id):
+                                LOGGER.warning("Delayed verification for kill switch %s failed. Forcing refresh.", kill_switch_id)
+                                await self.coordinator.async_request_refresh()
+                            else:
+                                LOGGER.debug("Delayed verification for kill switch %s confirmed.", kill_switch_id)
+
+                        self.hass.async_create_task(delayed_verification())
                     else:
                         LOGGER.error("Failed to toggle kill switch for %s", self.name)
                         # Revert optimistic state on failure