31 KiB
Tasks
Как строить — design.md (дальше «решение N»), что должно получиться —
дельты в specs/. Порядок — design, Migration Plan, но тесты и hook
пишутся первыми: так красный прогон снимается без checkout и stash.
Перед первым файлом слоя прочитать его правило: service-layer.md,
repo-layer.md, dto.md, infra.md, migrations.md, logging.md,
settings.md, run-modes.md, docker.md, balancer.md,
student-tests.md, api-contract.md, bench.md.
Commit делает основная сессия после подтверждения пользователя
(bench.md, «Измеренное состояние — commit»). Evidence — только с
закоммиченного кода. Временные проекты compose, их volumes, сети и
образы убираются сразу после проверки. Список volumes сверяется с
исходным: docker volume ls -q | sort | shasum. Volumes
mtusi-lab4_postgres_data и mtusi-lab4_s3_data не удаляются никогда.
Вопрос преподавателю об ответе API на потерянный оригинал открыт
(PLAN.md, ### track2-reconciler → «Вопросы», п. 1). Строится вариант
по умолчанию: метаданные — 200, байты — 404 после пометки и 500 до неё,
ссылка — 201. Ответ «иначе» меняет задачи 5.1 и 1.3 (тест «Потерянный
оригинал») и сценарий attachments, остальное — нет.
Ожидаемо красное по ходу работы, остальное разбирается по AGENTS.md:
- между задачами 1.3 и 9.1 сверка покрытия в
make student_testпадает на маркерах новых сценариев («marker points to unknown scenario»); - до задачи 12.2 —
test_exclusion_evidence_existsне меняется: исключений этот change не добавляет.
1. Hook, стенд отказов, тесты и красный прогон
-
1.1
student-tests/fault_hook.pyпо решению 11 (только stdlib, синтаксис 3.9, docstring — новые действия):put-object <ключ>: тело из stdin,docker exec -i <проект>-api python -c …— botocore образа с ключами API из окружения контейнера;delete-object <ключ>:weed shell fs.rm /buckets/<bucket>/<ключ>. Ключ у обоих — только под<FAULT_DATABASE>/attachments/, символы[A-Za-z0-9._/-], иначе код 2;delete-row,set-size,age-row,lost-ids— psql, значения только переменными psql;fail-attachments mark <filename>— отдельный триггерBEFORE UPDATE OF lost_at. Его снимаетclear-fail-attachments, прежние режимы новой колонки не касаются;reconcile dry-run|apply [<предел>]:compose_runпроекта, записи процесса и строкаexit_code=<n>, код hook — 0;stop|start cleaner;run-cleaner <секунд>: контейнер<проект>-cleaner-scheduledсRECONCILER__INTERVAL_SECONDS=1, затемdocker stop, журнал иdocker rm.
Ключей и секретов hook не печатает и не получает. Проверка:
make lint; поведение — 1.4 и группа 9. -
1.2 Стенд отказов:
failures.compose.yml: уcleaner—RECONCILER__INTERVAL_SECONDS: "0"с комментарием (решение 9);run_failures.py:<проект>-cleaner-scheduled— в списке уборки и журналов при падении; строкаstart cleanerназывает и интервал сверки.
Проверка:
make failure_checks FAULT_ARGS='-k readiness'— стенд поднят и убран, контейнеров и volumes проекта отказов после команды нет.Apply: вместо отдельного
-k readiness— прогоны-k reconcileи полный 9.2: строка «start cleaner: grace 20 s, interval 1 s, reconcile interval 0 s (0 — off)», после команды контейнеров проекта отказов 0, volumes — 155, как до. -
1.3 Тесты в
student-tests/test_failures.pyпо таблице решения 11 — восемь тестов с маркерамиfaultиspec:test_reconcile_finds_and_fixes;test_reconcile_keeps_fresh_used_and_unknown;test_reconcile_restored_original;test_reconcile_change_limit;test_reconcile_object_storage_stopped;test_reconcile_interrupted_by_database;test_reconcile_under_load;test_scheduled_reconcile.
Как устроены:
- помощники разбора записей сверки (
Found/Fixed/Finished,exit_code) — в начале раздела; - фильтр — по своим
idи ключам; - код выхода сверяется с записями того же прохода (решение 11);
- объекты без строки ждут G + 1 с, остальные —
age-row; - остановки —
with outage(...); - клиенты потоков — со сроком 30 с.
-
1.4 Красный прогон до кода групп 2–7:
make failure_checks FAULT_ARGS='-k reconcile'на нынешнем коде (5f4b9ff). Ожидаемо падают все восемь: командыreconcileнет (argparse — код 2), колонкиlost_atнет (lost-ids— ошибка hook). Число упавших и причины — в tasks при прогоне и в разделе красного прогонаevidence/tests/failure-checks.md(задача 12.6). Рабочий стенд не трогается.Прогон (2026-10-22): код приложения
c13df14(код тот же, что5f4b9ff: после него только документы), тесты окончательные —git archive c13df14в scratch с тестами и hook рабочего дерева,python3 student-tests/run_failures.py -k reconcile: 8 failed за 95 с. Причины:lost-idsиfail-attachments mark— нет колонкиlost_at(finds_and_fixes,under_load,interrupted_by_database); командыreconcileнет — код 2 и ни одной записи (keeps_fresh_used_and_ unknown,restored_original,change_limit— 2 вместо 3,object_storage_stopped— 2 вместо 1); плановой сверки нет —scheduled_reconcile. Первый прогон того же кода до правок тестов тоже дал 8 failed (вывод обрезан). Сводка без токенов — для 12.6.
2. Настройки, константы, enum и DTO
-
2.1 Секция
[reconciler]по решению 10 и дельтеservice-configuration:- класс
Reconcilerвsrc/config/settings.py:interval_seconds(float, ≥ 0, 3600),page_size(int, 1–1000, 1000),max_changes(int, ≥ 1, 100); - поле
reconcilerвSettings; - строки с комментариями в
config_example.toml.
Проверка:
uv run python -c "from src.config import settings; print(settings.reconciler)"— значения по умолчанию;RECONCILER__PAGE_SIZE=5000,RECONCILER__MAX_CHANGES=0иRECONCILER__INTERVAL_SECONDS=-1— ошибка проверки называет поле. - класс
-
2.2 Типы по решению 8 и
dto.md:ReconcileFinding(StrEnum) вsrc/schemas/enums/attachment.py;ReconcileFindingDTO,ReconcilePassDTOвsrc/schemas/dataclasses/attachment.py;AttachmentFullDTO.lost_at: datetime | None = None— последним полем;RECONCILE_FINDINGS_LOGGED_MAX = 1000вsrc/utils/constants.py;- реэкспорт в
__init__.pyпо алфавиту.
Проверка:
make lint.
3. Схема
-
3.1 Колонка
lost_atпо решению 6:- модель
Attachment—lost_at: Mapped[datetime | None](DateTime(timezone=True)); - ревизия поверх
739b8f04d5fb: первой строкойSET LOCAL lock_timeout = '2s',add_column;downgrade—drop_columnс тем же сроком.
Проверка на временной базе (
createdbв контейнереpostgres,DATABASE__NAMEв окружении, затемDROP DATABASE):upgradeс нуля → повтор без изменений →downgrade -1→upgrade;uv run alembic upgrade head --sql—SET LOCAL lock_timeoutпередALTER TABLE attachments ADD COLUMN lost_at;\d attachments— колонкаtimestamptzбез значения по умолчанию.
Вывод — для evidence 12.5.
- модель
4. Клиент S3 и repo
-
4.1
src/infra/s3/client.pyпо решению 3 и дельтеobject-storage:StoredObjectInfo.last_modified(из LIST и HEAD);- страница списка
list_page(prefix, *, token, max_keys)—list_objects_v2, результат — ключи с размером и временем плюс токен продолжения; - вызов без
Keyв_call(общий срок и перевод ошибок); NoSuchBucketиAccessDeniedна списке —ObjectStorageUnavailableс прежними записямиerror.
Проверка:
make lint; поведение — 4.4 и группа 9. -
4.2
src/core/repos/attachment_object.py:list_originals— префикс<namespace>/attachments/;parse_original_key—UUIDдля ключа вида<id>/originalв нижнем регистре, иначеNone;head_original;probe_originals— список сMaxKeys=1: bucket на месте и список разрешён.
Проверка:
make lint. -
4.3
src/core/repos/attachment.pyпо решениям 3–5 (одно выражение на функцию,repo-layer.md):_ATTACHMENT_COLUMNS+lost_at;- выборка страницы по
id = ANY(:ids) OR object_key = ANY(:keys); - keyset строк
readyпоid; find_attachment_reference(id, key);mark_lostиclear_lost— условныйUPDATE … RETURNING id.
Проверка:
make lint; на временной базе с ≥ 10 000 строкready—EXPLAIN (ANALYZE, BUFFERS)выборки страницы (Bitmap OR поpk_attachmentsиuq_attachments_object_keyили только pk при пустомkeys) и keyset (Index Scanpk_attachments). Итог — в design, «Уточнения apply». -
4.4 Проверка клиента и repo на временном проекте compose. Как в пробе design, Context: SeaweedFS на tmpfs и bootstrap группы 8.1. Ключ уборщика:
- список своего префикса страницами по 1000 — все ключи и
LastModified; - весь bucket и чужой префикс —
ObjectStorageUnavailable(«denied access»); - удалённый bucket —
ObjectStorageUnavailable(«bucket is missing»), а не пустая страница.
Проект и его ресурсы убраны.
- список своего префикса страницами по 1000 — все ключи и
5. API: потерянный оригинал
- 5.1
AttachmentService.open_contentпо решению 5 и дельтеattachments:lost_atзадан —info«Attachment content is lost» (attachment_id,object_key) иAttachmentNotFoundдо обращения к S3. Без пометки и без объекта — 500, как было. Метаданные иMessageServiceне меняются. Проверка:make lint; тесты 1.3 «Потерянный оригинал»;make test_isolated— прежние тесты вложений зелёные.
6. Сервис сверки
-
6.1
AttachmentReconcileService(db_scope, storage)вsrc/core/services/attachment_reconcile.pyпо решениям 3, 4, 7 и 8:- шаги «S3 → БД», «БД → S3», зависшие загрузки;
- перепроверка и проверка bucket до решения;
- предел изменений;
- действия по порядку решения 7;
stop_requestedмежду страницами и действиями;- итог —
ReconcilePassDTO; - записи журнала по дельте
service-loggingи не большеRECONCILE_FINDINGS_LOGGED_MAXзаписей находок; - уборка зависших — через
AttachmentCleanupService.
Проверка:
make lint; поведение — группа 9.
7. Процесс уборщика
-
7.1
src/cleaner/main.py(и__main__.py, если нужно) по решениям 1, 8 и 9:- команда
reconcile [--apply] [--max-changes N](N≥ 1), коды 0 / 3 / 1 / 2; - общая подготовка с сервисом: проверка grace, сигналы,
early_stop.disarm(), engine, клиент S3; - плановая сверка в цикле сервиса (при старте, затем через
[reconciler] interval_seconds, 0 — нет); - «Started cleaner» с параметрами сверки и режимом;
--once— как было.
Проверка без стенда:
RECONCILER__PAGE_SIZE=5000 uv run python -m src.cleaner reconcile— «Invalid cleaner settings» сreconciler.page_size, код 2;CLEANER__PENDING_GRACE_SECONDS=17 … reconcile— код 2 до обращения к хранилищам;… reconcile --max-changes 0— ошибка аргумента, код 2;make lint.
- команда
8. Стенд
-
8.1 Права S3 по решению 2 и дельте
object-storage:infra/s3/bootstrap.sh:S3_CLEANER_LIST_PREFIX(проверка^[a-z0-9_]+/attachments/$, иначе «FAILED» и код 1);- политика
cleaner-objectsсs3:ListBucketи условиемs3:prefix; - проверки
apply— список префикса 200, всего bucket 403; - строки режима
check— свой префикс 200, без префикса 403, чужой префикс 403, чужой bucket 403; - шапка скрипта;
docker-compose.yml:S3_CLEANER_LIST_PREFIX: ${POSTGRES_DB:?…}/attachments/уs3-bootstrap.
Проверка на временном проекте compose — tmpfs, синтетические секреты, bootstrap проекта:
- первый запуск и повтор дважды — код 0;
- неверный префикс — код 1 и шаг в сообщении;
- строки
checkс ожидаемыми кодами.
Затем на рабочем стенде
docker compose up -d s3-bootstrapиmake s3_check— код 0, строки списка ключом уборщика есть. Проект пробы убран, volumes сверены.Apply: проба
rcapply— design, «Уточнения apply», п. 14 (код 0 трижды, 7 неверных префиксов — код 1, строкиcheckожидаемые); проект удалён, volumes — 155, как до. Шаг на рабочем стенде (up -d s3-bootstrap,make s3_check) перенесён в 12.1: рабочий стенд в apply не перестраивается (поручение основной сессии), аmake s3_checkс новымbootstrap.shна прежней политике ждёт 200 на списке и упадёт. -
8.2
Makefile: цельreconcile($(DC) run --rm --no-deps cleaner reconcile,APPLY=1→--apply,MAX_CHANGES=N→--max-changes N) с комментарием в стиле файла. Проверка:make -n reconcile APPLY=1 MAX_CHANGES=5печатает команду с обоими флагами,make -n reconcile— без них. -
8.3
bench/: bootstrap профиляuploadsполучает префикс изbench.env(POSTGRES_DB=bench). Секретов не прибавилось,compose_envне меняется. Вbench.compose.ymlу описанногоcleaner—RECONCILER__INTERVAL_SECONDS: "0": профиль сверкиtrack2-reconcile-costвключит её сам. Проверка:make bench_uploads_quick— код 0 (bootstrap с префиксом прошёл), меткаquick-*в git не идёт.Apply: префикс приходит из
docker-compose.yml(${POSTGRES_DB}изbench.env—bench/attachments/),run.pyне менялся.make bench_uploads_quick(2026-10-22, меткаquick-uploads-20261022T161946Z, в.gitignore) — «s3 healthy, bootstrap done», 6/6 прогонов за 4 мин 31 с; предупреждение хоста о swap — это не замер. Контейнеровmtusi-bench*после — 0, volumes — 155.
9. Спеки и проверки отказов
-
9.1 Sync дельт в основные спеки — все семь capability, как в прежних changes: сверка покрытия читает только
openspec/specs/. Purposestorage-consistency— без «добавят следующие changes»: сверка описана. Проверка:openspec validate track2-reconciler --strict;make student_testчерез LB —test_coverage.pyзелёный, сверка называет новые сценарииstorage-consistencyиattachmentsпокрытыми проверками отказов.
Apply: семь спеков синхронизированы руками (Edit), каждый блок сверен
diffс дельтой — совпадает.openspec validate track2-reconciler --strict— valid,openspec validate --specs --strict— 24 passed.make student_test BASE_URL=http://localhost:8090(рабочий стенд на прежнем коде: новых тестов внеfaultнет) — 198 passed, «coverage: 240 scenarios in 13 specs, 223 tested (58 by make failure_checks), 17 excluded». -
9.2 Полный
make failure_checksна дереве после групп 2–8: все проверки зелёные (прежние 37 и новые 8), журнал PostgreSQL стенда без признаков аварии, стенд отказов удалён,StartedAtрабочего стенда прежний. Время прогона — в tasks. Два прогона одновременно не запускать (student-tests.md).Прогон 2026-10-22 (дерево apply): 45 passed за 458 с pytest, вся команда — 8 мин 01 с;
postgres log: 442 lines, crash markers 0; "too many clients" 24, "administrator command" 142;results: {'fault': 0, 'postgres': 0}.StartedAtвсех контейнеровmtusi-lab4до и после — прежние, контейнеровmtusi-lab4-failures— 0, volumes — 155. До этого два прогона-k reconcileна новом коде падали на дефектах тестов и hook (design, «Уточнения apply», пп. 15 и 17), не кода.
10. Драйвер скилла
-
10.1
driver.py reconcile-cycleпо решению 12 — только стенд с LB, без LB код 2. Шаги:- исходный dry-run;
- внесение расхождений с обеих сторон;
- ожидание grace прогона 30 с;
- dry-run со снимками до и после;
- 500 до сверки,
--apply, 404 и 200 после; - повтор, удаление чужого объекта, повтор с кодом 0;
- свежий объект после grace;
- возврат оригинала.
Триггер
commit— на уникальныйfilename, снимается вfinallyи в начале следующего прогона. Таблицы без токенов и секретов, код 1 при расхождении. Проверка: прогон на рабочем стенде (--port 8090) — код 0; повторный прогон — снова 0, и исходный dry-run не находит остатков прошлого.Apply: рабочий стенд ещё на прежнем коде (без колонки, политики и команды; перестройка — 12.1), поэтому проверено на временном полном стенде
rcdrv(docker-compose.ymlпроекта + override с хранилищами на tmpfs, синтетические секреты, LB на127.0.0.1:18091; драйвер — сCOMPOSE_PROJECT_NAME,COMPOSE_FILE,COMPOSE_ENV_FILES): первый прогон — 45 проверок, PASS, код 0, 1 мин 36 с; повторный — код 0, исходный dry-run:found={},lost_known=1(C прошлого прогона). Там же проверена остановка уборщика во время сверки приpause s3:docker compose stop cleaner— 4,7 с, код 0, «Finished reconcile pass» сinterrupted_by: stopи «Stopped cleaner». Прогон на рабочем стенде — 12.2. Стендrcdrvудалён, volumes — 155. -
10.2
driver.py reconcile-stress [--seconds S] [--clients N]по решению 12. Шаги:- предусловие — dry-run с grace 20 с, иначе код 2;
- внесённые расхождения;
- загрузки и отправки через LB, поток
--applyраз в ~3 с; - итоговая таблица и сверка SHA-256 каждого 201.
Проверка: прогон на рабочем стенде — код 0, несовпадений 0.
Apply: на том же временном стенде
rcdrv— код 0, 649 загрузок 201 (клиенты с паузой 0,2 с: без неё 4 клиента за 40 с записали 5 818 объектов по 100 KiB, для рабочего bucket это лишнее), 8 проходов--applyс кодом 0, исправленоmissing_object=2,orphan_object=2, несовпадений SHA-256 0, повтор — 0. Прогон на рабочем стенде — 12.3. -
10.3
SKILL.mdскилла: обе команды, их evidence и что они меняют на стенде (синтетические вложения, помеченные потерянными, остаются в рабочей базе). Строкиs3-checkприходят из bootstrap, разбор не меняется — проверить выводmake s3_check.
11. Правила и документы
-
11.1 Правила:
service-layer.md— сервис сверки, порядок действий, ветка 404;repo-layer.md— новые функции;dto.md—lost_at, DTO сверки, enum;infra.md— список клиента,last_modified, префикс;migrations.md— ревизияlost_at;docker.md— политикаcleaner-objects,S3_CLEANER_LIST_PREFIX, уборщик на время восстановления БД;settings.md—[reconciler];logging.md— журнал сверки;run-modes.md— командаreconcile, плановая сверка, коды;api-contract.md— 404 потерянного оригинала и вопрос;student-tests.md— действия hook, тесты, интервал сверки 0 на стенде отказов;balancer.md— порядок обновления (решение 6).
Проверка: в каждом правиле — ссылка на design этого change.
-
11.2 AGENTS.md:
- абзац инвариантов «Лаба 4, сверка» (что удаляется и что никогда, grace, предел, права S3, 404);
- карта кода —
attachment_reconcile.py, новые функции repo, команда уборщика; - таблица команд —
make reconcile,driver.py reconcile-cycle,reconcile-stress; - вступление — change в архиве, когда он будет заархивирован.
Apply: абзац, карта кода и команды — сделаны; вступление — при архивировании (change ещё активен).
-
11.3
KNOWN_ISSUES.md, запись «Bootstrap после удаления bucket», по решению 14: причина (слоты томов на маленьком диске,-volume.max=0), проба на 4 и 16 ГБ, стенды проекта не затронуты, предложение. Запись остаётся открытой.
12. Прогоны и evidence
-
12.1 Commit кода (основная сессия, после подтверждения). Затем рабочий стенд по порядку решения 6:
docker compose up -d s3-bootstrap;make rolling_update;docker compose up -d --no-deps cleaner.
Проверка:
- журнал уборщика — плановая сверка при старте без находок;
make reconcile— код 0;make test BASE_URL=http://localhost:8090;make student_test BASE_URL=http://localhost:8090;make test-persistence ACTION_SCRIPT=scripts/restart.shиmake test-failover ACTION_SCRIPT=scripts/stop-one.shдля обеих реплик — сBASE_URLLB;make s3_check.
Сделано 2026-10-22 16:32–16:38 UTC, commit
c1648d9:up -d s3-bootstrap— код 0, «cleaner key get/delete and list messenger/attachments/» (политика на стенде уже стояла: её применил bootstrap изmake test_isolatedв apply);make rolling_update APP_OUT_PORT=8090— 12 с,739b8f04d5fb→5c3e1f0a9b7d, реплики151df4af59c3,b5c48ae854d1, старые —exit 0;up -d --no-deps cleaner— плановая сверка при старте: 2 086 объектов и строк,found {};make reconcile— код 0;make s3_check— 70 проверок, PASS;make test— PASS;make student_test— 198 passed;make test-persistence— PASS;make test-failover— PASS дляb5c48ae854d1(113 записей, восстановление 1,6 с) и151df4af59c3(118, 1,2 с), между нимиmake replicas. LB остался на8090. -
12.2
evidence/reconcile/cycle.md— выводdriver.py --port 8090 reconcile-cycleс датой и commit. -
12.3
evidence/reconcile/stress.md— выводdriver.py --port 8090 reconcile-stress. -
12.4
evidence/reconcile/service.md:- «Started cleaner» с параметрами сверки;
- плановая сверка при старте;
docker compose stop cleanerво время сверки приdocker compose pause s3— время, код 0, записи прерывания и остановки; затемunpause;- отказ старта с
RECONCILER__PAGE_SIZE=5000; - коды разового прохода 0 и 3.
-
12.5 Остальное evidence:
evidence/s3/cleaner-list.md— bootstrap с новой политикой,make s3_check, окружениеs3-bootstrapвdocker compose config;evidence/migrations/lost-at.md— вывод 3.1 иmake rolling_update12.1 с ревизией до и после.
-
12.6
evidence/tests/:failure-checks.md— полный прогон и раздел красного прогона 1.4;student-test-lb.md;- вывод
make test_isolated.
Сделано с
c1648d9:make failure_checks— 45 из 45 за 462 с (8 мин 07 с), crash markers 0, рабочий стенд не тронут; раздел красного прогона (8 из 8 наc13df14);make student_testчерез LB — 198 passed, сверка 240 / 223 / 58 / 17;make test_isolated— 193 passed, 5 skipped, код 0, префиксtest_messenger/и база убраны. -
12.7 Регресс:
make bench_quick;bench_failover_quick;bench_rollout_quick(заменаe1161f7→ новая ревизия под нагрузкой, ошибок 0, сообщений = ключей);bench_restore_quick;make test_isolated— код 0 у каждой.
Метки
quick-*в git не идут.Сделано 2026-10-22 с
c1648d9(в паспортахdirty: true— только неотслеживаемые файлыevidence/):bench_quick— 18/18, код 0 (прерванный паузой лимита прогон 16:58 переснят, его каталог удалён);bench_failover_quick— 4/4, ошибок 0–2 на фазу (502 приstop/kill, как в прежних метках), сообщений = ключей 9 204;bench_rollout_ quick— заменаe1161f7→ текущий за 8,62 с, ревизияe656d6bbe1a4→5c3e1f0a9b7d, ошибок 0 / 0 / 0, старых после дренажа 0, 7 301 = 7 301;bench_restore_quick— код 0, RTO 5,02 с;make test_isolated— код 0 (12.6). Предупреждения хоста о swap — это не замеры. Контейнеровmtusi-bench*после — 0, volumes — 155;make reconcileна рабочем стенде после всего —found {}, код 0. -
12.8
REPORT.md:- раздел «Сверка хранилищ (трек 2, change
track2-reconciler)» — классы, проход, правила безопасности, предел, права S3, ответы API и вопрос преподавателю, плановая сверка; - строки таблицы доказательств уровня «5» с командами и путями evidence;
- ограничения из design, Risks;
- дополнение ответа на вопрос защиты «PUT прошёл, COMMIT нет».
PLAN.md— строка этапа 5 и решения apply в### track2-reconciler. - раздел «Сверка хранилищ (трек 2, change