598 lines
39 KiB
Markdown
598 lines
39 KiB
Markdown
# 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, стенд отказов, тесты и красный прогон
|
||
|
||
- [x] 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.
|
||
- [x] 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, как до.
|
||
- [x] 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 с.
|
||
- [x] 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
|
||
|
||
- [x] 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` — ошибка проверки называет поле.
|
||
- [x] 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. Схема
|
||
|
||
- [x] 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
|
||
|
||
- [x] 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.
|
||
- [x] 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`.
|
||
- [x] 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 Scan `pk_attachments`). Итог — в
|
||
design, «Уточнения apply».
|
||
- [x] 4.4 Проверка клиента и repo на временном проекте compose. Как в
|
||
пробе design, Context: SeaweedFS на tmpfs и bootstrap группы 8.1. Ключ
|
||
уборщика:
|
||
- список своего префикса страницами по 1000 — все ключи и
|
||
`LastModified`;
|
||
- весь bucket и чужой префикс — `ObjectStorageUnavailable` («denied
|
||
access»);
|
||
- удалённый bucket — `ObjectStorageUnavailable` («bucket is missing»),
|
||
а не пустая страница.
|
||
|
||
Проект и его ресурсы убраны.
|
||
|
||
## 5. API: потерянный оригинал
|
||
|
||
- [x] 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. Сервис сверки
|
||
|
||
- [x] 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. Процесс уборщика
|
||
|
||
- [x] 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. Стенд
|
||
|
||
- [x] 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 на списке и упадёт.
|
||
- [x] 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`
|
||
— без них.
|
||
- [x] 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. Спеки и проверки отказов
|
||
|
||
- [x] 9.1 Sync дельт в основные спеки — все семь capability, как в
|
||
прежних changes: сверка покрытия читает только `openspec/specs/`.
|
||
Purpose `storage-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».
|
||
- [x] 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. Драйвер скилла
|
||
|
||
- [x] 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.
|
||
- [x] 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.
|
||
- [x] 10.3 `SKILL.md` скилла: обе команды, их evidence и что они меняют
|
||
на стенде (синтетические вложения, помеченные потерянными, остаются в
|
||
рабочей базе). Строки `s3-check` приходят из bootstrap, разбор не
|
||
меняется — проверить вывод `make s3_check`.
|
||
|
||
## 11. Правила и документы
|
||
|
||
- [x] 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.
|
||
- [x] 11.2 AGENTS.md:
|
||
- абзац инвариантов «Лаба 4, сверка» (что удаляется и что никогда,
|
||
grace, предел, права S3, 404);
|
||
- карта кода — `attachment_reconcile.py`, новые функции repo, команда
|
||
уборщика;
|
||
- таблица команд — `make reconcile`, `driver.py reconcile-cycle`,
|
||
`reconcile-stress`;
|
||
- вступление — change в архиве, когда он будет заархивирован.
|
||
|
||
Apply: абзац, карта кода и команды — сделаны; вступление — при
|
||
архивировании (change ещё активен).
|
||
- [x] 11.3 `KNOWN_ISSUES.md`, запись «Bootstrap после удаления bucket»,
|
||
по решению 14: причина (слоты томов на маленьком диске, `-volume.max=0`),
|
||
проба на 4 и 16 ГБ, стенды проекта не затронуты, предложение. Запись
|
||
остаётся открытой.
|
||
|
||
## 12. Прогоны и evidence
|
||
|
||
- [x] 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_URL` LB;
|
||
- `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`.
|
||
- [x] 12.2 `evidence/reconcile/cycle.md` — вывод `driver.py --port 8090
|
||
reconcile-cycle` с датой и commit.
|
||
- [x] 12.3 `evidence/reconcile/stress.md` — вывод `driver.py --port 8090
|
||
reconcile-stress`.
|
||
- [x] 12.4 `evidence/reconcile/service.md`:
|
||
- «Started cleaner» с параметрами сверки;
|
||
- плановая сверка при старте;
|
||
- `docker compose stop cleaner` во время сверки при `docker compose
|
||
pause s3` — время, код 0, записи прерывания и остановки; затем
|
||
`unpause`;
|
||
- отказ старта с `RECONCILER__PAGE_SIZE=5000`;
|
||
- коды разового прохода 0 и 3.
|
||
- [x] 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_update`
|
||
12.1 с ревизией до и после.
|
||
- [x] 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/` и база убраны.
|
||
- [x] 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.
|
||
- [x] 12.8 `REPORT.md`:
|
||
- раздел «Сверка хранилищ (трек 2, change `track2-reconciler`)» —
|
||
классы, проход, правила безопасности, предел, права S3, ответы API
|
||
и вопрос преподавателю, плановая сверка;
|
||
- строки таблицы доказательств уровня «5» с командами и путями
|
||
evidence;
|
||
- ограничения из design, Risks;
|
||
- дополнение ответа на вопрос защиты «PUT прошёл, COMMIT нет».
|
||
|
||
`PLAN.md` — строка этапа 5 и решения apply в `### track2-reconciler`.
|
||
|
||
## 13. Замечания проверки
|
||
|
||
Находки `/opsx:verify` (2026-10-22, CRITICAL нет). Цикл проекта: тест до
|
||
кода, его падение на текущем коде с названной причиной, затем код. Пробы
|
||
verify — вне репозитория (scratchpad сессии). Evidence с незакоммиченного
|
||
дерева не снимается: пересъёмка — после commit основной сессии (13.7).
|
||
|
||
- [x] 13.1 W1. Опасные ветки «не удалять» без теста и сценария:
|
||
- hook `set-key <id> <ключ>` (psql, ключ только под `<FAULT_DATABASE>/`,
|
||
символы и `..` — как у `put-object`);
|
||
- сценарии «Безопасность сверки»: «Объект, на который ссылается строка,
|
||
не удаляется», «Предел не останавливает уборку зависших» — в дельте и
|
||
основном спеке одинаково;
|
||
- тесты `test_reconcile_keeps_referenced_objects` (проба 1 verify) и
|
||
`test_reconcile_limit_keeps_cleanup` (проба 2).
|
||
|
||
Ветки кода верны (пробы verify зелёные), поэтому красный прогон — на
|
||
временных регрессиях `attachment_reconcile.py` (без перепроверки ссылок
|
||
у объекта без строки, уборка зависших под пределом), затем регрессии
|
||
убираются.
|
||
|
||
Прогоны 2026-10-22 (`make failure_checks FAULT_ARGS='-k …'`): на коде
|
||
`a6071da` оба теста W1 — passed (ветки верны); на временных регрессиях —
|
||
2 failed за 39 с: `<Z>/original` — `orphan_object` вместо
|
||
`unknown_object`, зависшая загрузка не убрана (`{}` вместо
|
||
`stale_pending`). Регрессии убраны, `git diff src/` — пусто.
|
||
- [x] 13.2 W2. Строка с ключом вне `<база>/attachments/`: сверка делает
|
||
HEAD чужого префикса и помечает строку. Тест
|
||
`test_reconcile_foreign_key_untouched` (красный на текущем коде:
|
||
`missing_object` и пометка), затем код: такая строка `ready` или
|
||
зависшая загрузка — «чужой объект» (`unknown_object`) без HEAD, без
|
||
пометки и без уборки; HEAD, пометка и снятие пометки ещё раз проверяют
|
||
префикс. Сценарий «Ключ вне префикса вложений не трогается», класс
|
||
«чужой объект» и абзац о префиксах — в дельте и основном спеке.
|
||
|
||
Красный прогон на `a6071da` (вместе с W1, 60 с): 1 failed —
|
||
dry-run назвал готовую строку `missing_object`, зависшую —
|
||
`stale_pending`, а не `unknown_object`. Сервис уборки такую зависшую
|
||
загрузку убирает и после правки — `KNOWN_ISSUES.md` (design, п. 19).
|
||
- [x] 13.3 S1. `stop_requested()` между двумя вызовами подряд: страница
|
||
списка → БД, БД → HEAD в перепроверке, HEAD → `mark_lost` / `clear_lost`,
|
||
ссылки → DELETE, перед проверкой bucket. Остановка ждёт не больше одного
|
||
вызова: S3 ≤ 5 с, шаг с БД ≤ 6 с. `REPORT.md` — та же граница. Теста нет:
|
||
два деградировавших хранилища в окне одного вызова по HTTP не
|
||
воспроизвести детерминированно (design, «Уточнения apply», п. 20).
|
||
- [x] 13.4 S2. Точность `REPORT.md`: 2 086 — только у плановой сверки при
|
||
старте, длительность прохода 0,49–0,82 с, синтетика стресса — ещё две
|
||
пометки за прогон. Заголовок в `evidence/reconcile/service.md` — при
|
||
пересъёмке после commit (13.7).
|
||
- [x] 13.5 S3. AGENTS.md, карта evidence: `evidence/reconcile/`,
|
||
`evidence/s3/cleaner-list.md`, `evidence/migrations/lost-at.md`.
|
||
- [x] 13.6 S4. Перепроверка в `--apply` при N ≫ предела — решение не
|
||
делать в этом change (design, «Уточнения apply», п. 21), передано в
|
||
`PLAN.md`, `track2-reconcile-cost`.
|
||
- [x] 13.7 S5. `driver.py reconcile-signal` — код 1 разового прохода по
|
||
SIGTERM, пока вызов S3 ждёт замороженный S3 (только не рабочий проект
|
||
compose). После commit основной сессии — снимок на временном стенде в
|
||
`evidence/reconcile/service.md`, заголовок S2 там же, `make
|
||
failure_checks` → `evidence/tests/failure-checks.md`, строки `REPORT.md`
|
||
с числом проверок.
|
||
|
||
Сделано на дереве: команда, `SKILL.md`, AGENTS.md; на рабочем проекте —
|
||
отказ, код 2; функциональная проверка на временном проекте `rcsig`
|
||
(`docker-compose.yml` + override хранилищ на tmpfs, синтетические
|
||
секреты, образ из `make failure_checks`): код 1, `interrupted_by: stop`,
|
||
«Stopped cleaner» `exit_code` 1, `docker stop` 4,9 с, PASS; проект
|
||
удалён, volumes — 155.
|
||
|
||
После commit `84f8c35` (основная сессия), 2026-10-22 18:04–18:25 UTC:
|
||
- `make failure_checks` — 48 из 48 за 524 с, вся команда 9 мин 06 с,
|
||
crash markers 0, `StartedAt` рабочего стенда прежний →
|
||
`evidence/tests/failure-checks.md`; там же раздел красных прогонов
|
||
группы 13 (`git archive` во временные каталоги): на `a6071da` — 1
|
||
failed из 3 (`…_foreign_key_untouched`), на `84f8c35` с временными
|
||
регрессиями — 2 failed из 2; образ после — пересобран из `84f8c35`;
|
||
- `driver.py reconcile-signal` на временном `rcsig` — код 1,
|
||
`interrupted_by: stop`, `docker stop` 5,0 с, PASS → новый раздел
|
||
`evidence/reconcile/service.md`; заголовок «make reconcile (grace 30
|
||
s)» исправлен на выполненную команду;
|
||
- `make student_test BASE_URL=http://localhost:8090` на `84f8c35` — 198
|
||
passed, 243 / 226 / 61 / 17 → `evidence/tests/student-test-lb.md`.
|
||
Из восьми прогонов три дали по одному 503 на загрузке: PUT реплики
|
||
`151df4af59c3` (код `c1648d9`) в S3 — `ReadTimeoutError` через 1 мс, S3
|
||
— «truncated request body … got 0 bytes». Разбор — там же; причина на
|
||
пути API → S3 не найдена, change её не касается — `KNOWN_ISSUES.md`,
|
||
тесты не менялись;
|
||
- `REPORT.md` — 48 / 48, 243 / 226 / 61 / 17, строки на `84f8c35`,
|
||
`reconcile-signal`. Проект `rcsig` удалён, volumes — 155.
|
||
- [x] 13.8 Проверки на дереве: `make lint`, `make check`, `make validate
|
||
PYTHON=.venv/bin/python`, `openspec validate track2-reconciler
|
||
--strict` и `--specs`, `make failure_checks`, `make student_test
|
||
BASE_URL=http://localhost:8090`.
|
||
|
||
2026-10-22: lint, check, validate — PASS; `openspec validate` — valid,
|
||
`--specs --strict` — 24 passed; `make failure_checks` — **48 passed** за
|
||
536 с, crash markers 0, `results: {'fault': 0, 'postgres': 0}`,
|
||
контейнеров проекта отказов 0, volumes 155; `make student_test
|
||
BASE_URL=http://localhost:8090` — 198 passed, «coverage: 243 scenarios
|
||
in 13 specs, 226 tested (61 by make failure_checks), 17 excluded».
|