Override Liveness timeout on shutdown

Override the liveness timeout when a node announces a shutdown. This
causes the subscription to fail quickly. Set the timeout to 0 soon
after. Setting to 0 causes the SDK to use the default liveness timeout
from the next (successful) subscription onwards again.

Another alternative would be to shutdown the subscription (mark the
device as offline). This has the disadvantage that the device needs
to recreate the subscription from scratch when it comes back, which
causes unnecessary traffic.

If the node stays offline for longer than 30s, we'll still trigger
the offline logic which will shutdown the subscription entirely

Author: agners

matter_server/server/device_controller.py

@@ -77,6 +77,7 @@
 NODE_SUBSCRIPTION_CEILING_BATTERY_POWERED = 600
 NODE_RESUBSCRIBE_ATTEMPTS_UNAVAILABLE = 3
 NODE_RESUBSCRIBE_TIMEOUT_OFFLINE = 30 * 60 * 1000
+NODE_RESUBSCRIBE_FORCE_TIMEOUT = 5
 NODE_PING_TIMEOUT = 10
 NODE_PING_TIMEOUT_BATTERY_POWERED = 60
 NODE_MDNS_BACKOFF = 610  # must be higher than (highest) sub ceiling
@@ -1109,7 +1110,10 @@ def event_callback(
             self.event_history.append(node_event)
 
             if isinstance(data.Data, Clusters.BasicInformation.Events.ShutDown):
-                self._node_unavailable(node_id)
+                # Force resubscription after a shutdown event. Otherwise we'd have to
+                # wait for up to NODE_SUBSCRIPTION_CEILING_BATTERY_POWERED minutes for
+                # the SDK to notice the device is gone.
+                self._node_unavailable(node_id, True)
 
             self.server.signal_event(EventType.NODE_EVENT, node_event)
 
@@ -1490,15 +1494,40 @@ def _write_node_state(self, node_id: int, force: bool = False) -> None:
             force=force,
         )
 
-    def _node_unavailable(self, node_id: int) -> None:
+    def _node_unavailable(
+        self, node_id: int, force_resubscription: bool = False
+    ) -> None:
         """Mark node as unavailable."""
         # mark node as unavailable (if it wasn't already)
         node = self._nodes[node_id]
         if not node.available:
             return
         node.available = False
         self.server.signal_event(EventType.NODE_UPDATED, node)
-        LOGGER.info("Marked node %s as unavailable", node_id)
+        node_logger = LOGGER.getChild(f"node_{node_id}")
+        node_logger.info("Marked node as unavailable")
+        if force_resubscription:
+            # Make sure the subscriptions are expiring very soon to trigger subscription
+            # resumption logic quickly. This is especially important for battery operated
+            # devices so subscription resumption logic kicks in quickly.
+            node_logger.info(
+                "Forcing subscription timeout in %ds", NODE_RESUBSCRIBE_FORCE_TIMEOUT
+            )
+            asyncio.create_task(
+                self._chip_device_controller.subscription_override_liveness_timeout(
+                    node_id, NODE_RESUBSCRIBE_FORCE_TIMEOUT * 1000
+                )
+            )
+            # Clear the timeout soon after the scheduled timeout above. For future
+            # subscriptions we want to use the default timeout again.
+            self._loop.call_later(
+                NODE_RESUBSCRIBE_FORCE_TIMEOUT + 1,
+                lambda: asyncio.create_task(
+                    self._chip_device_controller.subscription_override_liveness_timeout(
+                        node_id, 0
+                    )
+                ),
+            )
 
     async def _node_offline(self, node_id: int) -> None:
         """Mark node as offline."""
@@ -1510,7 +1539,8 @@ async def _node_offline(self, node_id: int) -> None:
             return  # nothing to do to
         node.available = False
         self.server.signal_event(EventType.NODE_UPDATED, node)
-        LOGGER.info("Marked node %s as offline", node_id)
+        node_logger = LOGGER.getChild(f"node_{node_id}")
+        node_logger.info("Marked node as offline")
 
     async def _fallback_node_scanner(self) -> None:
         """Scan for operational nodes in the background that are missed by mdns."""

matter_server/server/sdk.py

@@ -395,6 +395,13 @@ async def shutdown_subscription(self, node_id: int) -> None:
         if sub := self._subscriptions.pop(node_id, None):
             await self._call_sdk(sub.Shutdown)
 
+    async def subscription_override_liveness_timeout(
+        self, node_id: int, liveness_timeout_ms: int
+    ) -> None:
+        """Override the liveness timeout for the subscription of the node."""
+        if sub := self._subscriptions.get(node_id, None):
+            await self._call_sdk(sub.OverrideLivenessTimeoutMs, liveness_timeout_ms)
+
     def node_has_subscription(self, node_id: int) -> bool:
         """Check if a node has an active subscription."""
         return node_id in self._subscriptions