75 KiB
Design
Context
Мотивация — proposal.md, раздел Why. Требования — specs/.
Код
Состояние после upload-memory (5f4b9ff):
-
Уборщик.
python -m src.cleaner [--once](src/cleaner/main.py):- свой engine (пул 1) и клиент S3 с ключами пользователя
cleaner; - цикл «проход → ожидание
[cleaner] interval_secondsили сигнала», проверка grace > B = 17 с при старте; - коды 0/1/2.
Проход —
AttachmentCleanupService.clean_stale_pending: кандидаты keyset по частичному индексу, каждая строка в два шага подFOR UPDATE SKIP LOCKED— пометка, затем объект и строка одной транзакцией. Объект без строки и строкуreadyбез объекта он не ищет. - свой engine (пул 1) и клиент S3 с ключами пользователя
-
Права S3 уборщика (
infra/s3/bootstrap.sh, политикаcleaner-objects): толькоs3:GetObjectиs3:DeleteObjectна<bucket>/*. Bootstrap иmake s3_checkпроверяют, что список объектов ключом уборщика — 403. Спекobject-storage(«Ограниченные учётные данные уборщика») прямо запрещает ему список. -
Клиент S3 (
ObjectStorage) умеетput,head,open,delete, списка у него нет._callвсегда передаётKey. Удалённый bucket у HEAD неотличим от отсутствующего ключа, правило —PLAN.md,s3-storage, вопрос 4. -
Скачивание (
AttachmentService.open_content): нет объекта или другой размер —error«Attachment content is missing» / «…size differs» и 500 (AttachmentContentMissing). Строка не меняется. -
Схема
attachments:status IN ('pending', 'ready');- уникальный
object_key— индексuq_attachments_object_key; - частичный индекс
pending; - CHECK
updated_at >= created_at.
Колонки пометки нет. Чтение и вставка перечисляют свои колонки (
_ATTACHMENT_COLUMNS), поэтому новая колонка прежнему коду не мешает. -
Тесты. Стенд отказов запускает уборщика с grace 20 с и интервалом 1 с. Hook умеет
attachment-ids,object-ids(fs.tree),fail-attachments …,kill-api/start-api. Сверка покрытия требует тест или исключение для каждого сценарияstorage-consistency.
Пробы (2026-10-22, scratchpad, проект compose rcprobe)
Стенд пробы:
- SeaweedFS тем же образом и аргументами, что
s3, данные на tmpfs; - PostgreSQL 18.6 на tmpfs;
- клиент botocore в образе
mtusi-messenger:lab4; - bootstrap — сам
infra/s3/bootstrap.shпроекта (read-only).
Volumes не создавались. Проект удалён, список volumes и сетей совпал с исходным (155 и 17).
| Проверка | Результат |
|---|---|
| Ключ уборщика с текущей политикой: список bucket, с префиксом и без, v1 и v2, HEAD bucket | 403 AccessDenied; HEAD отсутствующего ключа — 404, GET — NoSuchKey |
s3:ListBucket на arn:aws:s3:::messenger |
список своего bucket — 200, чужого — 403, HEAD bucket — 200, запись — 403 |
s3:ListBucket с Condition: StringLike s3:prefix messenger/attachments/* |
префикс messenger/attachments/ — 200, весь bucket и test_messenger/ — 403, HEAD bucket — 403, чужой bucket — 403. Условие SeaweedFS 4.48 соблюдает. Постраничный список под этим условием (3 страницы по 1000) — полный |
s3:ListBucket только на ресурсе <bucket>/* |
списка нет (403), как в AWS |
| ListObjectsV2, 2 503 и 20 003 ключа под префиксом, MaxKeys 1000 | 3 и 21 страница, 0,31 с и ~2,0 с (~0,1 мс на ключ); LastModified с точностью до секунды, UTC; Size, ETag; токен продолжения — последний ключ открытым текстом |
Порядок списка на соседях aaa/…, aaa-x, aaa.y/…, aaa0 |
порядок обхода каталогов: aaa/original, aaa/zzz, затем aaa-x. Это не порядок байтов: в нём aaa-x < aaa.y/… < aaa/…. Страницы по одному ключу совпали с одной страницей без пропусков и повторов |
weed shell fs.rm объекта в /buckets/… |
HEAD — 404, в списке объекта нет, пустой каталог <id>/ в список не попадает |
bucket удалён (s3.bucket.delete) |
список с префиксом — 404 NoSuchBucket, GET — NoSuchBucket, HEAD объекта — 404, как отсутствующий ключ |
PostgreSQL, 21 000 строк (20 000 ready), общий план |
ALTER TABLE … ADD COLUMN lost_at timestamptz — 0,36 мс (только каталог). Страница 1000 ключей object_key = ANY($1) OR id = ANY($2) — Bitmap OR двух индексов, 6–7 мс: часть по uq_attachments_object_key — 5,6–6,2 мс (сравнение текста), часть по pk_attachments — 0,3–0,4 мс; один object_key = ANY — 6 мс. Обход ready keyset по id (status, lost_at, updated_at — фильтр) — Index Scan pk_attachments, 1000 строк за 0,4–0,6 мс |
Запись KNOWN_ISSUES.md о bootstrap после удаления bucket
Воспроизведена на пробе и объяснена: дело в слотах томов, а не в повторном имени bucket.
| Стенд | Слотов томов | После s3.bucket.delete и повторного bootstrap |
|---|---|---|
| tmpfs 4 ГБ | 3 из 3 заняты | «bucket created», затем «FAILED: api key wait (code 500)» дважды подряд. В журнале S3 — «No writable volumes and no free volumes left for collection:messenger» |
| tmpfs 16 ГБ | 15 | «bucket created», проверки прошли за 2 с |
Почему так:
- сервер запущен с
-volume.max=0, и число слотов считается по свободному месту / 1 ГиБ; - удаление bucket удаляет томá его коллекции, но на маленьком диске слоты занимают тома коллекции по умолчанию (журналы filer);
- новых томов для
messengerвыделить некуда.
У рабочего стенда volume на диске ВМ: 417 слотов, 403 свободны (weed shell volume.list, только чтение). Там удаление bucket и повтор
bootstrap этим не падают. Решение 14.
Рабочий стенд перед change
Только чтение: 2 019 строк ready, 2 019 файлов original (fs.tree),
строк ready без объекта и объектов без строки — 0, pending — 0.
Goals / Non-Goals
Goals:
- Пункт трека 2 о reconciler (
PLAN.md, этап 5): обе стороны, dry-run,--apply, повтор = 0, стресс с проверкой SHA-256. - Ни при каком порядке действий сверка не удаляет подтверждённое, используемое и свежее (гипотеза 5).
- Остаточные риски
upload-consistencyзакрыты автоматически. PUT-зомби убирает плановая сверка. Строкуreadyбез объекта она помечает, и API отвечает по контракту, а не 500. - Смешанные версии при
make rolling_updateне хуже, чем до change.
Non-Goals:
- Стоимость обхода, стратегии и ограничение скорости —
track2-reconcile-cost(решение 13). - Восстановление байтов потерянного оригинала: их нет нигде.
- Сверка других префиксов bucket (
test_<db>/,.s3-check/) и чужих баз. - Новые статусы вложения. Контракт лабы 4 знает только
ready. - Исправление записи
KNOWN_ISSUES.mdо bootstrap: reconciler bucket не создаёт (решение 14).
Decisions
1. Сверка — часть уборщика
Пакет src/cleaner/ и сервис compose cleaner вырастают в reconciler,
как и задумано (PLAN.md, решение 7; design upload-consistency,
решение 12):
python -m src.cleaner(сервис) — прежний цикл уборки, плюс плановая сверка (решение 9);python -m src.cleaner --once— один проход уборки, как раньше;python -m src.cleaner reconcile [--apply] [--max-changes N]— разовая сверка, по умолчанию dry-run. В compose —docker compose run --rm --no-deps cleaner reconcile …(точка входа ужеpython -m src.cleaner). Цель Makefile —make reconcile [APPLY=1] [MAX_CHANGES=N];- сервис
AttachmentReconcileService(db_scope, storage)(src/core/services/attachment_reconcile.py), методreconcile(*, older_than, apply, max_changes, page_size, batch_size, stop_requested). Зависшие загрузки он отдаётAttachmentCleanupService(решение 7).
Как уборщик и сверка не мешают друг другу на строках pending:
- внутри процесса проходы идут по очереди, одновременно не бывают;
- между процессами (сервис и разовый
run) сверка трогает строкуpendingтолько процедурой уборщика — тот жеFOR UPDATE SKIP LOCKEDи пометка; - объект строки
pendingправило «объект без метаданных» не видит: строка на него ссылается; - пометку потерянного оригинала получает только строка
ready, а её уборщик не выбирает никогда; - все действия безопасно повторять, поэтому и две сверки разом ничего
не ломают: удаление объекта и условный
UPDATEидемпотентны.
Альтернатива: отдельная точка входа python -m src.reconciler, свой
сервис и пользователь S3 reconciler. Отвергнута:
- два процесса с доступом к одной базе, ещё два секрета, пользователь в
bootstrap и строки
make s3_check— ради разделения, которое почти ничего не даёт. У уборщика и так есть ключи всех объектов в БД, чтение и удаление любого объекта bucket. Список по префиксу своей базы (решение 2) добавляет к этому мало; - плановой сверке всё равно нужен долгоживущий процесс, а он уже есть.
Альтернатива: только ручная сверка, без плановой. Отвергнута: PUT-зомби
жил бы до ручного запуска, и остаточный риск upload-consistency остался
бы «навсегда» (решение 9). Альтернатива: фоновая задача реплик API.
Запрещена (AGENTS.md). Альтернатива: lifecycle-правила S3. Отвергнуты:
S3 не знает строк БД.
2. Права S3: список по префиксу вложений своей базы
Политика cleaner-objects получает второй оператор (проба —
Context):
{"Effect": "Allow", "Action": ["s3:ListBucket"],
"Resource": ["arn:aws:s3:::<bucket>"],
"Condition": {"StringLike": {"s3:prefix": ["<база>/attachments/*"]}}}
Чтение и удаление на <bucket>/* — как были.
- Префикс bootstrap получает в
S3_CLEANER_LIST_PREFIX: ${POSTGRES_DB:?…}/attachments/(окружениеs3-bootstrapвdocker-compose.yml). Это не секрет. Скрипт проверяет его по^[a-z0-9_]+/attachments/$и подставляет в JSON только проверенное значение. На стенде отказов и вbench/(POSTGRES_DB=bench) префикс берётся тем же путём. Уборщику его не передают: свой префикс он строит изsettings.database.name, как ключи объектов. - Проверки
apply:- ключ уборщика получает 200 на список с префиксом;
- 403 на список всего bucket — так же, как сейчас «cleaner key list is not denied».
- Режим
check(make s3_check), строки ключа уборщика:- «cleaner key list attachments prefix» — 200;
- «cleaner key list objects» без префикса — 403, как было;
- «cleaner key list other prefix» (
.s3-check/) — 403; - «cleaner key list other bucket» — 403, как было.
- Порядок обновления. Bootstrap только расширяет права и у API ничего не
забирает (
balancer.md). Новый уборщик со старой политикой получаетAccessDeniedна списке: проход сверки прерван,error«Object storage denied access», уборка работает. Поэтому вперёд — сначалаdocker compose up -d s3-bootstrap(решение 6).
Альтернатива: s3:ListBucket без условия. Отвергнута: уборщик видел бы
ключи других баз (test_<db>/) и проверочные объекты, а сверке они не
нужны. Альтернатива: s3:ListBucket на ресурсе <bucket>/*. По пробе
списка не даёт. Альтернатива: сузить по префиксу и чтение с удалением.
Отложена: проверки bootstrap удаляют ключом уборщика свои объекты под
.s3-bootstrap/ и .s3-check/, их пришлось бы переделать. Ключи
объектов уборщик и так берёт из БД своей базы.
3. Классы и проход сверки
Классы — спек storage-consistency, «Сверка bucket и БД». Порог
older_than = utcnow() − [cleaner] pending_grace_seconds один на
проход, по часам приложения, как у уборщика. Проход:
- S3 → БД. Страницы ListObjectsV2 по префиксу
<база>/attachments/([reconciler] page_size, до 1000).- Ключ вида
<база>/attachments/<uuid в нижнем регистре>/original(attachment_object_repo.parse_original_key) даётid. Остальные ключи — «нестандартные». - На страницу — одно выражение к БД:
id = ANY(:ids) OR object_key = ANY(:keys). Здесьids— из стандартных ключей,keys— только нестандартные, обычно их нет. По пробе выборка поidв 15 раз дешевле выборки по тексту ключа. - Классификация без новых вызовов S3:
- строка
idс тем же ключом.pending— пропуск, это дело уборщика.readyбез пометки: размер равен — порядок; другой — кандидат «другой размер», если строка старше порога, иначе «свежая».readyс пометкой: размер равен — кандидат «оригинал вернулся», иначе «уже помечено»; - строка
idс другим ключом — «чужой объект»; - строки нет:
LastModifiedраньше порога — кандидат «объект без метаданных», иначе «свежий объект»; - нестандартный ключ — строка с таким
object_keyесть: как у строки выше, иначе «чужой объект».
- строка
- Каждый ключ попадает в множество
seen.
- Ключ вида
- БД → S3. Keyset по
idпо всем строкамready([reconciler] page_sizeстрок, Index Scanpk_attachments— проба).- Строка без пометки старше порога, ключа которой нет в
seen, — кандидат «метаданные без объекта». - Моложе порога — «свежая».
- С пометкой — «уже помечено», если оригинал не вернулся на шаге 1.
- Строка без пометки старше порога, ключа которой нет в
- Зависшие загрузки — решение 7.
- Перепроверка каждого кандидата непосредственно перед решением, в обоих режимах (решение 4).
- Предел изменений, затем действия, если
--apply(решения 4 и 8).
Действия начинаются, только когда классификация закончена. Отказ хранилища на шагах 1–4 прерывает проход без единого изменения.
Почему множество, а не слияние двух отсортированных потоков. Порядок
списка SeaweedFS — обход каталогов, а не порядок байтов (проба). Слияние
с ORDER BY object_key COLLATE "C" на нестандартных ключах разошлось бы
и дало бы ложные расхождения в обе стороны. Цена множества — память
O(N): ~150 байт на ключ, при 100 тыс. объектов ~15 МБ при лимите
уборщика 256 МБ. Замер — track2-reconcile-cost.
Почему гонка двух снимков (списка и строк) не даёт ложных расхождений:
- объект без метаданных. API пишет строку до PUT (порядок записи
attachments). Если объект попал в список, строка его загрузки уже зафиксирована и видна выборке, которая идёт после списка. Её нет, только если её убрал уборщик, — тогда объект и правда лишний; - метаданные без объекта. Строки моложе порога не проверяются.
Строка старше порога стала
readyраньше начала прохода, а её объект записан ещё раньше. Объектыreadyникто, кроме сбоя, не удаляет, поэтому список их видит. Перепроверка HEAD отсекает и неполный ответ списка.
Альтернатива: HEAD на каждую строку вместо множества — стратегия
следующего change (гипотеза 2). Альтернатива: временная таблица ключей
в PostgreSQL и anti-join. Отвергнута: одна долгая транзакция противоречит
idle_in_transaction_session_timeout и сроку шага 6 с.
4. Правила безопасности
Свойства — спек «Безопасность сверки». Как они держатся:
-
Что можно удалить. Удаление объекта — только у класса «объект без метаданных». Удаление строки — только у зависшей загрузки процедурой уборщика. Строки
ready, используемые вложения (FKmessage_attachmentsи так не даст удалить строку) и объекты, на которые ссылается строка, не попадают ни в один удаляющий класс. -
Свежее.
- Объект: по
LastModifiedS3 (часы ВМ, точность — секунда). - Строка
ready: поupdated_at— время перевода вready. - Строка
pending: поcreated_at, как у уборщика.
Grace общий с уборщиком, его проверка границы живой загрузки (17 с) остаётся.
- Объект: по
-
Перепроверка непосредственно перед решением:
- объект без метаданных: выборка строки по
idили по ключу (find_attachment_reference) — нет; HEAD — объект есть и старше порога. Перед самим DELETE выборка строки — ещё раз. Выборка страницы ищет стандартные ключи только поid(решение 3), поэтому строку с чужимid, которая ссылается на этот ключ (изменённые метаданные), находит именно перепроверка. Такой объект — «чужой объект», и он не удаляется; - метаданные без объекта и другой размер:
get_attachment—ready, без пометки, тот же ключ; HEAD — объекта нет или размер другой; - оригинал вернулся: пометка на месте, HEAD — размер равен;
- не подтвердилось — кандидат выбывает без записи о расхождении.
- объект без метаданных: выборка строки по
-
Bucket на месте. Перед подтверждением отсутствия объектов — список с префиксом и
MaxKeys=1. HEAD bucket при условной политике — 403, проба. Удалённый bucket даётNoSuchBucket, и проход прерван. Пустой, пересозданный bucket проходит проверку, но тогда кандидатов больше предела, и действует он. -
Предел изменений. Число подтверждённых удалений объектов, пометок и снятий пометок сравнивается с
max_changes(100 или аргумент). Больше — ни одного из этих изменений:error, код 3. Уборка зависших загрузок пределом не ограничена: уборщик делает её и без сверки. Предел защищает от сверки с «чужой» базой — пустой или восстановленной из старой копии, при живом bucket — и от пустого bucket. -
Чужой объект — только отчёт и код 3. Удалять то, чего API не пишет, опасно: в лабе 5 под префиксом появятся варианты, а оператор мог положить копию сам.
-
Объект без метаданных удаляется в любой момент после порога. Объект зомби-загрузки удаляет и её компенсация. Два DELETE одного ключа безопасны.
Альтернатива: пометить строку перед действием, как уборщик. Не нужна:
сверка не удаляет строк, а пометка потери — один условный UPDATE.
Альтернатива: относительный предел (доля объектов). Отвергнут: на
маленьком стенде он слишком мал, на большом слишком велик. Абсолютный
предел понятнее оператору, и его легко поднять аргументом.
5. Потерянный оригинал и ответы API
-
Пометка — новая колонка
attachments.lost_at timestamptz NULL: время, когда сверка подтвердила потерю.statusиupdated_atне меняются. Поэтому ответ метаданных прежний,error_code—null, как требует контракт дляready.mark_lost:UPDATE … SET lost_at = :now WHERE id = :id AND status = 'ready' AND lost_at IS NULL AND object_key = :key RETURNING id;clear_lost:… SET lost_at = NULL WHERE id = :id AND lost_at IS NOT NULL AND object_key = :key.
-
API (спек
attachments, «Скачивание оригинала»):- скачивание помеченного — 404
not_foundбез обращения к S3, записьinfo«Attachment content is lost»; - непомеченного без объекта — 500, как было;
- метаданные — 200, как было;
- ссылка в новом сообщении — 201, как на любое
ready.
get_attachmentи DTO получаютlost_at.get_attachmentsиMessageServiceне меняются. - скачивание помеченного — 404
Почему так. В контракте лабы 4 у Attachment.status одно значение —
ready (contracts/openapi.json), поэтому метаданные не могут сказать
«потеряно». Для байтов контракт даёт «Отсутствующий вариант
ready-объекта — 404» (contracts/README.md). 500 — «неожиданное
исключение», а после сверки потеря уже ожидаема. Но прочтения возможны
разные, поэтому это вопрос преподавателю (Open Questions; PLAN.md,
### track2-reconciler). Ответ «иначе» меняет только open_content и
выборку вложений сообщения, спек attachments и тесты. Классы, правила
и проход сверки от него не зависят.
Альтернатива: статус lost или failed в CHECK. Отвергнута:
- контракт лабы 4 его не знает;
- замена CHECK и прежние реплики упали бы на неизвестном значении enum
при
make rolling_update.
Альтернатива: удалить метаданные потерянного вложения, если оно не
используется. Отвергнута: «строку без объекта не восстановить, reconciler
её находит и помечает» (PLAN.md, «Трек 5»). Подтверждённое вложение не
удаляется (гипотеза 5), а клиент с его id получил бы 404 на метаданные
без объяснения. Альтернатива: отдельная таблица находок. Отвергнута:
лишнее соединение в чтении вложения. Отчёт и так в журнале.
6. Схема и смешанные версии
Ревизия поверх 739b8f04d5fb:
- первой строкой
op.execute("SET LOCAL lock_timeout = '2s'")(migrations.md:ACCESS EXCLUSIVEна рабочую таблицу); - затем
add_column('attachments', Column('lost_at', DateTime(timezone= True), nullable=True))— только каталог, 0,36 мс на пробе; downgrade—drop_columnс тем жеlock_timeout.
Модель — lost_at: Mapped[datetime | None]. Индекса нет: сверка
просматривает все строки ready, API читает по id. CHECK «помечено
только ready» не добавляется. Для существующей таблицы это NOT VALID
или скан под блокировкой, а пометку и так ставит только условный
UPDATE.
| Смесь | Что происходит | По сравнению с «до change» |
|---|---|---|
новая схема + прежние реплики (5f4b9ff) |
колонку не читают, у помеченного без объекта — 500 | так же |
| новый уборщик + прежние реплики | пометки ставятся, прежние реплики их не видят (500); объекты без строки удаляются безопасно — порядок записи прежних версий тот же, строка до PUT, с change attachments |
не хуже |
| прежний уборщик + новые реплики | сверки нет, пометок нет | так же |
| новый уборщик + прежняя политика S3 | проход сверки прерван AccessDenied (error), уборка работает |
не хуже |
| новый уборщик на прежней схеме | уборка работает; сверка падает на lost_at, error «Reconcile pass failed», процесс живёт |
не хуже; порядок ниже не даёт такой смеси |
Порядок обновления:
- вперёд —
docker compose up -d s3-bootstrap(политика со списком); - затем
make rolling_update(миграция, затем реплики); - затем
docker compose up -d --no-deps cleaner.
Откат — сначала уборщик (docker compose stop cleaner или прежний
образ), потом make rolling_update COMMIT=<прежний> MIGRATE=0.
Колонка и пометки остаются, прежнему коду они не мешают, а после
возврата вперёд снова действуют.
7. Зависшие загрузки в сверке
- Dry-run: кандидаты —
attachment_repo.get_stale_pendingстраницами[cleaner] batch_size. Каждый — запись сid, ключом и возрастом. Ничего не меняется. --apply:AttachmentCleanupService.clean_stale_pending(older_than=…, batch_size=…, stop_requested=…)— тот же код, что у сервиса уборки: пометка, затем объект и строка одной транзакцией под блокировкой. Число убранных — в итог сверки.- Порядок действий
--apply: зависшие загрузки → объекты без метаданных → пометки → снятия пометок. Остановка (stop_requested) проверяется между действиями.
Альтернатива: сверка зависшие загрузки только называет. Отвергнута:
без работающего уборщика --apply не довёл бы стенд до «повтор = 0», а
общий код ничего не стоит.
8. Отчёт, журнал и коды выхода
-
DTO (
dto.md):ReconcileFindingDTO:kind,object_key,attachment_id,age_seconds,size_bytes,stored_size;ReconcilePassDTO:apply,listed_objects,checked_rows,foundиfixedпо классам,fresh_objects,fresh_rows,lost_known,refused,interrupted_by,duration_ms.
ReconcileFinding—StrEnumвenums/attachment.py:orphan_object,missing_object,size_mismatch,stale_pending,restored_object,unknown_object. Строки репозитория —AttachmentFullDTO, у него новое полеlost_atсо значением по умолчанию. Отдельный тип не нужен. -
Журнал (дельта
service-logging, модульattachment_reconcile_service):- находка —
warning«Found storage discrepancy»; - исправленная —
info«Fixed storage discrepancy» сaction(deleted_object,marked_lost,cleared_lost,removed_pending); - итог — «Finished reconcile pass» (
infoилиwarning); - предел —
error«Reconcile changes exceed limit»; - отдельные записи — первые
RECONCILE_FINDINGS_LOGGED_MAX(1000,constants.py), в итоге — сколько осталось без записи.
- находка —
-
Отчёт разового прохода — те же JSON-записи в stdout. Отдельного формата нет: hook и драйвер разбирают записи
Found/Fixed/Finished. -
Коды разового прохода (спек): 0 / 3 / 1 / 2. Код 3 — и при чужом объекте: он требует внимания оператора, хотя сверка его не тронет. Прерванный сигналом разовый проход — 1, сервис — 0 (дельта
graceful-shutdown).
9. Плановая сверка
-
В цикле сервиса после прохода уборки проверяется срок плановой сверки (
loop.time()против следующего срока):- первая сверка — при старте;
- следующая — через
[reconciler] interval_seconds(3600 с) после конца предыдущей; - 0 — без плановой сверки.
Это тот же
reconcile(apply=True, max_changes=[reconciler] max_changes). Непредвиденная ошибка —errorс traceback, процесс живёт, как у уборки. -
Граница. Объект без метаданных живёт не дольше grace + интервал + проход: ~15 + 60 мин + секунды. Цена на рабочем стенде (2 тыс. объектов) — меньше секунды в час. При 100 тыс. — порядка минуты под лимитом 0,25 CPU: разбор XML списка botocore — Python. Замер и выбор интервала —
track2-reconcile-cost. -
Стенд отказов —
RECONCILER__INTERVAL_SECONDS: "0"вfailures.compose.yml. Иначе плановая сверка исправляла бы расхождения, которые тест внёс и ещё проверяет. Плановую сверку проверяет отдельный уборщик с интервалом 1 с (решение 11).bench/уборщика не запускает. У описанного вbench.compose.ymlуборщика — тоже 0: профиль сверкиtrack2-reconcile-costзадаст интервал сам.
Альтернатива: плановая сверка только с dry-run. Отвергнута: зомби
оставались бы до ручного --apply. Предел и перепроверки делают
автоматическое исправление безопасным. Альтернатива: первая сверка
через интервал после старта. Отвергнута: частые пересоздания уборщика
(make run_docker, обновление) откладывали бы её бесконечно.
10. Настройки
Секция [reconciler] (класс Reconciler, дельта
service-configuration):
interval_seconds— float, ≥ 0, 3600;page_size— int, 1–1000, 1000;max_changes— int, ≥ 1, 100.
Разовая подмена — RECONCILER__*. Grace — [cleaner] pending_grace_seconds, одна ручка «свежести» на всю согласованность. Его
проверка при старте уже есть и действует и на reconcile. Запись
«Started cleaner» называет три новых значения и режим — сервис, --once
или reconcile с apply. Строки — в config_example.toml.
Альтернатива: свой grace_seconds у сверки. Отвергнута: две ручки
«свежести» разошлись бы. Для объектов без строки граница B не нужна, но
меньший grace ничего не даёт, кроме риска.
11. Внедрение ошибок и тесты отказов
Новые действия hook (fault_hook.py, только stdlib, ключи S3 hook не
получает):
| Действие | Что делает |
|---|---|
put-object <ключ> |
тело из stdin. docker exec -i <проект>-api python -c … — botocore образа с ключами API из окружения контейнера пишет объект мимо приложения. Ключ — только под <FAULT_DATABASE>/attachments/, символы [A-Za-z0-9._/-] |
delete-object <ключ> |
weed shell fs.rm /buckets/<bucket>/<ключ> — мимо шлюза S3, с той же проверкой ключа |
delete-row <id>, set-size <id> <байт>, age-row <id> <секунд> |
psql: удалить строку (неиспользуемого вложения), изменить size_bytes, сдвинуть created_at и updated_at назад вместе. CHECK и непомеченность pending сохраняются |
lost-ids |
id строк с lost_at |
fail-attachments mark <filename> |
новый режим: UPDATE, который ставит lost_at строке с этим filename, падает с 08006. Отдельный триггер BEFORE UPDATE OF lost_at, чтобы прежние режимы и их функция не зависели от новой колонки; clear-fail-attachments снимает и его |
reconcile dry-run|apply [<предел>] |
docker compose -p … run --rm --no-deps -T cleaner reconcile [--apply] [--max-changes N]: печатает записи процесса и строку exit_code=<n>, код hook — 0 |
stop|start cleaner |
сервис уборщика стенда (start — up -d --wait --no-recreate) |
run-cleaner <секунд> |
отдельный уборщик <проект>-cleaner-scheduled (run -d, RECONCILER__INTERVAL_SECONDS=1) на N секунд, затем docker stop и его журнал; run_failures.py убирает его вместе с остальными |
Объекты нельзя состарить: LastModified ставит S3. Поэтому тест с
объектом без метаданных ждёт G + 1 с. Строки состаривает age-row, и
там ждать не нужно.
Тесты (маркер fault; G = 20 с — grace стенда):
| Тест | Сценарии | Ход |
|---|---|---|
test_reconcile_finds_and_fixes |
storage-consistency «Расхождения с обеих сторон найдены», «Исправление расхождений», «Повторная сверка»; attachments «Потерянный оригинал» |
with outage(stop cleaner) → вложения A (в сообщении), B, C → put-object O (стандартный ключ), delete-object A, delete-row B, set-size C, загрузка P с fail-attachments commit (строка pending и объект) → ждать G + 1 → dry-run: у своих ключей и id — свои классы, exit_code 3, списки строк, объектов и lost-ids прежние, A — 500 → apply: O и объект B убраны, у P нет ни строки, ни объекта, A и C в lost-ids, A — 404, метаданные A равны ответу загрузки → повтор dry-run: своих расхождений нет, код соответствует записям |
test_reconcile_keeps_fresh_used_and_unknown |
«Свежие не тронуты», «Используемое вложение не удаляется», «Чужой объект не удаляется» | U1 в сообщении — age-row и delete-object; чужой X (…/attachments/x-<uuid>) → ждать G + 1 → свежие: U2 с удалённым объектом и F (put-object) → apply: F и X на месте, U2 не помечено, U1 помечено, метаданные U1 — 200, история отдаёт U1, строк не убыло, X — «чужой», код 3 → уборка X и F через hook |
test_reconcile_restored_original |
«Оригинал вернулся» | R: age-row, delete-object, apply → помечено → put-object R теми же байтами → apply → пометки нет, байты — 200 с тем же SHA-256 |
test_reconcile_change_limit |
«Предел изменений» | L1–L3: age-row, delete-object → apply с пределом 2: код 3, error называет число не меньше 3 и предел 2, lost-ids без L → apply с пределом 100 → помечены все три |
test_reconcile_object_storage_stopped |
«S3 недоступен во время сверки» | M: age-row, delete-object → with outage(stop s3): apply — код 1, M не помечено → после возврата apply помечает |
test_reconcile_interrupted_by_database |
«Прерванная сверка доводится повтором» | N1 (filename f), N2: age-row, delete-object → fail-attachments mark f → apply — код 1 → снять триггер → apply → оба помечены → dry-run без них |
test_reconcile_under_load |
«Сверка под нагрузкой» | внесены 2 объекта без строки и 2 потери (age-row); 4 потока ~G + 15 с загружают ~100 KiB PNG из шума и отправляют сообщения со свежими id; поток сверки — apply раз в 3 с. В конце: внесённые исправлены, каждое 201-вложение скачивается с тем же SHA-256, каждое сообщение отдаёт свои attachment_ids, новые lost-ids (разность до и после) — только внесённые |
test_scheduled_reconcile |
«Плановая сверка без команды» | S: age-row, delete-object → run-cleaner 6 → в журнале «Finished reconcile pass», S в lost-ids |
Тесты фильтруют записи сверки по своим id и ключам. Остатки прежних
тестов (их строки pending) могут попасть в отчёт и в код выхода,
поэтому код сверяется с записями того же прохода, а не с числом.
Уборщик стенда остановлен только в первом тесте и только на его окно
(with outage). Новые тесты добавляют к make failure_checks около
2,5–3 мин.
Красный прогон до кода. Новые тесты против прежнего кода — 5f4b9ff,
команды reconcile нет. Падают все восемь: hook возвращает код 2
команды и ошибку разбора аргументов. Это доказательство, что тесты
проверяют новое поведение. Сверка покрытия: новые сценарии
storage-consistency и attachments синхронизируются в основные спеки в
apply, как в прежних changes (spec_coverage.py читает только
openspec/specs/).
12. Драйвер и evidence
Драйвер скилла (stdlib, Python 3.9), только стенд с LB. Разовая сверка —
docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=<g> cleaner reconcile …, как у upload-consistency.
-
reconcile-cycle→evidence/reconcile/cycle.md:- исходный dry-run с grace по умолчанию: 0 расхождений, иначе код 2,
«стенд не сведён —
make reconcile»; - синтетические участники и вложения через LB;
- расхождения:
- объект без строки —
docker compose exec -T api python -c …с ключами реплики; - удалённые объекты —
weed shell fs.rm; - удалённая строка, изменённый размер — psql;
- обрыв между объектом и фиксацией — временный триггер
commitна уникальныйfilenameрабочей базы, снимается вfinallyи в начале следующего прогона; - чужой объект;
- объект без строки —
- ожидание grace прогона (30 с), затем dry-run: таблица «класс → ключ
→
id→ возраст», снимки строк и объектов до и после совпали; - байты потерянного — 500;
--apply: таблица исправлений; байты — 404, метаданные — 200; история отдаётid;- повтор: исправимых 0, остался чужой. Его удаление оператором — шаг драйвера, затем повтор — код 0. Свежий объект не тронут, а после grace удалён;
- возврат оригинала: «оригинал вернулся», байты — 200 с тем же SHA-256.
Код 1 при любом расхождении. Токенов и секретов в выводе нет.
- исходный dry-run с grace по умолчанию: 0 расхождений, иначе код 2,
«стенд не сведён —
-
reconcile-stress→evidence/reconcile/stress.md:- предусловие — dry-run с grace 20 с без расхождений (иначе код 2);
- внесённые расхождения;
- N клиентов M секунд загружают и отправляют через LB, поток сверки —
--applyс grace 20 с раз в ~3 с; - в конце — таблица: загрузки по кодам, сообщения, проходы и исправления по классам, скачивания с несовпавшим SHA-256 — 0, сообщения с недоступным вложением — 0, повтор — 0.
Это проверка корректности: тихий хост не нужен, паспорт хоста не снимается.
-
Остальное evidence:
evidence/reconcile/service.md— запись о старте с параметрами сверки, плановая сверка при старте,docker compose stop cleanerво время сверки приpause s3(время и код), отказ старта сRECONCILER__PAGE_SIZE=5000;evidence/s3/cleaner-list.md— bootstrap с новой политикой,make s3_checkсо строками списка, окружениеs3-bootstrapвdocker compose config;evidence/migrations/lost-at.md— ревизия с нуля, повтор, откат, сноваupgrade,--sqlсlock_timeout;evidence/tests/—make failure_checks,make student_testчерез LB,make test_isolated.
Регресс:
make bench_rollout_quick(заменаe1161f7→ новая ревизия),bench_failover_quick,bench_restore_quick,bench_quick. -
REPORT.md:- раздел «Сверка хранилищ (трек 2)» — классы, правила, предел, права S3, ответы API, вопрос преподавателю;
- строки таблицы доказательств уровня «5»;
- ограничения (Risks ниже);
- ответ на вопрос защиты «PUT прошёл, COMMIT нет» дополняется: зомби убирает сверка.
13. Граница с track2-reconcile-cost
| Здесь | В track2-reconcile-cost |
|---|---|
| одна стратегия: страницы LIST + одно выражение к БД на страницу, множество ключей, HEAD — только перепроверка найденного | --strategy head — HEAD на строку и выборка на объект (гипотеза 2) |
| поверхностная сверка: наличие и размер из LIST | --deep [--sample N] — SHA-256 чтением объекта, класс «другой SHA-256» (гипотеза 3) |
[reconciler] page_size, interval_seconds, max_changes |
ограничение скорости обхода и его влияние на p95 фоновой нагрузки (гипотеза 4); выбор интервала по замеру |
в итоге прохода — listed_objects, checked_rows, duration_ms |
профиль reconcile стенда bench/: N = 10k / 100k мимо API, доли расхождений, k6, сэмплер, 3 повтора, A/A, графики (гипотеза 1) |
стресс --apply под загрузками — корректность (гипотеза 5) |
выводы по гипотезам 1–5 и ограничения в REPORT.md |
14. Запись KNOWN_ISSUES.md о bootstrap
Причина найдена (Context): слоты томов на маленьком диске, а не
повторное имя bucket. Reconciler bucket не создаёт и не удаляет. На
NoSuchBucket он прерывает проход без изменений, поэтому чинить запись
этому change не нужно.
В apply запись переписывается:
- причина;
- условие — диск, на котором
-volume.max=0даёт мало слотов: tmpfs проб, а не volume стендов проекта; - проба на 16 ГБ;
- предложение на будущее —
-master.volumeSizeLimitMBменьше 1024 или явный-volume.maxна маленьких дисках.
Запись остаётся открытой.
Risks / Trade-offs
- [Источник истины — PostgreSQL: база из старой копии или пустая при
живом bucket] → объекты новых вложений станут «объектами без
метаданных», и до предела изменений сверка их удалит. По истине БД это
верно. Опасно восстановление базы в живую (
pg_restoreповерх) при работающем уборщике: удалились бы объекты строк, которые ещё не восстановлены. Митигация:- предел 100;
- grace по объекту на старые объекты не действует. Поэтому правило в
REPORT.mdиdocker.md: на время восстановления базы уборщик останавливают (docker compose stop cleaner), после — сначалаmake reconcile(dry-run).
- [Чужой объект живёт, пока его не удалит оператор] → код 3 и
warningна каждом проходе плановой сверки — видно в журнале. Удалять непонятное опаснее. - [Повреждение того же размера не видно] → поверхностная сверка сравнивает только размер. SHA-256 — глубокая сверка следующего change. Скачивание отдаёт такие байты и сейчас: API сверяет только размер.
- [Память O(N) на ключи списка] → ~15 МБ на 100 тыс. объектов при лимите уборщика 256 МБ. Замер — следующий change.
- [Плановая сверка задерживает уборку зависших загрузок на время
прохода] → на рабочем стенде — меньше секунды. На 100 тыс. — порядка
минуты при grace 15 мин. Ограничение — в спеке и
REPORT.md. - [Пометка по ложному «нет объекта»] при неполном списке S3 → HEAD
перепроверяет каждый кандидат и проверяет bucket. Остаток — bucket
пересоздан пустым или подменён между перепроверкой и
UPDATE. Тогда пометка верна: объекта правда нет. Она снимается сама, если объект вернётся. - [Две сверки одновременно] — плановая и разовая → действия
идемпотентны, отчёты могут разойтись в числах
fixed. Блокировки нет: проходу пришлось бы держать соединение пула уборщика всё время. - [Часы] →
LastModified— часы ВМ (S3), порог — часы контейнера уборщика, это одни часы. ТочностьLastModified— секунда, при grace 900 с это ничтожно.updated_atстрок пишут реплики. Консольный API на macOS расходится на секунды — меньше grace. - [Ответ API для потерянного оригинала — трактовка контракта] →
вопрос преподавателю. Ответ меняет одну ветку
open_content, сценарий и тест. - [Старый образ уборщика после
make rolling_update] → сверки нет, как до change. Порядок обновления — решение 6, строка вbalancer.md. - [Тесты отказов дольше на ~3 мин] → объекты нельзя состарить, ждать grace (20 с) нужно только тестам объектов без метаданных. Остальные состаривают строки.
Migration Plan
- Hook, стенд отказов и тесты раньше кода; красный прогон на нынешнем
коде (
5f4b9ff). - Настройки
[reconciler], enum и DTO, константа предела записей. - Модель и ревизия
lost_at: с нуля, повтор, откат, сноваupgrade,--sql. - Клиент S3 (список, время объекта), repo,
AttachmentService(404), сервис сверки, пакетsrc/cleaner/(команда, плановая сверка, коды). - Bootstrap (политика, префикс, проверки), compose (
s3-bootstrap),config_example.toml,Makefile(reconcile),bench/. - Sync дельт в основные спеки и правка Purpose
storage-consistency(«Сверку … добавят следующие changes» → сверка есть), полныйmake failure_checks. - Драйвер, правила, AGENTS.md,
KNOWN_ISSUES.md,PLAN.md; регресс; commit после подтверждения; evidence;REPORT.md.
На рабочем стенде — make run_docker: bootstrap обновит политику,
migrate добавит колонку, реплики и уборщик пересоздаются. Без простоя
— порядок решения 6. Первая плановая сверка — при старте нового
уборщика. По Context расхождений на стенде нет, ожидается итог без
находок.
Откат — по решению 6. Пометки остаются в колонке. Политика со списком прежнему уборщику не мешает.
Open Questions
-
Ответ API на потерянный оригинал — вопрос преподавателю (
PLAN.md,### track2-reconciler→ «Вопросы», п. 1). Контракт лабы 4 знает толькоstatus=ready. Есть три близких правила: «Отсутствующий вариант ready-объекта — 404», «404 — объекта нет или он чужой», «Неожиданное исключение — 500». По умолчанию до ответа (решение 5):- метаданные — 200;
- байты — 404 после пометки, 500 до неё;
- ссылка — 201.
Ответ меняет ветку
open_content(и выборку вложений сообщения, если ссылку тоже запретить), сценарийattachments«Потерянный оригинал» и тест. Классы, правила безопасности, схема и задачи сверки не меняются.
Уточнения apply
Решения, принятые в /opsx:apply (2026-10-22) без вопроса пользователю:
мелкие, по спекам и решениям выше.
-
Ответ на потерянный оригинал — вариант (а) по поручению основной сессии: вопрос 1
PLAN.mdоткрыт, сделано по умолчанию (решение 5). -
ReconcileAction— второйStrEnumрядом сReconcileFinding: названия действий в записях «Fixed» (deleted_object,marked_lost,cleared_lost,removed_pending) — значения enum, а не литералы. -
ReconcilePassDTOсверх решения 8:remaining(сколько подтверждённых осталось — по нему код 0 / 3) иunlogged(сколько находок не записано из-заRECONCILE_FINDINGS_LOGGED_MAX).foundиfixed—MappingProxyType: DTO frozen,dictв нём был бы изменяемым (dto.md). -
Шаг уборщика — публичный.
AttachmentCleanupService._removeсталremove_stale_pending(поведение то же,clean_stale_pendingзовёт его), и сверка с--applyубирает зависшие загрузки им по одной, а неclean_stale_pendingцеликом (решение 7): так у каждой убранной загрузки своя запись «Fixed … removed_pending» сid, как у остальных классов, а кандидаты — те же, что в dry-run. -
Какие записи у
--apply. Исправленное — толькоinfo«Fixed», оставшееся (чужой объект, отказ по пределу, прерванный проход) —warning«Found» в конце прохода. Так требует сценарийservice-logging«Журнал разового прохода» (в--apply— две записиinfo, а не четыре). -
Перепроверка и перед самим действием. Шаг 4 перепроверяет всех кандидатов в обоих режимах; с
--applyкаждое действие ещё раз проверяет своё условие непосредственно перед собой: объект без строки —find_attachment_reference, пометка и снятие пометки — HEAD и условныйUPDATE; перед первой пометкой bucket проверяется ещё раз (probe_originals). Не подтвердилось на действии — находка выбывает без записи и не считается оставшейся. -
Свежий чужой объект — свежий. Грейс действует на все объекты списка, в том числе чужие ключи: «свежее не считается расхождением» (спек «Безопасность сверки»). Объект без
LastModifiedсчитается свежим: удалять без доказанного возраста нельзя. -
Отказ после сигнала — остановка. Если вызов S3 или шаг с БД упал, когда сигнал уже пришёл (вызов ждал замороженный S3 до срока),
interrupted_by—stop: этого ждёт сценарийgraceful-shutdown«docker stop во время сверки». Причину отказа всё равно записал нижний слой (object_storage,database). -
404 без тела у списка — отсутствующий bucket. Клиент переводит
NoSuchKey/404уlist_objects_v2в «bucket is missing»: у списка «объекта нет» не бывает, а пустой список вместо ошибки сделал бы удалённый bucket «потерей всех оригиналов». -
Цикл сервиса. После прохода уборки — плановая сверка, если подошёл срок; пауза — меньшее из
[cleaner] interval_secondsи времени до сверки.--onceплановой сверки не делает (как раньше — один проход уборки). -
Проверка префикса bootstrap —
case, а неgrep -x: значение с переводом строки (x\n<база>/attachments/)grep -xпропустил бы по второй строке. Проверка — до любого шага в режимахapplyиcheck. Список своего префикса вapplyпроверяется с ожиданием (wait_key 200): новая политика доходит до шлюза подпиской, как ключ. -
Ревизия
5c3e1f0a9b7d(2026_10_22_1200-…_added_attachments_lost_at.py). Проверка на временной базеrc_lost_at_probeрабочего PostgreSQL: с нуля — все 7 ревизий, повтор — без изменений,downgrade -1и сноваupgrade,\d attachments—lost_at timestamp with time zone, без значения по умолчанию;--sql739b8f04d5fb:head —SET LOCAL lock_timeout = '2s'передALTER TABLE attachments ADD COLUMN lost_at TIMESTAMP WITH TIME ZONE. -
Планы (задача 4.3) — та же база, 21 000 строк (20 000
ready),VACUUM (ANALYZE), общий план (plan_cache_mode = force_generic_plan,PREPAREтекста, который рендерит SQLAlchemy для asyncpg):- страница 1000
id, пустойkeys— Bitmap Heap Scan ← BitmapOr (pk_attachments, 1000 строк, 0,41 мс;uq_attachments_object_key— 0 поисков), 1,5 мс, 652 буфера; - 1000
idи 2 нестандартных ключа — тот же BitmapOr, по ключам — 1 поиск, 0,6 мс; - keyset
readyпоidс середины, 1000 строк — Index Scanpk_attachments(id > $2, статус — фильтр), 0,57 мс.
Параметры — массивы (
= ANY($1::UUID[])), а не списокIN: план не зависит от длины страницы. - страница 1000
-
Проба клиента и bootstrap (задачи 4.4 и 8.1) — проект
rcapply(SeaweedFS проекта на tmpfs 16 ГБ, синтетические секреты, bootstrap иdocker-compose.ymlпроекта): bootstrap трижды — код 0 (bucket и пользователи созданы, затем «exists»); префиксыmessenger/,*,messenger/attachments/x, пустой,a/b/attachments/, с переводом строки,Messenger/attachments/— «FAILED: cleaner list prefix» и код 1;check— «cleaner key list attachments prefix» 200, «… objects», «… other prefix», «… other bucket» 403. Клиентом проекта ключом уборщика: 2 504 ключа под префиксом — 3 страницы по 1000 за 0,29 с, все ключи, у каждогоLastModified; весь bucket, префиксmessenger/other/иtest_messenger/attachments/—ObjectStorageUnavailable(«denied access»,AccessDenied); послеs3.bucket.deleteсписок иprobe_originals—ObjectStorageUnavailable(«bucket is missing»,NoSuchBucket), а не пустая страница. Проект удалён, список volumes совпал с исходным (155). -
Hook:
start cleaner—docker startконтейнера.docker compose start cleanerпроверяет зависимости сервиса, аmigrateстенд запускаетrun --rm— его контейнера нет («cleaner is missing dependency migrate»; найдено первым прогоном новых тестов на новом коде). -
Фикстура
stand(..., stdin=байты)— телоput-object;subprocessфикстуры — в байтовом режиме (stdout и stderr декодируются сами), прежние действия stdin не читают. -
Метаданные состаренных строк.
age-rowсдвигаетcreated_atиupdated_at,set-sizeменяетsize_bytes— это поля ответа API. Тесты сравнивают метаданные помеченных с ответом загрузки без полей, которые изменил сам hook (assert_lost_content(aged=True), у C — размер изset-size); пометка сверки полей ответа не меняет — это проверяет вложение A без таких правок. Первый прогон новых тестов на новом коде падал именно на этом (дефект теста: ожидание противоречило его же внесённому изменению). -
Драйвер на рабочем стенде — только после 12.1.
reconcile-cycleиreconcile-stressнужны колонкаlost_at, новая политика S3 уборщика и образ с командойreconcile; доdocker compose up -d s3-bootstrapиmake rolling_updateсверка на рабочем стенде падает (AccessDeniedна списке, нет колонки). Рабочий стенд в apply не перестраивается (поручение основной сессии), поэтому проверка драйвера в задачах 10.1–10.2 — на временном полном стенде (проект compose с LB, своими хранилищами на tmpfs и портами); на рабочем — в группе 12.
Решения правок по /opsx:verify (2026-10-22, группа 13 tasks):
- Ключ строки вне префикса вложений — чужой объект (W2). Строка
readyстарше порога, ключа которой нет в списке, раньше была кандидатом «метаданные без объекта», и перепроверка делала HEAD по её ключу — в том числе<другая база>/…или<база>/elsewhere/…. Это противоречило абзацу спека «Объекты других баз и ключи вне префикса … MUST NOT читать». Реальный случай — база, восстановленная под другим именем: её строки ведут к объектам исходной базы. Теперь такая строка (и зависшая загрузка с таким ключом — её уборка удалила бы объект по этому ключу) —unknown_objectбез HEAD, без пометки и без уборки, код 3; HEAD, пометка, снятие пометки и удаление объекта ещё раз проверяют префикс (attachment_object_repo.is_own_key). Новый класс не заведён: «чужой объект» уже значит «требует оператора, сверка не меняет» — определение класса в спеке дополнено. Сервис уборки (clean_stale_pending) зависшую загрузку с чужим ключом по-прежнему убирает вместе с объектом по её ключу — это поведениеupload-consistency, а не сверки; запись вKNOWN_ISSUES.md. - Сигнал — перед каждым вызовом хранилища (S1). Раньше между
проверками
stop_requested()бывало два вызова подряд (страница списка → выборка БД,get_attachment→ HEAD, HEAD →mark_lost/clear_lost, ссылки → DELETE, шаг БД →probe_originals), и при деградации S3 и PostgreSQL остановка ждала до ~11 с приstop_grace_period10 с. Теперь_check_stopстоит перед каждым вызовом, и остановка ждёт не больше одного: S3 ≤[s3] timeout_seconds(5 с), шаг с БД ≤ его срока (6 с). Теста нет: окно «первый вызов удался после долгого ожидания, а второй завис» по HTTP детерминированно не воспроизвести; прежний сценарий «docker stop во время сверки» (один зависший вызов) остаётся в evidence, код 1 разового прохода — п. 23. - Ранний отказ по пределу — не в этом change (S4). Мысль: в
--applyпрекращать перепроверку классов под пределом, как только подтверждённых большеmax_changes. Это ломает два инварианта: отчёт называет каждое расхождение (спек «Сверка bucket и БД») — неперепроверенные кандидаты не подтверждены и в отчёт не попали бы; ошибка предела называет число изменений — оно стало бы нижней границей. Поэтому не сделано. Цена при N ≫ предела — SELECT + HEAD на кандидата, ~1–3 мс; при 10 тыс. расхождений — десятки секунд, пока уборка ждёт. Варианты (перепроверка после решения о пределе с отчётом «кандидаты, не перепроверены», отдельный счётчик в итоге, порог «подтверждено > предела» только для плановой сверки) и замер —track2-reconcile-cost(PLAN.md). - Тесты W1 и красные прогоны группы 13. Hook
set-key <id> <ключ>меняет толькоobject_keyстроки (psql, ключ под<FAULT_DATABASE>/, в том числе внеattachments/— для W2). Ветки W1 в коде были верны:test_reconcile_keeps_referenced_objectsиtest_reconcile_limit_keeps_cleanupна кодеa6071da— зелёные, а на временных регрессиях (_recheck_orphanбезfind_attachment_reference;_actпропускает при отказе по пределу и зависшие) — 2 failed: объект<Z>/original, на который ссылается Y, сталorphan_object; зависшая загрузка не убрана. Регрессии убраны,git diff src/после — пусто.test_reconcile_foreign_key_untouchedна кодеa6071da— 1 failed: готовая строка с ключом<база>/elsewhere/<id>—missing_object(HEAD чужого префикса и пометка в--apply), зависшая —stale_pending(уборка удалила бы объект по чужому ключу). - Код 1 разового прохода по SIGTERM (S5) —
driver.py reconcile-signal: на проекте compose из окружения (рабочийmtusi-lab4— отказ, код 2) замораживает S3, запускает разовыйreconcile --applyотдельным контейнером, после «Started cleaner» —docker stop; ждёт код 1, «Finished reconcile pass» сinterrupted_by: stop, «Stopped cleaner» сexit_code1 и остановку быстрееstop_grace_period; S3 размораживается вfinally. Снимок — после commit, на временном стенде.