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

7.6 KiB
Raw Blame History

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.