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

70 KiB
Raw Blame History

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):

  1. 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 без признаков аварии, стенд отказов удалён.

  2. 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 файла пуст).

  3. 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. Правка возвращена.

  4. W4 — evidence «Отказ S3 во время прохода» — после коммита основной сессии (раздел в evidence/attachments/cleaner-process.md).

  5. S1 — docker.md, раздел «Уборщик»: entrypoint, как в docker-compose.yml, и почему не command (п. 6).