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

CHANGELOG.md

@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _Changes in the next release_
 
+### Breaking Changes
+- A WebSocket disconnection no longer emits the `DISCONNECT` event, but the net `CLIENT_DISCONNECTED` event.
+
+### Added
+- New `CLIENT_CONNECTED` event is emitted when a new WebSocket client connects.
+- WebSocket client identification in disconnect log statements.
+
 ---
 
 ## v0.3.2 - 2025-09-17

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
@@ -763,6 +774,11 @@ def remove_all_listeners(self, event: uc.Events | None) -> None:
     # Properties #
     ##############
 
+    @property
+    def client_count(self) -> int:
+        """Return number of WebSocket clients."""
+        return len(self._clients)
+
     @property
     def device_state(self) -> uc.DeviceStates:
         """

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?