WechatOnCloud/bridge/woc_bridge/messaging/send_queue.py

"""发送串行化队列。

所有 xdotool 操作经此队列串行执行，避免并发 UI 操作冲突。
内部维护最近 1 秒调用时间戳用于限流。
"""

from __future__ import annotations

import asyncio
import logging
import time
from typing import Any, Awaitable, Callable, Optional

from woc_bridge.models import BridgeError


logger = logging.getLogger("woc-bridge")

# 工厂类型：返回一个待执行的 coroutine
CoroFactory = Callable[[], Awaitable[Any]]


class SendQueue:
    """串行化发送队列 + 限流。

    通过 asyncio.Queue 串行执行所有发送任务；执行间隔可配置
    （默认 3000ms），单实例每秒调用上限可配置（默认 10）。
    """

    def __init__(
        self,
        send_delay_ms: int = 3000,
        max_calls_per_sec: int = 10,
        max_queue_size: int = 100,
    ) -> None:
        """初始化队列配置。

        Args:
            send_delay_ms: 两次发送之间的最小间隔毫秒
            max_calls_per_sec: 每秒最大调用次数
            max_queue_size: 队列最大深度，满时入队抛 RATE_LIMITED
        """
        self.send_delay_ms = send_delay_ms
        self.max_calls_per_sec = max_calls_per_sec
        self._queue: asyncio.Queue[tuple[CoroFactory, asyncio.Future, Optional[int]]] = asyncio.Queue(maxsize=max_queue_size)
        self._worker: asyncio.Task | None = None
        # 最近 1 秒内的调用时间戳
        self._recent_call_times: list[float] = []

    async def start(self) -> None:
        """启动 worker task。"""
        if self._worker is None or self._worker.done():
            self._worker = asyncio.create_task(self._run())

    async def stop(self) -> None:
        """取消 worker。"""
        if self._worker is not None and not self._worker.done():
            self._worker.cancel()
            try:
                await self._worker
            except asyncio.CancelledError:
                pass
            self._worker = None

    async def enqueue(
        self,
        coro_factory: CoroFactory,
        delay_ms: Optional[int] = None,
        wait_timeout_ms: Optional[int] = None,
    ) -> Any:
        """将一个返回 coroutine 的工厂入队，等待执行结果。

        Args:
            coro_factory: 调用后返回 coroutine 的工厂函数
            delay_ms: 自定义延时毫秒，None 用默认 send_delay_ms
            wait_timeout_ms: 队列等待超时毫秒，None 表示无限等待；
                             超时抛出 BridgeError(TIMEOUT)

        Returns:
            coroutine 的执行结果

        Raises:
            BridgeError: 限流命中、队列满或等待超时时抛错；
                        任务执行抛出的异常会透传给调用方
        """
        loop = asyncio.get_running_loop()
        future: asyncio.Future = loop.create_future()
        # 队列满时立即拒绝，避免无界增长 OOM
        if self._queue.maxsize > 0 and self._queue.qsize() >= self._queue.maxsize:
            logger.warning(
                "send_queue: 队列已满 (size=%d/%d)，拒绝入队",
                self._queue.qsize(), self._queue.maxsize,
            )
            raise BridgeError(
                code="RATE_LIMITED",
                message=f"发送队列已满（{self._queue.qsize()}/{self._queue.maxsize}），请稍后重试",
                details={"retry_after": 3},
            )
        await self._queue.put((coro_factory, future, delay_ms))
        pending = self._queue.qsize()
        logger.info("send_queue: 入队 (pending=%d)", pending)
        if wait_timeout_ms is not None and wait_timeout_ms > 0:
            try:
                return await asyncio.wait_for(
                    future, timeout=wait_timeout_ms / 1000.0
                )
            except asyncio.TimeoutError:
                # 竞争窗口：worker 可能刚好在此时完成并 set_result。
                # 若 future 已完成且未被取消，直接取结果；否则取消 future 并抛 TIMEOUT。
                if future.done() and not future.cancelled():
                    logger.info(
                        "send_queue: 等待超时但任务刚好完成，取结果 (pending=%d)",
                        pending,
                    )
                    return future.result()
                # 取消 future，worker 出队时发现 cancelled 会跳过执行
                future.cancel()
                wait_sec = wait_timeout_ms / 1000.0
                logger.warning(
                    "send_queue: 等待超时 (pending=%d, wait_timeout=%.1fs)",
                    pending, wait_sec,
                )
                raise BridgeError(
                    code="TIMEOUT",
                    message=f"发送队列等待超时（{pending} 个待处理，已等 {wait_sec:.1f}s）",
                    details={"retry_after": max(1, int(self.send_delay_ms / 1000))},
                )
        return await future

    def pending_count(self) -> int:
        """返回当前队列中待执行任务数（供 /api/status 暴露给客户端做退避决策）。"""
        return self._queue.qsize()

    def _check_rate_limit(self) -> None:
        """检查限流。

        清理 1 秒前的时间戳，若当前已满 max_calls_per_sec 则抛
        BridgeError(RATE_LIMITED)，并在 details 中携带 retry_after 秒数
        供上层设置 Retry-After 响应头。
        """
        now = time.monotonic()
        # 清理 1 秒前的时间戳
        self._recent_call_times = [t for t in self._recent_call_times if now - t < 1.0]
        if len(self._recent_call_times) >= self.max_calls_per_sec:
            # 计算建议等待秒数：最早一次调用距窗口边界还差多久
            oldest = self._recent_call_times[0]
            retry_after = max(1, int(1.0 - (now - oldest)) + 1)
            logger.warning(
                "send_queue: 限流命中，拒绝执行 (recent=%d/%d, retry_after=%ds)",
                len(self._recent_call_times), self.max_calls_per_sec, retry_after,
            )
            raise BridgeError(
                code="RATE_LIMITED",
                message=f"发送限流：每秒最多 {self.max_calls_per_sec} 次",
                details={"retry_after": retry_after},
            )
        logger.debug(
            "send_queue: 限流通过 (recent=%d/%d)",
            len(self._recent_call_times), self.max_calls_per_sec,
        )

    async def _run(self) -> None:
        """worker 主循环。

        循环取出任务执行；执行前检查限流（超限则失败该任务）；
        执行前记录开始时间戳（避免长任务导致 1 秒窗口内超限）；
        执行后 sleep delay_ms/1000（自定义延时优先于默认 send_delay_ms）。
        """
        while True:
            coro_factory, future, custom_delay_ms = await self._queue.get()
            # 调用方已超时取消：跳过执行与延时
            if future.cancelled():
                self._queue.task_done()
                logger.info(
                    "send_queue: 出队任务已取消，跳过 (pending=%d)",
                    self._queue.qsize(),
                )
                continue

            logger.info("send_queue: 出队，开始处理 (pending=%d)", self._queue.qsize())
            # 标记任务是否真正开始执行（用于决定 finally 是否延时）
            executed = False
            t_exec = time.perf_counter()
            try:
                # 执行前检查限流
                self._check_rate_limit()
                # 记录开始时间戳（限流窗口基于开始时刻，避免长任务后窗口偏移）
                self._recent_call_times.append(time.monotonic())
                executed = True
                # 执行任务
                logger.info("send_queue: 开始执行任务")
                result = await coro_factory()
                logger.info(
                    "send_queue: 任务执行完成 (%.0fms)",
                    (time.perf_counter() - t_exec) * 1000,
                )
                if not future.done():
                    future.set_result(result)
            except asyncio.CancelledError:
                # worker 被取消时，把取消传播给等待的调用方
                if not future.done():
                    future.cancel()
                raise
            except Exception as e:
                logger.warning(
                    "send_queue: 任务执行抛异常 %s: %s (%.0fms)",
                    type(e).__name__, e, (time.perf_counter() - t_exec) * 1000,
                )
                if not future.done():
                    future.set_exception(e)
            finally:
                self._queue.task_done()
                # 仅在任务真正执行过时延时，限流失败/已取消的任务不延时
                if executed:
                    delay = custom_delay_ms if custom_delay_ms is not None else self.send_delay_ms
                    logger.info(
                        "send_queue: 延时 %dms 后处理下一个",
                        delay,
                    )
                    await asyncio.sleep(delay / 1000.0)