Files
mtusi2026lab3/openspec/changes/replicas-lb/specs/container-run/spec.md
T
ricoromaandClaude Opus 5.5 8e15e02898 docs: propose replicas-lb change
HAProxy as the single entry point, API replicas without published
ports, resource limits and per-service secrets, restart and stop-one
hooks, replica tests in student-tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 17:40:04 +03:00

8.6 KiB
Raw Blame History

Spec Delta

MODIFIED Requirements

Requirement: Запуск через compose

make run_docker SHALL собирать образ и поднимать стенд через docker compose: PostgreSQL, Valkey, одноразовый сервис миграций, API_REPLICAS реплик API (capability load-balancing) и балансировщик (LB). Реплики API SHALL стартовать после готовности PostgreSQL и Valkey и успешных миграций. Миграции SHALL выполняться один раз за запуск отдельным сервисом, а не репликами. Перед этим цель 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 сервис отвечает через LB на http://localhost:8080/health/ready, работают две реплики API, и make student_test проходит

Scenario: Миграции один раз

  • WHEN выполнен make run_docker с двумя репликами
  • THEN журнал сервиса миграций содержит один прогон, а в журналах реплик API нет запуска миграций

Requirement: Порты из .env

Порты стенда и консольного запуска SHALL браться из одного .env:

  • внутренний порт API — APP__PORT: параметр приложения [app] port в формате настроек. Его слушает каждая реплика, на нём работают healthcheck и проверки LB, на нём же LB принимает запросы внутри своего контейнера;
  • внешний порт стенда — APP_OUT_PORT: порт LB на 127.0.0.1 хоста, приложение его не читает;
  • порт PostgreSQL внутри сети compose — POSTGRES_PORT, его слушает сам сервер и использует API в docker;
  • внешний порт PostgreSQL — POSTGRES_OUT_PORT: порт на 127.0.0.1 хоста для запуска в консоли;
  • порт Valkey внутри сети compose — VALKEY_PORT, внешний — VALKEY_OUT_PORT на 127.0.0.1 для запуска в консоли.

Если переменная порта API не задана, SHALL действовать 8080. Параметры приложения в .env SHALL записываться в формате настроек (SECTION__FIELD). Имя без секции допускается только для переменных, которые приложение не читает. Адреса и порты PostgreSQL и Valkey MUST NOT быть записаны в compose литералами.

Scenario: Другой внешний порт

  • WHEN в .env задано APP_OUT_PORT=8090, и выполнен make run_docker
  • THEN API доступно через LB на localhost:8090, а внутри контейнеров реплики слушают APP__PORT

Scenario: Другой внутренний порт

  • WHEN в .env задано APP__PORT=9090
  • THEN реплики внутри контейнеров слушают 9090 и становятся healthy, LB проверяет их на 9090, а 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

Scenario: Другой порт Valkey

  • WHEN в .env заданы другие VALKEY_PORT и VALKEY_OUT_PORT, а compose не правился
  • THEN make run_docker и make run_dev подключаются к Valkey на новых портах, и кэш работает

Requirement: Публикация только на localhost

Порты LB, PostgreSQL и Valkey SHALL публиковаться в compose только на 127.0.0.1 хоста. Адрес публикации SHALL быть записан литералом, а не переменной. Реплики API MUST NOT публиковать порты на хосте: к ним ходят только LB и контейнеры сети compose. Учебный стенд MUST NOT быть доступен с других машин сети.

Scenario: Адрес публикации

  • WHEN для запущенных контейнеров LB, API, Postgres и Valkey выполняется docker port
  • THEN порты LB, Postgres и Valkey опубликованы на 127.0.0.1, а не на 0.0.0.0, а у контейнеров API опубликованных портов нет

Requirement: Данные переживают рестарт стенда

Данные PostgreSQL SHALL храниться в именованном volume. Скрипт scripts/restart.sh SHALL перезапускать LB, все реплики API и все используемые хранилища — PostgreSQL и Valkey. Volume, схема и данные SHALL сохраняться: без удаления volume, очистки и повторного наполнения. Число реплик после рестарта SHALL оставаться прежним. Скрипт SHALL быть исполняемым, завершаться с кодом 0 только после перезапуска, укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка make test-persistence ACTION_SCRIPT=scripts/restart.sh SHALL проходить через LB.

Scenario: Рестарт hook-ом

  • WHEN пользователь вошёл, отправил сообщение, затем выполнен scripts/restart.sh
  • THEN контейнеры LB, всех реплик API, Postgres и Valkey перезапущены: те же ID и новое время старта в docker inspect. После готовности запрос с прежним токеном через LB получает 200 и видит своё сообщение

Scenario: Публичная проверка сохранности

  • WHEN на запущенном стенде выполняется make test-persistence ACTION_SCRIPT=scripts/restart.sh
  • THEN команда завершается с кодом 0 и печатает PASS

ADDED Requirements

Requirement: Лимиты ресурсов и секреты по сервисам

Каждый сервис стенда SHALL иметь лимиты CPU и памяти: LB, реплики API, сервис миграций, PostgreSQL и Valkey. Сумма лимитов и расчёт соединений PostgreSQL для заявленного числа реплик SHALL быть описаны в REPORT.md. Секреты SHALL передаваться только тем сервисам, которым они нужны:

  • пароль PostgreSQL — PostgreSQL, репликам API и сервису миграций;
  • пароль Valkey — Valkey и репликам API;
  • LB MUST NOT получать ни одного секрета.

Scenario: Лимиты у всех контейнеров

  • WHEN для каждого контейнера запущенного стенда выполняется docker inspect (HostConfig.NanoCpus, HostConfig.Memory)
  • THEN у LB, каждой реплики API, сервиса миграций, PostgreSQL и Valkey оба значения больше нуля

Scenario: Секреты по сервисам

  • WHEN проверяющий смотрит окружение сервисов в docker compose config
  • THEN у LB нет ни одного пароля, у сервиса миграций нет пароля Valkey, а пароль Valkey есть только у Valkey и реплик API