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

5.6 KiB
Raw Blame History

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 и уборщика