diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 5c573e48..bf210731 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -60,7 +60,10 @@ paths: `invalidate()`, `warning` «Database is unavailable» (модуль `database`) и `ServiceUnavailable`; отмена задачи тоже сбрасывает соединение (`close()` послал бы ROLLBACK); и `deadline_scope(*, timeout_seconds)` — общий срок JSON-запроса - без сессии (`api-layer.md`). `uow.py` — `SqlAlchemyUnitOfWork(session_factory, + без сессии (`api-layer.md`). Внутри общего срока таймер блока не взводится + (`_deadline_task`, только в той же задаче): оба истекали бы почти разом, и вторая + отмена прерывала бы закрытие соединения в пуле. Срок отката на JSON-ручке — общий + срок, вне их — срок блока. `uow.py` — `SqlAlchemyUnitOfWork(session_factory, *, timeout_seconds)` поверх `session_scope`, repo создаются на блок, соединение выдаётся лениво. Импортируют `uow.py` только точки входа процессов; `db/__init__.py` не импортирует ни его, ни `scope.py` (логгер не настраивается @@ -151,7 +154,11 @@ paths: запрос через новое соединение и ждёт сервер без срока, и замёрзший Postgres держит запрос до разморозки. Срок блока ставит `asyncio.timeout` в `session_scope`, а мягкое закрытие соединения - ограничивает `BoundedCloseConnection` (`connection_class` asyncpg). + ограничивает `BoundedCloseConnection` (`connection_class` asyncpg). Он же обрывает + транспорт после закрытия: `abort()` asyncpg на прерванном `close()` выходит сразу и + сокет не трогает, а сессия без транзакции (проверка `;`) жила бы сверх пула без + срока. Опирается на внутренний `_transport`, смену ловит + `test_no_sessions_over_pool_after_freeze`. - Engine — с `hide_parameters=True`. `str()` у `DBAPIError` включает `[SQL: ...]` и `[parameters: ...]`, и эта строка уходит в журнал: в `warning` из `session_scope` и в traceback ошибки 500. Без флага там diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index a0b6e93b..271d3f1c 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -75,7 +75,7 @@ paths: вставленного сообщения: внешний ключ на `messages` отложен до commit. Так повтор не пишет и не откатывает сообщение (design change `instance-id-idempotency`, решение 2); - - захват — `idempotency_repo.claim_key` по `(user_id, chat_id, key)` + - захват — `self.uow.idempotency.claim_key` по `(user_id, chat_id, key)` с порогом `expired_before = now - [idempotency] ttl_seconds` (часы приложения, как у сессий). Захватили (новый или просроченный ключ) — вставка сообщения и один `commit()`. Не захватили — ключ diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 7e39552f..bde2c6e0 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -451,7 +451,7 @@ EOF ``` `ChatService` и `MessageService` создаются с кэшем вторым параметром: -`ChatService(db_session=db_session, cache=cache)`, где `cache` — из +`ChatService(uow=uow, cache=cache)`, где `cache` — из `src.infra.cache.instance` (`await cache.aclose()` в конце, нужен `make start_cache`). Все методы keyword-only, commit делает сам сервис. Ошибки — доменные исключения из `src.core.exceptions` (базовый `DomainError`), не diff --git a/AGENTS.md b/AGENTS.md index b5037881..92b5f2b8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -563,7 +563,7 @@ src/ upload_slots.py # UploadSlots (asyncio.Semaphore по порядку прихода, счётчик ожидающих, срок ожидания; slot() — UploadsBusy или ожидание в мс, место в finally) и глобал upload_slots из [uploads]; импортирует только dependencies.py db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping; _ping_once — проверка соединения при выдаче одним обменом db/session.py # глобалы engine и session_factory процесса API - db/scope.py # session_scope(factory, timeout_seconds): сессия на блок, срок вместе с откатом, отмена и отказ БД → invalidate, warning, ServiceUnavailable; deadline_scope — общий срок JSON-запроса без сессии + db/scope.py # session_scope(factory, timeout_seconds): сессия на блок, срок вместе с откатом, отмена и отказ БД → invalidate, warning, ServiceUnavailable; deadline_scope — общий срок JSON-запроса без сессии, внутри него таймер блока той же задачи не взводится db/uow.py # SqlAlchemyUnitOfWork(factory, timeout_seconds) поверх session_scope, repo на блок; импортируют только точки входа db/errors.py # is_db_unavailable: какие ошибки драйвера — 503 db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit; attachment.py — Attachment (частичный индекс pending по (created_at, id), lost_at — пометка потерянного оригинала) и MessageAttachment (порядок position, FK без каскада) @@ -603,7 +603,7 @@ service-tests/ # быстрые тесты сервисов (вн builders.py # DTO для тестов: явное время, PASSWORD_HASH по виду CHECK repo_contract.py # один набор условий repo: на фейке и на настоящем SQL fakes/ # FakeDatabase (таблицы, снимок, events, held, fail_on), FakeUnitOfWork на базовом классе порта, фейки девяти repo, FakeCache, FakeObjectStorage, FakeJobPublisher, FakeImageRenderer - unit/ # make service_test: test_unit_of_work, test_architecture, test_repo_contract, test_ на каждый сервис; conftest подставляет поля settings + unit/ # make service_test: test_unit_of_work, test_architecture, test_repo_contract, test_ на каждый сервис, test_worker_deliveries (одновременные доставки); conftest подставляет поля settings db/ # make service_test_db: conftest (временная база, TcpProxy, «тесный» API окружением до импорта src), test_uow, test_repo_contract_sql, test_request_flow bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling / bench_uploads (с S3) run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json; профиль uploads (S3 и bootstrap на стенде, на прогон — новый volume S3 и реплика с окружением варианта через .work/variant.compose.yml, образ «до» — тег bench-from, сэмплер peak), в паспорте всех профилей stand.api_tcp_rmem и docker.kernel; профиль reconcile (S3 с портом метрик через .work/s3-metrics.compose.yml, наполнение \copy и загрузчиком, разовые проходы mtusi-bench-reconcile- с лимитом CPU варианта, «до» — .work/cleaner-before.compose.yml, метрики шлюза и pg_stat_database до и после, блок H4 с k6 background.js, отказ по пределу S4) @@ -659,7 +659,7 @@ evidence/plots/scaling-db/ # make bench_plots по серии db: R* по ли evidence/uploads/ # change upload-memory: <метка>/ — make bench_uploads (meta.json, runs.csv, summary.md, raw/), lb-timeouts.md — driver.py lb-upload-timeouts, rollout-upload.md — медленная загрузка во время make rolling_update evidence/bench/unit-of-work-*/ # change unit-of-work, профиль quick с именной меткой (идёт в git): before и aa на b2fb88f, after на 6ba74b1 evidence/rollout/unit-of-work*/ # change unit-of-work: unit-of-work (замена с Profile.rollout_from), unit-of-work-previous (--from b2fb88f: CPU на запрос старых и новых реплик) -evidence/compare/ # таблицы make bench_compare: <до>__<после>.md; unit-of-work-before__unit-of-work-after.md — цена шага +evidence/compare/ # таблицы make bench_compare: <до>__<после>.md; unit-of-work-before__unit-of-work-after.md и unit-of-work-aa__unit-of-work-after.md — цена шага от двух меток одного кода .github/workflows/application.yml # свой CI job (CONTRIBUTING.md, «CI»; contracts.yml — skeleton): checkout commit прогона (адрес Gitea литералом: github.server_url — внутренний http://gitea:3000, из job не резолвится; по той же причине contracts.yml на этом раннере падает на actions/checkout), сборка и стенд под проектом mtusi-lab5-safronov-ci-, job подключается к сети стенда, готовность — обе реплики через LB, make check / test, аноним в S3 — 403, make validate, make student_test, test-persistence, test-failover stop и kill, уборка при любом исходе; без s3_check, test_isolated и failure_checks (порты хоста). Раннер Gitea (act_runner) запускает job в контейнере на том же Docker, что стенд .github/ci/compose.yml # override стенда в CI: конфиги — configs из переменных окружения вместо bind mount (файлов job нет на хосте раннера), без портов на хосте, образ API с тегом прогона .github/ci/stand-env.sh # «.» в шагах job: содержимое конфигов в CI_* для configs (с переводом строки в конце: без него HAProxy конфиг не принимает), wait_replicas — /health/ready 200 от API_REPLICAS разных реплик через LB за 60 с diff --git a/QUESTIONS.md b/QUESTIONS.md index 9706c373..82e85f5e 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -206,6 +206,7 @@ - **Решения apply** (`design.md`, «Уточнения apply»): `commit` и `rollback` единицы работы — в базовом классе, реальные шаги `_commit` и `_rollback`, иначе правила блока дублировались бы в фейке; `rollback()` заканчивает блок, как и `commit()`; временная база — хуки pytest, а не фикстура, чтобы удаляться и при прерывании; замороженный прокси размораживается сторожем через 8 с, чтобы регрессия падала, а не висела. - **`driver.py reconcile-cycle` на наполненном стенде даёт один ложный FAIL** («exit code after X and Y are removed»): на 11 тыс. объектов проход идёт ~5,8 с, и проба F (grace 30 с) стареет раньше проверки. От кода не зависит, записано в `KNOWN_ISSUES.md`, не чинилось: вне изменения. +- **Правки verify** (`design.md`, уточнения 17–20). `BoundedCloseConnection` обрывает транспорт сам: дешёвая проверка (решение 7) превращала старую утечку сокета после заморозки в сессии PostgreSQL сверх пула без срока, откатывать её не понадобилось. При общем сроке таймера блока нет (`ContextVar` с задачей, `asyncio.timeout(None)`): иначе вторая отмена прерывала закрытие соединения. Заметное следствие: 503 при заморозке теперь приходит за `T` + закрытие, 4 с при сроке 2 с (при 6 с — 8 с < `timeout server` 10 с), а не за `T`. `service_factory` worker вынесен из `run()`, чтобы тест ловил регрессию в самой сборке. ### Вопросы @@ -213,4 +214,4 @@ ### Для пользователя -Основная сессия приняла расхождения с первоначальной постановкой, потому что сама её сформулировала, а решения пользователя они не меняют: общий срок JSON-запроса (решение 6) и дешёвую проверку соединения при выдаче (решение 7). Условие для второго: `make service_test_db` проверяет обрыв соединения с подменённой проверкой, чтобы смена внутренних имён SQLAlchemy падала тестом. Цена паттерна на этом стенде, по пробе: потолок реплики на истории и отправке ниже на 1–22 % (шум до 10 %), число соединений то же. Замер на коммите — группа 13 и `REPORT.md`. +Основная сессия приняла расхождения с первоначальной постановкой, потому что сама её сформулировала, а решения пользователя они не меняют: общий срок JSON-запроса (решение 6) и дешёвую проверку соединения при выдаче (решение 7). Условие для второго: `make service_test_db` проверяет обрыв соединения с подменённой проверкой, чтобы смена внутренних имён SQLAlchemy падала тестом. Цена паттерна на этом стенде, замер на коммите (`evidence/compare/unit-of-work-aa__unit-of-work-after.md` и `unit-of-work-before__unit-of-work-after.md`): потолок реплики на истории и отправке ниже, медианы −14,1 и −12,6 % от метки того же кода, снятой прямо перед «после» (ниже 18 ячеек из 18), −6,6 и −4,3 % от снятой позже (16 из 18). Один повтор на ячейку, две метки одного кода расходятся до 14–17 %: знак устойчив, точной величины нет. За оценку design (−1…−22 %) цена по ближней метке не вышла, число соединений то же. Рост CPU при 200/с (API +10,8 %) того же порядка, что расхождение двух прогонов одного кода (9,2 %). Вывод — `REPORT.md`. diff --git a/REPORT.md b/REPORT.md index 8fbf2f56..a82659ea 100644 --- a/REPORT.md +++ b/REPORT.md @@ -93,7 +93,7 @@ make replay → relay replay: реестр failed и возврат работы - `prefetch` отдельно от `concurrency`; очистка staging уборщиком, класс сверки `orphan_staging`; - схема только расширена: ревизии `c7e2f1a04b56` и `d3f9a6b2c1e7`. -**Единица работы** (design change `unit-of-work`, Cosmic Python, главы 2 и 6). Сервисы всех процессов зависят только от абстракций `src/core/ports/`: `AbstractUnitOfWork` и абстрактных repo; реализации на SQLAlchemy выбирают точки входа (`src/api/dependencies.py`, `src/worker/main.py`, `src/relay/main.py`, `src/cleaner/main.py`). Граница транзакции одна и видна в сервисе: `async with self.uow:` — один блок, одна транзакция; явный `await self.uow.commit()`, выход без него — откат. Вложенный блок и repo вне блока или после фиксации — ошибка, в том числе на фейке. Доменной модели, агрегатов и message bus нет: логика и так в сервисах, а границы транзакций заданы контрактом. Кэш Valkey и S3 в единицу работы не входят: фиксация и откат на них не действуют. Соединение занято на шаг: JSON-ручка получает его на вход и на операцию отдельно, а на хэш пароля, между шагами и на передачу ответа оно в пуле. `[database] request_timeout_seconds` — срок блока вместе с откатом при выходе; на JSON-ручках та же настройка ещё и общий срок запроса (`request_deadline`), иначе два шага дали бы до 12 с при `timeout server` 10 с, а очередь хэшей шла бы без срока. Поведение API, контракт, схема и настройки те же. +**Единица работы** (design change `unit-of-work`, Cosmic Python, главы 2 и 6). С PostgreSQL сервисы всех процессов работают только через абстракции `src/core/ports/`: `AbstractUnitOfWork` и абстрактные repo; реализации на SQLAlchemy выбирают точки входа (`src/api/dependencies.py`, `src/worker/main.py`, `src/relay/main.py`, `src/cleaner/main.py`). Остальные зависимости конкретные и названы: `Cache`, `ObjectStorage`, `JobPublisher`, `ImageRenderer` сервис импортирует как типы и получает конструктором (сигнатуры фейков сверяет тест, `design.md`, решение 8), а `src.infra.password` и логгер вызывает прямо из модуля (уточнение 20). Граница транзакции одна и видна в сервисе: `async with self.uow:` — один блок, одна транзакция; явный `await self.uow.commit()`, выход без него — откат. Вложенный блок и repo вне блока или после фиксации — ошибка, в том числе на фейке. Доменной модели, агрегатов и message bus нет: логика и так в сервисах, а границы транзакций заданы контрактом. Кэш Valkey и S3 в единицу работы не входят: фиксация и откат на них не действуют. Соединение занято на шаг: JSON-ручка получает его на вход и на операцию отдельно, а на хэш пароля, между шагами и на передачу ответа оно в пуле. `[database] request_timeout_seconds` — срок блока вместе с откатом при выходе; на JSON-ручках та же настройка ещё и общий срок запроса (`request_deadline`), иначе два шага дали бы до 12 с при `timeout server` 10 с, а очередь хэшей шла бы без срока. Поведение API, контракт, схема и настройки те же. Схема слоёв и поток отправки сообщения (каждая связь сверена с импортами и вызовами кода; поиском по связям помогал граф кода `graphify`, он только подсказка: схема написана руками): @@ -116,6 +116,7 @@ flowchart TD scope["src/infra/db/scope.py: session_scope, deadline_scope"] sqlrepos["src/core/repos/*: SqlAlchemy*Repository"] clients["src/infra: Cache, ObjectStorage, JobPublisher, ImageRenderer"] + password["src/infra/password.py"] end pg[("PostgreSQL")] routers --> deps @@ -126,6 +127,8 @@ flowchart TD deps --> scope services --> ports services --> clientrepos + services -- "тип клиента, вызовы издателя и процесса обработки" --> clients + services -- "хэш пароля" --> password clientrepos --> clients uow -. реализует .-> ports sqlrepos -. реализует .-> ports @@ -169,14 +172,26 @@ sequenceDiagram | `GET …/messages` | 7 | 12 | 8 | | `POST …/messages` | 8 | 13 | 9 | -Потолок и CPU реплики до и после, закрытая модель, 1 реплика 1 CPU, один повтор на ячейку: `caffeinate -isu uv run python bench/run.py --profile quick --label unit-of-work-before` и `unit-of-work-aa` на `b2fb88f` (`src` как на `9efab79`, временный `git worktree`), `--label unit-of-work-after` на `6ba74b1`; `make bench_compare BEFORE=unit-of-work-before AFTER=unit-of-work-after AA=unit-of-work-aa`. Метки — `evidence/bench/unit-of-work-*/`, сравнение — `evidence/compare/unit-of-work-before__unit-of-work-after.md`. У всех трёх `git.dirty` false, `host_warnings` пусты, `swapouts_delta` 0; посторонние контейнеры на хосте — `domains-api-1`, `domains-bot-1`, `domains-postgres-1` (названы в паспортах). Первая съёмка `unit-of-work-before` дала предупреждение о выгрузке 27708 страниц в swap и переснята (`bench.md`): порядок меток — aa, after, rollout, затем before, в той же сессии хоста; отброшенная метка в git не идёт. +Потолок и CPU реплики до и после, закрытая модель, 1 реплика 1 CPU, один повтор на ячейку: `caffeinate -isu uv run python bench/run.py --profile quick --label unit-of-work-before` и `unit-of-work-aa` на `b2fb88f` (`src` как на `9efab79`, временный `git worktree`), `--label unit-of-work-after` на `6ba74b1`; `make bench_compare BEFORE=unit-of-work-before AFTER=unit-of-work-after AA=unit-of-work-aa` и `make bench_compare BEFORE=unit-of-work-aa AFTER=unit-of-work-after AA=unit-of-work-before`. Метки — `evidence/bench/unit-of-work-*/`, сравнения — `evidence/compare/unit-of-work-before__unit-of-work-after.md` и `evidence/compare/unit-of-work-aa__unit-of-work-after.md`. Метки сняты до правок verify (`BoundedCloseConnection`, таймер блока при общем сроке): на пути без отказа те правки убирают один таймер блока и не добавляют обменов; метки не переснимались. У всех трёх `git.dirty` false, `host_warnings` пусты, `swapouts_delta` 0; посторонние контейнеры на хосте — `domains-api-1`, `domains-bot-1`, `domains-postgres-1` (названы в паспортах). Первая съёмка `unit-of-work-before` дала предупреждение о выгрузке 27708 страниц в swap и переснята (`bench.md`): порядок меток — aa, after, rollout, затем before, в той же сессии хоста; отброшенная метка в git не идёт. -| Сценарий | Шум A/A, наибольшее Δ RPS | Δ RPS по 9 ячейкам: медиана (мин…макс) | Вывод `bench_compare` | p50 при 1 клиенте, мс | -|---|---|---|---|---| -| история | 14,8 % (5k × 1) | −6,6 % (−18,8…−3,2) | эффект — 1k × 1 (−16,2 %) и 1k × 16 (−18,8 %), остальные в пределах шума | 1,86 → 2,22; 1,95 → 2,16; 1,85 → 2,22 | -| отправка | 34,8 % (5k × 16) | −4,3 % (−23,5…+37,5) | в пределах шума, кроме 5k × 16: +37,5 % — выброс ячейки «до» (383 RPS) | 2,05 → 2,40; 2,07 → 2,33; 1,89 → 2,41 | +Порядок съёмки: `aa` 20:19, `after` 20:23, затем rollout, `before` 20:32 UTC. Код `aa` и `before` один, поэтому обе метки — «до», и каждая служит уровнем шума для другой (`bench_compare` считает шум от своего «до»: одна пара меток даёт 14,8 и 17,4 %, 34,8 и 53,4 %). -CPU реплики на запрос, мкс, история: 1646 → 1811, 1520 → 1606, 1434 → 1767 (1k × 1, 4, 16); отправка: 1860 → 2009, 1618 → 1682, 1687 → 1954. Остальные ячейки и p95 — там же в `evidence/compare/`. По сравнению с оценкой `design.md` (потолок −1…−22 %, p50 при 150/с +0,2…0,5 мс): медианы и почти все ячейки внутри, вне её одна ячейка отправки, 10k × 1, −23,5 % при шуме 34,8 %; p50 здесь при 1 клиенте закрытой модели, а не при 150/с, прирост +0,21…+0,52 мс. Шум меток большой (один повтор на ячейку), поэтому точное число — порядок, а не доказанная величина. +| Сценарий | «До» | Шум A/A, наибольшее Δ RPS | Δ RPS по 9 ячейкам: медиана (мин…макс) | Ячеек ниже «до» | Вывод `bench_compare` | p50 при 1 клиенте, мс (1k, 5k, 10k) | +|---|---|---|---|---|---|---| +| история | `aa`, сразу перед `after` | 17,4 % (5k × 1) | −14,1 % (−21,1…−6,3) | 9 из 9 | эффект — 1k × 1 (−21,1 %) и 5k × 1 (−17,5 %), остальные в пределах шума | 1,78 → 2,22; 1,79 → 2,16; 1,83 → 2,22 | +| история | `before`, после rollout | 14,8 % (5k × 1) | −6,6 % (−18,8…−3,2) | 9 из 9 | эффект — 1k × 1 (−16,2 %) и 1k × 16 (−18,8 %), остальные в пределах шума | 1,86 → 2,22; 1,95 → 2,16; 1,85 → 2,22 | +| отправка | `aa`, сразу перед `after` | 53,4 % (5k × 16) | −12,6 % (−18,7…−2,1) | 9 из 9 | всё в пределах шума | 2,01 → 2,40; 2,06 → 2,33; 2,06 → 2,41 | +| отправка | `before`, после rollout | 34,8 % (5k × 16) | −4,3 % (−23,5…+37,5) | 7 из 9 | в пределах шума, кроме 5k × 16: +37,5 % — выброс ячейки «до» | 2,05 → 2,40; 2,07 → 2,33; 1,89 → 2,41 | + +Шум отправки задан одним выбросом: 5k × 16 в `before` — 383 RPS при 588 в `aa`. Без этой ячейки наибольшее расхождение A/A — 14,2 % (10k × 1, 433 и 495 RPS; считано не командой, а по `evidence/bench/unit-of-work-{aa,before}/runs.csv`), и −23,5 % той же ячейки от `before` выходит за него; от `aa` она даёт −12,6 %. + +CPU реплики на запрос от `aa`: выше в 18 ячейках из 18, история +116…+266 мкс, отправка +26…+332 мкс. От `before`: выше в 15 из 18, исключения — 5k × 1 истории (−99), 5k × 1 и 5k × 16 отправки (−3 и −681, та же ячейка-выброс). p95 и все ячейки — в `evidence/compare/`. + +**Что показывают данные.** Соединение на шаг снижает потолок реплики на этой закрытой модели: от метки того же кода, снятой прямо перед `after`, ниже все 18 ячеек, медианы −14,1 % на истории и −12,6 % на отправке, и в тех же 18 ячейках выше CPU реплики на запрос. От метки, снятой позже, медианы −6,6 и −4,3 %, ниже 16 ячеек из 18. + +**Чего данные не показывают.** Точной величины: на ячейку один повтор, две метки одного кода расходятся до 14–17 % даже без выброса, а по правилу `bench_compare` эффектом названы только 2 ячейки истории из 9 в каждом сравнении. Ячейки одной метки сняты подряд и независимыми не считаются: 18 из 18 говорит об устойчивости знака, а не о размере. `before` ниже `aa` в 13 ячейках из 18 при том же коде; если хост за эти 13 минут замедлялся, ближнее сравнение цену завышает, а дальнее занижает, и данные этого не различают. Поэтому цена — снижение потолка примерно от 4–7 до 13–14 % по медианам, а не одно число. + +**С оценкой `design.md`** (потолок −1…−22 %, p50 при 150/с +0,2…0,5 мс) цена не расходится: от `aa` все 18 ячеек внутри (−2,1…−21,1 %), от `before` вне её три ячейки: +0,4 %, +37,5 % и −23,5 %. p50 здесь при 1 клиенте закрытой модели, а не при 150/с, прирост +0,21…+0,52 мс. CPU на успешный запрос при постоянных 200 запросах в секунду (100 записей, 100 чтений; две реплики разных версий в одном прогоне): `bench/run.py --profile rollout --from b2fb88f --label unit-of-work-previous` на `6ba74b1`, `evidence/rollout/unit-of-work-previous/summary.md`, `git.dirty` false, `host_warnings` пусты: @@ -185,6 +200,8 @@ CPU на успешный запрос при постоянных 200 запр | API всего | 3066 | 3398 | | PostgreSQL | 478 | 560 | +Уровень шума — два прогона замены на один и тот же новый код: `evidence/rollout/unit-of-work/summary.md` даёт после замены API 3113 мкс и PostgreSQL 524 мкс, этот прогон — 3398 и 560. Расхождение одного кода (отношение чисел двух `summary.md`, считано вручную): API 285 мкс, 9,2 %; PostgreSQL 36 мкс, 6,9 %. Рост в прогоне выше: API на 332 мкс, 10,8 %, — того же порядка, поэтому отличить его от шума нельзя; PostgreSQL на 82 мкс, 17,2 %, — вдвое больше расхождения, но пара прогонов одна, и этого мало для вывода. Значения «до» двух прогонов для шума не годятся: там разный прежний код. + Замена с `b2fb88f` на `6ba74b1`: 10,2 с, ошибок 0 / 0 / 0, 12001 сообщение = 12001 ключ. Удержание соединения на запрос по пробе `design.md` (Context) ниже на 20–36 %; на commit отдельно не измерялось. **Транзакционные границы.** Ключ эффекта — первичный ключ `attachment_variants (attachment_id, pipeline_version, variant)`, логическая работа — `UNIQUE (attachment_id, pipeline_version)` в `attachment_jobs`. Вызовов S3 и брокера внутри блоков единицы работы нет, кроме двух осознанных исключений с коротким сроком: публикация relay (2 с < срока блока 6 с < простоя транзакции 10 с: блокировка строки и есть признак «публикует другой relay») и DELETE уборщика под блокировкой строки. Намеренные особенности перенесены без изменения порядка: уборка зависшей загрузки — два блока (пометка, затем объект и строка), вход закрывает блок чтения до KDF, занятый ключ идемпотентности снимает блокировку фиксацией до ответа, а компенсация загрузки различает сбой выражения и сбой на самой фиксации флагом перед явным `commit()`: автокоммит при выходе этого бы не дал (`design.md`, решение 10). @@ -502,7 +519,7 @@ H1 (пик ограничен местами) и H4 (нет 503 по сроку - **Прерванное остановкой задание.** Задание, прерванное `docker stop` дольше `graceful_shutdown_seconds` (8 с), считается начатой попыткой и продолжается по аренде: release на пути отмены ненадёжен. Замер на двух дорогих JPEG: 8,15 с, при замороженных PostgreSQL и брокере 9,18 с (`evidence/worker/process.md`). Худший случай остановки 8 + 0,5 + 0,5 + 0,5 = 9,5 с < 10 с. - **Искажения данных скана JPEG.** Структурная проверка и libjpeg байт внутри данных скана ошибкой не считают: такое вложение становится `ready`, а варианты будут с мусором. Проверка не декодирует пиксели при приёме намеренно. - **Цена соединения на шаг.** Двухшаговая JSON-ручка выдаёт соединение дважды: под перегрузкой запрос встаёт в очередь пула дважды, запас на ожидание у него около половины общего срока. Отказ БД при откате успешного чтения — 503, окно в один обмен: откат теперь до ответа. Отмена задачи сбрасывает соединение вместо возврата в пул (design change `unit-of-work`, Risks). -- **Подмена `do_ping`.** Дешёвая проверка соединения опирается на внутренние имена адаптера asyncpg в SQLAlchemy: закреплён `<2.2`, смену ловят тесты `test_ping_*` в `make service_test_db`. +- **Подмена `do_ping`.** Дешёвая проверка соединения опирается на внутренние имена адаптера asyncpg в SQLAlchemy: закреплён `<2.2`, смену ловят тесты `test_ping_*` в `make service_test_db`. Прерванная проверка не оставляет сессий сверх пула только потому, что `BoundedCloseConnection` сам обрывает внутренний `_transport` asyncpg (`design.md`, уточнение 17): смену имени ловит `test_no_sessions_over_pool_after_freeze`. - **Фейки не проверяют блокировки.** Быстрый тест зелёный при сломанном `SKIP LOCKED`: блокировки и конкуренцию доказывает только `make failure_checks` (таблица решения 11 design). - **Метаданные и скачивание вложения без общего срока.** Вход и блок — до 12 с при `timeout server` 10 с: клиент получит 504 от LB вместо 503. Дефект прежний, запись — `KNOWN_ISSUES.md`. - **Цепочка LB.** Брокера в пути нет, поэтому самым долгим снова стал путь компенсации: после тела `проверка ~4 + tx1 6 + PUT 5 + tx2 6 ≈ 21 с`, с DELETE компенсации `+ 5 ≈ 26 с` < `timeout server` 30 с. Наибольшая длительность живой загрузки `U = 17 + 30 + 26 ≈ 73 с` < дренаж замены 90 с: до тела `2 × request_timeout_seconds + wait_timeout_seconds` = 17 с; тело — `[uploads] body_timeout_seconds` 30 с. diff --git a/evidence/compare/unit-of-work-aa__unit-of-work-after.md b/evidence/compare/unit-of-work-aa__unit-of-work-after.md new file mode 100644 index 00000000..2a3c69ea --- /dev/null +++ b/evidence/compare/unit-of-work-aa__unit-of-work-after.md @@ -0,0 +1,71 @@ +# Сравнение меток: `unit-of-work-aa` → `unit-of-work-after` + +- Команда: `make bench_compare BEFORE=unit-of-work-aa AFTER=unit-of-work-after AA=unit-of-work-before` +- «До» и «после» — медиана повторов ячейки, в скобках min–max. Δ RPS — отношение медиан минус единица. +- CPU на запрос — `app_cpu_cores / rps`, медиана по повторам; задержки — медианы по повторам, «до → после». +- Уровень шума — наибольшее по ячейкам сценария изменение медианы RPS между `unit-of-work-before` и `unit-of-work-aa`. Он имеет смысл, только если код приложения в этих метках одинаков; это проверяется по git, команда этого не видит. +- «Эффект» — разбросы повторов не пересекаются и изменение медианы больше уровня шума сценария; иначе «в пределах шума». + +## Метки + +| | `unit-of-work-aa` | `unit-of-work-after` | `unit-of-work-before` | +|---|---|---|---| +| Commit | `b2fb88f` | `6ba74b1` | `b2fb88f` | +| Начало прогона | 2026-10-31T20:19:23+00:00 | 2026-10-31T20:23:07+00:00 | 2026-10-31T20:32:16+00:00 | +| Статус | complete | complete | complete | +| Версии в образе | python 3.12.14, fastapi 0.141.1, starlette 1.7.0, pydantic 2.13.5, uvicorn 0.54.0, sqlalchemy 2.1.1, asyncpg 0.31.0, redis 8.1.0 | python 3.12.14, fastapi 0.141.1, starlette 1.7.0, pydantic 2.13.5, uvicorn 0.54.0, sqlalchemy 2.1.1, asyncpg 0.31.0, redis 8.1.0 | python 3.12.14, fastapi 0.141.1, starlette 1.7.0, pydantic 2.13.5, uvicorn 0.54.0, sqlalchemy 2.1.1, asyncpg 0.31.0, redis 8.1.0 | +| Машина | Apple M3 Pro (6 P + 6 E), ВМ 12 vCPU / 7.7 GiB, Docker 29.9.2 | Apple M3 Pro (6 P + 6 E), ВМ 12 vCPU / 7.7 GiB, Docker 29.9.2 | Apple M3 Pro (6 P + 6 E), ВМ 12 vCPU / 7.7 GiB, Docker 29.9.2 | +| Хост в начале | выгрузок в swap за прогон 0, AC Power | выгрузок в swap за прогон 0, AC Power | выгрузок в swap за прогон 0, AC Power | + +## Замечания + +- `unit-of-work-aa`: посторонние контейнеры: domains-api-1, domains-bot-1, domains-postgres-1 +- `unit-of-work-after`: посторонние контейнеры: domains-api-1, domains-bot-1, domains-postgres-1 +- `unit-of-work-before`: посторонние контейнеры: domains-api-1, domains-bot-1, domains-postgres-1 + +## Уровень шума + +| Сценарий | Наибольшее изменение RPS, `unit-of-work-before` → `unit-of-work-aa` | Ячейка | +|---|---|---| +| read | 17.4% | 5k × 1 | +| write | 53.4% | 5k × 16 | + +## Сценарий `read` + +| Размер | Клиенты | RPS до | RPS после | Δ RPS | Вывод | CPU на запрос, мкс | Δ CPU, мкс | p50, мс | p95, мс | p99, мс | +|---|---|---|---|---|---|---|---|---|---|---| +| 1k | 1 | 529 (529–529) | 417 (417–417) | -21.1% | эффект | 1545 → 1811 | +266 | 1.78 → 2.22 | 2.16 → 2.92 | 2.55 → 3.76 | +| 1k | 4 | 704 (704–704) | 618 (618–618) | -12.2% | в пределах шума | 1428 → 1606 | +179 | 5.33 → 6.08 | 6.67 → 7.63 | 8.57 → 10.92 | +| 1k | 16 | 662 (662–662) | 568 (568–568) | -14.2% | в пределах шума | 1517 → 1767 | +249 | 22.05 → 26.01 | 43.02 → 56.30 | 63.12 → 66.86 | +| 5k | 1 | 523 (523–523) | 431 (431–431) | -17.5% | эффект | 1567 → 1751 | +184 | 1.79 → 2.16 | 2.24 → 2.79 | 2.74 → 3.46 | +| 5k | 4 | 711 (711–711) | 615 (615–615) | -13.5% | в пределах шума | 1412 → 1613 | +201 | 5.32 → 5.97 | 6.48 → 7.60 | 8.05 → 13.78 | +| 5k | 16 | 603 (603–603) | 565 (565–565) | -6.3% | в пределах шума | 1659 → 1775 | +116 | 23.04 → 25.44 | 54.77 → 56.14 | 88.00 → 67.89 | +| 10k | 1 | 490 (490–490) | 417 (417–417) | -14.9% | в пределах шума | 1674 → 1805 | +131 | 1.83 → 2.22 | 2.57 → 2.96 | 3.48 → 4.16 | +| 10k | 4 | 694 (694–694) | 596 (596–596) | -14.1% | в пределах шума | 1446 → 1667 | +221 | 5.34 → 6.01 | 7.04 → 8.84 | 9.82 → 16.64 | +| 10k | 16 | 646 (646–646) | 566 (566–566) | -12.4% | в пределах шума | 1555 → 1771 | +216 | 21.96 → 26.08 | 46.24 → 54.08 | 71.63 → 63.84 | + +Δ RPS по ячейкам: от -21.1% до -6.3%, медиана -14.1%. + +## Сценарий `write` + +| Размер | Клиенты | RPS до | RPS после | Δ RPS | Вывод | CPU на запрос, мкс | Δ CPU, мкс | p50, мс | p95, мс | p99, мс | +|---|---|---|---|---|---|---|---|---|---|---| +| 1k | 1 | 462 (462–462) | 376 (376–376) | -18.7% | в пределах шума | 1677 → 2009 | +332 | 2.01 → 2.40 | 2.70 → 3.63 | 3.51 → 5.18 | +| 1k | 4 | 598 (598–598) | 585 (585–585) | -2.1% | в пределах шума | 1656 → 1682 | +26 | 5.93 → 6.51 | 9.04 → 7.79 | 20.01 → 10.01 | +| 1k | 16 | 610 (610–610) | 518 (518–518) | -15.0% | в пределах шума | 1654 → 1954 | +300 | 24.93 → 28.68 | 40.01 → 42.58 | 69.13 → 77.10 | +| 5k | 1 | 430 (430–430) | 400 (400–400) | -6.9% | в пределах шума | 1781 → 1892 | +111 | 2.06 → 2.33 | 3.27 → 3.11 | 4.83 → 4.17 | +| 5k | 4 | 669 (669–669) | 566 (566–566) | -15.4% | в пределах шума | 1492 → 1735 | +243 | 5.80 → 6.54 | 6.97 → 9.23 | 8.44 → 13.66 | +| 5k | 16 | 588 (588–588) | 527 (527–527) | -10.4% | в пределах шума | 1713 → 1922 | +209 | 25.58 → 27.81 | 40.35 → 44.96 | 73.69 → 74.63 | +| 10k | 1 | 433 (433–433) | 378 (378–378) | -12.6% | в пределах шума | 1764 → 1977 | +213 | 2.06 → 2.41 | 3.15 → 3.45 | 5.44 → 4.91 | +| 10k | 4 | 617 (617–617) | 546 (546–546) | -11.6% | в пределах шума | 1613 → 1837 | +224 | 5.94 → 6.72 | 8.14 → 9.69 | 11.29 → 12.87 | +| 10k | 16 | 609 (609–609) | 515 (515–515) | -15.5% | в пределах шума | 1655 → 1962 | +307 | 25.02 → 29.18 | 37.35 → 44.99 | 68.04 → 66.27 | + +Δ RPS по ячейкам: от -18.7% до -2.1%, медиана -12.6%. + +## Память + +| Размер | Байт RSS на сообщение до | после | RSS после наполнения до, МиБ | после | Байт в БД на сообщение до | после | +|---|---|---|---|---|---|---| +| 1k | 928 | 1430 | 125.0 | 127.6 | 331 | 330 | +| 5k | 511 | 758 | 125.2 | 127.6 | 322 | 321 | +| 10k | 317 | 478 | 125.1 | 127.6 | 328 | 328 | diff --git a/openspec/changes/unit-of-work/design.md b/openspec/changes/unit-of-work/design.md index e68ba59f..d64f45eb 100644 --- a/openspec/changes/unit-of-work/design.md +++ b/openspec/changes/unit-of-work/design.md @@ -261,7 +261,7 @@ 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. +`request_deadline` — зависимость с `yield` вокруг `deadline_scope` (`src/infra/db/scope.py`): `asyncio.timeout`, `TimeoutError` → та же запись «Database is unavailable» и `ServiceUnavailable`. Это нынешний `get_db_session` без сессии: та же форма, тот же момент начала, то же закрытие после ответа. Новый JSON-роутер получает срок одной строкой. Таймера блока на этих ручках нет (уточнение 18): блок начат позже и первым не сработал бы, а вторая отмена прервала бы закрытие соединения. Срок истекает отменой задачи, поэтому и нужна ветка `CancelledError` решения 4. Это расхождение с буквальным текстом постановки, оно названо в отчёте стадии и в `QUESTIONS.md`: убрать общий срок — одна строка на роутер, но тогда придётся менять цепочку LB и спек `load-balancing`. @@ -428,6 +428,10 @@ Repo-функции вызываются из многих сервисов (`at 14. **Сторож заморозки в `TcpProxy.freeze`:** разморозка через 8 с. Без него регрессия «откат вне срока» вешала тест навсегда, а не роняла его (первый красный прогон задачи 11.7 завис): теперь тест доходит до проверки и падает. 15. **`test_architecture`: унаследованный абстрактный метод — не реализация.** Первый прогон регрессии «метод порта без фейка» остался зелёным: `getmembers` находил абстрактный метод у подкласса. Это был дефект самой проверки, исправлен, регрессия повторена. 16. **Комментарии «причину записал» в сервисах называют единицу работы, а не `session_scope`:** проверка задачи 9.2 ищет имя по всему `src`. +17. **Замечание verify C1: `BoundedCloseConnection` обрывает транспорт сам.** Прерванная проверка: SQLAlchemy закрывает соединение, `protocol.close()` ставит `closing` и ждёт отмену запроса; `wait_for` его отменяет, `Connection._abort()` зовёт `protocol.abort()`, а тот выходит сразу по `closing` (`asyncpg/protocol/protocol.pyx`). Сокет оставался открытым до конца процесса. Раньше сессию снимал сервер: проверка диалекта начиналась с `BEGIN`, срабатывал `idle_in_transaction_session_timeout`; у `;` транзакции нет, поэтому решение 7 превратило утечку сокета в сессии сверх пула без срока (6 заморозок при пуле 4: 24 `idle`). Решение 7 не откатывается, чинится корень: при штатном закрытии `protocol.close` обрывает транспорт сам, поэтому второй `abort` ничего не меняет (`test_soft_close_is_graceful`: Terminate дошёл, в журнале PostgreSQL нет `unexpected EOF`). `terminate()` не менялся: при `shield` в SQLAlchemy внутреннее закрытие дорабатывает и обрывает транспорт. **Почему `test_ping_*` этого не видели:** они проверяют обрыв (`drop`: транспорт уже закрыт), один обмен и живое соединение, но не заморозку на проверке; тесты заморозки застают открытую транзакцию, где сессию снимает сервер, смотрят сроки и пул процесса, а `pg_stat_activity` не смотрит никто, и прокси при выходе обрывает всё сам. +18. **Замечание verify W1: при общем сроке таймер блока не взводится.** Общий срок начат раньше на длительность блока входа, поэтому оба истекали почти разом: срок запроса отменял задачу, пул закрывал соединение в `_checkin_failed`, таймер блока прерывал это закрытие второй отменой (`Exception terminating connection`, запись пула возвращал сборщик мусора). `_deadline_task` (`ContextVar`) ставит `deadline_scope`, `session_scope` берёт `asyncio.timeout(None)`, только если значение — текущая задача: копию контекста получает и дочерняя задача, а отмена общего срока до неё не доходит (`test_child_task_under_deadline_keeps_block_timer`). Ветка `CancelledError` и срок отката те же, срок ответа — `T` + закрытие ≤ 8 с < `timeout server` 10 с. Прежде отказ при заморозке приходил за `T` (закрытие прерывалось), теперь за `T` + закрытие: 4,01 с при `T` = 2 с, как в таблице проб «Заморозка до запроса». Отвергнуто: срок блока чуть больше общего (тот же второй таймер с настройкой-зазором); срок в экземпляре единицы работы (решение 6). +19. **Замечание verify W2: `service_factory` в `src/worker/main.py` — функция модуля, а не замыкание в `run()`.** Иначе тест `_handle` со своей фабрикой не поймал бы регрессию «один сервис на все доставки» в самой сборке. Тест подменяет `SqlAlchemyUnitOfWork` модуля фейком, который уступает цикл внутри блока: фейковые repo не уступают, и без этого блоки двух задач не пересекались бы. Импорт `src.worker.main` соединений не открывает. +20. **Замечание verify S2: сервисы зависят не только от абстракций.** К конкретным `Cache`, `ObjectStorage`, `JobPublisher`, `ImageRenderer` (решение 8) добавляется `src.infra.password`: `UserService` вызывает `hash_password`, `SessionService` — `verify_password` прямо из модуля, конструктором не передаются. Порта нет: чистая функция с лимитом потоков, внешнего состояния нет, замена в тесте — `monkeypatch`. Цель «только от абстракций» относится к PostgreSQL. ### Регрессии задачи 11.7 @@ -448,3 +452,6 @@ Repo-функции вызываются из многих сервисов (`at | `put` worker внутри блока | `service_test` | `test_attachment_processing.py::test_put_is_not_inside_a_block`, `test_ready_and_variants_one_block`, `test_success_commits_ready_with_variants` | | `_connection` адаптера переименован в `_ping_once` | `service_test_db` | `test_ping_detects_dropped_connection_through_proxy`, `test_ping_is_one_exchange` | | `_handle_exception` адаптера переименован в `_ping_once` | `service_test_db` | `test_ping_detects_dropped_connection_through_proxy` | +| C1: без обрыва транспорта в `BoundedCloseConnection` | `service_test_db` | `test_uow.py::test_no_sessions_over_pool_after_freeze`: `2 > 0` в первом раунде | +| W1: таймер блока и при общем сроке | `service_test_db` | `test_request_flow.py::test_deadline_in_second_block_single_record`: запись пула `Exception terminating connection` | +| W2: один сервис на все доставки в `service_factory` | `service_test` | `test_worker_deliveries.py::test_concurrent_deliveries_have_own_unit_of_work`: `[['ack'], ['requeue']]` | 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 index d4ce6ab1..0d4670a4 100644 --- a/openspec/changes/unit-of-work/specs/unit-of-work/spec.md +++ b/openspec/changes/unit-of-work/specs/unit-of-work/spec.md @@ -102,6 +102,11 @@ - **WHEN** карточка чата есть в кэше, и участник читает чат - **THEN** соединение для этого блока не выдаётся +#### Scenario: После заморозки PostgreSQL сессий сверх пула нет + +- **WHEN** пул прогрет, PostgreSQL заморожен на проверке соединения при выдаче, блоки получили отказ по сроку, и сервер разморожен, несколько раз подряд +- **THEN** сброшенные соединения закрыты сразу, а не в конце процесса, и после каждой разморозки сессий процесса в PostgreSQL не больше размера пула + ### Requirement: Срок блока и отказ PostgreSQL Блок, включая откат при выходе, SHALL укладываться в `[database] request_timeout_seconds`. Если PostgreSQL недоступен или не ответил @@ -136,7 +141,13 @@ Запросы ручек пользователей, сессий, чатов и сообщений SHALL целиком укладываться в `[database] request_timeout_seconds`: все их блоки и очередь вычисления хэша пароля вместе. Срок истёк — ответ 503 `unavailable` и та же запись «Database is unavailable». Так ответ реплики приходит раньше `timeout server` балансировщика (10 с), как и до разделения запроса на шаги. Ручки вложений общего срока MUST NOT иметь: -передача тела и потока дольше срока одного блока, у них срок на шаг (`load-balancing`, «Загрузки через балансировщик»). +передача тела и потока дольше срока одного блока, у них срок на шаг (`load-balancing`, «Загрузки через балансировщик»). Внутри общего срока истекает он один: +второй отмены, которая прервала бы закрытие соединения, MUST NOT быть. + +#### Scenario: Срок запроса истёк во втором блоке: одна запись, без ERROR пула + +- **WHEN** PostgreSQL заморожен между блоком входа и блоком операции, и общий срок истекает +- **THEN** клиент получает 503 `unavailable` не позже общего срока и срока закрытия соединения, в журнале одна запись «Database is unavailable», записей об ошибке пула нет, занятых соединений нет #### Scenario: Два медленных шага diff --git a/openspec/changes/unit-of-work/tasks.md b/openspec/changes/unit-of-work/tasks.md index aace2a7b..0fb737a3 100644 --- a/openspec/changes/unit-of-work/tasks.md +++ b/openspec/changes/unit-of-work/tasks.md @@ -207,3 +207,29 @@ - [x] 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`. + +## 14. Замечания проверки + +Находки `/opsx:verify` на `6ba74b1` и `952c163`. Задачи 14.1–14.6 — код, тесты и документы на рабочем дереве; 14.7 — снятие на коммите, её закрывает основная сессия. + +- [x] 14.1 C1: `BoundedCloseConnection` обрывает транспорт после прерванного мягкого закрытия, иначе сессия PostgreSQL живёт сверх пула без срока (`src/infra/db/engine.py`). Сценарий спека «После заморозки PostgreSQL сессий сверх пула нет», тест в `service-tests/db/test_uow.py` через `TcpProxy` и `pg_stat_activity`, докстринг и `infra.md`, design («Уточнения»): почему `test_ping_*` этого не видели. + + Проверка: тест красный без правки; мягкое закрытие без отказа закрывает сессию штатно; `double_cancel.py`; заморозка PostgreSQL рабочего стенда, сессии до и после. +- [x] 14.2 W1: при общем сроке истекает один таймер: сценарий спека «Срок запроса истёк во втором блоке: одна запись, без ERROR пула», тест, красный без правки. Вне JSON-роутеров срок блока прежний. + + Проверка: `double_cancel.py 2 6 1 second-block`; `test_two_slow_steps_fit_single_deadline`, `test_hash_queue_gets_deadline` зелёные; цепочка LB `probe_freeze.py`: ≤ 8 с, 504 нет. +- [x] 14.3 W2: быстрый тест сценария «Одновременные доставки»: две одновременные `_handle` на фейках, у каждой своя единица работы, обе ACK. + + Проверка: красный при регрессии «один сервис на все доставки» (Edit, прогон, откат); `make service_test` с портами 1. +- [x] 14.4 W3: вывод о цене в `REPORT.md` и `QUESTIONS.md` по `make bench_compare BEFORE=unit-of-work-aa AFTER=unit-of-work-after AA=unit-of-work-before`: знак по всем ячейкам, выброс и порядок меток, шум CPU из двух rollout, сравнение с оценкой design. + + Проверка: каждое число есть в названном файле, посчитанное помимо команды подписано. +- [x] 14.5 S1: устаревшие имена в `SKILL.md` и `service-layer.md`. + + Проверка: `grep` старых имён пуст. +- [x] 14.6 S2: `REPORT.md`: от чего зависят сервисы, стрелки схемы к издателю и процессу обработки; `src.infra.password` — в design. + + Проверка: стрелки сверены с импортами. +- [ ] 14.7 Evidence на коммите правок: `service-tests`, `test-isolated`, `student-test-lb`, `failure-checks`, запись заморозки и `double_cancel.py` (основная сессия, отдельным сообщением). + + Проверка: шапка с commit, `git.dirty` false. diff --git a/service-tests/db/conftest.py b/service-tests/db/conftest.py index d5eb58c1..e8d98557 100644 --- a/service-tests/db/conftest.py +++ b/service-tests/db/conftest.py @@ -59,13 +59,34 @@ from sqlalchemy.ext.asyncio import ( # noqa: E402 ) from src.config import settings # noqa: E402 -from src.infra.db import create_engine, create_session_factory # noqa: E402 +from src.infra.db import ( # noqa: E402 + create_engine, + create_session_factory, + scope, +) from src.infra.db.models.base import Base # noqa: E402 from src.infra.db.uow import SqlAlchemyUnitOfWork # noqa: E402 _created = False +class DatabaseWarnings: + """Записи логгера `database`: сколько раз назван отказ.""" + + def __init__(self) -> None: + self.events: list[str] = [] + + def warning(self, event_name: str, **_: object) -> None: + self.events.append(event_name) + + +@pytest.fixture +def warnings(monkeypatch: pytest.MonkeyPatch) -> DatabaseWarnings: + recorder = DatabaseWarnings() + monkeypatch.setattr(scope, "logger", recorder) + return recorder + + async def _admin_connection(database: str = "postgres") -> asyncpg.Connection: source = settings.database return await asyncpg.connect( diff --git a/service-tests/db/test_request_flow.py b/service-tests/db/test_request_flow.py index 2d822ac4..59d8567b 100644 --- a/service-tests/db/test_request_flow.py +++ b/service-tests/db/test_request_flow.py @@ -3,6 +3,7 @@ JSON-запроса (спек `unit-of-work`). S3 и кэш — фейки: ра PostgreSQL как сервера, не затрагивается.""" import asyncio +import logging import time from collections.abc import AsyncIterator from pathlib import Path @@ -13,10 +14,17 @@ import pytest from sqlalchemy import event from builders import attachment_dto -from conftest import BLOCK_SECONDS, admin, truncate_all +from conftest import ( + BLOCK_SECONDS, + DatabaseWarnings, + TcpProxy, + admin, + truncate_all, +) from fakes import FakeCache, FakeDatabase, FakeObjectStorage from src.api import dependencies from src.core.repos import chat_cache +from src.core.services import ChatService from src.core.services import session as session_module from src.infra.db import create_engine, create_session_factory from src.infra.db.session import engine, session_factory @@ -24,6 +32,7 @@ from src.infra.db.uow import SqlAlchemyUnitOfWork from src.main import app from src.schemas.dataclasses import ChatFullDTO from src.schemas.enums import AttachmentStatus +from src.utils.constants import DB_CLOSE_TIMEOUT_SECONDS from src.utils.utc import utcnow pytestmark = pytest.mark.anyio @@ -268,6 +277,65 @@ async def test_hash_queue_gets_deadline(client: httpx.AsyncClient) -> None: assert max(elapsed for _, elapsed in results) < BLOCK_SECONDS + MARGIN +class _PoolRecords(logging.Handler): + """Записи пула: только текст, `exc_info` с кадрами не хранится.""" + + def __init__(self) -> None: + super().__init__(level=logging.WARNING) + self.messages: list[str] = [] + + def emit(self, record: logging.LogRecord) -> None: + self.messages.append(record.getMessage()) + + +async def test_deadline_in_second_block_single_record( + client: httpx.AsyncClient, + monkeypatch: pytest.MonkeyPatch, + proxy_target: tuple[str, int], + warnings: DatabaseWarnings, +) -> None: + """Сценарий «Срок запроса истёк во втором блоке: одна запись, без ERROR + пула»: заморозка между входом и операцией, зазор сроков — настоящая + длительность блока входа.""" + headers, _ = await _register_login(client) + records = _PoolRecords() + pool_logger = logging.getLogger("sqlalchemy.pool") + pool_logger.addHandler(records) + async with TcpProxy(*proxy_target) as proxy: + proxied = create_engine( + dependencies.settings.database.model_copy( + update={"host": "127.0.0.1", "port": proxy.port}, + ), + ) + monkeypatch.setattr( + dependencies, + "session_factory", + create_session_factory(proxied), + ) + real_list = ChatService.list_user_chats + + async def frozen_list(self, **kwargs): + proxy.freeze() + return await real_list(self, **kwargs) + + monkeypatch.setattr(ChatService, "list_user_chats", frozen_list) + try: + started = time.monotonic() + response = await client.get("/chats", headers=headers) + elapsed = time.monotonic() - started + checked_out = proxied.pool.checkedout() + finally: + pool_logger.removeHandler(records) + proxy.thaw() + await proxied.dispose() + assert response.status_code == 503 + assert response.json()["error"]["code"] == "unavailable" + assert elapsed < BLOCK_SECONDS + DB_CLOSE_TIMEOUT_SECONDS + MARGIN + assert warnings.events == ["Database is unavailable"] + assert records.messages == [] + assert checked_out == 0 + + async def test_upload_longer_than_block( client: httpx.AsyncClient, fake_clients, diff --git a/service-tests/db/test_uow.py b/service-tests/db/test_uow.py index a913f19e..65d4b62d 100644 --- a/service-tests/db/test_uow.py +++ b/service-tests/db/test_uow.py @@ -10,6 +10,7 @@ from sqlalchemy import event, exc, text from builders import NOW, PASSWORD_HASH, attachment_dto, user_dto from conftest import ( + DatabaseWarnings, TcpProxy, admin, make_engine, @@ -23,28 +24,16 @@ from src.infra.db import scope from src.infra.db.engine import _ping_once from src.infra.db.uow import SqlAlchemyUnitOfWork from src.schemas.enums import AttachmentStatus -from src.utils.constants import DB_CLOSE_TIMEOUT_SECONDS +from src.utils.constants import ( + DB_APPLICATION_NAME, + DB_CLOSE_TIMEOUT_SECONDS, +) pytestmark = pytest.mark.anyio SECONDS_MARGIN = 0.7 - - -class _Warnings: - """Записи логгера `database`: сколько раз назван отказ.""" - - def __init__(self) -> None: - self.events: list[str] = [] - - def warning(self, event_name: str, **_: object) -> None: - self.events.append(event_name) - - -@pytest.fixture -def warnings(monkeypatch: pytest.MonkeyPatch) -> _Warnings: - recorder = _Warnings() - monkeypatch.setattr(scope, "logger", recorder) - return recorder +# сервер замечает закрытый сокет не сразу +SESSIONS_SETTLE_SECONDS = 3.0 @pytest.fixture @@ -157,7 +146,7 @@ async def test_commit_returns_connection_after_exit(uow, engine) -> None: async def test_statement_longer_than_block( engine, - warnings: _Warnings, + warnings: DatabaseWarnings, ) -> None: """Сценарий «Запрос дольше срока».""" uow = make_uow(make_factory(engine), timeout_seconds=0.3) @@ -177,7 +166,10 @@ async def test_statement_longer_than_block( assert await _pid(uow) != first_pid -async def test_frozen_on_rollback(proxy_target, warnings: _Warnings) -> None: +async def test_frozen_on_rollback( + proxy_target, + warnings: DatabaseWarnings, +) -> None: """Сценарий «PostgreSQL заморожен при откате».""" async with TcpProxy(*proxy_target) as proxy: engine = make_engine(host="127.0.0.1", port=proxy.port, pool_size=1) @@ -247,7 +239,118 @@ async def test_cancel_with_open_transaction(proxy_target) -> None: await engine.dispose() -async def test_constraint_violation(uow, engine, warnings: _Warnings) -> None: +async def test_child_task_under_deadline_keeps_block_timer(engine) -> None: + """Общий срок снимает таймер только у своей задачи: дочернюю его отмена не + достанет, а копия контекста у неё та же.""" + uow = make_uow(make_factory(engine), timeout_seconds=0.3) + + async def slow_block() -> None: + async with uow: + await uow._current_session().execute(text("SELECT pg_sleep(4)")) + + started = time.monotonic() + async with scope.deadline_scope(timeout_seconds=30): + with pytest.raises(exceptions.ServiceUnavailable): + await asyncio.create_task(slow_block()) + assert time.monotonic() - started < 0.3 + DB_CLOSE_TIMEOUT_SECONDS + + +async def _app_sessions(connection) -> int: + """Сессии приложения во временной базе; соединение теста — без его имени.""" + return await connection.fetchval( + "SELECT count(*) FROM pg_stat_activity " + "WHERE datname = current_database() AND application_name = $1", + DB_APPLICATION_NAME, + ) + + +async def _settled_sessions(connection, *, limit: int) -> int: + """Сессии, когда их стало не больше `limit` или вышел срок ожидания.""" + deadline = time.monotonic() + SESSIONS_SETTLE_SECONDS + while True: + sessions = await _app_sessions(connection) + if sessions <= limit or time.monotonic() > deadline: + return sessions + await asyncio.sleep(0.1) + + +async def test_no_sessions_over_pool_after_freeze(proxy_target) -> None: + """Сценарий «После заморозки PostgreSQL сессий сверх пула нет»: заморозка на + проверке соединения при выдаче (транзакции нет, и срок простоя транзакции + сессию не снимет), три раза подряд.""" + pool_size = 2 + connection = await admin() + try: + baseline = await _app_sessions(connection) + async with TcpProxy(*proxy_target) as proxy: + engine = make_engine( + host="127.0.0.1", + port=proxy.port, + pool_size=pool_size, + ) + factory = make_factory(engine) + + async def step() -> None: + uow = make_uow(factory, timeout_seconds=0.3) + async with uow: + await uow._current_session().execute( + text("SELECT pg_sleep(0.05)"), + ) + + for _ in range(3): + # прогрев: открыты все соединения пула, запросы идут вместе + await asyncio.gather(*(step() for _ in range(pool_size))) + proxy.freeze() + results = await asyncio.gather( + *(step() for _ in range(pool_size)), + return_exceptions=True, + ) + assert all( + isinstance(result, exceptions.ServiceUnavailable) + for result in results + ), results + proxy.thaw() + # соединения этой пачки сброшены, в пуле их нет + assert engine.pool.checkedout() == 0 + sessions = await _settled_sessions(connection, limit=baseline) + assert sessions <= baseline, f"{sessions} > {baseline}" + # пул рабочий: новые соединения вместо сброшенных + await step() + await engine.dispose() + finally: + await connection.close() + + +async def test_soft_close_is_graceful(proxy_target) -> None: + """Мягкое закрытие без отказа: сервер получил Terminate и закрыл сессию сам, + обрыв транспорта после него ничего не меняет.""" + connection = await admin() + try: + baseline = await _app_sessions(connection) + async with TcpProxy(*proxy_target) as proxy: + engine = make_engine( + host="127.0.0.1", + port=proxy.port, + pool_size=1, + ) + async with engine.connect(): + pass + assert await _app_sessions(connection) == baseline + 1 + before = proxy.client_writes + await engine.dispose() + sessions = await _settled_sessions(connection, limit=baseline) + assert sessions == baseline + # единственная порция клиента после проверки — Terminate + assert proxy.client_writes == before + 1 + finally: + await connection.close() + + +async def test_constraint_violation( + uow, + engine, + warnings: DatabaseWarnings, +) -> None: """Сценарий «Нарушение ограничения».""" async with uow: first_pid = await _pid(uow) diff --git a/service-tests/unit/test_worker_deliveries.py b/service-tests/unit/test_worker_deliveries.py new file mode 100644 index 00000000..fe709f37 --- /dev/null +++ b/service-tests/unit/test_worker_deliveries.py @@ -0,0 +1,146 @@ +"""Сценарий «Одновременные доставки»: сервис и единица работы на доставку. + +Импорт `src.worker.main` не открывает соединений: клиентов создаёт `run()`, а +здесь только `service_factory` и `_handle` на фейках. Единица работы подменена +фейком там, где точка входа выбирает реализацию. +""" + +import asyncio +from dataclasses import dataclass, field + +import pytest + +from builders import attachment_dto, chat_dto, job_dto, user_dto +from fakes import ( + FakeDatabase, + FakeImageRenderer, + FakeObjectStorage, + FakeUnitOfWork, +) +from src.core.ports.uow import Repositories +from src.schemas import dataclasses +from src.schemas.enums import AttachmentStatus, AttachmentVariantName +from src.schemas.jobs import build_job_body +from src.utils.utc import utcnow +from src.worker import main as worker_main + +pytestmark = pytest.mark.anyio + +SOURCE = b"source-bytes" + + +class _YieldingUnitOfWork(FakeUnitOfWork): + """Уступает цикл внутри блока, как настоящая единица работы на обмене с + PostgreSQL: вторая задача на том же экземпляре попадает в открытый блок.""" + + async def _open(self) -> Repositories: + repositories = await super()._open() + await asyncio.sleep(0) + return repositories + + +@dataclass +class _Delivery: + """Сообщение брокера: итог — какой метод подтверждения вызван.""" + + body: bytes + redelivered: bool = False + settled: list[str] = field(default_factory=list) + + async def ack(self) -> None: + self.settled.append("ack") + + async def drop(self) -> None: + self.settled.append("drop") + + async def requeue(self) -> None: + self.settled.append("requeue") + + +def _rendered() -> dataclasses.RenderedVariantsDTO: + return dataclasses.RenderedVariantsDTO( + variants=tuple( + dataclasses.RenderedVariantDTO( + name=name, + content_type="image/jpeg", + width=10, + height=10, + data=name.value.encode(), + ) + for name in AttachmentVariantName + ), + peak_kib=100, + memory_limit_applied=True, + render_ms=5, + ) + + +async def _queued_job( + database: FakeDatabase, + storage: FakeObjectStorage, +) -> dataclasses.AttachmentJobDTO: + owner = user_dto() + chat = chat_dto(member_ids=(owner.id,)) + now = utcnow() + row = attachment_dto( + chat_id=chat.id, + owner_id=owner.id, + status=AttachmentStatus.QUEUED, + created_at=now, + data=SOURCE, + ) + job = job_dto(attachment_id=row.id, created_at=now) + uow = FakeUnitOfWork(database) + async with uow: + await uow.attachments.insert_attachment(attachment=row) + await uow.jobs.insert_job(job=job) + await uow.commit() + storage.seed(row.staging_key, SOURCE) + return job + + +async def test_concurrent_deliveries_have_own_unit_of_work( + database: FakeDatabase, + storage: FakeObjectStorage, + monkeypatch: pytest.MonkeyPatch, +) -> None: + created: list[FakeUnitOfWork] = [] + + def make_uow( + _factory: object, + *, + timeout_seconds: float, + ) -> FakeUnitOfWork: + created.append(_YieldingUnitOfWork(database)) + return created[-1] + + monkeypatch.setattr(worker_main, "SqlAlchemyUnitOfWork", make_uow) + stop = asyncio.Event() + make_service = worker_main.service_factory( + object(), + storage=storage, + renderer=FakeImageRenderer(database, _rendered()), + stop=stop, + ) + jobs = [await _queued_job(database, storage) for _ in range(2)] + database.events.clear() + deliveries = [ + _Delivery(body=build_job_body(job, attempt=job.attempt + 1)) + for job in jobs + ] + slots = asyncio.Semaphore(2) + + await asyncio.gather( + *( + worker_main._handle(make_service, delivery, slots, stop) + for delivery in deliveries + ), + ) + + assert [delivery.settled for delivery in deliveries] == [["ack"], ["ack"]] + assert len(created) == 2 + # вторая доставка вошла в свой блок, пока открыт блок первой + assert database.events[:2] == ["enter", "enter"] + for job in jobs: + attachment = database.attachments[job.attachment_id] + assert attachment.status == AttachmentStatus.READY diff --git a/src/infra/db/engine.py b/src/infra/db/engine.py index e8f0da1a..96fe95c9 100644 --- a/src/infra/db/engine.py +++ b/src/infra/db/engine.py @@ -28,13 +28,23 @@ class BoundedCloseConnection(asyncpg.Connection): соединение для CancelRequest и в `close()` ждёт его без срока. SQLAlchemy при отмене задачи закрывает соединение мягко, поэтому замёрзший Postgres держал бы запрос до разморозки. Здесь всё - закрытие ограничено: по истечении asyncpg обрывает соединение, а - SQLAlchemy переходит к принудительному закрытию. + закрытие ограничено, а транспорт обрывается в `finally`: прерванный + `close()` asyncpg уже пометил протокол закрывающимся, и его `abort()` + выходит сразу, не трогая сокет. Без этого сокет открыт до конца процесса, + и после разморозки сессия PostgreSQL живёт сверх пула, а срок простоя + транзакции её не снимет, если транзакции нет (проверка `_ping_once`). + После штатного закрытия обрыв ничего не делает: Terminate отправлен, и + транспорт asyncpg уже закрыл сам. `_transport` — внутреннее имя asyncpg, + его смену ловит `test_no_sessions_over_pool_after_freeze`. """ async def close(self, *, timeout: float | None = None) -> None: limit = timeout or DB_CLOSE_TIMEOUT_SECONDS - await asyncio.wait_for(super().close(timeout=timeout), limit) + transport = self._transport + try: + await asyncio.wait_for(super().close(timeout=timeout), limit) + finally: + transport.abort() def _ping_once(dbapi_connection: Any) -> bool: diff --git a/src/infra/db/scope.py b/src/infra/db/scope.py index f3ab8ad7..4eebc231 100644 --- a/src/infra/db/scope.py +++ b/src/infra/db/scope.py @@ -9,6 +9,7 @@ JSON-запроса (design change `unit-of-work`, решения 4 и 6). import asyncio from collections.abc import AsyncIterator from contextlib import asynccontextmanager +from contextvars import ContextVar from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker @@ -18,6 +19,13 @@ from src.infra.logger import AbstractLogger, get_logger logger: AbstractLogger = get_logger().bind(module="database") +# задача, у которой идёт общий срок. Задача, а не флаг: дочерняя задача получает +# копию контекста, но отмена общего срока до неё не доходит, и её блоку нужен свой +_deadline_task: ContextVar[asyncio.Task[object] | None] = ContextVar( + "deadline_task", + default=None, +) + @asynccontextmanager async def session_scope( @@ -36,10 +44,20 @@ async def session_scope( на зависшем сервере повис бы. По той же причине отмена задачи (остановка процесса, общий срок запроса) сбрасывает соединение: `close()` сессии послал бы ROLLBACK. + + Внутри `deadline_scope` своего таймера нет: общий срок той же настройкой начат + раньше и истекает первым. Таймер блока сработал бы через доли секунды, вторая + отмена прервала бы закрытие соединения в пуле: ERROR в журнале, а запись пула + вернул бы только сборщик мусора (change `unit-of-work`, уточнение 18). """ + limit = ( + None + if _deadline_task.get() is asyncio.current_task() + else timeout_seconds + ) async with session_factory() as db_session: try: - async with asyncio.timeout(timeout_seconds): + async with asyncio.timeout(limit): try: yield db_session except Exception as e: @@ -65,13 +83,17 @@ async def deadline_scope(*, timeout_seconds: float) -> AsyncIterator[None]: Истечение отменяет задачу: открытый блок сбрасывает своё соединение (`session_scope`), а здесь — та же запись и тот же отказ, что у срока блока. + Срок вызывающий задаёт не меньше срока блока: блоки своего таймера не взводят. """ + token = _deadline_task.set(asyncio.current_task()) try: async with asyncio.timeout(timeout_seconds): yield except TimeoutError as e: _log_unavailable(e) raise ServiceUnavailable from e + finally: + _deadline_task.reset(token) def _log_unavailable(error: Exception) -> None: diff --git a/src/worker/main.py b/src/worker/main.py index 41b7f15b..6f0df7ca 100644 --- a/src/worker/main.py +++ b/src/worker/main.py @@ -28,6 +28,8 @@ import signal from collections.abc import Callable from contextlib import suppress +from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker + from src.config import settings from src.core.services.attachment_processing import ( AttachmentProcessingService, @@ -38,7 +40,7 @@ from src.infra.db import create_engine, create_session_factory from src.infra.db.uow import SqlAlchemyUnitOfWork from src.infra.logger import AbstractLogger, get_logger from src.infra.render import ImageRenderer -from src.infra.s3 import create_object_storage +from src.infra.s3 import ObjectStorage, create_object_storage from src.schemas.enums import JobOutcome logger: AbstractLogger = get_logger().bind(module="worker") @@ -53,6 +55,30 @@ def main() -> int: return asyncio.run(run()) +def service_factory( + session_factory: async_sessionmaker[AsyncSession], + *, + storage: ObjectStorage, + renderer: ImageRenderer, + stop: asyncio.Event, +) -> Callable[[], AttachmentProcessingService]: + """Единица работы держит открытую сессию, а доставки идут одновременно: + сервис на доставку (design change `unit-of-work`, решение 3).""" + + def make_service() -> AttachmentProcessingService: + return AttachmentProcessingService( + uow=SqlAlchemyUnitOfWork( + session_factory, + timeout_seconds=settings.database.request_timeout_seconds, + ), + storage=storage, + renderer=renderer, + stop=stop, + ) + + return make_service + + async def run() -> int: stop = asyncio.Event() loop = asyncio.get_running_loop() @@ -67,20 +93,12 @@ async def run() -> int: session_factory = create_session_factory(engine) storage = create_object_storage(settings.s3, namespace=namespace) - renderer = ImageRenderer(worker) - - def make_service() -> AttachmentProcessingService: - # единица работы держит открытую сессию, а доставки идут одновременно: - # сервис на доставку (design change unit-of-work, решение 3) - return AttachmentProcessingService( - uow=SqlAlchemyUnitOfWork( - session_factory, - timeout_seconds=settings.database.request_timeout_seconds, - ), - storage=storage, - renderer=renderer, - stop=stop, - ) + make_service = service_factory( + session_factory, + storage=storage, + renderer=ImageRenderer(worker), + stop=stop, + ) try: if not (