- 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>
297 lines
18 KiB
Markdown
297 lines
18 KiB
Markdown
# 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 и уборщика
|