"""WebSocket 路由处理器。

当前实现仅用于维持连接并将连接注册到 Broadcaster，便于服务端主动推送消息。
"""

from __future__ import annotations

from fastapi import WebSocket, WebSocketDisconnect

from backend.services.broadcaster import Broadcaster


async def websocket_handler(ws: WebSocket, broadcaster: Broadcaster) -> None:
    """WebSocket 连接处理：接入、注册、保持心跳、断开清理。"""
    await ws.accept()
    await broadcaster.add(ws)
    logger.info("WebSocket 连接接入：%s", ws.client)
    try:
        while True:
            await ws.receive_text()
    except WebSocketDisconnect:
        # 客户端正常断开连接，无需打印堆栈信息
        pass
    finally:
        await broadcaster.remove(ws)
        logger.info("WebSocket 连接断开：%s", ws.client)