diff --git a/QUESTIONS.md b/QUESTIONS.md index 04d78b91..f37a9391 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -184,3 +184,30 @@ 3. Изображение, которое не уложилось в лимиты времени или памяти обработки, — это `invalid_image` или отдельный код? Контракт приводит коды как пример. Сделано: `invalid_image`, точная причина — в записи для оператора. Другой ответ добавляет значение enum и требует порядка обновления реплик раньше worker. 4. Контракт требует retention для «неуспешных и непривязанных исходников», но молчит о конечных объектах, которые успела записать неудачная попытка. Сделано: по истечении срока удаляются и они, метаданные `failed` остаются. Другой ответ убирает один шаг очистки. 5. Секреты worker читаются процессом обработки через `/proc/1/environ` под тем же UID: окружение самого процесса обработки их не содержит, но после эксплойта декодера защиты нет. Кодом не исправлено, ограничение названо в `REPORT.md` и `worker.md`. Предложение: `prctl(PR_SET_DUMPABLE, 0)` в процессе worker до запуска процессов обработки: тогда чужой процесс того же UID не откроет его `/proc//environ` и `mem`. Требуется ли это на уровне лабы? + +## unit-of-work + +Подробности и отвергнутые варианты — `openspec/changes/unit-of-work/design.md`; пробы — его раздел «Пробы» (проект compose `uowprobe`, данные в tmpfs, volumes не создавались, после проб ничего не осталось). + +### Решения + +- **Общий срок JSON-запроса остался, это расхождение с буквальной постановкой** «`request_timeout_seconds` — срок UoW, а не запроса» (решение 6). Срок блока — как в постановке, но на роутерах пользователей, сессий, чатов и сообщений сверх него стоит зависимость `request_deadline` той же настройкой. Без неё проба дала 503 за 3,31 с вместо 2 с при сроке 2 с (при 6 с — до 12 с, больше `timeout server` 10 с: 504 от LB вместо 503 реплики), и очередь хэшей шла без срока: 40 входов ждали 4,69 с вместо отказа за 2 с. Отменить решение просто (убрать `dependencies=` у четырёх `include_router`), но тогда придётся менять цепочку LB и её спек. +- **Откат при выходе из блока — под сроком, отмена задачи сбрасывает соединение** (решение 4). Прежний `session_scope` откатывал уже вне срока: на JSON-ручках незаметно (после ответа), на шаге замороженный PostgreSQL повесил бы готовый ответ до разморозки (проба: 8,38 с и 8,64 с против 4,01 с). Цена: отказ БД при откате успешного чтения — 503, окно в один обмен. +- **Цена шага принята, проверка соединения при выдаче — одним запросом** (решение 7). На пробе вторая выдача опускает потолок реплики 1 CPU на истории и отправке на 10–25 %, CPU PostgreSQL поднимает на 13–51 %. Проверка диалекта asyncpg стоит три обмена (`BEGIN`, `;`, `ROLLBACK`, транзакция там ради pgbouncer, которого на стенде нет); с одним обменом CPU PostgreSQL около прежнего, потолок −1…−22 %, p50 +0,2…0,5 мс, удержание соединения на запрос −20…−36 % (шум прежнего кода между прогонами до 10 %). Это мера, а не часть паттерна; подмена опирается на внутренние имена адаптера, SQLAlchemy закреплён `<2.2`. Чтение без транзакции и соединение Core вместо сессии ORM отвергнуты и остаются готовыми мерами, если замер на коммите покажет больше. +- **Порты — `src/core/ports/`, реализации repo остаются в `src/core/repos/`, `SqlAlchemyUnitOfWork` — `src/infra/db/uow.py`** (решение 1). Атрибуты единицы работы: `users`, `sessions`, `chats`, `messages`, `idempotency`, `attachments`, `jobs`, `variants`, `job_replays`. +- **Строже книги:** вложенный вход и repo вне блока — ошибка, commit заканчивает блок (решение 2). Весь нынешний код и так фиксирует последним действием блока; autobegin `AsyncSession` иначе открыл бы молчаливую транзакцию без срока. +- **Экземпляр единицы работы — на задачу:** запрос в API, доставка в worker, сервис в последовательных процессах (решение 3). +- **`CurrentUserBrief` убран:** любой вход теперь короткий блок, а различие с JSON-ручками — только в общем сроке на роутере (решение 6). Свойство «соединение в пуле до тела запроса» сохраняется. +- **Кэш и S3 — те же модули с клиентом первым параметром;** в тестах настоящие функции поверх фейков клиентов (решение 8). +- **Фейки — по контракту метода, общий набор `service-tests/repo_contract.py` на фейке и на SQL** (решение 11). Отсюда вторая цель `make service_test_db` на временной базе: она же проверяет настоящую единицу работы и общий срок запроса, а замороженный сервер даёт TCP-прокси, без `docker pause` рабочего PostgreSQL. +- **Каталог `service-tests/`, цели `make service_test` и `make service_test_db`;** новых зависимостей нет: `async def` тесты запускает плагин `anyio`. +- **Новые сценарии — в capability `unit-of-work`, дельта `data-storage` только меняет текст:** `student-tests/` этим изменением не правятся, а сверка покрытия упала бы на сценарии без теста. `unit-of-work` в `CAPABILITIES` не входит: её проверяют `service-tests/`. +- **Замер «до» — из временного `git worktree` на commit до кода,** подряд с «после» и A/A (`tasks.md`, 13.1): `make bench_ab` требует коммита отката. Метки с профилем `quick` под своими именами идут в git, потому что на них ссылается отчёт. `Profile.rollout_from` не меняется, сравнение с предыдущей версией — аргументом `--from`. + +### Вопросы + +Пока нет. Вопросов преподавателю это изменение не добавляет: контракт и поведение API те же. + +### Для пользователя + +Основная сессия приняла расхождения с первоначальной постановкой, потому что сама её сформулировала, а решения пользователя они не меняют: общий срок JSON-запроса (решение 6) и дешёвую проверку соединения при выдаче (решение 7). Условие для второго: `make service_test_db` проверяет обрыв соединения с подменённой проверкой, чтобы смена внутренних имён SQLAlchemy падала тестом. Цена паттерна на этом стенде, по пробе: потолок реплики на истории и отправке ниже на 1–22 % (шум до 10 %), число соединений то же. Замер на коммите — группа 13 и `REPORT.md`. diff --git a/openspec/changes/unit-of-work/.openspec.yaml b/openspec/changes/unit-of-work/.openspec.yaml new file mode 100644 index 00000000..aa079bc5 --- /dev/null +++ b/openspec/changes/unit-of-work/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-31 diff --git a/openspec/changes/unit-of-work/design.md b/openspec/changes/unit-of-work/design.md new file mode 100644 index 00000000..9b05a57b --- /dev/null +++ b/openspec/changes/unit-of-work/design.md @@ -0,0 +1,395 @@ +# Design + +## Context + +Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. Образец — Cosmic Python («Architecture Patterns with Python», +глава 2 Repository, глава 6 Unit of Work). Правила слоёв: `service-layer.md`, `repo-layer.md`, `api-layer.md`, `infra.md`, `worker.md`. + +### Код + +Состояние — `9efab79` (архив `pipeline-reliability`, ветка `feat/unit-of-work`). Строк с `session_scope`, `db_scope`, `get_db_session`, +`commit()` и `rollback()` по файлам: `attachment_reconcile` 20, `dependencies` 16, `attachment_processing` 14, `attachment_cleanup` 14, +`attachment` 11, `attachment_relay` 11, `relay/main` 9, `attachment_replay` 7, `cleaner/main` 5, `worker/main` 4, `session` 4, `message` 3, `user` 1, +`chat` 1 (инфраструктура `scope`, `engine`, `errors` не в счёт). + +Границы сейчас двух видов: +- **JSON-ручки:** `get_db_session` — зависимость с `yield`, одна на запрос (кэш зависимостей FastAPI), её закрывают после отправки ответа. Срок + `asyncio.timeout(request_timeout_seconds)` накрывает весь запрос: вход, очередь KDF, запросы, отдачу ответа. Соединение занято с первого выражения до + commit или до конца ответа; +- **всё остальное** (вложения, worker, relay, уборщик, сверка, replay): `db_scope` — короткая сессия на шаг, без вложенных. Срок — на шаг. Вход у вложений — отдельный + `CurrentUserBrief`, чтобы срок запроса не накрыл передачу тела. + +Внешние имена, от которых зависят инструменты вне `src/`, — решение 12. `src/config/settings.py` импортирует `sqlalchemy.engine.URL`, поэтому запрет SQLAlchemy в +сервисах проверяется разбором импортов их файлов, а не по `sys.modules`. + +### Пробы (2026-10-31, scratchpad, проект compose `uowprobe`) + +Настоящее приложение из рабочего дерева, образ `mtusi-messenger:lab5`. Код проекта не менялся: контейнеры режимов шага получают свой `src/api/dependencies.py` монтированием, с теми же сервисами и repo внутри блока `bounded_scope`, поэтому запросы к PostgreSQL те же, что будут у шагов. +Реплика 1 CPU / 512 МБ, PostgreSQL 2 CPU / 1 ГБ, Valkey 0,5 CPU / 128 МБ, k6 закреплённого образа в той же сети; данные — tmpfs, volumes не создавались. Рабочий стенд работал рядом без нагрузки, на хосте были посторонние контейнеры `domains-*`: числа стоимости — порядок, а не замер для отчёта. После проб контейнеры и сеть удалены. + +Первый замер через `app.dependency_overrides` отброшен: при непустых подменах FastAPI на каждом запросе заново разбирает сигнатуры всех зависимостей (`get_dependant` в `solve_dependencies`), и режимы шага выглядели на 15–30 % дороже настоящего. + +Режимы: +- `per_request` — как сейчас; +- `per_step` — вход и операция сервиса: своя сессия на шаг, откат до ответа, общий срок запроса (решения 4–6); +- `per_step_ping1` — то же, проверка соединения при выдаче одним запросом (решение 7); +- `per_step_ro_ping1` — ещё и шаги чтения без транзакции (`AUTOCOMMIT`); +- `per_request_ping1` — прежняя граница с дешёвой проверкой. + +**Обмены с PostgreSQL на запрос** (журнал `log_statement = all`, соединение пула уже открыто). Проверка при выдаче (`pool_pre_ping`) диалекта asyncpg — три обмена: `BEGIN`, `;`, `ROLLBACK` +(`_async_ping`, транзакция там ради pgbouncer, #10226). Именно она делает лишнюю выдачу дорогой: + +| Режим | `GET /users/me` | `GET …/messages` | `POST …/messages` | +|---|---|---|---| +| `per_request` | 6 | 7 | 8 | +| `per_step` | 6 | 12 | 13 | +| `per_step_ping1` | 4 | 8 | 9 | +| `per_step_ro_ping1` | 2 | 4 | 7 | +| `per_request_ping1` | 4 | 5 | 6 | + +Разбор `per_step`, история: `BEGIN ; ROLLBACK BEGIN SELECT ROLLBACK` на вход и столько же на страницу. Отправка: шесть на вход, затем `BEGIN ; ROLLBACK BEGIN INSERT INSERT COMMIT`. + +**Стоимость.** Два прогона подряд, A / B, в каждом три повтора по кругу, медианы. Запросы в секунду и CPU на запрос — закрытая модель, 8 клиентов, реплика упирается в свой CPU; задержка и удержание соединения — постоянные 150 запросов в секунду. Соединений с PostgreSQL столько же, пул прежний; `Выдач` — выдач соединения из пула на запрос. Сам прежний код между прогонами расходится до 10 %: это порядок величины, замер для отчёта — группа 13 `tasks.md`. + +| Ручка | Режим | Запросов/с | CPU реплики, мс | CPU PostgreSQL, мс | p50 при 150/с, мс | Выдач | Удержание при 150/с, мс | +|---|---|---|---|---|---|---|---| +| `GET /users/me` | `per_request` | 1493 / 1524 | 0,67 / 0,65 | 0,17 / 0,17 | 1,59 / 1,59 | 1 | 0,91 / 0,86 | +| | `per_step` | 1488 / 1416 | 0,67 / 0,71 | 0,16 / 0,17 | 1,73 / 1,65 | 1 | 0,64 / 0,63 | +| | `per_step_ping1` | 1489 / 1501 | 0,68 / 0,67 | 0,13 / 0,13 | 1,57 / 1,63 | 1 | 0,66 / 0,67 | +| `GET …/messages` | `per_request` | 702 / 629 | 1,42 / 1,58 | 0,34 / 0,40 | 2,20 / 2,34 | 1 | 1,82 / 2,04 | +| | `per_step` | 526 / 569 | 1,90 / 1,76 | 0,50 / 0,45 | 2,79 / 2,75 | 2 | 1,28 / 1,32 | +| | `per_step_ping1` | 547 / 621 | 1,83 / 1,61 | 0,43 / 0,36 | 2,73 / 2,62 | 2 | 1,45 / 1,52 | +| `POST …/messages` | `per_request` | 580 / 620 | 1,73 / 1,61 | 0,42 / 0,37 | 2,57 / 2,64 | 1 | 2,03 / 2,39 | +| | `per_step` | 505 / 465 | 1,98 / 2,15 | 0,48 / 0,56 | 3,67 / 2,92 | 2 | 2,40 / 1,70 | +| | `per_step_ping1` | 521 / 534 | 1,92 / 1,87 | 0,41 / 0,38 | 2,85 / 2,83 | 2 | 1,50 / 1,53 | + +Остальные варианты, запросов/с и CPU реплики, мс: `per_step_ro_ping1` (прогон A) — история 623 и 1,61, отправка 546 и 1,83; соединение Core вместо сессии ORM с дешёвой проверкой (прогон B) — история 667 и 1,50, отправка 581 и 1,72, а без неё — как `per_step`, 556 и 483; `per_request_ping1` (прогон A) — история 722, отправка 629. + +**Порядок кодов.** Десять запросов отправки (нет токена, битый JSON, лишнее поле, нет ключа, посторонний, занятый ключ с другим телом, неизвестный токен) и история при работающем и при остановленном PostgreSQL дают одинаковые коды в `per_request`, `per_step` и `per_step_ping1`. После `pg_terminate_backend` всех соединений следующий запрос — 200 во всех трёх, заморозка сразу после обрыва — 503 за 3,01 с (срок подключения) тоже во всех трёх. + +**Сроки и замороженный PostgreSQL** («тесный» API стенда отказов: `request_timeout_seconds` 2, пул 1, ожидание пула 1 с, `kdf_concurrency` 1): + +| Проверка | `per_request` | `per_step` без общего срока | `per_step` с общим сроком | +|---|---|---|---| +| История: `sessions` занята 1,5 с, `messages` — 5 с | 503 за 2,02 с | 503 за 3,31 с | 503 за 2,02 с | +| 40 входов сразу | 15 × 201, 25 × 503, самый долгий 2,07 с | 40 × 201, самый долгий 4,69 с | 15 × 201, 25 × 503, самый долгий 2,10 с | +| Заморозка до запроса: первый запрос; второй, в очереди пула; после разморозки | 503 за 4,03 с; 503 за 1,01 с; 200 | 503 за 4,01 с; 503 за 1,01 с; 200 | 503 за 4,01 с; 503 за 1,01 с; 200 | + +4 с при сроке 2 с — срок плюс закрытие соединения `BoundedCloseConnection` (2 с); при сроке 6 с это 8 с, меньше `timeout server` 10 с. Занятых соединений после разморозки нет. + +| Окно на замороженном PostgreSQL | `session_scope` как сейчас | предлагаемый блок (решение 4) | +|---|---|---| +| Заморозка между SELECT и выходом из блока | висит до разморозки: 200 через 8,38 с (пауза пробы) | 503 за 4,01 с | +| Срок запроса истёк при открытой транзакции, внутри блока | висит до разморозки: 503 через 8,64 с | 503 за 4,01 с | + +Ещё: зависимость с `yield` в `include_router(dependencies=…)` на FastAPI 0.141.1 начинается раньше зависимостей ручки и переводит срок в ответ обработчика (медленная зависимость и медленная ручка — 503 за 0,20 с, +422 валидации и быстрый ответ не задеты, другой роутер без неё — 200 за 0,51 с). Плагин pytest из `anyio` 4.15.1 запускает `async def` тесты без новых зависимостей. + +### Что найдено до решений + +1. **Цена шага — не новые соединения, а вторая выдача.** Соединений столько же, а суммарное удержание на запрос даже ниже: соединение больше не держится на обработку и отправку ответа. На вторую выдачу уходит 3 обмена проверки и 2 обмена транзакции (решение 7). +2. **`request_timeout_seconds` сейчас держит больше, чем БД.** Он накрывает очередь KDF: без него 40 входов не получают отказа и ждут её целиком (4,69 с при сроке 2 с). И срок двух шагов — до `2T` = 12 с при + `timeout server` 10 с: клиент получил бы 504 от LB вместо 503 реплики (решение 6). +3. **Откат при выходе из блока сейчас вне срока.** На JSON-ручке это незаметно: сессия закрывается после ответа. На шаге откат идёт до ответа, и замороженный PostgreSQL повесил бы готовый ответ до разморозки (решение 4). +4. **Отмена задачи внутри блока на замороженном сервере — тоже зависание:** `session.close()` шлёт ROLLBACK (решение 4). +5. **`AttachmentProcessingService` живёт на весь процесс и работает одновременно в нескольких задачах доставки.** Экземпляр единицы работы с состоянием (открытая сессия) в нём делить нельзя (решение 3). +6. **`CurrentUserBrief` становится ненужным:** любой вход — короткий блок. Разница остаётся одна: у JSON-ручек есть общий срок, у вложений нет (решение 6). +7. **Сценарий в `data-storage` нельзя добавить без теста.** Сверка покрытия `student-tests/` падает на сценарии без теста или исключения, а `student-tests/` этим изменением не правятся. Поэтому дельта `data-storage` + меняет только текст требования, а новые сценарии — в capability `unit-of-work` вне `CAPABILITIES`. +8. **Порядок кодов ошибок не меняется.** Вход остаётся зависимостью и идёт раньше валидации параметров и тела (401 → 400 → 404 → 409), битый JSON разбирается раньше зависимостей, проверки внутри `send_message` и загрузки идут в том же порядке. Отказ БД на + входе — 503 до 400, как сейчас. Меняется только то, что запрос с ошибкой валидации больше не держит соединение до конца ответа. Проверяют `test_idempotency.py` (порядок кодов) и стенд отказов без правок. + +## Goals / Non-Goals + +**Goals:** +- Сервисы зависят только от абстракций и проверяются за секунды без хранилищ. +- Граница транзакции видна в одном месте: `async with self.uow:` и явный `commit`. +- Соединение занято только на шаг; общий срок JSON-запроса, порядок кодов, журнал и цепочка LB прежние. +- Все намеренные особенности транзакций записаны и закреплены тестами (решение 10). + +**Non-Goals:** +- Доменная модель с classical mapping, агрегаты, доменные события и message bus (главы 1, 7–9): логика и так в сервисах, транзакционные границы заданы контрактом, а не агрегатами. +- Ускорение JSON-пути сверх снятия цены этого изменения: чтение без транзакции и прочие оптимизации (решение 7). +- Новые настройки, смена схемы, правка `student-tests/` и `contracts/`. + +## Decisions + +### Решение 1. Слои и файлы: `src/core/ports/`, `src/core/repos/`, `src/infra/db/uow.py` + +| Что | Где | Импортирует | +|---|---|---| +| `AbstractUnitOfWork` | `src/core/ports/uow.py` | только порты | +| абстрактные repo: `AbstractUserRepository`, … по домену | `src/core/ports/.py` | DTO, enum, `src.utils` | +| реализации: `SqlAlchemyUserRepository`, … | `src/core/repos/.py`, те же файлы | SQLAlchemy, модели, порт | +| `SqlAlchemyUnitOfWork` | `src/infra/db/uow.py` | `session_scope`, реализации | + +Имена файлов те же, что во всех слоях (`AGENTS.md`). Порт — термин главы 2: абстрактный repo — порт, реализация — адаптер. Атрибуты единицы работы: `users`, `sessions`, `chats`, `messages`, `idempotency`, `attachments`, `jobs`, +`variants`, `job_replays`. Точки сборки — `src/api/dependencies.py`, `src/worker/main.py`, `src/relay/main.py`, `src/cleaner/main.py`: только они знают про `src/infra/db/uow.py`. + +Отвергнуто: +- абстракция и реализация в одном модуле, как `repository.py` в книге: сервис импортировал бы модуль с SQLAlchemy, и запрет нельзя проверить разбором импортов; +- реализации в `src/infra/db/repos/`: чище по направлению зависимостей, но `chat_cache.py` и `attachment_object.py` остаются в `src/core/repos/` (решение 8), и repo разъехались бы по двум местам; файлы и история `git` остаются на месте; +- один файл `abstract.py` на все домены: 60 методов, против правила об именах. + +### Решение 2. Единица работы: асинхронный контекст, явный commit, один блок — одна транзакция + +```python +class AbstractUnitOfWork(abc.ABC): + users: AbstractUserRepository + ... + async def __aenter__(self) -> Self: ... # вложенный вход — ошибка, счётчик блоков + 1 + async def __aexit__(self, exc_type, exc, tb): ... # откат незафиксированного, repo недоступны + @abc.abstractmethod + async def commit(self) -> None: ... # конец транзакции и блока: repo недоступны + @abc.abstractmethod + async def rollback(self) -> None: ... +``` + +В сервисе: + +```python +async with self.uow: + job = await self.uow.jobs.lock_job(job_id=job_id) + if job is None: + return JobOutcome.ACK # выход без commit — откат + await self.uow.jobs.finish_job(...) + await self.uow.commit() +``` + +Отличия от книги, и почему: +- асинхронный контекст: стек асинхронный; +- **вложенный вход — ошибка.** Сейчас это правило «без вложенных» держит только внимательность, а нарушение при пуле 1 — самоблокировка до срока. Реентерабельный блок скрыл бы границу транзакции; +- **repo доступны только внутри блока, и commit заканчивает блок.** `AsyncSession` после `commit` и `close` молча начинает новую транзакцию (autobegin) без срока и без отката: такая ошибка не видна ни в коде, ни в тестах. Весь нынешний код фиксирует последним действием блока + (`_claim`, `_publish`, `remove_stale_pending`, …), вход уже разнесён на два блока; +- **счётчик блоков `blocks_opened`** в базовом классе вместо обёртки `db_scope` у сверки: тот же смысл, число входов в блок, в том числе неудачных по пулу (решение 10); +- реальные шаги работы базовый класс оставляет реализации (`_open`, `_close`): у SQLAlchemy откат и сброс соединения устроены иначе, чем у фейка (решение 4). + +Отвергнуто: +- commit при выходе без исключения: компенсации загрузки нужно различать «упало до COMMIT» и «упало на COMMIT» (решение 10), а чтения и отказы фиксировать нечего. Книга и задание — откат по умолчанию; +- `Protocol` вместо `abc.ABC`: ABC проверяет полноту реализации при создании экземпляра, фейк без метода падает сразу. Сигнатуры сверяет тест (решение 11). + +### Решение 3. Экземпляр единицы работы — на задачу + +Экземпляр держит открытую сессию, поэтому принадлежит одной задаче: +- **API:** зависимость `get_uow` на запрос (кэш зависимостей FastAPI: вход и сервис одного запроса — один экземпляр, блоки идут по очереди); +- **worker:** одновременные доставки, поэтому `AttachmentProcessingService` собирается на доставку. `_handle` получает фабрику сервиса; `storage`, `renderer`, `stop` общие; +- **relay, уборщик, сверка, replay:** работа последовательная, экземпляр на сервис. + +Страховка — та же ошибка вложенного входа: вторая задача на том же экземпляре падает сразу, в том числе на фейке. + +Отвергнуто: фабрика `self.uow_factory()` в сервисе (вспомогательным методам пришлось бы передавать единицу работы параметром, как сейчас `db_session`); состояние в `ContextVar` (скрытая привязка к задаче ради того, что решает один объект на доставку). + +### Решение 4. `session_scope` остаётся внутри, откат — под сроком, отмена сбрасывает соединение + +`SqlAlchemyUnitOfWork` открывает блок через `session_scope` (`src/infra/db/scope.py`): срок `asyncio.timeout`, `is_db_unavailable` → `invalidate()`, `warning` «Database is unavailable», `ServiceUnavailable`. Единственный его пользователь — единица работы. Две правки, обе — следствие того, что блок теперь заканчивается до ответа (пробы): + +```python +async with session_factory() as db_session: + try: + async with asyncio.timeout(timeout_seconds): + try: + yield db_session + except Exception as e: + if not is_db_unavailable(e): + await db_session.rollback() # отказ сервиса или S3: откат под сроком + raise + else: + await db_session.rollback() # выход без commit; после commit — без обмена + except asyncio.CancelledError: + await db_session.invalidate() # откат на зависшем сервере повис бы + raise + except Exception as e: + if not is_db_unavailable(e): + raise + await db_session.invalidate() + logger.warning("Database is unavailable", error_type=type(e).__name__, error=str(e)) + raise ServiceUnavailable from e +``` + +Отказ БД при откате успешного чтения тоже становится 503, хотя данные прочитаны. Окно — один обмен, отвечать 200 по соединению в неизвестном состоянии незачем: ветка одна на все исходы, клиент повторит чтение. Отмена задачи — это остановка процесса или общий срок запроса, оба случая редки, цена — новое соединение вместо возврата в пул. + +### Решение 5. JSON-ручки: соединение на шаг + +| Ручка | Шаги после (вход — зависимость, свой блок) | +|---|---| +| `GET /users/me` | вход | +| `POST /users` | KDF вне блока; блок: вставка, commit | +| `POST /auth/sessions` | блок: хэш пароля из БД; KDF вне блока; блок: вставка, commit | +| `DELETE /auth/sessions/current` | вход; блок: удаление, commit | +| `POST /chats` | вход; блок: пользователи, чат, участники, commit; кэш после блока | +| `GET /chats` | вход; блок: страница | +| `GET /chats/{id}` | вход; блок: кэш, при промахе — чтение и запись в кэш | +| `GET …/messages` | вход; блок: членство, курсор, страница | +| `POST …/messages` | вход; блок: членство, вложения, ключ, сообщение, связи, commit | + +Блоки вложений, worker, relay, уборщика, сверки и replay переносятся один к одному: `async with self.db_scope() as db_session` → `async with self.uow`. + +Членство нужно и внутри чужого блока (сообщение, вложение), поэтому логика — модульная функция `require_member(uow, cache, *, chat_id, user_id)` в `services/chat.py`, она требует открытый блок. `ChatService.get_chat_for_member` — блок вокруг неё. Сессия при попадании в кэш соединения не берёт: выдача ленивая, блок стоит только объекта сессии. + +Отвергнуто: блок на операцию внутри `get_chat_for_member` и вызов её до основного блока сообщения: лишняя выдача на промах кэша и другой порядок относительно проверки вложений; реентерабельный блок (решение 2). + +### Решение 6. Общий срок JSON-запроса — отдельная зависимость без сессии + +Исходная постановка: «`request_timeout_seconds` — срок UoW, а не запроса», с просьбой оценить влияние на проверках отказов. Оценка (пробы): срок на блок верен для всех процессов, но как единственный срок на JSON-ручках он меняет поведение API: +- два шага дают до `2T` = 12 с, больше `timeout server` 10 с: 504 от LB вместо 503 реплики, и правило цепочки `balancer.md` («`timeout server` больше срока запроса с запасом на KDF») перестаёт выполняться; +- очередь KDF остаётся без срока: регистрация и вход под всплеском не отказывают, а ждут (4,69 с при сроке 2 с, рост с числом клиентов), и клиент, получивший 504, потом находит своего пользователя созданным. + +Поэтому срок блока — как в постановке, а JSON-роутеры сверх него сохраняют общий срок той же настройкой: + +```python +# src/api/routers/v1/__init__.py +json_deadline = [Depends(request_deadline)] +v1_router.include_router(user_router, dependencies=json_deadline) +v1_router.include_router(session_router, dependencies=json_deadline) +v1_router.include_router(chat_router, dependencies=json_deadline) +v1_router.include_router(message_router, dependencies=json_deadline) +v1_router.include_router(attachment_router) # у вложений срок на шаг +``` + +`request_deadline` — зависимость с `yield` вокруг `deadline_scope` (`src/infra/db/scope.py`): `asyncio.timeout`, `TimeoutError` → та же запись «Database is unavailable» и `ServiceUnavailable`. Это нынешний `get_db_session` без сессии: та же форма, тот же момент начала, то же закрытие после ответа. Новый JSON-роутер получает срок одной строкой. Внутренний срок блока на этих ручках не срабатывает первым: блок начат позже. Срок истекает отменой задачи, поэтому и нужна ветка `CancelledError` решения 4. + +Это расхождение с буквальным текстом постановки, оно названо в отчёте стадии и в `QUESTIONS.md`: убрать общий срок — одна строка на роутер, но тогда придётся менять цепочку LB и спек `load-balancing`. + +Отвергнуто: +- единственный срок на блок: выше; +- `timeout server` 14 с: спек «Прежний срок остальных путей», методика `failover` и `failover_pre_vus` рассчитаны на 10 с; +- `request_timeout_seconds` 4 с: меняет `B = 2T + S3` уборщика и цепочку загрузки 17 и 26 с, а выражения обрезает раньше `statement_timeout`; +- срок внутри единицы работы (экземпляр делит дедлайн между блоками, `timeout_at`): не накрывает KDF, а единице работы пришлось бы знать о запросе; +- `CurrentUserBrief` с отдельной цепочкой зависимостей вместо условия на роутере: две версии входа ради одного отличия. + +### Решение 7. Цена шага и дешёвая проверка соединения + +Новых соединений нет: пул прежний, и PostgreSQL видит столько же сессий. Цена — вторая выдача на двухшаговой ручке: 5 обменов и работа пула и сессии в процессе. Без меры на пробе потолок реплики на истории и отправке ниже на 10–25 %, а CPU PostgreSQL выше на 13–51 %. + +Мера — проверка соединения при выдаче одним запросом `;`: транзакция в `_async_ping` нужна только pgbouncer в режиме транзакций, которого на стенде нет. `create_engine` подменяет `do_ping` диалекта: + +```python +def _ping_once(dbapi_connection) -> bool: + try: + await_(dbapi_connection._connection.fetchrow(";")) + except Exception as error: + dbapi_connection._handle_exception(error) + return True + +engine.dialect.do_ping = _ping_once +``` + +`pool_pre_ping` и разбор обрыва прежние: `_do_ping_w_event` получает ту же ошибку адаптера. Вторая выдача стоит 3 обмена вместо 5, мера действует на все процессы. + +Что остаётся (`per_step_ping1` против `per_request`, прогоны A и B): CPU PostgreSQL около прежнего (история +25 % и −10 %, отправка −3 % и +3 %); удержание соединения на запрос ниже на 20–36 %; p50 при 150/с на двухшаговых ручках выше на 0,2–0,5 мс; потолок реплики на истории −22 % и −1 %, на отправке −10 % и −14 %; `GET /users/me` без изменений. Это цена, которую изменение принимает: загрузки, worker, relay и уборщик и так были на шагу и только выигрывают от дешёвой проверки, а трек 1 — про очередь, а не про потолок JSON. Точное число — метки группы 13 и `REPORT.md`. + +Отвергнуто: +- соединение Core вместо сессии ORM: repo и так пишут только выражения Core, но выигрыш на пробе +7–9 % на двухшаговых ручках — в пределах разброса, а единице работы понадобилась бы своя ленивая выдача соединения; +- чтение без транзакции (`AUTOCOMMIT`): минус 2 обмена на блок чтения (потолок истории 623 против 547 в том же прогоне), но это второй вид блока, и запись в нём зафиксировалась бы молча, а цель изменения — одна граница транзакции; +- `pool_pre_ping=False`: первый запрос после рестарта PostgreSQL получал бы 503; +- своя проверка событием `checkout` (публичный `run_async`): ошибки драйвера приходят непереведёнными, и разбор обрыва пришлось бы писать заново; +- вход и операция в одном блоке ради одной выдачи: это нынешняя граница. + +Варианты с Core и `AUTOCOMMIT` остаются готовыми мерами на случай, если метки группы 13 покажут цену выше оценки: это отдельные изменения, в API они не видны. + +### Решение 8. Кэш и S3 вне единицы работы: те же модули и клиенты + +`chat_cache.py` и `attachment_object.py` остаются модульными функциями с первым параметром `cache` и `storage`, сервисы получают клиентов конструктором, как сейчас. В быстрых тестах настоящие функции работают поверх фейков клиентов (`FakeCache`, `FakeObjectStorage`): ключи, разбор ключей и формат значения не дублируются. `JobPublisher` и `ImageRenderer` — так же, `UploadSlots` — настоящий: внешнего состояния у него нет. + +Отвергнуто: +- `uow.objects` и `uow.cache`: S3 и Valkey не транзакционны, `commit` их не фиксирует, а откат не возвращает удалённый объект. В единице работы это обещание, которого нет, и как раз намеренные вызовы S3 внутри блока (решение 10) стали бы неотличимы от обычных; +- классы и абстракции для этих модулей: вторая реализация ключей или обёртка без логики. Подмены клиента достаточно; +- `Protocol` для клиентов: mypy в проекте нет, а сигнатуры сверяет тест решения 11. + +### Решение 9. Repo-классы: перенос без изменения выражений + +Функция `f(db_session, *, …)` становится методом `f(self, *, …)` класса с `self._session`. Выражения, блокировки, `literal_execute`, колонки, вспомогательные функции и правило «одна операция на метод» те же; `repo-layer.md` остаётся в силе. Контракт метода (что значит `None` и `False`) — в докстринге порта, подробности SQL (почему константа, какой индекс) — у реализации. Модульные помощники (`_to_dto`, `MESSAGE_COLUMNS`, `USER_COLUMNS`) остаются модульными. + +### Решение 10. Намеренные особенности через единицу работы + +Проверено по коду `9efab79`. + +| Особенность | Сейчас | Через единицу работы | Что проверяет | +|---|---|---|---| +| Публикация внутри транзакции relay: блокировка строки как признак | `attachment_relay._publish`: `lock_due_jobs` → `publish_many` → `mark_published` → commit в одном `db_scope` | тот же порядок в одном блоке. Издатель вызывается внутри `async with self.uow`, срок 2 с < срока блока 6 с < простоя транзакции 10 с | быстрый тест порядка; `test_two_relays`, `test_relay_killed_after_confirm`, `test_published_backlog_limit` | +| DELETE в S3 под блокировкой уборщика, два шага | `remove_stale_pending`: блокировка, пометка, commit; сигнал; блокировка, DELETE, строка, commit | два блока, между ними проверка сигнала; вызов S3 — внутри второго | быстрый тест порядка и отказа S3; `test_cleaner_failure_after_object_delete`, `test_cleaner_survives_outages`, `test_upload_outlives_grace` | +| Очистка staging под `FOR NO KEY UPDATE` | `_remove_staging`: одна транзакция на строку | один блок на строку, те же выражения | быстрый тест `failed`; `test_staging_removed_after_ready`, `test_staging_keeps_current_work`, `test_staging_cleanup_survives_outage` | +| Ранний commit перед KDF при входе | `session.login`: чтение, `commit()`, KDF | блок чтения заканчивается до `verify_password` (откат: писать нечего). Соединения на KDF нет, как и раньше | быстрый тест порядка; `service_test_db`: на KDF занятых соединений 0 | +| Снятие блокировки ключа идемпотентности | `send_message`: `get_key_result`, `commit()` до ответа | `await self.uow.commit()` в конце ветки того же блока, проверка хэша и `IdempotencyConflict` — после него. Выход снял бы блокировку и без commit, но commit прежний: ветка та же на проводе | быстрый тест ветки; `test_same_key_at_once`, `test_same_key_through_replicas`, `driver.py hang-key` | +| Откат нового ключа при `failed` вложении | `rollback()` и `AttachmentFailed` | исключение внутри блока: откат при выходе | быстрый тест: после 409 ключ свободен; `test_attachment_failed_after_message`, `test_replay_after_attachment_failed` | +| Компенсация загрузки по флагу «COMMIT отправлен» | `_mark_queued`: `commit_sent = True` прямо перед `commit()`, `try` вокруг scope | тот же код: явный `commit()` — отдельная точка, флаг перед ним. Автокоммит при выходе не дал бы отличить сбой выражения от сбоя COMMIT | быстрый тест трёх веток; `test_queued_failure_compensated`, `test_queued_commit_outcome_unknown`, `test_upload_outlives_grace` | +| Счёт сеансов сверки | обёртка `db_scope`, `_db_sessions`, её же получает внутренний сервис уборки | `uow.blocks_opened`, разность в `_Pass`; у внутреннего `AttachmentCleanupService` тот же экземпляр. Поле `db_sessions` журнала и `ReconcilePassDTO` прежнее | быстрый тест числа блоков; `test_reconcile_head_strategy_same_findings`; `bench/reconcile.py` сверяет с моделью | +| Сеанс на шаг уборщика и сверки, сигнал между шагами | `check_stop()`, `stop_requested()` между `db_scope` | те же блоки, сигнал — вне их | быстрый тест остановки; `driver.py reconcile-signal`, спек `graceful-shutdown` | +| `FOR NO KEY UPDATE`, `SKIP LOCKED` | выражения repo | те же выражения в методах | `test_two_relays`, `test_staging_keeps_current_work`, `test_cleaner_*` (решение 11) | +| Fencing | `_own_attempt`, условие `return_to_queued(attempt=…)` | те же проверки внутри блока | быстрый тест таблицы claim и `superseded`; `test_hung_worker_lease_fencing`, `test_hung_worker_thawed_after_ready` | +| `literal_execute` в выборках статусов | `_queued`, `_stale_pending`, `_staging_condition` | те же модульные функции | `service_test_db`: статус константой в тексте выражения; планы — `evidence/migrations/pipeline-reliability.md` | +| Вход с короткой сессией (`CurrentUserBrief`) | своя зависимость у вложений | любой вход — короткий блок: `CurrentUserBrief` убран, ручки вложений берут `CurrentUser`, а общего срока у их роутера нет (решение 6). Соединение в пуле до тела запроса | `service_test_db`: вложение дольше срока блока; `test_slow_body`, `test_upload_waits_for_slot` | +| Вызовов S3 в транзакциях worker нет | `_produce` вне `db_scope` | `_produce` вне блока | быстрый тест: `put` не между входом и выходом из блока | + +### Решение 11. Быстрые тесты: фейки по контракту метода, а не копия SQL + +**Фейки, а не моки.** Как в книге: тест проверяет исход, а не набор вызовов, и один фейк служит всем сервисам. `FakeDatabase` — таблицы-словари замороженных DTO, общие для экземпляров `FakeUnitOfWork`, как PostgreSQL для процессов. Вход в блок снимает снимок таблиц, откат его возвращает: «выход без commit» и атомарность проверяются по состоянию, а не по флагу `committed`. Тот же базовый класс — те же ошибки вложенного блока и repo вне блока. + +**Что есть в фейке, чего нет.** Метод реализует контракт из докстринга порта: условие перехода (`mark_queued` — `pending` и непомеченная, `return_to_queued` — та же попытка, `claim_key` — свободный или просроченный), keyset по полям, порядок результата. Нет: плана запроса, блокировок и ожидания, индексов, внешних ключей, `greatest`. Занятую строку (`SKIP LOCKED`) тест объявляет явно (`database.held`), отказ — явно (`fail_on`, `fail_commit`). Порядок действий, от которого зависит согласованность, виден в общем журнале `database.events`: вход, выражения, вызовы S3 и издателя, commit, выход. + +**Без дублирования SQL.** Условие метода всё равно написано дважды: на SQL и в Python. Разойтись им не даёт один набор `service-tests/repo_contract.py`: данные через методы портов, те же ожидания для каждого метода, по результату которого ветвятся сервисы. `make service_test` гоняет его на фейке за секунды, `make service_test_db` — на SQL, на временной базе. Сигнатуры и полноту сверяет `test_architecture.py` без БД. Сервисные тесты при этом не знают условий: они задают исходное состояние и смотрят исход. + +| Свойство | Почему фейк не может | Где доказано | +|---|---|---| +| `FOR UPDATE SKIP LOCKED`: два relay не публикуют одно задание | нужна настоящая конкуренция транзакций | `test_two_relays` | +| `FOR NO KEY UPDATE`: отправка сообщения не ждёт DELETE в S3 | конфликт режимов блокировки считает PostgreSQL | `test_staging_cleanup_survives_outage` (`attachment-free`) | +| `lock_job` и ожидание: worker ждёт COMMIT relay, fencing при заморозке | ожидание блокировки и реальные процессы | `test_relay_killed_after_confirm`, `test_hung_worker_lease_fencing`, `test_crash_after_commit_before_ack` | +| Захват ключа ждёт чужую транзакцию, гонка | `ON CONFLICT` и блокировка строки | `test_same_key_at_once`, `test_same_key_through_replicas`, `test_race.py` | +| Отложенный внешний ключ: ключ раньше сообщения | проверка внешних ключей | `test_message_failure_keeps_key_free`, весь набор отправки | +| Исход COMMIT, триггеры, `statement_timeout`, простой транзакции | сервер | `test_queued_commit_outcome_unknown`, `test_cleaner_failure_after_object_delete`, `driver.py hang-key` | +| Перевод отказа драйвера в 503, сброс соединения, срок блока, откат на зависшем сервере | настоящий драйвер и пул | `test_pool_exhausted`, `test_connection_limit_reached`, `test_database_stopped_and_back`; `service_test_db` (TCP-прокси, который перестаёт отвечать) | +| План запроса и частичные индексы | планировщик | `evidence/migrations/pipeline-reliability.md` | + +Поэтому `student-tests/` и `make failure_checks` остаются главным доказательством поведения, а быстрые тесты — скорость на ветках сервисов. + +Отвергнуто: +- `AsyncMock(spec=…)`: проверка вызовов, а не исхода, и каждый тест заново задаёт ответы repo; условия не закреплены нигде; +- SQLite: другой SQL (`FOR UPDATE`, `ON CONFLICT`, `ARRAY`, `timestamptz`) и всё равно не быстрее словарей; +- фейки без общего набора: условие разошлось бы молча. + +### Решение 12. Внутренние имена, на которые опираются инструменты вне `src/` + +Проверено поиском по `student-tests/`, `bench/`, `scripts/`, `.claude/skills/`. Должны остаться: +- `fault_hook.py`: `src.config.settings`, `src.infra.broker.queue_name`, командная строка `src.worker.render`; таблицы и колонки в psql; записи журнала; +- `driver.py`: `src.infra.db.session.engine` (`hang-key`), `src.config.settings`, `src.infra.s3.client` (`s3-idle`), `python -m src.<сервис>`; +- тесты и `bench/reconcile.py`: поле `db_sessions` итога сверки, записи журнала; hook запускает процессы, а не сервисы; +- `bench/`: импортов `src` нет, в паспорте — только версия пакета SQLAlchemy. + +Имён сервисов, repo, `session_scope` и `get_db_session` вне `src/` никто не использует, кроме раздела «Direct invocation» в `SKILL.md`: его примеры обновляются (`tasks.md`). Модули `src/infra/db/session.py` и `engine` остаются: их импортируют `main.py`, `dependencies.py` и драйвер. + +### Решение 13. Каталог, цели, образ + +``` +service-tests/ + pytest.ini # rootdir, pythonpath, addopts; pyproject.toml не применяется + fakes/ # FakeDatabase, FakeUnitOfWork, фейки repo и клиентов + unit/ # make service_test: без БД, docker и сети + db/ # make service_test_db: временная база test_uow_ +``` + +- `make service_test` — `uv run pytest service-tests/unit`. `settings` читает `.env` и `config.toml` по абсолютному пути от корня проекта, поэтому автоматическая фикстура `conftest.py` подставляет (`monkeypatch`) поля, от которых зависят ветки сервисов: попытки и сроки worker, места загрузок, сроки сессии и ключа. Результат не зависит от локальных файлов, а к хранилищам тесты и так не обращаются. `anyio` уже есть в зависимостях, его плагин запускает `async def` тесты: новых зависимостей и правки `uv.lock` нет. +- `make service_test_db: start_db` — на временной базе `test_uow_`: имя проверяется шаблоном до любых действий, база создаётся и мигрирует в начале, удаляется при любом исходе; те же приёмы, что `run_isolated.py`. Настройки «тесного» API — окружением до импорта `src`; приложение — в процессе теста через `httpx.ASGITransport`; S3 и кэш — фейки или закрытый порт: рабочий стенд, кроме его PostgreSQL как сервера, не затрагивается. +- `make student_test` каталог не собирает: `testpaths` в `pyproject.toml` прежний, правило black-box прежнее. В `pyproject.toml` — `src` ruff и `per-file-ignores` для неиспользуемых аргументов фейков. +- `.dockerignore` — `service-tests`; `Dockerfile` копирует только `src/` и миграции, но контекст сборки не должен тащить тесты, как `student-tests`. +- CI: шаг `make service_test` после `uv sync` в `.github/workflows/application.yml`. `service_test_db` в CI нет: нет порта PostgreSQL на хосте. + +### Решение 14. Порядок реализации — одним проходом + +Repo-функции вызываются из многих сервисов (`attachment` — из шести), поэтому промежуточного состояния, где половина сервисов на единице работы, а модульные функции ещё нужны второй половине, нет без временных обёрток. Перенос идёт одним проходом: порты → repo-классы → единица работы → фейки → сервисы с их быстрыми тестами → сборка. До группы сборки приложение не стартует, проверка — `make lint` и `make service_test` по уже перенесённым сервисам (`tasks.md`). История при этом одна запись на весь код: основная сессия коммитит группы кода разом. + +## Risks / Trade-offs + +- [Вторая выдача соединения: потолок реплики на истории и отправке падает, на пробе до 22 % при шуме 10 %] → решение 7, замер «до и после» на закоммиченном коде, цена — в `REPORT.md`; если окажется выше оценки — готовые меры там же, отдельным изменением. +- [Подмена `do_ping` опирается на внутренние `_connection` и `_handle_exception` адаптера] → SQLAlchemy закреплён `<2.2`; обрыв проверяют `service_test_db`, `test_connection_limit_reached`, `test_database_stopped_and_back`, рестарт — `make test-persistence`. +- [Два ожидания пула вместо одного: под перегрузкой запрос встаёт в очередь дважды, и запас на ожидание у него — около половины общего срока] → соединение держится короче (нет удержания на ответ и на работу приложения между выражениями), общий срок прежний, серии трека 1 мерят итоговый код. Сверх общего срока запрос всё равно получает 503. +- [Фейк разошёлся с SQL] → `repo_contract.py` на обоих, сверка сигнатур. +- [Быстрые тесты зелёные, а блокировка сломана] → блокировки — только `make failure_checks`, таблица решения 11; его полный прогон входит в готовность изменения. +- [Большой разовый diff] → `src/core/repos/` меняется механически, выражения те же; `student-tests/` не правятся и доказывают поведение; временные регрессии показывают, что тесты ловят нарушения (`tasks.md`). +- [Откат успешного чтения при отказе БД даёт 503 вместо 200] → окно в один обмен, решение 4; клиент повторяет чтение. +- [Отмена сбрасывает соединение: при остановке процесса пул теряет занятые соединения] → процесс и так выходит; срок запроса означает зависший сервер. +- [`request_timeout_seconds` теперь значит «срок блока, а на JSON-ручке ещё и весь запрос»] → комментарий в `settings.py`, `infra.md`, `api-layer.md`, раздел `REPORT.md`. +- [Смесь версий при `make rolling_update`] → схема, сообщения и ответы те же; старые и новые реплики, worker, relay и уборщик работают вместе в любом порядке. + +## Migration Plan + +Схемы, настроек и секретов не меняется. Вперёд: `make rolling_update` (миграций нет, скрипт прогоняет no-op), затем `docker compose up -d --no-deps worker relay cleaner`. Порядок неважен: новые и старые процессы совместимы. Откат: `make rolling_update COMMIT=<прежний> MIGRATE=0` и прежний образ тех же сервисов; `Profile.rollout_from` остаётся `7f38948` (`bench.md`: commit меняется при новой лабе или когда замена должна показать новое изменение схемы, здесь схемы нет), поэтому `make bench_rollout` показывает замену с версии до `pipeline-reliability` и CPU на запрос старых и новых реплик в одном прогоне. diff --git a/openspec/changes/unit-of-work/proposal.md b/openspec/changes/unit-of-work/proposal.md new file mode 100644 index 00000000..f14faea4 --- /dev/null +++ b/openspec/changes/unit-of-work/proposal.md @@ -0,0 +1,63 @@ +# Proposal + +## Why + +Сервисы сейчас сами открывают сессию (`db_scope`, `get_db_session`) и зовут `commit()`, а repo — +модульные функции над `AsyncSession`. Поэтому граница транзакции размазана по двум видам кода: JSON-ручки +держат сессию на весь запрос, вложения, worker, relay и уборщик — на шаг. Сервис нельзя проверить без +PostgreSQL, и ветки компенсации, fencing и отказов доказываются только получасовым стендом отказов. +Пользователь включает в лабу паттерн Unit of Work полноценно, по Cosmic Python (главы 2 и 6): отдельным +изменением до `track1-queue-overload`, чтобы трек 1 мерил итоговый код. + +## What Changes + +- **Абстракции.** `AbstractUnitOfWork` и абстрактные repo по доменам: сервисы зависят только от них. В + `src/core/services/` не остаётся `AsyncSession`, SQLAlchemy и глобалов хранилищ. +- **Реализации на SQLAlchemy.** `SqlAlchemyUnitOfWork` и repo-классы вместо модульных функций. SQL, блокировки + и `literal_execute` те же, переезжают в методы. Цепочка `session_scope` остаётся внутри UoW. +- **Граница в одном месте.** В сервисе: `async with self.uow:`, `self.uow.jobs.lock_job(...)`, явный + `await self.uow.commit()`; выход без commit — откат. Вложенный блок и repo вне блока — ошибка. +- **Соединение на шаг во всех процессах.** JSON-ручки тоже: вход и операция — разные блоки, соединение в пуле между + ними, на время хэша пароля и передачи ответа. `request_timeout_seconds` — срок блока, откат при выходе входит в + него. Общий срок JSON-запроса сохраняется отдельной зависимостью без сессии: иначе срок двух шагов (12 с) перерос бы + `timeout server` LB (10 с), а очередь хэшей осталась бы без срока (проба, design, Context). Цену второй выдачи соединения + снижает проверка соединения при выдаче одним запросом вместо трёх. +- **Быстрые тесты.** `FakeUnitOfWork`, фейковые repo и клиенты; новый каталог `service-tests/` вне образа и + цель `make service_test` без БД и docker. Цель `make service_test_db` на временной базе закрепляет совпадение + фейка и SQL и поведение настоящего UoW. Правило black-box для `student-tests/` не меняется. +- **Документы.** Правила слоёв, `AGENTS.md`, скилл `run-mtusi-messenger`, `REPORT.md`. + +Не входят: доменная модель с classical mapping, агрегаты, доменные события и message bus (главы 1, 7–9). +`Cache` Valkey и `ObjectStorage` S3 остаются клиентами за своими интерфейсами и в UoW не входят. + +Поведение API, контракт, публичные тесты, схема и настройки не меняются: миграций нет, тесты `student-tests/` и `make +failure_checks` не правятся и доказывают отсутствие регрессий. + +## Capabilities + +### New Capabilities + +- `unit-of-work`: граница транзакции в сервисах, зависимость от абстракций, соединение на шаг, срок блока и отказ + PostgreSQL, общий срок JSON-запроса, намеренные вызовы внешних систем внутри блока, быстрые тесты сервисов и цена шага + в отчёте. + +### Modified Capabilities + +- `data-storage`: «Ограниченный пул соединений и таймауты» — запрос занимает соединение на шаг, а не на весь запрос; + сценарии те же. + +## Impact + +- **API:** коды, тела, порядок проверок и журнал прежние. Цена — вторая выдача соединения на двухшаговой JSON-ручке: на пробе + потолок реплики 1 CPU на истории и отправке ниже на 1–22 % при шуме 10 %, p50 выше на 0,2–0,5 мс, удержание соединения на запрос + ниже на 20–36 %. Оценка — design, решение 7; замер — последняя группа `tasks.md`. +- **Код:** новые `src/core/ports/`, `src/infra/db/uow.py`; `src/core/repos/*` (кроме `chat_cache.py` и + `attachment_object.py`) — классы; все сервисы; `src/infra/db/scope.py`, `src/infra/db/engine.py`; + `src/api/dependencies.py`, `src/api/routers/v1/`; точки входа worker, relay, уборщика. +- **Тесты и инструменты:** новый `service-tests/`, `Makefile`, `pyproject.toml`, `.dockerignore`, + `.github/workflows/application.yml`; `student-tests/`, `fault_hook.py`, `bench/` и схема — без правок (проверка внутренних + имён — design, решение 12). +- **Документы:** `.claude/rules/` (`service-layer`, `repo-layer`, `api-layer`, `infra`, `worker`, `auth`, `logging`, новый + `service-tests`), `AGENTS.md`, `.claude/skills/run-mtusi-messenger/SKILL.md`, `REPORT.md`, `QUESTIONS.md`. +- **Зависимости и образ:** новых зависимостей нет (`anyio` уже есть), `uv.lock` тот же, образ содержит только новые модули + `src/`. diff --git a/openspec/changes/unit-of-work/specs/data-storage/spec.md b/openspec/changes/unit-of-work/specs/data-storage/spec.md new file mode 100644 index 00000000..c9314498 --- /dev/null +++ b/openspec/changes/unit-of-work/specs/data-storage/spec.md @@ -0,0 +1,37 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Ограниченный пул соединений и таймауты + +Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой. +Ожидание свободного соединения, подключение и выполнение запроса SHALL +иметь таймауты из настроек. Истёкший таймаут SHALL давать 503 +`unavailable`. + +Запрос SHALL занимать соединение только на время шага с PostgreSQL, а не на +весь запрос (capability `unit-of-work`). Между шагами, на время вычисления +хэша пароля и передачи ответа соединение SHALL быть в пуле. + +Пул SHALL держать постоянный набор соединений. Соединение, возвращённое +в пул после шага, SHALL оставаться открытым и обслуживать следующие +запросы. При настройках по умолчанию соединений сверх размера пула +сервис MUST NOT открывать. Запрос, которому не хватило свободного +соединения, SHALL ждать его в очереди пула не дольше таймаута ожидания, +а не открывать новое соединение с PostgreSQL. Новое соединение сервис +открывает, только пока пул не набрал своего размера, и взамен +соединения, закрытого после обрыва или отказа. + +#### Scenario: Соединения исчерпаны + +- **WHEN** все соединения пула заняты дольше таймаута ожидания +- **THEN** новый запрос получает 503 `unavailable` не позже этого + таймаута, а не ждёт бесконечно + +#### Scenario: Соединения пула не переоткрываются + +- **WHEN** пул прогрет, и сервису раз за разом приходят пачки + одновременных запросов, которых больше, чем соединений в пуле +- **THEN** все запросы пачек обслуживаются успешно +- **AND** PostgreSQL за время пачек не принимает от сервиса ни одного + нового соединения diff --git a/openspec/changes/unit-of-work/specs/unit-of-work/spec.md b/openspec/changes/unit-of-work/specs/unit-of-work/spec.md new file mode 100644 index 00000000..d4ce6ab1 --- /dev/null +++ b/openspec/changes/unit-of-work/specs/unit-of-work/spec.md @@ -0,0 +1,247 @@ +# Spec Delta + +## Purpose + +Как сервисы работают с PostgreSQL: граница транзакции названа в одном месте, сервисы зависят от абстракций и проверяются +быстрыми тестами без хранилищ, а соединение занято только на время шага. Поведение API эта capability не меняет. + +## ADDED Requirements + +### Requirement: Граница транзакции в сервисе + +Работа сервиса с PostgreSQL SHALL идти внутри блока единицы работы: один блок — одна транзакция. Изменения SHALL +фиксироваться только явной фиксацией в сервисе. Выход из блока без фиксации, в том числе по исключению, SHALL откатывать +незафиксированное: автоматической фиксации при выходе нет. После фиксации блок закончен: обращение к repo и вторая фиксация в +нём MUST завершаться ошибкой, следующая транзакция идёт следующим блоком. Repo MUST NOT фиксировать и откатывать. + +#### Scenario: Выход без фиксации + +- **WHEN** сервис записал строку внутри блока и вышел из него без фиксации +- **THEN** строки нет ни в этом, ни в другом соединении с PostgreSQL + +#### Scenario: Исключение внутри блока + +- **WHEN** внутри блока после записи брошено доменное исключение +- **THEN** запись откатывается, а вызывающий получает то же исключение + +#### Scenario: Фиксация + +- **WHEN** сервис записал строку, зафиксировал и вышел из блока +- **THEN** строку сразу видит другое соединение с PostgreSQL + +#### Scenario: Работа после фиксации + +- **WHEN** после фиксации сервис обращается к repo того же блока +- **THEN** это ошибка программирования, а не молчаливая вторая транзакция + +### Requirement: Сервисы зависят от абстракций + +Все сервисы всех процессов — API, worker, relay, уборщика, команды replay и сверки — SHALL получать единицу работы через +конструктор и обращаться к repo PostgreSQL только через неё. В коде сервисов MUST NOT быть сессии БД, импорта SQLAlchemy, +импорта реализаций единицы работы и repo и глобалов хранилищ. Реализации SHALL выбирать точки входа процессов. + +Кэш Valkey и S3 в единицу работы не входят: их клиенты SHALL передаваться сервису отдельно, а фиксация и откат на них не +действуют. + +#### Scenario: Запрещённый импорт + +- **WHEN** в сервис добавлен импорт SQLAlchemy, реализации единицы работы или repo на SQL +- **THEN** `make service_test` завершается с ненулевым кодом и называет файл и импорт + +#### Scenario: Сервис без хранилищ + +- **WHEN** сервис собран с фейковой единицей работы и фейками кэша, S3, брокера и процесса обработки +- **THEN** он выполняет свои ветки без PostgreSQL, Valkey, S3, брокера и docker + +### Requirement: Блок не вкладывается и не делится между задачами + +Единица работы SHALL открывать не больше одного блока одновременно: вход в уже открытый блок MUST завершаться ошибкой, а не +второй транзакцией и вторым соединением. Обращение к repo вне блока MUST завершаться ошибкой. Экземпляр единицы работы SHALL +принадлежать одной задаче: у каждого запроса и у каждой одновременной доставки worker он свой. Те же правила SHALL действовать +в фейке, чтобы быстрый тест ловил нарушение. + +#### Scenario: Вложенный блок + +- **WHEN** внутри открытого блока сервис входит в него ещё раз +- **THEN** вход завершается ошибкой, и второго соединения нет + +#### Scenario: Repo вне блока + +- **WHEN** сервис обращается к repo после выхода из блока или до входа в него +- **THEN** обращение завершается ошибкой, запроса к PostgreSQL нет + +#### Scenario: Одновременные доставки + +- **WHEN** worker обрабатывает две доставки одновременно +- **THEN** у каждой своя единица работы, и шаг одной не влияет на транзакцию другой + +### Requirement: Соединение на шаг + +Блок SHALL занимать соединение пула только от первого обращения к PostgreSQL до выхода из блока. Запрос MUST NOT занимать больше +одного соединения одновременно. В JSON-ручках проверка токена и операция сервиса SHALL быть разными блоками. На время вычисления +хэша пароля, между шагами и на время передачи тела и ответа соединение SHALL быть в пуле. Новых соединений с PostgreSQL сверх пула +это MUST NOT добавлять. + +#### Scenario: Ответ без занятого соединения + +- **WHEN** JSON-ручка с токеном читает из PostgreSQL и начинает отправлять ответ +- **THEN** соединение выдавалось ей дважды, а в момент отправки ни одно не занято + +#### Scenario: Пул из одного соединения + +- **WHEN** пул процесса — одно соединение, и одновременно идут две JSON-ручки по два шага +- **THEN** обе получают успешный ответ: запрос не ждёт соединение, которое занял сам + +#### Scenario: Вход не держит соединение на хэш + +- **WHEN** выполняется вход, и идёт проверка пароля +- **THEN** соединение запроса в пуле, и другой запрос при пуле из одного соединения обслуживается + +#### Scenario: Блок без обращения к PostgreSQL + +- **WHEN** карточка чата есть в кэше, и участник читает чат +- **THEN** соединение для этого блока не выдаётся + +### Requirement: Срок блока и отказ PostgreSQL + +Блок, включая откат при выходе, SHALL укладываться в `[database] request_timeout_seconds`. Если PostgreSQL недоступен или не ответил +в срок, соединение SHALL сбрасываться: оно не возвращается в пул и не получает команду отката, которая повисла бы на зависшем сервере. +В журнал SHALL уходить `warning` «Database is unavailable» без параметров запроса, а вызывающий SHALL получать доменный отказ, +который API отдаёт как 503 `unavailable`. Отмена задачи внутри блока SHALL сбрасывать соединение так же. Прочие ошибки PostgreSQL +(нарушение ограничения, ошибка триггера) SHALL откатывать транзакцию и доходить до вызывающего как есть: это дефект, и ответ на него — 500. + +#### Scenario: Запрос дольше срока + +- **WHEN** выражение внутри блока выполняется дольше срока блока +- **THEN** вызывающий получает доменный отказ, в журнале одна запись «Database is unavailable», соединение в пул не вернулось, а + следующий блок получает рабочее соединение + +#### Scenario: PostgreSQL заморожен при откате + +- **WHEN** блок чтения выполнил выражение, PostgreSQL заморожен, и блок завершается без фиксации +- **THEN** доменный отказ приходит не позже срока блока и срока закрытия соединения, а не после разморозки + +#### Scenario: Отмена при открытой транзакции + +- **WHEN** задача отменена внутри блока с открытой транзакцией при замороженном PostgreSQL +- **THEN** отмена доходит до вызывающего не позже срока закрытия соединения, а соединение в пул не вернулось + +#### Scenario: Нарушение ограничения + +- **WHEN** выражение внутри блока нарушает ограничение PostgreSQL +- **THEN** транзакция откачена, вызывающий получает исходную ошибку, записи «Database is unavailable» нет, соединение осталось в пуле + +### Requirement: Общий срок JSON-запроса + +Запросы ручек пользователей, сессий, чатов и сообщений SHALL целиком укладываться в `[database] request_timeout_seconds`: все их блоки и +очередь вычисления хэша пароля вместе. Срок истёк — ответ 503 `unavailable` и та же запись «Database is unavailable». Так ответ реплики +приходит раньше `timeout server` балансировщика (10 с), как и до разделения запроса на шаги. Ручки вложений общего срока MUST NOT иметь: +передача тела и потока дольше срока одного блока, у них срок на шаг (`load-balancing`, «Загрузки через балансировщик»). + +#### Scenario: Два медленных шага + +- **WHEN** срок равен T, проверка токена заняла больше половины T, а операция сервиса ждёт дольше оставшегося +- **THEN** клиент получает 503 `unavailable` через ~T, а не через сумму сроков двух блоков + +#### Scenario: Очередь хэшей + +- **WHEN** входов одновременно больше, чем успевает обработать ограничение вычисления хэша за T +- **THEN** не успевшие получают 503 `unavailable` через ~T, а не ждут очередь без срока + +#### Scenario: Вложение дольше срока блока + +- **WHEN** загрузка вложения или скачивание потоком идёт дольше `[database] request_timeout_seconds`, а каждый шаг с PostgreSQL укладывается в него +- **THEN** запрос завершается успешно + +### Requirement: Намеренные особенности транзакций сохраняются + +Переход на единицу работы MUST NOT менять порядок действий, от которого зависит согласованность: +- публикация relay идёт внутри блока, после блокировки строк и до отметки: блокировка строки и есть признак «публикует другой relay»; +- уборка зависшей загрузки — два блока: пометка строки, затем объект и строка; удаление объекта — внутри второго блока, раньше удаления + строки; очистка staging — внутри блока, под блокировкой строки, которая не мешает отправке сообщения; +- при фиксации `queued` сбой до отправки фиксации удаляет объект staging, а сбой на самой фиксации его не трогает: исход неизвестен; +- вход закрывает блок чтения до проверки пароля, сессия пишется вторым блоком; +- занятый ключ идемпотентности: сохранённое сообщение читается, блокировка строки ключа снимается до ответа, а новый ключ при `failed` вложении + откатывается; +- worker: вызовов S3 внутри блоков нет, а итог фиксирует только попытка с текущим номером; +- между шагами уборщика и сверки проверяется сигнал остановки, а итог сверки называет число блоков (`db_sessions`). + +Блокировки выражений, условие `SKIP LOCKED` и статусы константой в выборках SHALL остаться прежними. + +#### Scenario: Порядок публикации + +- **WHEN** relay публикует пакет +- **THEN** порядок действий: блокировка строк → публикация → отметка подтверждённых → фиксация, и всё это один блок + +#### Scenario: Порядок уборки + +- **WHEN** уборщик убирает зависшую загрузку, а S3 отказал на удалении объекта +- **THEN** пометка уже зафиксирована первым блоком, второй блок откачен, строка на месте и ждёт следующего прохода + +#### Scenario: Компенсация различает исход фиксации + +- **WHEN** перевод в `queued` падает на выражении, а в другом прогоне — на самой фиксации +- **THEN** в первом случае объект staging удалён, во втором на месте, и оба раза ответ 503 + +#### Scenario: Вложение стало failed до сообщения + +- **WHEN** новое сообщение ссылается на `failed` вложение +- **THEN** ответ 409, ни ключа, ни сообщения в PostgreSQL нет + +#### Scenario: Счёт блоков сверки + +- **WHEN** сверка выполняет проход +- **THEN** `db_sessions` итога равно числу блоков прохода, включая блоки уборки зависших загрузок + +### Requirement: Быстрые тесты сервисов + +Цель `make service_test` SHALL проверять ветки всех сервисов на фейках, без PostgreSQL, Valkey, S3, брокера, docker и сети. Каталог этих тестов +SHALL лежать вне `student-tests/`: `make student_test` его не собирает, а правило «только по HTTP» для `student-tests/` не меняется. В образ +приложения каталог MUST NOT попадать. + +Набор методов и их сигнатуры у абстрактного repo, его реализации на SQL и фейка SHALL совпадать; у фейков кэша, S3, издателя и процесса обработки +— с настоящими клиентами. Расхождение SHALL ронять `make service_test` и называть класс и метод. + +Один набор проверок условий repo SHALL выполняться на фейке целью `make service_test` и на настоящем SQL целью `make service_test_db`. Эта же цель SHALL на временной +базе в PostgreSQL стенда проверять настоящую единицу работы и общий срок JSON-запроса. Временная база SHALL удаляться при любом исходе, рабочая база MUST NOT +затрагиваться. Блокировки и поведение под конкуренцией остаются за `make failure_checks`: фейк их не воспроизводит. + +#### Scenario: Без хранилищ + +- **WHEN** PostgreSQL, Valkey, S3, брокер и docker недоступны, и выполнен `make service_test` +- **THEN** команда завершается с кодом 0 + +#### Scenario: Новый метод без фейка + +- **WHEN** в абстрактный repo добавлен метод, а у фейка или реализации на SQL его нет или сигнатура другая +- **THEN** `make service_test` падает и называет класс и метод + +#### Scenario: Условие фейка разошлось с SQL + +- **WHEN** условие метода в фейке или выражение на SQL отличается от проверки набора +- **THEN** падает цель той реализации, что разошлась: `make service_test` или `make service_test_db`, и сообщение называет метод + +#### Scenario: Временная база удалена + +- **WHEN** `make service_test_db` завершился, в том числе с падением теста +- **THEN** временной базы нет, а число строк рабочей базы не изменилось + +#### Scenario: Быстрых тестов нет в образе + +- **WHEN** в собранном образе просматривается рабочий каталог приложения +- **THEN** каталога быстрых тестов и их фейков в нём нет + +#### Scenario: Отдельно от набора по HTTP + +- **WHEN** выполнен `make student_test` +- **THEN** быстрые тесты не собраны и не выполнены + +### Requirement: Цена шага в отчёте + +`REPORT.md` SHALL называть цену соединения на шаг: сколько выражений PostgreSQL видит на запрос до и после, CPU API и PostgreSQL на запрос и задержку до и +после по меткам стенда `bench/`, снятым на закоммиченном коде подряд, с уровнем шума. Там же SHALL быть сказано, какая мера её снижает и что осталось. + +#### Scenario: Цена в отчёте + +- **WHEN** проверяющий открывает раздел об этом изменении в `REPORT.md` +- **THEN** в нём есть таблица «до и после», команды, commit и пути к меткам в `evidence/` diff --git a/openspec/changes/unit-of-work/tasks.md b/openspec/changes/unit-of-work/tasks.md new file mode 100644 index 00000000..72428f55 --- /dev/null +++ b/openspec/changes/unit-of-work/tasks.md @@ -0,0 +1,209 @@ +# Tasks + +Как строить — `design.md` (дальше «решение N»), что должно получиться — дельты в `specs/`. Перед первым файлом слоя прочитать его правило: `service-layer.md`, `repo-layer.md`, +`api-layer.md`, `api-contract.md`, `infra.md`, `worker.md`, `auth.md`, `logging.md`, `settings.md`, `run-modes.md`, `docker.md`, `balancer.md`, `student-tests.md`, `bench.md`. + +**Граница коммита.** Группы 1–12 — код, тесты и документы: проверяются на рабочем дереве, агент apply не коммитит и в `evidence/` не пишет. Группа 13 — снятие evidence и чисел `REPORT.md`: +её запускает основная сессия после коммита групп 1–12, на закоммиченном коде (`bench.md`, «Измеренное состояние — commit»). + +**Не меняются:** `student-tests/`, `tests/`, `contracts/`, `migrations/`, `bench/`, `docker-compose.yml`, схема, настройки, `Profile.rollout_from`. Если проверка упала, чинится код: они доказывают, что поведение то же. Проверка `git diff --stat` +по этим путям — задача 11.8. + +**Шага оператора нет.** Новых секретов и переменных нет. + +**Ожидаемо красное**, остальное разбирается по AGENTS.md: +- приложение не стартует от задачи 2.1 до конца группы 9 (решение 14): там проверки — `make lint` и `make service_test`; +- запрет импортов в `test_architecture.py` — до конца группы 8, по ещё не перенесённым сервисам: падать он должен только на них; +- `test_exclusion_evidence_exists` — по файлам `evidence/cache/hits.md`, `evidence/auth/passwords-and-tokens.md`, `evidence/idempotency/replay-after-restart.md`, которые снимаются на последнем шаге всего прогона лабы. Это не регрессия, но падать он должен только по `missing_evidence`. + +Решения по ходу работы — design, «Уточнения apply»; вопросы и решения без пользователя — `QUESTIONS.md`, `## unit-of-work`; дефект, найденный попутно, — `KNOWN_ISSUES.md`. + +## 1. Абстракции + +- [ ] 1.1 Порты repo по решениям 1 и 9: `src/core/ports/{user,session,chat,message,idempotency,attachment,attachment_job,attachment_variant,attachment_job_replay}.py` — `AbstractRepository(abc.ABC)`. Каждая функция `src/core/repos/.py` + (кроме `chat_cache.py` и `attachment_object.py`) — абстрактный метод с теми же именем и keyword-only параметрами без `db_session`. Докстринг — контракт: что значат `None` и `False`, какие условия у перехода. Импорты — только DTO, enum, `src.utils`. + + Проверка: `make lint`; `uv run python -c "import src.core.ports.attachment_job"`; `grep -rn sqlalchemy src/core/ports` пусто. +- [ ] 1.2 `src/core/ports/uow.py`, `AbstractUnitOfWork` по решению 2: атрибуты `users`, `sessions`, `chats`, `messages`, `idempotency`, `attachments`, `jobs`, `variants`, `job_replays`; `__aenter__`, `__aexit__`, `commit`, `rollback`; вложенный вход — ошибка; repo доступны только внутри блока и до `commit`; вторая фиксация — ошибка; + счётчик `blocks_opened`; реальные шаги — абстрактные `_open` и `_close`. + + Проверка: `make lint`; поведение — задача 4.4. + +## 2. Repo-классы + +- [ ] 2.1 `src/core/repos/{user,session,chat,message,idempotency}.py` — `SqlAlchemyRepository(AbstractRepository)` с `self._session`, по решению 9. Выражения и помощники без изменений, `MESSAGE_COLUMNS`, `USER_COLUMNS`, `to_message_dto` — модульные. + + Проверка: `make lint`; в `git diff` этих файлов у выражений меняются только отступ и `db_session` → `self._session`. +- [ ] 2.2 `src/core/repos/{attachment,attachment_job,attachment_variant,attachment_job_replay}.py` — так же. `literal_execute`, `FOR UPDATE`, `FOR NO KEY UPDATE`, `SKIP LOCKED`, `greatest`, параметры-массивы — как были. `chat_cache.py`, `attachment_object.py` не трогать (решение 8). + + Проверка: `make lint`; проверка `git diff`, как в 2.1; `grep -n "literal_execute\|with_for_update" src/core/repos/*.py` — то же число строк, что на `9efab79`. + +## 3. Единица работы на SQLAlchemy + +- [ ] 3.1 `src/infra/db/scope.py`: `session_scope` по решению 4 (откат под сроком при выходе без фиксации и при исключении, не связанном с отказом БД; ветка `CancelledError`; прежняя запись и `ServiceUnavailable`); `deadline_scope(*, timeout_seconds)` по решению 6 — та же запись и тот же отказ; докстринг. + + Проверка: `make lint`; поведение — группа 10. +- [ ] 3.2 `src/infra/db/uow.py`: `SqlAlchemyUnitOfWork(session_factory, *, timeout_seconds)` поверх `session_scope`; repo создаются на блок. `src/infra/db/__init__.py` его не импортирует: логгер не должен настраиваться в alembic. + + Проверка: `make lint`; `uv run python -c "import src.infra.db; import sys; assert 'src.infra.logger' not in sys.modules"`; поведение — группа 10. +- [ ] 3.3 `src/infra/db/engine.py`: дешёвая проверка соединения по решению 7, с комментарием, зачем. + + Проверка: `make lint`; поведение — задачи 10.2, 11.1. +- [ ] 3.4 `src/config/settings.py`: комментарий `request_timeout_seconds` по решению 6 (срок блока; на JSON-ручке ещё и весь запрос). Значение и валидатор те же. + + Проверка: `make lint`; в `git diff src/config/settings.py` — только комментарий. + +## 4. Каркас быстрых тестов и фейки + +- [ ] 4.1 По решению 13: `service-tests/pytest.ini`, `service-tests/unit/conftest.py` (автоматическая фикстура с полями `settings`, от которых зависят ветки сервисов, `anyio_backend`), цель `make service_test` рядом с `student_test`; `pyproject.toml`: `src` ruff и `per-file-ignores`; `.dockerignore`: `service-tests`. + + Проверка: `make service_test` собирает каталог и проходит при других значениях настроек (`WORKER__MAX_ATTEMPTS=9 make service_test`); `make student_test` его не собирает (`--collect-only`, нет ни одного узла `service-tests`); `make lint`. +- [ ] 4.2 `service-tests/fakes/`: `FakeDatabase` (таблицы, снимок, `events`, `held`, `fail_on`), `FakeUnitOfWork` на том же базовом классе (откат возвращает снимок, `fail_commit`), фейки девяти repo по контракту портов, решение 11. + + Проверка: задачи 4.4 и 4.5. +- [ ] 4.3 Там же `FakeCache`, `FakeObjectStorage` (`put`, `head`, `open`, `delete`, `list_page`, `stats`, `namespace`, `fail_on`), `FakeJobPublisher` (подтверждает всё или заданное подмножество, журнал в `events`), `FakeImageRenderer`. `UploadSlots` — настоящий. + + Проверка: задача 4.5. +- [ ] 4.4 `service-tests/unit/test_unit_of_work.py`: сценарии `unit-of-work` «Выход без фиксации», «Исключение внутри блока», «Фиксация», «Работа после фиксации», «Вложенный блок», «Repo вне блока» на фейке. + + Проверка: `make service_test`. +- [ ] 4.5 `service-tests/unit/test_architecture.py`: разбор импортов `src/core/services/*.py` и `src/core/ports/*.py` (запрещены `sqlalchemy`, `src.infra.db`, реализации repo на SQL, глобалы `instance`, `upload_slots` вне `TYPE_CHECKING`); набор методов и сигнатуры порт — реализация — фейк, фейки клиентов — настоящие клиенты (сценарии «Запрещённый импорт», «Новый метод без фейка», сообщение называет файл, класс и метод). + + Проверка: `make service_test`; красный прогон — задача 11.7. + +## 5. Сервисы JSON-ручек + +- [ ] 5.1 `UserService(uow)`, `SessionService(uow)` по решениям 5 и 10: KDF вне блока, вход — два блока. `service-tests/unit/test_user_service.py`, `test_session_service.py`: успех, занятый username, неверный пароль и неизвестный пользователь (тот же отказ, блока записи нет), нет токена (блока нет), истёкшая сессия, отзыв и повторный отзыв, порядок событий входа. + + Проверка: `make service_test`; `make lint`. +- [ ] 5.2 `ChatService(uow, cache)` и `require_member` по решению 5: кэш после commit, отсутствующий чат не кэшируется. `test_chat_service.py`: дубликаты и вызывающий вне списка, неизвестные пользователи, откат при сбое участников (ни чата, ни кэша), сбой commit — в кэше пусто, попадание без обращения к repo, промах с записью, посторонний, страницы и чужой курсор. + + Проверка: `make service_test`; `make lint`. +- [ ] 5.3 `MessageService(uow, cache)`: одна транзакция на блок, порядок прежний (членство → вложения → хэш → ключ). `test_message_service.py`: новое, повтор с тем же телом (тот же DTO, commit, новой строки нет), другое тело — конфликт после commit, `failed` при новом ключе — откат, и ключ свободен, `failed` при занятом ключе — повтор, неизвестное и `pending` вложение до ключа, порядок вложений, сбой записи сообщения — ключ свободен, страницы, `message_request_hash`. + + Проверка: `make service_test`; `make lint`. + +## 6. Сервис вложений + +- [ ] 6.1 `AttachmentService(uow, cache, storage, slots)`: те же шаги и порядок, `_mark_queued` с флагом перед `commit()` без изменения логики; убрать `DbScope`. `test_attachment_service.py`: порядок проверок (404, 415, 413, 429, тело), порядок записи и события (`pending` commit → `put` вне блока → `queued` и задание одним блоком), три ветки компенсации (сценарий «Компенсация различает исход фиксации» и `mark_queued` → `None`), сбой PUT без компенсации, метаданные (`pending` и посторонний — 404, варианты только у `ready`), `open_content` (не готово — 409, нет варианта — 404, `lost_at` — 404 без S3, нет объекта и другой размер — 500). + + Проверка: `make service_test` с `tests/fixtures/sample.png`; `make lint`. + +## 7. Worker, relay, replay + +- [ ] 7.1 `AttachmentProcessingService(uow, storage, renderer, stop)`: вспомогательные методы без параметра `db_session`, блоки те же. `test_attachment_processing.py`: разбор и `DROP`, вся таблица claim (нет задания, чужое вложение, `succeeded`, `failed`, раньше срока, живая аренда, истёкшая, бюджет), взятие, успех, постоянная и временная ошибка, `superseded` на `ready`, `failed` и возврате, отказ БД — `REQUEUE` и пауза, `put` не внутри блока. + + Проверка: `make service_test`; `make lint`. +- [ ] 7.2 `AttachmentRelayService(uow, publisher)`, `AttachmentReplayService(uow)`. `test_attachment_relay.py`: сценарий «Порядок публикации», подтверждённое подмножество, предел опубликованных, истёкшие аренды одним блоком, потерянные (ноль и не ноль готовых, брокер только при кандидатах), сигнал между шагами. `test_attachment_replay.py`: таблица отказов, `--apply` с аудитом одним блоком, показ без изменений, выбор по коду, сигнал. + + Проверка: `make service_test`; `make lint`. + +## 8. Уборщик и сверка + +- [ ] 8.1 `AttachmentCleanupService(uow, storage)`. `test_attachment_cleanup.py`: сценарий «Порядок уборки», сигнал между шагами, строка занята (`held`), keyset больше одной пачки, отказ БД и S3 в `interrupted_by`, очистка `ready` и `failed` с вариантами, чужой ключ, строка прежней версии. + + Проверка: `make service_test`; `make lint`. +- [ ] 8.2 `AttachmentReconcileService(uow, storage)`: убрать обёртку `db_scope` и `_db_sessions`, счёт — `uow.blocks_opened` (решение 10); внутренний сервис уборки на том же экземпляре. `test_attachment_reconcile.py`: все классы на `batch` и `head` с одинаковыми находками, dry-run без изменений, порядок действий `apply`, предел изменений и `unchecked`, чужой ключ, перепроверка отбрасывает кандидата, свежий объект, `--deep`, сигнал перед вызовом, прерывание отказом, сценарий «Счёт блоков сверки». + + Проверка: `make service_test` — весь каталог быстрее 30 с без хранилищ (сценарий «Без хранилищ»: остановить ничего не нужно, проверка — `make service_test` с `DATABASE__PORT=1 CACHE__PORT=1 S3__PORT=1`); `make lint`. + +## 9. Сборка + +- [ ] 9.1 `src/api/dependencies.py`: `get_uow`, `request_deadline`; сервисы на `UowDep`; убрать `db_session_scope`, `get_db_session`, `DbSessionDep`, `get_current_user_brief`, `CurrentUserBrief`. `src/api/routers/v1/__init__.py`: общий срок на роутерах пользователей, сессий, чатов и сообщений (решение 6). `routers/v1/attachment.py`: `CurrentUser` и докстринг модуля. + + Проверка: `make lint`; `make run_docker`, `make test`; `/openapi.json` не изменился, `uv run pytest student-tests/test_contract.py` зелёный. +- [ ] 9.2 `src/worker/main.py`: сервис на доставку (решение 3), `_pump` и `_handle` получают фабрику; `src/relay/main.py`, `src/cleaner/main.py`: `SqlAlchemyUnitOfWork` на сервис; замыкания `db_scope` убрать. Импорты `AsyncSession` и `session_scope` вне `src/infra/db/` не остаются. + + Проверка: `make lint`; `grep -rnE 'AsyncSession|session_scope|db_scope|DbScope|get_db_session' src --include='*.py'` находит только `src/infra/db/` и `src/core/repos/`; `make run_docker`, `driver.py --port defense-scenario` — `ready`, оригинал и thumbnail. + +## 10. Проверки на временной базе + +- [ ] 10.1 Цель `make service_test_db: start_db`, `service-tests/db/conftest.py` по решению 13: шаблон `^test_uow_[a-z0-9_]+$`, иначе код 2 до действий; база и миграции в начале, удаление при любом исходе; настройки «тесного» API окружением до импорта `src`; TCP-прокси до PostgreSQL, который умеет перестать отвечать. + + Проверка: `make service_test_db` дважды подряд; `\l` без `test_uow_*` после обоих и после теста, упавшего нарочно (сценарий «Временная база удалена»); `pg_stat_user_tables` рабочей базы не изменился. +- [ ] 10.2 `service-tests/db/test_uow.py`, настоящая единица работы: «Выход без фиксации», «Исключение внутри блока», «Фиксация», «Вложенный блок» без второго соединения; `blocks_opened`; соединение занято только внутри блока; «Запрос дольше срока» (`pg_sleep`), «PostgreSQL заморожен при откате», «Отмена при открытой транзакции» (через прокси), «Нарушение ограничения»; оборванное соединение пула (`pg_terminate_backend`): следующий блок получает новое без ошибки; статус константой в тексте выражений `lock_due_jobs`, `count_published`, `lock_stale_pending`, `get_staging_candidates`. + + Проверка: `make service_test_db`. +- [ ] 10.3 `service-tests/repo_contract.py`: один набор проверок по решению 11, данные — только через методы портов и явное время; `unit/test_repo_contract.py` гоняет его на фейке, `db/test_repo_contract_sql.py` — на SQL. Для каждого метода, по результату которого ветвятся сервисы: `mark_queued`, `mark_processing`, `return_to_queued` обоих repo, `return_group_to_queued`, `replay_failed`, `commit_ready`, `commit_failed`, `get_stale_pending`, `lock_stale_pending`, `mark_removing`, `delete_attachment`, `get_staging_candidates`, `lock_staging_candidate`, `clear_staging_key`, `get_attachments_for_objects`, `get_ready_page`, `find_attachment_reference`, `mark_lost`, `clear_lost`; `start_attempt`, `finish_job`, `lock_due_jobs`, `count_published`, `mark_published`, `recover_expired_leases`, `has_published_before`, `reset_published_before`, `replay_job`, `list_failed`; `claim_key`, `get_key_result`; `insert_user`, `get_user_credentials`, `get_existing_user_ids`; `get_current_session`, `delete_session`; `get_chat`, `get_user_chats_page`; `get_chat_messages_page`, порядок `attachment_ids`; `insert_variant`, `get_variants`, `get_variant`. Если фейк и SQL разошлись, чинится фейк: выражения на SQL этим изменением не меняются. + + Проверка: `make service_test` — набор на фейке, `make service_test_db` — тот же набор на SQL, число проверок равно. +- [ ] 10.4 `service-tests/db/test_request_flow.py`: приложение в процессе (`httpx.ASGITransport`, S3 и кэш — фейки): «Ответ без занятого соединения» (две выдачи, в начале ответа занятых 0), «Пул из одного соединения», «Вход не держит соединение на хэш», «Блок без обращения к PostgreSQL», «Два медленных шага» (`LOCK TABLE`), «Очередь хэшей», «Вложение дольше срока блока»; порядок кодов при упавшем PostgreSQL на входе. + + Проверка: `make service_test_db`. + +## 11. Проверка на стенде, рабочее дерево + +- [ ] 11.1 `make run_docker`, `make replicas`: `make test`, `make student_test` через LB, `make instances`. + + Проверка: зелёные, кроме `test_exclusion_evidence_exists`. +- [ ] 11.2 `make test_isolated`. + + Проверка: код 0; база, контейнеры и префикс убраны. +- [ ] 11.3 Полный `make failure_checks` при остановленном рабочем стенде. Отдельно смотреть тесный API: `test_pool_exhausted`, `test_connection_limit_reached`, `test_pool_keeps_connections`, `test_expired_token`, `test_key_free_after_ttl`. + + Проверка: код 0, все тесты проходят без правок; упавший разобрать по AGENTS.md: дефект приложения, тест или стенд. +- [ ] 11.4 `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` в режимах `stop` и `kill`; `driver.py --port hang-key`. + + Проверка: код 0; после `make replicas` реплики `UP`. +- [ ] 11.5 `driver.py --port defense-faults`, `worker-process`, `relay-process`, `upload-consistency`, `reconcile-cycle`, `pipeline-state`; `driver.py reconcile-signal --pace --apply` на не рабочем проекте; `make s3_check`; `make replay`; `make reconcile`. + + Проверка: коды как в их описаниях (`AGENTS.md`); в журнале нет «Unit of work» и трассировок; `db_sessions` в итоге `reconcile` — положительное число. +- [ ] 11.6 Замена без простоя: `make bench_rollout_quick`; на рабочем стенде `make rolling_update COMMIT=9efab79 MIGRATE=0`, затем `make rolling_update`, `docker compose up -d --no-deps worker relay cleaner`, `make test`. + + Проверка: `errors` 0, записей столько же, сколько ключей; `Profile.rollout_from` не менялся; стенд после возврата зелёный. +- [ ] 11.7 Тесты ловят нарушение: временные регрессии, каждую проверить красным прогоном и откатить, хэши `src` совпали: автокоммит при выходе из блока; компенсация без флага; отметка публикации отдельным блоком; DELETE уборщика после commit; откат вне срока; без ветки `CancelledError`; без `request_deadline`; условие `updated_at = created_at` убрано из SQL `mark_queued`; импорт SQLAlchemy в сервис; метод порта без фейка; `put` worker внутри блока. + + Проверка: таблица «регрессия → какой тест красный» в design, «Уточнения apply», перенос в `evidence/tests/service-tests.md` — задача 13.2. +- [ ] 11.8 Границы изменения: `git diff --stat` по `student-tests tests contracts migrations bench scripts docker-compose.yml uv.lock lab.json` пуст; образ без тестов: `docker run --rm --entrypoint ls mtusi-messenger:lab5 -A /app` — только `src`, `migrations`, `alembic.ini`, `.venv`; Pillow по-прежнему не в процессе API и worker (`/proc/1/maps`, `driver.py worker-process`). + + Проверка: вывод команд. + +## 12. Документы + +- [ ] 12.1 `.claude/rules/service-layer.md`, `repo-layer.md` (ещё `paths`: `src/core/ports/**`; классы и методы вместо функций), `api-layer.md` (нет `get_db_session` и `CurrentUserBrief`, `request_deadline`), `infra.md` (`scope.py`, `uow.py`, проверка соединения, откат под сроком), `worker.md` (сервис на доставку, блоки вместо `db_session`), `auth.md`, `logging.md`, `balancer.md` (общий срок в цепочке), `docker.md` (образ без `service-tests`, `.dockerignore`), `run-modes.md` (цели), `student-tests.md` (отсылка: быстрые тесты — не здесь); новый `.claude/rules/service-tests.md` (`paths: service-tests/**`: фейк реализует контракт порта, новый метод — порт, SQL, фейк и строка контракта, блокировки только в `make failure_checks`, настройки по умолчанию). + + Проверка: `grep -rnE 'db_scope|get_db_session|db_session_scope|CurrentUserBrief|DbSessionDep' .claude/rules` пусто, кроме ссылок на прежние change; пример из текста правила совпадает с кодом. +- [ ] 12.2 `AGENTS.md`: шапка (текущий change), «Обязательные правила» (новый пункт о единице работы; «Тесты пишем» — ещё быстрые тесты вне `student-tests/`), таблица правил, таблица команд (`make service_test`, `make service_test_db`), карта кода (`core/ports/`, repo-классы, `infra/db/uow.py`, `service-tests/`, строки сервисов с `uow`, `dependencies.py`), «Архитектура в двух словах», «Переход в следующую лабу» (`service-tests/`). + + Проверка: каждая новая цель есть в таблице, каждая новая папка — на карте; `make check`. +- [ ] 12.3 `.claude/skills/run-mtusi-messenger/SKILL.md`, «Direct invocation»: пример на `SqlAlchemyUnitOfWork`. + + Проверка: пример выполняется на `make upgrade`, вывод — `CurrentSessionDTO`. +- [ ] 12.4 `.github/workflows/application.yml`: шаг `make service_test` после `uv sync`. + + Проверка: `uv run python -c "import yaml; yaml.safe_load(open('.github/workflows/application.yml'))"`; `make check`. +- [ ] 12.5 `REPORT.md` (без чисел, их даёт группа 13): раздел об изменении в «Архитектура и решения», схема слоёв и потока отправки сообщения блоком Mermaid с портами и единицей работы (спек `code-knowledge-graph`, «Схема кода в отчёте»: каждая связь есть в коде), «Транзакционные границы», ограничения, Cosmic Python в источниках, использование ИИ. + + Проверка: стрелки сверены с импортами и вызовами. +- [ ] 12.6 `KNOWN_ISSUES.md`: запись о `GET /attachments/{id}`: вход и блок до `2T` = 12 с при `timeout server` 10 с, дефект прежний, не чинится здесь (решение 6, ручки вложений без общего срока). `QUESTIONS.md`, `## unit-of-work`: решения apply. `graphify update .`. + + Проверка: `graphify query "SqlAlchemyUnitOfWork AbstractUnitOfWork"` находит узлы; `make lint`. +- [ ] 12.7 Итог групп 1–12 для основной сессии: `make lint`, `make service_test`, `make service_test_db`, `openspec validate unit-of-work --strict`; `git status` и `git diff --stat` с предложением сообщения коммита. + + Проверка: все зелёные; основная сессия коммитит и запускает группу 13. + +## 13. Evidence на закоммиченном коде (основная сессия) + +В шапке каждого файла — команда, дата, commit (`git rev-parse --short HEAD`), `git.dirty` false; секретов нет (`evidence/README.md`). Перед замерами — проверка хоста (`bench.md`), рабочий стенд `make stop`, посторонние контейнеры названы в паспорте. + +- [ ] 13.1 Стоимость «до» и «после» подряд, в одной сессии хоста: временный `git worktree` commit до кода (`9efab79` или commit артефактов, `src` тот же), там дважды `caffeinate -isu uv run python bench/run.py --profile quick --label unit-of-work-before` и `--label unit-of-work-aa` (профиль `make bench_quick`, ~3 мин, такие метки идут в git); в основном дереве так же `--label unit-of-work-after`; каталоги меток из worktree — в `evidence/bench/`; worktree убрать. `make bench_compare BEFORE=unit-of-work-before AFTER=unit-of-work-after AA=unit-of-work-aa`. + + Проверка: три паспорта `git.dirty` false, `evidence/compare/unit-of-work-before__unit-of-work-after.md`; если worktree не подходит — `make bench_ab` по `bench.md`. +- [ ] 13.2 `make service_test`, `make service_test_db`, таблица регрессий 11.7 → `evidence/tests/service-tests.md`. + + Проверка: файл с временем прогона и числом тестов. +- [ ] 13.3 `make test_isolated` → `evidence/tests/test-isolated.md`; `make run_docker`, `make replicas`, `make student_test` → `evidence/tests/student-test-lb.md`; `make failure_checks` при остановленном рабочем стенде → `evidence/tests/failure-checks.md`. + + Проверка: итоги и commit в шапке, тесты не менялись (`git log -- student-tests` без новых коммитов от `9efab79`). +- [ ] 13.4 `make test-persistence ACTION_SCRIPT=scripts/restart.sh` → `evidence/replicas/test-persistence.md`; `make test-failover` `stop` и `kill` с `STOP_ONE_LOG` → `evidence/failover/test-failover.md`. + + Проверка: `StartedAt` до и после, остановленный контейнер совпадает с `TARGET_INSTANCE_ID`. +- [ ] 13.5 `driver.py --port defense-faults` → `evidence/attachments/defense-faults.md`; `make s3_check` → `evidence/s3/privacy.md`; `driver.py worker-process`, `relay-process` → `evidence/worker/process.md`, `evidence/relay/process.md`. + + Проверка: коды 0, в выводе нет секретов. +- [ ] 13.6 `make bench_rollout ROLLOUT_LABEL=unit-of-work` (замена с `Profile.rollout_from`) и `bench/run.py --profile rollout --from --label unit-of-work-previous` (та же нагрузка, та же схема: CPU на запрос старых и новых реплик в одном прогоне) → `evidence/rollout/<метка>/`. + + Проверка: ошибок 0, записей столько же, сколько ключей, `git.dirty` false, `from_commit` в паспорте. +- [ ] 13.7 `REPORT.md`: таблица решения 7 и цена шага из меток 13.1 и 13.6 (сценарий «Цена в отчёте»), строки доказательств уровня 4 с новым commit, `bench/`-числа переносить из `summary.md` и `evidence/compare/`, а не считать вручную; новые файлы и метки `evidence/` — на карте `AGENTS.md`. Основная сессия коммитит evidence и отчёт. + + Проверка: каждое число отчёта есть в названном файле; `openspec validate unit-of-work --strict`.