ss-tools/specs/032-translate-requests-httpx/spec.md

Feature Specification: Async Backend Refactoring

Feature Branch: 032-translate-requests-httpx Created: 2026-06-04 Status: Draft Input: Полный рефакторинг всех модулей backend на асинхронный неблокирующий ввод-вывод: замена синхронного requests на httpx.AsyncClient, асинхронное взаимодействие с БД, отказ от time.sleep в пользу asyncio.sleep, полная ликвидация блокировки event loop'а FastAPI при любых внешних вызовах.

Problem Statement

При одном воркере uvicorn любая синхронная блокирующая операция (HTTP-вызов к Superset, LLM, SMTP, Telegram, Slack; файловые операции shutil; time.sleep в циклах поллинга; Git-клонирование) останавливает все входящие запросы. Это делает систему неюзабельной при активной работе даже одного оператора и полностью непригодной для командного использования.

Scope: ~15 файлов, ~45 блокирующих вызовов

Корневая причина: APIClient (core/utils/network.py, 542 строки) — центральный HTTP-клиент на requests.Session. Через него проходит весь трафик ss-tools к Superset. Все 13 методов-миксинов SupersetClient используют его синхронно. Любой запрос к Superset (получение дашбордов, экспорт, импорт, SQL Lab, chart data, скриншоты) блокирует event loop.

Migration Strategy

Выбрано: Big-bang (Option A). Все синхронные вызовы requests, time.sleep, синхронный SupersetClient заменяются в одном PR. Синхронный код не сохраняется для обратной совместимости — асинхронный клиент становится единственным. AsyncSupersetClient и sync SupersetClient сливаются в один асинхронный клиент.

Модули, требующие рефакторинга

Priority	Module	Что блокирует
P1	core/utils/network.py — APIClient	Центральный хаб: requests.Session, все методы синхронные
P1	core/superset_client/ — SupersetClient + миксины	13 миксинов × синхронные методы, зависят от APIClient
P2	plugins/translate/ — LLM HTTP, SQL Lab, preview	requests.post к LLM, client.network.request к Superset, time.sleep в поллинге
P2	api/routes/dashboards/ — thumbnail, detail	Создаёт синхронный SupersetClient прямо в async def ручке
P3	plugins/backup.py — BackupPlugin	Экспорт дашбордов, файловый I/O — внутри async def execute()
P3	plugins/git_plugin.py — GitPlugin	shutil.*, SupersetClient, Git-клонирование — внутри async def
P3	plugins/llm_analysis/plugin.py — dashboard logs	client.network.request внутри async def _fetch_dashboard_logs()
P3	core/utils/fileio.py — файловые операции	shutil.rmtree, read_bytes, open() — вызываются из плагинов
P3	core/utils/superset_compilation_adapter.py	client.network.request для компиляции SQL — вызывается из dataset_review
P4	services/notifications/providers.py — SMTP, Telegram, Slack	smtplib.SMTP, requests.post — внутри async def send()
P4	services/git/_base.py — Git-операции	shutil, GitPython-клонирование
P4	plugins/storage/plugin.py — файлы	shutil.copyfileobj() в async def save_file()
P4	api/routes/ — прочие ручки	Остаточные синхронные вызовы
P4	core/task_manager/ — Task Manager	ThreadPoolExecutor заменяется на asyncio.create_task; WebSocket-логирование и lifecycle — асинхронные

Эталонные паттерны и существующая инфраструктура

• backend/src/core/utils/async_network.py — AsyncNetworkModule [C:5] с AsyncAPIClient [C:3] — уже существует. Полноценный асинхронный клиент на httpx.AsyncClient с SupersetAuthCache, 401-retry, error translation. Требуется расширение: добавление asyncio.Semaphore, connection pool config.
• backend/src/core/utils/network.py — NetworkModule [C:3] с APIClient [C:3] + SupersetAuthCache — синхронный клиент, будет заменён (Tombstone). SupersetAuthCache — общий для sync/async, сохраняется.
• plugins/llm_analysis/service.py — _call_sync() + asyncio.to_thread() — эталонный паттерн для обёртки sync-вызовов (БД, файловые операции).
• plugins/llm_analysis/service.py — AsyncOpenAI + httpx.AsyncClient — эталон для асинхронных LLM-вызовов.
• core/async_superset_client.py — существующий AsyncSupersetClient будет объединён с sync SupersetClient.

Clarifications

Session 2026-06-04

• Q: Migration strategy — dual-stack staged vs big-bang vs wrapper-only vs full async SQLAlchemy? → A: Option A — Big-bang: заменить все синхронные вызовы в одном PR. Sync-код удаляется, async становится единственным путём.
• Q: Test mock library for httpx — pytest-httpx vs respx vs MockTransport vs keep requests_mock? → A: Option A — pytest-httpx. Стандартный мок для httpx, минимум изменений в assertions, нативная интеграция с pytest.
• Q: Connection pool & concurrency limits — no limits vs semaphore per env vs semaphore per operation type? → A: Option B — asyncio.Semaphore на каждое окружение Superset (по умолчанию 20). Все операции конкурируют за один пул, first-come-first-served.
• Q: Semaphore exhaustion behavior — instant fail vs wait with timeout vs unlimited queue? → A: Option B — ожидание с таймаутом 30 секунд (настраивается). При превышении таймаута → 503 Service Unavailable.
• Q: Background tasks & ThreadPoolExecutor — per-task event loop vs full Task Manager async vs hybrid? → A: Option B — Task Manager полностью переходит на asyncio: asyncio.create_task вместо ThreadPoolExecutor для запуска задач.

User Scenarios & Testing

User Story 1 — Неблокирующее ядро: Superset API (Priority: P1)

Фундамент всего рефакторинга. Любое взаимодействие с Superset API — получение списка дашбордов, экспорт/импорт, SQL Lab execute, chart data, скриншоты, информация о датасетах — не блокирует обработку других HTTP-запросов. APIClient заменяется на асинхронный транспорт, SupersetClient становится полностью асинхронным.

Why this priority: Все плагины (translate, backup, git, llm_analysis, migration) зависят от SupersetClient. Без его асинхронности невозможен рефакторинг ни одного плагина.

Independent Test: Отправить три параллельных запроса к разным эндпоинтам Superset API через систему. Замерить общее время — должно быть ≈ max(time1, time2, time3), а не sum.

Acceptance Scenarios:

1. Given настроено окружение Superset, When одновременно вызываются get_dashboards() (пагинированный), get_dataset_detail() и export_dashboard(), Then все три вызова выполняются конкурентно, event loop не блокируется.
2. Given Superset отвечает медленно (5 секунд на дашборд), When одновременно приходит обычный GET-запрос (например, /health), Then GET-запрос получает ответ мгновенно, не дожидаясь Superset.
3. Given асинхронный SupersetClient, When происходит сетевая ошибка (connection refused), Then исключение всплывает только в запросе-инициаторе, не затрагивая другие конкурентные запросы.

---

User Story 2 — Параллельный Translate: preview + schema check (Priority: P2)

Оператор настраивает переводческую задачу. Нажимает «Предпросмотр» (preview) на вкладке Preview — система загружает данные из Superset, отправляет в LLM. Не дожидаясь, переключается на Target Config и нажимает «Проверить схему» — система немедленно обрабатывает запрос, возвращает результат проверки схемы, не дожидаясь окончания предпросмотра.

Why this priority: Прямая жалоба пользователя. Этот сценарий стал триггером всего рефакторинга.

Independent Test: POST /translate/jobs/A/preview (sample_size=10) и одновременно POST /translate/check-target-schema. Проверка схемы возвращает ответ до завершения предпросмотра.

Acceptance Scenarios:

1. Given запущен предпросмотр с LLM-вызовом (8-15 секунд), When немедленно отправляется запрос проверки схемы с поллингом SQL Lab (до 15 попыток), Then проверка схемы завершается до окончания предпросмотра.
2. Given активный поллинг SQL Lab (time.sleep заменён на asyncio.sleep), When одновременно приходит лёгкий GET-запрос, Then он обрабатывается без задержки.
3. Given выполняются три параллельных LLM-вызова (разные джобы, разные операторы), When один из них получает rate-limit (429) и уходит в backoff, Then два других продолжают выполняться без задержки.

---

User Story 3 — Все плагины: backup, git, llm_analysis, storage (Priority: P3)

Резервное копирование дашбордов (backup), деплой из Git, LLM-анализ дашбордов, загрузка файлов в storage — все эти операции выполняются асинхронно, не блокируя другие запросы.

Why this priority: После решения P1 (SupersetClient) и P2 (translate) — остальные плагины становятся «низко висящими фруктами». Их рефакторинг сводится к замене синхронных клиентов на асинхронные.

Independent Test: Запустить backup всех дашбордов (50+) и одновременно выполнить deploy из Git. Обе операции выполняются конкурентно.

Acceptance Scenarios:

1. Given запущен бэкап 50 дашбордов (каждый экспортируется и сохраняется на диск), When одновременно запускается деплой дашборда из Git, Then деплой не ждёт окончания бэкапа.
2. Given запущен LLM-анализ дашборда (загрузка скриншотов, вызов LLM), When одновременно загружается файл в storage, Then загрузка файла не блокируется LLM-вызовом.
3. Given Git-операция клонирования репозитория (5-10 секунд), When одновременно пользователь открывает список дашбордов, Then список загружается без задержки.

---

User Story 4 — Уведомления и фоновая отправка (Priority: P4)

Отправка уведомлений (SMTP, Telegram, Slack) по завершении задач, scheduled reports, alert'ы — все асинхронны и не блокируют основные запросы.

Why this priority: Уведомления — фоновая операция. Их блокировка не критична для UX, но smtplib.SMTP и requests.post в async def send() — нарушение контракта.

Independent Test: Отправить SMTP-уведомление (медленный SMTP-сервер, 3 секунды на подключение) одновременно с обычным API-запросом. API-запрос не задерживается.

Acceptance Scenarios:

1. Given отправляется Telegram-уведомление (requests.post заменён на httpx.AsyncClient.post), When одновременно приходит запрос на получение списка джоб, Then запрос списка не ждёт отправки уведомления.
2. Given SMTP-сервер недоступен (connection timeout 10 секунд), When отправляется email-уведомление, Then таймаут не блокирует другие запросы, ошибка логируется.

---

Edge Cases

• Отмена запроса клиентом (disconnect): При разрыве соединения все связанные внешние вызовы (HTTP, поллинг, файловые операции) должны быть отменены. Никаких «висящих» соединений и утечек.
• Таймауты внешних сервисов: Каждый внешний вызов имеет настраиваемый таймаут. Превышение таймаута — исключение только для запроса-инициатора.
• Сетевые ошибки: DNS failure, connection refused, TLS handshake failure — корректная обработка без влияния на другие запросы.
• CPU-bound парсинг: JSON-парсинг больших ответов LLM, валидация данных — выполняются через run_blocking(kind='cpu', fn=...).
• Файловые операции с большими файлами: Экспорт дашбордов (ZIP до 50MB), сохранение на диск — через aiofiles или run_blocking(kind='file', fn=...).
• Git-клонирование: Длительная операция (до 30 секунд) — выполняется в thread pool, не блокирует event loop.
• Гонка состояний (race conditions): При конкурентных запросах к одному ресурсу (например, одновременный deploy и backup одного дашборда) система должна обеспечивать консистентность данных.
• Исчерпание пула соединений к Superset: Когда все 20 слотов семафора заняты, новые запросы ожидают до 30 секунд. При превышении таймаута — ошибка 503 Service Unavailable с сообщением «Superset connection pool exhausted». Другие API (не использующие Superset) продолжают работать.
• Конкурентная аутентификация: Несколько корутин могут одновременно обнаружить истёкший CSRF‑токен. Обновление токена защищено asyncio.Lock per‑environment. Только одна корутина выполняет refresh, остальные ждут и переиспользуют результат.
• Graceful shutdown: При остановке сервера долгоживущие клиенты (httpx.AsyncClient), семафоры, очереди EventBus и активные задачи должны быть корректно закрыты в течение 30 секунд.
• Зависший поток в run_blocking: Если операция в run_blocking зависает (например, Git‑клонирование не отвечает), общий таймаут через asyncio.wait_for прерывает ожидание, но поток продолжает работу в фоне. Слот executor'а освобождается после возврата функции. Система логирует превышение таймаута и продолжает работу.
• Таймаут поллинга SQL Lab: Вся операция execute_and_poll (включая все попытки поллинга) должна иметь общий таймаут (настраиваемый, по умолчанию 120 секунд), чтобы не висеть бесконечно при зависшем SQL‑запросе на стороне Superset.

Requirements

Functional Requirements

Core Infrastructure (P1):

• FR-001: APIClient (базовый HTTP-клиент) должен быть переведён на асинхронный транспорт (httpx.AsyncClient). Все методы (request, authenticate, upload_file, fetch_paginated_*) становятся асинхронными.
• FR-002: SupersetClient и все 13 миксинов переводятся на асинхронный APIClient. Синхронный SupersetClient и AsyncSupersetClient объединяются в единый асинхронный клиент. Синхронный код удаляется полностью (big-bang).
• FR-003: Все вызовы SupersetClient из async def ручек должны перейти на асинхронный клиент. Создание синхронного SupersetClient(env) внутри async def запрещено.

Translate Plugin (P2):

• FR-004: LLM-вызовы (_llm_http.py, preview_llm_client.py) должны использовать httpx.AsyncClient вместо requests. Rate-limit backoff — asyncio.sleep вместо time.sleep.
• FR-005: SQL Lab executor (superset_executor.py) — поллинг с asyncio.sleep вместо time.sleep. Execute и poll — асинхронные методы.
• FR-006: Загрузка данных из Superset (chart data, source rows) — через асинхронный клиент.
• FR-007: Preview и schema check должны выполняться конкурентно без взаимной блокировки.

All Plugins (P3):

• FR-008: BackupPlugin — экспорт дашбордов и файловый I/O через асинхронный клиент + run_blocking(kind='file', fn=...) / aiofiles.
• FR-009: GitPlugin — shutil операции и Git-клонирование через run_blocking(kind='file'/'git', fn=...).
• FR-011: Storage Plugin — shutil.copyfileobj() заменён на run_blocking(kind='file', fn=...) или aiofiles.
• FR-015: Git-сервис (services/git/_base.py) — файловые операции через run_blocking(kind='file'/'git', fn=...).

Cross-cutting:

• FR-016: Все внешние HTTP-вызовы должны иметь настраиваемый таймаут.
• FR-017: Отмена клиентского запроса cascade-отменяет связанные внешние вызовы: awaitable HTTP/polling — немедленная отмена (httpx + CancelledError); операции в run_blocking (Git, файлы, БД) помечаются cancelled, завершаются до ближайшего checkpoint и освобождают ресурсы после возврата. Принудительная остановка потока не гарантируется.
• FR-018: Существующие success-коды (200, 201) и форматы ответов всех эндпоинтов остаются неизменными. Допускается добавление новых failure-кодов для ранее не обрабатывавшихся режимов: 503 (pool exhaustion), 504 (upstream timeout).
• FR-019: Лёгкие запросы (GET /jobs, GET /dashboards) не должны деградировать по времени ответа после рефакторинга.
• FR-020: CoT-логирование (REASON/REFLECT/EXPLORE) сохраняется на всех асинхронных путях.
• FR-021: Все операции с БД, вызываемые из асинхронного контекста, должны быть обёрнуты в run_blocking(kind='db', fn=...). SQLAlchemy‑сессии не пересекают границу потоков (FR-025).

Task Manager (P4):

• FR-022: ThreadPoolExecutor для запуска задач заменяется на asyncio.create_task. Задачи выполняются в основном event loop'е.
• FR-023: WebSocket-логирование задач переводится на асинхронную отправку (без блокирующего I/O). EventBus использует asyncio.Queue(maxsize=10000, настраивается); при переполнении новые события отбрасываются с предупреждением в лог (не блокируют задачу). При task.cancel() публикация логов для task_id прекращается, формируется финальное событие {"type":"cancelled"}. Уже поставленные в очередь события могут быть доставлены.
• FR-024: Lifecycle задач (запуск, отмена, статус) остаётся обратно совместимым — контракты TaskManager не меняются для потребителей.

Safety & Contracts:

• FR-025: SQLAlchemy‑сессии создаются, используются, коммитятся/откатываются и закрываются внутри одного worker‑потока. Никакие ORM‑объекты не пересекают границу потока без detach/serialization. DB‑адаптер владеет жизненным циклом сессии.
• FR-026: Обновление CSRF/auth‑токенов защищено asyncio.Lock per‑environment. Retry после 401 разрешён только для идемпотентных методов (GET). Для неидемпотентных (POST import, PUT) — ошибка всплывает вызывающему без автоматического retry.
• FR-027: Graceful shutdown: прекратить приём новых задач, отменить активные asyncio‑задачи, закрыть все httpx.AsyncClient через SupersetClientRegistry, слить EventBus, пометить незавершённые задачи как CANCELLED в течение 30 секунд (настраивается).
• FR-028: Планировщик задач (APScheduler) должен быть переведён на AsyncIOScheduler, либо все вызовы TaskManager.run_task() из scheduled jobs должны выполняться через asyncio.run_coroutine_threadsafe() с ожиданием результата.

Non-Functional Requirements

• NFR-001: При одном воркере uvicorn 3 параллельных «тяжёлых» запроса должны выполняться конкурентно (пересекающиеся временные интервалы), а не последовательно.
• NFR-002: CPU-bound операции (JSON-парсинг > 1MB, валидация, хеширование) выполняются через run_blocking(kind='cpu', fn=...).
• NFR-003: Утечки соединений (незакрытые HTTP-клиенты, файловые дескрипторы) после 500 последовательных запросов к любым эндпоинтам равны нулю.
• NFR-004: Время выполнения отдельной операции в отсутствие конкуренции (baseline) не увеличивается более чем на 10% относительно синхронной версии, замеренной до рефакторинга.
• NFR-005: Все новые зависимости (httpx, aiofiles, aiosmtplib) должны быть добавлены в requirements.txt.
• NFR-006: Количество одновременных соединений к одному окружению Superset ограничивается asyncio.Semaphore (по умолчанию 20, настраивается через конфигурацию окружения). Семафор — глобальный per‑environment через SupersetClientRegistry (синглтон), не per‑client. При исчерпании пула запрос ожидает до 30 секунд (настраивается), затем возвращает 503 Service Unavailable.
• NFR-007: Блокирующие адаптеры (Git, файлы, БД) используют именованные bounded‑executor'ы через loop.run_in_executor(named_executor, fn): db_executor, file_executor, git_executor с max_workers и queue timeout (по умолчанию 10 воркеров каждый). Прямое использование asyncio.to_thread (default executor) запрещено для production‑путей. Рекомендуется helper run_blocking(kind, fn, *args, timeout) в core/utils/executors.py.
• NFR-008: На shutdown: прекратить приём новых задач, отменить активные asyncio‑задачи с graceful‑timeout 30 секунд, закрыть все httpx.AsyncClient через SupersetClientRegistry, слить/закрыть EventBus, пометить незавершённые задачи как CANCELLED.
• NFR-009: Рекомендуемые runtime‑метрики (post‑MVP): event_loop_lag_ms, superset_pool_in_use{env}, superset_pool_wait_ms{env}, httpx_connections_open, task_cancel_total, threadpool_queue_depth.

Key Entities

• APIClient: Центральный HTTP-клиент — из синхронного requests.Session становится асинхронным httpx.AsyncClient. Точка входа для всех внешних HTTP-вызовов.
• SupersetClient: Фасад над APIClient с доменными методами (get_dashboards, export_dashboard, get_dataset_detail, etc.) — все методы становятся асинхронными.
• SQL Lab Executor: Сервис отправки SQL и поллинга результатов — поллинг становится неблокирующим.
• LLM API Client: Клиент для OpenAI-совместимых API — транспорт меняется на httpx.AsyncClient.
• Notification Providers: SMTP, Telegram, Slack — каждый провайдер становится действительно асинхронным.
• Plugin Execute Contract: Все плагины реализуют async def execute() — теперь без синхронных блокирующих вызовов внутри.
• Task Manager: Менеджер фоновых задач — переходит с ThreadPoolExecutor на asyncio.create_task. Задачи разделяют основной event loop.
• SupersetClientRegistry: Синглтон-реестр долгоживущих клиентов по env_id — хранит shared httpx.AsyncClient + shared asyncio.Semaphore + auth‑lock. Закрывает все клиенты на shutdown.

Success Criteria

Measurable Outcomes

• SC-001: Проверка схемы (/check-target-schema), отправленная одновременно с предпросмотром (/preview), завершается до окончания предпросмотра — результат доступен пользователю параллельно, а не последовательно.
• SC-002: Три параллельных «тяжёлых» запроса (preview + backup + schema check) при одном воркере uvicorn завершаются за время ≈ max(t1, t2, t3), а не sum.
• SC-003: Легковесный GET-запрос (/health, /translate/jobs) во время активного поллинга SQL Lab (до 30 секунд) получает ответ за < 100ms.
• SC-004: Экспорт 50 дашбордов (backup) и деплой дашборда (git) выполняются конкурентно без взаимной блокировки.
• SC-005: Существующие поведенческие assertions в тестах backend остаются эквивалентными (логика проверок не меняется). Тестовые фикстуры и async‑механика могут измениться (замена requests_mock → pytest_httpx, добавление pytest.mark.asyncio).
• SC-006: Ноль утечек соединений после 500 последовательных запросов к любым эндпоинтам.
• SC-007: Время выполнения предпросмотра перевода не увеличилось более чем на 10% относительно синхронной версии.
• SC-008: Количество «грязных» async def-ручек, содержащих синхронные блокирующие вызовы, равно нулю (верифицируется статическим анализом).