Files
mtusi2026lab4/openspec/changes/upload-consistency/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

88 lines
5.6 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.
# Spec Delta
## MODIFIED 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: Лимиты ресурсов и секреты по сервисам
Каждый сервис стенда 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 и уборщика