devcopilot 0.2.0__py3-none-any.whl

messaging/limiter.py

@@ -0,0 +1,300 @@
+"""
+Global Rate Limiter for Messaging Platforms.
+
+Centralizes outgoing message requests and ensures compliance with rate limits
+using a strict sliding window algorithm and a task queue.
+"""
+
+import asyncio
+from collections import deque
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from loguru import logger
+
+from config.settings import get_settings
+from core.rate_limit import StrictSlidingWindowLimiter as SlidingWindowLimiter
+
+from .safe_diagnostics import format_exception_for_log
+
+
+class MessagingRateLimiter:
+    """
+    A thread-safe global rate limiter for messaging.
+
+    Uses a custom queue with task compaction (deduplication) to ensure
+    only the latest version of a message update is processed.
+    """
+
+    _instance: MessagingRateLimiter | None = None
+    _lock = asyncio.Lock()
+
+    def __new__(cls, *args, **kwargs):
+        return super().__new__(cls)
+
+    @classmethod
+    async def get_instance(
+        cls,
+        *,
+        rate_limit: int = 1,
+        rate_window: float = 1.0,
+    ) -> MessagingRateLimiter:
+        """Get the singleton instance of the limiter.
+
+        ``rate_limit`` and ``rate_window`` apply only when the singleton is first
+        created. Call :meth:`shutdown_instance` before changing parameters.
+        """
+        async with cls._lock:
+            if cls._instance is None:
+                cls._instance = cls(rate_limit=rate_limit, rate_window=rate_window)
+                # Start the background worker (tracked for graceful shutdown).
+                cls._instance._start_worker()
+        return cls._instance
+
+    def __init__(self, *, rate_limit: int, rate_window: float) -> None:
+        # Prevent double initialization in singleton
+        if hasattr(self, "_initialized"):
+            return
+
+        self.limiter = SlidingWindowLimiter(rate_limit, rate_window)
+        # Custom queue state - using deque for O(1) popleft
+        self._queue_list: deque[str] = deque()  # Deque of dedup_keys in order
+        self._queue_map: dict[
+            str, tuple[Callable[[], Awaitable[Any]], list[asyncio.Future]]
+        ] = {}
+        self._condition = asyncio.Condition()
+        self._shutdown = asyncio.Event()
+        self._worker_task: asyncio.Task | None = None
+
+        self._initialized = True
+        self._paused_until = 0
+
+        logger.info(
+            f"MessagingRateLimiter initialized ({rate_limit} req / {rate_window}s with Task Compaction)"
+        )
+
+    def _start_worker(self) -> None:
+        """Ensure the worker task exists."""
+        if self._worker_task and not self._worker_task.done():
+            return
+        # Named task helps debugging shutdown hangs.
+        self._worker_task = asyncio.create_task(
+            self._worker(), name="msg-limiter-worker"
+        )
+
+    async def _worker(self):
+        """Background worker that processes queued messaging tasks."""
+        logger.info("MessagingRateLimiter worker started")
+        while not self._shutdown.is_set():
+            try:
+                # Get a task from the queue
+                async with self._condition:
+                    while not self._queue_list and not self._shutdown.is_set():
+                        await self._condition.wait()
+
+                    if self._shutdown.is_set():
+                        break
+
+                    dedup_key = self._queue_list.popleft()
+                    func, futures = self._queue_map.pop(dedup_key)
+
+                # Check for manual pause (FloodWait)
+                now = asyncio.get_event_loop().time()
+                if self._paused_until > now:
+                    wait_time = self._paused_until - now
+                    logger.warning(
+                        f"Limiter worker paused, waiting {wait_time:.1f}s more..."
+                    )
+                    await asyncio.sleep(wait_time)
+
+                # Wait for rate limit capacity
+                async with self.limiter:
+                    try:
+                        result = await func()
+                        for f in futures:
+                            if not f.done():
+                                f.set_result(result)
+                    except Exception as e:
+                        # Report error to all futures and log it
+                        for f in futures:
+                            if not f.done():
+                                f.set_exception(e)
+
+                        error_msg = str(e).lower()
+                        if "flood" in error_msg or "wait" in error_msg:
+                            seconds = 30
+                            try:
+                                if hasattr(e, "seconds"):
+                                    seconds = e.seconds
+                                elif "after " in error_msg:
+                                    # Try to parse "retry after X"
+                                    parts = error_msg.split("after ")
+                                    if len(parts) > 1:
+                                        seconds = int(parts[1].split()[0])
+                            except Exception:
+                                pass
+
+                            logger.error(
+                                f"FloodWait detected! Pausing worker for {seconds}s"
+                            )
+                            wait_secs = (
+                                float(seconds)
+                                if isinstance(seconds, (int, float, str))
+                                else 30.0
+                            )
+                            self._paused_until = (
+                                asyncio.get_event_loop().time() + wait_secs
+                            )
+                        else:
+                            d = get_settings().log_messaging_error_details
+                            logger.error(
+                                "Error in limiter worker for key {}: {}",
+                                dedup_key,
+                                format_exception_for_log(e, log_full_message=d),
+                            )
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                d = get_settings().log_messaging_error_details
+                if d:
+                    logger.error(
+                        "MessagingRateLimiter worker critical error: {}",
+                        e,
+                        exc_info=True,
+                    )
+                else:
+                    logger.error(
+                        "MessagingRateLimiter worker critical error: exc_type={}",
+                        type(e).__name__,
+                    )
+                await asyncio.sleep(1)
+
+    async def shutdown(self, timeout: float = 2.0) -> None:
+        """Stop the background worker so process shutdown doesn't hang."""
+        self._shutdown.set()
+        try:
+            async with self._condition:
+                self._condition.notify_all()
+        except Exception:
+            # Best-effort: condition may be bound to a closing loop.
+            pass
+
+        task = self._worker_task
+        if not task or task.done():
+            self._worker_task = None
+            return
+
+        task.cancel()
+        try:
+            await asyncio.wait_for(task, timeout=timeout)
+        except TimeoutError:
+            logger.warning("MessagingRateLimiter worker did not stop before timeout")
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            d = get_settings().log_messaging_error_details
+            logger.debug(
+                "MessagingRateLimiter worker shutdown error: {}",
+                format_exception_for_log(e, log_full_message=d),
+            )
+        finally:
+            self._worker_task = None
+
+    @classmethod
+    async def shutdown_instance(cls, timeout: float = 2.0) -> None:
+        """Shutdown and clear the singleton instance (safe to call multiple times)."""
+        inst = cls._instance
+        if not inst:
+            return
+        try:
+            await inst.shutdown(timeout=timeout)
+        finally:
+            cls._instance = None
+
+    async def _enqueue_internal(self, func, future, dedup_key, front=False):
+        await self._enqueue_internal_multi(func, [future], dedup_key, front)
+
+    async def _enqueue_internal_multi(self, func, futures, dedup_key, front=False):
+        async with self._condition:
+            if dedup_key in self._queue_map:
+                # Compaction: Update existing task with new func, append new futures
+                _old_func, old_futures = self._queue_map[dedup_key]
+                old_futures.extend(futures)
+                self._queue_map[dedup_key] = (func, old_futures)
+                logger.debug(
+                    f"Compacted task for key: {dedup_key} (now {len(old_futures)} futures)"
+                )
+            else:
+                self._queue_map[dedup_key] = (func, futures)
+                if front:
+                    self._queue_list.appendleft(dedup_key)
+                else:
+                    self._queue_list.append(dedup_key)
+                self._condition.notify_all()
+
+    async def enqueue(
+        self, func: Callable[[], Awaitable[Any]], dedup_key: str | None = None
+    ) -> Any:
+        """
+        Enqueue a messaging task and return its future result.
+        If dedup_key is provided, subsequent tasks with the same key will replace this one.
+        """
+        if dedup_key is None:
+            # Unique key to avoid deduplication
+            dedup_key = f"task_{id(func)}_{asyncio.get_event_loop().time()}"
+
+        future = asyncio.get_event_loop().create_future()
+        await self._enqueue_internal(func, future, dedup_key)
+        return await future
+
+    def fire_and_forget(
+        self, func: Callable[[], Awaitable[Any]], dedup_key: str | None = None
+    ):
+        """Enqueue a task without waiting for the result."""
+        if dedup_key is None:
+            dedup_key = f"task_{id(func)}_{asyncio.get_event_loop().time()}"
+
+        future = asyncio.get_event_loop().create_future()
+
+        async def _wrapped():
+            max_retries = 2
+            for attempt in range(max_retries + 1):
+                try:
+                    return await self.enqueue(func, dedup_key)
+                except Exception as e:
+                    error_msg = str(e).lower()
+                    # Only retry transient connectivity issues that might have slipped through
+                    # or occurred between platform checks.
+                    if attempt < max_retries and any(
+                        x in error_msg for x in ["connect", "timeout", "broken"]
+                    ):
+                        wait = 2**attempt
+                        d = get_settings().log_messaging_error_details
+                        if d:
+                            logger.warning(
+                                "Limiter fire_and_forget transient error (attempt {}): {}. Retrying in {}s...",
+                                attempt + 1,
+                                e,
+                                wait,
+                            )
+                        else:
+                            logger.warning(
+                                "Limiter fire_and_forget transient error (attempt {}): exc_type={}. Retrying in {}s...",
+                                attempt + 1,
+                                type(e).__name__,
+                                wait,
+                            )
+                        await asyncio.sleep(wait)
+                        continue
+
+                    d = get_settings().log_messaging_error_details
+                    logger.error(
+                        "Final error in fire_and_forget for key {}: {}",
+                        dedup_key,
+                        format_exception_for_log(e, log_full_message=d),
+                    )
+                    if not future.done():
+                        future.set_exception(e)
+                    break
+
+        _ = asyncio.create_task(_wrapped())

messaging/models.py

@@ -0,0 +1,36 @@
+"""Platform-agnostic message models."""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+
+@dataclass
+class IncomingMessage:
+    """
+    Platform-agnostic incoming message.
+
+    Adapters convert platform-specific events to this format.
+    """
+
+    text: str
+    chat_id: str
+    user_id: str
+    message_id: str
+    platform: str  # "telegram", "discord", "slack", etc.
+
+    # Optional fields
+    reply_to_message_id: str | None = None
+    # Forum topic ID (Telegram); required when replying in forum supergroups
+    message_thread_id: str | None = None
+    username: str | None = None
+    # Pre-sent status message ID (e.g. "Transcribing voice note..."); handler edits in place
+    status_message_id: str | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    # Platform-specific raw event for edge cases
+    raw_event: Any = None
+
+    def is_reply(self) -> bool:
+        """Check if this message is a reply to another message."""
+        return self.reply_to_message_id is not None

messaging/node_event_pipeline.py

@@ -0,0 +1,127 @@
+"""CLI event handling for a single queued node (transcript + session + errors)."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from loguru import logger
+
+from core.trace import trace_event
+
+from .cli_event_constants import TRANSCRIPT_EVENT_TYPES, get_status_for_event
+from .platforms.base import ManagedClaudeSessionManagerProtocol
+from .safe_diagnostics import text_len_hint
+from .session import SessionStore
+from .transcript import TranscriptBuffer
+from .trees import MessageState, MessageTree
+
+
+async def handle_session_info_event(
+    event_data: dict[str, Any],
+    tree: MessageTree | None,
+    node_id: str,
+    captured_session_id: str | None,
+    temp_session_id: str | None,
+    *,
+    cli_manager: ManagedClaudeSessionManagerProtocol,
+    session_store: SessionStore,
+) -> tuple[str | None, str | None]:
+    """Handle session_info event; return updated (captured_session_id, temp_session_id)."""
+    if event_data.get("type") != "session_info":
+        return captured_session_id, temp_session_id
+
+    real_session_id = event_data.get("session_id")
+    if not real_session_id or not temp_session_id:
+        return captured_session_id, temp_session_id
+
+    await cli_manager.register_real_session_id(temp_session_id, real_session_id)
+    trace_event(
+        stage="claude_cli",
+        event="claude_cli.session.registered",
+        source="claude_cli",
+        node_id=node_id,
+        temp_session_id=temp_session_id,
+        real_session_id=real_session_id,
+        tree_root_id=tree.root_id if tree else None,
+    )
+    if tree and real_session_id:
+        await tree.update_state(
+            node_id,
+            MessageState.IN_PROGRESS,
+            session_id=real_session_id,
+        )
+        session_store.save_tree(tree.root_id, tree.to_dict())
+
+    return real_session_id, None
+
+
+async def process_parsed_cli_event(
+    parsed: dict[str, Any],
+    transcript: TranscriptBuffer,
+    update_ui: Callable[..., Awaitable[None]],
+    last_status: str | None,
+    had_transcript_events: bool,
+    tree: MessageTree | None,
+    node_id: str,
+    captured_session_id: str | None,
+    *,
+    session_store: SessionStore,
+    format_status: Callable[..., str],
+    propagate_error_to_children: Callable[[str, str, str], Awaitable[None]],
+    log_messaging_error_details: bool = False,
+) -> tuple[str | None, bool]:
+    """Process a single parsed CLI event. Returns (last_status, had_transcript_events)."""
+    ptype = parsed.get("type") or ""
+
+    if ptype in TRANSCRIPT_EVENT_TYPES:
+        transcript.apply(parsed)
+        had_transcript_events = True
+
+    status = get_status_for_event(ptype, parsed, format_status)
+    if status is not None:
+        await update_ui(status)
+        last_status = status
+    elif ptype == "block_stop":
+        await update_ui(last_status, force=True)
+    elif ptype == "complete":
+        if not had_transcript_events:
+            transcript.apply({"type": "text_chunk", "text": "Done."})
+        trace_event(
+            stage="claude_cli",
+            event="turn.completed",
+            source="cli_event",
+            node_id=node_id,
+            claude_session_id=captured_session_id,
+        )
+        await update_ui(format_status("✅", "Complete"), force=True)
+        if tree and captured_session_id:
+            await tree.update_state(
+                node_id,
+                MessageState.COMPLETED,
+                session_id=captured_session_id,
+            )
+            session_store.save_tree(tree.root_id, tree.to_dict())
+    elif ptype == "error":
+        error_msg = parsed.get("message", "Unknown error")
+        em = error_msg if isinstance(error_msg, str) else str(error_msg)
+        trace_event(
+            stage="claude_cli",
+            event="turn.failed",
+            source="cli_event",
+            node_id=node_id,
+            claude_session_id=captured_session_id,
+            cli_error_message=em,
+        )
+        if log_messaging_error_details:
+            logger.error("HANDLER: Error event received: {}", error_msg)
+        else:
+            logger.error(
+                "HANDLER: Error event received: message_chars={}",
+                text_len_hint(em),
+            )
+        await update_ui(format_status("❌", "Error"), force=True)
+        if tree:
+            await propagate_error_to_children(node_id, error_msg, "Parent task failed")
+
+    return last_status, had_transcript_events