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>
93 lines
5.9 KiB
Markdown
93 lines
5.9 KiB
Markdown
# 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
|