- 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>
482 lines
34 KiB
Markdown
482 lines
34 KiB
Markdown
# Design
|
||
|
||
## Context
|
||
|
||
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`.
|
||
|
||
Сейчас всё состояние — `MemoryStore` (`src/infra/memory.py`): dict-ы и
|
||
отсортированные списки, атомарность держится на отсутствии `await`
|
||
внутри repo-функций. Сервисы получают `store` в конструкторе, repo —
|
||
первым параметром. Правила слоёв уже описывают целевое состояние
|
||
лабы 2 (`.claude/rules/`, commit `93b699a`), их здесь не пересказываем.
|
||
|
||
Решения обсуждены в `/opsx:explore` перед этим change: трек «5» — 2,
|
||
сессии — Postgres без кэша (change `session-auth`), Redis/Valkey — кэш
|
||
состава чатов (change `membership-cache`), конфиг без комментирования,
|
||
литерал только у адреса публикации `127.0.0.1`.
|
||
|
||
Проверено на версиях этого change пробными скриптами:
|
||
|
||
- SQLAlchemy 2.1.1 ставит greenlet только через extra `asyncio`
|
||
(`Requires-Dist: greenlet>=1; extra == "asyncio"`); без него
|
||
асинхронный engine не работает.
|
||
- В SQLAlchemy 2.1.1 флага `async_fallback` нет (в 2.0 он устарел).
|
||
Синхронный `env.py` bp_proxies с asyncpg на 2.1 не заработает.
|
||
- FastAPI 0.141.1: исключение из ручки попадает в `except` зависимости
|
||
с `yield`, а исключение, брошенное оттуда, обрабатывает
|
||
зарегистрированный обработчик (получен 503 из своего обработчика).
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
|
||
- `student-tests/` проходят против `make run_dev` и `make run_docker`
|
||
без правки тестов поведения: 78 из 79. Исключение —
|
||
`test_security_scheme_in_openapi`. Он сверяет схему `devUser` на
|
||
сервере со схемой в `contracts/openapi.json`, а в контракте lab2 её
|
||
нет (переход 1 → 2). Тест падал с момента переноса кода, чинится
|
||
вместе со спеком `identification` в `session-auth`.
|
||
- `make test_isolated` проверяет образ и связку compose и не оставляет
|
||
данных в рабочей базе. Здесь проверяется его механика: база,
|
||
контейнер, уборка при любом исходе. Зелёный прогон и evidence набора
|
||
против контейнера возможны только после `session-auth`: smoke lab2
|
||
требует вход и Bearer, а тест выше падает до тех пор.
|
||
- Консоль и docker работают от одного `.env` без переключений.
|
||
- Каждая мутация — одна транзакция, уникальность и связи держит БД.
|
||
|
||
**Non-Goals:**
|
||
|
||
- Аутентификация, пароли, сессии, `WWW-Authenticate` — `session-auth`.
|
||
Здесь `X-User-Id` и `devUser` остаются как есть.
|
||
- Redis/Valkey и кэш — `membership-cache`.
|
||
- Автоматические проверки отказов (остановка БД, откат составной
|
||
операции) — `failure-checks`; здесь поведение реализуется и
|
||
проверяется вручную с записью в `evidence/`.
|
||
- `bench/` под Postgres, EXPLAIN на ≥10 000 — `bench-postgres`.
|
||
- Производительность сверх индекса истории и keyset без `OFFSET`.
|
||
|
||
## Decisions
|
||
|
||
### 1. Хранилище меняется раньше аутентификации
|
||
|
||
Change не трогает HTTP-контракт лабы 1. Тогда `student-tests` —
|
||
готовая регрессия: красный тест поведения значит дефект хранилища.
|
||
Меняются только записи исключений в `spec_coverage.py`, которые
|
||
следуют за дельтами `data-storage` и `health`.
|
||
|
||
*Альтернатива:* хранилище и вход одним change. Отвергнута: красный
|
||
тест не отличал бы дефект БД от дефекта аутентификации.
|
||
|
||
### 2. Стек доступа к данным
|
||
|
||
`sqlalchemy[asyncio]` 2.1 + `asyncpg` + `alembic`, все три в основной
|
||
группе зависимостей: сервис миграций работает в runtime-образе, а он
|
||
собирается с `--no-dev`.
|
||
|
||
*Альтернативы:* psycopg 3 (второй знакомый вариант, но bp_proxies и
|
||
правила уже на asyncpg); голый asyncpg без SQLAlchemy (правила слоёв
|
||
опираются на `AsyncSession`, `pg_insert`, `tuple_`, а параметризация
|
||
через SQLAlchemy закрывает требование уровня 4 без самодельного SQL).
|
||
|
||
### 3. Схема
|
||
|
||
```
|
||
users chats
|
||
id uuid PK id uuid PK
|
||
username text UQ title text
|
||
display_name text created_at timestamptz
|
||
created_at timestamptz
|
||
^ ^
|
||
| |
|
||
chat_members messages
|
||
chat_id uuid FK -> chats --+ id uuid PK
|
||
user_id uuid FK -> users | PK chat_id --+ FK (chat_id, sender_id)
|
||
position smallint | sender_id --+ -> chat_members
|
||
created_at timestamptz (= chats.created_at) text text
|
||
PK (chat_id, user_id) created_at timestamptz
|
||
UQ (chat_id, position)
|
||
IX (user_id, created_at, chat_id) IX (chat_id, created_at, id)
|
||
```
|
||
|
||
- Все ограничения именованные (`migrations.md`). `CHECK` дублируют
|
||
контракт как защиту в глубину: шаблон `username`, длины
|
||
`display_name`, `title` и `text` в code points (`char_length`).
|
||
Первым всё равно отвечает API (400); сработавший `CHECK` — это дефект
|
||
валидации, и он даст 500, а не тихую запись.
|
||
- `position` хранит порядок `member_ids` из запроса: `test_chats.py`
|
||
сверяет его дословно. `member_ids` чата собирается
|
||
`array_agg(user_id ORDER BY position)`.
|
||
- Внешний ключ сообщения — составной, на `chat_members (chat_id,
|
||
user_id)`: сообщение от не участника невозможно на уровне БД, а не
|
||
только проверкой в сервисе.
|
||
- `chat_members.created_at` — копия `chats.created_at` (у `Base` это
|
||
поле есть у всех моделей, `migrations.md`). Благодаря ей список чатов
|
||
пользователя идёт keyset-ом по индексу
|
||
`(user_id, created_at, chat_id)` без сортировки всех его чатов.
|
||
Значение неизменяемо, рассинхрону неоткуда взяться.
|
||
- `id` и `created_at` назначает сервис (`uuid4()`, `utcnow()`), БД
|
||
их не генерирует: иначе порядок, который видит клиент, зависел бы от
|
||
двух часов.
|
||
|
||
*Альтернатива для списка чатов:* `JOIN` без копии даты и сортировка
|
||
всех чатов пользователя. Проще, но это полный просмотр чатов
|
||
пользователя на каждую страницу — ровно то, что рубрика уровня 4
|
||
запрещает для истории.
|
||
|
||
### 4. Транзакции и repo
|
||
|
||
Одна `AsyncSession` на запрос, commit — только в сервисе
|
||
(`service-layer.md`). Уровень изоляции — `READ COMMITTED`, явных
|
||
блокировок нет.
|
||
|
||
| Операция | Шаги в одной транзакции |
|
||
|---|---|
|
||
| регистрация | `INSERT ... ON CONFLICT (username) DO NOTHING RETURNING` → `None` = 409 → commit |
|
||
| создание чата | `SELECT id FROM users WHERE id = ANY(...)` → `INSERT chats` → `INSERT chat_members` (одна многострочная вставка) → commit |
|
||
| сообщение | чат с участниками → проверка членства → `INSERT messages` → commit |
|
||
| чтения | один `SELECT`; commit не нужен, сессия закрывается откатом |
|
||
|
||
Блокировки не нужны: пользователи и участники не удаляются и не
|
||
меняются, значит проверка перед вставкой не устаревает, а гонку
|
||
регистрации закрывает уникальный индекс. Составной внешний ключ и
|
||
внешние ключи участников — страховка на случай ошибки в сервисе.
|
||
|
||
Keyset: `tuple_(created_at, id) > tuple_(:t, :id)`, `ORDER BY
|
||
created_at, id`, `LIMIT limit + 1`. `uuid` Postgres сравнивает
|
||
побайтно — тот же порядок, что `UUID.int` у smoke. Формат курсора
|
||
(`src/utils/cursor.py`) не меняется.
|
||
|
||
Семантика при конкурентных вставках (в `REPORT.md`): повторов при
|
||
обходе нет. Сообщение, которое закоммитилось позже, но с `created_at`
|
||
меньше уже пройденного курсора, текущий обход пропустит; новый обход
|
||
с начала его увидит. Время ставит один процесс API с часами хоста.
|
||
|
||
### 5. Engine, пул и таймауты
|
||
|
||
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]`, значения по умолчанию:
|
||
|
||
| Параметр | По умолчанию | Зачем |
|
||
|---|---|---|
|
||
| `pool_size` / `max_overflow` | 10 / 5 | ограниченный пул (уровень 4) |
|
||
| `pool_timeout_seconds` | 5 | ожидание соединения → 503, а не очередь без конца |
|
||
| `connect_timeout_seconds` | 3 | недоступный хост не держит запрос |
|
||
| `statement_timeout_ms` | 5000 | серверный `statement_timeout` через `server_settings` |
|
||
| `request_timeout_seconds` | 6 | срок всей работы запроса с БД (`asyncio.timeout` в `get_db_session`): зависший сервер или обрыв сети, где серверный таймаут не сработает |
|
||
|
||
`command_timeout` asyncpg не используется: задача 5.1 показала, что
|
||
зависший сервер он не ограничивает (решение 6).
|
||
|
||
`pool_pre_ping=True`: после рестарта Postgres соединения пула мертвы, и
|
||
без проверки первый запрос после `scripts/restart.sh` получил бы 503.
|
||
Цена — один короткий round trip на выдачу соединения из пула.
|
||
`application_name=mtusi-messenger` — чтобы соединения были видны в
|
||
`pg_stat_activity`. URL — `sqlalchemy.engine.URL.create(...)` в
|
||
`Database.url`: пароль со спецсимволами экранируется, строку никто не
|
||
собирает руками.
|
||
|
||
### 6. Недоступность БД → 503
|
||
|
||
Зависимость `get_db_session` (с `yield`) ставит срок
|
||
`request_timeout_seconds` на всю работу запроса с БД, ловит ошибки
|
||
недоступности (`src/infra/db/errors.py`), закрывает сессию с
|
||
`invalidate()`, пишет `warning` и бросает `ServiceUnavailable`; таблица
|
||
`errors.py` отдаёт 503 `unavailable`. Так перевод в одном месте, с
|
||
логом, и ни один сервис не оборачивает каждый вызов.
|
||
|
||
Классы исключений сняты задачей 5.1 на SQLAlchemy 2.1.1 и asyncpg 0.31:
|
||
|
||
| Отказ | Исключение | Время до ответа |
|
||
|---|---|---|
|
||
| Postgres остановлен | `ConnectionRefusedError` (SQLAlchemy не оборачивает) | сразу |
|
||
| сервер не отвечает на подключение | `TimeoutError` (`connect_timeout_seconds`) | 3 с |
|
||
| сработал `statement_timeout` | `DBAPIError`, SQLSTATE `57014` | по таймауту |
|
||
| пул исчерпан | `sqlalchemy.exc.TimeoutError` | `pool_timeout_seconds` |
|
||
| соединение оборвано | `DBAPIError` с `connection_invalidated` | сразу |
|
||
| сервер завис, соединение из пула | `TimeoutError` срока запроса | 6 + 2 с |
|
||
|
||
Перехватываются `OSError` (сюда входит `TimeoutError`),
|
||
`sqlalchemy.exc.TimeoutError` и `DBAPIError` с `connection_invalidated`
|
||
или SQLSTATE класса `08`, `57014`, `57P01`–`57P03`. Остальные
|
||
`DBAPIError` (ограничения, синтаксис) — дефект, им положен 500.
|
||
|
||
Зависший сервер (`docker compose pause`) нашёл дефект в связке
|
||
библиотек. На отмене запроса asyncpg шлёт серверу CancelRequest через
|
||
новое соединение без срока, а SQLAlchemy закрывает прерванное
|
||
соединение мягко и ждёт этой отмены. Без поправки запрос висел до
|
||
разморозки сервера (169 с в замере), и `command_timeout` asyncpg его не
|
||
ограничивал. Поправка — `BoundedCloseConnection` (публичный
|
||
`connection_class` asyncpg): мягкое закрытие ограничено 2 с, после чего
|
||
asyncpg обрывает соединение. Отсюда «6 + 2 с» в таблице.
|
||
|
||
`/health/ready` не ходит через эту зависимость: отдельная проверка
|
||
`SELECT 1` с таймаутом через глобальный engine.
|
||
|
||
*Альтернативы:* обработчик исключений SQLAlchemy в `errors.py` —
|
||
отвергнут, `errors.py` не логирует (`logging.md`), а потеря БД в логе
|
||
нужна; `try/except` в каждом методе сервиса — шум без пользы.
|
||
|
||
### 7. Конфигурация: консоль и docker из одного `.env`
|
||
|
||
```
|
||
.env (шаблон .env.example)
|
||
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB <- их читает и образ postgres
|
||
POSTGRES_HOST=postgres адрес Postgres в сети compose (docker)
|
||
POSTGRES_PORT=5432 порт, который слушает сервер (PGPORT)
|
||
POSTGRES_OUT_PORT=5433 порт публикации на 127.0.0.1 (console)
|
||
DATABASE__HOST=127.0.0.1 \
|
||
DATABASE__PORT=${POSTGRES_OUT_PORT} мосты для console:
|
||
DATABASE__USER=${POSTGRES_USER} приложение на хосте читает .env
|
||
DATABASE__PASSWORD=${POSTGRES_PASSWORD}
|
||
DATABASE__NAME=${POSTGRES_DB} /
|
||
|
||
docker-compose.yml
|
||
x-app-env: &app-env api и migrate — одно окружение
|
||
APP__RUN_MODE: docker литерал: это определение режима
|
||
DATABASE__HOST: ${POSTGRES_HOST:-postgres}
|
||
DATABASE__PORT: ${POSTGRES_PORT:-5432}
|
||
DATABASE__USER / __PASSWORD / __NAME: ${POSTGRES_*}
|
||
postgres:
|
||
environment: POSTGRES_USER / _PASSWORD / _DB, PGPORT: ${POSTGRES_PORT:-5432}
|
||
ports: "127.0.0.1:${POSTGRES_OUT_PORT:-5433}:${POSTGRES_PORT:-5432}"
|
||
networks.default.aliases: ["${POSTGRES_HOST:-postgres}"]
|
||
```
|
||
|
||
- `.env` в контейнер не попадает, поэтому консольные `DATABASE__*` из
|
||
него не конфликтуют с docker-значениями из `environment`.
|
||
- Алиас в сети делает любое значение `POSTGRES_HOST` рабочим для
|
||
Postgres стенда; внешний адрес уводит API во внешнюю БД.
|
||
- `PGPORT` меняет порт самого сервера (так его читает `postgres`) и
|
||
`pg_isready` в healthcheck; иначе смена `POSTGRES_PORT` сломала бы
|
||
стенд. Проверяется сценарием «Другой порт Postgres».
|
||
- `127.0.0.1` — литерал: требование безопасности, а не параметр.
|
||
- В `.env.example` пароль пустой. `make env_setup` при создании `.env`
|
||
подставляет случайный (`openssl rand -hex 16`), существующий `.env`
|
||
не трогает. С пустым паролем образ postgres не стартует — забытый
|
||
шаг проявится сразу, а в git не лежит общий пароль стенда.
|
||
- В `config_example.toml` — только то, что читает одно приложение:
|
||
пул и таймауты `[database]`. Адрес и учётные данные там не
|
||
дублируются (`settings.md`).
|
||
|
||
*Альтернатива:* блоки `[database]` для консоли и docker с
|
||
комментированием, как в bp_proxies. Отвергнута: ручное переключение,
|
||
пароль в двух местах, `config.toml` здесь не запекается в образ.
|
||
|
||
### 8. Миграции
|
||
|
||
- `alembic.ini`: `script_location = migrations`, `file_template` из
|
||
`migrations.md`, `prepend_sys_path = .`, без `sqlalchemy.url`.
|
||
- `env.py` — асинхронный шаблон alembic: `create_async_engine(
|
||
settings.database.url)`, затем `await conn.run_sync(do_run_migrations)`.
|
||
Ревизии остаются синхронным кодом `op.*`. URL не проходит через
|
||
ConfigParser alembic, поэтому `%` в пароле ничего не ломает.
|
||
- Логи миграций — через `src/infra/logger.py` (JSON), а не `fileConfig`
|
||
из `alembic.ini`: у сервиса миграций тот же формат журнала, что у API.
|
||
Логгер `alembic` — уровень `INFO`, чтобы строки «Running upgrade»
|
||
были видны.
|
||
- Первая ревизия пишется autogenerate и дописывается руками:
|
||
autogenerate не видит `CHECK` (`migrations.md`).
|
||
|
||
Запуск:
|
||
|
||
```
|
||
console make run_dev
|
||
start_db docker compose up -d --wait postgres
|
||
upgrade uv run alembic upgrade head --> 127.0.0.1:${POSTGRES_OUT_PORT}
|
||
APP__RUN_MODE=console uv run python -m src
|
||
|
||
docker make run_docker
|
||
postgres --healthy--> migrate --exit 0--> api
|
||
(образ API, depends_on:
|
||
alembic upgrade migrate: service_completed_successfully
|
||
head, restart: no)
|
||
```
|
||
|
||
`make revision` зависит от `upgrade`: autogenerate сравнивает модели с
|
||
базой на `head`.
|
||
|
||
### 9. Compose и образ
|
||
|
||
- Postgres — последняя 18.x, тег с патч-версией и digest индекса
|
||
(`docker.md`). Точку монтирования volume берём из метаданных образа
|
||
(`docker image inspect` → `Config.Volumes`): у 18.x она изменилась
|
||
относительно 17.x.
|
||
- Именованный volume `postgres_data`; верхнеуровневое `name:` проекта,
|
||
чтобы имена volume и контейнеров не зависели от имени каталога.
|
||
- `Dockerfile`: в runtime дополнительно `COPY migrations alembic.ini`.
|
||
- `make run_no_compose` удаляется вместе с переменными `DOCKER_IMAGE` и
|
||
`DOCKER_CONTAINER` в `Makefile`: без Postgres один контейнер API не
|
||
обслуживает запросы, а мосты `${...}` из `.env` голый `docker run
|
||
--env-file` не раскрывает. Образ собирает `make run_docker`, сборку из
|
||
чистого clone проверяет команда из `docker.md`. Healthcheck остаётся
|
||
в образе: его берут compose и стенд `bench/`.
|
||
|
||
*Альтернатива:* оставить цель как проверку образа (live 200, ready
|
||
503). Отвергнута: цель, которая по построению поднимает неготовый
|
||
сервис, — лишнее, что нужно поддерживать и описывать.
|
||
|
||
### 10. `scripts/restart.sh`
|
||
|
||
`docker compose stop api` → `docker compose restart postgres` →
|
||
`docker compose up -d --wait postgres` (тот же контейнер, ожидание
|
||
healthcheck) → `docker compose start api`. Volume не трогается.
|
||
`start api` запускает и зависимость `migrate` (задача 6.1 увидела это
|
||
по `StartedAt`): повторный прогон миграций — no-op (`db-migrations`).
|
||
Hook отрабатывает за ~4 с. Готовность API он не ждёт — это делает тест.
|
||
В `evidence/` — `docker compose ps` и `StartedAt` из `docker inspect`
|
||
до и после.
|
||
|
||
### 11. Что ещё меняется вокруг кода
|
||
|
||
- `MemoryStore` и `get_store` удаляются, `health.py` зависит от проверки
|
||
БД. DTO остаются frozen; `ChatFullDTO.member_ids` собирается из
|
||
`array_agg`.
|
||
- Скилл `run-mtusi-messenger`: `driver.py start` перед сервером
|
||
выполняет `make start_db upgrade`; в `SKILL.md` убираются «рестарт =
|
||
пустое состояние» и примеры с `MemoryStore`.
|
||
- Правила: `settings.md` — консольный адрес Postgres в `.env`, а не в
|
||
`config.toml`; `infra.md` — перевод ошибок драйвера в
|
||
`get_db_session`; `run-modes.md` — именованный volume вместо
|
||
`POSTGRES_VOLUME`, `run_dev` с миграциями; `docker.md` — переменные
|
||
Postgres в compose. Из `settings.md`, `run-modes.md`, `docker.md` и
|
||
`AGENTS.md` уходят упоминания `make run_no_compose`.
|
||
- `AGENTS.md`: из «Переходного состояния» уходят пункты про
|
||
`MemoryStore`, `migrations/`, `scripts/restart.sh`; `X-User-Id`
|
||
остаётся до `session-auth`.
|
||
|
||
### 12. `make test_isolated`: образ на временной базе
|
||
|
||
Тесты ходят в API по HTTP, поэтому временной базе нужен свой API. Им
|
||
становится отдельный контейнер из того же определения сервиса compose,
|
||
что и рабочий: так один прогон проверяет код, образ и связку compose, а
|
||
рабочий стенд и рабочая база не трогаются.
|
||
|
||
```
|
||
make test_isolated (зависит от env_setup и start_db)
|
||
uv run python student-tests/run_isolated.py
|
||
0. docker rm -f <тестовый контейнер> хвост прошлого прогона
|
||
DROP DATABASE IF EXISTS "test_<db>" WITH (FORCE)
|
||
1. docker compose build api
|
||
2. CREATE DATABASE "test_<db>"
|
||
3. docker compose run --rm --no-deps -e DATABASE__NAME=test_<db> migrate
|
||
4. docker compose run -d --no-deps --name <тестовый контейнер>
|
||
-e DATABASE__NAME=test_<db>
|
||
-p 127.0.0.1:$TEST_APP_PORT:$APP__PORT api
|
||
5. ждать GET http://127.0.0.1:$TEST_APP_PORT/health/ready = 200 (не дольше 60 с)
|
||
6. make test BASE_URL=http://127.0.0.1:$TEST_APP_PORT
|
||
make student_test BASE_URL=http://127.0.0.1:$TEST_APP_PORT
|
||
finally (и по Ctrl+C):
|
||
при неудаче: docker logs --tail 50 <тестовый контейнер>
|
||
docker stop -> docker rm <тестовый контейнер>
|
||
DROP DATABASE "test_<db>" WITH (FORCE) (кроме KEEP_TEST_DB=1)
|
||
код выхода: первый ненулевой из smoke, набора, уборки
|
||
```
|
||
|
||
- **`docker compose run` берёт определение сервиса целиком:** образ,
|
||
`x-app-env`, монтирование `config.toml`, сеть и алиас Postgres.
|
||
Подменяется только `DATABASE__NAME`, поэтому ошибки в якоре окружения,
|
||
в `PGPORT`, в алиасе или в составе образа роняют и этот прогон.
|
||
- **`--no-deps`**, чтобы `run` не прогнал `migrate` по рабочей базе и
|
||
не пересоздал рабочие контейнеры. Postgres уже поднят `start_db`.
|
||
- **Публикация — явным `-p` на `127.0.0.1`.** `compose run` без
|
||
`--service-ports` порты сервиса не публикует, поэтому с рабочим API
|
||
на `APP_OUT_PORT` конфликта нет. Порт внутри контейнера тот же
|
||
`APP__PORT`, healthcheck образа работает как обычно.
|
||
- **Сборка перед прогоном.** Проверяется образ ровно из рабочего дерева,
|
||
а не устаревший. `migrate` использует тот же тег образа, что и `api`,
|
||
поэтому одна сборка покрывает оба. С кэшем слоя зависимостей это
|
||
секунды.
|
||
- **`CREATE` и `DROP` — через `docker compose exec -T postgres psql`**
|
||
под `POSTGRES_USER` по локальному сокету контейнера. Скрипту не нужны
|
||
ни `psql` на хосте, ни драйвер БД, он остаётся на stdlib, как
|
||
`bench/`. Имя базы проверяется по `^[a-z0-9_]+$` и берётся в кавычки.
|
||
- **`WITH (FORCE)`** (Postgres 13+) рвёт оставшиеся соединения. Базу
|
||
можно удалить, даже если контейнер не остановился штатно.
|
||
- **`TEST_APP_PORT`** в `.env`, по умолчанию 18088. Не пересекается с
|
||
рабочим API (8080) и портами драйвера скилла `run-mtusi-messenger`
|
||
(18080, 18090). Имя без секции: приложение его не читает.
|
||
- **Имя тестового контейнера фиксировано** (`<проект>-test-api`):
|
||
хвост прошлого прогона находится и удаляется без поиска.
|
||
- **Evidence.** Вывод `make test_isolated` — это прогон набора против
|
||
контейнера, которого требует спек `student-tests`, «Результат прогона
|
||
сохраняется». Отдельный прогон против `make run_docker` для evidence
|
||
не нужен. `make student_test` не меняется и работает против любого
|
||
`BASE_URL`. Успешный прогон снимает `session-auth`: в этом change
|
||
smoke lab2 и `test_security_scheme_in_openapi` ещё падают (Goals).
|
||
|
||
*Альтернативы:* сервис на хосте (`uv run python -m src` с временной
|
||
базой) — быстрее, но не проверяет образ и compose и требует настройки,
|
||
выключающей reload в режиме console; оба режима сразу — больше кода в
|
||
скрипте ради цикла, который и так даёт `make run_dev` +
|
||
`make student_test`; отдельный контейнер Postgres на tmpfs — второй
|
||
сервис в compose ради мусора тестов; чистка через `DELETE` из тестов —
|
||
ломает black-box и правило `student-tests.md`.
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- [Два `make test_isolated` одновременно удалят базу друг друга] →
|
||
Параллельный запуск не поддерживается (спек `student-tests`); прогон
|
||
занимает секунды, одному разработчику этого хватает.
|
||
- [Каждый `make test_isolated` пересобирает образ: цикл «поправил →
|
||
проверил» медленнее, чем на хосте] → Быстрая итерация — `make run_dev`
|
||
и `make student_test`; `test_isolated` — итоговая проверка перед
|
||
коммитом и evidence.
|
||
- [Проверки отказов из `failure-checks` с остановкой Postgres положат и
|
||
рабочую базу: сервер общий] → Временная база решает проблему мусора,
|
||
а не изоляцию отказов; `failure-checks` выберет для них отдельный
|
||
контейнер.
|
||
- [До `session-auth` ни один прогон не зелёный: падают smoke lab2 и
|
||
`test_security_scheme_in_openapi`] → Регрессию хранилища видно по
|
||
остальным 78 тестам; известное падение записано в «Переходном
|
||
состоянии» `AGENTS.md`, успешный `test_isolated` — задача
|
||
`session-auth`.
|
||
- [Пользователи из этого change без пароля, а `session-auth` добавит
|
||
`password_hash`] → Данные стенда синтетические. `session-auth` решает
|
||
сам: колонка `NOT NULL` после `make wipe_data` или nullable с отказом
|
||
во входе. Отмечено здесь, чтобы не стало сюрпризом.
|
||
- [`pool_pre_ping` — лишний round trip на выдачу соединения] →
|
||
Приемлемо для учебного стенда; альтернатива `pool_recycle` не спасает
|
||
от рестарта БД между выдачами.
|
||
- [Время ставит приложение, а не БД] → Одна реплика API на одном хосте;
|
||
при репликах лабы 3 часы общие (один Docker-host). Ограничение в
|
||
`REPORT.md`.
|
||
- [`CHECK` на `text` 1–4000 помешает lab4, где разрешён пустой текст с
|
||
вложениями] → Новая миграция в lab4, применённую не трогаем.
|
||
- [SQLAlchemy 2.1 — свежая ветка] → Асинхронный `env.py` и код repo
|
||
работают и на 2.0; при дефекте 2.1 откат на `<2.1` без правок кода.
|
||
- [Прогоны против рабочего стенда (`make student_test`, `make test`)
|
||
копят данные в volume] → Обычный прогон — `make test_isolated`
|
||
(решение 12); для чистого рабочего стенда — `make wipe_data`.
|
||
- [Точный набор исключений драйвера для 503 неизвестен заранее] →
|
||
Задача с остановленным Postgres фиксирует его до написания
|
||
перехвата.
|
||
|
||
## Migration Plan
|
||
|
||
Данных для переноса нет: лаба 1 хранила всё в памяти. Порядок:
|
||
зависимости и настройки → модели и первая ревизия → repo и сервисы →
|
||
lifespan, health, 503 → compose, Makefile, restart hook → тесты и
|
||
evidence → документы. Откат: `git revert` коммитов change и
|
||
`make wipe_data`.
|
||
|
||
## Open Questions
|
||
|
||
- Значения пула и таймаутов по умолчанию могут уточниться по замерам
|
||
`bench-postgres`: это настройки, спеки и план от них не зависят.
|