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:
@@ -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
@@ -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
@@ -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
@@ -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`. Если это единственное хранилище сессий, нужен
|
||||
|
||||
@@ -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
@@ -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
@@ -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}`
|
||||
|
||||
@@ -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: не править, не ослаблять,
|
||||
|
||||
@@ -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
|
||||
проходят без рестарта сервера.
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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-модели
|
||||
|
||||
@@ -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/`.
|
||||
|
||||
@@ -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`), а потеря БД в логе
|
||||
|
||||
@@ -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 .`.
|
||||
Проверка: все команды без ошибок.
|
||||
|
||||
@@ -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`), без
|
||||
|
||||
@@ -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: Журнал контейнера
|
||||
|
||||
|
||||
@@ -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` не позже этого
|
||||
таймаута, а не ждёт бесконечно
|
||||
|
||||
@@ -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
|
||||
@@ -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 и видят одни и
|
||||
те же данные
|
||||
|
||||
@@ -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
@@ -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:
|
||||
|
||||
@@ -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
@@ -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(
|
||||
|
||||
@@ -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 в браузере",
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user