Files
mtusi2026lab4/openspec/specs/container-run/spec.md
T
ricoromaandClaude Opus 5.5 5b42bd2891 feat: compensate failed uploads and clean stale pending attachments
- upload: delete the stored object when ready fails before COMMIT or the
  pending row is gone (503 instead of 500); unknown COMMIT outcome keeps it
- cleaner service (python -m src.cleaner): stale pending rows older than
  grace (900 s, must exceed 17 s live-upload bound) under FOR UPDATE SKIP
  LOCKED, object before row, own S3 user with read/delete only
- shared session_scope for API and cleaner; early_stop process name
- partial index on pending attachments, CREATE INDEX CONCURRENTLY
- s3-bootstrap: cleaner user, policy and checks; make env_setup appends
  missing template variables to an existing .env
- failure checks: cleaner on the failure stand, id-list hook actions,
  five new and three updated tests; driver upload-consistency
- sync upload-consistency deltas into main specs (storage-consistency)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 06:10:37 +03:00

297 lines
18 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.
# container-run Specification
## Purpose
Как стенд сервиса запускается и настраивается: compose с PostgreSQL,
Valkey, сервером S3, одноразовыми миграциями и bootstrap S3 и API
(`make run_docker`), публикация портов только на localhost,
конфигурация на старте, сохранность данных при рестарте стенда и явное
удаление учебных данных.
## Requirements
### Requirement: Запуск через compose
`make run_docker` SHALL собирать образ и поднимать стенд через
`docker compose`. В стенд входят:
- PostgreSQL и Valkey;
- сервер S3 (capability `object-storage`);
- одноразовые сервисы миграций и bootstrap S3;
- `API_REPLICAS` реплик API (capability `load-balancing`);
- уборщик незавершённых загрузок (capability `storage-consistency`) —
один долгоживущий процесс на образе API со своей командой;
- балансировщик (LB).
Реплики API SHALL стартовать после готовности PostgreSQL и Valkey,
успешных миграций и успешного bootstrap S3. Миграции и bootstrap SHALL
выполняться один раз за запуск отдельными сервисами, а не репликами.
Уборщик SHALL стартовать после готовности PostgreSQL, успешных миграций
и успешного bootstrap S3. Реплики API его не ждут, а фоновую уборку
MUST NOT выполнять сами. Уборщик MUST NOT публиковать порты и SHALL
перезапускаться после сбоя.
Перед этим цель SHALL создавать недостающие `.env` и `config.toml` из
шаблонов (`make env_setup`) и MUST NOT перезаписывать существующие: в
существующий `.env` она только дописывает переменные шаблона, которых в
нём нет (capability `service-configuration`, «Подключение к S3»).
`make stop` SHALL останавливать сервисы, `make down` — удалять
контейнеры, сохраняя volumes, `make logs` — показывать журнал всех
реплик API.
#### Scenario: Штатный запуск
- **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** сервис отвечает через LB на
`http://localhost:8080/health/ready`, работают две реплики API и
уборщик, сервер S3 в состоянии `healthy`, bootstrap S3 завершился с
кодом 0, и `make student_test` проходит
#### Scenario: Миграции один раз
- **WHEN** выполнен `make run_docker` с двумя репликами
- **THEN** журнал сервиса миграций содержит один прогон, а в журналах
реплик API нет запуска миграций
#### Scenario: Bootstrap S3 один раз
- **WHEN** выполнен `make run_docker` с двумя репликами
- **THEN** журнал bootstrap S3 содержит один прогон, завершённый до
старта реплик и уборщика, а в журналах реплик API нет создания bucket
### 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 S3 внутри сети compose — `S3_PORT`, его слушает сам сервер
S3, используют API в docker и bootstrap; внешний — `S3_OUT_PORT` на
`127.0.0.1` для запуска в консоли.
Если переменная порта API не задана, SHALL действовать 8080. Параметры
приложения в `.env` SHALL записываться в формате настроек
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
которые приложение не читает. Адреса и порты PostgreSQL, Valkey и S3
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 на
новых портах, и кэш работает
#### Scenario: Другой порт S3
- **WHEN** в `.env` заданы другие `S3_PORT` и `S3_OUT_PORT`, а compose
не правился
- **THEN** сервер S3 слушает `S3_PORT` и становится `healthy`, bootstrap
проходит, `make s3_check` проходит, а приложение в консоли обращается
к S3 на `127.0.0.1:$S3_OUT_PORT`
### Requirement: Оба способа запуска описаны в REPORT.md
Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два
способа запуска стенда:
- `make run_docker` — всё в compose;
- `make run_dev` — PostgreSQL, Valkey и S3 с bootstrap в compose,
сервис на хосте.
Для каждого SHALL быть указаны подготовка (`make env_setup`), команды,
которые выполняет цель Makefile, применение миграций и bootstrap S3,
ожидание готовности, проверки и остановка.
#### Scenario: Запуск по отчёту
- **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md`
для любого из двух способов
- **THEN** `/health/ready` отвечает 200, а `make student_test` и
`make s3_check` проходят
### Requirement: Публикация только на localhost
Порты LB, PostgreSQL и Valkey и порт API S3 SHALL публиковаться в
compose только на `127.0.0.1` хоста. Адрес публикации SHALL быть
записан литералом, а не переменной. Другие порты сервера S3 (консоль,
UI, внутренние серверы хранилища) MUST NOT публиковаться. Реплики API и
одноразовые сервисы MUST NOT публиковать порты на хосте: к репликам
ходят только LB и контейнеры сети compose. Учебный стенд MUST NOT быть
доступен с других машин сети.
#### Scenario: Адрес публикации
- **WHEN** для запущенных контейнеров LB, API, Postgres, Valkey и S3
выполняется `docker port`
- **THEN** порты LB, Postgres, Valkey и порт API S3 опубликованы на
`127.0.0.1`, а не на `0.0.0.0`; других портов у S3 не опубликовано, а
у контейнеров API опубликованных портов нет
### Requirement: Конфигурация на старте
`config.toml` SHALL подключаться к контейнеру при запуске, только на
чтение, и MUST NOT копироваться в образ. В compose файл SHALL
монтироваться так, чтобы его отсутствие давало явную ошибку запуска, а
не создавало на хосте каталог `config.toml/`. Секреты, которые нужны и
compose, и приложению, SHALL передаваться через `environment` (см.
`.claude/rules/settings.md`).
#### Scenario: Правка config.toml
- **WHEN** в `config.toml` изменён `[app] log_level` и контейнер
перезапущен без пересборки образа
- **THEN** сервис работает с новым уровнем логирования
#### Scenario: Нет config.toml, запуск через make
- **WHEN** `make run_docker` запускается без `config.toml`
- **THEN** `config.toml` создаётся из `config_example.toml`, и сервис
стартует
#### Scenario: Нет config.toml, compose напрямую
- **WHEN** `docker compose up` запускается без `config.toml`
- **THEN** запуск завершается ошибкой о несуществующем источнике
монтирования, и каталог `config.toml/` на хосте не появляется
### Requirement: Данные переживают рестарт стенда
Данные PostgreSQL и S3 SHALL храниться в именованных volumes. Скрипт
`scripts/restart.sh` SHALL перезапускать LB, все реплики API и все
используемые хранилища — PostgreSQL, Valkey и S3. Volumes, схема,
bucket, учётные записи S3 и данные SHALL сохраняться: без удаления
volumes, очистки и повторного наполнения. Bootstrap S3, который снова
выполняется при старте реплик, состояние хранилища не меняет. Число
реплик после рестарта 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 и S3
перезапущены: те же ID и новое время старта в `docker inspect`. После
готовности запрос с прежним токеном через LB получает 200 и видит
своё сообщение, а bootstrap S3 после рестарта сообщает, что bucket и
пользователь уже есть
#### Scenario: Публичная проверка сохранности
- **WHEN** на запущенном стенде выполняется `make test-persistence
ACTION_SCRIPT=scripts/restart.sh`
- **THEN** команда завершается с кодом 0 и печатает `PASS`
### Requirement: Удаление учебных данных
`make stop` и `make down` MUST NOT удалять volumes с данными PostgreSQL
и S3. Удаление данных стенда SHALL выполняться отдельной явной командой
`make wipe_data`, которая запрашивает подтверждение и называет
удаляемые данные.
#### Scenario: down сохраняет данные
- **WHEN** выполнены `make down`, затем `make run_docker`
- **THEN** ранее созданные пользователи, сообщения и объекты S3 на месте
#### Scenario: Явное удаление
- **WHEN** выполнен `make wipe_data` и удаление подтверждено
- **THEN** volumes Postgres и S3 удалены, и следующий `make run_docker`
поднимает пустую базу со схемой из миграций и пустой приватный bucket,
созданный bootstrap
### Requirement: Журнал контейнера
Журнал сервиса SHALL выводиться в stdout контейнера в формате
capability `service-logging`. Между Docker и журналом MUST NOT быть
посторонних строк лаунчера (например, от `uv`).
#### Scenario: docker logs
- **WHEN** выполняется `make logs` для работающего сервиса
- **THEN** каждая строка — JSON-запись сервиса или uvicorn
### Requirement: Свой проект compose у лабы
Стенд SHALL запускаться под именем проекта compose `mtusi-lab4` с
образом `mtusi-messenger:lab4`. Контейнеры, сети и volumes стенда
SHALL принадлежать этому проекту. Запуск, остановка и `make wipe_data`
MUST NOT затрагивать ресурсы проектов прошлых лаб (`mtusi-lab3`).
#### Scenario: Данные прошлой лабы не затронуты
- **WHEN** на машине есть volume `mtusi-lab3_postgres_data`, и в этом
репозитории выполнены `make run_docker`, затем `make wipe_data` с
подтверждением
- **THEN** стенд создаёт и затем удаляет только volumes своего проекта
(`mtusi-lab4_postgres_data`, `mtusi-lab4_s3_data`), а
`mtusi-lab3_postgres_data` остаётся с прежней датой создания
### Requirement: Лимиты ресурсов и секреты по сервисам
Каждый сервис стенда SHALL иметь лимиты CPU и памяти: LB, реплики API,
уборщик, сервисы миграций и bootstrap S3, PostgreSQL, Valkey и сервер
S3. Сумма лимитов и расчёт соединений PostgreSQL для заявленного числа
реплик и уборщика SHALL быть описаны в `REPORT.md`. Секреты SHALL
передаваться только тем сервисам, которым они нужны:
- пароль PostgreSQL — PostgreSQL, репликам API, уборщику и сервису
миграций;
- пароль Valkey — Valkey и репликам API;
- административные ключ и секрет S3 — только серверу S3;
- ключ подписи служебных вызовов S3 — серверу S3 и bootstrap;
- ключи пользователя API в S3 — bootstrap и репликам API;
- ключи пользователя уборщика в S3 — bootstrap и уборщику;
- LB MUST NOT получать ни одного секрета, а сервис миграций, PostgreSQL
и Valkey MUST NOT получать секретов S3. Уборщик MUST NOT получать
пароль Valkey, ключи API, административные ключи S3 и ключ подписи.
#### Scenario: Лимиты у всех контейнеров
- **WHEN** для каждого контейнера запущенного стенда выполняется
`docker inspect` (`HostConfig.NanoCpus`, `HostConfig.Memory`)
- **THEN** у LB, каждой реплики API, уборщика, сервисов миграций и
bootstrap S3, PostgreSQL, Valkey и сервера S3 оба значения больше нуля
#### Scenario: Секреты по сервисам
- **WHEN** проверяющий смотрит окружение сервисов в
`docker compose config`
- **THEN** у LB нет ни одного секрета; у сервиса миграций нет пароля
Valkey и секретов S3; пароль Valkey есть только у Valkey и реплик API;
административные ключи S3 — только у сервера S3, ключ подписи — у
сервера S3 и bootstrap, ключи API в S3 — у bootstrap и реплик API,
ключи уборщика в S3 — у bootstrap и уборщика