diff --git a/app/channels/MAX_SETUP.md b/app/channels/MAX_SETUP.md new file mode 100644 index 0000000..f612b24 --- /dev/null +++ b/app/channels/MAX_SETUP.md @@ -0,0 +1,150 @@ +# Подключение будущего бота MAX + +Серверная часть готова к подключению. Сам бот ещё не создан, секреты не заполнены, +реальная отправка не включена. Изменений интерфейса сайта в этой поставке нет. +Интеграция уведомляет **самого пациента**; врачебные оповещения остаются в существующем канале проекта. + +## Что реализовано + +- Одноразовая ссылка для привязки аккаунта MAX к текущему пациенту сайта, срок по умолчанию 10 минут. +- Подтверждение подключения, `/help`, `/stop`, отключение при остановке или удалении бота в MAX. +- Нейтральные напоминания из существующего планировщика сайта: тесты, дневник, приём лекарств и другие события outbox. +- Уведомление о завершении теста: сервер каждые примерно 30 секунд находит новые завершённые + `QuestionnaireRecord` и `ScaleResult`, начиная с момента подключения MAX. Незавершённые и старые тесты не отправляются. +- Постоянная очередь, восстановление после перезапуска, ограниченные повторы при сетевых ошибках и ответах 429/5xx. +- В сообщении только короткий текст и кнопка на сайт. Ответы, оценки, диагнозы, назначения и ключ входа на сайт + в MAX не передаются. Переписка с ботом не сохраняется и не отправляется в LLM. + +## 1. Создать бота — будущему владельцу + +1. Открыть [MAX для партнёров](https://business.max.ru/) и пройти регистрацию/проверку профиля. + Условия допуска зависят от типа владельца; актуальный порядок — в + [официальной инструкции подключения](https://dev.max.ru/help/platform_connection). +2. Создать чат-бота, оформить описание и пройти требуемую MAX модерацию. +3. В настройках бота получить токен и скопировать имя из его публичной ссылки `https://max.ru/ИМЯ`. +4. Передать администратору сервера имя бота, а токен — через защищённое хранилище секретов. + Токен не нужен в переписке, MR или репозитории. + +## 2. Заполнить настройки сервера + +Нужны доступная identity/clinical БД проекта, публичный HTTPS-адрес сайта и HTTPS-адрес API на порту 443. +Входящие POST от MAX должны доходить до API без браузерной CAPTCHA или страницы авторизации. +Прокси должен передавать заголовок `X-Max-Bot-Api-Secret` и не журналировать тело webhook/Authorization. +Дополнительные таблицы identity создаются существующим `init_db()` при запуске приложения. + +В `.env` сервера (вне Git) заполнить: + +```dotenv +MAX_ENABLED=false +MAX_BOT_TOKEN= +MAX_BOT_USERNAME= +MAX_WEBHOOK_SECRET= +MAX_WEBHOOK_URL=https://api.example.org/api/v1/webhooks/max +MAX_SITE_URL=https://patient.example.org/ +MAX_LINK_TTL_SECONDS=600 +# При необходимости — PEM-файл доверенного CA, доступный внутри контейнера: +MAX_CA_BUNDLE= +DEMO_CLOCK=false +``` + +- `MAX_BOT_USERNAME` — только имя, без `@`, домена или параметров ссылки. +- `MAX_WEBHOOK_SECRET` — отдельная случайная строка, не токен бота: 32–256 символов из `A–Z a–z 0–9 _ -`. + Сгенерировать локально, например `python -c 'import secrets; print(secrets.token_urlsafe(32))'`, сохранить в секреты. +- `MAX_SITE_URL` ведёт в обычный личный кабинет; не добавлять в адрес ключи доступа или данные пациента. +- Исходящие запросы идут на `https://platform-api2.max.ru`, токен передаётся заголовком `Authorization`. + Верификация TLS всегда включена. Если системе нужен корневой сертификат Минцифры, установить его по + официальной инструкции MAX и указать PEM-путь в `MAX_CA_BUNDLE`; не отключать проверку TLS. +- Переменные должны попасть именно в окружение API-контейнера/процесса, а не только панели сайта. + В текущем Compose сервис `app` уже получает `.env` через `env_file`. + После изменения окружения пересоздать процесс/контейнер API. Новые зависимости не требуются. + +## 3. Проверить и включить + +В каталоге проекта, в том же окружении, где работает API: + +```sh +uv run python -m app.channels.max_setup check +``` + +Команда проверит токен и совпадение имени бота. Сообщений пользователям она не отправляет. +Затем установить `MAX_ENABLED=true`, перезапустить API и выполнить: + +```sh +uv run python -m app.channels.max_setup subscribe +uv run python -m app.channels.max_setup status +``` + +`subscribe` регистрирует только заданный webhook с секретом и событиями +`bot_started`, `message_created`, `bot_stopped`, `dialog_removed`. Старые чужие подписки автоматически +не удаляются: при переносе сервера владелец должен проверить их отдельно через MAX API. +`status` проверяет регистрацию адреса; это ещё не проверка доступности сервера из MAX. +Команды не печатают токены, секрет webhook или сырые ответы платформы. + +При запуске через Compose вместо `uv run python ...` использовать +`docker compose exec app python -m app.channels.max_setup check` (также `subscribe` и `status`). +После изменения `.env` пересоздать API: `docker compose up -d --build --force-recreate app`. + +Запускать один процесс API с MAX на один токен бота: его worker отправляет до одного сообщения в секунду. +БД защищает очередь от параллельного захвата, но общий лимит скорости нескольких процессов не координируется. +Планировщик и MAX worker запускаются вместе с FastAPI, отдельный процесс бота не нужен. +При `MAX_ENABLED=false` сетевых вызовов MAX и фонового worker нет; сайт продолжает обычную работу. + +## API для разработчика сайта + +В проекте используется ключ текущего пациента, полученный при входе. Для этих ручек передавать его +как `Authorization: Bearer `; это существующая авторизация прототипа, не новая система SSO. +Не брать token другого пациента и не публиковать демонстрационные учётные записи для реального использования. + +| Метод и путь | Запрос | Ответ | +|---|---|---| +| `GET /api/v1/me/notifications/max` | Authorization | `available`, `connected`, `last_delivery` | +| `POST /api/v1/me/notifications/max/link` | Authorization; JSON `{"consent": true}` | `url`, `expires_at` | +| `DELETE /api/v1/me/notifications/max` | Authorization | состояние с `connected: false` | +| `POST /api/v1/webhooks/max` | MAX JSON + `X-Max-Bot-Api-Secret` | `{"success": true}` после записи события | + +Поток подключения: пациент явно соглашается на уведомления → сайт получает `url` → открывает ссылку MAX → +пользователь запускает бота → webhook подтверждает привязку → повторный GET показывает `connected: true`. +Ссылка одноразовая; новая ссылка отменяет предыдущую. Изначальный ключ пациента не входит в URL MAX. +Для привязки и доставки дополнительно нужны действующее согласие и подтверждение совершеннолетия в состоянии пациента. +Активную привязку нельзя молча переназначить другому аккаунту: сначала отключить её. + +Коды ошибок: 401 — неизвестный/отсутствующий ключ пациента; 403 — нет согласия или неверный секрет webhook; +422 — неверный запрос; 413 — webhook больше 64 КиБ; 503 — MAX выключен или хранилище события недоступно. +Повтор webhook с тем же идентификатором события не создаёт новых отправок. Групповые чаты игнорируются. + +`last_delivery`: `queued`, `sending`, `sent`, `failed`, `cancelled` или `null`. +`sent` означает принятие сообщения API MAX, а не прочтение человеком. + +## Пробное подключение после создания бота + +1. Войти на сайте синтетическим пациентом и дать необходимые согласия. +2. Получить ссылку через POST выше (Swagger `/docs` или будущий интерфейс сайта), перейти в MAX и запустить бота. +3. Убедиться, что GET показывает `connected: true` и приходит подтверждение. +4. Завершить тест на сайте; примерно через 30 секунд плюс очередь должно прийти сообщение без результатов. +5. Дождаться события планировщика и проверить нейтральное напоминание с кнопкой на сайт. +6. Отправить `/stop`: GET должен показать `connected: false`, ожидающие уведомления отменяются. +7. Повторить подключение новой ссылкой, проверить DELETE через API и остановку бота через интерфейс MAX. + +При недоставке проверить настройки и подписку, доступность HTTPS, состояние очереди и коды ошибок в логах. +`http_401`/`http_403` требуют проверки токена/прав; `http_429` — ожидания; `transport` — сети/TLS; +`failed` после шести попыток требует вмешательства администратора. Детали ответов и идентификаторы в логи не выводятся. +Отключение отменяет очередь; уже принятый MAX запрос отозвать невозможно. + +## Гарантии и ограничения + +Очередь и подтверждения событий сохраняются в identity БД. Клинические записи остаются в clinical БД. +Для событий завершения тестов БД повторно просматривается после перезапуска; ключи уведомлений предотвращают +повторную постановку. Напоминания используют существующий механизм outbox/повторов планировщика. +При временных ошибках — до 6 попыток с увеличением задержки и учётом `Retry-After`; зависшая отправка получает +новую аренду через 60 секунд. Потеря процесса между принятием сообщения MAX и записью успеха в БД может +привести к повторному сообщению: MAX не предоставляет ключ идемпотентности отправки. +Не удалять строки дедупликации/очереди без согласованной политики хранения. При большом количестве пациентов +нужны пакетное сканирование завершённых тестов и общий ограничитель скорости; текущая реализация рассчитана на MVP. + +Проверки разработчика: `make lint test`; тесты MAX работают с синтетикой и подменённым HTTP-транспортом. +Реальную доставку подтвердит только пробное подключение после выдачи токена и настройки публичного сервера. + +Официальные контракты: [отправка сообщений](https://dev.max.ru/docs-api/methods/POST/messages), +[подписка webhook](https://dev.max.ru/docs-api/methods/POST/subscriptions), +[события](https://dev.max.ru/docs-api/objects/Update), +[ссылки запуска бота](https://dev.max.ru/docs/chatbots/bots-coding/prepare). diff --git a/app/channels/max_bot.py b/app/channels/max_bot.py new file mode 100644 index 0000000..e2a2dc6 --- /dev/null +++ b/app/channels/max_bot.py @@ -0,0 +1,224 @@ +"""Notifications-only MAX adapter; no patient text enters the dialog engine or an LLM. + +Webhook transactions persist receipts and replies together, then return immediately. +The worker delivers from identity DB with leases and bounded retries. MAX has no send +idempotency key: a crash after API acceptance and before commit can duplicate a message. +""" + +import asyncio +import contextlib +import json +import logging +from functools import lru_cache + +import yaml +from pydantic import BaseModel, Field +from sqlalchemy import select +from sqlalchemy.exc import IntegrityError + +from app.channels.max_client import MaxApiError, MaxClient +from app.config import get_settings +from app.core import clock +from app.db.max_notifications import MaxBinding, MaxReceipt +from app.db.session import get_identity_session +from app.dialog.contracts import Reply +from app.integrations import max_store as store +from app.integrations.base import Outbox, integrations + +log = logging.getLogger(__name__) + + +class Texts(BaseModel): + connected: str = Field(max_length=4000) + not_connected: str = Field(max_length=4000) + invalid: str = Field(max_length=4000) + stopped: str = Field(max_length=4000) + help: str = Field(max_length=4000) + notification: str = Field(max_length=4000) + completed: str = Field(max_length=4000) + open_site: str = Field(max_length=128) + + +@lru_cache +def texts() -> Texts: + path = get_settings().config_dir / "texts" / "max.yaml" + return Texts.model_validate(yaml.safe_load(path.read_text(encoding="utf-8"))) + + +def _event(event: dict) -> tuple[str, int, str, str] | None: + """Normalize only documented private-user events; unknown/malformed events are ignored.""" + kind = event.get("update_type") + stamp = event.get("timestamp") + if type(stamp) is not int or stamp < 0: + return None + message_id = "" + if kind == "message_created": + message = event.get("message") + if not isinstance(message, dict): + return None + recipient, body = message.get("recipient"), message.get("body") + if not isinstance(recipient, dict) or recipient.get("chat_type") != "dialog" or not isinstance(body, dict): + return None + user, text, message_id = message.get("sender"), body.get("text"), body.get("mid") + if not isinstance(message_id, str) or not message_id or not isinstance(text, str): + return None + elif kind in ("bot_started", "bot_stopped", "dialog_removed"): + user, text = event.get("user"), event.get("payload") or "" + else: + return None + if not isinstance(user, dict) or user.get("is_bot") is not False: + return None + uid = user.get("user_id") + if type(uid) is not int or not 0 < uid < 2**63 or not isinstance(text, str) or len(text) > 4000: + return None + # Names, profile details and raw text are neither persisted nor logged. + receipt = store.digest(f"{kind}:{uid}:{message_id or stamp}") + return kind, uid, text.strip(), receipt + + +async def handle_update(event: dict) -> None: + if not get_settings().max_enabled or (parsed := _event(event)) is None: + return + kind, user_id, text, receipt = parsed + now = clock.now() + try: + async with get_identity_session() as session: + if await session.get(MaxReceipt, receipt): + return + session.add(MaxReceipt(digest=receipt, received_at=now)) + await session.flush() + binding = await session.scalar(select(MaxBinding).where(MaxBinding.user_id == user_id)) + reply_token = None + command, _, payload = text.partition(" ") + if kind in ("bot_stopped", "dialog_removed") or command.lower() == "/stop": + if binding: + await store.disconnect(session, binding.token) + # When MAX itself stops/deletes the bot, do not attempt a reply. + if kind != "message_created": + return + reply = "stopped" + elif kind == "bot_started" or command.lower() == "/start": + code = text if kind == "bot_started" else payload.strip() + if code: + token = await store.code_token(session, code, now) if len(code) <= 128 else None + linked = ( + token and await store.active_patient(token) and await store.bind(session, code, user_id, now) + ) + reply = "connected" if linked else "invalid" + reply_token = token if linked else None + else: + reply = "connected" if binding and binding.enabled else "not_connected" + reply_token = binding.token if binding and binding.enabled else None + else: + reply = "help" + await store.enqueue(session, key=receipt, user_id=user_id, token=reply_token, kind=reply, now=now) + except IntegrityError: + # A concurrent delivery of the same webhook can race on its receipt primary key. + async with get_identity_session() as session: + if await session.get(MaxReceipt, receipt) is None: + raise + + +class MaxOutbox: + def __init__(self, fallback: Outbox): + self.fallback = fallback + + async def push(self, token: str, replies: list[Reply]) -> None: + if replies and get_settings().max_enabled and await store.active_patient(token): + async with get_identity_session() as session: + binding = await session.get(MaxBinding, token) + if binding and binding.enabled: + # Hash the event for retry deduplication; never store/transmit its clinical text. + event = json.dumps([r.model_dump() for r in replies], sort_keys=True, ensure_ascii=False) + key = store.digest(f"{token}:{binding.connected_at.isoformat()}:{clock.today()}:{event}") + await store.enqueue( + session, key=key, user_id=binding.user_id, token=token, kind="notification", now=clock.now() + ) + await self.fallback.push(token, replies) + + +async def deliver_one(client: MaxClient) -> bool: + async with get_identity_session() as session: + row = await store.claim(session, clock.now()) + if row is None: + return False + if row.token is not None: + async with get_identity_session() as session: + binding = await session.get(MaxBinding, row.token) + valid = ( + binding + and binding.enabled + and binding.user_id == row.user_id + and binding.connected_at <= row.created_at + ) + if not valid or not await store.active_patient(row.token): + async with get_identity_session() as session: + await store.finish(session, row, state="cancelled", now=clock.now()) + return True + settings, messages = get_settings(), texts() + try: + await client.send( + row.user_id, getattr(messages, row.kind), site_url=settings.max_site_url, button=messages.open_site + ) + except MaxApiError as exc: + retry = exc.retryable and row.attempts < store.MAX_ATTEMPTS + delay = max(exc.retry_after, min(300, 5 * 2 ** (row.attempts - 1))) + async with get_identity_session() as session: + await store.finish( + session, + row, + state="queued" if retry else "failed", + now=clock.now(), + error=exc.code, + retry_seconds=delay if retry else 0, + ) + log.warning("MAX delivery deferred=%s code=%s", retry, exc.code) + else: + async with get_identity_session() as session: + await store.finish(session, row, state="sent", now=clock.now()) + return True + + +async def _run(client: MaxClient) -> None: + tick = 0 + while True: + try: + if tick % 30 == 0: + async with get_identity_session() as session: + await store.collect_completed(session, clock.now()) + await deliver_one(client) + except Exception as exc: + # No exception text: SQL/HTTP errors may contain identifiers or parameters. + log.error("MAX worker failed type=%s", type(exc).__name__) + tick += 1 + # One send per second per process, below MAX's two-per-second per-dialog limit. + await asyncio.sleep(1) + + +_client: MaxClient | None = None +_task: asyncio.Task | None = None +_wrapper: MaxOutbox | None = None + + +async def start() -> None: + global _client, _task, _wrapper + if not get_settings().max_enabled or _task is not None: + return + texts() # Validate templates before replacing a working outbox. + _client = MaxClient(get_settings()) + _wrapper = MaxOutbox(integrations.outbox) + integrations.outbox = _wrapper + _task = asyncio.create_task(_run(_client), name="max-notifications") + + +async def stop() -> None: + global _client, _task, _wrapper + if _task: + _task.cancel() + with contextlib.suppress(asyncio.CancelledError): + await _task + if _wrapper and integrations.outbox is _wrapper: + integrations.outbox = _wrapper.fallback + if _client: + await _client.close() + _client = _task = _wrapper = None diff --git a/app/channels/max_client.py b/app/channels/max_client.py new file mode 100644 index 0000000..1282423 --- /dev/null +++ b/app/channels/max_client.py @@ -0,0 +1,101 @@ +"""Small MAX Bot API client. Secrets stay in headers; failures never expose response bodies.""" + +import logging +import ssl + +import httpx + +from app.config import Settings + +API_URL = "https://platform-api2.max.ru" +UPDATE_TYPES = ["bot_started", "message_created", "bot_stopped", "dialog_removed"] + + +class _HideRecipient(logging.Filter): + def filter(self, record: logging.LogRecord) -> bool: + # httpx INFO normally logs query strings, which include a MAX user_id. + return "platform-api2.max.ru" not in record.getMessage() + + +logging.getLogger("httpx").addFilter(_HideRecipient()) + + +class MaxApiError(Exception): + def __init__(self, code: str, *, retryable: bool = False, retry_after: float = 0): + self.code, self.retryable, self.retry_after = code, retryable, retry_after + super().__init__(code) + + +class MaxClient: + def __init__(self, settings: Settings, *, transport: httpx.AsyncBaseTransport | None = None): + context = ssl.create_default_context() + if settings.max_ca_bundle: + context.load_verify_locations(cafile=str(settings.max_ca_bundle)) + self.http = httpx.AsyncClient( + base_url=API_URL, + headers={"Authorization": settings.max_bot_token.get_secret_value()}, + timeout=httpx.Timeout(5), + verify=context, + follow_redirects=False, + transport=transport, + ) + + async def close(self) -> None: + await self.http.aclose() + + async def request(self, method: str, path: str, **kwargs) -> dict: + try: + response = await self.http.request(method, path, **kwargs) + except httpx.RequestError: + raise MaxApiError("transport", retryable=True) from None + if not response.is_success: + try: + delay = min(3600, max(0, float(response.headers.get("Retry-After", "0")))) + except ValueError: + delay = 0 + raise MaxApiError( + f"http_{response.status_code}", + retryable=response.status_code in (408, 429) or response.status_code >= 500, + retry_after=delay, + ) + try: + data = response.json() + except ValueError: + raise MaxApiError("invalid_response", retryable=True) from None + if not isinstance(data, dict): + raise MaxApiError("invalid_response", retryable=True) + if data.get("success") is False: + raise MaxApiError("rejected") + return data + + async def send(self, user_id: int, text: str, *, site_url: str, button: str) -> None: + data = await self.request( + "POST", + "/messages", + params={"user_id": user_id, "disable_link_preview": "true"}, + json={ + "text": text, + "notify": True, + "attachments": [ + { + "type": "inline_keyboard", + "payload": {"buttons": [[{"type": "link", "text": button, "url": site_url}]]}, + } + ], + }, + ) + if not isinstance(data.get("message"), dict): + raise MaxApiError("missing_message", retryable=True) + + async def subscribe(self, settings: Settings) -> None: + data = await self.request( + "POST", + "/subscriptions", + json={ + "url": settings.max_webhook_url, + "update_types": UPDATE_TYPES, + "secret": settings.max_webhook_secret.get_secret_value(), + }, + ) + if data.get("success") is not True: + raise MaxApiError("subscription_not_confirmed") diff --git a/app/channels/max_setup.py b/app/channels/max_setup.py new file mode 100644 index 0000000..2fffd08 --- /dev/null +++ b/app/channels/max_setup.py @@ -0,0 +1,56 @@ +"""Operator commands for a future bot owner. Never runs as part of application startup.""" + +import argparse +import asyncio +import sys + +from pydantic import ValidationError + +from app.channels.max_client import MaxApiError, MaxClient +from app.config import Settings + + +async def run(command: str) -> None: + # Validate the same configuration even while the deployed app is still disabled. + settings = Settings(max_enabled=True) + client = MaxClient(settings) + try: + bot = await client.request("GET", "/me") + if bot.get("is_bot") is not True: + raise MaxApiError("not_a_bot") + if bot.get("username") != settings.max_bot_username: + raise MaxApiError("bot_username_mismatch") + if command == "subscribe": + await client.subscribe(settings) + print("Webhook MAX зарегистрирован. Проверьте командой status, затем выполните пробное подключение.") + elif command == "status": + result = await client.request("GET", "/subscriptions") + subscriptions = result.get("subscriptions", []) + configured = any(isinstance(s, dict) and s.get("url") == settings.max_webhook_url for s in subscriptions) + print("Нужный webhook зарегистрирован." if configured else "Нужный webhook не найден.") + if not configured: + raise MaxApiError("webhook_missing") + else: + print("Токен принят MAX, имя бота совпадает с настройкой. Подписка не изменялась.") + finally: + await client.close() + + +def main() -> int: + parser = argparse.ArgumentParser(description="Подготовка MAX: параметры берутся только из .env/окружения.") + parser.add_argument("command", choices=("check", "subscribe", "status")) + args = parser.parse_args() + try: + asyncio.run(run(args.command)) + except ValidationError: + print("Проверьте параметры MAX в .env по app/channels/MAX_SETUP.md.", file=sys.stderr) + return 1 + except (MaxApiError, OSError) as exc: + code = exc.code if isinstance(exc, MaxApiError) else "tls_or_file_error" + print(f"Не удалось выполнить настройку MAX: {code}. Секреты и ответ сервера скрыты.", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/config/texts/max.yaml b/config/texts/max.yaml new file mode 100644 index 0000000..7747fe7 --- /dev/null +++ b/config/texts/max.yaml @@ -0,0 +1,8 @@ +connected: "Уведомления подключены. Здесь будут появляться напоминания с сайта. Отключить их можно командой /stop." +not_connected: "Чтобы получать уведомления, откройте сайт и подключите MAX в настройках уведомлений." +invalid: "Не удалось подключить уведомления. Создайте новую ссылку на сайте. Если MAX уже подключён к другому аккаунту, сначала отключите прежнюю привязку." +stopped: "Уведомления отключены. Подключить их снова можно по новой ссылке с сайта." +help: "Этот бот присылает уведомления. Пройти тесты, посмотреть результаты и продолжить общение можно на сайте. Команда /stop отключает уведомления." +notification: "На сайте есть напоминание для вас. Откройте личный кабинет, чтобы продолжить." +completed: "Прохождение теста завершено. Подробности доступны в личном кабинете на сайте." +open_site: "Открыть сайт" diff --git a/tests/test_max_bot.py b/tests/test_max_bot.py new file mode 100644 index 0000000..1798118 --- /dev/null +++ b/tests/test_max_bot.py @@ -0,0 +1,281 @@ +"""End-to-end server-only MAX flow, real SQLite transactions and mocked network.""" + +from datetime import timedelta +from unittest.mock import AsyncMock +from urllib.parse import parse_qs, urlsplit + +import pytest +from httpx import ASGITransport, AsyncClient +from sqlalchemy import select + +from app.channels import max_bot +from app.channels.max_client import MaxApiError +from app.config import get_settings +from app.core import clock +from app.db import repo, session +from app.db.bootstrap import init_db +from app.db.clinical import ScaleResult +from app.db.intake import QuestionnaireRecord +from app.db.max_notifications import MaxBinding, MaxDelivery, MaxReceipt +from app.dialog.contracts import Reply +from app.integrations import max_store as store +from app.integrations.base import MemoryOutbox, integrations +from app.main import app + +TOKEN = "synthetic-patient" +SECRET = "synthetic-webhook-secret-" * 2 + + +@pytest.fixture(autouse=True) +async def database(monkeypatch): + for key, value in { + "MAX_ENABLED": "true", + "MAX_BOT_TOKEN": "fake-token", + "MAX_BOT_USERNAME": "test_bot", + "MAX_WEBHOOK_SECRET": SECRET, + "MAX_WEBHOOK_URL": "https://api.example.org/api/v1/webhooks/max", + "MAX_SITE_URL": "https://example.org", + }.items(): + monkeypatch.setenv(key, value) + get_settings.cache_clear() + max_bot.texts.cache_clear() + await session.configure(identity_url="sqlite+aiosqlite:///:memory:", clinical_url="sqlite+aiosqlite:///:memory:") + await init_db() + async with session.get_clinical_session() as s: + await repo.upsert_profile(s, token=TOKEN, doctor_id="") + await repo.set_dialog_state( + s, token=TOKEN, state="idle", data={"consent": True, "adult": True}, now=clock.now() + ) + yield + await max_bot.stop() + await session.configure() + get_settings.cache_clear() + + +def event(kind="bot_started", text="", uid=100, *, stamp=1000): + user = {"user_id": uid, "is_bot": False, "first_name": "Synthetic"} + if kind == "message_created": + return { + "update_type": kind, + "timestamp": stamp, + "message": { + "sender": user, + "recipient": {"chat_type": "dialog", "chat_id": 123}, + "body": {"mid": f"mid-{stamp}", "text": text}, + }, + } + return {"update_type": kind, "timestamp": stamp, "user": user, "chat_id": 123, "payload": text} + + +async def connect(): + async with session.get_identity_session() as s: + code, _ = await store.issue_code(s, TOKEN, clock.now(), 600) + await max_bot.handle_update(event(text=code)) + return code + + +async def test_http_connect_webhook_duplicate_notification_and_stop(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client: + auth = {"Authorization": f"Bearer {TOKEN}"} + linked = await client.post("/api/v1/me/notifications/max/link", headers=auth, json={"consent": True}) + code = parse_qs(urlsplit(linked.json()["url"]).query)["start"][0] + headers = {"X-Max-Bot-Api-Secret": SECRET} + for _ in range(2): + assert ( + await client.post("/api/v1/webhooks/max", headers=headers, json=event(text=code)) + ).status_code == 200 + assert (await client.get("/api/v1/me/notifications/max", headers=auth)).json()["connected"] + async with session.get_identity_session() as s: + assert len((await s.scalars(select(MaxReceipt))).all()) == 1 + assert len((await s.scalars(select(MaxDelivery))).all()) == 1 + sender = AsyncMock() + assert await max_bot.deliver_one(sender) + assert sender.send.call_args.args == (100, max_bot.texts().connected) + await client.post("/api/v1/webhooks/max", headers=headers, json=event("message_created", "/stop", stamp=2000)) + assert not (await client.get("/api/v1/me/notifications/max", headers=auth)).json()["connected"] + + +async def test_unbound_start_help_and_invalid_code_are_generic(): + for e in (event(), event("message_created", "private patient text", stamp=2000), event(text="expired", stamp=3000)): + await max_bot.handle_update(e) + async with session.get_identity_session() as s: + rows = (await s.scalars(select(MaxDelivery))).all() + assert {r.kind for r in rows} == {"not_connected", "help", "invalid"} + assert all(r.token is None for r in rows) + assert not (await s.scalars(select(MaxBinding))).all() + + +@pytest.mark.parametrize("kind", ["bot_stopped", "dialog_removed", "message_created"]) +async def test_stopping_cancels_pending_confirmation_and_reminders(kind): + await connect() + await max_bot.MaxOutbox(MemoryOutbox()).push(TOKEN, [Reply(text="private scheduled question")]) + await max_bot.handle_update(event(kind, "/stop", stamp=2000)) + async with session.get_identity_session() as s: + assert not (await s.get(MaxBinding, TOKEN)).enabled + rows = (await s.scalars(select(MaxDelivery).where(MaxDelivery.token == TOKEN))).all() + assert rows and all(r.state == "cancelled" for r in rows) + sender = AsyncMock() + await max_bot.deliver_one(sender) + assert sender.send.call_count == (1 if kind == "message_created" else 0) + + +async def test_private_patient_content_stays_in_fallback_only(): + await connect() + fallback = MemoryOutbox() + wrapper = max_bot.MaxOutbox(fallback) + replies = [Reply(text="SYNTHETIC confidential result 42", kind="question")] + await wrapper.push(TOKEN, replies) + await wrapper.push(TOKEN, replies) + assert fallback.drain(TOKEN) == replies * 2 + async with session.get_identity_session() as s: + rows = (await s.scalars(select(MaxDelivery).where(MaxDelivery.kind == "notification"))).all() + assert len(rows) == 1 + assert "confidential" not in repr(rows[0].__dict__) + sender = AsyncMock() + while await max_bot.deliver_one(sender): + pass + assert any(c.args[1] == max_bot.texts().notification for c in sender.send.call_args_list) + assert all("confidential" not in c.args[1] and TOKEN not in str(c.kwargs) for c in sender.send.call_args_list) + + +async def test_revoked_consent_prevents_binding_and_delivery(): + await connect() + async with session.get_clinical_session() as s: + await repo.set_dialog_state( + s, token=TOKEN, state="idle", data={"consent": False, "adult": True}, now=clock.now() + ) + sender = AsyncMock() + await max_bot.deliver_one(sender) + sender.send.assert_not_called() + async with session.get_identity_session() as s: + await store.disconnect(s, TOKEN) + code, _ = await store.issue_code(s, TOKEN, clock.now(), 600) + await max_bot.handle_update(event(text=code, stamp=2000)) + async with session.get_identity_session() as s: + assert not (await s.get(MaxBinding, TOKEN)).enabled + + +@pytest.mark.parametrize( + "bad", + [ + {}, + {"update_type": "other", "timestamp": 1}, + event() | {"timestamp": True}, + event() | {"user": {"user_id": True, "is_bot": False}}, + event() | {"user": {"user_id": 100, "is_bot": True}}, + event() | {"payload": {"wrong": "type"}}, + {"update_type": "message_created", "timestamp": 1, "message": {}}, + ], +) +async def test_malformed_or_bot_events_are_ignored(bad): + await max_bot.handle_update(bad) + async with session.get_identity_session() as s: + assert not (await s.scalars(select(MaxReceipt))).all() + + +async def test_group_cannot_claim_a_patient_link(): + async with session.get_identity_session() as s: + code, _ = await store.issue_code(s, TOKEN, clock.now(), 600) + update = event("message_created", "/start " + code) + update["message"]["recipient"]["chat_type"] = "chat" + await max_bot.handle_update(update) + async with session.get_identity_session() as s: + assert await s.get(MaxBinding, TOKEN) is None + assert await store.code_token(s, code, clock.now()) == TOKEN + + +async def test_429_respects_retry_deadline_and_then_succeeds(monkeypatch): + await max_bot.handle_update(event()) + now = clock.now() + monkeypatch.setattr(clock, "now", lambda: now) + sender = AsyncMock() + sender.send.side_effect = MaxApiError("http_429", retryable=True, retry_after=120) + assert await max_bot.deliver_one(sender) + async with session.get_identity_session() as s: + row = (await s.scalars(select(MaxDelivery))).one() + assert row.state == "queued" and row.next_attempt_at == now + timedelta(seconds=120) + assert not await max_bot.deliver_one(sender) + now += timedelta(seconds=121) + sender.send.side_effect = None + assert await max_bot.deliver_one(sender) + async with session.get_identity_session() as s: + row = (await s.scalars(select(MaxDelivery))).one() + assert row.state == "sent" and row.attempts == 2 + + +async def test_permanent_error_does_not_retry(): + await max_bot.handle_update(event()) + sender = AsyncMock() + sender.send.side_effect = MaxApiError("http_403") + await max_bot.deliver_one(sender) + assert not await max_bot.deliver_one(sender) + async with session.get_identity_session() as s: + assert (await s.scalars(select(MaxDelivery))).one().state == "failed" + + +@pytest.mark.parametrize("source", ["scale", "questionnaire"]) +async def test_completed_test_produces_one_neutral_notification(source): + await connect() + sender = AsyncMock() + await max_bot.deliver_one(sender) + sender.reset_mock() + async with session.get_clinical_session() as s: + now = clock.now() + if source == "scale": + s.add(ScaleResult(token=TOKEN, ts=now, scale="phq9", total=1, severity="synthetic", complete=True)) + else: + s.add( + QuestionnaireRecord( + id="synthetic-form", + token=TOKEN, + kind="intake", + version="test", + policy_version="test", + started_at=now, + completed_at=now, + day=now.date(), + status="complete", + answers={}, + details={}, + ) + ) + for _ in range(2): + async with session.get_identity_session() as s: + await store.collect_completed(s, clock.now()) + assert await max_bot.deliver_one(sender) + assert not await max_bot.deliver_one(sender) + sender.send.assert_awaited_once_with( + 100, max_bot.texts().completed, site_url="https://example.org", button=max_bot.texts().open_site + ) + + +async def test_private_start_command_accepts_issued_code(): + async with session.get_identity_session() as s: + code, _ = await store.issue_code(s, TOKEN, clock.now(), 600) + await max_bot.handle_update(event("message_created", "/start " + code)) + async with session.get_identity_session() as s: + assert (await s.get(MaxBinding, TOKEN)).user_id == 100 + + +async def test_disabled_lifecycle_never_constructs_client(monkeypatch): + monkeypatch.setenv("MAX_ENABLED", "false") + get_settings.cache_clear() + monkeypatch.setattr(max_bot, "MaxClient", lambda _: pytest.fail("disabled MAX must not create a network client")) + before = integrations.outbox + await max_bot.start() + await max_bot.handle_update(event()) + await max_bot.stop() + assert integrations.outbox is before + + +async def test_lifecycle_wraps_once_restores_and_closes(monkeypatch): + sender = AsyncMock() + monkeypatch.setattr(max_bot, "MaxClient", lambda _: sender) + before = integrations.outbox + await max_bot.start() + first = integrations.outbox + await max_bot.start() + assert integrations.outbox is first and first.fallback is before + await max_bot.stop() + assert integrations.outbox is before + sender.close.assert_awaited_once() diff --git a/tests/test_max_client.py b/tests/test_max_client.py new file mode 100644 index 0000000..65061de --- /dev/null +++ b/tests/test_max_client.py @@ -0,0 +1,95 @@ +"""Wire contract with MAX, using an in-process HTTP fake (no real bot/token).""" + +import json +import logging + +import httpx +import pytest + +from app.channels.max_client import API_URL, UPDATE_TYPES, MaxApiError, MaxClient +from app.config import Settings + + +def settings(): + return Settings( + _env_file=None, + max_enabled=True, + max_bot_token="synthetic-secret-token", + max_bot_username="synthetic_bot", + max_webhook_secret="synthetic-webhook-secret-" * 2, + max_webhook_url="https://api.example.org/api/v1/webhooks/max", + max_site_url="https://example.org", + ) + + +async def test_message_wire_contract_and_no_identifiers_in_logs(caplog): + def handler(request): + assert str(request.url).startswith(API_URL + "/messages?") + assert request.url.params["user_id"] == "1234567890123" + assert "access_token" not in request.url.params + assert request.headers["Authorization"] == "synthetic-secret-token" + body = json.loads(request.content) + assert body["text"] == "neutral reminder" and "format" not in body + button = body["attachments"][0]["payload"]["buttons"][0][0] + assert button == {"type": "link", "text": "Open", "url": "https://example.org"} + return httpx.Response(200, json={"message": {"body": {"mid": "synthetic-id"}}}) + + client = MaxClient(settings(), transport=httpx.MockTransport(handler)) + with caplog.at_level(logging.INFO): + await client.send(1234567890123, "neutral reminder", site_url="https://example.org", button="Open") + await client.close() + assert "1234567890123" not in caplog.text and "synthetic-secret-token" not in caplog.text + + +@pytest.mark.parametrize( + "status,retry", [(429, True), (500, True), (503, True), (408, True), (401, False), (403, False)] +) +async def test_error_codes_are_redacted_and_classified(status, retry): + client = MaxClient( + settings(), + transport=httpx.MockTransport( + lambda r: httpx.Response( + status, json={"message": "sensitive provider text"}, headers={"Retry-After": "120"} + ) + ), + ) + with pytest.raises(MaxApiError) as error: + await client.send(100, "neutral", site_url="https://example.org", button="Open") + assert error.value.retryable is retry and error.value.retry_after == 120 + assert "sensitive" not in str(error.value) + await client.close() + + +@pytest.mark.parametrize("body", [{"success": False, "message": "private"}, {}, {"success": True}, []]) +async def test_http_200_is_not_enough_to_mark_delivered(body): + client = MaxClient(settings(), transport=httpx.MockTransport(lambda r: httpx.Response(200, json=body))) + with pytest.raises(MaxApiError): + await client.send(100, "neutral", site_url="https://example.org", button="Open") + await client.close() + + +async def test_timeout_is_retryable_without_request_details(): + def handler(request): + raise httpx.ReadTimeout("private URL", request=request) + + client = MaxClient(settings(), transport=httpx.MockTransport(handler)) + with pytest.raises(MaxApiError, match="^transport$") as error: + await client.request("GET", "/me") + assert error.value.retryable + await client.close() + + +async def test_subscription_includes_secret_and_exact_event_types(): + def handler(request): + assert request.url.path == "/subscriptions" + body = json.loads(request.content) + assert body == { + "url": settings().max_webhook_url, + "update_types": UPDATE_TYPES, + "secret": settings().max_webhook_secret.get_secret_value(), + } + return httpx.Response(200, json={"success": True}) + + client = MaxClient(settings(), transport=httpx.MockTransport(handler)) + await client.subscribe(settings()) + await client.close() diff --git a/tests/test_max_setup.py b/tests/test_max_setup.py new file mode 100644 index 0000000..680dde7 --- /dev/null +++ b/tests/test_max_setup.py @@ -0,0 +1,51 @@ +"""Operator tools do not send messages or expose credentials.""" + +from unittest.mock import AsyncMock + +import pytest + +from app.channels import max_setup +from app.channels.max_client import MaxApiError +from app.config import Settings + + +@pytest.fixture +def client(monkeypatch): + settings = Settings(_env_file=None, max_bot_username="test_bot", max_webhook_url="https://api.example.org/hook") + sender = AsyncMock() + sender.request.return_value = {"is_bot": True, "username": "test_bot"} + monkeypatch.setattr(max_setup, "Settings", lambda **kwargs: settings) + monkeypatch.setattr(max_setup, "MaxClient", lambda cfg: sender) + return sender + + +async def test_check_only_reads_bot_identity(client): + await max_setup.run("check") + client.request.assert_awaited_once_with("GET", "/me") + client.subscribe.assert_not_called() + client.send.assert_not_called() + client.close.assert_awaited_once() + + +async def test_subscribe_is_explicit_and_checks_bot_first(client): + await max_setup.run("subscribe") + client.subscribe.assert_awaited_once() + client.send.assert_not_called() + + +async def test_mismatched_bot_does_not_change_webhooks(client): + client.request.return_value = {"is_bot": True, "username": "another_bot"} + with pytest.raises(MaxApiError, match="bot_username_mismatch"): + await max_setup.run("subscribe") + client.subscribe.assert_not_called() + client.close.assert_awaited_once() + + +async def test_status_checks_exact_configured_webhook(client): + client.request.side_effect = [ + {"is_bot": True, "username": "test_bot"}, + {"subscriptions": [{"url": "https://elsewhere.example.org"}]}, + ] + with pytest.raises(MaxApiError, match="webhook_missing"): + await max_setup.run("status") + client.subscribe.assert_not_called()