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>
7.6 KiB
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.