Files
mtusi2026lab4/openspec/changes/upload-consistency/design.md
T
ricoromaandClaude Opus 5.5 87c48b940b fix: address upload-consistency verify findings
Mark a stale pending row in its own committed transaction before the
cleaner deletes the object, and let mark_ready promote only unmarked
rows, so a cleaner rollback after the object delete can no longer leave
a ready attachment without its object. Add fault checks for an unknown
COMMIT outcome, an upload outliving the grace period and a cleaner
failure after the object delete; fix the cleaner entrypoint in rules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 21:27:47 +03:00

853 lines
70 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.
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`.
Код — состояние после `attachments` (`d9d44c5`):
- `AttachmentService.upload` (`src/core/services/attachment.py`):
проверки → тело → строка `pending` с `object_key` (tx1, commit) → PUT
(`[s3] timeout_seconds`, 5 с, без повторов) → `mark_ready` (`UPDATE …
WHERE status = 'pending' RETURNING`, tx2, commit) → 201. Каждый шаг с
БД — свой `db_session_scope()` со сроком `[database]
request_timeout_seconds` (6 с), отказ БД → 503;
- отказ PUT или tx2 → 503, строка `pending` остаётся. Компенсации нет,
а `mark_ready` → `None` даёт `RuntimeError` (500) с пометкой «ветку
переопределит `upload-consistency`»;
- политика S3 пользователя API уже включает `s3:DeleteObject`, у клиента
есть `delete` (отсутствие ключа — не ошибка, нет bucket — 503);
- `db_session_scope` живёт в `src/api/dependencies.py`: процессу вне API
его не взять;
- индексов по `status` и `created_at` у `attachments` нет.
### Что найдено до решений
1. **Счёт объектов hook по каталогам ошибается после DELETE.**
`fault_hook.py count-objects` считает каталоги `<id>` под `<база>/
attachments`. После DELETE объекта SeaweedFS оставляет пустой
каталог. Его убирает `EmptyFolderCleaner` сервера, в пробе — через
~2 мин (журнал S3: «deleting empty folder … (triggered by
original)»). Тесты `attachments` объекты не удаляли и этого не
видели. С уборщиком счёт по каталогам завышен. Формат `fs.tree` по
выводам пробы: первый каталог — после DELETE, остальные с объектом:
```
attachments
├──11111111-1111-4111-8111-111111111111
├──22222222-2222-4222-8222-222222222222
│ └──original
└──aaaaaaaa-0000-4000-8000-000000000001
└──original
```
2. **Глобальные счётчики в тестах станут нестабильны.** Уборщик стенда
отказов убирает строки прежних тестов параллельно со следующими.
«`pending` +1» и «счётчики не изменились» в
`test_upload_with_object_storage_stopped` и
`test_rejected_uploads_leave_nothing` зависели бы от порядка тестов.
3. **Образ API несёт HTTP-healthcheck** (`/health/ready`). Долгоживущий
уборщик на том же образе HTTP не слушает и стал бы `unhealthy`.
4. **Рабочий `.env` уже есть.** Новые секреты уборщика `make env_setup`
в него не допишет (правило `settings.md`), а с `:?` compose без них
не разберёт файл — ни одной командой.
5. **`bench/run.py` генерирует секреты стенда сам** (`compose_env`):
новые обязательные переменные compose нужны и ему, иначе профили
`bench/` не стартуют.
### Пробы (2026-10-21, scratchpad, проект compose `ucprobe`)
Стенд пробы: SeaweedFS тем же образом и аргументами, что `s3`, и
PostgreSQL 18.6, данные на tmpfs. Volumes не создавались, проект удалён.
Клиент приложения запускался в образе `mtusi-messenger:lab4` в сети
пробы.
| Проверка | Результат |
|---|---|
| Пользователь с политикой только `s3:DeleteObject` на `bucket/*`: DELETE существующего, повторный, никогда не существовавшего | 204, 204, 204; после него GET ключом API — 404 |
| Тот же ключ: GET, HEAD, PUT, список объектов, создание и удаление bucket, DELETE в другом bucket | все 403; список bucket-ов — 200 с пустым списком, как у ключа API |
| DELETE ключом уборщика, когда его bucket удалён; DELETE в чужом несуществующем bucket | 404 `NoSuchBucket` (клиент → 503); 403 |
| Пустой каталог `<id>/` после DELETE | `fs.ls` и `fs.tree` его показывают; список S3 (ListObjectsV2 с `delimiter` и без) — нет; сервер убрал его через ~2 мин |
| PUT клиентом приложения при `docker pause` S3: срок 5 с, 111 817 байт и 10 MiB, процесс завершается или живёт после 503, затем `unpause` | 4 из 4: 503 за 5,00–5,01 с, объекта после разморозки нет |
| Тот же `put` против сервера-заглушки, который принимает запрос и молчит | заголовок `Expect: 100-continue` (botocore, `add_expect_header`), до ответа сервера получено 0 байт тела: aiohttp ждёт `100 Continue`. Поэтому при замороженном S3 тело не уходит вовсе |
| Ошибка из триггера (`RAISE … USING ERRCODE`) через engine приложения | `P0001`, `40001` — `is_db_unavailable` False (500); `57P01`, `08006`, `53300` — True (503); пул после ошибки рабочий |
| `CREATE INDEX CONCURRENTLY IF NOT EXISTS … WHERE status = 'pending'` в `autocommit_block` асинхронного `env.py` проекта | с нуля, повтор (no-op), `downgrade` (`DROP INDEX CONCURRENTLY IF EXISTS`), снова `upgrade` — без ошибок, индекс `indisvalid` |
## Goals / Non-Goals
**Goals:**
- Пункт рубрики «4» о компенсации и очистке с доказательством отказами
на стенде отказов (`PLAN.md`, этап 3).
- Порядок шагов загрузки не меняется (решение пользователя). Меняются
только ветки ошибок.
- Уборщик и живая загрузка не мешают друг другу. Загрузка, пережившая
grace, не создаёт `ready` без объекта.
- Задел для трека 2: пакет уборщика с проходами, свой пользователь S3,
capability `storage-consistency`.
**Non-Goals:**
- Объекты, записанные мимо API, строки `ready` без объекта, сверка
списком bucket, dry-run, стоимость обхода — трек 2. Здесь уборщик
идёт только от строк БД.
- Вложения `ready`, на которые не ссылается ни одно сообщение. Это
учтённые вложения: строка и объект есть, контракт срока им не задаёт.
Сюда же попадает загрузка, у которой клиент оборвал соединение после
тела: uvicorn задачу не отменяет, вложение становится `ready`, а 201
до клиента не доходит.
- Лимит одновременных загрузок, сроки чтения тела — `upload-memory`.
- Отказ хоста и диска S3 — одна нода, как и раньше (`balancer.md`).
## Decisions
### 1. Компенсация в загрузке
Объект удаляется сразу, только когда точно известно, что вложение не
станет `ready`:
| Где сбой | Объект | Ответ | Строка `pending` |
|---|---|---|---|
| tx1 (запись строки) | PUT не выполнялся | 503 | нет |
| PUT: отказ, срок, 5xx | не трогается | 503 | уборщику |
| tx2 до отправки COMMIT (сам `UPDATE`, пул, срок на нём) | удаляется до ответа | 503 (отказ БД) или 500 (дефект) | уборщику |
| tx2 на COMMIT (связь оборвалась во время фиксации) | не трогается | 503 | уборщику, если фиксации не было |
| `mark_ready` → `None` (строку убрал уборщик) | удаляется до ответа | 503 | нет |
| процесс убит или задача отменена (SIGKILL, отмена при остановке) | не трогается | — | уборщику |
- Граница «до отправки COMMIT» — флаг в сервисе, он ставится прямо
перед `commit()`. Ошибка в `mark_ready` — транзакция не
зафиксирована, PostgreSQL сам её откатит. Ошибка в `commit()` — исход
неизвестен.
- Компенсация — `storage.delete(key)` ключом API, без повторов, срок —
`[s3] timeout_seconds`. Не удалось — `warning`, исходная ошибка
уходит дальше, объект убирает уборщик.
- `mark_ready` → `None` — 503 `ServiceUnavailable` и `error` «Pending
attachment was removed before ready»: загрузка пережила grace, это
сигнал увеличить grace. Прежний `RuntimeError` (500) убирается.
- `CancelledError` не ловится (`except Exception`): при отмене `await`
не надёжен, остаток — уборщику.
- Журнал (`logging.md`): `warning` «Attachment upload left pending» с
`attachment_id` и шагом (`put`, `ready`, `commit`); `info` или
`warning` о компенсации — удалён объект или нет.
*Альтернатива:* компенсация удаляет и строку. Отвергнута. Чаще всего
tx2 падает из-за отказа PostgreSQL, и удаление строки упало бы так же.
Строка без объекта безопасна, уборщик её уберёт. Обратный порядок
(сначала строка, потом объект) при сбое второго шага оставил бы объект
без строки. *Альтернатива:* компенсация и при неизвестном исходе
COMMIT. Отвергнута: вложение могло стать `ready`, и удаление объекта
дало бы `ready` без объекта — 500 при скачивании. *Альтернатива:*
компенсация после неудачного PUT. Отвергнута:
- при замороженном S3 DELETE ждал бы ещё 5 с, ответ — 10 с, вровень с
`timeout server` HAProxy;
- поздний объект DELETE не убирает, если тот запишется после него;
- проба показала: тело при замороженном S3 не уходит, позднего объекта
нет.
*Альтернатива:* компенсация фоновой задачей после ответа. Отвергнута:
фоновая работа в репликах API запрещена (AGENTS.md), и при остановке
реплики задача терялась бы. *Альтернатива:* новый статус `deleting` как
забор от `mark_ready`. Отвергнута: замена CHECK, а старые реплики падают
на неизвестном значении enum. Блокировки строки у уборщика (решение 3)
достаточно.
### 2. Уборщик — отдельный процесс
- Пакет `src/cleaner/`: `__main__.py` (ранний обработчик сигналов, как у
API, затем `main()`) и `main.py` (настройки, проверка grace, цикл,
выход). Команда — `python -m src.cleaner [--once]`.
- Свои клиенты, как будущий worker лабы 5 (`infra.md`):
- `create_engine(settings.database)` с пулом 1 (`DATABASE__POOL_SIZE:
1` в окружении сервиса): проход последовательный, второе соединение
не нужно;
- `create_object_storage(settings.s3, namespace=имя базы)` с ключами
уборщика.
Глобалы процесса API (`src/infra/db/session.py`, `s3/instance.py`) не
импортируются.
- Цикл: проход (решение 3), затем ожидание `interval_seconds` или
сигнала. `--once` — один проход и выход: код 0 — проход завершён, 1 —
прерван отказом хранилища или ошибкой, 2 — неверная конфигурация.
- Сигналы:
- `src/infra/early_stop.py` получает имя процесса для записи «Stopped
… before startup»; у API текст прежний;
- после старта цикла — обработчики asyncio. SIGTERM и SIGINT ставят
флаг, текущая строка доводится (не дольше срока шага с БД, 6 с), и
процесс выходит с кодом 0 и записью «Stopped cleaner»;
- `stop_grace_period` 10 с, как у `api`.
- Healthcheck образа (HTTP) в сервисе выключен (`healthcheck: disable:
true`). Живость видна по журналу: старт, проходы, отказы. Уборщик ни
от кого не зависит, никто не ждёт его `healthy`.
- В консоли (`make run_dev`) уборщика нет. Зависшие загрузки консольного
API уберёт уборщик стенда или разовый `docker compose run --rm
--no-deps cleaner --once`. Цель Makefile не заводится: образ для
уборщика собирает `make run_docker`.
*Альтернатива:* фоновая задача в репликах API. Запрещена (AGENTS.md):
N реплик — N уборщиков, а остановка реплики обрывала бы проход.
*Альтернатива:* цель Makefile без расписания. Отвергнута решением
пользователя (`PLAN.md`, решение 7): «вечных» объектов нет только при
регулярном ручном запуске. *Альтернатива:* lifecycle-правила S3 по
возрасту. Отвергнуты: S3 не знает статуса строки и удалил бы и `ready`.
Префикс staging с TTL — вопрос лабы 5. *Альтернатива:* `pg_cron` или
cron-контейнер. Отвергнуты: ещё один образ, S3 из PostgreSQL не
достать, а интервал и grace проще держать в настройках приложения.
### 3. Проход уборки и блокировка строки
Сервис `AttachmentCleanupService(db_scope, storage)`
(`src/core/services/attachment_cleanup.py`), метод
`clean_stale_pending(*, older_than, batch_size)`:
1. `older_than = utcnow() - pending_grace_seconds` — один на проход, по
часам приложения, как срок сессий и ключей идемпотентности.
2. Кандидаты — короткая транзакция: `SELECT id, object_key, created_at
… WHERE status = 'pending' AND created_at < :older_than AND
(created_at, id) > (:after) ORDER BY created_at, id LIMIT
:batch_size`. Это keyset, как у истории, по частичному индексу
(решение 6). Занятая строка не возвращает проход к началу.
3. Каждый кандидат — три шага (после verify W1, «Уточнения apply»,
п. 16; было — одна транзакция с DELETE объекта внутри):
1. транзакция пометки: `SELECT … WHERE id = :id AND status =
'pending' AND created_at < :older_than FOR UPDATE SKIP LOCKED`
(нет строки — её уже убрали, она стала `ready` или её держит
другой процесс: пропуск) → `UPDATE … SET updated_at = utcnow()` →
commit;
2. `storage.delete(object_key)` вне транзакции: 204 и для
отсутствующего объекта;
3. транзакция строки: та же блокировка → `DELETE FROM attachments
WHERE id = :id` → commit.
Отказ S3 прерывает проход: помеченная строка остаётся `pending`,
следующий проход ставит пометку заново (решение 5).
4. Итог — DTO: сколько убрано, сколько пропущено, причина прерывания,
длительность.
Зачем блокировка. Уборщик трогает только строки старше grace, а живая
загрузка короче grace (решение 4). Но процесс API, замороженный дольше
grace, после разморозки дойдёт до `mark_ready`. Без блокировки возможен
такой порядок:
| Загрузка (зомби) | Уборщик |
|---|---|
| PUT — объект записан | |
| | DELETE объекта |
| `mark_ready` — строка `ready`, 201 | |
| | `DELETE … WHERE status = 'pending'` — 0 строк |
Итог — `ready` без объекта: клиент получил 201, скачивание — 500. С
блокировкой `mark_ready` ждёт commit уборщика. Ветка `None` решения 1:
503 и удаление объекта. Если `mark_ready` успел раньше, строка уже
`ready`, и уборщик её не выбирает.
Одной блокировки мало (verify W1). В первой версии блокировка, DELETE
объекта и DELETE строки шли одной транзакцией, и её откат уже после
удачного DELETE в S3 возвращал строку `pending` в прежнем виде. Откат —
сбой БД перед COMMIT, срок 6 с, заморозка уборщика дольше
`idle_in_transaction_session_timeout`. То же, если DELETE в S3 истёк по
сроку, а сервер выполнил его позже. Ждавший `mark_ready` делал такую
строку `ready` без объекта (проба 3 verify). Поэтому пометка: уборщик
до DELETE объекта сдвигает `updated_at` отдельной зафиксированной
транзакцией, а `mark_ready` переводит в `ready` только строку с
`updated_at = created_at`. Вставка пишет оба поля одним значением
(`now`), а пометка — время уборщика, оно позже порога прохода и тем
более `created_at`. Помеченная строка `ready` уже не станет, и любой
исход шагов 2–3 оставляет её `pending`: загрузка получает `None` (503 и
компенсация), уборку доводит следующий проход. Миграции нет, CHECK
`updated_after_created` выполняется.
Блокировку и соединение уборщика держат только короткие транзакции
пометки и удаления строки; DELETE в S3 — между ними, вне транзакции.
Пул у уборщика свой, на реплики это не влияет. Сроки шага: `[s3]
timeout_seconds` (5) и `[database] request_timeout_seconds` (6) <
`idle_in_transaction_session_timeout` (10 с).
Остаток риска, назван в спеке и `REPORT.md`. Процесс API заморожен
дольше grace посреди PUT, уборщик убрал строку, затем после разморозки
S3 принял тело. Компенсации при этом нет: PUT для API завершился
ошибкой по сроку. Или PUT прошёл, `mark_ready` получил `None`, а
удаление при компенсации не удалось. Объект остаётся без строки, его
находит только сверка списком bucket (трек 2). Второй остаток — окно
`make rolling_update` (п. 16): реплики прежней версии пометку не
проверяют.
*Альтернатива:* без блокировки, условие возраста в `mark_ready` (`AND
created_at > :deadline`). Отвергнута: API пришлось бы знать grace
уборщика, а у старых реплик при замене условия нет. *Альтернатива:*
сначала удалить строку, потом объект. Отвергнута: сбой второго шага
оставляет объект без строки, ровно то, что запрещает рубрика.
*Альтернатива:* HEAD перед удалением, чтобы писать в журнал, был ли
объект. Отвергнута: лишний вызов на строку, а промах HEAD не основание
для разрушающего решения (`PLAN.md`, `s3-storage`, «Вопросы», п. 4).
Удаление идемпотентно и так. *Альтернатива:* одна транзакция на всю
выборку. Отвергнута: несколько вызовов S3 подряд превысили бы срок
простоя транзакции (10 с).
### 4. Grace period и его обоснование
Граница живой загрузки B — от записи `created_at` до фиксации `ready`:
- tx1 ≤ `request_timeout_seconds` (6 с; `created_at` назначается до
tx1, ожидание пула внутри срока);
- PUT ≤ `[s3] timeout_seconds` (5 с);
- tx2 ≤ `request_timeout_seconds` (6 с).
B = 2 × 6 + 5 = 17 с. Тело и проверка изображения идут до
`created_at` и в B не входят: медленный клиент B не удлиняет.
Компенсация идёт после неудачи tx2, когда строка уже не станет `ready`,
и тоже не входит.
| Параметр | Рабочий стенд | Стенд отказов | Почему |
|---|---|---|---|
| `pending_grace_seconds` | 900 | 20 | > B = 17. Запас ×50 покрывает заморозку процесса API (профиль `failover` с `docker pause`, остановки ВМ Docker Desktop) и будущие ожидания `upload-memory`. Цена — незавершённые загрузки, а это только сбои, живут до ~16 мин |
| `interval_seconds` | 60 | 1 | наибольший возраст остатка — grace + интервал + проход |
| `batch_size` | 100 | 100 | одна выборка — до 100 строк по индексу |
- Уборщик при старте проверяет `grace > 2 × request_timeout_seconds +
s3.timeout_seconds` по своим настройкам и иначе выходит с кодом 2 и
`error` (спек `service-configuration`). Проверка — в точке входа
уборщика, а не валидатором `Settings`: реплики API от неё не зависят.
`config.toml` у API и уборщика один, поэтому сроки совпадают.
Подмена сроков окружением только у API проверку обошла бы — это
ограничение, оно в `REPORT.md`.
- Часы. `created_at` пишет реплика API, порог считает уборщик, оба по
`utcnow()` на одном хосте Docker. Консольный API на macOS и уборщик в
ВМ Docker Desktop могут разойтись на секунды — это много меньше
запаса grace над B.
- Стенд отказов: grace 20 с — честное значение для сроков обычного API
стенда (по умолчанию). Занижать сроки ради меньшего grace значило бы
обойти проверку.
- `upload-memory`: если он добавит ожидание между `pending` и `ready`
(очередь загрузок), граница и проверка grace расширяются в том же
change. Это строка в `PLAN.md` для него.
*Альтернатива:* 60 с. Отвергнута: запас ×3,5 съедает одна пауза ВМ или
`docker pause` реплики. *Альтернатива:* 24 ч. Отвергнута: остатки сбоев
лежат сутки, защита на рабочем стенде без разового запуска невозможна,
а безопасности сверх ×50 почти не прибавляется.
### 5. Отказы хранилищ в уборщике
- S3 недоступен, не ответил, отказал в доступе или bucket нет
(`ObjectStorageUnavailable`): транзакция строки откатывается, проход
прерывается на первой строке, в журнале `warning` с причиной. Дальше
— через интервал. Удалённый bucket SeaweedFS отдаёт `NoSuchBucket`
(проба), клиент переводит его в 503, строки остаются. Запись
`KNOWN_ISSUES.md` о bootstrap после удаления bucket — трек 2.
- PostgreSQL недоступен (`ServiceUnavailable` общего контекста сессии,
решение 7): проход пропускается, запись `warning` о недоступности
пишет сам контекст.
- Непредвиденная ошибка: `error` с traceback, проход прерывается,
процесс живёт, следующий проход — через интервал. На рабочем стенде
`restart: unless-stopped` поднимет и упавший процесс. На стенде отказов
`restart: "no"`, чтобы падение не пряталось за перезапуском.
- Без перезапуска после возврата хранилища: клиент S3 повторов не
делает и следующий вызов проходит, пул PostgreSQL с `pool_pre_ping`.
### 6. Схема: частичный индекс
Ревизия поверх `ef25d50b01a8`: индекс `ix_attachments_pending_created_at`
на `attachments (created_at, id) WHERE status = 'pending'`. Модель —
`Index(..., postgresql_where=...)` в `Attachment`. Autogenerate условие
не видит (`migrations.md`), ревизия правится руками:
- `with op.get_context().autocommit_block()`: `SET lock_timeout =
'2s'`, `create_index(..., postgresql_concurrently=True,
if_not_exists=True)`, `RESET lock_timeout`. В режиме autocommit `SET
LOCAL` не действует, поэтому уровень сессии и явный сброс;
- `downgrade` — `drop_index(..., postgresql_concurrently=True,
if_exists=True)` так же.
`CONCURRENTLY` не берёт блокировку, запрещающую запись, — правило
`migrations.md` для индексов. Повтор после сбоя проходит благодаря `IF
NOT EXISTS`. Остаток — INVALID-индекс после прерванной сборки: `IF NOT
EXISTS` его не пересоздаст. Способ починки (`DROP INDEX CONCURRENTLY`,
повтор миграции) — в `migrations.md`. Старые реплики индекс не замечают.
Проба — Context.
*Альтернатива:* обычный `CREATE INDEX` в транзакции миграции. Отвергнута
правилом `migrations.md`: `SHARE` на `attachments` останавливает запись
загрузок на время сборки. *Альтернатива:* без индекса. Отвергнута:
каждые 60 с полный просмотр `attachments`, а стоимость обхода — тема
трека 2.
### 7. Общий контекст короткой сессии
Тело `db_session_scope` (срок, `is_db_unavailable` → `invalidate()`,
`warning`, `ServiceUnavailable`) переезжает в `src/infra/db/`:
`session_scope(session_factory, *, timeout_seconds)`. `db_session_scope`
и `get_db_session` в `dependencies.py` остаются тонкими обёртками над
ним с фабрикой API, поведение API прежнее. Уборщик строит свой `db_scope`
той же функцией со своей фабрикой. Это и задел для worker лабы 5.
*Альтернатива:* копия функции в `src/cleaner/`. Отвергнута: два места с
логикой перевода отказа БД разошлись бы.
### 8. Права S3 уборщика и bootstrap
- Пользователь `cleaner`, политика `cleaner-objects`: `s3:GetObject` и
`s3:DeleteObject` на `arn:aws:s3:::<bucket>/*`. Записи, списка и прав на
bucket нет. Чтение уборщику сейчас не нужно: HEAD он не делает,
решение 3. Оно оставлено по решению пользователя («чтение/удаление»)
как задел для глубокой сверки трека 2 (SHA-256 объекта). `s3:ListBucket`
— `track2-reconciler`, если понадобится.
- Ключи — `S3_CLEANER_ACCESS_KEY` и `S3_CLEANER_SECRET_KEY` в `.env`:
`make env_setup` генерирует их для нового `.env`, в compose — с `:?`
«copy S3 lines from .env.example», как остальные секреты S3. Получают
их только `s3-bootstrap` и `cleaner`.
- `infra/s3/bootstrap.sh`, режим `apply`: шаги пользователя (`apply_user`)
становятся общими для пользователя, политики и пары ключей. Порядок:
bucket → политики → пользователи → проверки. Новый секрет любого
пользователя распознаётся по `SignatureDoesNotMatch`, как у API.
Ожидание, пока ключ дойдёт до шлюза: у API — PUT проверочного объекта,
у уборщика — DELETE несуществующего ключа (PUT ему запрещён). Ждём
204.
- Проверки каждого запуска — спек `object-storage`, «Проверка
приватности вне API»:
- ключ API пишет и читает объект;
- ключ уборщика его читает, получает 403 на запись и список, затем
удаляет;
- GET ключом API после удаления — 404.
Режим `check` (`make s3_check`): строки ключа уборщика по таблице
пробы — свой и чужой bucket, административные запросы. Для DELETE
берётся свой проверочный объект, общий нужен проверкам с хоста.
- `driver.py s3-check` печатает новые строки без изменений кода
разбора: строки приходят из bootstrap.
*Альтернатива:* только `s3:DeleteObject` — по пробе хватает. Отвергнута
только потому, что пользователь задал «чтение/удаление» и это задел
трека 2. Отличие — одна строка политики. *Альтернатива:* ключ API у
уборщика. Отвергнута: у API есть запись, и решение 7 `PLAN.md` требует
своих прав.
### 9. Стенд
- Сервис `cleaner` в `docker-compose.yml`:
- `image: mtusi-messenger:lab4`, `pull_policy: never`, `entrypoint:
["python", "-m", "src.cleaner"]` («Уточнения apply», п. 6),
`restart: unless-stopped`;
- окружение — `x-db-env` и `DATABASE__POOL_SIZE: "1"`. S3 — адрес,
порт и bucket тем же якорем, что у `api` (якорь делится на адрес и
ключи), ключи — `S3_CLEANER_*`;
- `config.toml` read-only, `depends_on`: `postgres` healthy, `migrate`
и `s3-bootstrap` completed successfully;
- healthcheck выключен (решение 2), `stop_grace_period: 10s`, портов
нет;
- лимиты стартово 0,25 CPU / 256 МБ, по замеру `docker stats` в apply
(по пробе `s3-storage` клиент S3 — ~+45 MiB RSS к интерпретатору).
Соединений PostgreSQL на стенде: `API_REPLICAS × pool_size` +
`migrate` + уборщик = 2 × 10 + 1 + 1, при замене 3 × 10 + 1 + 1 ≤ 100.
Расчёт и сумма лимитов — в `REPORT.md`.
- `scripts/restart.sh` не меняется. Уборщик не хранилище и не реплика
API, рестарт PostgreSQL и S3 он переживает сам (решение 5).
`test-persistence` от него не зависит.
- `scripts/rolling-update.sh` не меняется. Уборщик, как bootstrap, он не
трогает. Новый код уборщика — `docker compose up -d --no-deps cleaner`
или `make run_docker`. Старый код уборщика на новой схеме работает:
миграция только добавляет индекс. Строка — в `balancer.md`.
- `bench/`:
- `compose_env` генерирует `S3_CLEANER_*` (фильтр паспорта по
`SECRET`/`ACCESS_KEY` их уже скрывает);
- `bench.compose.yml` описывает `cleaner` как `s3`: образ стенда, без
`config.toml`, `restart: "no"`;
- профили его не запускают: сервисы перечислены, реплики — с
`--no-deps`.
- `make test_isolated` не меняется. Уборщик рабочего стенда работает
только со строками рабочей базы и её префиксом. Объекты `test_<db>/`
он не видит, их убирает уборка прогона.
- Шаг оператора для существующего `.env` — две строки секретов (вопрос
`PLAN.md`, `### upload-consistency`). До него любая команда compose
останавливается на `:?`, в том числе `make failure_checks` и `make
test_isolated`.
### 10. Тесты отказов
Стенд отказов (`run_failures.py`, `failures.compose.yml`):
- после bootstrap запускается `cleaner` (`up -d --no-deps cleaner`), в
override — `CLEANER__PENDING_GRACE_SECONDS: "20"`,
`CLEANER__INTERVAL_SECONDS: "1"`, `restart: "no"`;
- значения уходят тестам: `FAULT_CLEANER_GRACE_S`,
`FAULT_CLEANER_INTERVAL_S` из конфигурации compose, как
`storage_names`;
- при падении выводится и журнал уборщика.
Действия hook (`fault_hook.py`, только stdlib):
| Действие | Что делает |
|---|---|
| `attachment-ids` | строки `<id> <status>` всех вложений базы стенда (psql) |
| `last-pending` | `id` самого нового вложения в статусе `pending` или пусто (замечание S6) |
| `object-ids` | `id` вложений, у которых есть файл `original` в `/buckets/<bucket>/<db>/attachments` — по файлам из `fs.tree`, а не по каталогам (Context, п. 1) |
| `fail-attachments insert\|ready\|stall <filename>` | триггер: `insert` — вставка строки с этим `filename` падает, `ready` — перевод такой строки в `ready` падает, оба с SQLSTATE `08006` (класс «отказ соединения», для API это 503: проба); `stall` — перевод в `ready` ждёт `pg_sleep(4)`, меньше `statement_timeout` 5 с |
| `clear-fail-attachments` | убрать триггер и функцию |
| `kill-api` / `start-api` | `docker kill` / `docker start` контейнера `<проект>-api` — обычного API стенда, имя из `FAULT_PROJECT`. После `start-api` ждём `healthy` образа |
`count-attachments` и `count-objects` заменяются этими списками: проверки
сравнивают множества `id`, а не числа (Context, п. 2). Объекты без
строки — `object-ids − attachment-ids`, по префиксу базы стенда.
Тесты и сценарии (маркеры `spec`; `G` — grace, `I` — интервал стенда
отказов):
| Тест | Сценарии | Ход |
|---|---|---|
| `test_upload_with_object_storage_stopped` (меняется) | `attachments` «Запись в S3 не удалась», «Незавершённая загрузка не видна» | S3 `stop` → загрузка 503 → новый `id` из множеств — `pending`, готовые те же → по `last-pending` метаданные, байты и сообщение со ссылкой — 404 с тем же `message`, что у случайного `id` → текст 201 → S3 `start` → та же загрузка 201 |
| `test_rejected_uploads_leave_nothing` (меняется) | «Отклонённая загрузка ничего не оставляет» | новых `id` в обоих списках нет |
| `test_metadata_insert_failure` | «Сбой записи метаданных» | `fail-attachments insert` → 503 → новых `id` нет ни в строках, ни в объектах |
| `test_interrupted_body` | «Обрыв передачи тела» | итератор тела отдаёт 1 MiB и бросает исключение → у клиента ошибка транспорта → новых `id` нет → следующая загрузка 201 |
| `test_ready_failure_compensated` | «Фиксация ready не удалась», `storage-consistency` «Свежая загрузка не тронута», «Зависшая загрузка убрана» | `fail-attachments ready` → 503 → `id` = `last-pending`, объекта уже нет → на ~G/2 строка ещё `pending` (уборщик сделал ~10 проходов) → не позже G + I + запаса строки нет, объектов без строки нет |
| `test_object_storage_paused` (меняется) | «S3 завис», «Зависшая загрузка убрана» | как было, плюс после `unpause`: строка и объект этой загрузки убраны после G, объектов без строки нет |
| `test_killed_between_put_and_ready` | «Объект без фиксации убран» | `fail-attachments stall` → загрузка в потоке → появился `last-pending` → `kill-api` → у клиента нет 201 → строка `pending` и объект есть → `start-api` → после G ни строки, ни объекта, объектов без строки нет, загрузка 201 |
| `test_cleaner_survives_outages` | «S3 недоступен во время уборки», «БД недоступна во время уборки», «Готовые вложения не тронуты» | готовое вложение R → S3 `stop` → загрузка 503 (строка X) → `outage stop postgres` на ~3 с → ждём G + 3I при остановленном S3: X ещё `pending` → S3 `start` → X убрана за I + запаса → R: метаданные 200, байты с тем же SHA-256 |
Времена: запас поверх G + I — 5 с (проход, hook, планировщик Docker
Desktop). Клиенты потоков — со сроком 30 с. Новые тесты добавляют к `make
failure_checks` около 2 мин. В `test_killed_between_put_and_ready` окно
для `kill-api` — 4 с задержки триггера. `last-pending` через psql отвечает
за 0,1–0,3 с, PUT 100 КБ длится миллисекунды, поэтому к моменту `kill`
объект уже записан, а `ready` ждёт в триггере.
Соседство с прежними тестами:
- `test_pool_keeps_connections` считает новые сессии PostgreSQL.
Соединение уборщика одно, держится в пуле с `pool_pre_ping` и после
обрыва (`fill-connections`) восстанавливается за интервал 1 с. Тест
ждёт 11 с до калибровки и калибруется двумя вызовами, так что
переподключение в окно не попадает. Если попадёт, калибровка назовёт
шум;
- `fill-connections` обрывает и соединение уборщика. Его повторы раз в
1 с медленнее попыток hook (0,05 с), слоты держит hook.
### 11. Драйвер, evidence, отчёт
`driver.py --port <LB> upload-consistency` на рабочем стенде (только
stdlib, Python 3.9):
1. синтетические участники и чат, готовое вложение R;
2. `docker compose pause s3` → загрузка через LB — 503 (срок 5 с) →
`unpause`. Строка `pending` по psql (`id`, статус, возраст, ключ), по
`id` метаданные, байты и ссылка в сообщении — 404;
3. триггер «фиксация `ready` падает» на рабочей базе, только для
уникального `filename` прогона. Он снимается в `finally`, а остаток
прерванного прогона — в начале следующего. Загрузка — 503 → строка
`pending`, объекта нет (компенсация);
4. ожидание grace прогона (30 с > B) → `docker compose run --rm
--no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once` — его
вывод;
5. psql и `fs.tree`: строк и объектов обеих загрузок нет, объектов без
строки под префиксом рабочей базы нет; R скачивается с тем же SHA-256.
Код 1 при любом расхождении. Токенов и секретов в выводе нет. Это
evidence `evidence/attachments/consistency.md` и пункт 4 сценария
защиты. Уборщик сервиса (grace 900 с) эти строки не трогает.
Разовый запуск и сервис не мешают друг другу (`SKIP LOCKED`).
Evidence (с закоммиченного кода):
- `evidence/attachments/consistency.md` — `driver.py
upload-consistency` и журнал сервиса `cleaner`;
- `evidence/tests/failure-checks.md` — `make failure_checks` с новыми
тестами;
- `evidence/s3/cleaner-key.md` — `make s3_check` со строками ключа
уборщика и `docker compose config` (секреты по сервисам);
- `evidence/attachments/cleaner-process.md` — процесс уборщика:
- запись о старте с параметрами по умолчанию;
- отказ старта при grace 17 с и при интервале 0 и `abc`;
- `docker compose stop cleaner` — время и код выхода;
- остановка во время старта;
- `docker stats` под лимитом;
- `evidence/migrations/pending-index.md` — ревизия с нуля, повтор,
откат, `indisvalid`, план выборки кандидатов (`EXPLAIN`) по индексу на
данных.
`REPORT.md`:
- раздел «Согласованность БД и S3» — таблица решения 1, уборщик,
блокировка, grace с расчётом B, права S3, отказы;
- ответ на вопрос защиты «PUT прошёл, COMMIT нет»: строка `pending` с
ключом уже в БД. Сбой до COMMIT — компенсация. Исход COMMIT неизвестен
— объект не трогаем, решает уборщик по строке после grace. Процесс
убит — уборщик. Остаток — заморозка дольше grace посреди PUT, трек 2;
- строки таблицы доказательств уровня «4», строка уборщика в таблице
сервисов, расчёт соединений и лимитов;
- ограничения: остаток решения 3, проверка grace по настройкам
уборщика, вложения `ready` без ссылок, пустые каталоги SeaweedFS
(~2 мин), до +5 с к ответу 503 при компенсации, если S3 медлит.
### 12. Задел для трека 2
- Capability `storage-consistency`: сверка и её классы расхождений
добавятся требованиями к ней.
- Пакет `src/cleaner/` с проходами: сейчас один, `stale_pending`.
Reconciler добавит проходы сверки, режимы `--dry-run` и `--apply` и,
если понадобится, `s3:ListBucket` пользователю `cleaner` (одна строка
политики bootstrap).
- Частичный индекс и keyset прохода — база для замера стоимости обхода.
## Risks / Trade-offs
- [Заморозка процесса API дольше grace посреди PUT оставляет объект без
строки; то же — PUT прошёл после уборки, а удаление при компенсации не
удалось] → вероятность — заморозка дольше 15 мин ровно посреди PUT
(и для второго случая ещё отказ S3 на компенсации); запас grace ×50
над B; `error` в журнале у ветки `None`, `warning` «Attachment object
kept for cleaner»; находит сверка трека 2. В спеке и `REPORT.md`
названо прямо.
- [`ready` без объекта при откате транзакции уборщика после удачного
DELETE в S3 (verify W1)] → закрыто пометкой строки отдельной
транзакцией до DELETE объекта (решение 3, «Уточнения apply», п. 16).
Остаток — окно `make rolling_update`: реплики прежней версии
пометку не проверяют, прежний уборщик её не ставит. Оно длится до
конца замены и `docker compose up -d --no-deps cleaner`, нужен ещё и
зомби дольше grace — ограничение в `REPORT.md`.
- [Три шага на строку вместо одной транзакции: SIGTERM посреди строки
мог бы ждать 6 + 5 + 6 с при зависших хранилищах] → флаг остановки
проверяется и между шагами, доводится только текущий шаг (≤ 6 с <
10 с `stop_grace_period`). Требование `graceful-shutdown` уточнено.
- [Компенсация добавляет до 5 с к ответу 503, если S3 стал медленным
после удачного PUT] → только ветка сбоя tx2. Худший путь загрузки и
так длиннее `timeout server` HAProxy (`attachments`, Risks). Пересмотр
цепочки — `upload-memory`.
- [Транзакции уборщика держат блокировку строки] → только короткие
транзакции пометки и удаления строки и только строки старше grace;
DELETE в S3 — между ними, вне транзакции (после verify W1).
`mark_ready` зомби-загрузки подождёт — это и нужно. Пул уборщика свой
(1 соединение).
- [Долгий отказ S3 копит строки `pending`: каждая попытка загрузки — одна
строка] → после возврата S3 уборщик убирает их выборками по 100 через
индекс. Стоимость обхода — трек 2.
- [Шаг оператора `.env` блокирует compose до переноса строк] → понятное
сообщение `:?`, вопрос в `PLAN.md`, команда переноса в `REPORT.md`.
- [Тайминги тестов отказов] → запас 5 с поверх G + I, окно `kill-api`
4 с при отклике hook 0,1–0,3 с, пороги ниже «плохого» поведения на
порядок (`student-tests.md`).
- [Пустые каталоги `<id>/` в filer живут ~2 мин после DELETE] → hook
считает файлы `original`. В списке S3 их нет (проба), это не объекты.
Учесть сверке трека 2.
- [Проверка grace опирается на сроки из настроек уборщика] → `config.toml`
общий. Подмена сроков окружением только у API — ограничение в
`REPORT.md`.
- [После `make rolling_update` уборщик на прежнем образе] → схема
только расширяется, прежний код уборщика корректен. Обновление —
`docker compose up -d --no-deps cleaner` (`balancer.md`).
- [Уборщик на стенде отказов зашумит прежние тесты] → разобрано в
решении 10. Если `test_pool_keeps_connections` поймает шум, его
калибровка это назовёт. Тогда в apply — пауза уборщика hook-ом на окно
теста.
## Migration Plan
1. Настройки и константы, общий контекст сессии (решение 7), имя
процесса в `early_stop`.
2. Модель и ревизия индекса (решение 6): с нуля, повтор, откат, план.
3. Repo, `AttachmentService` (решение 1), сервис уборки (решение 3),
пакет `src/cleaner/` (решение 2).
4. Bootstrap, `.env.example`, `env_setup`, compose, `bench/`. Шаг
оператора: строки `S3_CLEANER_*` в рабочем `.env`.
5. Hook, стенд отказов, тесты, sync дельт в основные спеки (сверка
покрытия читает только `openspec/specs/`, как в `attachments`),
`make failure_checks`.
6. Драйвер, правила, AGENTS.md, `PLAN.md`; регресс; commit после
подтверждения; evidence; `REPORT.md`.
На рабочем стенде — `make run_docker`. Будут пересозданы:
- `migrate` — индекс `CONCURRENTLY`;
- `s3-bootstrap` — пользователь `cleaner`;
- реплики API разом, раз образ новый;
- `cleaner` запускается.
Без простоя — `make rolling_update`, затем `docker compose up -d
s3-bootstrap cleaner`. Bootstrap только добавляет пользователя и права у
API не забирает (`balancer.md`).
Откат — `make rolling_update COMMIT=d9d44c5 MIGRATE=0` и `docker compose
stop cleaner`. Индекс и пользователь `cleaner` остаются, прежнему коду
они не мешают. Строки `pending` снова копятся до возврата вперёд.
## Open Questions
- ~~Перенос `S3_CLEANER_ACCESS_KEY` и `S3_CLEANER_SECRET_KEY` в рабочий
`.env`~~ — закрыт ответом основной сессии 2026-10-21 (`PLAN.md`,
`### upload-consistency` → «Вопросы», п. 1): `make env_setup`
дописывает недостающие переменные шаблона. «Уточнения apply», п. 1.
## Уточнения apply
1. **`make env_setup` дописывает недостающие переменные** (ответ
основной сессии на вопрос 1 `PLAN.md`). В существующий `.env` в
конец, под комментарием `# added by make env_setup from
.env.example`, уходят строки `NAME=…` шаблона, имени которых в `.env`
нет: секреты — той же подстановкой случайных значений, что для
нового `.env` (`ENV_FILLED` в `Makefile`), остальные — значениями
шаблона (`ENV_APPEND_MISSING`, awk). Прежние строки не меняются, в
вывод — только имена. Это меняет прежнее правило `settings.md`
(«существующий `.env` не меняется, строки переносятся руками»), поэтому
в дельты добавлены абзац и сценарий «Недостающие переменные в
существующем `.env`» (`service-configuration`, «Подключение к S3») и
уточнение `container-run` («Запуск через compose»); спеки
синхронизированы. Проверка во временном каталоге: `.env` прежнего
шаблона (без `S3_CLEANER_*`) → `make env_setup` → «added to existing
.env: S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY», SHA-256 прежних
строк тот же, повтор ничего не дописывает, два новых `.env` — секреты
непустые и разные (по хэшам). В рабочем каталоге — те же две строки.
2. **Статус в запросах уборщика — константа, а не параметр.** SQLAlchemy
передаёт `status = 'pending'` параметром (`$1::VARCHAR`), а условие
частичного индекса планировщик доказывает только по константе: общий
план подготовленного выражения asyncpg (после пяти выполнений) индекс
не взял бы. В `_stale_pending` — `literal(..., literal_execute=True)`:
значение в тексте запроса, остальное — параметры. План (временная база
с той же схемой: 20 000 `ready` и 2 000 `pending` за 2 ч, `SET
plan_cache_mode = force_generic_plan`, `PREPARE` текста запроса
repo): первая страница и страница после ключа — `Index Scan using
ix_attachments_pending_created_at`, `Index Cond: (created_at < $1)` и
`ROW(created_at, id) > ROW($2, $3)`, 100 строк, 28–29 буферов, 0,03–
0,04 мс. Снят на временной базе, а не на рабочей в откатываемой
транзакции: на рабочей индекса в тот момент ещё не было (миграция —
`make run_docker` позже). Evidence с рабочей базы — задача 10.2.
3. **Проверка ревизии индекса** (временная база `ucidx_probe` в
контейнере стенда, затем `DROP DATABASE`): `upgrade head` с нуля →
повтор (0 ревизий) → `downgrade -1` (индекса нет) → `upgrade`
(`indisvalid` true); `alembic_version`, откаченный на
`ef25d50b01a8` при существующем индексе, — повтор проходит (`IF NOT
EXISTS`). `alembic upgrade head --sql`: `CREATE INDEX CONCURRENTLY IF
NOT EXISTS …` между `COMMIT` прежних ревизий и `BEGIN` записи версии.
4. **Остановка посреди прохода.** У `clean_stale_pending` параметр
`stop_requested` (по умолчанию «никогда»): проверяется перед каждой
строкой, и по SIGTERM проход доводит текущую строку и не берёт новые
(спек `graceful-shutdown`, «Остановка уборщика»). Причина в итоге —
`interrupted_by="stop"`, запись прохода `info`, `--once` — код 0.
Флаг цикла один проверял бы только между проходами, а проход из
многих выборок длиннее 10 с.
5. **Неверные настройки уборщика** — не traceback pydantic, а одна запись
«Invalid cleaner settings» (`loc` и `msg` ошибок без значений полей:
там могут быть секреты) и код 2, как у отказа по grace. Запись — через
`early_stop.write_record` (общая с записью ранней остановки): логгер
читает те же настройки и не настроен. Проверено: grace 17 —
`error` с grace, обоими сроками и границей 17, код 2, без обращений к
хранилищам; `CLEANER__INTERVAL_SECONDS=0` и `abc` — код 2.
6. **`entrypoint`, а не `command` у сервиса `cleaner`.** С `command`
разовый `docker compose run --rm --no-deps cleaner --once` заменял
команду на `--once` («executable file not found»), найдено первым
прогоном драйвера. Точка входа `python -m src.cleaner`, аргументы
после имени сервиса — флаги уборщика.
7. **Компенсация** — `_mark_ready` и `_compensate` в
`AttachmentService`: флаг «COMMIT отправлен» ставится перед
`commit()` только при найденной строке, поэтому `mark_ready` → `None`
со сбоем самого `commit()` тоже компенсируется (ничего не станет
`ready`). Записи: `warning` «Attachment upload left pending»
(`step` `put` / `ready` / `commit`), `info` «Deleted attachment
object» / `warning` «Attachment object kept for cleaner», `error`
«Pending attachment was removed before ready».
8. **`session_scope`** — `src/infra/db/scope.py`, модуль журнала
`database` (было `api_dependencies`; других записей у того логгера не
было). В `db/__init__.py` не экспортируется: иначе `alembic` при
импорте моделей настраивал бы логгер.
9. **Тесты отказов, красный прогон до кода.** Новые тесты и hook против
прежней ветки `mark_ready` (временная правка `upload`, возвращена) и
без уборщика (`docker compose -p mtusi-lab4-failures stop cleaner`
сразу после старта): 4 failed, 7 passed —
`test_ready_failure_compensated` (объект остался после 503),
`test_killed_between_put_and_ready`, `test_cleaner_survives_outages`,
`test_object_storage_paused` (строки никто не убрал). «Сбой записи
метаданных», «Обрыв передачи тела», «Незавершённая загрузка не
видна» прежний код уже выполнял — тесты закрепляют поведение.
Зелёный полный `make failure_checks`: 29 passed за 190 с (было ~70 с),
вся команда 208 с, журнал PostgreSQL без признаков аварии,
`StartedAt` рабочего стенда прежний, контейнеров и volumes стенда
отказов после команды нет.
10. **`make failure_checks FAULT_ARGS='-k health'`** из задачи 6.2 не
выбирает ни одного теста (имена — `test_readiness_*`, маркер `spec`
в `-k` не входит): pytest код 5, команда — ненулевой код, журналы API
и уборщика выведены, стенд удалён — то есть это проверка «Упавшая
проверка», а не «строка уборщика при коде 0». Строка `start cleaner:
grace 20 s, interval 1 s` при коде 0 — в полном прогоне (п. 9).
11. **Рабочая база.** Первый консольный `python -m src.cleaner --once`
в apply убрал одну строку `pending` возрастом ~5,4 ч — остаток прогона
S3-отказа change `attachments`; объекта у неё не было.
12. **Лимиты уборщика** — 0,25 CPU / 256 МБ оставлены: в простое
`docker stats` — ~91 MiB, проходы на стенде — десятки миллисекунд.
13. **`test-persistence` и уборщик.** `make test-persistence` — PASS;
у контейнера уборщика прежний `StartedAt` и `RestartCount` 0, разовый
`cleaner --once` после рестарта — код 0. Записи `warning` об отказе в
этот раз нет: при интервале 60 с проход не попал в окно рестарта
PostgreSQL и S3 (~25 с). Работу уборщика при отказах хранилищ
доказывает `test_cleaner_survives_outages` (интервал 1 с).
14. **Регресс.** `make bench_quick`, `bench_failover_quick`,
`bench_rollout_quick` (замена `e656d6bbe1a4 → 739b8f04d5fb`, индекс
`CONCURRENTLY` под нагрузкой, ошибок 0, сообщений = ключей),
`bench_restore_quick` — код 0; `make test` — PASS lab4, `make
student_test` через LB — 197 passed (сверка: 212 сценариев, 33 —
проверками отказов), `make test_isolated` — 192 passed, 5 skipped,
`make test-failover` (stop и kill) — PASS, `make s3_check` — 68
проверок, код 0, `driver.py stop-at-start` — PASS («Stopped API
before startup» прежняя), финальный `make failure_checks` — 29
passed.
15. **Окно 0 у уборщика** (evidence, задача 10.2): `docker compose
stop cleaner` сразу после `up -d` (до 0,05 с) — сигнал теряется до
раннего обработчика (PID 1 без обработчика), SIGKILL через 10 с,
код 137; с 0,05 с — «Stopped cleaner before startup», код 0 за 0,2 с.
То же ограничение, что у API (`run-modes.md`, «окно 0»), названо в
`REPORT.md`; данных не портит. В apply пауза 0,3 с его не задевала.
Правки по verify 2026-10-21 (0 CRITICAL, 4 WARNING, 1 SUGGESTION; решения
основной сессии, tasks, группа 11):
16. **W1 закрыт кодом: пометка строки до удаления объекта** (решение 3,
Risks). Уборщик: `lock_stale_pending` → `mark_removing` (`updated_at
= utcnow()`) → commit; `delete_original`; `lock_stale_pending` →
`delete_attachment` → commit. `mark_ready` — `AND updated_at =
created_at`, помеченная строка — `None`, то есть прежняя ветка
«строку убрал уборщик» (503 и компенсация). Проверено:
- вставка `pending` пишет оба поля одним `now` — и в текущем коде, и
в `d9d44c5` (`git show`): строки, вставленные прежними репликами,
новый `mark_ready` переводит в `ready` как раньше;
- пометка строго позже `created_at`: строка выбрана по `created_at <
older_than`, а `utcnow()` уборщика позже `older_than`;
- повтор после сбоя между транзакциями идемпотентен — пометка
ставится заново, следующий проход доводит строку;
- окно `make rolling_update`: реплики прежней версии (`f2dc0b3`)
условия не знают, а скрипт уборщика не пересоздаёт (прежний
уборщик не помечает). До конца замены и `docker compose up -d
--no-deps cleaner` остаётся прежний риск W1, это ограничение
(`balancer.md`, `REPORT.md`). Смешанные версии друг другу не
мешают: прежний уборщик с новыми репликами — поведение до правки,
новый уборщик с прежними репликами — тоже.
Три шага вместо одной транзакции удлиняют худший SIGTERM посреди
строки до 6 + 5 + 6 с при зависших хранилищах. Поэтому
`stop_requested()` проверяется и между шагами (доводится только
текущий, ≤ 6 с < 10 с), а требование `graceful-shutdown` «Остановка
уборщика» уточнено: «довести текущий шаг уборки … новых шагов не
начинать», в дельте и основном спеке. Попутно итог прохода называет
`interrupted_by="stop"` и после последней строки выборки (раньше —
`None`).
Тест — `test_cleaner_failure_after_object_delete`, режим hook
`undeletable` (вставка на час старше, ожидание перевода в `ready`,
удаление строки падает с 08006); сценарий «Сбой уборки после удаления
объекта» (`storage-consistency`, «Безопасность уборки»). Красный на
коде `f2dc0b3` (`make failure_checks FAULT_ARGS='-k "commit_outcome
or outlives or failure_after_object"'`: 1 failed, 2 passed) — 201
вместо 503 за 4,6 с: уборщик удалил объект, откатился на DELETE
строки, ждавший `mark_ready` перевёл её в `ready`. Зелёный полный
`make failure_checks` на новом коде — 32 passed за 222 с, вся
команда 239 с, журнал PostgreSQL без признаков аварии, стенд отказов
удалён.
17. **W2 — тест ветки «исход COMMIT неизвестен».** Режим hook `commit`:
`CREATE CONSTRAINT TRIGGER … AFTER UPDATE DEFERRABLE INITIALLY
DEFERRED`, 08006 на COMMIT перевода в `ready`. Тест
`test_ready_commit_outcome_unknown`, сценарий «Исход фиксации
неизвестен» (`attachments`, «Порядок записи»). На `f2dc0b3` зелёный
(код верен, как в пробе 1 verify); красный на временной регрессии
«компенсация на любой сбой» (`if not commit_sent` → всегда): объекта
нет сразу после 503. Правка возвращена (`git diff` файла пуст).
18. **W3 — тест ветки «строку убрал уборщик до `ready`».** Режим hook
`outlive`: вставка на час старше — `created_at` и `updated_at`
вместе, иначе после п. 16 строка выглядела бы помеченной и тест
проверял бы не ту ветку; ожидание перевода в `ready` до 4,5 с в
триггере уровня оператора, пока строка `pending` не исчезнет.
Триггер — `BEFORE UPDATE OF status`, а не любой `UPDATE`: пометка
уборщика меняет только `updated_at`, и общий триггер заставил бы
ждать и её (уборщик ждал бы исчезновения строки, которую сам держит,
до 4,5 с). Тест `test_upload_outlives_grace`, сценарий «Загрузка
дольше grace» (`storage-consistency`). На `f2dc0b3` зелёный; красный
на временном возврате `RuntimeError`: 500 вместо 503. Правка
возвращена.
19. **W4 — evidence «Отказ S3 во время прохода»** — после коммита
основной сессии (раздел в `evidence/attachments/cleaner-process.md`).
20. **S1** — `docker.md`, раздел «Уборщик»: `entrypoint`, как в
`docker-compose.yml`, и почему не `command` (п. 6).