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

Research: Async Backend Refactoring

Feature: 032-translate-requests-httpx Date: 2026-06-04 Status: ✅ Implemented — all decisions applied

R1: APIClient Migration — requests.Session → httpx.AsyncClient

Decision

Расширить существующий AsyncAPIClient в backend/src/core/utils/async_network.py — добавить семафор asyncio.Semaphore(connection_pool_size), connection pool config и поддержку параметров из EnvironmentConfig. Новый файл async_client.py не создаётся — async_network.py остаётся каноническим путём. SupersetAuthCache (общий для sync/async) и пагинированные хелперы уже существуют и переиспользуются.

Rationale

• httpx==0.28.1 уже в requirements.txt. Никаких новых зависимостей для базового HTTP.
• httpx.AsyncClient поддерживает connection pooling (keepalive) и таймауты на уровне клиента.
• async_network.py уже содержит AsyncAPIClient с auth‑cache и error translation. Расширение существующего кода устраняет дублирование.
• API-поверхность методов APIClient.request() остаётся похожей, что упрощает миграцию миксинов.

Alternatives Considered

• aiohttp: Отвергнут — httpx уже в зависимостях, имеет лучший API и поддержку sync/async dual-mode.
• Оставить requests + asyncio.to_thread: Отвергнут — создаёт тред на каждый запрос, неэффективно при высокой нагрузке.
• httpx.Client (sync mode): Отвергнут — это просто замена requests на httpx без решения проблемы блокировки event loop'а.

Impact On Contracts / Tasks

• Новый контракт: AsyncAPIClient [C:4] — stateful (connection pool, cookie jar, CSRF token).
• Контракты на auth.py [C:3] и paginated.py [C:3] извлекаются из старого network.py.
• Все 13 миксинов SupersetClient обновляют @RELATION DEPENDS_ON -> [AsyncAPIClient].

---

R2: SupersetClient Merge — Sync + AsyncSupersetClient → Unified Async

Decision

Синхронный SupersetClient (_base.py) и AsyncSupersetClient (async_superset_client.py) сливаются в единый SupersetClient с полностью асинхронными методами. AsyncSupersetClient удаляется. Все 13 миксинов становятся асинхронными. Старый синхронный код удаляется полностью (big-bang).

Rationale

• Big-bang выбран на этапе clarification — не требует поддержки dual-stack.
• AsyncSupersetClient уже реализует асинхронные версии некоторых методов (get_dashboards, get_datasets, export_dashboard) — их сигнатуры становятся целевыми для объединённого клиента.
• Удаление sync-кода исключает риск случайного использования блокирующего клиента в будущем.

Alternatives Considered

• Dual-stack (sync + async): Отвергнут на этапе clarification.
• Wrapper-only (asyncio.to_thread на всё): Отвергнут — избыточные треды, не решает проблему connection pooling'а.

Impact On Contracts / Tasks

• Контракт SupersetClient [C:4] обновляется: все методы → async def, @SIDE_EFFECT — HTTP-вызовы, @PRE — валидный env_config.
• AsyncSupersetClient → Tombstone с @DEPRECATED + @REPLACED_BY -> [SupersetClient].
• 13 файлов миксинов требуют обновления сигнатур.

---

R3: Task Manager Asyncio Migration

Decision

ThreadPoolExecutor в TaskManager заменяется на asyncio.create_task. Все фоновые задачи выполняются в основном event loop'е. EventBus для WebSocket-логирования становится асинхронным (использует asyncio.Queue вместо queue.Queue). TaskLifecycle переходит на async-контекстные менеджеры.

Rationale

• Выбрано на этапе clarification (Option B).
• asyncio.create_task не создаёт дополнительных тредов, задачи разделяют ресурсы event loop'а.
• Упрощает отмену задач: task.cancel() + CancelledError cascade.
• WebSocket-логирование через asyncio.Queue интегрируется нативно.

Alternatives Considered

• Per-task event loop (asyncio.run): Отвергнут — создаёт изоляцию между задачами, усложняет общую отмену.
• Hybrid (лёгкие на create_task, тяжёлые на ThreadPoolExecutor): Отвергнут — усложняет архитектуру без выигрыша, т.к. все тяжёлые операции теперь асинхронны.

Impact On Contracts / Tasks

• Контракт TaskManager [C:5] — @INVARIANT: задачи не блокируют event loop, @DATA_CONTRACT: Input: TaskParams → Output: TaskResult.
• Контракт EventBus [C:4] обновляется: queue.Queue → asyncio.Queue, call_soon_threadsafe удаляется.
• Контракт TaskLifecycle [C:4] обновляется: async context managers.

---

R4: Connection Pool / Semaphore Design

Decision

asyncio.Semaphore(20) на каждое окружение Superset. Семафор создаётся при инициализации AsyncAPIClient для конкретного env_id. Все операции (экспорт, SQL Lab, chart data) конкурируют за один пул. При исчерпании — asyncio.wait_for(semaphore.acquire(), timeout=30). Таймаут и размер пула настраиваются через конфигурацию окружения.

Rationale

• Выбрано на этапе clarification (Option B — semaphore per env, wait with timeout).
• asyncio.Semaphore — это built-in, не требует внешних зависимостей.
• Конфигурация на уровне окружения позволяет задать разные лимиты для dev/staging/prod Superset.
• Таймаут 30 секунд даёт достаточно времени для освобождения слота при типичных операциях (экспорт дашборда — 2-5 секунд).

Alternatives Considered

• Без ограничений: Отвергнут — risk of overwhelming Superset.
• Семафоры по типам операций: Отвергнут — избыточная сложность для текущего масштаба.

Impact On Contracts / Tasks

• Контракт AsyncAPIClient [C:4] добавляет @INVARIANT: количество одновременных запросов ≤ semaphore_size.
• Новый edge case: 503 Service Unavailable при таймауте семафора.
• Тесты на семафор: test_semaphore_timeout_returns_503, test_semaphore_releases_after_completion.

---

R5: Test Mock Migration — requests_mock → pytest_httpx

Decision

Все тесты, использующие requests_mock, переводятся на pytest-httpx. pytest-httpx предоставляет фикстуру httpx_mock, которая перехватывает вызовы httpx.AsyncClient на транспортном уровне. Логика assertions (проверка URL, method, payload, response) сохраняется.

Rationale

• Выбрано на этапе clarification (Option A).
• pytest-httpx — de-facto стандарт для тестирования httpx в pytest.
• Минимальные изменения в assertions: httpx_mock.add_response(url=..., method="GET", json=...) — синтаксис похож на requests_mock.

Alternatives Considered

• respx: Отвергнут — менее распространён в pytest-экосистеме.
• Встроенный httpx.MockTransport: Отвергнут — больше boilerplate.
• Сохранить requests_mock + врапперы: Отвергнут — костыль, тесты не проверяют реальное асинхронное поведение.

Impact On Contracts / Tasks

• Новая dev-зависимость: pytest-httpx в requirements-dev.txt или pyproject.toml.
• Обновление conftest.py: глобальная фикстура httpx_mock.
• Все тестовые файлы, использующие requests_mock, обновляются.

---

R6: LLM Client Migration — requests → httpx.AsyncClient

Decision

Два файла LLM-клиентов (_llm_http.py и preview_llm_client.py) переводятся на httpx.AsyncClient. Функции call_openai_compatible() становятся async def. Rate-limit backoff (time.sleep) заменяется на asyncio.sleep. Оба файла используют один и тот же паттерн, поэтому логика HTTP-вызова выносится в общий модуль _llm_async_http.py.

Rationale

• httpx.AsyncClient уже используется в llm_analysis/service.py через AsyncOpenAI — прецедент есть.
• Вынос общей HTTP-логики в отдельный модуль устраняет дублирование между _llm_http.py (для execution) и preview_llm_client.py (для preview).
• asyncio.sleep вместо time.sleep — не блокирует event loop при rate-limit ожидании.

Alternatives Considered

• AsyncOpenAI (как в llm_analysis): Отвергнут для translate — translate использует OpenAI-совместимый протокол, но не официальный OpenAI SDK. AsyncOpenAI не поддерживает произвольные base_url с кастомными провайдерами (OpenRouter, LiteLLM, Kilo).
• httpx.Client (sync) в asyncio.to_thread: Отвергнут — избыточно, httpx.AsyncClient решает проблему нативно.

Impact On Contracts / Tasks

• Контракт LLMHttpClient [C:4] — новый модуль _llm_async_http.py с async def call_openai_compatible().
• _llm_http.py и preview_llm_client.py → Tombstone с @DEPRECATED + @REPLACED_BY.
• _llm_call.py: вызов call_llm_for_batch() становится async def.

---

R7: SQL Lab Executor Async Migration

Decision

SupersetSqlLabExecutor.execute_sql() и poll_execution_status() становятся async def. Вызовы client.network.request() заменяются на await async_client.request(). time.sleep(poll_interval) заменяется на await asyncio.sleep(poll_interval). Класс остаётся в superset_executor.py, но получает AsyncAPIClient вместо sync SupersetClient.

Rationale

• Поллинг — основной блокировщик в проверке схемы (до 15 × 1s + HTTP latency = до 30s блокировки).
• asyncio.sleep передаёт управление event loop'у между попытками поллинга.
• asyncio.wait_for может быть использован для общего таймаута всей операции проверки схемы.

Impact On Contracts / Tasks

• Контракт SupersetSqlLabExecutor [C:4] — все методы async def, @SIDE_EFFECT — асинхронные HTTP-вызовы к Superset SQL Lab API.
• check_target_schema (_job_routes.py) — уже async def, теперь вызывает await validate_target_table_schema().

---

R8: File I/O Async Strategy

Decision

Гибридный подход:

• Большие файлы (экспорт дашбордов ZIP > 1MB, загрузка в storage > 10MB): aiofiles для потокового чтения/записи.
• Мелкие операции (shutil.rmtree, shutil.copy2, read_bytes, CRC32): asyncio.to_thread().
• aiofiles добавляется в requirements.txt.

Rationale

• asyncio.to_thread для мелких операций — минимальный overhead, не требует новой зависимости.
• aiofiles для больших файлов — предоставляет async-интерфейс, избегает блокировки event loop (может использовать executor-потоки внутри, но API остаётся неблокирующим).
• Гибридный подход балансирует простоту и эффективность.

Alternatives Considered

• Только asyncio.to_thread: Отвергнут — для больших файлов (50MB ZIP) тред блокируется на секунды, что исчерпывает thread pool.
• Только aiofiles: Отвергнут — для мелких операций (shutil.rmtree) aiofiles избыточен и не поддерживает рекурсивные операции.

Impact On Contracts / Tasks

• Контракт FileIO [C:3] обновляется: @RATIONALE для гибридного подхода.
• aiofiles добавляется в requirements.txt.
• shutil вызовы в плагинах оборачиваются в asyncio.to_thread.

---

R9: WebSocket Logging Async Migration

Decision

EventBus переходит с queue.Queue + call_soon_threadsafe на asyncio.Queue. WebSocket-отправка логов становится нативной асинхронной операцией. TaskLifecycle использует asyncio.Queue для получения событий от задач.

Rationale

• asyncio.Queue интегрируется с event loop'ом без тредовой синхронизации.
• call_soon_threadsafe больше не нужен — все задачи в одном event loop'е.
• Упрощает отмену: при закрытии WebSocket очередь очищается, задачи не зависают.

Impact On Contracts / Tasks

• Контракт EventBus [C:4] — замена queue.Queue → asyncio.Queue.
• Контракт TaskLifecycle [C:4] — асинхронный run_task().
• WebSocket-ручки (/ws/tasks/{id}) — уже async def, изменений не требуют.

---

R10: Notification Providers Async Migration

Decision

• SMTP: smtplib.SMTP → aiosmtplib.SMTP (async SMTP-клиент).
• Telegram/Slack: requests.post → httpx.AsyncClient.post.
• Все методы send() становятся действительно асинхронными.

Rationale

• aiosmtplib — зрелая библиотека (2k+ stars), поддерживает STARTTLS, аутентификацию.
• httpx.AsyncClient для Telegram/Slack — переиспользование того же клиента, что и для Superset/LLM.

Impact On Contracts / Tasks

• Контракты SMTPProvider, TelegramProvider, SlackProvider [C:3] — async def send().
• aiosmtplib добавляется в requirements.txt.

---

Unmitigated Risks

R1: Сложность отладки асинхронных race conditions

Вероятность: Средняя | Влияние: Высокое
Ошибки конкурентности могут не воспроизводиться в тестах (одновременный deploy + backup одного дашборда, параллельное обновление кэша).
Митигация: Интеграционные тесты с asyncio.gather и случайными задержками (fuzzing). Увеличенное логирование с trace_id.

R2: Миграция тестов с requests_mock на pytest-httpx

Вероятность: Средняя | Влияние: Среднее
Различия в API моков могут привести к тому, что тесты перестанут проверять правильные заголовки/куки.
Митигация: Пошаговая верификация (T049-T053). Параллельный запуск старых и новых тестов на время переходного периода.

R3: Исчерпание семафора и таймауты

Вероятность: Высокая | Влияние: Среднее
При долгой операции (экспорт >30 с) ожидающие запросы получат 503, хотя слот скоро освободится.
Митигация: connection_pool_timeout настраивается. Рекомендуется увеличить default до 60 с для prod. Метрика superset_pool_wait_time для мониторинга (post‑MVP).

R4: Утечки ресурсов при asyncio.to_thread

Вероятность: Низкая | Влияние: Высокое
Поток в to_thread может зависнуть (сетевой вызов внутри). Приведёт к утечке потока из bounded‑executor.
Митигация: Bounded‑executor'ы с max_workers. Где возможно — asyncio.wait_for вокруг to_thread. Для Git/файлов — явный таймаут в адаптере.

R5: Сложность рефакторинга Task Manager

Вероятность: Низкая | Влияние: Высокое
Переход с ThreadPoolExecutor на asyncio.create_task может нарушить логику отмены задач и WebSocket‑логирования, если текущий код полагается на тредовую изоляцию.
Митигация: Сквозной тест: запустить долгую задачу, отменить через API, проверить WebSocket‑событие отмены и завершение всех корутин.

R6: Производительность при массовых DB-операциях

Вероятность: Средняя | Влияние: Среднее
При 100 параллельных запросах каждый создаёт поток для БД через to_thread.
Митигация: Bounded db_executor с max_workers=10. Очередь запросов через asyncio.Semaphore для БД (отдельный от Superset пула).

---

Summary of New Dependencies

Package	Purpose	Already in requirements.txt?
httpx==0.28.1	Async HTTP client	✅ Yes
anyio==4.12.0	Async I/O primitives	✅ Yes
pytest-httpx	Test mock for httpx	❌ Add to dev deps
aiofiles	Async file I/O	❌ Add to requirements.txt
aiosmtplib	Async SMTP	❌ Add to requirements.txt