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>
853 lines
70 KiB
Markdown
853 lines
70 KiB
Markdown
# 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).
|