Files
mtusi2026lab2/openspec/changes/postgres-storage/specs/container-run/spec.md
T
ricoromaandClaude Opus 5.5 4921afa39d feat: store messenger data in PostgreSQL
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>
2026-10-01 15:33:49 +03:00

140 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.