- 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>
7.0 KiB
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 уборщик не стартует, в журнале — ошибка проверки настроек