Debounce disconnect state to suppress button flicker

When the browser WebSocket drops and reconnects within 8 seconds,
on_all_browsers_disconnected() is now suppressed — preventing the
brief red stop-icon flash on mic/camera buttons during active calls.

Author: stephen-tatari

streamdeck-plugin/src/browser_websocket_server.py

@@ -9,6 +9,8 @@
 
 
 class BrowserWebsocketServer:
+    DISCONNECT_NOTIFY_DELAY_SECONDS = 8.0
+
     """
     The BrowserWebsocketServer manages our connection to our browser extension,
     brokering messages between Google Meet and our plugin's EventHandler.
@@ -22,12 +24,17 @@ class BrowserWebsocketServer:
     websockets hanging around, or if we have multiple Meet tabs.
     """
 
-    def __init__(self):
+    def __init__(self, disconnect_notify_delay_seconds: float | None = None):
         """
         Remember to call start() before attempting to use your new instance!
         """
 
         self._logger = logging.getLogger(__name__)
+        self._disconnect_notify_delay_seconds = (
+            disconnect_notify_delay_seconds
+            if disconnect_notify_delay_seconds is not None
+            else self.DISCONNECT_NOTIFY_DELAY_SECONDS
+        )
 
         """
         Store all of the connected sockets we have open to the browser extension,
@@ -40,6 +47,7 @@ def __init__(self):
         Any EventHandlers registered to receive inbound events from the browser extension.
         """
         self._handlers: List["EventHandler"] = []
+        self._disconnect_notify_task: asyncio.Task | None = None
 
     async def start(self, hostname: str, port: int) -> websockets.Server:
         return await websockets.serve(self._message_receive_loop, hostname, port)
@@ -70,6 +78,7 @@ def num_connected_clients(self) -> int:
         return len(self._ws_clients)
 
     def _register_client(self, ws: websockets.ServerConnection) -> None:
+        self._cancel_disconnect_notification()
         self._ws_clients.add(ws)
         self._logger.info(
             (f"{ws.remote_address} has connected to our browser websocket."
@@ -113,12 +122,51 @@ async def _message_receive_loop(self, ws: websockets.ServerConnection) -> None:
             await self._unregister_client(ws)
 
         if not self._ws_clients:
+            self._schedule_disconnect_notification()
+
+    def _schedule_disconnect_notification(self) -> None:
+        if self._disconnect_notify_task and not self._disconnect_notify_task.done():
+            return
+
+        self._logger.info(
+            ("Scheduling browser disconnect notification in"
+             f" {self._disconnect_notify_delay_seconds} seconds."))
+        self._disconnect_notify_task = asyncio.create_task(
+            self._notify_all_browsers_disconnected_after_delay())
+
+    def _cancel_disconnect_notification(self) -> None:
+        if not self._disconnect_notify_task:
+            return
+
+        if self._disconnect_notify_task.done():
+            self._disconnect_notify_task = None
+            return
+
+        self._logger.info(
+            ("Cancelled pending browser disconnect notification because a"
+             " browser client connected."))
+        self._disconnect_notify_task.cancel()
+        self._disconnect_notify_task = None
+
+    async def _notify_all_browsers_disconnected_after_delay(self) -> None:
+        current_task = asyncio.current_task()
+
+        try:
+            await asyncio.sleep(self._disconnect_notify_delay_seconds)
+            self._logger.info(
+                ("Browser disconnect notification fired after"
+                 f" {self._disconnect_notify_delay_seconds} seconds."))
             for handler in self._handlers:
                 try:
                     await handler.on_all_browsers_disconnected()
                 except Exception:
                     self._logger.exception(
                         "Connection mananger received an exception from EventHandler!")
+        except asyncio.CancelledError:
+            raise
+        finally:
+            if self._disconnect_notify_task is current_task:
+                self._disconnect_notify_task = None
 
     async def _process_inbound_message(self, message: str | bytes) -> None:
         """

streamdeck-plugin/tests/test_browser_websocket_server.py

@@ -1,9 +1,29 @@
+import asyncio
 from unittest import IsolatedAsyncioTestCase
 from unittest.mock import AsyncMock, MagicMock, call
 
 from src.browser_websocket_server import BrowserWebsocketServer
 
 
+class BlockingWebsocket:
+
+    def __init__(self):
+        self.close = AsyncMock()
+        self.remote_address = ("127.0.0.1", 9999)
+        self._disconnect_event = asyncio.Event()
+
+    def disconnect(self):
+        self._disconnect_event.set()
+
+    def __aiter__(self):
+        return self._message_iterator()
+
+    async def _message_iterator(self):
+        await self._disconnect_event.wait()
+        if False:
+            yield "unused"
+
+
 class BrowserWebsocketServerTests(IsolatedAsyncioTestCase):
 
     async def test_handler_registration(self):
@@ -60,19 +80,23 @@ async def test_sockets_gracefully_closed(self):
 
         mock_websocket.close.assert_called_once()
 
-    async def test_browser_disconnected_callback_called(self):
+    async def test_browser_disconnected_callback_called_after_delay(self):
         """
         Test that our EventHandler's on_all_browsers_disconnected is called
-        once there are no connected clients.
+        once there are no connected clients for the full debounce window.
         """
         event_handler = AsyncMock()
-        server = BrowserWebsocketServer()
+        server = BrowserWebsocketServer(disconnect_notify_delay_seconds=0.01)
         server.register_event_handler(event_handler)
         mock_websocket = AsyncMock()
 
         await server._message_receive_loop(mock_websocket)
+        event_handler.on_all_browsers_disconnected.assert_not_called()
+
+        await asyncio.sleep(0.02)
 
         event_handler.on_all_browsers_disconnected.assert_called_with()
+        self.assertIsNone(server._disconnect_notify_task)
 
     async def test_browser_connected_callback_called(self):
         """
@@ -105,6 +129,54 @@ async def test_browser_disconnected_callback_not_called(self):
         event_handler.on_all_browsers_disconnected.assert_not_called()
         event_handler.on_browser_connected.assert_not_called()
 
+    async def test_transient_browser_disconnect_suppressed_within_window(self):
+        """
+        Test that transient websocket disconnects do not notify handlers when a
+        browser reconnects before the debounce window expires.
+        """
+        event_handler = AsyncMock()
+        server = BrowserWebsocketServer(disconnect_notify_delay_seconds=0.05)
+        server.register_event_handler(event_handler)
+
+        await server._message_receive_loop(AsyncMock())
+
+        blocking_websocket = BlockingWebsocket()
+        reconnect_task = asyncio.create_task(
+            server._message_receive_loop(blocking_websocket))
+        await asyncio.sleep(0.06)
+
+        event_handler.on_all_browsers_disconnected.assert_not_called()
+
+        blocking_websocket.disconnect()
+        await reconnect_task
+        server._disconnect_notify_task.cancel()
+        await asyncio.sleep(0)
+
+    async def test_disconnect_notification_task_cancelled_on_reconnect(self):
+        """
+        Test that a pending disconnect notification task is cancelled when a
+        new browser websocket reconnects within the debounce window.
+        """
+        server = BrowserWebsocketServer(disconnect_notify_delay_seconds=0.05)
+
+        await server._message_receive_loop(AsyncMock())
+        disconnect_notify_task = server._disconnect_notify_task
+        self.assertIsNotNone(disconnect_notify_task)
+        self.assertFalse(disconnect_notify_task.done())
+
+        blocking_websocket = BlockingWebsocket()
+        reconnect_task = asyncio.create_task(
+            server._message_receive_loop(blocking_websocket))
+        await asyncio.sleep(0.01)
+
+        self.assertTrue(disconnect_notify_task.cancelled())
+        self.assertIsNone(server._disconnect_notify_task)
+
+        blocking_websocket.disconnect()
+        await reconnect_task
+        server._disconnect_notify_task.cancel()
+        await asyncio.sleep(0)
+
     async def test_socket_messages_read(self):
         """
         Test that our code reads inbound messages from websockets.