diff --git a/.claude/rules/api-layer.md b/.claude/rules/api-layer.md index 8f1b6063..e95752e8 100644 --- a/.claude/rules/api-layer.md +++ b/.claude/rules/api-layer.md @@ -40,9 +40,10 @@ FastAPI, один процесс. Что обязан отдавать HTTP — - Текущий пользователь — `Depends(get_current_user)` из `dependencies.py`, по Bearer-токену (`auth.md`). Сервис — зависимость-фабрика (`Depends(get_chat_service)`), которая собирает - его из `AsyncSession`. Сессию БД открывает отдельная зависимость из - `async_sessionmaker` в `request.app.state`: одна на запрос, закрывается - после ответа. Commit делает сервис (`service-layer.md`). + его из `AsyncSession`. Сессию БД открывает `get_db_session` из + глобального `session_factory` (`src/infra/db/session.py`): одна на + запрос, закрывается после ответа, вся работа с БД ограничена сроком, + отказ БД — 503 (`infra.md`). Commit делает сервис (`service-layer.md`). - Ошибки — доменные исключения из сервиса. `HTTPException` не бросать. Статус, `code` и заголовки ответа (`WWW-Authenticate` у 401) назначает одна таблица в `errors.py`. diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index 3864b0ad..fbbdf236 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -104,13 +104,18 @@ changes `load-bench-harness` (стенд) и `perf-bottleneck-fix` ## Измеренное состояние — commit -Указание пользователя (2026-09-30). Перед замером или тестом, результат -которого идёт в отчёт, состояние кода коммитится; хеш попадает в шапку -файла доказательства и в `REPORT.md`. Пробное изменение `src`, которое -потом откатывается, — отдельный commit, откат — новый commit поверх -(`git revert`), без переписывания истории. Любое число в отчёте должно -воспроизводиться из названного commit. Push и остальные операции git — -по-прежнему только по просьбе. +Замер или тест, результат которого идёт в отчёт, снимается с +закоммиченного состояния кода; хеш попадает в шапку файла доказательства +и в `REPORT.md`. Любое число в отчёте должно воспроизводиться из +названного commit (указание пользователя 2026-09-30). + +Коммит делает не агент сам: перед замером он показывает изменения +(`git status`, `git diff --stat`), предлагает сообщение коммита и ждёт +подтверждения пользователя (указание пользователя 2026-10-01). +Пробное изменение `src`, которое потом откатывается, — отдельный commit, +откат — новый commit поверх (`git revert`), без переписывания истории; +оба — по тому же порядку. Push и остальные операции git — только по +просьбе. ## Сравнение меток: `make bench_compare` @@ -122,7 +127,8 @@ changes `load-bench-harness` (стенд) и `perf-bottleneck-fix` REAPPLY=` снимает «до», коммитит доказательства, возвращает изменение и снимает «после». Команда сама делает два коммита и отказывается стартовать на нечистом рабочем дереве: стенд - записал бы в паспорт `dirty: true`. + записал бы в паспорт `dirty: true`. Поэтому `make bench_ab` агент + запускает только с согласия пользователя. - Уровень шума берётся из сравнения двух меток одного и того же кода приложения (A/A), параметр `AA`. Что код одинаков, проверяется по git (`git diff -- src Dockerfile pyproject.toml diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index 11b7fa78..f9a687ab 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -54,16 +54,16 @@ paths: проверка идёт только через `interval`, и контейнер становится `healthy` не раньше 10 с. Порт — `APP__PORT` из окружения, по умолчанию 8080. Healthcheck живёт только в образе: он нужен и без - compose (`make run_no_compose`, стенд `bench/`), а compose берёт его - из образа и не дублирует. + compose (стенд `bench/`), а compose берёт его из образа и не + дублирует. - В образ не попадают `.env`, `config.toml`, секреты, `tests/`, `student-tests/`, `contracts/`, `evidence/`, `.claude/`, `openspec/`, `.venv/`. Отличие от bp_proxies: там `config.toml` копируется в образ, здесь нельзя. Чистый clone его не содержит, и сборка упала бы, а `Dockerfile.example` (п. 6) запрещает класть конфиг и секреты в образ. Конфигурация приходит на старте: `config.toml` монтируется - read-only в `/app/config.toml`, переменные — `environment` compose - или `docker run --env-file .env`. Это согласовано с преподавателем + read-only в `/app/config.toml`, переменные — `environment` compose. + Это согласовано с преподавателем 2026-09-29 как выполнение README лабы 1, п. 3 и `Dockerfile.example`, п. 6 (AGENTS.md, «Согласования с преподавателем»). Что где лежит — `settings.md`. @@ -99,11 +99,17 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t ## docker-compose.yml - Сервис `api`: `build: .`; порты `"127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"` - (снаружи / внутри, стенд учебный — только localhost); `environment`: - `APP__RUN_MODE=docker`, `APP__PORT=${APP__PORT:-8080}` и мосты - `SECTION__FIELD=${...}` (`settings.md`); healthcheck образа проверяет + (снаружи / внутри, стенд учебный — только localhost); `environment` + — общий с `migrate` якорь `x-app-env`: `APP__RUN_MODE: docker`, + `APP__PORT`, `DATABASE__*` из переменных `POSTGRES_*` + (`settings.md`, «Консоль и docker»); healthcheck образа проверяет `APP__PORT`; `stop_grace_period: 10s`; `restart: unless-stopped`. Имена переменных в `.env` — `settings.md`, «Имена в `.env`». +- Литералов адреса и порта Postgres в compose нет: `POSTGRES_HOST` + становится алиасом сервиса в сети, `POSTGRES_PORT` — портом самого + сервера через `PGPORT` (его же берут `pg_isready` и `psql` в + контейнере). Литерал — только адрес публикации `127.0.0.1`: это + требование безопасности, а не параметр. - `config.toml` — только длинной записью, иначе при отсутствии файла Docker молча создаст на хосте каталог `config.toml/`, и приложение упадёт на чтении настроек (проверено): @@ -139,11 +145,17 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t `compose.example.yaml` — лишь список ролей, стенд — свой `docker-compose.yml` (compose находит его сам, как и `compose.yaml`). - Образы зависимостей закреплены так же, как базовый: тег с патч-версией - и digest индекса (`postgres:17.N-<вариант>@sha256:...`), не - `postgres:17` и не `latest`. -- У каждой зависимости свой healthcheck (`pg_isready` у Postgres), API - ждёт `depends_on: condition: service_healthy`. Миграции — отдельный - одноразовый сервис, API ждёт его `service_completed_successfully`. + и digest индекса (`postgres:18.6-trixie@sha256:...`), не + `postgres:18` и не `latest`. Точка монтирования volume — из + `Config.Volumes` образа: у Postgres 18 это `/var/lib/postgresql`, а не + `/var/lib/postgresql/data`, как у 17. +- У каждой зависимости свой healthcheck, API ждёт `depends_on: + condition: service_healthy`. У Postgres — `pg_isready -h 127.0.0.1` + по TCP: при инициализации образ поднимает временный сервер только на + сокете, и проверка через сокет сказала бы «готов» раньше времени. + Миграции — отдельный одноразовый сервис на образе API + (`pull_policy: never`, образ собирает `api`), API ждёт его + `service_completed_successfully`. - Данные — именованные volumes. `make down` и скрипты их не удаляют; удаление учебных данных — отдельная явная команда в `REPORT.md`. - Postgres наружу — только `127.0.0.1:${POSTGRES_OUT_PORT}`, для @@ -166,6 +178,10 @@ Hook для `make test-persistence ACTION_SCRIPT=scripts/restart.sh` - Перезапускает API и **все** используемые хранилища: Postgres и, если есть, Redis или Valkey. Volumes, схему и данные сохраняет: без `down -v`, `FLUSHALL`, повторного seed и изменения тестовых данных. +- Порядок: `stop api` → `restart postgres` → `up -d --wait postgres` + (тот же контейнер, ожидание healthcheck) → `start api`. `start api` + запускает и зависимость `migrate`: повторный прогон миграций — + no-op. - `#!/bin/sh`, `set -eu`, исполняемый бит в git (`chmod +x`, `git update-index --chmod=+x`). Возвращает 0 только после действия, укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает. diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 19ed3a39..5cb1a603 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -10,24 +10,35 @@ paths: S3, брокер, телеметрия. Бизнес-правил (уникальность, доступ, валидация) здесь нет: они в сервисах, атомарные операции — в repo. -- Объект создаётся один раз в lifespan `src/main.py`, кладётся в - `app.state` и закрывается в shutdown lifespan. Соединения при импорте - модуля не открываются; исключение — ленивая настройка логгера. -- Сервисы получают объект через зависимость из `src/api/dependencies.py` - и не импортируют модульный глобал. -- `db/`: `create_async_engine` и `async_sessionmaker` в lifespan, - `engine.dispose()` в shutdown. Асинхронный драйвер (asyncpg или - psycopg 3) выбирает design change. Модели — `db/models/` - (`migrations.md`). +- Клиент хранилища (engine Postgres, с «4» клиент Redis/Valkey) — + глобал своего модуля (`db/session.py`): создаётся при импорте по + `settings` (настройки читаются один раз на процесс), соединения + открывает лениво, при первом запросе. Модуль не импортирует пакет + `src/infra/<клиент>/` и модели, поэтому alembic и скрипты клиента не + создают. Закрытие (`engine.dispose()`) — в lifespan `src/main.py`. + Почему не `app.state` — design change `postgres-storage`, решение 5. +- Глобал импортируют только `src/main.py` (закрытие) и + `src/api/dependencies.py`; сервисы получают сессию или клиент через + конструктор из зависимости и сами глобал не импортируют. Процессу со + своим пулом (worker с лабы 5) — свой вызов фабрики `create_engine`. +- `db/`: `engine.py` — фабрики engine и сессий, `BoundedCloseConnection`, + `ping`; `session.py` — глобалы `engine` и `session_factory`; + `errors.py` — `is_db_unavailable`; модели — `models/` + (`migrations.md`). Драйвер — asyncpg. - Источник истины — PostgreSQL. SQLite, файлы и память процесса его не заменяют (`README.md`, п. 2). Кэш не хранит ничего, чего нет в Postgres; исключение — сессии, если их хранилище выбрано в Redis или Valkey (`auth.md`). - Пул ограничен (`pool_size`, `max_overflow`, `pool_timeout`), у - подключения и запроса есть таймауты (connect, `statement_timeout` или - `command_timeout` драйвера). Это требование уровня 4; значения — поля - секции `[database]` (`settings.md`). Пул считается на один процесс - (`run-modes.md`). + подключения и запроса есть таймауты (`connect_timeout_seconds`, + серверный `statement_timeout`, срок запроса `request_timeout_seconds`). + Это требование уровня 4; значения — поля секции `[database]` + (`settings.md`). Пул считается на один процесс (`run-modes.md`). +- `command_timeout` asyncpg не использовать: на таймауте он отменяет + запрос через новое соединение и ждёт сервер без срока, и замёрзший + Postgres держит запрос до разморозки. Срок запроса ставит + `asyncio.timeout` в `get_db_session`, а мягкое закрытие соединения + ограничивает `BoundedCloseConnection` (`connection_class` asyncpg). - `/health/ready` проверяет критичные зависимости через infra: `SELECT 1` в Postgres с коротким таймаутом, Redis или Valkey — если без него не работает обязательный путь (хранилище сессий). @@ -35,8 +46,10 @@ S3, брокер, телеметрия. Бизнес-правил (уникал `REPORT.md`. - Потеря соединения и таймауты драйвера на бизнес-запросе — 503 `unavailable` без деталей (`api-contract.md`), не 500 и не обход - аутентификации. В каком слое исключение драйвера становится - `ServiceUnavailable`, решает design change. + аутентификации. Перевод — в `get_db_session`: `is_db_unavailable` + решает, отказ ли это, сессия закрывается через `invalidate()`, в + журнал — `warning`. Остальные `DBAPIError` (ограничения, синтаксис) — + дефект, им положен 500. - Redis или Valkey — одно из двух, на «4». Роль (сессии с TTL или осмысленный кэш), источник истины, политика expiry и инвалидации — в `REPORT.md`. Если это единственное хранилище сессий, нужен diff --git a/.claude/rules/migrations.md b/.claude/rules/migrations.md index 8c8dd7c0..12060356 100644 --- a/.claude/rules/migrations.md +++ b/.claude/rules/migrations.md @@ -48,6 +48,15 @@ paths: редактировать: новая ревизия поверх. - Миграции применяются до старта API: в compose — отдельный одноразовый сервис на образе API (`docker.md`), API ждёт - `service_completed_successfully`. Не `sh -c "alembic upgrade head && - python -m src"` (сервер перестаёт быть PID 1) и не из lifespan: с - лабы 3 реплик несколько. + `service_completed_successfully`; в консоли — `make run_dev` через + `make upgrade`. Не `sh -c "alembic upgrade head && python -m src"` + (сервер перестаёт быть PID 1) и не из lifespan: с лабы 3 реплик + несколько. +- `migrations/env.py` — асинхронный шаблон alembic: URL из + `settings.database.url`, мимо ConfigParser (`%` в пароле ничего не + ломает), журнал — JSON через `src/infra/logger.py`. Синхронный + `env.py` с asyncpg, как в bp_proxies, на SQLAlchemy 2.1 не работает: + флаг `async_fallback` удалён. Ревизии — обычный синхронный `op.*`. +- В ревизиях — литералы, а не константы `src`: применённая ревизия не + меняется вместе с кодом. Autogenerate для новой таблицы рендерит и + `CHECK`; для существующей таблицы новые `CHECK` дописываются руками. diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index 25980df8..706ef0e4 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -21,8 +21,8 @@ README слушал `0.0.0.0`) и литерал в `environment` compose; дл |---|---|---| | Процесс | `uv run python -m src` на хосте | `python -m src` — PID 1 контейнера | | uvicorn | `127.0.0.1`, `reload=True` по `src/` | `0.0.0.0`, без reload | -| Порт | `settings.app.port`: `APP__PORT` из `.env`, без него — 8080 | `APP__PORT` из `.env` внутри (на нём же healthcheck), `APP_OUT_PORT` снаружи — одинаково в compose и `run_no_compose` | -| Хранилища | Postgres (и Redis/Valkey на «4») — контейнеры compose, приложение ходит на `127.0.0.1:<*_OUT_PORT>`; миграции — `make upgrade` | всё в compose, зависимости по имени сервиса; миграции — отдельный сервис до старта API (`migrations.md`) | +| Порт | `settings.app.port`: `APP__PORT` из `.env`, без него — 8080 | `APP__PORT` из `.env` внутри (на нём же healthcheck), `APP_OUT_PORT` снаружи | +| Хранилища | Postgres (и Redis/Valkey на «4») — контейнеры compose, приложение ходит на `127.0.0.1:<*_OUT_PORT>` (`settings.md`, «Консоль и docker»); `make run_dev` сам поднимает Postgres и накатывает миграции | всё в compose, зависимости по имени сервиса; миграции — отдельный сервис до старта API (`migrations.md`) | | Рестарт | reload процесса данные и сессии не теряет | рестарт API и хранилищ с volumes данные и сессии не теряет (`make test-persistence`) | ## Точка входа @@ -54,32 +54,30 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`. bp_proxies: переменные наверху (`DC=docker compose`), заголовки `# -------------------------`, свой `.PHONY` у каждой цели, имена в snake_case. Apple Container не делать. -- Набор, перенесённый из лабы 1: - - `run_dev` (`APP__RUN_MODE=console uv run python -m src`); - - `run_no_compose: env_setup` — `docker build`, затем - `docker run --rm -p 127.0.0.1:$(APP_OUT_PORT):$(APP__PORT) - --env-file .env ...` на переднем плане, без `config.toml`. Порты - из `.env` (`-include .env` в секции `Docker targets`, дефолт 8080). - Остановка — Ctrl+C или `docker stop`. С лабы 2 контейнер стартует - без Postgres и мостов (`settings.md`), `/health/ready` отвечает 503: - цель проверяет образ, а не стенд; +- Запуск и общие цели: + - `run_dev: upgrade` — Postgres из compose и миграции, затем + `APP__RUN_MODE=console uv run python -m src`; - `run_docker: env_setup` (недостающие `.env` и `config.toml` из шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`), - к нему `stop`, `down`, `logs` + к нему `stop`, `down` (volume остаётся), `logs` (`$(DC) logs -f --no-log-prefix api`: без префикса `api-1 |` каждая строка — JSON); - `lint` (`ruff format .` + `ruff check --fix .`, дважды), - `env_setup` (копирует шаблоны `.env` и `config.toml`), - `student_test`. + `env_setup` (шаблоны `.env` и `config.toml`, в новый `.env` — + случайный `POSTGRES_PASSWORD`), `student_test`. - Стенд лабы 2 — `run_docker`; в `REPORT.md` описывается он, а - `run_no_compose` — как проверка образа. -- Лабе 2 нужны ещё: `start_db` / `stop_db`, `start_redis` / - `stop_redis` (если выбран Redis или Valkey), `revision` - (интерактивный `read -p`), `upgrade`. Volume передаётся переменной - (`POSTGRES_VOLUME=$(DOCKER_POSTGRES_VOLUME)`), перед миграциями - поднимается БД. `make down` volumes не удаляет; удаление учебных - данных — отдельная явная цель, описанная в `REPORT.md`. + Оба способа запуска — `run_docker` и `run_dev` — описываются в + `REPORT.md`. Запуска одного контейнера без compose нет: API без + Postgres не обслуживает запросы. +- PostgreSQL и миграции: `start_db` (`$(DC) up -d --wait postgres`), + `stop_db`, `upgrade: start_db` (`uv run alembic upgrade head`), + `revision: upgrade` (autogenerate, сообщение — `read -p`), + `wipe_data` (`$(DC) down -v --remove-orphans` только после ввода + `yes`). Volume — именованный `postgres_data` в compose. С «4» — + `start_redis` / `stop_redis`, если выбран Redis или Valkey. +- `test_isolated: env_setup start_db` — образ на временной базе + (`student-tests.md`). Скрипт запускается `$(PYTHON)`, а не `uv run`: + uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку. ## Troubleshooting @@ -89,8 +87,8 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`. `APP_OUT_PORT` и `make test BASE_URL=http://localhost:<порт>`. - Разовая подмена внешнего порта для целей Makefile — только аргументом: `make run_docker APP_OUT_PORT=8090`. Внутренний - `APP__PORT` — только в `.env`: в `run_no_compose` приложение берёт - его из `--env-file .env`, аргумент make сдвинул бы лишь `-p`. Префикс + `APP__PORT` — только в `.env`: его читают и compose, и приложение в + console, а аргумент make поменял бы одну переменную make. Префикс `APP_OUT_PORT=8090 make ...` не сработает: `-include .env` перекроет его, и в recipe (в том числе в `docker compose`) уйдёт значение из `.env`. diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index d1259119..75bb5332 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -20,9 +20,9 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда - Приоритет (`settings_customise_sources`): окружение процесса → `.env` → `config.toml` → дефолты. Отсутствующий файл пропускается. Без `.env` и `config.toml` `Settings` обязан загрузиться на дефолтах: так - работают импорт `src`, `make run_no_compose` и чистый clone. Стенд - лабы 2 запускается через compose и получает значения из `.env`; без - Postgres приложение стартует, но `/health/ready` отвечает 503. + работают импорт `src`, alembic и чистый clone. Стенд лабы 2 + запускается через compose и получает значения из `.env`; без Postgres + приложение стартует, но `/health/ready` отвечает 503. - Все поля живут в секциях, откуда бы ни пришло значение: секцию задаёт класс `Settings`, а не файл. Вложенные поля в env — через `__`, регистр не важен: `DATABASE__PASSWORD` попадает в @@ -46,8 +46,8 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда | Где | Что | В git | |---|---|---| -| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, лимиты трека 5, TTL, адреса зависимостей для console, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` | -| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*`, пароли Redis / MinIO / брокера; мосты `SECTION__FIELD=${...}` для приложения | нет; шаблон `.env.example` | +| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` | +| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*` (адрес, порты, учётные данные), пароли Redis / MinIO / брокера; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольный адрес Postgres | нет; шаблон `.env.example` | | окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — | | `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50), пути: одинаковы на всех установках | да | @@ -67,10 +67,9 @@ Postgres, Redis, MinIO, брокера — нужны ещё и контейне Если переменная касается самого приложения, в `.env` она пишется в формате настроек (`SECTION__FIELD`), даже когда её читают ещё compose и Makefile. Пример — внутренний порт `APP__PORT`: на нём слушает -приложение, его публикуют compose и `make run_no_compose`, на нём -работает healthcheck. Compose читает `${APP__PORT}` напрямую и передаёт -в `environment` под тем же именем, а голый `docker run --env-file .env` -отдаёт его приложению как есть. +приложение, его публикует compose, на нём работает healthcheck. Compose +читает `${APP__PORT}` напрямую и передаёт в `environment` под тем же +именем. Имя без секции — только у того, что приложение не читает: `APP_OUT_PORT` (порт на хосте), `POSTGRES_*` и другие переменные @@ -99,8 +98,23 @@ compose полю секции: контейнер. Сам `.env` в контейнер не передаётся. `docker run --env-file .env` раскрывать `${...}` не умеет и передаст -строку буквально. Стенд лабы 2 запускается через compose, а -`make run_no_compose` проверяет только образ. +строку буквально, поэтому стенд запускается только через compose. + +## Консоль и docker из одного `.env` + +Переключение консоль ↔ docker не требует правки файлов и +комментирования блоков, как в bp_proxies (design change +`postgres-storage`, решение 7): + +- консоль: приложение на хосте читает `.env`, мосты + `DATABASE__HOST=127.0.0.1`, `DATABASE__PORT=${POSTGRES_OUT_PORT}` и + учётные данные из `POSTGRES_*`; +- docker: `.env` в контейнер не попадает, адрес и порт приходят из + `environment` compose — `DATABASE__HOST: ${POSTGRES_HOST}`, + `DATABASE__PORT: ${POSTGRES_PORT}` в общем якоре `x-app-env`. + +Адрес и порт Postgres в compose — только переменные `.env`, литерал — +лишь адрес публикации `127.0.0.1` (`docker.md`). Контрактное `SESSION_TTL_SECONDS` устроено так же: переменная под этим именем в `.env` и мост `AUTH__SESSION_TTL_SECONDS=${SESSION_TTL_SECONDS}` diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 4817e261..7e7cd4c3 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -39,11 +39,17 @@ paths: требует, чтобы одновременно в полёте было ≥ 2 запросов, иначе гонка не доказана. Проверяются количество и уникальность `id`, а также отсутствие потерь при обходе всех страниц. +- Обычный прогон — `make test_isolated` (`student-tests/run_isolated.py`): + образ из рабочего дерева на временной базе `test_`, публичный + smoke и весь набор против отдельного контейнера, затем уборка при + любом исходе. Его вывод — evidence набора против контейнера. + `make student_test` — против любого запущенного стенда (`BASE_URL`), + он оставляет данные в рабочей базе. - Проверкам, которым нужен особый стенд (TTL 2 с, остановленные - Postgres или Redis), обычный `make student_test` не подходит. Сами - тесты контейнеры не трогают: стенд готовит явный hook или отдельная - цель Makefile, как `make test-persistence` в skeleton. Механизм - выбирает design change. + Postgres или Redis), обычный прогон не подходит. Сами тесты + контейнеры не трогают: стенд готовит явный hook или отдельная цель + Makefile, как `make test-persistence` в skeleton. Механизм выбирает + change `failure-checks`. - Пароли и токены тестов синтетические, не печатаются и не попадают в `evidence/` (`evidence/README.md`). - `tests/` — публичные проверки skeleton: не править, не ослаблять, diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 504b0574..bb072a73 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -1,54 +1,61 @@ --- name: run-mtusi-messenger -description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, in-memory, лаба 1) — на хосте или в Docker. Use when asked to run / start / stop the server or the container, run the smoke test, `make test` or `make student_test`, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the container, or call services directly without HTTP. +description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, лаба 2) — на хосте или в Docker. Use when asked to run / start / stop the server or the container, run the smoke test, `make test`, `make student_test` or `make test_isolated`, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the container, or call services directly without HTTP. --- REST API мессенджера (пользователи, чаты, сообщения) — сервер на -FastAPI/uvicorn, состояние в памяти процесса. Агент управляет им через -`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает свой -экземпляр в фоне, гоняет сценарий по HTTP, публичный smoke и -собственные тесты, шлёт одиночные запросы и останавливает сервер. -Против контейнера (`make run_docker`) работают те же команды драйвера, -кроме `start`/`stop`. Только стандартная библиотека Python. +FastAPI/uvicorn, данные в PostgreSQL из compose. Агент управляет им через +`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres и +накатывает миграции (`make upgrade`), запускает свой экземпляр сервера +в фоне, гоняет сценарий по HTTP, публичный smoke и собственные тесты, +шлёт одиночные запросы и останавливает сервер. Против контейнера +(`make run_docker`) работают те же команды драйвера, кроме +`start`/`stop`. Только стандартная библиотека Python. Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12, Python 3.12 из `.python-version`, Docker Desktop 29.8. +До change `session-auth` API идентифицирует по `X-User-Id`, поэтому +публичный smoke лабы 2 падает на регистрации с `password` (400), а в +`student-tests` падает `test_security_scheme_in_openapi`: схемы `devUser` +нет в контракте lab2. Это ожидаемо (AGENTS.md, «Переходное состояние»). + ## Setup ```bash -uv sync --all-extras # venv с ruff и dev-группой (openapi-spec-validator) -make env_setup # .env и config.toml из шаблонов, существующие не трогает +uv sync --all-extras # venv с ruff и dev-группой (pytest, httpx, валидатор) +make env_setup # .env (случайный POSTGRES_PASSWORD) и config.toml, существующие не трогает ``` -Без `.env` и `config.toml` сервер тоже поднимается — на дефолтах -(порт 8080, `INFO`). +Нужен запущенный Docker: Postgres живёт в compose. Без Postgres сервер +стартует, но `/health/ready` отвечает 503; `driver.py start` сам делает +`make upgrade`. ## Run (agent path) ```bash D=.claude/skills/run-mtusi-messenger/driver.py -python3 $D all # start → flow → tests/smoke.py → student-tests → stop; код 0 = всё прошло +python3 $D all # start → flow → tests/smoke.py → student-tests → stop ``` По шагам, когда между ними нужно что-то сделать (поправить код, посмотреть лог, послать свой запрос): ```bash -python3 $D start # фон, ждёт /health/ready до 30 с +python3 $D start # make upgrade, затем фон; ждёт /health/ready до 30 с python3 $D status # listeners: [pid reloader, pid worker], ready: True python3 $D flow # ~35 проверок: регистрация, 409, /me, 401, чат, 5 сообщений, # пагинация limit=2 по курсору, чужой → 404, 400-е, X-Request-Id python3 $D req POST /api/v1/users --data '{"username":"zoe_demo","display_name":"Зоя"}' python3 $D req GET /api/v1/users/me --user python3 $D smoke # публичный tests/smoke.py против этого порта -python3 $D student # make student_test BASE_URL=http://localhost: — 79 тестов, <1 с +python3 $D student # make student_test BASE_URL=http://localhost: — 80 тестов, ~1,5 с python3 $D stop ``` | команда | что делает | |---|---| -| `start` | `APP__RUN_MODE=console APP__PORT= uv run python -m src` в своей группе процессов | +| `start` | `make upgrade`, затем `APP__RUN_MODE=console APP__PORT= uv run python -m src` в своей группе процессов | | `status` | кто слушает порт, отвечает ли `/health/ready`; код 1, если никого | | `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat | | `req METHOD PATH [--user UUID] [--data JSON]` | один запрос: статус, `x-request-id`, тело; код 2 при статусе ≥ 400 | @@ -66,17 +73,18 @@ python3 $D stop ## Run: контейнер (compose) -Образ `mtusi-messenger:lab1`, compose-сервис `api`. Внешний порт — -аргументом make, чтобы не столкнуться с 8080: +Образ `mtusi-messenger:lab2`, compose-сервисы `postgres`, `migrate` +(одноразовые миграции) и `api`. Внешний порт — аргументом make, чтобы не +столкнуться с 8080: ```bash -make run_docker APP_OUT_PORT=18090 # build + up -d; healthy за ~2 с -docker compose ps --format '{{.Name}} {{.Ports}} {{.Status}}' +make run_docker APP_OUT_PORT=18090 # build + up -d: postgres → migrate → api +docker compose ps -a --format '{{.Name}} {{.Ports}} {{.Status}}' python3 $D --port 18090 flow # те же проверки против контейнера -python3 $D --port 18090 smoke docker compose logs --no-log-prefix api | tail -5 # JSON-строки, без -f -docker compose restart api # рестарт = пустое состояние: старые X-User-Id → 401 -make down # остановить и удалить, ~0,5 с +scripts/restart.sh # рестарт API и Postgres: данные и X-User-Id остаются +make down # удалить контейнеры, volume с данными остаётся +make wipe_data # удалить и данные: только после ввода yes ``` `make run_docker` сам создаёт недостающие `.env` и `config.toml` @@ -86,33 +94,42 @@ make down # остановить и удали ## Direct invocation (без HTTP) -Для правок в `src/core/` сервисы вызываются поверх `MemoryStore`, сервер -не нужен. `APP__LOG_LEVEL=WARNING` убирает JSON-логи сервисов из вывода: +Для правок в `src/core/` сервисы вызываются поверх сессии БД, сервер не +нужен, но Postgres с миграциями нужен (`make upgrade`). +`APP__LOG_LEVEL=WARNING` убирает JSON-логи сервисов из вывода: ```bash +make upgrade APP__LOG_LEVEL=WARNING uv run python - <<'EOF' import asyncio -from src.infra.memory import MemoryStore +import uuid from src.core.services import UserService +from src.infra.db.session import engine, session_factory async def main(): - users = UserService(store=MemoryStore()) - user = await users.register(username="alice", display_name="Alice") - print(await users.identify(raw_user_id=str(user.id))) + async with session_factory() as db_session: + users = UserService(db_session=db_session) + user = await users.register( + username=f"alice_{uuid.uuid4().hex[:6]}", + display_name="Alice", + ) + print(await users.identify(raw_user_id=str(user.id))) + await engine.dispose() asyncio.run(main()) EOF ``` -`ChatService` и `MessageService` создаются так же (`store=...`), все -методы keyword-only. Ошибки — доменные исключения из `src.core.exceptions` -(базовый `DomainError`), не HTTP-коды: `identify(raw_user_id="not-a-uuid")` -бросает `Unidentified`. +`ChatService` и `MessageService` создаются так же (`db_session=...`), +все методы keyword-only, commit делает сам сервис. Ошибки — доменные +исключения из `src.core.exceptions` (базовый `DomainError`), не +HTTP-коды: `identify(raw_user_id="not-a-uuid")` бросает `Unidentified`. +Созданное так остаётся в рабочей базе. ## Run (human path) ```bash -make run_dev # 127.0.0.1:8080, reload по src/; Ctrl-C +make run_dev # Postgres + миграции, затем 127.0.0.1:8080, reload по src/; Ctrl-C ``` Блокирует терминал — агенту не подходит, используй `driver.py start`. @@ -121,31 +138,38 @@ make run_dev # 127.0.0.1:8080, reload по src/; Ctrl-C ```bash make check # офлайн-структура skeleton +make test_isolated # образ на временной базе: smoke + student-tests, уборка python3 $D all # живой сервер + flow + smoke + student-tests make lint # ruff; затрагивает и driver.py ``` -Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none`, -`PASS: lab1 public API scenario...`, `79 passed`, `All checks passed!`. +Ожидаемо до `session-auth`: `PASS: offline skeleton structure...`, +`FAILED: none` у `flow`, smoke — `FAIL: POST /api/v1/users: expected +[201], received 400`, student — `1 failed, 79 passed` +(`test_security_scheme_in_openapi`), `All checks passed!`. Поэтому +`all` и `test_isolated` пока выходят с ненулевым кодом. ## Gotchas - **На 8080 обычно уже работает `make run_dev` пользователя.** Поэтому драйвер по умолчанию на 18080. `driver.py --port 8080 stop` чужой сервер не убьёт (нет pid-файла → `left running`, код 1) — и не надо: - в его памяти данные пользователя. -- **Правка любого файла в `src/` (хватает `touch`) перезапускает worker - и стирает всё состояние** — в логе `WatchFiles detected changes ... - Reloading...`. Задевает и `make run_dev` на 8080. Старые `X-User-Id` - после этого дают 401. После правки кода: `flow` заново, а не `req` со - старыми id. + это процесс пользователя. +- **Экземпляр драйвера пишет в ту же рабочую базу**, что `make run_dev` и + `make run_docker`: тестовые пользователи и чаты там остаются. Чистый + прогон — `make test_isolated` (временная база `test_`), чистый + стенд — `make wipe_data`. +- **Правка файла в `src/` перезапускает worker** (`WatchFiles detected + changes ... Reloading...`), задевает и `make run_dev` на 8080. Данные + в Postgres остаются, прежние `X-User-Id` работают. - **`lsof` на порт показывает два PID** — reloader и worker делят один сокет. Убивать по `lsof -t | xargs kill` бессмысленно: reloader поднимет worker снова. Драйвер шлёт SIGTERM группе процессов; SIGTERM на обёртку `uv run` тоже гасит всё дерево. -- **`uv sync` без `--all-extras` удалит ruff из `.venv`** (`Would - uninstall ruff`): ruff в extra `dev`, а `make lint` и PyCharm им - пользуются. +- **`uv run` и `uv sync` без `--all-extras` удаляют ruff из `.venv`** + (`Would uninstall ruff`): ruff в extra `dev`. `make lint` берёт + глобальный ruff, PyCharm — из `.venv`: после `make upgrade` или + `driver.py start` при необходимости `uv sync --all-extras`. - **`make lint` форматирует и `.claude/skills/`** — ruff в `pyproject.toml` исключает только `tests` и `scripts`. Драйвер написан под 79 колонок и COM812; при правке проверять @@ -168,6 +192,10 @@ make lint # ruff; затрагивает и dr порту, который поднимал не драйвер. Свой экземпляр гасить `stop` на его порту; чужой не трогать. Чей он — `lsof -nP -iTCP:8080 -sTCP:LISTEN`, затем `ps -o pid,ppid,etime,command -p `. -- **`req GET /api/v1/users/me --user ` вдруг даёт 401, хотя минуту - назад было 200** — сервер перезагрузился после правки в `src/` и - потерял пользователей (см. Gotchas). +- **`make upgrade failed` в `start`** — не запущен Docker или занят порт + Postgres `POSTGRES_OUT_PORT` (5433): `docker ps`, `lsof -nP + -iTCP:5433 -sTCP:LISTEN`. +- **`/health/ready` отвечает 503, `/health/live` — 200** — Postgres + недоступен: `docker compose ps postgres`, `make start_db`. Запросы к + API в это время получают 503 `unavailable`, после возврата Postgres + проходят без рестарта сервера. diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index 0e8f1f24..941b35b3 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -6,7 +6,8 @@ python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] Команды: - start поднять `python -m src` в фоне (console, reload) и дождаться + start `make upgrade` (Postgres из compose и миграции), затем поднять + `python -m src` в фоне (console, reload) и дождаться /health/ready; лог и pid — /tmp/mtusi-api-.{log,pid} status кто слушает порт и что отвечает /health/ready flow сквозной сценарий по HTTP с проверками; код выхода 1 при провале @@ -18,8 +19,9 @@ all start → flow → smoke → student (если есть student-tests/) → stop Порт по умолчанию 18080, а не 8080: на 8080 обычно висит `make run_dev` -пользователя, и его состояние в памяти трогать не надо. flow, req, smoke -и student работают с любым сервером на порту, в том числе с контейнером +пользователя, и его процесс трогать не надо. Экземпляр драйвера пишет в +ту же рабочую базу Postgres, что и `make run_dev`. flow, req, smoke и +student работают с любым сервером на порту, в том числе с контейнером (`make run_docker APP_OUT_PORT=`). """ @@ -117,6 +119,18 @@ def cmd_start(port: int) -> int: return 0 print(f"port {port} is busy:", listener_pids(port)) return 1 + # без Postgres сервис стартует, но /health/ready отвечает 503 + upgrade = subprocess.run( + ["make", "upgrade"], + cwd=ROOT, + capture_output=True, + text=True, + check=False, + ) + if upgrade.returncode != 0: + print("make upgrade failed:") + print((upgrade.stdout + upgrade.stderr)[-2000:]) + return 1 env = os.environ | {"APP__RUN_MODE": "console", "APP__PORT": str(port)} with log_path.open("wb") as log: proc = subprocess.Popen( diff --git a/AGENTS.md b/AGENTS.md index 4dd3c2e4..e91a2f28 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,8 +4,8 @@ REST API мессенджера (пользователи, чаты, истор переносится через все семь лабораторных курса и на каждой обрастает инфраструктурой. Текущая работа — **лаба 2** (`lab.json`): PostgreSQL как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или -Valkey. Код перенесён из лабы 1 и пока работает in-memory в одном -процессе; переход на lab2 идёт через changes OpenSpec. Стек: Python +Valkey. Код перенесён из лабы 1, переход на lab2 идёт через changes +OpenSpec (раздел «Переходное состояние»). Стек: Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в stdout). @@ -26,9 +26,10 @@ stdout). Ответ преподавателя записать в «Согласования с преподавателем». - Git не трогать без явной просьбы: никаких commit, push, checkout, reset, stash. Смотреть можно (`git status`, `git diff`, `git log`). - Исключение — замеры: состояние кода, которое меряется или тестируется - для отчёта, коммитится перед замером, в том числе пробное изменение и - его откат (`.claude/rules/bench.md`, «Измеренное состояние — commit»). + Замер или evidence для отчёта снимается с закоммиченного кода, но + коммит — только после подтверждения пользователя: показать изменения, + предложить сообщение, ждать ок (`.claude/rules/bench.md`, «Измеренное + состояние — commit»). - Перед завершением задачи с кодом — `make lint`. Правки API проверять на запущенном сервере (`make run_dev` или контейнер, затем `make test` и `make student_test`), а не «на глаз». @@ -77,22 +78,23 @@ stdout). ## Переходное состояние -Код перенесён из лабы 1 (commit `7b775a2`) и ещё не переведён на -лабу 2. Этот файл и `.claude/rules/` описывают целевое состояние -лабы 2, поэтому код с ними пока расходится: +Код перенесён из лабы 1 (commit `7b775a2`), хранилище уже переведено +на PostgreSQL (change `postgres-storage`). Этот файл и `.claude/rules/` +описывают целевое состояние лабы 2, поэтому в остальном код с ними пока +расходится: -- хранилище — `MemoryStore` (`src/infra/memory.py`), `get_current_user` - читает `X-User-Id`, регистрации с паролем, входа и logout нет. - Публичный smoke лабы 2 не проходит; +- `get_current_user` читает `X-User-Id`, регистрации с паролем, входа и + logout нет — change `session-auth`. До него публичный smoke лабы 2 не + проходит, а `test_security_scheme_in_openapi` падает: он сверяет + схему `devUser` с контрактом lab2, где её нет. `make test_isolated` + поэтому ещё не зелёный; - `student-tests/` идентифицируются `X-User-Id`, `bench/` поднимает - стенд без Postgres, `inproc.py` работает на `MemoryStore` + стенд без Postgres, `inproc.py` ссылается на удалённый `MemoryStore` (`bench.md`); -- `openspec/specs/` описывают поведение лабы 1 (`identification`, - `data-storage`, `users`), скилл `run-mtusi-messenger` — стенд лабы 1; -- в `docker-compose.yml` только сервис `api`; `migrations/`, - `scripts/restart.sh` и `REPORT.md` не готовы. +- `openspec/specs/` `identification` и `users` описывают поведение + лабы 1; +- `REPORT.md` заполнен только по хранению. -Код на `MemoryStore` не расширять: новое сразу пишется под Postgres. Правила лабы 1 — `git show 7b775a2:.claude/rules/<файл>`. Закрытый пункт убрать отсюда, закрытый переход — удалить раздел. @@ -236,13 +238,17 @@ stdout). | `make test [BASE_URL=...]` | публичный smoke против запущенного сервера | | `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` | | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (`tests/README.md`) | -| `make run_dev` | `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload | +| `make run_dev` | `make upgrade` (Postgres из compose и миграции), затем `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload | | `make lint` | `ruff format` + `ruff check --fix`, дважды: так нужно из-за COM812; `tests/` и `scripts/` skeleton исключены в `[tool.ruff]` | -| `make env_setup` | `.env.example` → `.env`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает | -| `make run_no_compose` | `make env_setup` (только недостающие файлы) + `docker build` + `docker run --rm --env-file .env` на переднем плане, порты `APP_OUT_PORT` / `APP__PORT` из `.env`, без `config.toml`; стоп — Ctrl+C. Без Postgres — только проверка образа | -| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: стенд лабы 2; `config.toml` монтируется read-only | -| `make stop` / `make down` | остановить / удалить контейнеры compose | -| `make logs` | журнал сервиса compose, каждая строка — JSON (`--no-log-prefix`) | +| `make env_setup` | `.env.example` → `.env` со случайным `POSTGRES_PASSWORD`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает | +| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: postgres → migrate → api; `config.toml` монтируется read-only | +| `make stop` / `make down` | остановить / удалить контейнеры compose; volume с данными остаётся | +| `make logs` | журнал API, каждая строка — JSON (`--no-log-prefix`) | +| `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` | +| `make upgrade` | `start_db` + `uv run alembic upgrade head` с хоста (`127.0.0.1:POSTGRES_OUT_PORT`) | +| `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` | +| `make wipe_data` | `down -v` — удалить данные стенда; только после ввода `yes` | +| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_`: сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test`, уборка при любом исходе (`student-tests.md`) | | `make student_test [BASE_URL=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера; сервер недоступен — код 2 и одна строка с адресом | | `make bench [BENCH_LABEL=...]` | полная матрица (~18 мин на лабе 1) на своём стенде `mtusi-bench-*` без портов хоста; результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста. Цели `bench*` под Postgres ещё не доработаны (`.claude/rules/bench.md`) | | `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт | @@ -259,8 +265,7 @@ stdout). ## Карта кода Файлы домена называются одинаково во всех слоях (`user`, `chat`, -`message`, `session` и т.д.). Помеченное «(лаба 2)» появится с -переходом на Postgres, «(лаба 1)» с ним уйдёт. +`message`, `session` и т.д.). ``` src/ @@ -280,8 +285,10 @@ src/ exceptions/.py # доменные исключения, реэкспорт в __init__.py infra/ logger.py # structlog, get_logger(), contextvar-ы request_id / user_id - memory.py # (лаба 1) MemoryStore — dict-ы и индексы в памяти процесса - db/ # (лаба 2) engine, async_sessionmaker, models/ + db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping + db/session.py # глобалы engine и session_factory процесса API + db/errors.py # is_db_unavailable: какие ошибки драйвера — 503 + db/models/ # модели SQLAlchemy (Base с created_at и to_dict) schemas/ dataclasses/.py # DTO между repo → service → api enums/.py # StrEnum доменов, RunModeEnum @@ -296,21 +303,23 @@ student-tests/ # black-box тесты по HTTP (уровень 4) spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4 test_.py # сценарии основных спеков, маркер @pytest.mark.spec + run_isolated.py # make test_isolated: образ на временной базе test_ (stdlib) bench/ # нагрузочный стенд из лабы 1 (под Postgres не доработан): make bench / make bench_quick run.py # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json k6/ # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы inproc.py # make bench_inproc: разложение времени запроса внутри процесса, сверка формата времени compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд -migrations/, alembic.ini # (лаба 2) ревизии alembic; применяет одноразовый сервис compose +migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose infra/ # конфигурации сервисов стенда (Postgres, Redis/Valkey); README.md — skeleton -scripts/restart.sh # (лаба 2) restart hook для make test-persistence, по restart.example.sh -Dockerfile # builder (uv sync --locked) → runtime: .venv + src, UID 10001, healthcheck -docker-compose.yml # сервис api: порты из .env, config.toml read-only; (лаба 2) postgres, миграции, volumes +scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh +Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck +docker-compose.yml # postgres, migrate, api; адреса и порты из .env, volume postgres_data .dockerignore config_example.toml, .env.example -evidence/container/ # выводы проверок контейнера для REPORT.md -evidence/tests/ # вывод make student_test для REPORT.md +evidence/storage/ # отказы БД, пул, рестарт, порты Postgres +evidence/migrations/ # миграции с нуля и повторно +evidence/tests/ # выводы make test_isolated и make student_test для REPORT.md evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6 evidence/profile/<метка>.txt # результаты make bench_inproc evidence/compare/ # таблицы make bench_compare: <до>__<после>.md @@ -321,9 +330,8 @@ KNOWN_ISSUES.md # найденные попутно дефекты, - Поток однонаправленный. Роутер (зависимости, модели API) → сервис (логика, проверки доступа, id и время, логи) → repo (одна атомарная - операция над хранилищем, отдаёт DTO) → хранилище из `src/infra/` - (лаба 1 — `MemoryStore`, лаба 2+ — `AsyncSession`). Подробности — в - правилах слоёв. + операция над хранилищем, отдаёт DTO) → PostgreSQL через + `AsyncSession` (`src/infra/db/`). Подробности — в правилах слоёв. - Отличия от bp_proxies. Из `core/` вынесены инфраструктура (`src/infra/`: логгер, хранилища, клиенты), утилиты (`src/utils/`), настройки (`src/config/` вместо `src/data/`) и HTTP-модели diff --git a/REPORT.md b/REPORT.md index e42f2b05..c77d2c77 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,234 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO +- Автор, группа: Сафронов Роман Николаевич, БВТ2301 +- Целевая оценка 5; выбранный трек 5: 2 (план запроса и восстановление) - Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта + +Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change +`postgres-storage`). Впереди: пароли, вход и сессии (`session-auth`), +кэш Redis/Valkey (`membership-cache`), проверки отказов уровня 4 +(`failure-checks`), EXPLAIN и стенд под Postgres (`bench-postgres`), +трек 2 (`track2-query-plans`, `track2-backup-restore`). ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +**Версии.** Образ API: `python:3.12.14-slim-trixie` и `uv 0.12.17`, +Postgres: `postgres:18.6-trixie`; все закреплены тегом и digest индекса +(amd64 + arm64) в `Dockerfile` и `docker-compose.yml`. Приложение: +Python 3.12, FastAPI 0.141.1, SQLAlchemy 2.1.1 (async), asyncpg 0.31.0, +alembic 1.20.0 и остальное строго по `uv.lock`. Проверено на Docker +Desktop 29.8.1 (VM linux/arm64), Compose v5.5.1, macOS на Apple M3 Pro. + +**Нужно на машине:** Docker с BuildKit, `make`, `python3` (3.9+) для +публичных проверок и `make test_isolated`, свободные порты +`127.0.0.1:8080` (API) и `127.0.0.1:5433` (Postgres). uv на хосте нужен +только для запуска сервиса без контейнера (`make run_dev`). + +**Подготовка и секреты.** `make env_setup` создаёт `.env` из +`.env.example` и `config.toml` из `config_example.toml`; существующие +файлы не трогает. В шаблоне пароль Postgres пустой, в новый `.env` +подставляется случайный (`openssl rand -hex 16`), так что общего пароля +стенда в git нет. Отдельно запускать `env_setup` не нужно: его вызывают +`make run_docker`, `make run_dev` и `make test_isolated`. Пароль задаётся +Postgres только при создании volume: после смены `POSTGRES_PASSWORD` +нужен `make wipe_data`. + +```sh +git clone && cd <каталог clone> +git checkout solution/bvt2301-safronov +``` + +### Способ 1. Всё в compose: `make run_docker` + +```sh +make run_docker +# make env_setup (только недостающие .env и config.toml) +# DOCKER_BUILDKIT=1 docker compose build +# docker compose up -d postgres -> migrate (alembic upgrade head) -> api +``` + +Порядок задают `depends_on`: `migrate` стартует после healthcheck +Postgres (`pg_isready` по TCP), API — после того, как `migrate` +завершился с кодом 0. Готовность — `GET http://127.0.0.1:8080/health/ready` +→ 200 (несколько секунд после команды). Журнал API — `make logs`, +миграций — `docker compose logs migrate`. + +### Способ 2. Сервис на хосте: `make run_dev` + +```sh +make run_dev +# docker compose up -d --wait postgres +# uv run alembic upgrade head -> 127.0.0.1:5433 +# APP__RUN_MODE=console uv run python -m src +``` + +Сервис слушает `127.0.0.1:8080` с reload по `src/`, Postgres — тот же +контейнер и тот же volume, что у способа 1. Переключение между способами +не требует правки файлов (раздел «Конфигурация»). + +### Проверки + +```sh +make check # структура skeleton +make validate PYTHON=.venv/bin/python # OpenAPI 3.1 (после uv sync --all-extras) +make test_isolated # образ на временной базе: smoke + student-tests, уборка +make student_test # собственные тесты против запущенного стенда (BASE_URL) +make test # публичный smoke против запущенного стенда +``` + +До change `session-auth` публичный smoke лабы 2 падает на регистрации с +`password`, а в `student-tests` падает `test_security_scheme_in_openapi` +(контракт lab2 не содержит схему `devUser`); остальные 79 тестов +проходят. + +### Остановка и удаление данных + +- `make stop` — остановить контейнеры; `make down` — удалить контейнеры, + volume `postgres_data` с данными остаётся; +- `make wipe_data` — удалить контейнеры и volume, только после ввода + `yes`; следующий `make run_docker` поднимает пустую базу со схемой. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +клиент --HTTP--> api (FastAPI, 1 процесс) --asyncpg, пул--> postgres (volume postgres_data) + ^ + migrate (тот же образ, alembic upgrade head, до старта api) +``` + +**Источник истины** — PostgreSQL. Пользователи, чаты, участники и +сообщения хранятся только в нём; память процесса, файлы и SQLite не +используются. Подтверждённая запись (201) зафиксирована commit до ответа. + +**Схема** (миграция `migrations/versions/…_added_messenger_tables.py`): + +| Таблица | Ключи и ограничения | Индексы | +|---|---|---| +| `users` | PK `id`; UNIQUE `username`; CHECK шаблона `username` и длины `display_name` | `uq_users_username` | +| `chats` | PK `id`; CHECK длины `title` | — | +| `chat_members` | PK `(chat_id, user_id)`; FK на `chats` и `users`; UNIQUE `(chat_id, position)`; `position` хранит порядок `member_ids` | `(user_id, created_at, chat_id)` — keyset списка чатов | +| `messages` | PK `id`; составной FK `(chat_id, sender_id)` → `chat_members`: отправитель обязан быть участником; CHECK длины `text` | `(chat_id, created_at, id)` — keyset истории | + +`id` и `created_at` назначает сервис (`uuid4()`, `utcnow()`), а не БД. +`chat_members.created_at` — копия времени чата, по ней список чатов идёт +keyset-ом по индексу без сортировки всех чатов пользователя. `CHECK` +дублируют контракт: первым отвечает API (400), сработавший `CHECK` — +дефект валидации. + +**Транзакционные границы.** Одна `AsyncSession` на запрос, commit делает +сервис, изоляция `READ COMMITTED`: + +| Операция | Шаги в одной транзакции | +|---|---| +| регистрация | `INSERT … ON CONFLICT (username) DO NOTHING RETURNING`; конфликт → 409 | +| создание чата | проверка существования участников → `INSERT chats` → `INSERT chat_members` (одна вставка) → commit; ошибка до commit — откат, не остаётся ни чата, ни участников | +| сообщение | проверка членства → `INSERT messages` → commit | +| чтения | один `SELECT` | + +Явные блокировки не нужны: пользователи и участники не меняются и не +удаляются, гонку регистрации закрывает уникальный индекс (тест +`test_same_username_at_once`: из 10 одновременных регистраций одна 201, +девять 409). + +**Пагинация.** Курсор — ключ `(created_at, id)` последнего элемента; +запрос — сравнение кортежей по индексу, без `OFFSET`. Повторов при обходе +нет. Сообщение, которое закоммитилось позже, но с `created_at` меньше уже +пройденного курсора, текущий обход пропустит, а новый обход с начала +увидит. Время ставит один процесс API с часами хоста; при нескольких +репликах лабы 3 часы общие (один Docker-host). + +**Недоступность БД.** Критичная зависимость `/health/ready` — PostgreSQL +(`SELECT 1` с таймаутом 2 с). Ошибки соединения и таймауты на +бизнес-запросе дают 503 `unavailable` без деталей, причина пишется в +журнал (`warning`), после возврата Postgres запросы обслуживаются без +рестарта API. Таймауты: подключение 3 с, ожидание соединения пула 5 с, +серверный `statement_timeout` 5 с, срок всей работы запроса с БД 6 с; +пул 10 + 5 соединений. При замёрзшем сервере ответ приходит через 6 + 2 с: +2 с — ограниченное мягкое закрытие прерванного соединения. Без этого +ограничения asyncpg и SQLAlchemy ждали разморозки сервера (169 с в +замере); подробности — design change `postgres-storage`, решение 6. + +**Конфигурация.** Все значения — из `.env`, переключение консоль ↔ +docker без правки файлов. Консольный сервис читает `.env` с мостами +`DATABASE__*`; в контейнер `.env` не попадает, адрес и порт Postgres +приходят из `environment` compose. В compose нет литералов адреса и +порта Postgres, литерал — только адрес публикации `127.0.0.1`. + +| Переменная skeleton (`.env.example`) | В этом проекте | +|---|---| +| `APP_HOST` | режим `APP__RUN_MODE`: console — `127.0.0.1`, docker — `0.0.0.0` | +| `APP_PORT` | `APP__PORT` (внутри), `APP_OUT_PORT` (публикация на `127.0.0.1`) | +| `APP_ENV` | не используется: окружение одно — учебный стенд | +| `SESSION_TTL_SECONDS` | TODO, change `session-auth` | +| `DATABASE_URL_FILE` | не используется: URL собирает приложение из `[database]`, пароль — мостом из `POSTGRES_PASSWORD` | +| `SESSION_STORE` | TODO, change `session-auth` (сессии в PostgreSQL) | +| `CACHE_URL_FILE` | TODO, change `membership-cache` | + +**Что перенесено из лабы 1 и что изменено.** HTTP-контракт лабы 1 +(`X-User-Id`) пока сохранён: замену хранилища проверяют перенесённые +`student-tests` без правки тестов поведения. Хранилище `MemoryStore` +заменено PostgreSQL, repo и сервисы переписаны на `AsyncSession`, цель +`make run_no_compose` удалена: API без Postgres не обслуживает запросы. +Согласования с преподавателем из лабы 1 действуют: FastAPI с его +расхождениями и конфиг через `config.toml` (AGENTS.md). ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Публичный smoke | `make test`, `make test_isolated` | TODO: до `session-auth` падает на регистрации с `password` | TODO | +| PostgreSQL содержит пользователей, чаты, участников и сообщения; PK/FK, уникальный `username` | `\d` в `psql`, `alembic check` после миграций | 4 таблицы, ограничения и индексы по таблице выше; модели совпадают со схемой | `evidence/migrations/from-zero-and-rerun.md`, `migrations/versions/` | +| Миграции с нуля и повторно без дублирования | `make wipe_data`, `make run_docker`, `docker compose run --rm migrate` | `migrate` завершился с кодом 0 до старта API; повтор — no-op, число строк не изменилось | `evidence/migrations/from-zero-and-rerun.md` | +| Данные переживают рестарт API и хранилищ без удаления volumes | `scripts/restart.sh` | у API и Postgres новые `StartedAt`, прежний `X-User-Id` видит свои данные, порядок участников и истории тот же | `evidence/storage/restart.md`; `make test-persistence` — после `session-auth` | +| Составная операция создания чата атомарна | код `ChatService.create_chat`: один commit | автоматическая проверка отката — change `failure-checks` | TODO | +| Basic, Bearer, срок жизни и отзыв сессии, KDF | — | TODO, change `session-auth` | TODO | +| Secrets и volumes не в git | `.gitignore`, `make env_setup` | `.env`, `config.toml` игнорируются; пароль Postgres генерируется локально | `.gitignore` | +| Собственные тесты против контейнера | `make test_isolated` | механика проверена: база и контейнер убираются при любом исходе; зелёный прогон — после `session-auth` | `evidence/tests/test-isolated-mechanics.md` | +| Конфигурация из `.env`, без литералов адреса и порта Postgres в compose | `POSTGRES_PORT` и `POSTGRES_OUT_PORT` изменены в `.env`, `make run_docker`, `make run_dev` | оба способа запуска подключились к новому порту, compose не правился | `evidence/storage/postgres-port.md` | +| Уровень 4: ограниченный пул и таймауты | пул из одного соединения, Postgres на паузе | второй запрос — 503 через 1 с (`pool_timeout`), первый — 503 через 6 + 2 с | `evidence/storage/pool-timeout.md` | +| Уровень 4: недоступность БД | `docker compose stop` и `pause postgres` | 503 `unavailable` без деталей, `/health/live` 200, после возврата — без рестарта API | `evidence/storage/db-unavailable.md` | +| Уровень 4: гонка регистрации одного `username` | `test_same_username_at_once` | одна 201, девять 409 | TODO: вывод `make test_isolated` после `session-auth` | +| Уровень 4: параметризованные запросы | код repo | SQLAlchemy Core/ORM с параметрами, SQL из строк нет | `src/core/repos/` | +| Остальные пункты уровня 4 | — | TODO: Redis/Valkey, EXPLAIN на ≥10 000, проверки expiry и отказов | TODO | +| Трек 5 | — | TODO | TODO | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Стенд: Docker Desktop 29.8.1 на macOS (Apple M3 Pro), ВМ Docker 12 CPU и +7 GiB RAM, лимиты контейнерам не задавались; таймауты — по умолчанию из +`config_example.toml`. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `docker compose stop postgres` | 503 вместо 500, ready 503, live 200 | 503 через 0,1 с; ready 503, live 200 | после `start` — сразу, без рестарта API; подтверждённые данные на месте | +| `docker compose pause postgres` (сервер завис) | 503 не позже срока запроса | 503 через 8,0 с (6 с срок + 2 с закрытие), ready 503 через 2 с | после `unpause` — сразу | +| пул исчерпан (1 соединение, сервер завис) | ожидание не дольше `pool_timeout` | 503 через 1,0 с | после `unpause` — сразу | +| `scripts/restart.sh` (API и Postgres) | данные и порядок на месте | hook 3,7 с, готовность через 1 с после него | потерь нет | ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Сервер, замёрзший при открытом соединении, держит запрос 8 с, а не + 6: 2 с уходят на ограниченное закрытие соединения. +- Время сообщений ставит процесс API: порядок истории зависит от часов + хоста; конкурентные вставки могут быть пропущены текущим обходом + (раздел «Пагинация»). +- Один Docker-host: потерю хоста стенд не переживает, Postgres без + реплик. +- Прогоны `make student_test` и `make test` против рабочего стенда + оставляют данные в рабочей базе; обычный прогон — `make test_isolated`. +- Не реализовано: вход и сессии, Redis/Valkey, автоматические проверки + отказов, EXPLAIN и трек 2 — следующие changes. + +## Источники, библиотеки и использование ИИ + +- Документация: PostgreSQL 18 (транзакции, `statement_timeout`, + `pg_isready`), SQLAlchemy 2.1 (asyncio, пул, обработка разрывов), + alembic (async-шаблон `env.py`), asyncpg (параметры подключения, + `connection_class`), Docker Compose (`depends_on`, `--wait`, сети). +- Библиотеки: FastAPI, pydantic, pydantic-settings, structlog, + SQLAlchemy, asyncpg, alembic, uvicorn; в тестах — pytest и httpx. +- ИИ: Claude (Claude Code) помогал проектировать change + `postgres-storage` (OpenSpec), писать код, правила и отчёт, а также + проверял поведение на стенде. Решения и все правки просмотрены автором; + поведение подтверждено командами, выводы которых лежат в `evidence/`. diff --git a/openspec/changes/postgres-storage/design.md b/openspec/changes/postgres-storage/design.md index 6711e018..9b58f610 100644 --- a/openspec/changes/postgres-storage/design.md +++ b/openspec/changes/postgres-storage/design.md @@ -153,7 +153,23 @@ created_at, id`, `LIMIT limit + 1`. `uuid` Postgres сравнивает ### 5. Engine, пул и таймауты -`create_async_engine` в lifespan, `engine.dispose()` в shutdown. +Engine и фабрика сессий — глобалы `src/infra/db/session.py`. Они +создаются при импорте по `settings.database` (пул открывает соединения +лениво, при первом запросе), а `engine.dispose()` вызывается в lifespan. +Модуль импортируют только `src/main.py` и `src/api/dependencies.py`: +пакет `src/infra/db` и модели его не тянут, поэтому alembic и скрипты +engine не создают. Фабрика `create_engine(database)` остаётся для +процесса со своим пулом (worker с лабы 5). + +*Альтернатива:* создавать engine в lifespan и класть в `app.state`, как +было в первой реализации. Сравнение с wms_backend (там глобалы модуля) по +критериям этого проекта: настройки читаются один раз на процесс, поэтому +создание в lifespan гибкости не даёт; тесты black-box по HTTP, подмена +engine внутри процесса не нужна, а `test_isolated` подменяет базу через +окружение до старта процесса; `app.state` даёт нетипизированный +`getattr` и ветки «engine ещё не создан», которых после старта не +бывает. Отвергнута. + Параметры — секция `[database]`, значения по умолчанию: | Параметр | По умолчанию | Зачем | @@ -210,7 +226,7 @@ created_at, id`, `LIMIT limit + 1`. `uuid` Postgres сравнивает asyncpg обрывает соединение. Отсюда «6 + 2 с» в таблице. `/health/ready` не ходит через эту зависимость: отдельная проверка -`SELECT 1` с таймаутом через engine из `app.state`. +`SELECT 1` с таймаутом через глобальный engine. *Альтернативы:* обработчик исключений SQLAlchemy в `errors.py` — отвергнут, `errors.py` не логирует (`logging.md`), а потеря БД в логе diff --git a/openspec/changes/postgres-storage/tasks.md b/openspec/changes/postgres-storage/tasks.md index 91a03c00..cf8b0c84 100644 --- a/openspec/changes/postgres-storage/tasks.md +++ b/openspec/changes/postgres-storage/tasks.md @@ -88,7 +88,8 @@ commit»). одна транзакция (решение 4); удалить `MemoryStore`, `get_store` и `src/infra/memory.py`. Проверка: `grep -rn MemoryStore src` пусто, `make lint` чистый. -- [x] 4.3 `src/main.py`: engine в lifespan, `dispose()` при остановке; +- [x] 4.3 Engine и фабрика сессий — глобалы `src/infra/db/session.py` + (решение 5), `dispose()` в lifespan `src/main.py`; `dependencies.py`: `get_db_session`, фабрики сервисов; `get_current_user` по-прежнему по `X-User-Id`. Проверка: `make run_dev` поднимается до `/health/ready` 200; по SIGTERM в журнале @@ -101,59 +102,59 @@ commit»). (`docker compose pause postgres`); записать исключения из traceback для отказа в соединении, клиентского таймаута и таймаута пула. Проверка: список внесён в решение 6 `design.md`. -- [ ] 5.2 Перехват в `get_db_session` (решение 6): откат, `warning`, +- [x] 5.2 Перехват в `get_db_session` (решение 6): откат, `warning`, `ServiceUnavailable`. Проверка: сценарии «БД остановлена» и «БД вернулась» (`data-storage`) — 503 `unavailable` без деталей, после `docker compose start postgres` запросы проходят без рестарта API; - вывод в `evidence/storage/db-unavailable.txt`. -- [ ] 5.3 `/health/ready`: `SELECT 1` с таймаутом через engine. + вывод в `evidence/storage/db-unavailable.md`. +- [x] 5.3 `/health/ready`: `SELECT 1` с таймаутом через engine. Проверка: при остановленном Postgres `/health/ready` — 503 не позже таймаута, `/health/live` — 200. -- [ ] 5.4 Сценарий «Соединения исчерпаны»: `DATABASE__POOL_SIZE=1`, +- [x] 5.4 Сценарий «Соединения исчерпаны»: `DATABASE__POOL_SIZE=1`, `DATABASE__MAX_OVERFLOW=0`, `DATABASE__POOL_TIMEOUT_SECONDS=1`, Postgres на паузе, два одновременных запроса. Проверка: второй получает 503 примерно через 1 с, первый — 503 после `request_timeout_seconds` и закрытия соединения (6 + 2 с); вывод в - `evidence/storage/pool-timeout.txt`. + `evidence/storage/pool-timeout.md`. ## 6. Рестарт стенда -- [ ] 6.1 `scripts/restart.sh` по решению 10, исполняемый бит в git. +- [x] 6.1 `scripts/restart.sh` по решению 10, исполняемый бит в git. Проверка: `git ls-files -s scripts/restart.sh` — режим `100755`; скрипт укладывается в 90 с; по журналу записано, прогоняет ли `up` сервис `migrate` заново. -- [ ] 6.2 Сценарий «Рестарт hook-ом» (`container-run`) и «Прежний +- [x] 6.2 Сценарий «Рестарт hook-ом» (`container-run`) и «Прежний пользователь после рестарта» (`data-storage`): пользователь, чат с `member_ids` в порядке `[bob, alice]`, сообщения; `StartedAt` до и после `scripts/restart.sh`. Проверка: после рестарта тот же `X-User-Id` получает 200, история и порядок участников прежние; - вывод в `evidence/storage/restart.txt`. + вывод в `evidence/storage/restart.md`. ## 7. Проверки стенда -- [ ] 7.1 Сценарий «Консоль и контейнер» (`student-tests`): `make +- [x] 7.1 Сценарий «Консоль и контейнер» (`student-tests`): `make student_test` против `make run_dev` и против `make run_docker`. Проверка: в обоих прогонах прошли все тесты, кроме `test_security_scheme_in_openapi` (переход контракта, design, Goals). Evidence набора против контейнера снимает `session-auth`. -- [ ] 7.2 Миграции с нуля и повторно (`db-migrations`): `make +- [x] 7.2 Миграции с нуля и повторно (`db-migrations`): `make wipe_data`, `make run_docker`, журнал `migrate`; затем повторный прогон миграций при данных в базе. Проверка: `migrate` завершился с кодом 0 раньше старта API; число строк во всех таблицах до и после - повтора одинаково; вывод в `evidence/migrations/from-zero-and-rerun.txt`. -- [ ] 7.3 Сценарий «Другой порт Postgres»: `POSTGRES_PORT=5544`, + повтора одинаково; вывод в `evidence/migrations/from-zero-and-rerun.md`. +- [x] 7.3 Сценарий «Другой порт Postgres»: `POSTGRES_PORT=5544`, `POSTGRES_OUT_PORT=5545` в `.env`, compose не правится. Проверка: `make run_docker` доходит до `/health/ready` 200, `make run_dev` подключается к `127.0.0.1:5545`; `.env` возвращён; вывод в - `evidence/storage/postgres-port.txt`. -- [ ] 7.4 Сценарий «Консоль, затем docker» (`service-configuration`) и + `evidence/storage/postgres-port.md`. +- [x] 7.4 Сценарий «Консоль, затем docker» (`service-configuration`) и «down сохраняет данные» (`container-run`). Проверка: данные, созданные через `make run_dev`, видны после `make run_docker` и после `make down` + `make run_docker`, файлы конфигурации не менялись. -- [ ] 7.5 Сценарий «Адрес публикации» (`container-run`). Проверка: +- [x] 7.5 Сценарий «Адрес публикации» (`container-run`). Проверка: `docker port` для API и Postgres стенда показывает `127.0.0.1`, а не `0.0.0.0`. -- [ ] 7.6 Механика «Прогон на временной базе» (`student-tests`) при +- [x] 7.6 Механика «Прогон на временной базе» (`student-tests`) при запущенном рабочем стенде с данными: обычный прогон (до `session-auth` он заканчивается падением smoke — это сценарий «Упавшие тесты»); остановка тестового контейнера во время прогона; @@ -162,9 +163,9 @@ commit»). тестового контейнера (`docker ps -a`) соответствуют сценарию; число строк рабочей базы до и после одинаково, рабочий API отвечает; после разбора `KEEP_TEST_DB` база удалена руками; вывод в - `evidence/tests/test-isolated-mechanics.txt`. Сценарий «Успешный + `evidence/tests/test-isolated-mechanics.md`. Сценарий «Успешный прогон» и evidence набора против контейнера — задача `session-auth`. -- [ ] 7.7 Перенести дельты в основные спеки (`/opsx:sync`) и в том же +- [x] 7.7 Перенести дельты в основные спеки (`/opsx:sync`) и в том же шаге обновить `student-tests/spec_coverage.py`: тексты исключений «Прежний пользователь после рестарта» и «Хранилище не готово», исключения для «Сбой при добавлении участников», «БД остановлена», @@ -179,25 +180,27 @@ commit»). ## 8. Документы и инструменты -- [ ] 8.1 Правила по решениям 11 и 12: `settings.md`, `infra.md`, +- [x] 8.1 Правила по решениям 11 и 12: `settings.md`, `infra.md`, `run-modes.md` (плюс `test_isolated`), `docker.md`, `student-tests.md` (обычный прогон и evidence — `make test_isolated`, против любого стенда — `make student_test`). Проверка: `grep -n "POSTGRES_VOLUME\|решает design change" .claude/rules` — только там, где решение ещё не принято (`membership-cache`); `grep -rn run_no_compose .claude` пусто. -- [ ] 8.2 `AGENTS.md`: «Переходное состояние» без закрытых пунктов и с +- [x] 8.2 `AGENTS.md`: «Переходное состояние» без закрытых пунктов и с известным падением `test_security_scheme_in_openapi` до `session-auth`, карта кода, команды `start_db`, `stop_db`, `upgrade`, `revision`, `wipe_data`, `test_isolated`, без `run_no_compose`. Проверка: каждая команда из таблицы есть в `Makefile` (`make -n <цель>`). -- [ ] 8.3 Скилл `run-mtusi-messenger`: `driver.py start` перед - сервером выполняет `make start_db upgrade`; `SKILL.md` без «рестарт = - пустое состояние» и `MemoryStore`. Проверка: `python3 - .claude/skills/run-mtusi-messenger/driver.py all` завершается с кодом - 0. -- [ ] 8.4 `REPORT.md`: запуск из чистого clone (`make run_docker`, +- [x] 8.3 Скилл `run-mtusi-messenger`: `driver.py start` перед + сервером выполняет `make upgrade`; `SKILL.md` без «рестарт = пустое + состояние» и `MemoryStore`. Проверка: `python3 + .claude/skills/run-mtusi-messenger/driver.py all` — `start` сам + поднимает Postgres, `flow` без провалов, падают только smoke lab2 и + `test_security_scheme_in_openapi` (до `session-auth`, design, Goals), + затем `stop`. +- [x] 8.4 `REPORT.md`: запуск из чистого clone (`make run_docker`, `make run_dev`, остановка, `make wipe_data`), проверки (`make test_isolated`; `make student_test` против любого стенда); архитектура — схема, транзакционные границы, @@ -205,6 +208,6 @@ commit»). часов, соответствие переменных `.env.example` skeleton; строки доказательств уровня «3» по хранению со ссылками на `evidence/`. Проверка: у каждой строки есть команда, наблюдение и путь к файлу. -- [ ] 8.5 Финальная проверка: `make lint`, `make check`, +- [x] 8.5 Финальная проверка: `make lint`, `make check`, `openspec validate postgres-storage --strict`, `graphify update .`. Проверка: все команды без ошибок. diff --git a/openspec/specs/container-image/spec.md b/openspec/specs/container-image/spec.md index 82822fd4..5bb521ab 100644 --- a/openspec/specs/container-image/spec.md +++ b/openspec/specs/container-image/spec.md @@ -19,7 +19,7 @@ #### Scenario: Свежий clone - **WHEN** в новом clone репозитория выполняется - `docker build -t mtusi-messenger:lab1 .` + `docker build -t mtusi-messenger:lab2 .` - **THEN** образ собирается без ошибок #### Scenario: Устаревший lock @@ -59,23 +59,30 @@ MUST NOT быть доступны этому пользователю на за ### Requirement: Состав образа -Образ SHALL содержать только то, что нужно для работы сервиса: -интерпретатор, зависимости времени выполнения и исходники `src/`. В -образе MUST NOT быть `config.toml`, `.env`, публичных и собственных +Образ SHALL содержать только то, что нужно для работы сервиса и +применения миграций: интерпретатор, зависимости времени выполнения, +исходники `src/`, каталог миграций и конфигурацию инструмента миграций. +В образе MUST NOT быть `config.toml`, `.env`, публичных и собственных тестов, контрактов, файлов `.claude` и `openspec`, а также инструментов сборки: uv и компиляторов. #### Scenario: Нет конфигов и лишних каталогов - **WHEN** в образе просматривается рабочий каталог приложения -- **THEN** в нём есть только исходники и окружение зависимостей, а - `config.toml` и `.env` отсутствуют +- **THEN** в нём есть только исходники, миграции с их конфигурацией и + окружение зависимостей, а `config.toml` и `.env` отсутствуют #### Scenario: Нет uv в runtime - **WHEN** в контейнере запрашивается `uv` - **THEN** команда не найдена +#### Scenario: Миграции из образа + +- **WHEN** контейнер из этого образа запускается командой применения + миграций с настройками подключения к Postgres +- **THEN** миграции применяются без доступа к исходникам на хосте + ### Requirement: Сервер — основной процесс контейнера Процессом с PID 1 SHALL быть сам сервер (`python -m src`), без diff --git a/openspec/specs/container-run/spec.md b/openspec/specs/container-run/spec.md index 65d4c68e..fb65dccd 100644 --- a/openspec/specs/container-run/spec.md +++ b/openspec/specs/container-run/spec.md @@ -2,120 +2,93 @@ ## Purpose -Как контейнер сервиса запускается и настраивается: два способа запуска — -голый `docker run` из README (`make run_no_compose`) и compose -(`make run_docker`), публикация портов, конфигурация на старте и -поведение состояния при рестарте контейнера. +Как стенд сервиса запускается и настраивается: compose с PostgreSQL, +одноразовыми миграциями и API (`make run_docker`), публикация портов +только на localhost, конфигурация на старте, сохранность данных при +рестарте стенда и явное удаление учебных данных. ## Requirements -### Requirement: Запуск командами из README - -Команды из `README.md` SHALL работать без compose и без `config.toml`: -`docker build -t mtusi-messenger:lab1 .` и -`docker run --rm --name mtusi-messenger-lab1 -p 127.0.0.1:8080:8080 --env-file .env mtusi-messenger:lab1`. -Внутри контейнера сервис SHALL работать в режиме `docker` и слушать -`0.0.0.0:8080`, не требуя дополнительных переменных. - -`make run_no_compose` SHALL выполнять эти две команды, подставляя в -`-p` порты из `.env` (требование «Порты из .env»): собирать образ и -запускать контейнер на переднем плане с журналом в терминале. Перед -этим он SHALL создавать недостающие `.env` и `config.toml` из шаблонов -(`make env_setup`) и MUST NOT перезаписывать существующие. С `.env` -из шаблона команда SHALL совпадать с README. Остановка — Ctrl+C в этом -терминале или `docker stop mtusi-messenger-lab1` из другого, после -чего контейнер удаляется (`--rm`). - -#### Scenario: Публичный smoke против контейнера - -- **WHEN** контейнер запущен командой из README или - `make run_no_compose`, а в другом терминале выполняется `make test` -- **THEN** результат — `PASS: lab1 public API scenario` - -#### Scenario: Свежий clone без .env - -- **WHEN** в свежем clone без `.env` выполнен `make run_no_compose` -- **THEN** `.env` создаётся из `.env.example`, сервис стартует и - публикуется на `127.0.0.1:8080` - -#### Scenario: Остановка по Ctrl+C - -- **WHEN** в терминале с `make run_no_compose` нажат Ctrl+C -- **THEN** сервис штатно завершается (в журнале есть «Shutting down» и - «Finished server process»), а контейнера `mtusi-messenger-lab1` после - этого нет в `docker ps -a` - -#### Scenario: Без config.toml - -- **WHEN** контейнер запущен без смонтированного `config.toml` -- **THEN** сервис стартует на значениях по умолчанию - ### Requirement: Запуск через compose -`make run_docker` SHALL собирать образ и поднимать сервис `api` через -`docker compose`. Перед этим он SHALL создавать недостающие `.env` и -`config.toml` из шаблонов (`make env_setup`) и MUST NOT перезаписывать -существующие. `make stop` SHALL останавливать сервис, `make down` — -удалять контейнер, `make logs` — показывать журнал. +`make run_docker` SHALL собирать образ и поднимать стенд через +`docker compose`: PostgreSQL, одноразовый сервис миграций и API. API +SHALL стартовать после готовности PostgreSQL и успешных миграций. +Перед этим цель SHALL создавать недостающие `.env` и `config.toml` из +шаблонов (`make env_setup`) и MUST NOT перезаписывать существующие. +`make stop` SHALL останавливать сервисы, `make down` — удалять +контейнеры, сохраняя volume, `make logs` — показывать журнал API. #### Scenario: Штатный запуск - **WHEN** в свежем clone выполнен `make run_docker` - **THEN** сервис отвечает на `http://localhost:8080/health/ready`, и - `make test` проходит + `make student_test` проходит ### Requirement: Порты из .env -Оба способа запуска, `make run_no_compose` и `make run_docker`, SHALL -брать порты из одного `.env`: -- внутренний — `APP__PORT`: параметр приложения `[app] port` в формате - настроек, приложение читает его само, на нём же работает - healthcheck; -- внешний — `APP_OUT_PORT`: порт на `127.0.0.1` хоста, приложение его - не читает. +Порты стенда и консольного запуска SHALL браться из одного `.env`: +- внутренний порт API — `APP__PORT`: параметр приложения `[app] port` в + формате настроек, на нём же работает healthcheck; +- внешний порт API — `APP_OUT_PORT`: порт на `127.0.0.1` хоста, + приложение его не читает; +- порт PostgreSQL внутри сети compose — `POSTGRES_PORT`, его слушает + сам сервер и использует API в docker; +- внешний порт PostgreSQL — `POSTGRES_OUT_PORT`: порт на `127.0.0.1` + хоста для запуска в консоли. -Если переменная не задана, SHALL действовать 8080. Параметры +Если переменная порта API не задана, SHALL действовать 8080. Параметры приложения в `.env` SHALL записываться в формате настроек (`SECTION__FIELD`). Имя без секции допускается только для переменных, -которые приложение не читает. +которые приложение не читает. Адрес и порт PostgreSQL MUST NOT быть +записаны в compose литералами. #### Scenario: Другой внешний порт -- **WHEN** в `.env` задано `APP_OUT_PORT=8090` -- **THEN** при любом из двух способов API доступно на `localhost:8090`, - а внутри контейнера сервис слушает `APP__PORT` +- **WHEN** в `.env` задано `APP_OUT_PORT=8090`, и выполнен + `make run_docker` +- **THEN** API доступно на `localhost:8090`, а внутри контейнера + сервис слушает `APP__PORT` #### Scenario: Другой внутренний порт - **WHEN** в `.env` задано `APP__PORT=9090` -- **THEN** при любом из двух способов сервис внутри контейнера слушает - 9090, контейнер становится `healthy`, а API доступно на - `localhost:$APP_OUT_PORT` +- **THEN** сервис внутри контейнера слушает 9090, контейнер становится + `healthy`, а API доступно на `localhost:$APP_OUT_PORT` + +#### Scenario: Другой порт Postgres + +- **WHEN** в `.env` заданы `POSTGRES_PORT=5544` и + `POSTGRES_OUT_PORT=5545`, а compose не правился +- **THEN** `make run_docker` поднимает стенд, `/health/ready` отвечает + 200, а `make run_dev` подключается к Postgres на `127.0.0.1:5545` ### Requirement: Оба способа запуска описаны в REPORT.md -Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать оба -способа: `make run_no_compose` (без compose, команды README) и -`make run_docker` (compose). Для каждого SHALL быть указаны подготовка -(обе цели сами вызывают `make env_setup`), команды, которые выполняет -цель Makefile, ожидание готовности, `make test` и остановка. +Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два +способа запуска стенда: `make run_docker` (всё в compose) и +`make run_dev` (Postgres в compose, сервис на хосте). Для каждого SHALL +быть указаны подготовка (`make env_setup`), команды, которые выполняет +цель Makefile, применение миграций, ожидание готовности, проверки и +остановка. #### Scenario: Запуск по отчёту - **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md` для любого из двух способов -- **THEN** `/health/ready` отвечает 200, а `make test` проходит +- **THEN** `/health/ready` отвечает 200, а `make student_test` проходит ### Requirement: Публикация только на localhost -Порт сервиса SHALL публиковаться только на `127.0.0.1` хоста: в -README-команде, в `make run_no_compose` и в compose. Учебный стенд -MUST NOT быть доступен с других машин сети. +Порты API и PostgreSQL SHALL публиковаться в compose только на +`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не +переменной. Учебный стенд MUST NOT быть доступен с других машин сети. #### Scenario: Адрес публикации -- **WHEN** для запущенного контейнера выполняется `docker port` -- **THEN** порт опубликован на `127.0.0.1`, а не на `0.0.0.0` +- **WHEN** для запущенных контейнеров API и Postgres выполняется + `docker port` +- **THEN** порты опубликованы на `127.0.0.1`, а не на `0.0.0.0` ### Requirement: Конфигурация на старте @@ -144,17 +117,39 @@ compose, и приложению, SHALL передаваться через `env - **THEN** запуск завершается ошибкой о несуществующем источнике монтирования, и каталог `config.toml/` на хосте не появляется -### Requirement: Состояние теряется при рестарте контейнера +### Requirement: Данные переживают рестарт стенда -Перезапуск контейнера SHALL давать пустое состояние: у контейнера нет -volume для данных. Это ожидаемое поведение лабы 1, его показывают на -защите. +Данные PostgreSQL SHALL храниться в именованном volume. Скрипт +`scripts/restart.sh` SHALL перезапускать API и все используемые +хранилища, сохраняя volume, схему и данные: без удаления volume, +очистки и повторного наполнения. Скрипт SHALL быть исполняемым, +завершаться с кодом 0 только после перезапуска, укладываться в 90 с и +MUST NOT печатать секреты. -#### Scenario: Жизненный цикл на защите +#### Scenario: Рестарт hook-ом -- **WHEN** пользователь создан, отправил сообщение и прочитал его, после - чего контейнер перезапущен тем же образом -- **THEN** запрос с прежним `X-User-Id` получает 401 +- **WHEN** пользователь создан, отправил сообщение, затем выполнен + `scripts/restart.sh` +- **THEN** контейнеры API и Postgres перезапущены (новое время старта в + `docker inspect`), а после готовности запрос с прежним `X-User-Id` + получает 200 и видит своё сообщение + +### Requirement: Удаление учебных данных + +`make stop` и `make down` MUST NOT удалять volume с данными. Удаление +данных стенда SHALL выполняться отдельной явной командой +`make wipe_data`, которая запрашивает подтверждение. + +#### Scenario: down сохраняет данные + +- **WHEN** выполнены `make down`, затем `make run_docker` +- **THEN** ранее созданные пользователи и сообщения на месте + +#### Scenario: Явное удаление + +- **WHEN** выполнен `make wipe_data` и удаление подтверждено +- **THEN** volume Postgres удалён, и следующий `make run_docker` + поднимает пустую базу со схемой из миграций ### Requirement: Журнал контейнера diff --git a/openspec/specs/data-storage/spec.md b/openspec/specs/data-storage/spec.md index 05067d4f..1f4922c2 100644 --- a/openspec/specs/data-storage/spec.md +++ b/openspec/specs/data-storage/spec.md @@ -2,19 +2,19 @@ ## Purpose -Где живёт состояние мессенджера на лабе 1 и какие гарантии оно даёт: -память одного процесса, потеря при рестарте, защита от гонок при -параллельных запросах. +Где живут данные мессенджера с лабы 2 и какие гарантии они дают: +PostgreSQL как источник истины, сохранность после рестарта, целостность +и транзакции на стороне БД, поведение при недоступности БД и +ограниченные ресурсы подключения. ## Requirements -### Requirement: Состояние только в памяти одного процесса +### Requirement: Хранение в PostgreSQL -Пользователи, чаты и сообщения SHALL храниться только в памяти одного -процесса сервиса. Сервис MUST NOT использовать базы данных, Redis, -файлы состояния и внешние сервисы. Все запросы экземпляра SHALL -обслуживаться одним общим состоянием, без нескольких worker-процессов -с независимой памятью. +Пользователи, чаты, участники чатов и сообщения SHALL храниться в +PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные в +памяти процесса, файлах или SQLite. Подтверждённая запись (ответ 201) +SHALL быть зафиксирована в БД до ответа и видна следующему чтению. #### Scenario: Созданное видно сразу @@ -22,22 +22,25 @@ его `id` в `X-User-Id` - **THEN** пользователь найден -### Requirement: Потеря состояния при рестарте +### Requirement: Данные переживают рестарт -После перезапуска процесса состояние SHALL быть пустым. Это ожидаемое -поведение лабы 1. +После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее +подтверждённые пользователи, чаты, участники и сообщения SHALL быть +доступны в прежнем виде. #### Scenario: Прежний пользователь после рестарта -- **WHEN** сервис перезапущен и клиент использует `X-User-Id`, - созданный до рестарта -- **THEN** ответ 401 +- **WHEN** стенд перезапущен `scripts/restart.sh`, и клиент использует + `X-User-Id`, созданный до рестарта +- **THEN** ответ 200, а история чата этого пользователя содержит те же + сообщения в том же порядке ### Requirement: Параллельные запросы не повреждают состояние Параллельные запросы MUST NOT терять, дублировать или повреждать -записи. Проверки с последующей записью (уникальность `username`) -SHALL выполняться атомарно. +записи. Уникальность `username` SHALL обеспечиваться ограничением БД, +а не проверкой перед вставкой, поэтому одновременная регистрация +одного имени создаёт ровно одного пользователя. #### Scenario: 100 сообщений от 10 клиентов @@ -51,3 +54,62 @@ SHALL выполняться атомарно. - **WHEN** несколько клиентов одновременно регистрируют одинаковый `username` - **THEN** создан ровно один пользователь + +### Requirement: Целостность данных в БД + +Ограничения SHALL проверяться самой БД, а не только сервисом: +уникальность `username`, существование пользователей и чатов, на +которые ссылаются участники и сообщения, уникальность участника в +чате, членство отправителя в чате сообщения. Порядок `member_ids`, +заданный при создании чата, SHALL сохраняться. + +#### Scenario: Порядок участников + +- **WHEN** чат создан с `member_ids` в порядке `[bob, alice]` +- **THEN** `GET` этого чата и список чатов возвращают `member_ids` в + том же порядке, в том числе после рестарта стенда + +### Requirement: Составная операция в одной транзакции + +Создание чата вместе с участниками SHALL выполняться одной +транзакцией: при ошибке на любом шаге в БД MUST NOT остаться ни чата, +ни части его участников. + +#### Scenario: Сбой при добавлении участников + +- **WHEN** чат уже записан в транзакции, а запись участников + завершается ошибкой +- **THEN** транзакция откатывается, чата нет ни в `GET` по его `id`, ни + в списках чатов участников + +### Requirement: Недоступность PostgreSQL + +Если PostgreSQL недоступен или не ответил за отведённое время, +запрос SHALL завершаться ответом 503 с `code` `unavailable` в формате +ошибки, а не 500 и не зависанием. Частично выполненная операция MUST +NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL +обслуживать запросы без перезапуска. + +#### Scenario: БД остановлена + +- **WHEN** PostgreSQL остановлен, и клиент отправляет сообщение +- **THEN** ответ 503 `unavailable` без деталей в `message` + +#### Scenario: БД вернулась + +- **WHEN** PostgreSQL остановлен, затем снова запущен, а сервис не + перезапускался +- **THEN** следующие запросы после готовности БД обслуживаются штатно + +### Requirement: Ограниченный пул соединений и таймауты + +Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой. +Ожидание свободного соединения, подключение и выполнение запроса SHALL +иметь таймауты из настроек. Истёкший таймаут SHALL давать 503 +`unavailable`. + +#### Scenario: Соединения исчерпаны + +- **WHEN** все соединения пула заняты дольше таймаута ожидания +- **THEN** новый запрос получает 503 `unavailable` не позже этого + таймаута, а не ждёт бесконечно diff --git a/openspec/specs/db-migrations/spec.md b/openspec/specs/db-migrations/spec.md new file mode 100644 index 00000000..cc40b6a2 --- /dev/null +++ b/openspec/specs/db-migrations/spec.md @@ -0,0 +1,69 @@ +# db-migrations Specification + +## Purpose + +Как схема PostgreSQL появляется и меняется: версионируемые миграции, +применение с нуля и повторно без побочных эффектов, запуск миграций до +старта API в docker и в консоли. + +## Requirements + +### Requirement: Схема версионируется миграциями + +Таблицы, ограничения и индексы SHALL создаваться только миграциями из +репозитория. Сервис MUST NOT создавать или менять схему при старте. +Применённая миграция MUST NOT редактироваться: изменение схемы — новая +миграция поверх. + +#### Scenario: Схема с нуля + +- **WHEN** миграции применяются к пустой базе на новом volume +- **THEN** создаются все таблицы, ограничения и индексы, и сервис + обслуживает обязательные запросы без ручных шагов + +### Requirement: Повторный запуск миграций + +Повторное применение миграций к актуальной схеме SHALL завершаться +успешно и MUST NOT менять схему или данные. Миграции MUST NOT +создавать пользовательские данные. + +#### Scenario: Второй прогон + +- **WHEN** миграции применены, в базе есть пользователи, чаты и + сообщения, и миграции применяются ещё раз +- **THEN** команда завершается с кодом 0, а число строк во всех таблицах + не меняется + +### Requirement: Миграции до старта API в docker + +В стенде compose миграции SHALL применяться отдельным одноразовым +сервисом на образе приложения после готовности PostgreSQL. API SHALL +стартовать только после успешного завершения миграций. Если миграции +завершились ошибкой, API MUST NOT стартовать. + +#### Scenario: Порядок запуска + +- **WHEN** стенд поднимается командой `make run_docker` +- **THEN** сервис миграций завершается с кодом 0 раньше, чем стартует + API, а `/health/ready` отвечает 200 + +#### Scenario: Ошибка миграции + +- **WHEN** применение миграций завершается ошибкой +- **THEN** контейнер API не запускается, а ошибка видна в журнале + сервиса миграций + +### Requirement: Миграции до старта API в консоли + +`make run_dev` SHALL одной командой поднимать PostgreSQL из compose, +дожидаться его готовности, применять миграции и запускать сервис на +хосте. Отдельно миграции SHALL применяться командой `make upgrade`, +новая ревизия SHALL создаваться командой `make revision` на базе с +актуальной схемой. + +#### Scenario: Консольный запуск с нуля + +- **WHEN** в свежем clone после `make env_setup` выполняется + `make run_dev` +- **THEN** Postgres запущен, миграции применены, сервис отвечает на + `http://127.0.0.1:8080/health/ready` кодом 200 diff --git a/openspec/specs/health/spec.md b/openspec/specs/health/spec.md index c3fc3d7b..b13c4bae 100644 --- a/openspec/specs/health/spec.md +++ b/openspec/specs/health/spec.md @@ -23,19 +23,22 @@ MUST NOT зависеть от состояния хранилища. `GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`, когда сервис может безопасно обслуживать обязательные запросы, и 503 с -`code` `unavailable` в формате ошибки, когда не может. На лабе 1 -критичная зависимость одна — хранилище в памяти процесса, готовое после -завершения запуска. Проверка MUST NOT требовать идентификации. +`code` `unavailable` в формате ошибки, когда не может. На лабе 2 +критичная зависимость — PostgreSQL: проверка SHALL выполнять запрос к +нему с коротким таймаутом при каждом обращении. Проверка MUST NOT +требовать идентификации. #### Scenario: Сервис запущен -- **WHEN** запуск сервиса завершён и клиент запрашивает `GET /health/ready` +- **WHEN** запуск сервиса завершён, PostgreSQL доступен, и клиент + запрашивает `GET /health/ready` - **THEN** ответ 200, тело `{"status": "ok"}` #### Scenario: Хранилище не готово -- **WHEN** хранилище ещё не инициализировано -- **THEN** ответ 503 с `code` `unavailable` в формате ошибки +- **WHEN** PostgreSQL недоступен +- **THEN** ответ 503 с `code` `unavailable` в формате ошибки не позже + таймаута проверки, а `GET /health/live` при этом отвечает 200 ### Requirement: Health вне версии API и без идентификации diff --git a/openspec/specs/service-configuration/spec.md b/openspec/specs/service-configuration/spec.md index 6a0e2986..25246146 100644 --- a/openspec/specs/service-configuration/spec.md +++ b/openspec/specs/service-configuration/spec.md @@ -82,3 +82,40 @@ SHALL слушать только `127.0.0.1` и перезапускаться - **WHEN** в корне создан `config.toml` - **THEN** `git status` его не показывает, а `config_example.toml` отслеживается + +### Requirement: Подключение к PostgreSQL + +Параметры подключения SHALL задаваться в секции `[database]`: адрес, +порт, пользователь, пароль, имя базы, размер пула и таймауты. Пароль +SHALL иметь один источник — `POSTGRES_PASSWORD` в `.env`, который +читает и контейнер Postgres. Значения параметров MUST NOT печататься в +журнал целиком: пароль и строка подключения с паролем в журнал не +попадают. + +#### Scenario: Пароль в одном месте + +- **WHEN** в `.env` меняется `POSTGRES_PASSWORD`, и стенд пересоздаётся + на новом volume +- **THEN** и Postgres, и сервис в консоли и в docker используют новый + пароль без правки других файлов + +#### Scenario: Пароль не в журнале + +- **WHEN** сервис стартует и подключается к Postgres +- **THEN** в журнале нет значения пароля + +### Requirement: Консоль и docker без правки конфигурации + +Переключение между запуском в консоли и в docker MUST NOT требовать +правки `.env`, `config.toml` или compose, в том числе +комментирования и раскомментирования блоков. В консоли сервис SHALL +подключаться к Postgres по адресу публикации на хосте из `.env`, в +docker — по адресу и порту Postgres внутри сети compose, которые compose +передаёт в окружение контейнера из переменных `.env`. + +#### Scenario: Консоль, затем docker + +- **WHEN** выполнен `make run_dev`, затем он остановлен и выполнен + `make run_docker`, а файлы конфигурации между запусками не менялись +- **THEN** оба запуска доходят до `/health/ready` 200 и видят одни и + те же данные diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index d49e347c..a67f5765 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -160,3 +160,50 @@ SHALL проходить против сервера, запущенного н - **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md` - **THEN** в ней есть команда, наблюдаемый результат и путь к файлу вывода в `evidence/` + +### Requirement: Прогон на временной базе + +`make test_isolated` SHALL проверять образ, собранный из рабочего +дерева, в связке compose на временной базе `test_<имя рабочей базы>` в +PostgreSQL стенда. Команда SHALL: собрать образ, создать базу заново, +применить к ней миграции сервисом миграций compose, запустить отдельный +контейнер API из определения сервиса compose, в котором подменено только +имя базы, опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`, +дождаться готовности, выполнить публичный smoke (`make test`) и весь +набор (`make student_test`) против этого контейнера, затем остановить и +удалить контейнер и удалить базу. Код выхода SHALL быть ненулевым, если +не прошёл smoke, набор или уборка. Рабочая база и рабочий контейнер API +MUST NOT затрагиваться. Параллельный запуск двух прогонов не +поддерживается. + +#### Scenario: Успешный прогон + +- **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и + выполнен `make test_isolated` +- **THEN** smoke и набор прошли, код выхода 0, ни базы `test_`, ни + тестового контейнера после команды нет, число строк в таблицах + рабочей базы не изменилось, а рабочий API продолжает отвечать + +#### Scenario: Упавшие тесты + +- **WHEN** во время `make test_isolated` падает хотя бы один тест +- **THEN** код выхода ненулевой, журнал тестового контейнера выведен, + контейнер удалён, база `test_` удалена + +#### Scenario: Прерывание + +- **WHEN** `make test_isolated` прерван Ctrl+C +- **THEN** тестовый контейнер остановлен и удалён, база `test_` + удалена + +#### Scenario: Хвост прошлого прогона + +- **WHEN** тестовый контейнер или база `test_` остались от прогона, + убитого без уборки +- **THEN** следующий `make test_isolated` удаляет их и начинает заново + +#### Scenario: Сохранить базу для разбора + +- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1` +- **THEN** после прогона тестовый контейнер удалён, база `test_` + остаётся, а команда печатает её имя diff --git a/src/api/dependencies.py b/src/api/dependencies.py index 284f5b4a..fcf5efb5 100644 --- a/src/api/dependencies.py +++ b/src/api/dependencies.py @@ -5,18 +5,15 @@ from collections.abc import AsyncIterator from dataclasses import dataclass from typing import Annotated -from fastapi import Depends, Query, Request, Security +from fastapi import Depends, Query, Security from fastapi.security import APIKeyHeader -from sqlalchemy.ext.asyncio import ( - AsyncEngine, - AsyncSession, - async_sessionmaker, -) +from sqlalchemy.ext.asyncio import AsyncSession from src.config import settings from src.core import exceptions from src.core.services import ChatService, MessageService, UserService from src.infra.db import is_db_unavailable, ping +from src.infra.db.session import engine, session_factory from src.infra.logger import AbstractLogger, current_user_id, get_logger from src.schemas import dataclasses from src.utils.constants import ( @@ -30,7 +27,7 @@ from src.utils.constants import ( logger: AbstractLogger = get_logger().bind(module="api_dependencies") -async def get_db_session(request: Request) -> AsyncIterator[AsyncSession]: +async def get_db_session() -> AsyncIterator[AsyncSession]: """Одна сессия БД на запрос; commit делает сервис. Незакоммиченное при выходе откатывается. Вся работа запроса с БД @@ -39,13 +36,6 @@ async def get_db_session(request: Request) -> AsyncIterator[AsyncSession]: 503 `unavailable`, а соединение не возвращается в пул: его состояние неизвестно, а откат на зависшем сервере повис бы. """ - session_factory: async_sessionmaker[AsyncSession] | None = getattr( - request.app.state, - "session_factory", - None, - ) - if session_factory is None: - raise exceptions.ServiceUnavailable async with session_factory() as db_session: try: async with asyncio.timeout( @@ -67,15 +57,12 @@ async def get_db_session(request: Request) -> AsyncIterator[AsyncSession]: DbSessionDep = Annotated[AsyncSession, Depends(get_db_session)] -async def require_database(request: Request) -> None: +async def require_database() -> None: """Readiness: Postgres отвечает на `SELECT 1` за отведённое время. Любая ошибка — 503: готовность не должна отвечать 500. Не логирует: healthcheck спрашивает каждые несколько секунд. """ - engine: AsyncEngine | None = getattr(request.app.state, "engine", None) - if engine is None: - raise exceptions.ServiceUnavailable try: await ping(engine, timeout=READINESS_DB_TIMEOUT_SECONDS) except Exception as e: diff --git a/src/infra/db/session.py b/src/infra/db/session.py new file mode 100644 index 00000000..23f69bed --- /dev/null +++ b/src/infra/db/session.py @@ -0,0 +1,15 @@ +"""Engine и фабрика сессий процесса API. + +Создаются при импорте по `settings.database`: настройки читаются один раз +на процесс, а соединения пул открывает лениво, при первом запросе. +Импортируют модуль только `src/main.py` (закрытие в lifespan) и +`src/api/dependencies.py`. `src/infra/db/__init__.py` и модели его не +импортируют, поэтому alembic и скрипты engine не создают. Другому +процессу со своим пулом (worker с лабы 5) — свой вызов `create_engine`. +""" + +from src.config import settings +from src.infra.db.engine import create_engine, create_session_factory + +engine = create_engine(settings.database) +session_factory = create_session_factory(engine) diff --git a/src/main.py b/src/main.py index cc128157..518521c3 100644 --- a/src/main.py +++ b/src/main.py @@ -8,7 +8,7 @@ from src.api import errors from src.api.middlewares import RequestContextMiddleware from src.api.routers import health_router, v1_router from src.config import settings -from src.infra.db import create_engine, create_session_factory +from src.infra.db.session import engine from src.infra.logger import AbstractLogger, get_logger from src.schemas.enums import RunModeEnum @@ -16,13 +16,10 @@ logger: AbstractLogger = get_logger().bind(module="startup") @asynccontextmanager -async def lifespan(app: FastAPI) -> AsyncIterator[None]: +async def lifespan(_: FastAPI) -> AsyncIterator[None]: database = settings.database - # engine не подключается при создании: без Postgres сервис стартует, - # а /health/ready отвечает 503 - engine = create_engine(database) - app.state.engine = engine - app.state.session_factory = create_session_factory(engine) + # engine подключается лениво: без Postgres сервис стартует, а + # /health/ready отвечает 503 if not database.password.get_secret_value(): logger.warning("Database password is empty") logger.info( diff --git a/student-tests/spec_coverage.py b/student-tests/spec_coverage.py index 34d03623..c876fa83 100644 --- a/student-tests/spec_coverage.py +++ b/student-tests/spec_coverage.py @@ -47,14 +47,36 @@ EXCLUDED: dict[Scenario, Exclusion] = { "traceback и тем же request_id", ), ("data-storage", "Прежний пользователь после рестарта"): Exclusion( - reason="нужен рестарт процесса, тесты сервер не трогают", - check="evidence/container/lifecycle.txt: после рестарта " - "прежний X-User-Id получает 401", + reason="нужен рестарт стенда, тесты сервер не трогают", + check="evidence/storage/restart.md: после scripts/restart.sh " + "прежний X-User-Id получает 200, данные и порядок те же", + ), + ("data-storage", "Сбой при добавлении участников"): Exclusion( + reason="нужен сбой БД посреди транзакции: штатным запросом его " + "не вызвать, участники проверяются до вставки", + check="одна транзакция и один commit в ChatService.create_chat; " + "автоматическая проверка отката — change failure-checks", + ), + ("data-storage", "БД остановлена"): Exclusion( + reason="нужно остановить Postgres, тесты стенд не трогают", + check="evidence/storage/db-unavailable.md; автоматическая " + "проверка — change failure-checks", + ), + ("data-storage", "БД вернулась"): Exclusion( + reason="нужно остановить и снова запустить Postgres", + check="evidence/storage/db-unavailable.md; автоматическая " + "проверка — change failure-checks", + ), + ("data-storage", "Соединения исчерпаны"): Exclusion( + reason="нужны пул из одного соединения и замороженный Postgres", + check="evidence/storage/pool-timeout.md; автоматическая " + "проверка — change failure-checks", ), ("health", "Хранилище не готово"): Exclusion( - reason="хранилище создаётся при старте, у запущенного сервера " - "оно готово всегда", - check="ветка 503 в src/api/routers/health.py, проверка чтением кода", + reason="нужно остановить Postgres, тесты стенд не трогают", + check="evidence/storage/db-unavailable.md: /health/ready — 503, " + "/health/live — 200; автоматическая проверка — change " + "failure-checks", ), ("identification", "Кнопка Authorize в Swagger"): Exclusion( reason="это интерфейс /docs в браузере", diff --git a/student-tests/test_data_storage.py b/student-tests/test_data_storage.py index ff4cbbc7..45634aab 100644 --- a/student-tests/test_data_storage.py +++ b/student-tests/test_data_storage.py @@ -1,11 +1,12 @@ """Спек `data-storage`. -Гонки — в `test_race.py`, рестарт — исключение в `spec_coverage.py`. +Гонки — в `test_race.py`; рестарт, отказы БД и пул — исключения в +`spec_coverage.py`. """ import pytest -from api_client import API, Api +from api_client import API, Actor, Api from contract import assert_ok @@ -15,3 +16,22 @@ def test_created_user_visible_at_once(api: Api) -> None: actor = api.register() resp = api.request("GET", f"{API}/users/me", actor=actor) assert assert_ok(resp, 200, "User") == actor.user + + +@pytest.mark.spec("data-storage", "Порядок участников") +def test_member_order_kept(api: Api, alice: Actor, bob: Actor) -> None: + # порядок [bob, alice] из запроса не совпадает с порядком регистрации; + # «в том числе после рестарта» — evidence/storage/restart.md + created = api.create_chat(bob, alice, title="Порядок участников") + expected = [bob.id, alice.id] + assert created["member_ids"] == expected + + resp = api.request("GET", f"{API}/chats/{created['id']}", actor=alice) + assert assert_ok(resp, 200, "Chat")["member_ids"] == expected + + listed = { + chat["id"]: chat["member_ids"] + for page in api.chat_pages(alice) + for chat in page["items"] + } + assert listed[created["id"]] == expected