refactor!: WS client disconnection may not emit a disconnect event

The `disconnect` event is defined in the Integration-API and may not be
used to signal a WebSocket disconnection.
New events have been introduced to listen to WS connections and
disconnections and a new `client_count` property to get the number of
clients.

Author: zehnm

ucapi/api.py

@@ -162,24 +162,35 @@ async def _handle_ws(self, websocket) -> None:
             # authenticate on connection
             await self._authenticate(websocket, True)
 
+            self._events.emit(uc.Events.CLIENT_CONNECTED)
+
             async for message in websocket:
                 # process message
                 await self._process_ws_message(websocket, message)
 
         except ConnectionClosedOK:
-            _LOG.info("WS: Connection closed")
+            _LOG.info("[%s] WS: Connection closed", websocket.remote_address)
 
         except websockets.exceptions.ConnectionClosedError as e:
             # no idea why they made code & reason deprecated...
-            _LOG.info("WS: Connection closed with error %d: %s", e.code, e.reason)
+            _LOG.info(
+                "[%s] WS: Connection closed with error %d: %s",
+                websocket.remote_address,
+                e.code,
+                e.reason,
+            )
 
         except websockets.exceptions.WebSocketException as e:
-            _LOG.error("WS: Connection closed due to processing error: %s", e)
+            _LOG.error(
+                "[%s] WS: Connection closed due to processing error: %s",
+                websocket.remote_address,
+                e,
+            )
 
         finally:
             self._clients.remove(websocket)
-            _LOG.info("WS: Client removed")
-            self._events.emit(uc.Events.DISCONNECT)
+            _LOG.info("[%s] WS: Client removed", websocket.remote_address)
+            self._events.emit(uc.Events.CLIENT_DISCONNECTED)
 
     async def _send_ok_result(
         self, websocket, req_id: int, msg_data: dict[str, Any] | list | None = None

ucapi/api_definitions.py

@@ -82,13 +82,23 @@ class WsMsgEvents(str, Enum):
 class Events(str, Enum):
     """Internal library events."""
 
+    CLIENT_CONNECTED = "client_connected"
+    """WebSocket client connected."""
+    CLIENT_DISCONNECTED = "client_disconnected"
+    """WebSocket client disconnected."""
     ENTITY_ATTRIBUTES_UPDATED = "entity_attributes_updated"
     SUBSCRIBE_ENTITIES = "subscribe_entities"
+    """Integration API `subscribe_events` message."""
     UNSUBSCRIBE_ENTITIES = "unsubscribe_entities"
+    """Integration API `unsubscribe_events` message."""
     CONNECT = "connect"
+    """Integration-API `connect` event message."""
     DISCONNECT = "disconnect"
+    """Integration-API `disconnect` event message."""
     ENTER_STANDBY = "enter_standby"
+    """Integration-API `enter_standby` event message."""
     EXIT_STANDBY = "exit_standby"
+    """Integration-API `exit_standby` event message."""
 
 
 # Does EventCategory need to be public?