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

7.0 KiB
Raw Blame History

Spec Delta

MODIFIED Requirements

Requirement: Подключение к S3

Параметры S3 SHALL задаваться в секции [s3]:

  • адрес и порт;
  • имя bucket;
  • ключи пользователя S3 процесса: у реплик API — пользователя API, у уборщика — пользователя уборщика;
  • регион;
  • срок вызова и срок установки соединения;
  • размер пула соединений клиента.

Секреты API и уборщика SHALL иметь по одному источнику — переменной .env, которую читает и bootstrap S3. Процесс получает свой секрет мостом или через environment compose. Имя bucket читают и приложение, и bootstrap, поэтому в .env оно записывается в формате настроек. Новый .env из make env_setup SHALL получать случайные секреты S3: административный секрет, секрет API, секрет уборщика и ключ подписи. В существующий .env make env_setup SHALL дописывать переменные шаблона, которых в нём нет: секреты — случайными значениями, остальные — значениями шаблона. Существующие строки он MUST NOT менять, а в вывод SHALL печатать только имена дописанных переменных, без значений. Секреты S3 MUST NOT попадать в журнал.

Имя bucket SHALL соответствовать правилам имён bucket S3: 3–63 символа, строчные латинские буквы, цифры, . и -, первый и последний символ — буква или цифра. Сроки SHALL быть положительными числами. Иначе сервис MUST NOT стартовать (требование «Некорректное значение останавливает запуск»).

Соответствие имён skeleton S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID_FILE и S3_SECRET_ACCESS_KEY_FILE реальной конфигурации SHALL быть описано в REPORT.md.

Scenario: Секрет API в одном месте

  • WHEN в .env меняется секрет API S3, и стенд поднимается заново
  • THEN bootstrap приводит к нему пользователя API, а сервис в консоли и в docker использует новый секрет без правки других файлов

Scenario: Секреты в новом .env

  • WHEN make env_setup дважды выполняется в каталоге без .env, и между запусками .env удаляется
  • THEN секреты S3, в том числе секрет уборщика, в обоих .env непустые и различаются

Scenario: Недостающие переменные в существующем .env

  • WHEN в существующем .env нет переменных, которые есть в шаблоне (например, секретов уборщика), и выполняется make env_setup
  • THEN эти переменные дописаны в конец .env, секреты среди них непустые, прежние строки не изменились, а вывод называет только имена дописанных переменных; повторный запуск ничего не дописывает

Scenario: Секреты S3 не в журнале

  • WHEN сервис стартует и обращается к S3, в том числе с неверным секретом
  • THEN в журнале нет ни секретов S3, ни ключей доступа

Scenario: Недопустимое имя bucket

  • WHEN сервис запускается с S3__BUCKET=Bad_Bucket
  • THEN сервис не стартует, а в выводе упомянут bucket

ADDED Requirements

Requirement: Параметры уборщика

Параметры уборщика незавершённых загрузок (capability storage-consistency) SHALL задаваться в секции [cleaner]:

  • interval_seconds — пауза между проходами, по умолчанию 60;
  • pending_grace_seconds — grace period, по умолчанию 900;
  • batch_size — сколько незавершённых загрузок уборщик выбирает одним запросом к PostgreSQL, по умолчанию 100.

Значения SHALL быть положительными, batch_size — целым. Иначе уборщик MUST NOT стартовать (требование «Некорректное значение останавливает запуск»).

Grace SHALL быть больше границы живой загрузки — суммы сроков её шагов после записи метаданных: 2 × [database] request_timeout_seconds + [s3] timeout_seconds, по настройкам процесса уборщика (17 с по умолчанию). Иначе уборщик MUST NOT стартовать: код выхода ненулевой, а ошибка называет grace, оба срока и границу.

Сравнение grace с границей SHALL выполнять только уборщик при своём старте: реплики API секцию [cleaner] не используют и от этой проверки не зависят. Разовая подмена SHALL работать через окружение CLEANER__* без правки файлов. Значения по умолчанию и обоснование grace SHALL быть описаны в REPORT.md.

Scenario: Параметры по умолчанию

  • WHEN уборщик запущен без секции [cleaner] и без переменных CLEANER__*
  • THEN запись о его старте называет интервал 60 с, grace 900 с и выборку 100

Scenario: Grace не больше границы

  • WHEN уборщик запускается с CLEANER__PENDING_GRACE_SECONDS=17 при сроках по умолчанию
  • THEN уборщик не стартует, код выхода ненулевой, а ошибка называет grace, оба срока и границу 17 с

Scenario: Интервал не число

  • WHEN уборщик запускается с CLEANER__INTERVAL_SECONDS=0 или CLEANER__INTERVAL_SECONDS=abc
  • THEN уборщик не стартует, в журнале — ошибка проверки настроек