Files
mtusi2026lab4/evidence/attachments/consistency.md
T
ricoromaandClaude Opus 5.5 f2dc0b368a docs: add upload-consistency evidence and report
- evidence: consistency (driver upload-consistency), cleaner process,
  cleaner S3 key, pending index plan on the working database
- re-run failure_checks (29/29), student_test via LB and test_isolated
  with the cleaner and storage-consistency coverage
- REPORT: database and S3 consistency, compensation table, grace period
  rationale, "PUT succeeded, COMMIT did not" answer, level 4 rows,
  limitations; PLAN stage 3 and AGENTS evidence map

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 06:32:48 +03:00

10 KiB
Raw Blame History

Согласованность БД и S3: компенсация и уборщик незавершённых загрузок

  • Дата: 2026-10-21, 03:11:19–03:12:02 UTC.
  • Commit: 5b42bd2 (change upload-consistency, код приложения, стенда и драйвера).
  • Стенд: рабочий mtusi-lab4 после make run_docker с этого commit — HAProxy на 127.0.0.1:8080, две реплики API, PostgreSQL, Valkey, S3 (SeaweedFS, bucket messenger), сервис cleaner (grace 900 с, интервал 60 с, выборка 100). Docker Desktop 29.9.1, Apple M3 Pro.
  • Спеки: attachments «Порядок записи» (сценарии «Запись в S3 не удалась», «Незавершённая загрузка не видна», «Фиксация ready не удалась»), storage-consistency «Уборщик незавершённых загрузок», «Безопасность уборки» («Готовые вложения не тронуты»). Design change upload-consistency, решения 1, 3, 4, 11; пункт 4 сценария защиты — «PUT прошёл, COMMIT нет».

Команда driver.py upload-consistency на рабочем стенде через LB, без печати токенов и секретов:

  1. синтетические Алиса, Боб и чат; готовое вложение R (tests/fixtures/sample.png);
  2. docker compose pause s3 → загрузка через LB — 503 за срок вызова S3 (5 с) → unpause в finally. В PostgreSQL — новая строка pending с ключом объекта (строка пишется до PUT), объекта нет;
  3. триггер на рабочей базе: перевод в ready вложения с уникальным filename прогона падает с SQLSTATE 08006 (для API — отказ PostgreSQL). Загрузка — 503, строка pending осталась, объекта уже нет: API удалил его до ответа (компенсация, COMMIT ещё не отправлялся). Триггер снят в finally, проверено — driver trigger left 0;
  4. обе строки pending через API не видны: метаданные, байты и сообщение со ссылкой — 404;
  5. после grace прогона 30 с (больше границы живой загрузки 17 с) — разовый docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once: обе загрузки убраны, строк и объектов нет, объектов без строки под префиксом рабочей базы нет (объекты — файлы original по weed shell fs.tree, а не каталоги: пустой каталог <id>/ SeaweedFS убирает через ~2 мин); R скачивается с тем же SHA-256.

Уборщик сервиса (grace 900 с) эти строки не трогал: им меньше 900 с. Разовый проход и сервис не мешают друг другу — строка берётся под FOR UPDATE SKIP LOCKED.

Проверка: код 0

$ python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 upload-consistency
upload with paused S3: 503 after 5.1 s
pending 8289ac18-b943-4bc3-a880-1c42569f9f0a: pending age 5 s key messenger/attachments/8289ac18-b943-4bc3-a880-1c42569f9f0a/original
pending 9f796b82-b932-491f-8540-653aab7083a1: pending age 0 s key messenger/attachments/9f796b82-b932-491f-8540-653aab7083a1/original
waiting 30 s for grace 30 s
cleaner --once (grace 30 s): exit 0
  {"event": "Started cleaner", "instance_id": "0fffc1a281f8", "module": "cleaner", "interval_seconds": 60.0, "pending_grace_seconds": 30, "batch_size": 100, "live_upload_bound_seconds": 17.0, "once": true, "database_host": "postgres", "database_port": 5432, "database_name": "messenger", "database_pool_size": 1, "s3_host": "s3", "s3_port": 8333, "s3_bucket": "messenger", "level": "info", "timestamp": "2026-10-21T03:12:01.055336Z", "lineno": 120, "func_name": "run", "filename": "main.py"}
  {"event": "Removed stale attachment", "instance_id": "0fffc1a281f8", "module": "attachment_cleanup_service", "method": "clean_stale_pending", "attachment_id": "8289ac18-b943-4bc3-a880-1c42569f9f0a", "object_key": "messenger/attachments/8289ac18-b943-4bc3-a880-1c42569f9f0a/original", "age_seconds": 41, "level": "info", "timestamp": "2026-10-21T03:12:01.161609Z", "lineno": 156, "func_name": "_remove", "filename": "attachment_cleanup.py"}
  {"event": "Removed stale attachment", "instance_id": "0fffc1a281f8", "module": "attachment_cleanup_service", "method": "clean_stale_pending", "attachment_id": "9f796b82-b932-491f-8540-653aab7083a1", "object_key": "messenger/attachments/9f796b82-b932-491f-8540-653aab7083a1/original", "age_seconds": 36, "level": "info", "timestamp": "2026-10-21T03:12:01.237346Z", "lineno": 156, "func_name": "_remove", "filename": "attachment_cleanup.py"}
  {"event": "Finished cleanup pass", "instance_id": "0fffc1a281f8", "module": "attachment_cleanup_service", "method": "clean_stale_pending", "removed": 2, "skipped": 0, "interrupted_by": null, "duration_ms": 182, "level": "info", "timestamp": "2026-10-21T03:12:01.237453Z", "lineno": 120, "func_name": "clean_stale_pending", "filename": "attachment_cleanup.py"}
  {"event": "Stopped cleaner", "instance_id": "0fffc1a281f8", "module": "cleaner", "exit_code": 0, "level": "info", "timestamp": "2026-10-21T03:12:01.240031Z", "lineno": 158, "func_name": "run", "filename": "main.py"}
bucket messenger, prefix messenger/: 1200 objects, 1200 rows, 0 objects without a row
ready attachment R uploaded      expected 201     got 201
upload with paused S3            expected 503     got 503
new pending rows (paused)        expected 1       got 1
upload with ready failure        expected 503     got 503
new pending rows (ready failure) expected 1       got 1
object after compensation        expected absent  got absent
driver trigger left              expected 0       got 0
metadata of pending 8289ac18     expected 404     got 404
content of pending 8289ac18      expected 404     got 404
message with 8289ac18            expected 404     got 404
metadata of pending 9f796b82     expected 404     got 404
content of pending 9f796b82      expected 404     got 404
message with 9f796b82            expected 404     got 404
cleaner --once exit code         expected 0       got 0
row of 8289ac18                  expected absent  got absent
object of 8289ac18               expected absent  got absent
row of 9f796b82                  expected absent  got absent
object of 9f796b82               expected absent  got absent
objects without a row            expected 0       got 0
R downloaded                     expected 200     got 200
R sha256 = uploaded              expected yes     got yes
PASS: pending rows are invisible, the ready failure is compensated, the cleaner removed both uploads, no object without a row, R intact
exit=0

age_seconds в записи уборщика — возраст строки в момент удаления (её created_at — по часам реплики API, порог — по часам уборщика, один хост Docker).

Журнал реплик API за прогон

docker compose logs --no-log-prefix --since 2026-10-21T03:11:15Z api, записи загрузок без служебных полей места вызова. Первая загрузка — шаг put (S3 заморожен, срок вызова 5 с): объект не трогается, строку убирает уборщик. Вторая — шаг ready (отказ PostgreSQL до отправки COMMIT): объект удалён сразу.

{"event": "Object storage is unavailable", "instance_id": "13f1cb708119", "module": "object_storage", "operation": "put_object", "duration_ms": 5003, "error_type": "TimeoutError", "level": "warning", "timestamp": "2026-10-21T03:11:24.992289Z"}
{"event": "Attachment upload left pending", "instance_id": "13f1cb708119", "module": "attachment_service", "attachment_id": "8289ac18-b943-4bc3-a880-1c42569f9f0a", "step": "put", "level": "warning", "timestamp": "2026-10-21T03:11:24.993236Z"}
{"event": "Database is unavailable", "instance_id": "c6cde1dc6109", "module": "database", "error_type": "DBAPIError", "level": "warning", "timestamp": "2026-10-21T03:11:25.502173Z"}
{"event": "Attachment upload left pending", "instance_id": "c6cde1dc6109", "module": "attachment_service", "attachment_id": "9f796b82-b932-491f-8540-653aab7083a1", "step": "ready", "level": "warning", "timestamp": "2026-10-21T03:11:25.502305Z"}
{"event": "Deleted attachment object", "instance_id": "c6cde1dc6109", "module": "attachment_service", "attachment_id": "9f796b82-b932-491f-8540-653aab7083a1", "object_key": "messenger/attachments/9f796b82-b932-491f-8540-653aab7083a1/original", "level": "info", "timestamp": "2026-10-21T03:11:25.503567Z"}

filename вложений (uc-<метка>-….png) в журналах API и уборщика за прогон — 0 вхождений (grep -c "uc-"); у записей загрузки только filename_length.

Журнал сервиса cleaner

docker compose logs --no-log-prefix cleaner после прогона: одна запись старта с параметрами по умолчанию. Пустые проходы раз в 60 с пишутся на уровне debug и при log_level = INFO в журнал не попадают; строки прогона сервис не трогал (им меньше grace 900 с).

{"event": "Started cleaner", "instance_id": "37c2debb97a9", "module": "cleaner", "interval_seconds": 60.0, "pending_grace_seconds": 900, "batch_size": 100, "live_upload_bound_seconds": 17.0, "once": false, "database_host": "postgres", "database_port": 5432, "database_name": "messenger", "database_pool_size": 1, "s3_host": "s3", "s3_port": 8333, "s3_bucket": "messenger", "level": "info", "timestamp": "2026-10-21T03:01:21.099231Z", "lineno": 120, "filename": "main.py", "func_name": "run"}

Поведение уборщика при отказах S3 и PostgreSQL, свежая загрузка моложе grace и kill реплики между PUT и фиксацией — проверки отказов make failure_checks (evidence/tests/failure-checks.md).