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

93 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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