Files
mtusi2026lab4/openspec/changes/upload-consistency/specs/attachments/spec.md
T
ricoromaandClaude Opus 5.5 87c48b940b fix: address upload-consistency verify findings
Mark a stale pending row in its own committed transaction before the
cleaner deletes the object, and let mark_ready promote only unmarked
rows, so a cleaner rollback after the object delete can no longer leave
a ready attachment without its object. Add fault checks for an unknown
COMMIT outcome, an upload outliving the grace period and a cleaner
failure after the object delete; fix the cleaner entrypoint in rules.

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

5.9 KiB
Raw Blame History

Spec Delta

MODIFIED Requirements

Requirement: Порядок записи

Загрузка SHALL выполняться по шагам:

  1. проверки и чтение тела;
  2. запись метаданных в статусе «загружается» (pending) вместе с ключом объекта, фиксация в PostgreSQL;
  3. запись объекта в S3;
  4. статус ready, фиксация;
  5. ответ 201.

Объект, который записал API, SHALL быть известен PostgreSQL до записи в S3: без зафиксированных метаданных объект не записывается. Вложение не в статусе ready MUST NOT быть видно через API: его метаданные и байты — 404, ссылка на него в сообщении — 404.

Сбой после шага 2 из-за отказа хранилища SHALL давать 503 unavailable, а не 500. Отказ — S3 или PostgreSQL недоступен, не ответил за срок или отказал. Метаданные «загружается» при этом остаются. Их и объект убирает уборщик после grace period (capability storage-consistency). Компенсация — сверх этого:

  • объект записан, а перевод в ready не удался до того, как фиксация отправлена в PostgreSQL. API SHALL удалить записанный объект до ответа. Удаление не гарантировано: если оно не удалось, объект убирает уборщик;
  • исход фиксации ready неизвестен: связь оборвалась во время фиксации. API MUST NOT удалять объект — вложение могло стать ready;
  • к шагу 4 метаданных «загружается» уже нет или уборщик уже начал их уборку, потому что загрузка длилась дольше grace. Ответ SHALL быть 503 unavailable, и API SHALL удалить записанный объект.

Если запись метаданных на шаге 2 не удалась, объект MUST NOT записываться; отказ PostgreSQL при этом — 503 unavailable. Загрузка, которую отклонили до шага 2 (401, 400, 404, 413, 415) или клиент оборвал посреди тела, MUST NOT оставлять ни метаданных, ни объекта.

Scenario: Запись в S3 не удалась

  • WHEN S3 остановлен, и участник загружает настоящий PNG
  • THEN ответ 503 unavailable, в PostgreSQL появилось одно новое вложение — в статусе «загружается», а число готовых не изменилось
  • AND текстовое сообщение в тот же чат — 201, а после возврата S3 та же загрузка — 201

Scenario: Отклонённая загрузка ничего не оставляет

  • WHEN участник и посторонний отправляют загрузки, которые отклоняются с 404, 413 по Content-Length, 413 по счётчику, 413 по пикселям, 415 по типу и 415 по целостности
  • THEN в PostgreSQL не появилось ни одного нового вложения, а в bucket — ни одного нового объекта вложения

Scenario: Незавершённая загрузка не видна

  • WHEN загрузка при остановленном S3 оставила вложение в статусе «загружается», и участник чата по его id запрашивает метаданные и байты и отправляет сообщение со ссылкой на него
  • THEN все три ответа 404 not_found с тем же message, что у неизвестного id

Scenario: Сбой записи метаданных

  • WHEN PostgreSQL отказывает при записи метаданных новой загрузки
  • THEN ответ 503 unavailable, а нового вложения нет ни в PostgreSQL, ни в bucket

Scenario: Фиксация ready не удалась

  • WHEN объект вложения записан в S3, а PostgreSQL отказывает при переводе вложения в ready
  • THEN ответ 503 unavailable, а не 500, и объекта этого вложения в bucket уже нет
  • AND вложение остаётся в статусе «загружается» до уборщика, а по API его не видно

Scenario: Исход фиксации неизвестен

  • WHEN объект вложения записан в S3, а фиксация перевода в ready обрывается отказом PostgreSQL
  • THEN ответ 503 unavailable, вложение в статусе «загружается» и по API не видно, а его объект в bucket остаётся: API его не удаляет
  • AND после grace уборщик убирает и метаданные, и объект, а в bucket нет объектов вложений без метаданных

Scenario: Обрыв передачи тела

  • WHEN клиент обрывает соединение посреди тела загрузки
  • THEN нового вложения нет ни в PostgreSQL, ни в bucket, а следующая загрузка того же участника — 201