funora 0.0.1.dev2__py3-none-any.whl

funora/bot/_runtime.py

@@ -0,0 +1,447 @@
+"""Рантайм бота: наблюдение и разбор очереди исходящих в одном потоке.
+
+Здесь нет ни своего цикла, ни своей политики повторов, ни своего порядка шагов.
+Всё это живёт в ядре и достаётся готовым: рантайм только подставляет разбор
+очереди в паузу между опросами - через крючок on_idle у драйвера.
+
+Одно правило, ради которого класс и написан: ПЛОЩАДКУ ТРОГАЕТ ОДИН ПОТОК.
+Посторонний кладёт задание в очередь и ждёт квитанцию; отправляет тот же поток,
+что ведёт наблюдение. Иначе ограничитель исходящих недосчитывает предел, и
+узнаёте вы об этом от площадки.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from contextlib import nullcontext
+from pathlib import Path
+from typing import TYPE_CHECKING, Final
+
+from .._client import Client
+from .._fileio import file_lock
+from .._poll import Schedule
+from .._watch import Router
+from ..errors import (
+    ConfigurationError,
+    FunoraError,
+    HandlerError,
+    UsageError,
+    ValidationError,
+)
+from ._outbox import Outbox, SendCommand, SendTicket
+from ._spool import Spool
+
+if TYPE_CHECKING:
+    from ._delivery import AutoDelivery, DeliveryDecision, DeliveryPlan
+
+__all__ = ["Bot", "MAX_SENDS_PER_IDLE"]
+
+_log = logging.getLogger("funora.bot")
+
+#: Сколько отправок разбирать за одну паузу.
+#:
+#: Предел нужен, и он не про вежливость. Одна отправка - это чтение страницы
+#: диалога плюс сама отправка, а при неоднозначном ответе ещё и сверка: три
+#: чтения переписки с паузами 1, 3 и 8 секунд. Три задания подряд в худшем
+#: случае растягивают паузу на минуту, и всё это время наблюдение стоит.
+MAX_SENDS_PER_IDLE: Final[int] = 3
+
+#: Приставка ключа идемпотентности, которой автовыдача помечает свои задания.
+#:
+#: Единственный носитель связи между заданием в очереди и заказом: очередь про
+#: заказы не знает и знать не должна, а реестру выдач нужно узнать, чем кончилась
+#: отправка. Ключ чужого задания этой приставки не несёт и пропускается.
+_DELIVERY_KEY_PREFIX: Final[str] = "delivery:"
+
+
+class Bot:
+    """Наблюдение с очередью исходящих.
+
+    Args:
+        client (Client): Клиент. Рантайм становится его единственным
+            пользователем: звать операции клиента из других потоков нельзя.
+        router (Router): Реестр обработчиков событий.
+        max_sends_per_idle (int): Сколько отправок разбирать за одну паузу.
+    """
+
+    __slots__ = (
+        "_client",
+        "_router",
+        "_outbox",
+        "_spool",
+        "_limit",
+        "_sent",
+        "_refused",
+    )
+
+    def __init__(
+        self,
+        client: Client,
+        router: Router,
+        *,
+        max_sends_per_idle: int = MAX_SENDS_PER_IDLE,
+        spool_path: Path | str | None = None,
+    ) -> None:
+        # Ноль означал бы «не разбирать очередь никогда»: take(0) отдаёт
+        # пустой перечень, задания копятся, квитанции не закрываются, и
+        # положивший их ждёт вечно. Молча.
+        if max_sends_per_idle < 1:
+            raise ValidationError(
+                f"предел отправок за паузу {max_sends_per_idle} не годится: при "
+                "нём очередь не разбирается никогда, задания копятся, а "
+                "положивший их ждёт закрытия квитанции, которого не будет"
+            )
+
+        self._client = client
+        self._router = router
+        self._outbox = Outbox()
+
+        #: Очередь между ПРОЦЕССАМИ. None означает, что её не просили.
+        #:
+        #: Она не заменяет очередь в памяти, а дополняет её: та решает
+        #: задачу про потоки, эта - про процессы. Телеграм-бот, поднятый
+        #: отдельной командой, до очереди в памяти не дотягивается ничем.
+        self._spool = Spool(spool_path) if spool_path is not None else None
+        self._limit = max_sends_per_idle
+        self._sent = 0
+        self._refused = 0
+
+    @property
+    def spool(self) -> Spool | None:
+        """Очередь исходящих между процессами.
+
+        Returns:
+            Spool | None: Очередь либо None, если её не просили.
+        """
+        return self._spool
+
+    @property
+    def outbox(self) -> Outbox:
+        """Очередь исходящих.
+
+        Returns:
+            Outbox: Очередь, в которую можно класть из любого потока.
+        """
+        return self._outbox
+
+    @property
+    def sent(self) -> int:
+        """Сколько заданий отправлено с начала работы.
+
+        Returns:
+            int: Число отправок, дошедших до площадки.
+        """
+        return self._sent
+
+    @property
+    def refused(self) -> int:
+        """Сколько заданий отвергнуто отказом.
+
+        Returns:
+            int: Число заданий, на которых отправка не состоялась.
+        """
+        return self._refused
+
+    def send(
+        self,
+        chat_id: str,
+        text: str,
+        *,
+        idempotency_key: str,
+        declared_cold: bool = False,
+    ) -> SendTicket:
+        """Просит отправить сообщение.
+
+        Звать можно из любого потока - в этом весь смысл. Сама отправка
+        произойдёт в потоке наблюдения, в ближайшей паузе.
+
+        Args:
+            chat_id (str): Числовой идентификатор диалога.
+            text (str): Текст сообщения.
+            idempotency_key (str): Ключ, по которому повтор узнаётся повтором.
+            declared_cold (bool): Признание, что переписка холодная.
+
+        Returns:
+            SendTicket: Квитанция, по которой можно дождаться исхода.
+
+        Raises:
+            UsageError: Если очередь переполнена.
+        """
+        return self._outbox.put(
+            SendCommand(
+                chat_id=chat_id,
+                text=text,
+                idempotency_key=idempotency_key,
+                declared_cold=declared_cold,
+            )
+        )
+
+    def run(
+        self,
+        *,
+        account_id: str = "self",
+        max_iterations: int | None = None,
+        schedule: Schedule | None = None,
+        state_path: str | Path | None = None,
+        use_channel: bool = True,
+        max_threads_per_step: int = 5,
+        on_handler_error: Callable[[HandlerError], None] | None = None,
+    ) -> None:
+        """Ведёт наблюдение и разбирает очередь исходящих.
+
+        Метод блокирующий. Он и есть главный цикл бота.
+
+        Args:
+            account_id (str): Идентификатор аккаунта для отпечатков событий.
+            max_iterations (int | None): Сколько шагов сделать.
+            schedule (Schedule | None): Расписание опроса.
+            state_path (str | Path | None): Файл состояния.
+            use_channel (bool): Слушать ли канал обновлений площадки. По
+                умолчанию да: покупатель получает ответ за секунды, а не за
+                десятки секунд. Выключение возвращает прежний опрос страниц.
+            max_threads_per_step (int): Сколько переписок дочитывать за шаг.
+            on_handler_error (Callable[[HandlerError], None] | None): Что делать
+                с отказом обработчика.
+
+        Returns:
+            None
+
+        Raises:
+            FunoraError: Любая ошибка чтения, которую не удалось повторить.
+        """
+        worker = (
+            file_lock(self._spool.root / ".worker.lock", blocking=False)
+            if self._spool is not None
+            else nullcontext()
+        )
+        with worker:
+            self._outbox.claim()
+            try:
+                # Застрявшее разбирается ОДИН РАЗ, на старте, и до первого опроса.
+                # Задание, взятое умершим процессом, могло уйти на площадку и могло не
+                # уйти; повторять его нельзя, и молчать о нём нельзя тоже.
+                if self._spool is not None:
+                    self._spool.recover()
+
+                self._client.run(
+                    self._client.engine.watch(
+                        self._router,
+                        account_id=account_id,
+                        max_iterations=max_iterations,
+                        schedule=schedule,
+                        state_path=state_path,
+                        max_threads_per_step=max_threads_per_step,
+                        use_channel=use_channel,
+                    ),
+                    router=self._router,
+                    on_handler_error=on_handler_error,
+                    on_idle=self._drain,
+                )
+            finally:
+                self._outbox.release()
+
+    def _note_delivery(self, idempotency_key: str, outcome: str) -> None:
+        """Проставляет реестру выдач настоящий исход отправки.
+
+        ЗАЧЕМ ЭТО ЗДЕСЬ. Автовыдача заводит запись исходом ``queued`` и уходит:
+        отправка случится позже и в другом месте. Прежде исход так и оставался
+        ``queued`` навсегда, и успешная выдача была неотличима от потерянной -
+        а найти потерянные не было способа вовсе.
+
+        Заказ узнаётся по ключу идемпотентности: автовыдача составляет его как
+        ``delivery:<заказ>``, и другого носителя связи между заданием и заказом
+        нет. Ключ чужого задания сюда просто не подходит и молча пропускается.
+
+        Запись не заводится, если её нет: см. DeliveryLedger.settle.
+
+        Args:
+            idempotency_key (str): Ключ задания.
+            outcome (str): Исход отправки либо имя отказа.
+
+        Returns:
+            None
+        """
+        if not idempotency_key.startswith(_DELIVERY_KEY_PREFIX):
+            return
+        order_id = idempotency_key[len(_DELIVERY_KEY_PREFIX) :]
+        engine = self._client.engine
+        engine.delivered.settle(order_id, outcome)
+        # Сохранение сразу: исход, оставшийся только в памяти, теряется тем же
+        # перезапуском, ради которого реестр и заведён долговечным.
+        engine.save_delivery()
+
+    def _drain(self, pause_ms: int) -> None:
+        """Разбирает очередь исходящих.
+
+        Вызывается драйвером в паузе между опросами и потому исполняется в
+        потоке наблюдения - том единственном, которому позволено трогать
+        площадку.
+
+        Отказ ОДНОГО задания не отменяет остальные и не роняет наблюдение: он
+        уходит в квитанцию, и ждать его будет тот, кто задание положил. Уронить
+        цикл из-за одного неудачного сообщения значило бы поставить наблюдение в
+        зависимость от чужой кнопки.
+
+        Args:
+            pause_ms (int): Длительность паузы в миллисекундах. Не используется:
+                предел ставится числом заданий, а не временем. Время предсказать
+                нельзя - сверка отправки сама спит до двенадцати секунд.
+
+        Returns:
+            None
+        """
+        left = self._limit
+        for _ in range(left):
+            batch = self._outbox.take(1)
+            if not batch:
+                break
+            ticket = batch[0]
+            left -= 1
+            command = ticket.command
+            try:
+                result = self._client.chats.send_text(
+                    command.chat_id,
+                    command.text,
+                    declared_cold=command.declared_cold,
+                )
+            except FunoraError as exc:
+                self._refused += 1
+                _log.warning(
+                    "задание %s не отправлено: %s",
+                    command.idempotency_key,
+                    type(exc).__name__,
+                )
+                ticket.settle(error=exc)
+                self._note_delivery(command.idempotency_key, type(exc).__name__)
+                continue
+            except Exception as exc:
+                ticket.settle(error=exc)
+                self._note_delivery(command.idempotency_key, "unexpected_error")
+                raise
+            self._sent += 1
+            ticket.settle(result=result)
+            self._note_delivery(command.idempotency_key, result.outcome.value)
+
+        # Каталог разбирается ПОСЛЕ памяти и в остаток того же предела. Предел
+        # общий нарочно: он бережёт не очередь, а паузу между опросами, и две
+        # очереди с собственными пределами вдвое удлинили бы её.
+        #
+        # Реестр выдач при этом уже поправлен: исход проставляется сразу за
+        # квитанцией, а не в конце разбора. Разбор может оборваться на середине,
+        # и заданиям, которые успели уйти, незачем оставаться неразобранными
+        # из-за тех, которые не успели.
+        if self._spool is None:
+            return
+
+        for _ in range(left):
+            entries = self._spool.take(1)
+            if not entries:
+                break
+            entry = entries[0]
+            command = entry.command
+            try:
+                result = self._client.chats.send_text(
+                    command.chat_id,
+                    command.text,
+                    declared_cold=command.declared_cold,
+                )
+            except FunoraError as exc:
+                self._refused += 1
+                _log.warning(
+                    "задание %s из каталога не отправлено: %s",
+                    command.idempotency_key,
+                    type(exc).__name__,
+                )
+                self._spool.settle(entry, state="refused", detail=type(exc).__name__)
+                continue
+            self._sent += 1
+            self._spool.settle(entry, state="sent", detail=result.outcome.value)
+
+    def deliveries(
+        self,
+        plan: DeliveryPlan,
+        on_hold: Callable[[DeliveryDecision], None] | None = None,
+    ) -> AutoDelivery:
+        """Собирает автовыдачу, связанную с файлом состояния клиента.
+
+        СОБИРАТЬ ЕЁ РУКАМИ НЕ НАДО, и это не вежливость. Реестр выданного
+        обязан переживать перезапуск: обнулившись, он выдаст товар второй раз
+        по заказу, который в списке продаж всё ещё оплачен. Связать его с
+        файлом состояния можно только через движок, который этот файл открыл.
+
+        Собранная руками автовыдача про файл не знает и знать не может, а
+        выглядит рабочей: первый прогон отдаёт товар, второй отдаёт его снова.
+
+        Args:
+            plan (DeliveryPlan): Что и кому выдавать.
+            on_hold (Callable[[DeliveryDecision], None] | None): Что делать с
+                заказом, который сам не выдаётся.
+
+        Returns:
+            AutoDelivery: Автовыдача с долговечным реестром.
+
+        Raises:
+            ConfigurationError: Если у клиента нет файла состояния. Реестр в
+                памяти здесь хуже отсутствия реестра: он выглядит защитой и ею
+                не является.
+        """
+        from ._delivery import AutoDelivery
+
+        engine = self._client.engine
+        if engine._ledger is None:
+            raise ConfigurationError(
+                "автовыдача без файла состояния невозможна: реестр выданного "
+                "обнулится при перезапуске, и товар уйдёт второй раз по заказу, "
+                "который в списке продаж всё ещё оплачен. Передайте клиенту "
+                "state_path"
+            )
+
+        return AutoDelivery(
+            plan,
+            engine.delivered,
+            lambda chat, text, key, cold: self.send(
+                chat, text, idempotency_key=key, declared_cold=cold
+            ),
+            on_hold=on_hold,
+            persist=engine.save_delivery,
+        )
+
+    def send_now(
+        self,
+        chat_id: str,
+        text: str,
+        *,
+        declared_cold: bool = False,
+    ) -> object:
+        """Отправляет сообщение немедленно, минуя очередь.
+
+        Звать МОЖНО ТОЛЬКО из потока наблюдения - из обработчика события. Вызов
+        из чужого потока отвергается вслух.
+
+        Отказ громкий, а не молчаливая гонка, потому что гонка здесь не роняет
+        ничего и не бросает исключений: она портит счёт ограничителя исходящих.
+        Проявится это превышением настоящего предела площадки, и объяснит вам
+        это площадка.
+
+        Args:
+            chat_id (str): Числовой идентификатор диалога.
+            text (str): Текст сообщения.
+            declared_cold (bool): Признание, что переписка холодная.
+
+        Returns:
+            object: Квитанция отправки - SendResult.
+
+        Raises:
+            UsageError: Если вызов идёт не из потока наблюдения.
+            FunoraError: Если отправка не состоялась.
+        """
+        if not self._outbox.is_owner():
+            raise UsageError(
+                "send_now зовут не из потока наблюдения. Клиент не защищён ни "
+                "одной блокировкой: у ограничителя исходящих проверка и запись "
+                "не атомарны, и второй поток недосчитывает предел - то есть "
+                "превышает настоящий предел площадки. Кладите задание в очередь "
+                "методом send: его разберёт тот же поток, что ведёт наблюдение"
+            )
+        return self._client.chats.send_text(chat_id, text, declared_cold=declared_cold)