Skip to content

Personal AI, On Personal Devices

Python
17.9 KB
Raw Blame
"""TelegramChannel — native Telegram Bot API adapter."""

from __future__ import annotations

import asyncio
import logging
import os
import textwrap
import threading
from typing import Any, Dict, List, Optional

from openjarvis.channels._stubs import (
    BaseChannel,
    ChannelHandler,
    ChannelMessage,
    ChannelStatus,
)
from openjarvis.core.events import EventBus, EventType
from openjarvis.core.registry import ChannelRegistry

logger = logging.getLogger(__name__)


@ChannelRegistry.register("telegram")
class TelegramChannel(BaseChannel):
    """Native Telegram channel adapter using the Bot API.

    Parameters
    ----------
    bot_token:
        Telegram Bot API token.  Falls back to ``TELEGRAM_BOT_TOKEN`` env var.
    allowed_chat_ids:
        Comma-separated list of chat IDs allowed to interact.
    parse_mode:
        Message parse mode (``Markdown``, ``HTML``, etc.).
    bus:
        Optional event bus for publishing channel events.
    """

    channel_id = "telegram"

    def __init__(
        self,
        bot_token: str = "",
        *,
        allowed_chat_ids: str = "",
        parse_mode: str = "Markdown",
        bus: Optional[EventBus] = None,
    ) -> None:
        self._token = bot_token or os.environ.get("TELEGRAM_BOT_TOKEN", "")
        self._allowed_chat_ids = allowed_chat_ids
        self._parse_mode = parse_mode
        self._bus = bus
        self._handlers: List[ChannelHandler] = []
        self._status = ChannelStatus.DISCONNECTED
        self._listener_thread: Optional[threading.Thread] = None
        self._stop_event = threading.Event()
        # Serialize connect/disconnect all the way through listener
        # registration and shutdown.  Without this lock, disconnect() can
        # complete just before a concurrent connect() clears the shared stop
        # event, losing the stop request and leaving a fresh poller behind.
        self._lifecycle_lock = threading.RLock()
        # Published by _poll_loop while it's running so disconnect() can
        # wake the async lifecycle owner (#784).
        self._app: Optional[Any] = None
        self._loop: Optional[Any] = None
        self._async_stop_event: Optional[asyncio.Event] = None
        self._runtime_lock = threading.Lock()

    # -- connection lifecycle ---------------------------------------------------

    def connect(self) -> None:
        """Start listening for incoming messages via long polling."""
        with self._lifecycle_lock:
            if self._listener_thread is not None and self._listener_thread.is_alive():
                # A poller is already running against this bot token; starting
                # another one causes Telegram's getUpdates API to return 409
                # Conflict for one or both pollers (#784).
                logger.warning(
                    "Telegram channel already connected; ignoring duplicate connect()"
                )
                return

            if not self._token:
                logger.warning("No Telegram bot token configured")
                self._status = ChannelStatus.ERROR
                return

            self._stop_event.clear()
            self._status = ChannelStatus.CONNECTING

            try:
                from telegram.ext import ApplicationBuilder  # noqa: F401

                listener = threading.Thread(
                    target=self._poll_loop,
                    daemon=True,
                )
                self._listener_thread = listener
                # Publish CONNECTED before starting.  A listener that fails
                # immediately can then reliably overwrite it with ERROR;
                # connect() must not race afterward and hide that failure.
                self._status = ChannelStatus.CONNECTED
                listener.start()
                logger.info("Telegram channel connected (long polling)")
            except ImportError:
                # python-telegram-bot not installed — send-only mode
                logger.info(
                    "python-telegram-bot not installed; send-only mode",
                )
                self._status = ChannelStatus.CONNECTED
            except Exception:
                self._listener_thread = None
                self._status = ChannelStatus.ERROR
                logger.exception("Failed to start Telegram listener")

    def disconnect(self) -> None:
        """Stop the listener thread.

        The listener owns every async startup/shutdown phase. ``disconnect``
        only publishes a stop request onto that owned loop, which is observed
        between initialize, polling startup, and application startup as well
        as during steady-state polling. Status is only reported DISCONNECTED
        once the thread has actually terminated.
        """
        with self._lifecycle_lock:
            self._stop_event.set()

            with self._runtime_lock:
                loop = self._loop
                async_stop_event = self._async_stop_event
            if loop is not None and async_stop_event is not None:
                try:
                    loop.call_soon_threadsafe(async_stop_event.set)
                except RuntimeError:
                    logger.debug("Telegram poll loop's event loop already closed")

            if self._listener_thread is not None:
                self._listener_thread.join(timeout=5.0)
                if self._listener_thread.is_alive():
                    logger.warning(
                        "Telegram listener thread did not stop within timeout;"
                        " leaving status unchanged to avoid a duplicate poller"
                    )
                    return
                self._listener_thread = None

            self._status = ChannelStatus.DISCONNECTED

    # -- send / receive --------------------------------------------------------

    def send(
        self,
        channel: str,
        content: str,
        *,
        conversation_id: str = "",
        metadata: Dict[str, Any] | None = None,
    ) -> bool:
        """Send a message to a Telegram chat via the Bot API."""
        if not self._token:
            logger.warning("Cannot send: no Telegram bot token")
            return False

        try:
            import httpx

            _TELEGRAM_MAX_LEN = 4096
            url = f"https://api.telegram.org/bot{self._token}/sendMessage"
            # Canonical channel send contract (see BaseChannel.send): the first
            # positional ``channel`` arg is the DESTINATION (the Telegram chat
            # id).  ``conversation_id`` is the inbound message id used as a
            # reply/thread reference (``reply_to_message_id``).  We fall back to
            # ``conversation_id`` as the chat id only when ``channel`` is empty,
            # for backwards compatibility with legacy callers that passed the
            # chat id via ``conversation_id``.
            chat_id = channel or conversation_id
            reply_to = conversation_id if (channel and conversation_id) else ""
            chunks = textwrap.wrap(
                content,
                width=_TELEGRAM_MAX_LEN,
                break_long_words=True,
                replace_whitespace=False,
            )
            if not chunks:
                # Empty content wraps to an empty chunk list -- there is
                # nothing to send, so this must not fall through to the
                # success path below and report a message that was never
                # transmitted (#783).
                return False
            for chunk in chunks:
                payload: Dict[str, Any] = {
                    "chat_id": chat_id,
                    "text": chunk,
                }
                if self._parse_mode:
                    payload["parse_mode"] = self._parse_mode
                if reply_to:
                    payload["reply_to_message_id"] = reply_to

                resp = httpx.post(url, json=payload, timeout=10.0)
                if resp.status_code >= 300:
                    # Telegram rejects unparseable Markdown (lone asterisks,
                    # unclosed code fences, unescaped snake_case
                    # identifiers, etc.) with a 400 naming the cause in the
                    # response body. Retry once as plain text instead of
                    # dropping the message outright (#783).
                    if self._parse_mode and "can't parse entities" in resp.text.lower():
                        logger.warning(
                            "Telegram rejected Markdown formatting, "
                            "retrying as plain text: %s",
                            resp.text,
                        )
                        plain_payload = {
                            k: v for k, v in payload.items() if k != "parse_mode"
                        }
                        resp = httpx.post(url, json=plain_payload, timeout=10.0)
                    if resp.status_code >= 300:
                        logger.warning(
                            "Telegram API returned status %d: %s",
                            resp.status_code,
                            resp.text,
                        )
                        return False
            self._publish_sent(channel, content, conversation_id)
            return True
        except Exception:
            logger.debug("Telegram send failed", exc_info=True)
            return False

    def status(self) -> ChannelStatus:
        """Return the current connection status."""
        return self._status

    def list_channels(self) -> List[str]:
        """Return available channel identifiers."""
        return ["telegram"]

    def on_message(self, handler: ChannelHandler) -> None:
        """Register a callback for incoming messages."""
        self._handlers.append(handler)

    # -- internal helpers -------------------------------------------------------

    def _stop_requested(self, async_stop_event: asyncio.Event) -> bool:
        return self._stop_event.is_set() or async_stop_event.is_set()

    async def _run_stage_until_stopped(
        self,
        awaitable: Any,
        async_stop_event: asyncio.Event,
    ) -> bool:
        """Run one startup stage, cancelling it when disconnect wins the race."""
        if self._stop_requested(async_stop_event):
            close = getattr(awaitable, "close", None)
            if callable(close):
                close()
            return False

        stage_task = asyncio.create_task(awaitable)
        stop_task = asyncio.create_task(async_stop_event.wait())
        try:
            done, _ = await asyncio.wait(
                {stage_task, stop_task},
                return_when=asyncio.FIRST_COMPLETED,
            )
            if stop_task in done or self._stop_event.is_set():
                stage_task.cancel()
                await asyncio.gather(stage_task, return_exceptions=True)
                return False

            await stage_task
            return True
        finally:
            stop_task.cancel()
            await asyncio.gather(stop_task, return_exceptions=True)

    async def _shutdown_partially_initialized_app(
        self,
        app: Any,
        updater: Any,
    ) -> None:
        """Release PTB resources even when ``Application.initialize`` was cut short.

        PTB intentionally makes ``Application.shutdown`` a no-op until its
        initialize method reaches the final bookkeeping assignment.  A stop can
        arrive after the bot's HTTP clients are initialized but before that
        assignment, so explicitly shut down the partially initialized
        components in that narrow state.
        """
        app_initialized = getattr(app, "_initialized", None)
        try:
            await app.shutdown()
        finally:
            if app_initialized is False:
                seen: set[int] = set()
                for component in (
                    updater,
                    getattr(app, "update_processor", None),
                    getattr(app, "bot", None),
                ):
                    if component is None or id(component) in seen:
                        continue
                    seen.add(id(component))
                    shutdown = getattr(component, "shutdown", None)
                    if not callable(shutdown):
                        continue
                    try:
                        await shutdown()
                    except Exception:
                        logger.debug(
                            "Failed to clean up partially initialized "
                            "Telegram component",
                            exc_info=True,
                        )

    async def _run_polling_lifecycle(
        self,
        app: Any,
        async_stop_event: asyncio.Event,
    ) -> None:
        """Own PTB's lifecycle so no stop can disappear inside run_polling.

        ``Application.run_polling`` checks its private stop marker before
        ``Updater.start_polling`` but not after it. A disconnect in that await
        therefore used to be lost and the subsequent ``run_forever`` stranded
        the thread. Explicit boundaries make the shared stop request durable.
        """
        updater = getattr(app, "updater", None)
        if updater is None:
            raise RuntimeError("Telegram application has no updater")

        try:
            if not await self._run_stage_until_stopped(
                app.initialize(), async_stop_event
            ):
                return
            if getattr(app, "post_init", None) is not None:
                if not await self._run_stage_until_stopped(
                    app.post_init(app), async_stop_event
                ):
                    return

            if not await self._run_stage_until_stopped(
                updater.start_polling(drop_pending_updates=True),
                async_stop_event,
            ):
                return

            if not await self._run_stage_until_stopped(app.start(), async_stop_event):
                return

            await async_stop_event.wait()
        finally:
            if getattr(updater, "running", False):
                await updater.stop()
            if getattr(app, "running", False):
                await app.stop()
                if getattr(app, "post_stop", None) is not None:
                    await app.post_stop(app)
            await self._shutdown_partially_initialized_app(app, updater)
            if getattr(app, "post_shutdown", None) is not None:
                await app.post_shutdown(app)

    def _poll_loop(self) -> None:
        """Long-poll for updates using python-telegram-bot."""
        loop: Any | None = None
        app: Any | None = None
        try:
            from telegram.ext import ApplicationBuilder, MessageHandler, filters

            # This thread owns the loop and every PTB startup/shutdown phase.
            # Publishing the stop event lets disconnect wake it safely from
            # another thread without asking PTB to stop a half-started app.
            loop = asyncio.new_event_loop()
            asyncio.set_event_loop(loop)
            async_stop_event = asyncio.Event()
            with self._runtime_lock:
                self._async_stop_event = async_stop_event
                self._loop = loop

            app = ApplicationBuilder().token(self._token).build()
            with self._runtime_lock:
                self._app = app

            async def _handle_msg(update, context):
                msg = update.message
                if msg is None:
                    return
                cm = ChannelMessage(
                    channel="telegram",
                    sender=str(msg.from_user.id) if msg.from_user else "",
                    content=msg.text or "",
                    message_id=str(msg.message_id),
                    conversation_id=str(msg.chat.id),
                )
                # Enforce allow-list when configured
                if self._allowed_chat_ids:
                    _allowed = {
                        cid.strip()
                        for cid in self._allowed_chat_ids.split(",")
                        if cid.strip()
                    }
                    if cm.conversation_id not in _allowed:
                        logger.debug(
                            "Ignoring message from unlisted chat %s",
                            cm.conversation_id,
                        )
                        return
                for handler in self._handlers:
                    try:
                        handler(cm)
                    except Exception:
                        logger.exception("Telegram handler error")
                if self._bus is not None:
                    self._bus.publish(
                        EventType.CHANNEL_MESSAGE_RECEIVED,
                        {
                            "channel": cm.channel,
                            "sender": cm.sender,
                            "content": cm.content,
                            "message_id": cm.message_id,
                        },
                    )

            app.add_handler(MessageHandler(filters.TEXT, _handle_msg))
            loop.run_until_complete(self._run_polling_lifecycle(app, async_stop_event))
        except Exception:
            logger.debug("Telegram poll loop error", exc_info=True)
            if not self._stop_event.is_set():
                self._status = ChannelStatus.ERROR
        finally:
            with self._runtime_lock:
                self._app = None
                self._async_stop_event = None
                self._loop = None
            if loop is not None and not loop.is_closed():
                asyncio.set_event_loop(None)
                loop.close()
            if self._stop_event.is_set():
                self._status = ChannelStatus.DISCONNECTED

    def _publish_sent(self, channel: str, content: str, conversation_id: str) -> None:
        """Publish a CHANNEL_MESSAGE_SENT event on the bus."""
        if self._bus is not None:
            self._bus.publish(
                EventType.CHANNEL_MESSAGE_SENT,
                {
                    "channel": channel,
                    "content": content,
                    "conversation_id": conversation_id,
                },
            )


__all__ = ["TelegramChannel"]