Replace the in-memory store with PostgreSQL 18.6: SQLAlchemy 2.1 async engine on asyncpg, alembic migrations with an async env.py, repos on AsyncSession and services that own the transaction. Username uniqueness is enforced by the database (ON CONFLICT), a chat and its members are created in one transaction, member order is kept in chat_members.position, and a composite foreign key makes the sender a member of the chat. History and chat lists use keyset pagination on (chat_id, created_at, id) and (user_id, created_at, chat_id). The compose stand runs postgres, a one-shot migrate service on the API image and the API. All Postgres addresses come from .env without literals; only the 127.0.0.1 publish address stays literal. make run_dev starts Postgres and applies migrations before the server, and make env_setup generates a random Postgres password. Unavailable PostgreSQL yields 503: get_db_session bounds the request with asyncio and classifies driver errors. BoundedCloseConnection limits asyncpg's graceful close, which otherwise waited without limit on a frozen server and held the request until it was resumed. Add scripts/restart.sh for make test-persistence and make test_isolated, which runs the image on a throwaway test database. Remove make run_no_compose. X-User-Id identification is unchanged until the session-auth change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
140 lines
7.6 KiB
Markdown
140 lines
7.6 KiB
Markdown
# Spec Delta
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: Данные переживают рестарт стенда
|
||
|
||
Данные PostgreSQL SHALL храниться в именованном volume. Скрипт
|
||
`scripts/restart.sh` SHALL перезапускать API и все используемые
|
||
хранилища, сохраняя volume, схему и данные: без удаления volume,
|
||
очистки и повторного наполнения. Скрипт SHALL быть исполняемым,
|
||
завершаться с кодом 0 только после перезапуска, укладываться в 90 с и
|
||
MUST NOT печатать секреты.
|
||
|
||
#### Scenario: Рестарт hook-ом
|
||
|
||
- **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`
|
||
поднимает пустую базу со схемой из миграций
|
||
|
||
## MODIFIED Requirements
|
||
|
||
### Requirement: Запуск через compose
|
||
|
||
`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 student_test` проходит
|
||
|
||
### Requirement: Порты из .env
|
||
|
||
Порты стенда и консольного запуска 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`
|
||
хоста для запуска в консоли.
|
||
|
||
Если переменная порта API не задана, SHALL действовать 8080. Параметры
|
||
приложения в `.env` SHALL записываться в формате настроек
|
||
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
|
||
которые приложение не читает. Адрес и порт PostgreSQL MUST NOT быть
|
||
записаны в compose литералами.
|
||
|
||
#### Scenario: Другой внешний порт
|
||
|
||
- **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`
|
||
|
||
#### 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_docker` (всё в compose) и
|
||
`make run_dev` (Postgres в compose, сервис на хосте). Для каждого SHALL
|
||
быть указаны подготовка (`make env_setup`), команды, которые выполняет
|
||
цель Makefile, применение миграций, ожидание готовности, проверки и
|
||
остановка.
|
||
|
||
#### Scenario: Запуск по отчёту
|
||
|
||
- **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md`
|
||
для любого из двух способов
|
||
- **THEN** `/health/ready` отвечает 200, а `make student_test` проходит
|
||
|
||
### Requirement: Публикация только на localhost
|
||
|
||
Порты API и PostgreSQL SHALL публиковаться в compose только на
|
||
`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не
|
||
переменной. Учебный стенд MUST NOT быть
|
||
доступен с других машин сети.
|
||
|
||
#### Scenario: Адрес публикации
|
||
|
||
- **WHEN** для запущенных контейнеров API и Postgres выполняется
|
||
`docker port`
|
||
- **THEN** порты опубликованы на `127.0.0.1`, а не на `0.0.0.0`
|
||
|
||
## REMOVED Requirements
|
||
|
||
### Requirement: Запуск командами из README
|
||
|
||
**Reason**: README лабы 2 не содержит команд запуска одного контейнера,
|
||
а API без PostgreSQL не обслуживает запросы. Цель `make run_no_compose`
|
||
удаляется.
|
||
**Migration**: стенд — `make run_docker`, консоль — `make run_dev`.
|
||
Сборку образа проверяет `make run_docker`, сборку из чистого clone —
|
||
требование «Сборка из чистого clone» capability `container-image`.
|
||
|
||
### Requirement: Состояние теряется при рестарте контейнера
|
||
|
||
**Reason**: на лабе 2 данные хранятся в PostgreSQL с volume и обязаны
|
||
переживать рестарт.
|
||
**Migration**: требование «Данные переживают рестарт стенда» и
|
||
`scripts/restart.sh`.
|