feat: finish postgres-storage change

- keep engine and session factory in src/infra/db/session.py
- sync delta specs into openspec/specs, add db-migrations spec
- update rules, AGENTS.md and run skill for lab 2 storage
- fill REPORT.md for the storage part

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-01 16:20:49 +03:00
co-authored by Claude Opus 5.5
parent 90394ecdfb
commit 2d0a7c83e9
26 changed files with 947 additions and 357 deletions
+4 -3
View File
@@ -40,9 +40,10 @@ FastAPI, один процесс. Что обязан отдавать HTTP —
- Текущий пользователь — `Depends(get_current_user)` из - Текущий пользователь — `Depends(get_current_user)` из
`dependencies.py`, по Bearer-токену (`auth.md`). Сервис — `dependencies.py`, по Bearer-токену (`auth.md`). Сервис —
зависимость-фабрика (`Depends(get_chat_service)`), которая собирает зависимость-фабрика (`Depends(get_chat_service)`), которая собирает
его из `AsyncSession`. Сессию БД открывает отдельная зависимость из его из `AsyncSession`. Сессию БД открывает `get_db_session` из
`async_sessionmaker` в `request.app.state`: одна на запрос, закрывается глобального `session_factory` (`src/infra/db/session.py`): одна на
после ответа. Commit делает сервис (`service-layer.md`). запрос, закрывается после ответа, вся работа с БД ограничена сроком,
отказ БД — 503 (`infra.md`). Commit делает сервис (`service-layer.md`).
- Ошибки — доменные исключения из сервиса. `HTTPException` не бросать. - Ошибки — доменные исключения из сервиса. `HTTPException` не бросать.
Статус, `code` и заголовки ответа (`WWW-Authenticate` у 401) Статус, `code` и заголовки ответа (`WWW-Authenticate` у 401)
назначает одна таблица в `errors.py`. назначает одна таблица в `errors.py`.
+14 -8
View File
@@ -104,13 +104,18 @@ changes `load-bench-harness` (стенд) и `perf-bottleneck-fix`
## Измеренное состояние — commit ## Измеренное состояние — commit
Указание пользователя (2026-09-30). Перед замером или тестом, результат Замер или тест, результат которого идёт в отчёт, снимается с
которого идёт в отчёт, состояние кода коммитится; хеш попадает в шапку закоммиченного состояния кода; хеш попадает в шапку файла доказательства
файла доказательства и в `REPORT.md`. Пробное изменение `src`, которое и в `REPORT.md`. Любое число в отчёте должно воспроизводиться из
потом откатывается, — отдельный commit, откат — новый commit поверх названного commit (указание пользователя 2026-09-30).
(`git revert`), без переписывания истории. Любое число в отчёте должно
воспроизводиться из названного commit. Push и остальные операции git — Коммит делает не агент сам: перед замером он показывает изменения
по-прежнему только по просьбе. (`git status`, `git diff --stat`), предлагает сообщение коммита и ждёт
подтверждения пользователя (указание пользователя 2026-10-01).
Пробное изменение `src`, которое потом откатывается, — отдельный commit,
откат — новый commit поверх (`git revert`), без переписывания истории;
оба — по тому же порядку. Push и остальные операции git — только по
просьбе.
## Сравнение меток: `make bench_compare` ## Сравнение меток: `make bench_compare`
@@ -122,7 +127,8 @@ changes `load-bench-harness` (стенд) и `perf-bottleneck-fix`
REAPPLY=<commit отката>` снимает «до», коммитит доказательства, REAPPLY=<commit отката>` снимает «до», коммитит доказательства,
возвращает изменение и снимает «после». Команда сама делает два возвращает изменение и снимает «после». Команда сама делает два
коммита и отказывается стартовать на нечистом рабочем дереве: стенд коммита и отказывается стартовать на нечистом рабочем дереве: стенд
записал бы в паспорт `dirty: true`. записал бы в паспорт `dirty: true`. Поэтому `make bench_ab` агент
запускает только с согласия пользователя.
- Уровень шума берётся из сравнения двух меток одного и того же кода - Уровень шума берётся из сравнения двух меток одного и того же кода
приложения (A/A), параметр `AA`. Что код одинаков, проверяется по git приложения (A/A), параметр `AA`. Что код одинаков, проверяется по git
(`git diff <commit> <commit> -- src Dockerfile pyproject.toml (`git diff <commit> <commit> -- src Dockerfile pyproject.toml
+28 -12
View File
@@ -54,16 +54,16 @@ paths:
проверка идёт только через `interval`, и контейнер становится проверка идёт только через `interval`, и контейнер становится
`healthy` не раньше 10 с. Порт — `APP__PORT` из окружения, по `healthy` не раньше 10 с. Порт — `APP__PORT` из окружения, по
умолчанию 8080. Healthcheck живёт только в образе: он нужен и без умолчанию 8080. Healthcheck живёт только в образе: он нужен и без
compose (`make run_no_compose`, стенд `bench/`), а compose берёт его compose (стенд `bench/`), а compose берёт его из образа и не
из образа и не дублирует. дублирует.
- В образ не попадают `.env`, `config.toml`, секреты, `tests/`, - В образ не попадают `.env`, `config.toml`, секреты, `tests/`,
`student-tests/`, `contracts/`, `evidence/`, `.claude/`, `openspec/`, `student-tests/`, `contracts/`, `evidence/`, `.claude/`, `openspec/`,
`.venv/`. Отличие от bp_proxies: там `config.toml` копируется в образ, `.venv/`. Отличие от bp_proxies: там `config.toml` копируется в образ,
здесь нельзя. Чистый clone его не содержит, и сборка упала бы, а здесь нельзя. Чистый clone его не содержит, и сборка упала бы, а
`Dockerfile.example` (п. 6) запрещает класть конфиг и секреты в образ. `Dockerfile.example` (п. 6) запрещает класть конфиг и секреты в образ.
Конфигурация приходит на старте: `config.toml` монтируется Конфигурация приходит на старте: `config.toml` монтируется
read-only в `/app/config.toml`, переменные — `environment` compose read-only в `/app/config.toml`, переменные — `environment` compose.
или `docker run --env-file .env`. Это согласовано с преподавателем Это согласовано с преподавателем
2026-09-29 как выполнение README лабы 1, п. 3 и `Dockerfile.example`, 2026-09-29 как выполнение README лабы 1, п. 3 и `Dockerfile.example`,
п. 6 (AGENTS.md, «Согласования с преподавателем»). Что где лежит — п. 6 (AGENTS.md, «Согласования с преподавателем»). Что где лежит —
`settings.md`. `settings.md`.
@@ -99,11 +99,17 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t
## docker-compose.yml ## docker-compose.yml
- Сервис `api`: `build: .`; порты `"127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"` - Сервис `api`: `build: .`; порты `"127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"`
(снаружи / внутри, стенд учебный — только localhost); `environment`: (снаружи / внутри, стенд учебный — только localhost); `environment`
`APP__RUN_MODE=docker`, `APP__PORT=${APP__PORT:-8080}` и мосты — общий с `migrate` якорь `x-app-env`: `APP__RUN_MODE: docker`,
`SECTION__FIELD=${...}` (`settings.md`); healthcheck образа проверяет `APP__PORT`, `DATABASE__*` из переменных `POSTGRES_*`
(`settings.md`, «Консоль и docker»); healthcheck образа проверяет
`APP__PORT`; `stop_grace_period: 10s`; `restart: unless-stopped`. `APP__PORT`; `stop_grace_period: 10s`; `restart: unless-stopped`.
Имена переменных в `.env` — `settings.md`, «Имена в `.env`». Имена переменных в `.env` — `settings.md`, «Имена в `.env`».
- Литералов адреса и порта Postgres в compose нет: `POSTGRES_HOST`
становится алиасом сервиса в сети, `POSTGRES_PORT` — портом самого
сервера через `PGPORT` (его же берут `pg_isready` и `psql` в
контейнере). Литерал — только адрес публикации `127.0.0.1`: это
требование безопасности, а не параметр.
- `config.toml` — только длинной записью, иначе при отсутствии файла - `config.toml` — только длинной записью, иначе при отсутствии файла
Docker молча создаст на хосте каталог `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` — лишь список ролей, стенд — свой `compose.example.yaml` — лишь список ролей, стенд — свой
`docker-compose.yml` (compose находит его сам, как и `compose.yaml`). `docker-compose.yml` (compose находит его сам, как и `compose.yaml`).
- Образы зависимостей закреплены так же, как базовый: тег с патч-версией - Образы зависимостей закреплены так же, как базовый: тег с патч-версией
и digest индекса (`postgres:17.N-<вариант>@sha256:...`), не и digest индекса (`postgres:18.6-trixie@sha256:...`), не
`postgres:17` и не `latest`. `postgres:18` и не `latest`. Точка монтирования volume — из
- У каждой зависимости свой healthcheck (`pg_isready` у Postgres), API `Config.Volumes` образа: у Postgres 18 это `/var/lib/postgresql`, а не
ждёт `depends_on: condition: service_healthy`. Миграции — отдельный `/var/lib/postgresql/data`, как у 17.
одноразовый сервис, API ждёт его `service_completed_successfully`. - У каждой зависимости свой 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` и скрипты их не удаляют; - Данные — именованные volumes. `make down` и скрипты их не удаляют;
удаление учебных данных — отдельная явная команда в `REPORT.md`. удаление учебных данных — отдельная явная команда в `REPORT.md`.
- Postgres наружу — только `127.0.0.1:${POSTGRES_OUT_PORT}`, для - Postgres наружу — только `127.0.0.1:${POSTGRES_OUT_PORT}`, для
@@ -166,6 +178,10 @@ Hook для `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
- Перезапускает API и **все** используемые хранилища: Postgres и, если - Перезапускает API и **все** используемые хранилища: Postgres и, если
есть, Redis или Valkey. Volumes, схему и данные сохраняет: без есть, Redis или Valkey. Volumes, схему и данные сохраняет: без
`down -v`, `FLUSHALL`, повторного seed и изменения тестовых данных. `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`, - `#!/bin/sh`, `set -eu`, исполняемый бит в git (`chmod +x`,
`git update-index --chmod=+x`). Возвращает 0 только после действия, `git update-index --chmod=+x`). Возвращает 0 только после действия,
укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает. укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает.
+28 -15
View File
@@ -10,24 +10,35 @@ paths:
S3, брокер, телеметрия. Бизнес-правил (уникальность, доступ, валидация) S3, брокер, телеметрия. Бизнес-правил (уникальность, доступ, валидация)
здесь нет: они в сервисах, атомарные операции — в repo. здесь нет: они в сервисах, атомарные операции — в repo.
- Объект создаётся один раз в lifespan `src/main.py`, кладётся в - Клиент хранилища (engine Postgres, с «4» клиент Redis/Valkey) —
`app.state` и закрывается в shutdown lifespan. Соединения при импорте глобал своего модуля (`db/session.py`): создаётся при импорте по
модуля не открываются; исключение — ленивая настройка логгера. `settings` (настройки читаются один раз на процесс), соединения
- Сервисы получают объект через зависимость из `src/api/dependencies.py` открывает лениво, при первом запросе. Модуль не импортирует пакет
и не импортируют модульный глобал. `src/infra/<клиент>/` и модели, поэтому alembic и скрипты клиента не
- `db/`: `create_async_engine` и `async_sessionmaker` в lifespan, создают. Закрытие (`engine.dispose()`) — в lifespan `src/main.py`.
`engine.dispose()` в shutdown. Асинхронный драйвер (asyncpg или Почему не `app.state` — design change `postgres-storage`, решение 5.
psycopg 3) выбирает design change. Модели — `db/models/` - Глобал импортируют только `src/main.py` (закрытие) и
(`migrations.md`). `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, файлы и память процесса его не - Источник истины — PostgreSQL. SQLite, файлы и память процесса его не
заменяют (`README.md`, п. 2). Кэш не хранит ничего, чего нет в заменяют (`README.md`, п. 2). Кэш не хранит ничего, чего нет в
Postgres; исключение — сессии, если их хранилище выбрано в Redis или Postgres; исключение — сессии, если их хранилище выбрано в Redis или
Valkey (`auth.md`). Valkey (`auth.md`).
- Пул ограничен (`pool_size`, `max_overflow`, `pool_timeout`), у - Пул ограничен (`pool_size`, `max_overflow`, `pool_timeout`), у
подключения и запроса есть таймауты (connect, `statement_timeout` или подключения и запроса есть таймауты (`connect_timeout_seconds`,
`command_timeout` драйвера). Это требование уровня 4; значения — поля серверный `statement_timeout`, срок запроса `request_timeout_seconds`).
секции `[database]` (`settings.md`). Пул считается на один процесс Это требование уровня 4; значения — поля секции `[database]`
(`run-modes.md`). (`settings.md`). Пул считается на один процесс (`run-modes.md`).
- `command_timeout` asyncpg не использовать: на таймауте он отменяет
запрос через новое соединение и ждёт сервер без срока, и замёрзший
Postgres держит запрос до разморозки. Срок запроса ставит
`asyncio.timeout` в `get_db_session`, а мягкое закрытие соединения
ограничивает `BoundedCloseConnection` (`connection_class` asyncpg).
- `/health/ready` проверяет критичные зависимости через infra: - `/health/ready` проверяет критичные зависимости через infra:
`SELECT 1` в Postgres с коротким таймаутом, Redis или Valkey — если `SELECT 1` в Postgres с коротким таймаутом, Redis или Valkey — если
без него не работает обязательный путь (хранилище сессий). без него не работает обязательный путь (хранилище сессий).
@@ -35,8 +46,10 @@ S3, брокер, телеметрия. Бизнес-правил (уникал
`REPORT.md`. `REPORT.md`.
- Потеря соединения и таймауты драйвера на бизнес-запросе — 503 - Потеря соединения и таймауты драйвера на бизнес-запросе — 503
`unavailable` без деталей (`api-contract.md`), не 500 и не обход `unavailable` без деталей (`api-contract.md`), не 500 и не обход
аутентификации. В каком слое исключение драйвера становится аутентификации. Перевод — в `get_db_session`: `is_db_unavailable`
`ServiceUnavailable`, решает design change. решает, отказ ли это, сессия закрывается через `invalidate()`, в
журнал — `warning`. Остальные `DBAPIError` (ограничения, синтаксис) —
дефект, им положен 500.
- Redis или Valkey — одно из двух, на «4». Роль (сессии с TTL или - Redis или Valkey — одно из двух, на «4». Роль (сессии с TTL или
осмысленный кэш), источник истины, политика expiry и инвалидации — осмысленный кэш), источник истины, политика expiry и инвалидации —
в `REPORT.md`. Если это единственное хранилище сессий, нужен в `REPORT.md`. Если это единственное хранилище сессий, нужен
+12 -3
View File
@@ -48,6 +48,15 @@ paths:
редактировать: новая ревизия поверх. редактировать: новая ревизия поверх.
- Миграции применяются до старта API: в compose — отдельный - Миграции применяются до старта API: в compose — отдельный
одноразовый сервис на образе API (`docker.md`), API ждёт одноразовый сервис на образе API (`docker.md`), API ждёт
`service_completed_successfully`. Не `sh -c "alembic upgrade head && `service_completed_successfully`; в консоли — `make run_dev` через
python -m src"` (сервер перестаёт быть PID 1) и не из lifespan: с `make upgrade`. Не `sh -c "alembic upgrade head && python -m src"`
лабы 3 реплик несколько. (сервер перестаёт быть 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` дописываются руками.
+22 -24
View File
@@ -21,8 +21,8 @@ README слушал `0.0.0.0`) и литерал в `environment` compose; дл
|---|---|---| |---|---|---|
| Процесс | `uv run python -m src` на хосте | `python -m src` — PID 1 контейнера | | Процесс | `uv run python -m src` на хосте | `python -m src` — PID 1 контейнера |
| uvicorn | `127.0.0.1`, `reload=True` по `src/` | `0.0.0.0`, без reload | | 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` | | Порт | `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>`; миграции — `make upgrade` | всё в compose, зависимости по имени сервиса; миграции — отдельный сервис до старта API (`migrations.md`) | | Хранилища | 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`) | | Рестарт | reload процесса данные и сессии не теряет | рестарт API и хранилищ с volumes данные и сессии не теряет (`make test-persistence`) |
## Точка входа ## Точка входа
@@ -54,32 +54,30 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
bp_proxies: переменные наверху (`DC=docker compose`), заголовки bp_proxies: переменные наверху (`DC=docker compose`), заголовки
`# -------------------------`, свой `.PHONY` у каждой цели, имена в `# -------------------------`, свой `.PHONY` у каждой цели, имена в
snake_case. Apple Container не делать. snake_case. Apple Container не делать.
- Набор, перенесённый из лабы 1: - Запуск и общие цели:
- `run_dev` (`APP__RUN_MODE=console uv run python -m src`); - `run_dev: upgrade` — Postgres из compose и миграции, затем
- `run_no_compose: env_setup` — `docker build`, затем `APP__RUN_MODE=console uv run python -m src`;
`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_docker: env_setup` (недостающие `.env` и `config.toml` из - `run_docker: env_setup` (недостающие `.env` и `config.toml` из
шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`), шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`),
к нему `stop`, `down`, `logs` к нему `stop`, `down` (volume остаётся), `logs`
(`$(DC) logs -f --no-log-prefix api`: без префикса `api-1 |` (`$(DC) logs -f --no-log-prefix api`: без префикса `api-1 |`
каждая строка — JSON); каждая строка — JSON);
- `lint` (`ruff format .` + `ruff check --fix .`, дважды), - `lint` (`ruff format .` + `ruff check --fix .`, дважды),
`env_setup` (копирует шаблоны `.env` и `config.toml`), `env_setup` (шаблоны `.env` и `config.toml`, в новый `.env` —
`student_test`. случайный `POSTGRES_PASSWORD`), `student_test`.
Стенд лабы 2 — `run_docker`; в `REPORT.md` описывается он, а Оба способа запуска — `run_docker` и `run_dev` — описываются в
`run_no_compose` — как проверка образа. `REPORT.md`. Запуска одного контейнера без compose нет: API без
- Лабе 2 нужны ещё: `start_db` / `stop_db`, `start_redis` / Postgres не обслуживает запросы.
`stop_redis` (если выбран Redis или Valkey), `revision` - PostgreSQL и миграции: `start_db` (`$(DC) up -d --wait postgres`),
(интерактивный `read -p`), `upgrade`. Volume передаётся переменной `stop_db`, `upgrade: start_db` (`uv run alembic upgrade head`),
(`POSTGRES_VOLUME=$(DOCKER_POSTGRES_VOLUME)`), перед миграциями `revision: upgrade` (autogenerate, сообщение — `read -p`),
поднимается БД. `make down` volumes не удаляет; удаление учебных `wipe_data` (`$(DC) down -v --remove-orphans` только после ввода
данных — отдельная явная цель, описанная в `REPORT.md`. `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 ## Troubleshooting
@@ -89,8 +87,8 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
`APP_OUT_PORT` и `make test BASE_URL=http://localhost:<порт>`. `APP_OUT_PORT` и `make test BASE_URL=http://localhost:<порт>`.
- Разовая подмена внешнего порта для целей Makefile — только - Разовая подмена внешнего порта для целей Makefile — только
аргументом: `make run_docker APP_OUT_PORT=8090`. Внутренний аргументом: `make run_docker APP_OUT_PORT=8090`. Внутренний
`APP__PORT` — только в `.env`: в `run_no_compose` приложение берёт `APP__PORT` — только в `.env`: его читают и compose, и приложение в
его из `--env-file .env`, аргумент make сдвинул бы лишь `-p`. Префикс console, а аргумент make поменял бы одну переменную make. Префикс
`APP_OUT_PORT=8090 make ...` не сработает: `-include .env` перекроет `APP_OUT_PORT=8090 make ...` не сработает: `-include .env` перекроет
его, и в recipe (в том числе в `docker compose`) уйдёт значение из его, и в recipe (в том числе в `docker compose`) уйдёт значение из
`.env`. `.env`.
+25 -11
View File
@@ -20,9 +20,9 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда
- Приоритет (`settings_customise_sources`): окружение процесса → `.env` - Приоритет (`settings_customise_sources`): окружение процесса → `.env`
→ `config.toml` → дефолты. Отсутствующий файл пропускается. Без → `config.toml` → дефолты. Отсутствующий файл пропускается. Без
`.env` и `config.toml` `Settings` обязан загрузиться на дефолтах: так `.env` и `config.toml` `Settings` обязан загрузиться на дефолтах: так
работают импорт `src`, `make run_no_compose` и чистый clone. Стенд работают импорт `src`, alembic и чистый clone. Стенд лабы 2
лабы 2 запускается через compose и получает значения из `.env`; без запускается через compose и получает значения из `.env`; без Postgres
Postgres приложение стартует, но `/health/ready` отвечает 503. приложение стартует, но `/health/ready` отвечает 503.
- Все поля живут в секциях, откуда бы ни пришло значение: секцию задаёт - Все поля живут в секциях, откуда бы ни пришло значение: секцию задаёт
класс `Settings`, а не файл. Вложенные поля в env — через `__`, класс `Settings`, а не файл. Вложенные поля в env — через `__`,
регистр не важен: `DATABASE__PASSWORD` попадает в регистр не важен: `DATABASE__PASSWORD` попадает в
@@ -46,8 +46,8 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда
| Где | Что | В git | | Где | Что | В git |
|---|---|---| |---|---|---|
| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, лимиты трека 5, TTL, адреса зависимостей для console, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` | | `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` |
| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*`, пароли Redis / MinIO / брокера; мосты `SECTION__FIELD=${...}` для приложения | нет; шаблон `.env.example` | | `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*` (адрес, порты, учётные данные), пароли Redis / MinIO / брокера; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольный адрес Postgres | нет; шаблон `.env.example` |
| окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — | | окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — |
| `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50), пути: одинаковы на всех установках | да | | `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50), пути: одинаковы на всех установках | да |
@@ -67,10 +67,9 @@ Postgres, Redis, MinIO, брокера — нужны ещё и контейне
Если переменная касается самого приложения, в `.env` она пишется в Если переменная касается самого приложения, в `.env` она пишется в
формате настроек (`SECTION__FIELD`), даже когда её читают ещё compose и формате настроек (`SECTION__FIELD`), даже когда её читают ещё compose и
Makefile. Пример — внутренний порт `APP__PORT`: на нём слушает Makefile. Пример — внутренний порт `APP__PORT`: на нём слушает
приложение, его публикуют compose и `make run_no_compose`, на нём приложение, его публикует compose, на нём работает healthcheck. Compose
работает healthcheck. Compose читает `${APP__PORT}` напрямую и передаёт читает `${APP__PORT}` напрямую и передаёт в `environment` под тем же
в `environment` под тем же именем, а голый `docker run --env-file .env` именем.
отдаёт его приложению как есть.
Имя без секции — только у того, что приложение не читает: Имя без секции — только у того, что приложение не читает:
`APP_OUT_PORT` (порт на хосте), `POSTGRES_*` и другие переменные `APP_OUT_PORT` (порт на хосте), `POSTGRES_*` и другие переменные
@@ -99,8 +98,23 @@ compose полю секции:
контейнер. Сам `.env` в контейнер не передаётся. контейнер. Сам `.env` в контейнер не передаётся.
`docker run --env-file .env` раскрывать `${...}` не умеет и передаст `docker run --env-file .env` раскрывать `${...}` не умеет и передаст
строку буквально. Стенд лабы 2 запускается через compose, а строку буквально, поэтому стенд запускается только через compose.
`make run_no_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` устроено так же: переменная под этим Контрактное `SESSION_TTL_SECONDS` устроено так же: переменная под этим
именем в `.env` и мост `AUTH__SESSION_TTL_SECONDS=${SESSION_TTL_SECONDS}` именем в `.env` и мост `AUTH__SESSION_TTL_SECONDS=${SESSION_TTL_SECONDS}`
+10 -4
View File
@@ -39,11 +39,17 @@ paths:
требует, чтобы одновременно в полёте было ≥ 2 запросов, иначе гонка требует, чтобы одновременно в полёте было ≥ 2 запросов, иначе гонка
не доказана. Проверяются количество и уникальность `id`, а также не доказана. Проверяются количество и уникальность `id`, а также
отсутствие потерь при обходе всех страниц. отсутствие потерь при обходе всех страниц.
- Обычный прогон — `make test_isolated` (`student-tests/run_isolated.py`):
образ из рабочего дерева на временной базе `test_<db>`, публичный
smoke и весь набор против отдельного контейнера, затем уборка при
любом исходе. Его вывод — evidence набора против контейнера.
`make student_test` — против любого запущенного стенда (`BASE_URL`),
он оставляет данные в рабочей базе.
- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные - Проверкам, которым нужен особый стенд (TTL 2 с, остановленные
Postgres или Redis), обычный `make student_test` не подходит. Сами Postgres или Redis), обычный прогон не подходит. Сами тесты
тесты контейнеры не трогают: стенд готовит явный hook или отдельная контейнеры не трогают: стенд готовит явный hook или отдельная цель
цель Makefile, как `make test-persistence` в skeleton. Механизм Makefile, как `make test-persistence` в skeleton. Механизм выбирает
выбирает design change. change `failure-checks`.
- Пароли и токены тестов синтетические, не печатаются и не попадают в - Пароли и токены тестов синтетические, не печатаются и не попадают в
`evidence/` (`evidence/README.md`). `evidence/` (`evidence/README.md`).
- `tests/` — публичные проверки skeleton: не править, не ослаблять, - `tests/` — публичные проверки skeleton: не править, не ослаблять,
+74 -46
View File
@@ -1,54 +1,61 @@
--- ---
name: run-mtusi-messenger 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 мессенджера (пользователи, чаты, сообщения) — сервер на REST API мессенджера (пользователи, чаты, сообщения) — сервер на
FastAPI/uvicorn, состояние в памяти процесса. Агент управляет им через FastAPI/uvicorn, данные в PostgreSQL из compose. Агент управляет им через
`.claude/skills/run-mtusi-messenger/driver.py`: он поднимает свой `.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres и
экземпляр в фоне, гоняет сценарий по HTTP, публичный smoke и накатывает миграции (`make upgrade`), запускает свой экземпляр сервера
собственные тесты, шлёт одиночные запросы и останавливает сервер. в фоне, гоняет сценарий по HTTP, публичный smoke и собственные тесты,
Против контейнера (`make run_docker`) работают те же команды драйвера, шлёт одиночные запросы и останавливает сервер. Против контейнера
кроме `start`/`stop`. Только стандартная библиотека Python. (`make run_docker`) работают те же команды драйвера, кроме
`start`/`stop`. Только стандартная библиотека Python.
Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12, Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12,
Python 3.12 из `.python-version`, Docker Desktop 29.8. 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 ## Setup
```bash ```bash
uv sync --all-extras # venv с ruff и dev-группой (openapi-spec-validator) uv sync --all-extras # venv с ruff и dev-группой (pytest, httpx, валидатор)
make env_setup # .env и config.toml из шаблонов, существующие не трогает make env_setup # .env (случайный POSTGRES_PASSWORD) и config.toml, существующие не трогает
``` ```
Без `.env` и `config.toml` сервер тоже поднимается — на дефолтах Нужен запущенный Docker: Postgres живёт в compose. Без Postgres сервер
(порт 8080, `INFO`). стартует, но `/health/ready` отвечает 503; `driver.py start` сам делает
`make upgrade`.
## Run (agent path) ## Run (agent path)
```bash ```bash
D=.claude/skills/run-mtusi-messenger/driver.py 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 ```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 status # listeners: [pid reloader, pid worker], ready: True
python3 $D flow # ~35 проверок: регистрация, 409, /me, 401, чат, 5 сообщений, python3 $D flow # ~35 проверок: регистрация, 409, /me, 401, чат, 5 сообщений,
# пагинация limit=2 по курсору, чужой → 404, 400-е, X-Request-Id # пагинация limit=2 по курсору, чужой → 404, 400-е, X-Request-Id
python3 $D req POST /api/v1/users --data '{"username":"zoe_demo","display_name":"Зоя"}' python3 $D req POST /api/v1/users --data '{"username":"zoe_demo","display_name":"Зоя"}'
python3 $D req GET /api/v1/users/me --user <uuid из ответа выше> python3 $D req GET /api/v1/users/me --user <uuid из ответа выше>
python3 $D smoke # публичный tests/smoke.py против этого порта python3 $D smoke # публичный tests/smoke.py против этого порта
python3 $D student # make student_test BASE_URL=http://localhost:<port> — 79 тестов, <1 с python3 $D student # make student_test BASE_URL=http://localhost:<port> — 80 тестов, ~1,5 с
python3 $D stop python3 $D stop
``` ```
| команда | что делает | | команда | что делает |
|---|---| |---|---|
| `start` | `APP__RUN_MODE=console APP__PORT=<port> uv run python -m src` в своей группе процессов | | `start` | `make upgrade`, затем `APP__RUN_MODE=console APP__PORT=<port> uv run python -m src` в своей группе процессов |
| `status` | кто слушает порт, отвечает ли `/health/ready`; код 1, если никого | | `status` | кто слушает порт, отвечает ли `/health/ready`; код 1, если никого |
| `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat | | `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat |
| `req METHOD PATH [--user UUID] [--data JSON]` | один запрос: статус, `x-request-id`, тело; код 2 при статусе ≥ 400 | | `req METHOD PATH [--user UUID] [--data JSON]` | один запрос: статус, `x-request-id`, тело; код 2 при статусе ≥ 400 |
@@ -66,17 +73,18 @@ python3 $D stop
## Run: контейнер (compose) ## Run: контейнер (compose)
Образ `mtusi-messenger:lab1`, compose-сервис `api`. Внешний порт — Образ `mtusi-messenger:lab2`, compose-сервисы `postgres`, `migrate`
аргументом make, чтобы не столкнуться с 8080: (одноразовые миграции) и `api`. Внешний порт — аргументом make, чтобы не
столкнуться с 8080:
```bash ```bash
make run_docker APP_OUT_PORT=18090 # build + up -d; healthy за ~2 с make run_docker APP_OUT_PORT=18090 # build + up -d: postgres → migrate → api
docker compose ps --format '{{.Name}} {{.Ports}} {{.Status}}' docker compose ps -a --format '{{.Name}} {{.Ports}} {{.Status}}'
python3 $D --port 18090 flow # те же проверки против контейнера python3 $D --port 18090 flow # те же проверки против контейнера
python3 $D --port 18090 smoke
docker compose logs --no-log-prefix api | tail -5 # JSON-строки, без -f docker compose logs --no-log-prefix api | tail -5 # JSON-строки, без -f
docker compose restart api # рестарт = пустое состояние: старые X-User-Id → 401 scripts/restart.sh # рестарт API и Postgres: данные и X-User-Id остаются
make down # остановить и удалить, ~0,5 с make down # удалить контейнеры, volume с данными остаётся
make wipe_data # удалить и данные: только после ввода yes
``` ```
`make run_docker` сам создаёт недостающие `.env` и `config.toml` `make run_docker` сам создаёт недостающие `.env` и `config.toml`
@@ -86,33 +94,42 @@ make down # остановить и удали
## Direct invocation (без HTTP) ## Direct invocation (без HTTP)
Для правок в `src/core/` сервисы вызываются поверх `MemoryStore`, сервер Для правок в `src/core/` сервисы вызываются поверх сессии БД, сервер не
не нужен. `APP__LOG_LEVEL=WARNING` убирает JSON-логи сервисов из вывода: нужен, но Postgres с миграциями нужен (`make upgrade`).
`APP__LOG_LEVEL=WARNING` убирает JSON-логи сервисов из вывода:
```bash ```bash
make upgrade
APP__LOG_LEVEL=WARNING uv run python - <<'EOF' APP__LOG_LEVEL=WARNING uv run python - <<'EOF'
import asyncio import asyncio
from src.infra.memory import MemoryStore import uuid
from src.core.services import UserService from src.core.services import UserService
from src.infra.db.session import engine, session_factory
async def main(): async def main():
users = UserService(store=MemoryStore()) async with session_factory() as db_session:
user = await users.register(username="alice", display_name="Alice") 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))) print(await users.identify(raw_user_id=str(user.id)))
await engine.dispose()
asyncio.run(main()) asyncio.run(main())
EOF EOF
``` ```
`ChatService` и `MessageService` создаются так же (`store=...`), все `ChatService` и `MessageService` создаются так же (`db_session=...`),
методы keyword-only. Ошибки — доменные исключения из `src.core.exceptions` все методы keyword-only, commit делает сам сервис. Ошибки — доменные
(базовый `DomainError`), не HTTP-коды: `identify(raw_user_id="not-a-uuid")` исключения из `src.core.exceptions` (базовый `DomainError`), не
бросает `Unidentified`. HTTP-коды: `identify(raw_user_id="not-a-uuid")` бросает `Unidentified`.
Созданное так остаётся в рабочей базе.
## Run (human path) ## Run (human path)
```bash ```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`. Блокирует терминал — агенту не подходит, используй `driver.py start`.
@@ -121,31 +138,38 @@ make run_dev # 127.0.0.1:8080, reload по src/; Ctrl-C
```bash ```bash
make check # офлайн-структура skeleton make check # офлайн-структура skeleton
make test_isolated # образ на временной базе: smoke + student-tests, уборка
python3 $D all # живой сервер + flow + smoke + student-tests python3 $D all # живой сервер + flow + smoke + student-tests
make lint # ruff; затрагивает и driver.py make lint # ruff; затрагивает и driver.py
``` ```
Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none`, Ожидаемо до `session-auth`: `PASS: offline skeleton structure...`,
`PASS: lab1 public API scenario...`, `79 passed`, `All checks passed!`. `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 ## Gotchas
- **На 8080 обычно уже работает `make run_dev` пользователя.** Поэтому - **На 8080 обычно уже работает `make run_dev` пользователя.** Поэтому
драйвер по умолчанию на 18080. `driver.py --port 8080 stop` чужой драйвер по умолчанию на 18080. `driver.py --port 8080 stop` чужой
сервер не убьёт (нет pid-файла → `left running`, код 1) — и не надо: сервер не убьёт (нет pid-файла → `left running`, код 1) — и не надо:
в его памяти данные пользователя. это процесс пользователя.
- **Правка любого файла в `src/` (хватает `touch`) перезапускает worker - **Экземпляр драйвера пишет в ту же рабочую базу**, что `make run_dev` и
и стирает всё состояние** — в логе `WatchFiles detected changes ... `make run_docker`: тестовые пользователи и чаты там остаются. Чистый
Reloading...`. Задевает и `make run_dev` на 8080. Старые `X-User-Id` прогон — `make test_isolated` (временная база `test_<db>`), чистый
после этого дают 401. После правки кода: `flow` заново, а не `req` со стенд — `make wipe_data`.
старыми id. - **Правка файла в `src/` перезапускает worker** (`WatchFiles detected
changes ... Reloading...`), задевает и `make run_dev` на 8080. Данные
в Postgres остаются, прежние `X-User-Id` работают.
- **`lsof` на порт показывает два PID** — reloader и worker делят один - **`lsof` на порт показывает два PID** — reloader и worker делят один
сокет. Убивать по `lsof -t | xargs kill` бессмысленно: reloader сокет. Убивать по `lsof -t | xargs kill` бессмысленно: reloader
поднимет worker снова. Драйвер шлёт SIGTERM группе процессов; SIGTERM поднимет worker снова. Драйвер шлёт SIGTERM группе процессов; SIGTERM
на обёртку `uv run` тоже гасит всё дерево. на обёртку `uv run` тоже гасит всё дерево.
- **`uv sync` без `--all-extras` удалит ruff из `.venv`** (`Would - **`uv run` и `uv sync` без `--all-extras` удаляют ruff из `.venv`**
uninstall ruff`): ruff в extra `dev`, а `make lint` и PyCharm им (`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 в - **`make lint` форматирует и `.claude/skills/`** — ruff в
`pyproject.toml` исключает только `tests` и `scripts`. Драйвер написан `pyproject.toml` исключает только `tests` и `scripts`. Драйвер написан
под 79 колонок и COM812; при правке проверять под 79 колонок и COM812; при правке проверять
@@ -168,6 +192,10 @@ make lint # ruff; затрагивает и dr
порту, который поднимал не драйвер. Свой экземпляр гасить `stop` на его порту, который поднимал не драйвер. Свой экземпляр гасить `stop` на его
порту; чужой не трогать. Чей он — `lsof -nP -iTCP:8080 -sTCP:LISTEN`, порту; чужой не трогать. Чей он — `lsof -nP -iTCP:8080 -sTCP:LISTEN`,
затем `ps -o pid,ppid,etime,command -p <pid>`. затем `ps -o pid,ppid,etime,command -p <pid>`.
- **`req GET /api/v1/users/me --user <id>` вдруг даёт 401, хотя минуту - **`make upgrade failed` в `start`** — не запущен Docker или занят порт
назад было 200** — сервер перезагрузился после правки в `src/` и Postgres `POSTGRES_OUT_PORT` (5433): `docker ps`, `lsof -nP
потерял пользователей (см. Gotchas). -iTCP:5433 -sTCP:LISTEN`.
- **`/health/ready` отвечает 503, `/health/live` — 200** — Postgres
недоступен: `docker compose ps postgres`, `make start_db`. Запросы к
API в это время получают 503 `unavailable`, после возврата Postgres
проходят без рестарта сервера.
+17 -3
View File
@@ -6,7 +6,8 @@
python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] <cmd> python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] <cmd>
Команды: Команды:
start поднять `python -m src` в фоне (console, reload) и дождаться start `make upgrade` (Postgres из compose и миграции), затем поднять
`python -m src` в фоне (console, reload) и дождаться
/health/ready; лог и pid — /tmp/mtusi-api-<port>.{log,pid} /health/ready; лог и pid — /tmp/mtusi-api-<port>.{log,pid}
status кто слушает порт и что отвечает /health/ready status кто слушает порт и что отвечает /health/ready
flow сквозной сценарий по HTTP с проверками; код выхода 1 при провале flow сквозной сценарий по HTTP с проверками; код выхода 1 при провале
@@ -18,8 +19,9 @@
all start → flow → smoke → student (если есть student-tests/) → stop all start → flow → smoke → student (если есть student-tests/) → stop
Порт по умолчанию 18080, а не 8080: на 8080 обычно висит `make run_dev` Порт по умолчанию 18080, а не 8080: на 8080 обычно висит `make run_dev`
пользователя, и его состояние в памяти трогать не надо. flow, req, smoke пользователя, и его процесс трогать не надо. Экземпляр драйвера пишет в
и student работают с любым сервером на порту, в том числе с контейнером ту же рабочую базу Postgres, что и `make run_dev`. flow, req, smoke и
student работают с любым сервером на порту, в том числе с контейнером
(`make run_docker APP_OUT_PORT=<port>`). (`make run_docker APP_OUT_PORT=<port>`).
""" """
@@ -117,6 +119,18 @@ def cmd_start(port: int) -> int:
return 0 return 0
print(f"port {port} is busy:", listener_pids(port)) print(f"port {port} is busy:", listener_pids(port))
return 1 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)} env = os.environ | {"APP__RUN_MODE": "console", "APP__PORT": str(port)}
with log_path.open("wb") as log: with log_path.open("wb") as log:
proc = subprocess.Popen( proc = subprocess.Popen(
+44 -36
View File
@@ -4,8 +4,8 @@ REST API мессенджера (пользователи, чаты, истор
переносится через все семь лабораторных курса и на каждой обрастает переносится через все семь лабораторных курса и на каждой обрастает
инфраструктурой. Текущая работа — **лаба 2** (`lab.json`): PostgreSQL инфраструктурой. Текущая работа — **лаба 2** (`lab.json`): PostgreSQL
как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или
Valkey. Код перенесён из лабы 1 и пока работает in-memory в одном Valkey. Код перенесён из лабы 1, переход на lab2 идёт через changes
процессе; переход на lab2 идёт через changes OpenSpec. Стек: Python OpenSpec (раздел «Переходное состояние»). Стек: Python
3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в
stdout). stdout).
@@ -26,9 +26,10 @@ stdout).
Ответ преподавателя записать в «Согласования с преподавателем». Ответ преподавателя записать в «Согласования с преподавателем».
- Git не трогать без явной просьбы: никаких commit, push, checkout, - Git не трогать без явной просьбы: никаких commit, push, checkout,
reset, stash. Смотреть можно (`git status`, `git diff`, `git log`). reset, stash. Смотреть можно (`git status`, `git diff`, `git log`).
Исключение — замеры: состояние кода, которое меряется или тестируется Замер или evidence для отчёта снимается с закоммиченного кода, но
для отчёта, коммитится перед замером, в том числе пробное изменение и коммит — только после подтверждения пользователя: показать изменения,
его откат (`.claude/rules/bench.md`, «Измеренное состояние — commit»). предложить сообщение, ждать ок (`.claude/rules/bench.md`, «Измеренное
состояние — commit»).
- Перед завершением задачи с кодом — `make lint`. Правки API проверять на - Перед завершением задачи с кодом — `make lint`. Правки API проверять на
запущенном сервере (`make run_dev` или контейнер, затем `make test` и запущенном сервере (`make run_dev` или контейнер, затем `make test` и
`make student_test`), а не «на глаз». `make student_test`), а не «на глаз».
@@ -77,22 +78,23 @@ stdout).
## Переходное состояние ## Переходное состояние
Код перенесён из лабы 1 (commit `7b775a2`) и ещё не переведён на Код перенесён из лабы 1 (commit `7b775a2`), хранилище уже переведено
лабу 2. Этот файл и `.claude/rules/` описывают целевое состояние на PostgreSQL (change `postgres-storage`). Этот файл и `.claude/rules/`
лабы 2, поэтому код с ними пока расходится: описывают целевое состояние лабы 2, поэтому в остальном код с ними пока
расходится:
- хранилище — `MemoryStore` (`src/infra/memory.py`), `get_current_user` - `get_current_user` читает `X-User-Id`, регистрации с паролем, входа и
читает `X-User-Id`, регистрации с паролем, входа и logout нет. logout нет — change `session-auth`. До него публичный smoke лабы 2 не
Публичный smoke лабы 2 не проходит; проходит, а `test_security_scheme_in_openapi` падает: он сверяет
схему `devUser` с контрактом lab2, где её нет. `make test_isolated`
поэтому ещё не зелёный;
- `student-tests/` идентифицируются `X-User-Id`, `bench/` поднимает - `student-tests/` идентифицируются `X-User-Id`, `bench/` поднимает
стенд без Postgres, `inproc.py` работает на `MemoryStore` стенд без Postgres, `inproc.py` ссылается на удалённый `MemoryStore`
(`bench.md`); (`bench.md`);
- `openspec/specs/` описывают поведение лабы 1 (`identification`, - `openspec/specs/` `identification` и `users` описывают поведение
`data-storage`, `users`), скилл `run-mtusi-messenger` — стенд лабы 1; лабы 1;
- в `docker-compose.yml` только сервис `api`; `migrations/`, - `REPORT.md` заполнен только по хранению.
`scripts/restart.sh` и `REPORT.md` не готовы.
Код на `MemoryStore` не расширять: новое сразу пишется под Postgres.
Правила лабы 1 — `git show 7b775a2:.claude/rules/<файл>`. Закрытый Правила лабы 1 — `git show 7b775a2:.claude/rules/<файл>`. Закрытый
пункт убрать отсюда, закрытый переход — удалить раздел. пункт убрать отсюда, закрытый переход — удалить раздел.
@@ -236,13 +238,17 @@ stdout).
| `make test [BASE_URL=...]` | публичный smoke против запущенного сервера | | `make test [BASE_URL=...]` | публичный smoke против запущенного сервера |
| `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` | | `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` |
| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (`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 lint` | `ruff format` + `ruff check --fix`, дважды: так нужно из-за COM812; `tests/` и `scripts/` skeleton исключены в `[tool.ruff]` |
| `make env_setup` | `.env.example` → `.env`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает | | `make env_setup` | `.env.example` → `.env` со случайным `POSTGRES_PASSWORD`, `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`: postgres → migrate → api; `config.toml` монтируется read-only |
| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: стенд лабы 2; `config.toml` монтируется read-only | | `make stop` / `make down` | остановить / удалить контейнеры compose; volume с данными остаётся |
| `make stop` / `make down` | остановить / удалить контейнеры compose | | `make logs` | журнал API, каждая строка — JSON (`--no-log-prefix`) |
| `make logs` | журнал сервиса compose, каждая строка — 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_<db>`: сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test`, уборка при любом исходе (`student-tests.md`) |
| `make student_test [BASE_URL=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера; сервер недоступен — код 2 и одна строка с адресом | | `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 [BENCH_LABEL=...]` | полная матрица (~18 мин на лабе 1) на своём стенде `mtusi-bench-*` без портов хоста; результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста. Цели `bench*` под Postgres ещё не доработаны (`.claude/rules/bench.md`) |
| `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт | | `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт |
@@ -259,8 +265,7 @@ stdout).
## Карта кода ## Карта кода
Файлы домена называются одинаково во всех слоях (`user`, `chat`, Файлы домена называются одинаково во всех слоях (`user`, `chat`,
`message`, `session` и т.д.). Помеченное «(лаба 2)» появится с `message`, `session` и т.д.).
переходом на Postgres, «(лаба 1)» с ним уйдёт.
``` ```
src/ src/
@@ -280,8 +285,10 @@ src/
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py
infra/ infra/
logger.py # structlog, get_logger(), contextvar-ы request_id / user_id logger.py # structlog, get_logger(), contextvar-ы request_id / user_id
memory.py # (лаба 1) MemoryStore — dict-ы и индексы в памяти процесса db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping
db/ # (лаба 2) engine, async_sessionmaker, models/ db/session.py # глобалы engine и session_factory процесса API
db/errors.py # is_db_unavailable: какие ошибки драйвера — 503
db/models/ # модели SQLAlchemy (Base с created_at и to_dict)
schemas/ schemas/
dataclasses/<domain>.py # DTO между repo → service → api dataclasses/<domain>.py # DTO между repo → service → api
enums/<domain>.py # StrEnum доменов, RunModeEnum enums/<domain>.py # StrEnum доменов, RunModeEnum
@@ -296,21 +303,23 @@ student-tests/ # black-box тесты по HTTP (уровень 4)
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия
test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4 test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4
test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
run_isolated.py # make test_isolated: образ на временной базе test_<db> (stdlib)
bench/ # нагрузочный стенд из лабы 1 (под Postgres не доработан): make bench / make bench_quick bench/ # нагрузочный стенд из лабы 1 (под Postgres не доработан): make bench / make bench_quick
run.py # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json run.py # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json
k6/ # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы k6/ # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы
inproc.py # make bench_inproc: разложение времени запроса внутри процесса, сверка формата времени inproc.py # make bench_inproc: разложение времени запроса внутри процесса, сверка формата времени
compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд 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 infra/ # конфигурации сервисов стенда (Postgres, Redis/Valkey); README.md — skeleton
scripts/restart.sh # (лаба 2) restart hook для make test-persistence, по restart.example.sh scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh
Dockerfile # builder (uv sync --locked) → runtime: .venv + src, UID 10001, healthcheck Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck
docker-compose.yml # сервис api: порты из .env, config.toml read-only; (лаба 2) postgres, миграции, volumes docker-compose.yml # postgres, migrate, api; адреса и порты из .env, volume postgres_data
.dockerignore .dockerignore
config_example.toml, .env.example config_example.toml, .env.example
evidence/container/ # выводы проверок контейнера для REPORT.md evidence/storage/ # отказы БД, пул, рестарт, порты Postgres
evidence/tests/ # вывод make student_test для REPORT.md evidence/migrations/ # миграции с нуля и повторно
evidence/tests/ # выводы make test_isolated и make student_test для REPORT.md
evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6 evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6
evidence/profile/<метка>.txt # результаты make bench_inproc evidence/profile/<метка>.txt # результаты make bench_inproc
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
@@ -321,9 +330,8 @@ KNOWN_ISSUES.md # найденные попутно дефекты,
- Поток однонаправленный. Роутер (зависимости, модели API) → сервис - Поток однонаправленный. Роутер (зависимости, модели API) → сервис
(логика, проверки доступа, id и время, логи) → repo (одна атомарная (логика, проверки доступа, id и время, логи) → repo (одна атомарная
операция над хранилищем, отдаёт DTO) → хранилище из `src/infra/` операция над хранилищем, отдаёт DTO) → PostgreSQL через
(лаба 1 — `MemoryStore`, лаба 2+ — `AsyncSession`). Подробности — в `AsyncSession` (`src/infra/db/`). Подробности — в правилах слоёв.
правилах слоёв.
- Отличия от bp_proxies. Из `core/` вынесены инфраструктура - Отличия от bp_proxies. Из `core/` вынесены инфраструктура
(`src/infra/`: логгер, хранилища, клиенты), утилиты (`src/utils/`), (`src/infra/`: логгер, хранилища, клиенты), утилиты (`src/utils/`),
настройки (`src/config/` вместо `src/data/`) и HTTP-модели настройки (`src/config/` вместо `src/data/`) и HTTP-модели
+211 -14
View File
@@ -1,37 +1,234 @@
# Отчёт — лабораторная 2 # Отчёт — лабораторная 2
- Автор, группа: TODO - Автор, группа: Сафронов Роман Николаевич, БВТ2301
- Целевая оценка; выбранный трек 5, если нужен: TODO - Целевая оценка 5; выбранный трек 5: 2 (план запроса и восстановление)
- Commit/PR: TODO после публикации - 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 ## Запуск из чистого 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 <fork> && 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 | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO | | Публичный smoke | `make test`, `make test_isolated` | TODO: до `session-auth` падает на регистрации с `password` | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO | | PostgreSQL содержит пользователей, чаты, участников и сообщения; PK/FK, уникальный `username` | `\d` в `psql`, `alembic check` после миграций | 4 таблицы, ограничения и индексы по таблице выше; модели совпадают со схемой | `evidence/migrations/from-zero-and-rerun.md`, `migrations/versions/` |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | | Миграции с нуля и повторно без дублирования | `make wipe_data`, `make run_docker`, `docker compose run --rm migrate` | `migrate` завершился с кодом 0 до старта API; повтор — no-op, число строк не изменилось | `evidence/migrations/from-zero-and-rerun.md` |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO | | Данные переживают рестарт 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 |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. | 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/`.
+18 -2
View File
@@ -153,7 +153,23 @@ created_at, id`, `LIMIT limit + 1`. `uuid` Postgres сравнивает
### 5. Engine, пул и таймауты ### 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]`, значения по умолчанию: Параметры — секция `[database]`, значения по умолчанию:
| Параметр | По умолчанию | Зачем | | Параметр | По умолчанию | Зачем |
@@ -210,7 +226,7 @@ created_at, id`, `LIMIT limit + 1`. `uuid` Postgres сравнивает
asyncpg обрывает соединение. Отсюда «6 + 2 с» в таблице. asyncpg обрывает соединение. Отсюда «6 + 2 с» в таблице.
`/health/ready` не ходит через эту зависимость: отдельная проверка `/health/ready` не ходит через эту зависимость: отдельная проверка
`SELECT 1` с таймаутом через engine из `app.state`. `SELECT 1` с таймаутом через глобальный engine.
*Альтернативы:* обработчик исключений SQLAlchemy в `errors.py` — *Альтернативы:* обработчик исключений SQLAlchemy в `errors.py` —
отвергнут, `errors.py` не логирует (`logging.md`), а потеря БД в логе отвергнут, `errors.py` не логирует (`logging.md`), а потеря БД в логе
+31 -28
View File
@@ -88,7 +88,8 @@ commit»).
одна транзакция (решение 4); удалить `MemoryStore`, `get_store` и одна транзакция (решение 4); удалить `MemoryStore`, `get_store` и
`src/infra/memory.py`. Проверка: `grep -rn MemoryStore src` пусто, `src/infra/memory.py`. Проверка: `grep -rn MemoryStore src` пусто,
`make lint` чистый. `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`, фабрики сервисов; `dependencies.py`: `get_db_session`, фабрики сервисов;
`get_current_user` по-прежнему по `X-User-Id`. Проверка: `make `get_current_user` по-прежнему по `X-User-Id`. Проверка: `make
run_dev` поднимается до `/health/ready` 200; по SIGTERM в журнале run_dev` поднимается до `/health/ready` 200; по SIGTERM в журнале
@@ -101,59 +102,59 @@ commit»).
(`docker compose pause postgres`); записать исключения из traceback (`docker compose pause postgres`); записать исключения из traceback
для отказа в соединении, клиентского таймаута и таймаута пула. для отказа в соединении, клиентского таймаута и таймаута пула.
Проверка: список внесён в решение 6 `design.md`. Проверка: список внесён в решение 6 `design.md`.
- [ ] 5.2 Перехват в `get_db_session` (решение 6): откат, `warning`, - [x] 5.2 Перехват в `get_db_session` (решение 6): откат, `warning`,
`ServiceUnavailable`. Проверка: сценарии «БД остановлена» и «БД `ServiceUnavailable`. Проверка: сценарии «БД остановлена» и «БД
вернулась» (`data-storage`) — 503 `unavailable` без деталей, после вернулась» (`data-storage`) — 503 `unavailable` без деталей, после
`docker compose start postgres` запросы проходят без рестарта API; `docker compose start postgres` запросы проходят без рестарта API;
вывод в `evidence/storage/db-unavailable.txt`. вывод в `evidence/storage/db-unavailable.md`.
- [ ] 5.3 `/health/ready`: `SELECT 1` с таймаутом через engine. - [x] 5.3 `/health/ready`: `SELECT 1` с таймаутом через engine.
Проверка: при остановленном Postgres `/health/ready` — 503 не позже Проверка: при остановленном Postgres `/health/ready` — 503 не позже
таймаута, `/health/live` — 200. таймаута, `/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`, `DATABASE__MAX_OVERFLOW=0`, `DATABASE__POOL_TIMEOUT_SECONDS=1`,
Postgres на паузе, два одновременных запроса. Проверка: второй Postgres на паузе, два одновременных запроса. Проверка: второй
получает 503 примерно через 1 с, первый — 503 после получает 503 примерно через 1 с, первый — 503 после
`request_timeout_seconds` и закрытия соединения (6 + 2 с); вывод в `request_timeout_seconds` и закрытия соединения (6 + 2 с); вывод в
`evidence/storage/pool-timeout.txt`. `evidence/storage/pool-timeout.md`.
## 6. Рестарт стенда ## 6. Рестарт стенда
- [ ] 6.1 `scripts/restart.sh` по решению 10, исполняемый бит в git. - [x] 6.1 `scripts/restart.sh` по решению 10, исполняемый бит в git.
Проверка: `git ls-files -s scripts/restart.sh` — режим `100755`; Проверка: `git ls-files -s scripts/restart.sh` — режим `100755`;
скрипт укладывается в 90 с; по журналу записано, прогоняет ли `up` скрипт укладывается в 90 с; по журналу записано, прогоняет ли `up`
сервис `migrate` заново. сервис `migrate` заново.
- [ ] 6.2 Сценарий «Рестарт hook-ом» (`container-run`) и «Прежний - [x] 6.2 Сценарий «Рестарт hook-ом» (`container-run`) и «Прежний
пользователь после рестарта» (`data-storage`): пользователь, чат с пользователь после рестарта» (`data-storage`): пользователь, чат с
`member_ids` в порядке `[bob, alice]`, сообщения; `StartedAt` до и `member_ids` в порядке `[bob, alice]`, сообщения; `StartedAt` до и
после `scripts/restart.sh`. Проверка: после рестарта тот же после `scripts/restart.sh`. Проверка: после рестарта тот же
`X-User-Id` получает 200, история и порядок участников прежние; `X-User-Id` получает 200, история и порядок участников прежние;
вывод в `evidence/storage/restart.txt`. вывод в `evidence/storage/restart.md`.
## 7. Проверки стенда ## 7. Проверки стенда
- [ ] 7.1 Сценарий «Консоль и контейнер» (`student-tests`): `make - [x] 7.1 Сценарий «Консоль и контейнер» (`student-tests`): `make
student_test` против `make run_dev` и против `make run_docker`. student_test` против `make run_dev` и против `make run_docker`.
Проверка: в обоих прогонах прошли все тесты, кроме Проверка: в обоих прогонах прошли все тесты, кроме
`test_security_scheme_in_openapi` (переход контракта, design, Goals). `test_security_scheme_in_openapi` (переход контракта, design, Goals).
Evidence набора против контейнера снимает `session-auth`. Evidence набора против контейнера снимает `session-auth`.
- [ ] 7.2 Миграции с нуля и повторно (`db-migrations`): `make - [x] 7.2 Миграции с нуля и повторно (`db-migrations`): `make
wipe_data`, `make run_docker`, журнал `migrate`; затем повторный wipe_data`, `make run_docker`, журнал `migrate`; затем повторный
прогон миграций при данных в базе. Проверка: `migrate` завершился прогон миграций при данных в базе. Проверка: `migrate` завершился
с кодом 0 раньше старта API; число строк во всех таблицах до и после с кодом 0 раньше старта API; число строк во всех таблицах до и после
повтора одинаково; вывод в `evidence/migrations/from-zero-and-rerun.txt`. повтора одинаково; вывод в `evidence/migrations/from-zero-and-rerun.md`.
- [ ] 7.3 Сценарий «Другой порт Postgres»: `POSTGRES_PORT=5544`, - [x] 7.3 Сценарий «Другой порт Postgres»: `POSTGRES_PORT=5544`,
`POSTGRES_OUT_PORT=5545` в `.env`, compose не правится. Проверка: `POSTGRES_OUT_PORT=5545` в `.env`, compose не правится. Проверка:
`make run_docker` доходит до `/health/ready` 200, `make run_dev` `make run_docker` доходит до `/health/ready` 200, `make run_dev`
подключается к `127.0.0.1:5545`; `.env` возвращён; вывод в подключается к `127.0.0.1:5545`; `.env` возвращён; вывод в
`evidence/storage/postgres-port.txt`. `evidence/storage/postgres-port.md`.
- [ ] 7.4 Сценарий «Консоль, затем docker» (`service-configuration`) и - [x] 7.4 Сценарий «Консоль, затем docker» (`service-configuration`) и
«down сохраняет данные» (`container-run`). Проверка: данные, «down сохраняет данные» (`container-run`). Проверка: данные,
созданные через `make run_dev`, видны после `make run_docker` и после созданные через `make run_dev`, видны после `make run_docker` и после
`make down` + `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`, а не `docker port` для API и Postgres стенда показывает `127.0.0.1`, а не
`0.0.0.0`. `0.0.0.0`.
- [ ] 7.6 Механика «Прогон на временной базе» (`student-tests`) при - [x] 7.6 Механика «Прогон на временной базе» (`student-tests`) при
запущенном рабочем стенде с данными: обычный прогон (до запущенном рабочем стенде с данными: обычный прогон (до
`session-auth` он заканчивается падением smoke — это сценарий `session-auth` он заканчивается падением smoke — это сценарий
«Упавшие тесты»); остановка тестового контейнера во время прогона; «Упавшие тесты»); остановка тестового контейнера во время прогона;
@@ -162,9 +163,9 @@ commit»).
тестового контейнера (`docker ps -a`) соответствуют сценарию; число тестового контейнера (`docker ps -a`) соответствуют сценарию; число
строк рабочей базы до и после одинаково, рабочий API отвечает; после строк рабочей базы до и после одинаково, рабочий API отвечает; после
разбора `KEEP_TEST_DB` база удалена руками; вывод в разбора `KEEP_TEST_DB` база удалена руками; вывод в
`evidence/tests/test-isolated-mechanics.txt`. Сценарий «Успешный `evidence/tests/test-isolated-mechanics.md`. Сценарий «Успешный
прогон» и evidence набора против контейнера — задача `session-auth`. прогон» и evidence набора против контейнера — задача `session-auth`.
- [ ] 7.7 Перенести дельты в основные спеки (`/opsx:sync`) и в том же - [x] 7.7 Перенести дельты в основные спеки (`/opsx:sync`) и в том же
шаге обновить `student-tests/spec_coverage.py`: тексты исключений шаге обновить `student-tests/spec_coverage.py`: тексты исключений
«Прежний пользователь после рестарта» и «Хранилище не готово», «Прежний пользователь после рестарта» и «Хранилище не готово»,
исключения для «Сбой при добавлении участников», «БД остановлена», исключения для «Сбой при добавлении участников», «БД остановлена»,
@@ -179,25 +180,27 @@ commit»).
## 8. Документы и инструменты ## 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` `run-modes.md` (плюс `test_isolated`), `docker.md`, `student-tests.md`
(обычный прогон и evidence — `make test_isolated`, против любого (обычный прогон и evidence — `make test_isolated`, против любого
стенда — `make student_test`). Проверка: `grep -n "POSTGRES_VOLUME\|решает стенда — `make student_test`). Проверка: `grep -n "POSTGRES_VOLUME\|решает
design change" .claude/rules` — только там, где решение ещё не design change" .claude/rules` — только там, где решение ещё не
принято (`membership-cache`); `grep -rn run_no_compose .claude` принято (`membership-cache`); `grep -rn run_no_compose .claude`
пусто. пусто.
- [ ] 8.2 `AGENTS.md`: «Переходное состояние» без закрытых пунктов и с - [x] 8.2 `AGENTS.md`: «Переходное состояние» без закрытых пунктов и с
известным падением `test_security_scheme_in_openapi` до известным падением `test_security_scheme_in_openapi` до
`session-auth`, `session-auth`,
карта кода, команды `start_db`, `stop_db`, `upgrade`, `revision`, карта кода, команды `start_db`, `stop_db`, `upgrade`, `revision`,
`wipe_data`, `test_isolated`, без `run_no_compose`. Проверка: каждая команда из `wipe_data`, `test_isolated`, без `run_no_compose`. Проверка: каждая команда из
таблицы есть в `Makefile` (`make -n <цель>`). таблицы есть в `Makefile` (`make -n <цель>`).
- [ ] 8.3 Скилл `run-mtusi-messenger`: `driver.py start` перед - [x] 8.3 Скилл `run-mtusi-messenger`: `driver.py start` перед
сервером выполняет `make start_db upgrade`; `SKILL.md` без «рестарт = сервером выполняет `make upgrade`; `SKILL.md` без «рестарт = пустое
пустое состояние» и `MemoryStore`. Проверка: `python3 состояние» и `MemoryStore`. Проверка: `python3
.claude/skills/run-mtusi-messenger/driver.py all` завершается с кодом .claude/skills/run-mtusi-messenger/driver.py all` — `start` сам
0. поднимает Postgres, `flow` без провалов, падают только smoke lab2 и
- [ ] 8.4 `REPORT.md`: запуск из чистого clone (`make run_docker`, `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 `make run_dev`, остановка, `make wipe_data`), проверки (`make
test_isolated`; `make student_test` против любого стенда); test_isolated`; `make student_test` против любого стенда);
архитектура — схема, транзакционные границы, архитектура — схема, транзакционные границы,
@@ -205,6 +208,6 @@ commit»).
часов, соответствие переменных `.env.example` skeleton; строки часов, соответствие переменных `.env.example` skeleton; строки
доказательств уровня «3» по хранению со ссылками на `evidence/`. доказательств уровня «3» по хранению со ссылками на `evidence/`.
Проверка: у каждой строки есть команда, наблюдение и путь к файлу. Проверка: у каждой строки есть команда, наблюдение и путь к файлу.
- [ ] 8.5 Финальная проверка: `make lint`, `make check`, - [x] 8.5 Финальная проверка: `make lint`, `make check`,
`openspec validate postgres-storage --strict`, `graphify update .`. `openspec validate postgres-storage --strict`, `graphify update .`.
Проверка: все команды без ошибок. Проверка: все команды без ошибок.
+13 -6
View File
@@ -19,7 +19,7 @@
#### Scenario: Свежий clone #### Scenario: Свежий clone
- **WHEN** в новом clone репозитория выполняется - **WHEN** в новом clone репозитория выполняется
`docker build -t mtusi-messenger:lab1 .` `docker build -t mtusi-messenger:lab2 .`
- **THEN** образ собирается без ошибок - **THEN** образ собирается без ошибок
#### Scenario: Устаревший lock #### Scenario: Устаревший lock
@@ -59,23 +59,30 @@ MUST NOT быть доступны этому пользователю на за
### Requirement: Состав образа ### Requirement: Состав образа
Образ SHALL содержать только то, что нужно для работы сервиса: Образ SHALL содержать только то, что нужно для работы сервиса и
интерпретатор, зависимости времени выполнения и исходники `src/`. В применения миграций: интерпретатор, зависимости времени выполнения,
образе MUST NOT быть `config.toml`, `.env`, публичных и собственных исходники `src/`, каталог миграций и конфигурацию инструмента миграций.
В образе MUST NOT быть `config.toml`, `.env`, публичных и собственных
тестов, контрактов, файлов `.claude` и `openspec`, а также инструментов тестов, контрактов, файлов `.claude` и `openspec`, а также инструментов
сборки: uv и компиляторов. сборки: uv и компиляторов.
#### Scenario: Нет конфигов и лишних каталогов #### Scenario: Нет конфигов и лишних каталогов
- **WHEN** в образе просматривается рабочий каталог приложения - **WHEN** в образе просматривается рабочий каталог приложения
- **THEN** в нём есть только исходники и окружение зависимостей, а - **THEN** в нём есть только исходники, миграции с их конфигурацией и
`config.toml` и `.env` отсутствуют окружение зависимостей, а `config.toml` и `.env` отсутствуют
#### Scenario: Нет uv в runtime #### Scenario: Нет uv в runtime
- **WHEN** в контейнере запрашивается `uv` - **WHEN** в контейнере запрашивается `uv`
- **THEN** команда не найдена - **THEN** команда не найдена
#### Scenario: Миграции из образа
- **WHEN** контейнер из этого образа запускается командой применения
миграций с настройками подключения к Postgres
- **THEN** миграции применяются без доступа к исходникам на хосте
### Requirement: Сервер — основной процесс контейнера ### Requirement: Сервер — основной процесс контейнера
Процессом с PID 1 SHALL быть сам сервер (`python -m src`), без Процессом с PID 1 SHALL быть сам сервер (`python -m src`), без
+80 -85
View File
@@ -2,120 +2,93 @@
## Purpose ## Purpose
Как контейнер сервиса запускается и настраивается: два способа запуска — Как стенд сервиса запускается и настраивается: compose с PostgreSQL,
голый `docker run` из README (`make run_no_compose`) и compose одноразовыми миграциями и API (`make run_docker`), публикация портов
(`make run_docker`), публикация портов, конфигурация на старте и только на localhost, конфигурация на старте, сохранность данных при
поведение состояния при рестарте контейнера. рестарте стенда и явное удаление учебных данных.
## Requirements ## 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 ### Requirement: Запуск через compose
`make run_docker` SHALL собирать образ и поднимать сервис `api` через `make run_docker` SHALL собирать образ и поднимать стенд через
`docker compose`. Перед этим он SHALL создавать недостающие `.env` и `docker compose`: PostgreSQL, одноразовый сервис миграций и API. API
`config.toml` из шаблонов (`make env_setup`) и MUST NOT перезаписывать SHALL стартовать после готовности PostgreSQL и успешных миграций.
существующие. `make stop` SHALL останавливать сервис, `make down` — Перед этим цель SHALL создавать недостающие `.env` и `config.toml` из
удалять контейнер, `make logs` — показывать журнал. шаблонов (`make env_setup`) и MUST NOT перезаписывать существующие.
`make stop` SHALL останавливать сервисы, `make down` — удалять
контейнеры, сохраняя volume, `make logs` — показывать журнал API.
#### Scenario: Штатный запуск #### Scenario: Штатный запуск
- **WHEN** в свежем clone выполнен `make run_docker` - **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** сервис отвечает на `http://localhost:8080/health/ready`, и - **THEN** сервис отвечает на `http://localhost:8080/health/ready`, и
`make test` проходит `make student_test` проходит
### Requirement: Порты из .env ### Requirement: Порты из .env
Оба способа запуска, `make run_no_compose` и `make run_docker`, SHALL Порты стенда и консольного запуска SHALL браться из одного `.env`:
брать порты из одного `.env`: - внутренний порт API — `APP__PORT`: параметр приложения `[app] port` в
- внутренний — `APP__PORT`: параметр приложения `[app] port` в формате формате настроек, на нём же работает healthcheck;
настроек, приложение читает его само, на нём же работает - внешний порт API — `APP_OUT_PORT`: порт на `127.0.0.1` хоста,
healthcheck; приложение его не читает;
- внешний — `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 записываться в формате настроек приложения в `.env` SHALL записываться в формате настроек
(`SECTION__FIELD`). Имя без секции допускается только для переменных, (`SECTION__FIELD`). Имя без секции допускается только для переменных,
которые приложение не читает. которые приложение не читает. Адрес и порт PostgreSQL MUST NOT быть
записаны в compose литералами.
#### Scenario: Другой внешний порт #### Scenario: Другой внешний порт
- **WHEN** в `.env` задано `APP_OUT_PORT=8090` - **WHEN** в `.env` задано `APP_OUT_PORT=8090`, и выполнен
- **THEN** при любом из двух способов API доступно на `localhost:8090`, `make run_docker`
а внутри контейнера сервис слушает `APP__PORT` - **THEN** API доступно на `localhost:8090`, а внутри контейнера
сервис слушает `APP__PORT`
#### Scenario: Другой внутренний порт #### Scenario: Другой внутренний порт
- **WHEN** в `.env` задано `APP__PORT=9090` - **WHEN** в `.env` задано `APP__PORT=9090`
- **THEN** при любом из двух способов сервис внутри контейнера слушает - **THEN** сервис внутри контейнера слушает 9090, контейнер становится
9090, контейнер становится `healthy`, а API доступно на `healthy`, а API доступно на `localhost:$APP_OUT_PORT`
`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 ### Requirement: Оба способа запуска описаны в REPORT.md
Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать оба Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два
способа: `make run_no_compose` (без compose, команды README) и способа запуска стенда: `make run_docker` (всё в compose) и
`make run_docker` (compose). Для каждого SHALL быть указаны подготовка `make run_dev` (Postgres в compose, сервис на хосте). Для каждого SHALL
(обе цели сами вызывают `make env_setup`), команды, которые выполняет быть указаны подготовка (`make env_setup`), команды, которые выполняет
цель Makefile, ожидание готовности, `make test` и остановка. цель Makefile, применение миграций, ожидание готовности, проверки и
остановка.
#### Scenario: Запуск по отчёту #### Scenario: Запуск по отчёту
- **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md` - **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md`
для любого из двух способов для любого из двух способов
- **THEN** `/health/ready` отвечает 200, а `make test` проходит - **THEN** `/health/ready` отвечает 200, а `make student_test` проходит
### Requirement: Публикация только на localhost ### Requirement: Публикация только на localhost
Порт сервиса SHALL публиковаться только на `127.0.0.1` хоста: в Порты API и PostgreSQL SHALL публиковаться в compose только на
README-команде, в `make run_no_compose` и в compose. Учебный стенд `127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не
MUST NOT быть доступен с других машин сети. переменной. Учебный стенд MUST NOT быть доступен с других машин сети.
#### Scenario: Адрес публикации #### Scenario: Адрес публикации
- **WHEN** для запущенного контейнера выполняется `docker port` - **WHEN** для запущенных контейнеров API и Postgres выполняется
- **THEN** порт опубликован на `127.0.0.1`, а не на `0.0.0.0` `docker port`
- **THEN** порты опубликованы на `127.0.0.1`, а не на `0.0.0.0`
### Requirement: Конфигурация на старте ### Requirement: Конфигурация на старте
@@ -144,17 +117,39 @@ compose, и приложению, SHALL передаваться через `env
- **THEN** запуск завершается ошибкой о несуществующем источнике - **THEN** запуск завершается ошибкой о несуществующем источнике
монтирования, и каталог `config.toml/` на хосте не появляется монтирования, и каталог `config.toml/` на хосте не появляется
### Requirement: Состояние теряется при рестарте контейнера ### Requirement: Данные переживают рестарт стенда
Перезапуск контейнера SHALL давать пустое состояние: у контейнера нет Данные PostgreSQL SHALL храниться в именованном volume. Скрипт
volume для данных. Это ожидаемое поведение лабы 1, его показывают на `scripts/restart.sh` SHALL перезапускать API и все используемые
защите. хранилища, сохраняя volume, схему и данные: без удаления volume,
очистки и повторного наполнения. Скрипт SHALL быть исполняемым,
завершаться с кодом 0 только после перезапуска, укладываться в 90 с и
MUST NOT печатать секреты.
#### Scenario: Жизненный цикл на защите #### Scenario: Рестарт hook-ом
- **WHEN** пользователь создан, отправил сообщение и прочитал его, после - **WHEN** пользователь создан, отправил сообщение, затем выполнен
чего контейнер перезапущен тем же образом `scripts/restart.sh`
- **THEN** запрос с прежним `X-User-Id` получает 401 - **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: Журнал контейнера ### Requirement: Журнал контейнера
+79 -17
View File
@@ -2,19 +2,19 @@
## Purpose ## Purpose
Где живёт состояние мессенджера на лабе 1 и какие гарантии оно даёт: Где живут данные мессенджера с лабы 2 и какие гарантии они дают:
память одного процесса, потеря при рестарте, защита от гонок при PostgreSQL как источник истины, сохранность после рестарта, целостность
параллельных запросах. и транзакции на стороне БД, поведение при недоступности БД и
ограниченные ресурсы подключения.
## Requirements ## Requirements
### Requirement: Состояние только в памяти одного процесса ### Requirement: Хранение в PostgreSQL
Пользователи, чаты и сообщения SHALL храниться только в памяти одного Пользователи, чаты, участники чатов и сообщения SHALL храниться в
процесса сервиса. Сервис MUST NOT использовать базы данных, Redis, PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные в
файлы состояния и внешние сервисы. Все запросы экземпляра SHALL памяти процесса, файлах или SQLite. Подтверждённая запись (ответ 201)
обслуживаться одним общим состоянием, без нескольких worker-процессов SHALL быть зафиксирована в БД до ответа и видна следующему чтению.
с независимой памятью.
#### Scenario: Созданное видно сразу #### Scenario: Созданное видно сразу
@@ -22,22 +22,25 @@
его `id` в `X-User-Id` его `id` в `X-User-Id`
- **THEN** пользователь найден - **THEN** пользователь найден
### Requirement: Потеря состояния при рестарте ### Requirement: Данные переживают рестарт
После перезапуска процесса состояние SHALL быть пустым. Это ожидаемое После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее
поведение лабы 1. подтверждённые пользователи, чаты, участники и сообщения SHALL быть
доступны в прежнем виде.
#### Scenario: Прежний пользователь после рестарта #### Scenario: Прежний пользователь после рестарта
- **WHEN** сервис перезапущен и клиент использует `X-User-Id`, - **WHEN** стенд перезапущен `scripts/restart.sh`, и клиент использует
созданный до рестарта `X-User-Id`, созданный до рестарта
- **THEN** ответ 401 - **THEN** ответ 200, а история чата этого пользователя содержит те же
сообщения в том же порядке
### Requirement: Параллельные запросы не повреждают состояние ### Requirement: Параллельные запросы не повреждают состояние
Параллельные запросы MUST NOT терять, дублировать или повреждать Параллельные запросы MUST NOT терять, дублировать или повреждать
записи. Проверки с последующей записью (уникальность `username`) записи. Уникальность `username` SHALL обеспечиваться ограничением БД,
SHALL выполняться атомарно. а не проверкой перед вставкой, поэтому одновременная регистрация
одного имени создаёт ровно одного пользователя.
#### Scenario: 100 сообщений от 10 клиентов #### Scenario: 100 сообщений от 10 клиентов
@@ -51,3 +54,62 @@ SHALL выполняться атомарно.
- **WHEN** несколько клиентов одновременно регистрируют одинаковый - **WHEN** несколько клиентов одновременно регистрируют одинаковый
`username` `username`
- **THEN** создан ровно один пользователь - **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` не позже этого
таймаута, а не ждёт бесконечно
+69
View File
@@ -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
+9 -6
View File
@@ -23,19 +23,22 @@ MUST NOT зависеть от состояния хранилища.
`GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`, `GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`,
когда сервис может безопасно обслуживать обязательные запросы, и 503 с когда сервис может безопасно обслуживать обязательные запросы, и 503 с
`code` `unavailable` в формате ошибки, когда не может. На лабе 1 `code` `unavailable` в формате ошибки, когда не может. На лабе 2
критичная зависимость одна — хранилище в памяти процесса, готовое после критичная зависимость — PostgreSQL: проверка SHALL выполнять запрос к
завершения запуска. Проверка MUST NOT требовать идентификации. нему с коротким таймаутом при каждом обращении. Проверка MUST NOT
требовать идентификации.
#### Scenario: Сервис запущен #### Scenario: Сервис запущен
- **WHEN** запуск сервиса завершён и клиент запрашивает `GET /health/ready` - **WHEN** запуск сервиса завершён, PostgreSQL доступен, и клиент
запрашивает `GET /health/ready`
- **THEN** ответ 200, тело `{"status": "ok"}` - **THEN** ответ 200, тело `{"status": "ok"}`
#### Scenario: Хранилище не готово #### Scenario: Хранилище не готово
- **WHEN** хранилище ещё не инициализировано - **WHEN** PostgreSQL недоступен
- **THEN** ответ 503 с `code` `unavailable` в формате ошибки - **THEN** ответ 503 с `code` `unavailable` в формате ошибки не позже
таймаута проверки, а `GET /health/live` при этом отвечает 200
### Requirement: Health вне версии API и без идентификации ### Requirement: Health вне версии API и без идентификации
@@ -82,3 +82,40 @@ SHALL слушать только `127.0.0.1` и перезапускаться
- **WHEN** в корне создан `config.toml` - **WHEN** в корне создан `config.toml`
- **THEN** `git status` его не показывает, а `config_example.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 и видят одни и
те же данные
+47
View File
@@ -160,3 +160,50 @@ SHALL проходить против сервера, запущенного н
- **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md` - **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md`
- **THEN** в ней есть команда, наблюдаемый результат и путь к файлу - **THEN** в ней есть команда, наблюдаемый результат и путь к файлу
вывода в `evidence/` вывода в `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_<db>`, ни
тестового контейнера после команды нет, число строк в таблицах
рабочей базы не изменилось, а рабочий API продолжает отвечать
#### Scenario: Упавшие тесты
- **WHEN** во время `make test_isolated` падает хотя бы один тест
- **THEN** код выхода ненулевой, журнал тестового контейнера выведен,
контейнер удалён, база `test_<db>` удалена
#### Scenario: Прерывание
- **WHEN** `make test_isolated` прерван Ctrl+C
- **THEN** тестовый контейнер остановлен и удалён, база `test_<db>`
удалена
#### Scenario: Хвост прошлого прогона
- **WHEN** тестовый контейнер или база `test_<db>` остались от прогона,
убитого без уборки
- **THEN** следующий `make test_isolated` удаляет их и начинает заново
#### Scenario: Сохранить базу для разбора
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
- **THEN** после прогона тестовый контейнер удалён, база `test_<db>`
остаётся, а команда печатает её имя
+5 -18
View File
@@ -5,18 +5,15 @@ from collections.abc import AsyncIterator
from dataclasses import dataclass from dataclasses import dataclass
from typing import Annotated from typing import Annotated
from fastapi import Depends, Query, Request, Security from fastapi import Depends, Query, Security
from fastapi.security import APIKeyHeader from fastapi.security import APIKeyHeader
from sqlalchemy.ext.asyncio import ( from sqlalchemy.ext.asyncio import AsyncSession
AsyncEngine,
AsyncSession,
async_sessionmaker,
)
from src.config import settings from src.config import settings
from src.core import exceptions from src.core import exceptions
from src.core.services import ChatService, MessageService, UserService from src.core.services import ChatService, MessageService, UserService
from src.infra.db import is_db_unavailable, ping 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.infra.logger import AbstractLogger, current_user_id, get_logger
from src.schemas import dataclasses from src.schemas import dataclasses
from src.utils.constants import ( from src.utils.constants import (
@@ -30,7 +27,7 @@ from src.utils.constants import (
logger: AbstractLogger = get_logger().bind(module="api_dependencies") 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 делает сервис. """Одна сессия БД на запрос; commit делает сервис.
Незакоммиченное при выходе откатывается. Вся работа запроса с БД Незакоммиченное при выходе откатывается. Вся работа запроса с БД
@@ -39,13 +36,6 @@ async def get_db_session(request: Request) -> AsyncIterator[AsyncSession]:
503 `unavailable`, а соединение не возвращается в пул: его состояние 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: async with session_factory() as db_session:
try: try:
async with asyncio.timeout( async with asyncio.timeout(
@@ -67,15 +57,12 @@ async def get_db_session(request: Request) -> AsyncIterator[AsyncSession]:
DbSessionDep = Annotated[AsyncSession, Depends(get_db_session)] DbSessionDep = Annotated[AsyncSession, Depends(get_db_session)]
async def require_database(request: Request) -> None: async def require_database() -> None:
"""Readiness: Postgres отвечает на `SELECT 1` за отведённое время. """Readiness: Postgres отвечает на `SELECT 1` за отведённое время.
Любая ошибка — 503: готовность не должна отвечать 500. Не логирует: Любая ошибка — 503: готовность не должна отвечать 500. Не логирует:
healthcheck спрашивает каждые несколько секунд. healthcheck спрашивает каждые несколько секунд.
""" """
engine: AsyncEngine | None = getattr(request.app.state, "engine", None)
if engine is None:
raise exceptions.ServiceUnavailable
try: try:
await ping(engine, timeout=READINESS_DB_TIMEOUT_SECONDS) await ping(engine, timeout=READINESS_DB_TIMEOUT_SECONDS)
except Exception as e: except Exception as e:
+15
View File
@@ -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)
+4 -7
View File
@@ -8,7 +8,7 @@ from src.api import errors
from src.api.middlewares import RequestContextMiddleware from src.api.middlewares import RequestContextMiddleware
from src.api.routers import health_router, v1_router from src.api.routers import health_router, v1_router
from src.config import settings 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.infra.logger import AbstractLogger, get_logger
from src.schemas.enums import RunModeEnum from src.schemas.enums import RunModeEnum
@@ -16,13 +16,10 @@ logger: AbstractLogger = get_logger().bind(module="startup")
@asynccontextmanager @asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]: async def lifespan(_: FastAPI) -> AsyncIterator[None]:
database = settings.database database = settings.database
# engine не подключается при создании: без Postgres сервис стартует, # engine подключается лениво: без Postgres сервис стартует, а
# а /health/ready отвечает 503 # /health/ready отвечает 503
engine = create_engine(database)
app.state.engine = engine
app.state.session_factory = create_session_factory(engine)
if not database.password.get_secret_value(): if not database.password.get_secret_value():
logger.warning("Database password is empty") logger.warning("Database password is empty")
logger.info( logger.info(
+28 -6
View File
@@ -47,14 +47,36 @@ EXCLUDED: dict[Scenario, Exclusion] = {
"traceback и тем же request_id", "traceback и тем же request_id",
), ),
("data-storage", "Прежний пользователь после рестарта"): Exclusion( ("data-storage", "Прежний пользователь после рестарта"): Exclusion(
reason="нужен рестарт процесса, тесты сервер не трогают", reason="нужен рестарт стенда, тесты сервер не трогают",
check="evidence/container/lifecycle.txt: после рестарта " check="evidence/storage/restart.md: после scripts/restart.sh "
"прежний X-User-Id получает 401", "прежний 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( ("health", "Хранилище не готово"): Exclusion(
reason="хранилище создаётся при старте, у запущенного сервера " reason="нужно остановить Postgres, тесты стенд не трогают",
"оно готово всегда", check="evidence/storage/db-unavailable.md: /health/ready — 503, "
check="ветка 503 в src/api/routers/health.py, проверка чтением кода", "/health/live — 200; автоматическая проверка — change "
"failure-checks",
), ),
("identification", "Кнопка Authorize в Swagger"): Exclusion( ("identification", "Кнопка Authorize в Swagger"): Exclusion(
reason="это интерфейс /docs в браузере", reason="это интерфейс /docs в браузере",
+22 -2
View File
@@ -1,11 +1,12 @@
"""Спек `data-storage`. """Спек `data-storage`.
Гонки — в `test_race.py`, рестарт — исключение в `spec_coverage.py`. Гонки — в `test_race.py`; рестарт, отказы БД и пул — исключения в
`spec_coverage.py`.
""" """
import pytest import pytest
from api_client import API, Api from api_client import API, Actor, Api
from contract import assert_ok from contract import assert_ok
@@ -15,3 +16,22 @@ def test_created_user_visible_at_once(api: Api) -> None:
actor = api.register() actor = api.register()
resp = api.request("GET", f"{API}/users/me", actor=actor) resp = api.request("GET", f"{API}/users/me", actor=actor)
assert assert_ok(resp, 200, "User") == actor.user 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