Files
mtusi2026lab3/openspec/changes/archive/2026-10-01-postgres-storage/specs/container-run/spec.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec
  change instance-id-idempotency)
- rename the compose project to mtusi-lab3 and the image to :lab3
- add X-Instance-Id to every response and instance_id to every log
  record ([app] instance_id, hostname by default)
- require Idempotency-Key on POST messages: keys table in Postgres,
  key and message in one transaction, replay returns the same 201,
  another body gets 409, TTL from [idempotency] ttl_seconds
- send the key from student-tests, k6 scenarios and the skill driver;
  add idempotency, X-Instance-Id, key race and fault tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 19:42:36 +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.