funora 0.0.1.dev2__py3-none-any.whl

funora/bot/_delivery.py

@@ -0,0 +1,341 @@
+"""Автовыдача товара: от события о заказе до сообщения покупателю.
+
+ЧЕРТА, ВОКРУГ КОТОРОЙ ВСЁ УСТРОЕНО. Выдача идёт сама только там, где ВСЕ условия
+выполнены положительно. Любое незнание - не повод действовать осторожнее, а
+повод не действовать: вопрос уходит человеку.
+
+Условий пять, и каждое отвечает на свой вопрос:
+
+1. Состояние заказа прочитано и равно «оплачен». Не «не закрыт»: состояний
+   известно два из скольких-то, и заказ в возврате даёт ненаблюдённое значение.
+   Правило «если не закрыт, значит ждёт выдачи» на нём и ломается.
+2. По этому заказу ещё не выдавали. Реестр выдач переживает перезапуск.
+3. Чтение списка продаж полно. Неполное чтение означает, что часть строк не
+   разобрана, а не что их нет.
+4. Заказ сопоставлен с ОДНИМ собственным лотом. Двусмысленность - отказ.
+5. Для этого лота задан товар.
+
+Что здесь СОЗНАТЕЛЬНО не делается: выдача не отменяется. Состояние возврата не
+наблюдалось ни разу, отменять нечем, и механизм односторонний. Продавец, которому
+это важно, обязан знать заранее.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Final
+
+from .._delivered import QUEUED_OUTCOME, Delivery, DeliveryLedger
+from .._matching import match_offer
+from .._orders import OrderListEntry
+from .._own_lots import OwnLot
+from .._result import Completeness
+from ..extraction import OrderStatus
+from ._outbox import SendTicket
+
+__all__ = ["DeliveryPlan", "DeliveryDecision", "AutoDelivery", "HOLD_FOR_OPERATOR"]
+
+_log = logging.getLogger("funora.bot.delivery")
+
+#: Решение: выдать нечего, вопрос уходит человеку.
+HOLD_FOR_OPERATOR: Final[str] = "hold_for_operator"
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveryDecision:
+    """Что решено по заказу.
+
+    Attributes:
+        order_id (str): Заказ.
+        will_deliver (bool): Выдаётся ли сам.
+        reason (str): Машиночитаемая причина решения.
+        offer_id (str): Опознанное предложение. Пустая строка, если не
+            опознано.
+        candidates (tuple[str, ...]): Подошедшие предложения. Больше одного
+            означает, что различить их нечем.
+    """
+
+    order_id: str
+    will_deliver: bool
+    reason: str
+    offer_id: str = ""
+    candidates: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveryPlan:
+    """Что и кому выдавать.
+
+    Attributes:
+        goods (dict[str, str]): Товар по идентификатору предложения. Что именно
+            отправить покупателю, когда заказ опознан.
+        chat_of (Callable[[str], str]): Как узнать узел диалога по заказу.
+            Отдельной функцией, а не полем: узел лежит на странице заказа, идти
+            за ним - запрос, и делать этот запрос стоит только тогда, когда всё
+            остальное сошлось.
+        declared_cold (bool): Объявлять ли обращение холодным.
+
+            ПО УМОЛЧАНИЮ ДА, и это не послабление, а исправление. Холодной
+            считается переписка, в которой собеседник нам не писал, а покупатель,
+            купивший и промолчавший, - самый обычный случай, а не редкий.
+            Автовыдача прежде звала отправку без этого признака, ограничитель
+            отвергал её с cold_outreach_not_declared, и товар не уходил ровно
+            тому, кто вёл себя тише всех. Заказ при этом уже был помечен
+            выданным.
+
+            Признание здесь честное: обращение вправду холодное. Покупка
+            переписку не греет - это записано в spec/runtime/budget.yaml и
+            остаётся верным. Но выдача оплаченного товара и есть тот случай, ради
+            которого квота холодных обращений существует.
+
+            ПОМНИТЕ ПРО ПОТОЛОК: холодных обращений три в сутки. Продавцу, у
+            которого продаж больше, придётся либо здороваться с покупателем
+            первым по событию о заказе - тогда переписка станет тёплой его
+            ответом, - либо выдавать руками. Молча упереться в потолок нельзя:
+            отправка откажет вслух, и заказ уйдёт в on_hold.
+    """
+
+    goods: dict[str, str]
+    chat_of: Callable[[str], str]
+    declared_cold: bool = True
+
+
+class AutoDelivery:
+    """Автовыдача: решает по заказу и кладёт задание в очередь.
+
+    Сама ничего не отправляет и в сеть не ходит. Отправку выполняет очередь
+    исходящих, а значит - тот же поток, что ведёт наблюдение, и с теми же
+    пределами.
+
+    Args:
+        plan (DeliveryPlan): Что и кому выдавать.
+        ledger (DeliveryLedger): Реестр уже выданного.
+        send (Callable[[str, str, str, bool], SendTicket]): Как поставить
+            отправку в очередь: узел, текст, ключ идемпотентности, признание
+            холодного обращения.
+        on_hold (Callable[[DeliveryDecision], None] | None): Что делать с
+            заказом, который сам не выдаётся. Без него такой заказ виден только
+            в журнале.
+        persist (Callable[[], None] | None): Как сохранить реестр на диск.
+
+            Без него реестр живёт в памяти процесса, и каждый перезапуск
+            обнуляет память о выданном: заказ, который в списке продаж всё ещё
+            оплачен, выдаётся второй раз.
+
+            Собирать автовыдачу руками поэтому не стоит - есть Bot.deliveries(),
+            который связывает всё правильно по построению.
+    """
+
+    __slots__ = ("_plan", "_ledger", "_send", "_on_hold", "_persist", "_decisions")
+
+    def __init__(
+        self,
+        plan: DeliveryPlan,
+        ledger: DeliveryLedger,
+        send: Callable[[str, str, str, bool], SendTicket],
+        on_hold: Callable[[DeliveryDecision], None] | None = None,
+        persist: Callable[[], None] | None = None,
+    ) -> None:
+        self._plan = plan
+        self._ledger = ledger
+        self._send = send
+        self._on_hold = on_hold
+        self._persist = persist
+        self._decisions: list[DeliveryDecision] = []
+
+    @property
+    def decisions(self) -> tuple[DeliveryDecision, ...]:
+        """Решения, принятые с начала работы.
+
+        Returns:
+            tuple[DeliveryDecision, ...]: Все решения по порядку.
+        """
+        return tuple(self._decisions)
+
+    def decide(
+        self,
+        order: OrderListEntry,
+        lots: tuple[OwnLot, ...],
+        *,
+        page_completeness: Completeness,
+    ) -> DeliveryDecision:
+        """Решает, выдавать ли по заказу, и НИЧЕГО не отправляет.
+
+        Метод чистый нарочно: решение проверяется без сети и без очереди, а
+        решение здесь - самое дорогое место всего механизма.
+
+        Args:
+            order (OrderListEntry): Строка списка продаж.
+            lots (tuple[OwnLot, ...]): Собственные лоты раздела.
+            page_completeness (Completeness): Полнота чтения списка продаж.
+
+        Returns:
+            DeliveryDecision: Что решено и почему.
+        """
+        decision = self._decide(order, lots, page_completeness=page_completeness)
+        self._decisions.append(decision)
+        return decision
+
+    def _decide(
+        self,
+        order: OrderListEntry,
+        lots: tuple[OwnLot, ...],
+        *,
+        page_completeness: Completeness,
+    ) -> DeliveryDecision:
+        """Проверяет пять условий по порядку.
+
+        Порядок дешёвых проверок вперёд: сперва то, что не требует разбора
+        текста.
+
+        Args:
+            order (OrderListEntry): Строка списка продаж.
+            lots (tuple[OwnLot, ...]): Собственные лоты раздела.
+            page_completeness (Completeness): Полнота чтения списка продаж.
+
+        Returns:
+            DeliveryDecision: Что решено и почему.
+        """
+        if self._ledger.seen(order.order_id):
+            return DeliveryDecision(order.order_id, False, "already_delivered")
+
+        if page_completeness is not Completeness.COMPLETE:
+            # Неполное чтение означает, что часть строк не разобрана. Выдавать
+            # по такому списку значило бы решать по данным, которых нет.
+            return DeliveryDecision(order.order_id, False, "orders_page_incomplete")
+
+        if not order.status.is_observed:
+            # Состояние не прочитано. Это НЕ «ещё не закрыт»: заказ в возврате
+            # или споре даёт ровно такое значение.
+            return DeliveryDecision(order.order_id, False, "status_not_observed")
+
+        if order.status.value is not OrderStatus.PAID:
+            return DeliveryDecision(order.order_id, False, "status_not_paid")
+
+        matched = match_offer(
+            order.description_text,
+            {one.offer_id.value: one.description_text for one in lots if one.offer_id.is_observed},
+        )
+        if not matched.offer_id.is_observed:
+            return DeliveryDecision(
+                order.order_id,
+                False,
+                str(matched.offer_id.reason),
+                candidates=matched.candidates,
+            )
+
+        offer_id = matched.offer_id.value
+        if offer_id not in self._plan.goods:
+            return DeliveryDecision(order.order_id, False, "no_goods_for_offer", offer_id=offer_id)
+
+        return DeliveryDecision(
+            order.order_id,
+            True,
+            "ready",
+            offer_id=offer_id,
+            candidates=matched.candidates,
+        )
+
+    def handle(
+        self,
+        order: OrderListEntry,
+        lots: tuple[OwnLot, ...],
+        *,
+        page_completeness: Completeness,
+    ) -> SendTicket | None:
+        """Решает и, если можно, ставит выдачу в очередь.
+
+        Запись в реестр идёт ВПЕРЕДИ постановки в очередь. Порядок тот же и по
+        той же причине, что у реестра отправок: «запишем, когда подтвердится»
+        означает не записать ровно те выдачи, которые могли уйти.
+
+        Args:
+            order (OrderListEntry): Строка списка продаж.
+            lots (tuple[OwnLot, ...]): Собственные лоты раздела.
+            page_completeness (Completeness): Полнота чтения списка продаж.
+
+        Returns:
+            SendTicket | None: Квитанция отправки либо None, если выдача не
+            состоялась.
+        """
+        decision = self.decide(order, lots, page_completeness=page_completeness)
+        if not decision.will_deliver:
+            _log.info(
+                "заказ %s не выдаётся сам: %s%s",
+                decision.order_id,
+                decision.reason,
+                f", кандидаты {list(decision.candidates)}" if decision.candidates else "",
+            )
+            if self._on_hold is not None:
+                self._on_hold(decision)
+            return None
+
+        # УЗЕЛ ДИАЛОГА БЕРЁТСЯ ДО ЗАПИСИ В РЕЕСТР, и порядок здесь важнее, чем
+        # кажется. chat_of - это СЕТЕВОЕ чтение страницы заказа, а не поле:
+        # именно поэтому оно и сделано функцией.
+        #
+        # Прежде запись стояла впереди него, и всякий отказ этого чтения -
+        # оборванная сессия, исчерпанный бюджет, изменившаяся вёрстка - оставлял
+        # заказ НАВСЕГДА помеченным выданным при нуле отправок. Повторно он не
+        # выдаётся никогда, а on_hold не срабатывает: решение-то было
+        # положительным.
+        #
+        # Что довод «пишем впереди отправки» защищает - это окно между записью и
+        # ОТПРАВКОЙ. Сетевое чтение адреса в это окно не входит: оно происходит
+        # до того, как принято решение действовать, и его отказ означает «мы ещё
+        # ничего не сделали», а не «мы, возможно, уже отправили».
+        try:
+            chat_id = self._plan.chat_of(decision.order_id)
+        except Exception as exc:
+            _log.warning(
+                "заказ %s: узел диалога не прочитан (%s), выдача не состоялась и в реестр "
+                "не записана",
+                decision.order_id,
+                type(exc).__name__,
+            )
+            if self._on_hold is not None:
+                self._on_hold(
+                    DeliveryDecision(
+                        decision.order_id,
+                        False,
+                        "chat_not_read",
+                        offer_id=decision.offer_id,
+                    )
+                )
+            return None
+
+        self._ledger.record(
+            Delivery(
+                order_id=decision.order_id,
+                offer_id=decision.offer_id,
+                at_ms=int(datetime.now(UTC).timestamp() * 1000),
+                outcome=QUEUED_OUTCOME,
+            )
+        )
+        # Сохранение НА ДИСК тоже впереди отправки, и по тому же доводу:
+        # перезапуск между постановкой в очередь и записью выдал бы товар
+        # второй раз.
+        if self._persist is not None:
+            self._persist()
+
+        try:
+            return self._send(
+                chat_id,
+                self._plan.goods[decision.offer_id],
+                f"delivery:{decision.order_id}",
+                self._plan.declared_cold,
+            )
+        except Exception:
+            self._ledger.settle(decision.order_id, "queue_failed")
+            if self._persist is not None:
+                self._persist()
+            if self._on_hold is not None:
+                self._on_hold(
+                    DeliveryDecision(
+                        decision.order_id, False, "queue_failed", offer_id=decision.offer_id
+                    )
+                )
+            raise

funora/bot/_outbox.py

@@ -0,0 +1,261 @@
+"""Очередь исходящих: как попросить об отправке из чужого потока.
+
+ЗАЧЕМ ОНА ВООБЩЕ НУЖНА. Клиент не защищён ни одной блокировкой. Бюджет,
+ограничитель исходящих и состояние сессии - обычные изменяемые объекты, и у
+двух из них проверка с последующей записью не атомарна: ограничитель сперва
+спрашивает `check`, потом пишет `record`, а бюджет сперва резервирует, потом
+списывает.
+
+Второй поток, зовущий отправку напрямую, эти пары разрывает. Проявится это не
+отказом и не исключением, а НЕДОСЧЁТОМ: ограничитель решит, что за час ушло
+меньше сообщений, чем ушло на самом деле. Узнаете вы об этом от площадки.
+
+Поэтому здесь заведён единственный порядок, при котором посторонний поток может
+попросить об отправке: положить задание в очередь. Разбирает её тот же поток,
+что ведёт наблюдение, - в паузе между опросами.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from queue import Empty, Full, Queue
+from typing import Final
+
+from .._runner import SendResult
+
+__all__ = ["SendCommand", "SendTicket", "Outbox"]
+
+#: Сколько заданий очередь принимает, прежде чем отказывать.
+#:
+#: Предел нужен: телеграм-бот, у которого что-то заклинило, наполняет очередь
+#: быстрее, чем наблюдение её вычерпывает - три отправки за шаг против
+#: неограниченного числа нажатий. Очередь без предела съела бы память, а
+#: сообщения всё равно ушли бы с опозданием на часы.
+MAX_PENDING: Final[int] = 256
+
+
+@dataclass(frozen=True, slots=True)
+class SendCommand:
+    """Просьба отправить сообщение.
+
+    Attributes:
+        chat_id (str): Числовой идентификатор диалога.
+        text (str): Текст сообщения.
+        idempotency_key (str): Ключ, по которому повтор узнаётся повтором.
+            Задание с уже виденным ключом не отправляется второй раз.
+
+            Обязателен НАРОЧНО, умолчания у него нет. Отправка необратима:
+            лишнее сообщение покупателю не отменить, а перезапуск процесса,
+            повтор события и нажатие кнопки дважды - обычные вещи. Ключ, который
+            вызывающий обязан придумать сам, заставляет его хотя бы раз подумать
+            о том, что считается тем же самым сообщением.
+        declared_cold (bool): Признание, что переписка холодная и вы пишете
+            первым.
+    """
+
+    chat_id: str
+    text: str
+    idempotency_key: str
+    declared_cold: bool = False
+
+
+@dataclass(slots=True)
+class SendTicket:
+    """Квитанция о принятом задании: чем оно кончилось.
+
+    Ждать её можно из любого потока. Отправка при этом происходит не здесь, а в
+    потоке наблюдения.
+
+    Attributes:
+        command (SendCommand): Задание, о котором квитанция.
+    """
+
+    command: SendCommand
+    _done: threading.Event = field(default_factory=threading.Event)
+    _result: SendResult | None = None
+    _error: Exception | None = None
+    _duplicate: bool = False
+
+    @property
+    def duplicate(self) -> bool:
+        """Сообщает, что задание отброшено как повтор.
+
+        Returns:
+            bool: True, если ключ идемпотентности уже встречался.
+        """
+        return self._duplicate
+
+    def settle(
+        self,
+        *,
+        result: SendResult | None = None,
+        error: Exception | None = None,
+        duplicate: bool = False,
+    ) -> None:
+        """Закрывает квитанцию.
+
+        Args:
+            result (SendResult | None): Исход отправки.
+            error (FunoraError | None): Отказ, если отправка не состоялась.
+            duplicate (bool): Отброшено ли задание как повтор.
+
+        Returns:
+            None
+        """
+        self._result = result
+        self._error = error
+        self._duplicate = duplicate
+        self._done.set()
+
+    def wait(self, timeout: float | None = None) -> SendResult | None:
+        """Ждёт исхода задания.
+
+        Args:
+            timeout (float | None): Сколько секунд ждать. None означает без
+                предела.
+
+        Returns:
+            SendResult | None: Исход отправки. None означает, что задание
+            отброшено как повтор либо ожидание истекло, - различить это можно
+            признаками `duplicate` и `ready`.
+
+        Raises:
+            FunoraError: Тот самый отказ, что случился в потоке наблюдения.
+                Бросается ЗДЕСЬ, в потоке вызывающего: иначе он о нём не узнал
+                бы вовсе - в потоке наблюдения его некому ловить.
+        """
+        self._done.wait(timeout)
+        if self._error is not None:
+            raise self._error
+        return self._result
+
+    @property
+    def ready(self) -> bool:
+        """Сообщает, закрыта ли квитанция.
+
+        Returns:
+            bool: True, если задание уже отработано.
+        """
+        return self._done.is_set()
+
+
+class Outbox:
+    """Очередь исходящих сообщений.
+
+    Класть задания можно из любого потока. Разбирает очередь тот, кто ведёт
+    наблюдение, и только он.
+
+    Args:
+        max_pending (int): Сколько заданий держать, прежде чем отказывать.
+    """
+
+    __slots__ = ("_queue", "_seen", "_lock", "_owner")
+
+    def __init__(self, max_pending: int = MAX_PENDING) -> None:
+        # Ноль и отрицательное у очереди стандартной библиотеки означают БЕЗ
+        # ПРЕДЕЛА - ровно наоборот тому, что читается в имени. Единственный
+        # предел, объявленный здесь обязательным, снимался бы значением,
+        # которое выглядит как «не принимать ничего».
+        if max_pending < 1:
+            from ..errors import ValidationError
+
+            raise ValidationError(
+                f"предел очереди исходящих {max_pending} не годится: очередь "
+                "стандартной библиотеки понимает ноль и отрицательное как "
+                "«без предела», то есть снимает защиту, а не ужесточает её"
+            )
+        self._queue: Queue[SendTicket] = Queue(maxsize=max_pending)
+        # Ключи, которые уже отработаны. Множество растёт, и это осознанно:
+        # забыть ключ значит разрешить повтор, а повтор здесь - второе сообщение
+        # покупателю. Память тут дешевле.
+        self._seen: set[str] = set()
+        self._lock = threading.Lock()
+        self._owner: int | None = None
+
+    def put(self, command: SendCommand) -> SendTicket:
+        """Кладёт задание в очередь.
+
+        Звать можно из любого потока.
+
+        Args:
+            command (SendCommand): Просьба отправить сообщение.
+
+        Returns:
+            SendTicket: Квитанция, по которой можно дождаться исхода.
+
+        Raises:
+            UsageError: Если очередь переполнена.
+        """
+        from ..errors import UsageError
+
+        ticket = SendTicket(command=command)
+
+        with self._lock:
+            if command.idempotency_key in self._seen:
+                # Повтор узнаётся ДО очереди: иначе он занял бы место и дождался
+                # бы своей отбраковки только у исполнителя.
+                ticket.settle(duplicate=True)
+                return ticket
+            try:
+                self._queue.put_nowait(ticket)
+            except Full as exc:
+                raise UsageError(
+                    f"очередь исходящих переполнена: {self._queue.maxsize} заданий ждут отправки"
+                ) from exc
+            self._seen.add(command.idempotency_key)
+
+        return ticket
+
+    def take(self, limit: int) -> list[SendTicket]:
+        """Забирает из очереди до указанного числа заданий.
+
+        Args:
+            limit (int): Сколько заданий забрать.
+
+        Returns:
+            list[SendTicket]: Взятые задания в порядке поступления.
+        """
+        taken: list[SendTicket] = []
+        for _ in range(max(0, limit)):
+            try:
+                taken.append(self._queue.get_nowait())
+            except Empty:
+                break
+        return taken
+
+    def claim(self) -> None:
+        """Запоминает поток, который разбирает очередь.
+
+        Returns:
+            None
+        """
+        from ..errors import UsageError
+
+        with self._lock:
+            if self._owner is not None:
+                raise UsageError("очередь уже принадлежит запущенному циклу бота")
+            self._owner = threading.get_ident()
+
+    def release(self) -> None:
+        """Снимает владение после выхода из цикла."""
+        with self._lock:
+            if self._owner == threading.get_ident():
+                self._owner = None
+
+    def is_owner(self) -> bool:
+        """Сообщает, тот ли это поток, что разбирает очередь.
+
+        Returns:
+            bool: True, если вызов идёт из потока наблюдения.
+        """
+        return self._owner is not None and self._owner == threading.get_ident()
+
+    @property
+    def pending(self) -> int:
+        """Сколько заданий ждёт отправки.
+
+        Returns:
+            int: Длина очереди.
+        """
+        return self._queue.qsize()