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