funora 0.0.1.dev2__py3-none-any.whl

funora/reconciliation.py

@@ -0,0 +1,51 @@
+r"""Сверка после неоднозначного исхода записи.
+
+Файл порождён из спецификации, править его руками нельзя: правка исчезнет при
+следующей сборке. Источник - spec/protocol/reconciliation.yaml в репозитории Funora-spec.
+Перестроить: .venv\Scripts\python.exe tools/codegen.py
+
+Сверка - ПРОЦЕДУРА НАБЛЮДЕНИЯ, а не петля управления. Она отвечает на
+вопрос «что вышло из отправки» и ничего не предпринимает.
+
+СВЕРКА НИКОГДА НЕ ОТПРАВЛЯЕТ ПОВТОРНО. Решение принимает вызывающий, и
+только он: у отправленного сообщения нет отмены, и автоматика,
+решающая за человека, однажды напишет покупателю дважды.
+
+Вердикта отрицания здесь НЕТ. Отсутствие сообщения в истории -
+свидетельство отрицательное, и объявлять по нему «не отправлено»
+значило бы подтолкнуть вызывающего написать второй раз.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final
+
+__all__ = ["ReconcileVerdict", "RECONCILE_READS", "RECONCILE_DELAYS_MS"]
+
+
+class ReconcileVerdict(StrEnum):
+    """Чем окончилась сверка.
+
+    delivered: Своё новое сообщение найдено в истории. Положительное свидетельство.
+
+    absent_from_history: Чтение полное, признак себя показал себя, искомого сообщения
+        нет.
+
+    undetermined: Сверка ответа не дала. Честное незнание.
+
+    """
+
+    DELIVERED = "delivered"
+    ABSENT_FROM_HISTORY = "absent_from_history"
+    UNDETERMINED = "undetermined"
+
+
+#: Сколько раз перечитывать историю.
+RECONCILE_READS: Final[int] = 3
+
+#: Паузы перед каждым чтением, миллисекунды.
+#:
+#: Числа ВЫБРАНЫ, а не наблюдены: ни одной записанной отправки не
+#: пришлось сверять чтением - все подтверждались самим ответом канала.
+RECONCILE_DELAYS_MS: Final[tuple[int, ...]] = (1000, 3000, 8000)

funora/response_classes.py

@@ -0,0 +1,155 @@
+r"""Соответствие вердиктов классификатора ошибкам.
+
+Файл порождён из спецификации, править его руками нельзя: правка исчезнет при
+следующей сборке. Источник - spec/protocol/response-classes.yaml в репозитории Funora-spec.
+Перестроить: .venv\Scripts\python.exe tools/codegen.py
+
+Ключ - пара из класса ответа и машиночитаемой причины. Значение - класс
+ошибки либо None, если ответ пригоден для разбора.
+
+Таблица порождается, а не пишется, потому что от неё зависит, повторит
+клиент запрос или остановится навсегда. Шесть реализаций, составивших её
+порознь, разойдутся именно на негативных ветках - там, где расхождение
+дороже всего и заметно позже всего.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final
+
+from .errors import (
+    AccessBlockedError,
+    ChallengeRequiredError,
+    NetworkError,
+    ProtocolChangedError,
+    RateLimitedError,
+    RemoteServerError,
+    SessionExpiredError,
+    UnexpectedResponseError,
+)
+
+__all__ = [
+    "VERDICT_ERRORS",
+    "RESPONSE_CLASSES",
+    "STATUS_CLASS",
+    "Health",
+    "INITIAL_HEALTH",
+    "HEALTH_BY_VERDICT",
+    "WRITES_PAUSED_IN",
+]
+
+#: Классы ответа, объявленные спецификацией.
+#:
+#: Перечень нужен, чтобы проверить полноту таблицы: класс без единой
+#: записи означает, что реализации выберут ошибку сами.
+RESPONSE_CLASSES: Final[frozenset[str]] = frozenset(
+    {
+        "ok",
+        "login_required",
+        "challenge",
+        "blocked",
+        "rate_limited",
+        "maintenance",
+        "wrong_identity",
+        "transport_error",
+        "unknown",
+    }
+)
+
+#: Класс ответа по коду, когда тело разбирать бессмысленно.
+#:
+#: Прежде таблица жила рукописной копией в классификаторе. Правка
+#: спецификации не давала ни одного признака: сборка зелёная,
+#: спецификация зелёная, а расхождение обнаружилось бы в работе - и
+#: ровно на той ошибке, от которой спецификация предостерегает
+#: отдельным разделом: код 429, принятый за блокировку, навсегда
+#: останавливает опрос.
+STATUS_CLASS: Final[dict[int, str]] = {
+    401: "login_required",
+    403: "blocked",
+    429: "rate_limited",
+    503: "maintenance",
+}
+
+#: Пара «класс ответа, причина» и ошибка, которую она означает.
+VERDICT_ERRORS: Final[dict[tuple[str, str], type[Exception] | None]] = {
+    ("ok", "identity_confirmed"): None,
+    ("ok", "no_signature_matched_identity_unchecked"): None,
+    ("login_required", "http_401"): SessionExpiredError,
+    ("login_required", "signature:guest_navbar"): SessionExpiredError,
+    ("login_required", "signature:login_page"): SessionExpiredError,
+    ("login_required", "signature:login_form"): SessionExpiredError,
+    ("challenge", "signature:challenge_widget"): ChallengeRequiredError,
+    ("challenge", "signature:challenge_text"): ChallengeRequiredError,
+    ("blocked", "http_403"): AccessBlockedError,
+    ("blocked", "signature:blocked_text"): AccessBlockedError,
+    ("rate_limited", "http_429"): RateLimitedError,
+    ("maintenance", "http_503"): RemoteServerError,
+    ("maintenance", "signature:maintenance_text"): RemoteServerError,
+    ("wrong_identity", "host_mismatch"): UnexpectedResponseError,
+    ("wrong_identity", "host_unreadable"): UnexpectedResponseError,
+    ("transport_error", "http_5xx"): RemoteServerError,
+    ("transport_error", "http_4xx"): UnexpectedResponseError,
+    ("transport_error", "body_truncated"): NetworkError,
+    ("unknown", "empty_body"): UnexpectedResponseError,
+    ("unknown", "identity_marker_absent"): ProtocolChangedError,
+    ("unknown", "body_unparsable"): UnexpectedResponseError,
+}
+
+
+class Health(StrEnum):
+    """Состояние доступа к площадке.
+
+    От него зависит, приостановлена ли автоматика записи. Перечень
+    объявлен схемой события protocol.health_changed и повторён в
+    spec/protocol/response-classes.yaml вместе с правилами перехода.
+    """
+
+    AUTHENTICATED = "authenticated"
+    DEGRADED = "degraded"
+    PROTOCOL_CHANGED = "protocol_changed"
+    RATE_LIMITED = "rate_limited"
+    CHALLENGED = "challenged"
+    BLOCKED = "blocked"
+
+
+#: Начальное состояние.
+#:
+#: До первого ответа состояние не проверяется: клиент не знает о
+#: площадке ничего, пока не сходил.
+INITIAL_HEALTH: Final[Health] = Health.AUTHENTICATED
+
+#: В какое состояние переводит класс ответа.
+#:
+#: None означает «состояние не меняется». Сетевой отказ и
+#: неопознанный ответ говорят о нас и о дороге, а не о том, как
+#: площадка к нам относится: менять по ним состояние доступа значило
+#: бы объявлять аккаунт ограниченным из-за оборванного соединения.
+HEALTH_BY_VERDICT: Final[dict[str, Health | None]] = {
+    "ok": Health.AUTHENTICATED,
+    "login_required": Health.DEGRADED,
+    "challenge": Health.CHALLENGED,
+    "blocked": Health.BLOCKED,
+    "rate_limited": Health.RATE_LIMITED,
+    "maintenance": Health.DEGRADED,
+    "wrong_identity": Health.DEGRADED,
+    "transport_error": None,
+    "unknown": None,
+}
+
+#: Состояния, в которых автоматика записи приостановлена.
+#:
+#: Возобновление - только явным действием пользователя либо
+#: возвратом в начальное состояние по успешному ответу. Сама по себе
+#: пауза не истекает: истекающая означала бы, что клиент снова пишет
+#: на площадку, которая только что отказала, и не спросил никого.
+WRITES_PAUSED_IN: Final[frozenset[Health]] = frozenset(
+    {
+        Health.DEGRADED,
+        Health.PROTOCOL_CHANGED,
+        Health.RATE_LIMITED,
+        Health.CHALLENGED,
+        Health.BLOCKED,
+    }
+)

funora/retry.py

@@ -0,0 +1,238 @@
+r"""Политики повторов.
+
+Файл порождён из спецификации, править его руками нельзя: правка исчезнет при
+следующей сборке. Источник - spec/protocol/retry-policy.yaml в репозитории Funora-spec.
+Перестроить: .venv\Scripts\python.exe tools/codegen.py
+
+Числа не выбираются реализацией. Отступление, синхронизированное между
+шестью SDK, превращается в согласованную волну запросов, и площадка
+видит не шесть вежливых клиентов, а один невежливый.
+
+Запасная политика намеренно строже конкретных: неизвестный класс отказа
+не повод быть смелее.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Final
+
+__all__ = [
+    "RetryPolicy",
+    "RETRY_POLICIES",
+    "FALLBACK_POLICY",
+    "GLOBAL_MAX_ATTEMPTS",
+    "RetryDecision",
+    "DECISION_MATRIX",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    """Политика повторов для одного класса ошибки.
+
+    Attributes:
+        stable_id (str): Устойчивый идентификатор класса ошибки.
+        max_attempts (int): Сколько попыток допустимо всего, включая первую.
+        base_ms (int): Основа задержки, миллисекунды.
+        multiplier (float): Во сколько раз растёт задержка.
+        cap_ms (int): Потолок задержки, миллисекунды.
+        jitter (str): Вид разброса.
+        respect_retry_after (bool): Уважать ли заголовок Retry-After.
+        max_retry_after_ms (int): Верхняя граница уважения заголовка.
+        fail_closed (bool): Останавливать ли работу до вмешательства.
+        account_scoped (bool): Действует ли ограничение на весь аккаунт.
+    """
+
+    stable_id: str
+    max_attempts: int
+    base_ms: int
+    multiplier: float
+    cap_ms: int
+    jitter: str
+    respect_retry_after: bool
+    max_retry_after_ms: int
+    fail_closed: bool
+    account_scoped: bool
+
+
+#: Политика по устойчивому идентификатору класса ошибки.
+RETRY_POLICIES: Final[dict[str, RetryPolicy]] = {
+    "funora.transport": RetryPolicy(
+        stable_id="funora.transport",
+        max_attempts=2,
+        base_ms=1000,
+        multiplier=2.0,
+        cap_ms=15000,
+        jitter="full",
+        respect_retry_after=True,
+        max_retry_after_ms=300000,
+        fail_closed=False,
+        account_scoped=False,
+    ),
+    "funora.transport.timeout": RetryPolicy(
+        stable_id="funora.transport.timeout",
+        max_attempts=3,
+        base_ms=1000,
+        multiplier=2.0,
+        cap_ms=30000,
+        jitter="full",
+        respect_retry_after=False,
+        max_retry_after_ms=300000,
+        fail_closed=False,
+        account_scoped=False,
+    ),
+    "funora.transport.network": RetryPolicy(
+        stable_id="funora.transport.network",
+        max_attempts=3,
+        base_ms=500,
+        multiplier=2.0,
+        cap_ms=30000,
+        jitter="full",
+        respect_retry_after=False,
+        max_retry_after_ms=300000,
+        fail_closed=False,
+        account_scoped=False,
+    ),
+    "funora.transport.rate_limited": RetryPolicy(
+        stable_id="funora.transport.rate_limited",
+        max_attempts=2,
+        base_ms=5000,
+        multiplier=3.0,
+        cap_ms=120000,
+        jitter="full",
+        respect_retry_after=True,
+        max_retry_after_ms=300000,
+        fail_closed=False,
+        account_scoped=True,
+    ),
+    "funora.transport.remote_server": RetryPolicy(
+        stable_id="funora.transport.remote_server",
+        max_attempts=3,
+        base_ms=2000,
+        multiplier=2.0,
+        cap_ms=60000,
+        jitter="full",
+        respect_retry_after=True,
+        max_retry_after_ms=300000,
+        fail_closed=False,
+        account_scoped=False,
+    ),
+    "funora.auth.invalid_credentials": RetryPolicy(
+        stable_id="funora.auth.invalid_credentials",
+        max_attempts=1,
+        base_ms=0,
+        multiplier=1.0,
+        cap_ms=0,
+        jitter="full",
+        respect_retry_after=False,
+        max_retry_after_ms=300000,
+        fail_closed=False,
+        account_scoped=False,
+    ),
+    "funora.auth.session_expired": RetryPolicy(
+        stable_id="funora.auth.session_expired",
+        max_attempts=1,
+        base_ms=0,
+        multiplier=1.0,
+        cap_ms=0,
+        jitter="full",
+        respect_retry_after=False,
+        max_retry_after_ms=300000,
+        fail_closed=False,
+        account_scoped=False,
+    ),
+    "funora.auth.access_blocked": RetryPolicy(
+        stable_id="funora.auth.access_blocked",
+        max_attempts=1,
+        base_ms=0,
+        multiplier=1.0,
+        cap_ms=0,
+        jitter="full",
+        respect_retry_after=False,
+        max_retry_after_ms=300000,
+        fail_closed=True,
+        account_scoped=False,
+    ),
+    "funora.auth.challenge_required": RetryPolicy(
+        stable_id="funora.auth.challenge_required",
+        max_attempts=1,
+        base_ms=0,
+        multiplier=1.0,
+        cap_ms=0,
+        jitter="full",
+        respect_retry_after=False,
+        max_retry_after_ms=300000,
+        fail_closed=True,
+        account_scoped=False,
+    ),
+    "funora.protocol.changed": RetryPolicy(
+        stable_id="funora.protocol.changed",
+        max_attempts=1,
+        base_ms=0,
+        multiplier=1.0,
+        cap_ms=0,
+        jitter="full",
+        respect_retry_after=False,
+        max_retry_after_ms=300000,
+        fail_closed=False,
+        account_scoped=False,
+    ),
+    "funora.budget.exhausted": RetryPolicy(
+        stable_id="funora.budget.exhausted",
+        max_attempts=1,
+        base_ms=0,
+        multiplier=1.0,
+        cap_ms=0,
+        jitter="full",
+        respect_retry_after=False,
+        max_retry_after_ms=300000,
+        fail_closed=False,
+        account_scoped=False,
+    ),
+}
+
+#: Политика для классов ошибок без собственной записи.
+#:
+#: Строже конкретных намеренно: неизвестный класс отказа не повод быть
+#: смелее. Реализация, подставляющая здесь самую щедрую политику,
+#: получает самое агрессивное поведение как раз тогда, когда меньше
+#: всего понимает происходящее.
+FALLBACK_POLICY: Final[RetryPolicy] = RETRY_POLICIES["funora.transport"]
+
+#: Потолок числа попыток независимо от политики класса ошибки.
+GLOBAL_MAX_ATTEMPTS: Final[int] = 5
+
+
+class RetryDecision(StrEnum):
+    """Что матрица говорит о повторе.
+
+    Решение о повторе - пересечение класса ошибки и безопасности
+    операции. Реализация, сводящая матрицу к «повторяем только
+    чтения», строже контракта: это безопасно, но расходится -
+    второй SDK на той же трассе поступит иначе.
+    """
+
+    NEVER = "never"
+    ALLOWED = "allowed"
+    ALLOWED_WITH_KEY = "allowed_with_key"
+    RECONCILE_FIRST = "reconcile_first"
+
+
+#: Строки матрицы решения о повторе, в порядке спецификации.
+#:
+#: Порядок значим: строки читаются сверху вниз, и первая подошедшая
+#: решает. Первая строка отсекает неповторяемый класс ошибки
+#: независимо от операции.
+#:
+#: Кортеж: повторяем ли класс ошибки; безопасность операции либо
+#: None, если строка о любой; возможен ли побочный эффект либо None,
+#: если неважно; решение.
+DECISION_MATRIX: Final[tuple[tuple[bool, str | None, bool | None, RetryDecision], ...]] = (
+    (False, None, None, RetryDecision.NEVER),
+    (True, "safe", None, RetryDecision.ALLOWED),
+    (True, "idempotent", None, RetryDecision.ALLOWED_WITH_KEY),
+    (True, "unsafe", True, RetryDecision.RECONCILE_FIRST),
+    (True, "unsafe", False, RetryDecision.ALLOWED),
+)

funora/send_outcome.py

@@ -0,0 +1,78 @@
+r"""Исход обращения к каналу обновлений с действием.
+
+Файл порождён из спецификации, править его руками нельзя: правка исчезнет при
+следующей сборке. Источник - spec/protocol/send-outcome.yaml в репозитории Funora-spec.
+Перестроить: .venv\Scripts\python.exe tools/codegen.py
+
+Три исхода, а не два. Третий - unconfirmed - честное незнание, а не
+третий род неудачи: отправка могла состояться и могла не состояться.
+
+Двузначный ответ вынудил бы реализацию выбрать одно из двух зол.
+Объявить успехом всё, что вернулось с кодом 200, значит однажды сказать
+«отправлено» о неотправленном. Объявить неудачей значит однажды
+отправить второй раз, а отменить сообщение покупателю нельзя.
+
+Порядок шагов нормативен и объявлен в спецификации. Здесь он
+порождается перечнем, чтобы проверка могла пройти по нему, а не по
+прозе.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final
+
+__all__ = ["SendOutcome", "SEND_REASONS", "SEND_PIPELINE"]
+
+
+class SendOutcome(StrEnum):
+    """Чем окончилось обращение к каналу с действием.
+
+    confirmed: Площадка вернула сообщение в ответе. Отправка состоялась, и это
+        ПОЛОЖИТЕЛЬНОЕ свидетельство, а не отсутствие отказа.
+
+    refused: Площадка сообщила об отказе. Сообщение не отправлено.
+
+    unconfirmed: Ответ получен, но подтверждения в нём нет. Отправка могла состояться и
+        могла не состояться, и вызывающему сказано именно это.
+
+    """
+
+    CONFIRMED = "confirmed"
+    REFUSED = "refused"
+    UNCONFIRMED = "unconfirmed"
+
+
+#: Причины решения. Машиночитаемы и закрыты.
+SEND_REASONS: Final[dict[str, str]] = {
+    "transport_error": "Ответ после отправки не получен; запрос мог быть исполнен.",
+    "unexpected_http_status": "HTTP-статус ответа не подтверждает исполнение действия.",
+    "confirmed_by_channel": "Ответ несёт новое сообщение в том самом диалоге.",
+    "channel_reported_error": "Поле error непусто. Что именно в нём - неизвестно.",
+    "body_not_json": "Тело ответа не разобралось.",
+    "body_not_an_object": "Разобранное - не объект.",
+    "response_not_an_object": "Поле response не объект, а значит ответ не на действие.",
+    "response_error_missing": "В объекте response отсутствует обязательное поле error.",
+    "no_chat_node_in_answer": "Среди объектов ответа нет узла диалога.",
+    "node_mismatch": "Узел диалога в ответе - не тот, в который отправляли.",
+    "empty_message_list": "Узел диалога есть, новых сообщений в нём нет.",
+}
+
+#: Порядок шагов. НОРМАТИВЕН: две реализации, проверившие условия
+#: в разном порядке, разойдутся ровно на том ответе, ради которого
+#: правило написано.
+#:
+#: Каждый шаг - имя, исход при непрохождении и причина.
+SEND_PIPELINE: Final[tuple[tuple[str, str, str], ...]] = (
+    ("Ответ транспорта получен", "unconfirmed", "transport_error"),
+    ("HTTP-статус ответа допускает подтверждение", "unconfirmed", "unexpected_http_status"),
+    ("Тело разбирается как JSON", "unconfirmed", "body_not_json"),
+    ("Разобранное - объект", "unconfirmed", "body_not_an_object"),
+    ("Поле response - объект", "unconfirmed", "response_not_an_object"),
+    ("В объекте response есть поле error", "unconfirmed", "response_error_missing"),
+    ("Поле error пусто", "refused", "channel_reported_error"),
+    ("Среди объектов есть узел диалога", "unconfirmed", "no_chat_node_in_answer"),
+    ("Узел диалога - тот самый", "unconfirmed", "node_mismatch"),
+    ("Список сообщений непуст", "unconfirmed", "empty_message_list"),
+    ("Подтверждено", "confirmed", "confirmed_by_channel"),
+)

funora/skeleton_format.py

@@ -0,0 +1,77 @@
+r"""Формат структурного скелета страницы.
+
+Файл порождён из спецификации, править его руками нельзя: правка исчезнет при
+следующей сборке. Источник - spec/conformance/skeleton-format.yaml в репозитории Funora-spec.
+Перестроить: .venv\Scripts\python.exe tools/codegen.py
+
+Формат снимков страниц. Снимки - общая проверочная база: по ним
+сверяется, что объявленный селектор вправду присутствует на
+наблюдённой странице.
+
+Версия формата и набор классов знаков порождаются, а не пишутся здесь.
+Прежде версия была литералом в _skeleton.py, а описание формата жило
+только в README фикстур эталонной реализации: вторая реализация не
+могла ни построить такой же скелет, ни проверить, что построила.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+__all__ = [
+    "SKELETON_FORMAT",
+    "ACCEPTED_SKELETON_FORMATS",
+    "NUMBERED_SKELETON_FORMATS",
+    "CHARACTER_CLASSES",
+]
+
+
+#: Версия формата, которой снимаются новые скелеты.
+SKELETON_FORMAT: Final[str] = "structural-skeleton-v9"
+
+#: Версии, которые разрешено читать.
+#:
+#: Старые версии принимаются, а не отвергаются: снимок стоит
+#: живого запроса под сессией, и переснять его бывает нечем -
+#: истечение сессии воспроизводится не по желанию.
+ACCEPTED_SKELETON_FORMATS: Final[frozenset[str]] = frozenset(
+    {
+        "structural-skeleton-v3",
+        "structural-skeleton-v4",
+        "structural-skeleton-v5",
+        "structural-skeleton-v6",
+        "structural-skeleton-v7",
+        "structural-skeleton-v8",
+        "structural-skeleton-v9",
+    }
+)
+
+#: Версии, в которых идентификаторы различимы между собой.
+#:
+#: Пока они схлопывались в одну подпись, всякая проверка курсора,
+#: гашения и порождения событий проходила впустую и выглядела при
+#: этом пройденной. Требовать различимости от снимка версии v3
+#: нечестно - восстановить её он не может, - а от прочих обязательно.
+NUMBERED_SKELETON_FORMATS: Final[frozenset[str]] = frozenset(
+    {
+        "structural-skeleton-v4",
+        "structural-skeleton-v5",
+        "structural-skeleton-v6",
+        "structural-skeleton-v7",
+        "structural-skeleton-v8",
+        "structural-skeleton-v9",
+    }
+)
+
+#: Классы знаков, из которых складывается подпись текста.
+#:
+#: Две реализации с разными наборами дадут разные подписи одному
+#: тексту, и снимок одной перестанет годиться другой.
+CHARACTER_CLASSES: Final[dict[str, str]] = {
+    "a": "Латиница любого регистра.",
+    "c": "Кириллица любого регистра.",
+    "d": "Цифры.",
+    "o": "Всё прочее.",
+    "p": "Пунктуация ASCII.",
+    "s": "Пробельные знаки.",
+}