Files
mtusi2026lab4/openspec/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

526 lines
31 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.
# attachments Specification
## Purpose
Вложения-изображения в чатах с лабы 4. Здесь описано:
- загрузка PNG и JPEG с лимитами до чтения и распаковки;
- проверка типа и целостности по содержимому, правила `filename`;
- доступ только участникам чата, метаданные и побайтный download;
- где лежат метаданные и байты, порядок записи и отказ S3;
- доступность файла через любую реплику и после рестарта стенда.
## Requirements
### Requirement: Загрузка вложения
`POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` SHALL
принимать тело — сырые байты одного изображения PNG или JPEG, не
multipart и не JSON, с `Content-Type: image/png` или `image/jpeg`. При
успехе ответ SHALL быть 201 с объектом `Attachment` без других полей:
- `id` — новый UUID, его назначает сервер;
- `chat_id` — чат из пути, `owner_id` — текущий пользователь;
- `filename` — переданное имя без изменений;
- `content_type` — тип, определённый по содержимому;
- `size_bytes` и `sha256` (64 шестнадцатеричных символа в нижнем
регистре) — размер и SHA-256 принятых байтов;
- `status` — `ready`, `variants` — `[]`, `error_code` — null;
- `created_at` и `updated_at` — время сервера в RFC 3339 UTC.
Ответ 201 SHALL означать, что сохранены и оригинал, и метаданные
(требование «Порядок записи»). Загрузку может выполнить любой участник
чата.
#### Scenario: Загрузка PNG
- **WHEN** Алиса загружает в свой чат публичный fixture
`tests/fixtures/sample.png` с `Content-Type: image/png` и
`filename=sample.png`
- **THEN** ответ 201, `status` `ready`, `variants` `[]`, `error_code`
null, `owner_id` — Алиса, `chat_id` — этот чат, `filename`
`sample.png`, `content_type` `image/png`, `size_bytes` 111817, а
`sha256` равен SHA-256 файла
#### Scenario: Загрузка JPEG
- **WHEN** Боб загружает в общий с Алисой чат настоящий JPEG с
`Content-Type: image/jpeg`
- **THEN** ответ 201, `content_type` `image/jpeg`, `owner_id` — Боб, а
`size_bytes` и `sha256` совпадают с размером и SHA-256 файла
#### Scenario: Разновидности PNG и JPEG
- **WHEN** участник загружает PNG с палитрой, с альфа-каналом, в
оттенках серого с альфа-каналом, 16 и 1 бит на канал, чересстрочный
(Adam7), а также JPEG прогрессивный, в оттенках серого, CMYK и с EXIF
- **THEN** каждый ответ 201 с `content_type` по формату файла
### Requirement: Лимит размера до чтения тела
Тело больше 10 485 760 байт (10 MiB) SHALL отклоняться ответом 413
`payload_too_large`, а тело ровно 10 485 760 байт проверку размера
SHALL проходить. Если `Content-Length` запроса больше лимита, ответ
SHALL отдаваться без чтения тела. Без `Content-Length` (передача
частями) тело SHALL читаться потоком со счётчиком. Ответ 413 SHALL
отдаваться, как только прочитано больше лимита, остаток тела MUST NOT
читаться. На одну загрузку процесс API MUST NOT держать в памяти больше
лимита и одного блока чтения тела.
#### Scenario: Граница размера
- **WHEN** участник загружает настоящий PNG размером ровно 10 485 760
байт, а затем такой же PNG на один байт длиннее
- **THEN** первый ответ 201, второй — 413 `payload_too_large`
#### Scenario: Заявленный размер больше лимита
- **WHEN** участник загружает 30 MiB с `Content-Length` 31 457 280
- **THEN** ответ 413 `payload_too_large` в формате ошибки, а клиент
получает его, не дожидаясь отправки всего тела
#### Scenario: Большое тело без Content-Length
- **WHEN** участник передаёт 30 MiB частями, без `Content-Length`
- **THEN** ответ 413 `payload_too_large` в формате ошибки
### Requirement: Лимит пикселей до распаковки
Ширину и высоту изображения сервис SHALL брать из заголовка до
распаковки данных: у PNG — из IHDR, у JPEG — из маркера кадра. Больше
40 000 000 пикселей — ответ 413 `payload_too_large`, ровно 40 000 000
проверку SHALL проходить. Проверка MUST NOT декодировать изображение в
память процесса API: распакованные данные PNG SHALL проверяться
потоком, их объём MUST NOT превышать следующего из размеров
изображения, и память проверки не зависит от числа пикселей. Данные
длиннее заявленных размеров — повреждённое изображение (требование
«Повреждённое изображение»).
#### Scenario: Огромные размеры в маленьком файле
- **WHEN** участник загружает PNG и JPEG по несколько килобайт, в
заголовке которых 40 000 001 пиксель и больше
- **THEN** каждый ответ 413 `payload_too_large`
#### Scenario: Ровно 40 млн пикселей
- **WHEN** участник загружает настоящий PNG 8000 × 5000 пикселей
- **THEN** ответ 201
#### Scenario: Данные длиннее размеров
- **WHEN** участник загружает PNG 100 × 100, данные изображения
которого распаковываются в сотни мегабайт
- **THEN** ответ 415 `unsupported_media_type`, а сервис не
распаковывает данные дальше заявленного размера изображения
### Requirement: Тип по содержимому
Тип вложения SHALL определяться по первым байтам содержимого: сигнатура
PNG — `image/png`, маркер начала JPEG — `image/jpeg`. Ответ SHALL быть
415 `unsupported_media_type`, если:
- `Content-Type` запроса нет или его тип не `image/png` и не
`image/jpeg`; параметры типа и регистр букв не учитываются;
- содержимое не PNG и не JPEG, в том числе пустое тело;
- тип содержимого не совпадает с `Content-Type` запроса (подмена MIME).
#### Scenario: Не изображение
- **WHEN** участник загружает текст, тело GIF и пустое тело с
`Content-Type: image/png`
- **THEN** каждый ответ 415 `unsupported_media_type`
#### Scenario: Подмена MIME
- **WHEN** участник загружает настоящий JPEG с `Content-Type: image/png`
и настоящий PNG с `Content-Type: image/jpeg`
- **THEN** оба ответа 415 `unsupported_media_type`
#### Scenario: Неподходящий Content-Type
- **WHEN** участник загружает настоящий PNG с `Content-Type`
`application/octet-stream`, `text/plain` и без `Content-Type`, а затем
с `Content-Type: IMAGE/PNG; charset=binary`
- **THEN** первые три ответа 415, последний — 201
### Requirement: Повреждённое изображение
Сервис SHALL проверять целостность структуры изображения без
декодирования пикселей и отвечать 415 `unsupported_media_type` на
заведомо повреждённое.
- PNG:
- первым идёт IHDR с допустимыми полями;
- каждый чанк целиком в файле, и его CRC верна;
- неизвестных критичных чанков нет;
- данные изображения (IDAT) идут подряд, их поток zlib завершён и
распаковывается ровно в объём, который следует из размеров, глубины
цвета и чересстрочности;
- тип фильтра каждой строки допустим;
- IEND есть.
- JPEG:
- маркеры и длины сегментов разбираются до конца;
- кадр (SOF) один и с ненулевыми размерами;
- есть хотя бы один скан;
- есть маркер конца EOI.
Байты после IEND или EOI повреждением не считаются: они входят в
оригинал, в его размер и SHA-256. Искажения внутри сжатых данных
скана JPEG, которые не нарушают структуру, сервис не обнаруживает: у
формата нет контрольной суммы.
#### Scenario: Обрезанный файл
- **WHEN** участник загружает PNG и JPEG, обрезанные наполовину и без
последних байтов
- **THEN** каждый ответ 415 `unsupported_media_type`
#### Scenario: Испорченные данные PNG
- **WHEN** участник загружает `sample.png` с одним изменённым байтом
внутри IDAT и сигнатуру PNG, за которой случайные байты
- **THEN** оба ответа 415 `unsupported_media_type`
#### Scenario: Хвост после конца изображения
- **WHEN** участник загружает PNG и JPEG, к которым дописаны байты
после IEND и EOI
- **THEN** оба ответа 201, `size_bytes` и `sha256` учитывают дописанные
байты, а скачанный оригинал содержит их
### Requirement: Имя файла
`filename` SHALL содержать от 1 до 255 Unicode code points. Ответ SHALL
быть 400 `invalid_request`, если параметра нет, имя пустое, длиннее
255 code points, состоит из одних пробельных символов или содержит:
- `/` или `\`;
- управляющий символ — категория Unicode Cc: U+0000–U+001F, в том числе
NUL, или U+007F–U+009F.
Отказ ограничен этим списком контракта (`contracts/README.md`). Прочие
символы SHALL приниматься, в том числе:
- символы форматирования и управления направлением текста (категория
Cf, например U+202E и U+2066);
- разделители строк и абзацев U+2028 и U+2029.
Имя в строке запроса SHALL быть корректным UTF-8 после
процент-декодирования. Неверная последовательность байтов (например,
`%FF`, обрезанная или закодированный суррогат) и байт вне ASCII в
строке запроса — 400 `invalid_request`. Замена таких байтов символом
U+FFFD MUST NOT превращать отказ в принятое имя.
Принятое имя SHALL храниться и возвращаться без изменений, без обрезки
и нормализации. Имя только отображается: оно MUST NOT участвовать в
ключе объекта и в пути на диске. Как безопасно показать имя, решает
клиент.
#### Scenario: Имя не в UTF-8
- **WHEN** участник загружает настоящий PNG с `filename=a%FFb.png`,
`filename=a%C3.png` и `filename=a%ED%A0%80b.png`, а затем с
`filename=%C3%A9t%C3%A9.png`
- **THEN** первые три ответа 400 `invalid_request`, последний — 201 с
`filename` `été.png`
#### Scenario: Опасное имя
- **WHEN** участник загружает настоящий PNG с `filename`
`../x.png`, `a/b.png`, `a\b.png`, с NUL, с переводом строки, с DEL, с
управляющим символом C1 U+0085, пустым, из одних пробелов и из 256
code points
- **THEN** каждый ответ 400 `invalid_request`
#### Scenario: Имя в Unicode
- **WHEN** участник загружает файл с `filename` из 255 code points:
кириллица, emoji с ZWJ и пробелы по краям
- **THEN** ответ 201, а `filename` в ответе загрузки и в метаданных
совпадает с переданным
#### Scenario: Символы форматирования в имени
- **WHEN** участник загружает файлы, в `filename` которых есть U+202E,
U+2066 с U+2069, U+2028 и мягкий перенос U+00AD
- **THEN** каждый ответ 201, а `filename` в ответе загрузки и в
метаданных совпадает с переданным
### Requirement: Порядок проверок загрузки
Если у загрузки несколько ошибок, ответ SHALL определяться первой из
них по порядку:
1. 401 — нет действительной сессии;
2. 400 — неверный `chat_id` или `filename`;
3. 404 — чата нет или пользователь в нём не состоит;
4. 415 — `Content-Type` запроса;
5. 413 — `Content-Length` запроса;
6. 413 — число прочитанных байтов;
7. 415 или 413 — содержимое: формат и целостность или число пикселей.
Тело MUST NOT читаться, пока не пройдены проверки 1–5. Ошибка клиента
MUST NOT давать 500.
#### Scenario: Посторонний с большим файлом
- **WHEN** Ева загружает 30 MiB в чат Алисы и Боба
- **THEN** ответ 404 `not_found`, а не 413
#### Scenario: Без сессии с опасным именем
- **WHEN** загрузка без `Authorization` идёт с `filename` `a/b.png`, а
затем с допустимым именем
- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer`
#### Scenario: Неверный тип и большой размер
- **WHEN** участник загружает 30 MiB с `Content-Type: text/plain`
- **THEN** ответ 415 `unsupported_media_type`
### Requirement: Доступ к вложению
Метаданные и байты вложения SHALL быть доступны любому участнику чата
вложения, а не только владельцу. Посторонний, неизвестный `id` и
вложение, загрузка которого не завершена, SHALL получать одинаковый 404
`not_found`. Запрос без действительной сессии — 401, `attachment_id` не
UUID — 400 `invalid_request`.
#### Scenario: Другой участник
- **WHEN** Алиса загрузила вложение в чат с Бобом, и Боб запрашивает
его метаданные и байты
- **THEN** оба ответа 200
#### Scenario: Посторонний и неизвестный id
- **WHEN** Ева запрашивает метаданные и байты вложения чата Алисы и
Боба, а Алиса — по случайному UUID
- **THEN** все ответы 404 `not_found` с одинаковым `message`
#### Scenario: Неверный id вложения
- **WHEN** участник запрашивает метаданные и байты по `attachment_id`
`123` и `abc`
- **THEN** каждый ответ 400 `invalid_request`
#### Scenario: Чтение без сессии
- **WHEN** метаданные и байты вложения запрашиваются без
`Authorization`
- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer`
### Requirement: Метаданные вложения
`GET /api/v1/attachments/{attachment_id}` SHALL отвечать 200 с
объектом `Attachment`, равным ответу на загрузку этого вложения.
#### Scenario: Метаданные равны ответу загрузки
- **WHEN** Алиса загрузила вложение, а Боб запрашивает его метаданные
- **THEN** ответ 200, JSON совпадает с ответом на загрузку во всех
полях
### Requirement: Скачивание оригинала
`GET /api/v1/attachments/{attachment_id}/content` SHALL отвечать 200 с
байтами оригинала без изменений: их размер и SHA-256 равны `size_bytes`
и `sha256` вложения. Заголовки ответа:
- `Content-Type` — `content_type` вложения без параметров;
- `Content-Length` — размер оригинала;
- `X-Content-Type-Options: nosniff`.
Байты SHALL отдавать API, ответ MUST NOT быть перенаправлением.
Параметр `variant` SHALL принимать только `original`, это и значение по
умолчанию. Любое другое значение — 400 `invalid_request`. Ключ объекта,
адрес и учётные данные S3 MUST NOT попадать ни в тело, ни в заголовки
ответов API.
#### Scenario: Побайтный оригинал
- **WHEN** Боб скачивает PNG и JPEG, загруженные Алисой
- **THEN** каждый ответ 200, не перенаправление, байты совпадают с
загруженными, `Content-Type` — `image/png` и `image/jpeg`,
`Content-Length` равен размеру, есть `X-Content-Type-Options: nosniff`
#### Scenario: Вариант original
- **WHEN** участник скачивает вложение с `variant=original`, а затем с
`variant=thumbnail` и с пустым `variant`
- **THEN** первый ответ 200 с теми же байтами, остальные — 400
`invalid_request`
#### Scenario: Без следов хранилища в ответе
- **WHEN** участник загружает вложение, читает метаданные и скачивает
байты
- **THEN** в телах ответов нет полей вне схемы контракта, а в
заголовках нет `Location` и заголовков `x-amz-*`
### Requirement: Где хранятся вложения
Метаданные вложения SHALL храниться в PostgreSQL, байты оригинала —
одним объектом в приватном bucket S3 (`object-storage`). Байты MUST
NOT храниться ни в PostgreSQL, ни в файлах реплики API. Ключ объекта
назначает сервер: имя базы, `/attachments/`, `id` вложения и
`/original`. Каждая загрузка SHALL создавать новое вложение и новый
объект, в том числе повтор той же загрузки: прозрачных повторов
загрузки нет (`contracts/README.md`).
#### Scenario: Байты не в БД и не на диске API
- **WHEN** после загрузок через балансировщик проверяющий смотрит
схему таблиц вложений, ключи объектов в PostgreSQL, объекты в bucket
и изменения файловой системы контейнеров реплик API
- **THEN** в таблицах нет колонки с байтами изображения, ключ каждого
объекта имеет вид `<база>/attachments/<id>/original` и не содержит
`filename`, объект с этим ключом есть в bucket, анонимный GET его
ключа — 403, а в контейнерах реплик нет файлов оригиналов
#### Scenario: Повторная загрузка
- **WHEN** участник дважды загружает один и тот же файл
- **THEN** оба ответа 201 с разными `id` и одинаковым `sha256`, и оба
вложения скачиваются
### 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
### Requirement: Недоступность S3
Если S3 недоступен, не ответил за срок вызова или отказал
(`object-storage`), загрузка и скачивание байтов SHALL отвечать 503
`unavailable` в формате ошибки. Ответ SHALL приходить не позже срока
вызова S3 с запасом, а не 500 и не зависанием. Без S3 SHALL работать:
- метаданные вложения;
- история чата с `attachment_ids`;
- отправка сообщений, в том числе со ссылкой на готовое вложение;
- `/health/ready`.
После возврата S3 загрузка и скачивание SHALL проходить без перезапуска
API.
#### Scenario: S3 остановлен
- **WHEN** вложение загружено, затем S3 остановлен, и участник
скачивает байты, читает метаданные, отправляет сообщение с этим
вложением и запрашивает `/health/ready`
- **THEN** скачивание — 503 `unavailable`, метаданные — 200, сообщение
— 201, готовность — 200
- **AND** после возврата S3 скачивание — 200 с теми же байтами
#### Scenario: S3 завис
- **WHEN** контейнер S3 заморожен (`docker pause`), и участник
загружает файл и скачивает байты готового вложения
- **THEN** оба ответа 503 `unavailable` не позже срока вызова S3 с
запасом, а после разморозки скачивание — 200
### Requirement: Вложение доступно через любую реплику
Готовое вложение SHALL скачиваться через любую реплику API за
балансировщиком, в том числе после остановки реплики, которая его
приняла. Метаданные и оригинал SHALL переживать перезапуск стенда
(`scripts/restart.sh`, вместе с S3) с сохранёнными volumes и читаться
прежним токеном.
#### Scenario: Скачивание через другую реплику
- **WHEN** вложение загружено через балансировщик, ответ дала реплика
с одним `X-Instance-Id`
- **THEN** байты скачиваются через реплику с другим `X-Instance-Id` и
совпадают с загруженными
#### Scenario: Принявшая реплика остановлена
- **WHEN** вложение загружено через балансировщик, затем реплика с
`X-Instance-Id` ответа на загрузку остановлена `scripts/stop-one.sh`
- **THEN** метаданные и байты через балансировщик — 200 от другой
реплики, SHA-256 совпадает с загруженным, посторонний получает 404
#### Scenario: Рестарт стенда
- **WHEN** вложение загружено, затем выполнен `scripts/restart.sh`
- **THEN** прежним токеном метаданные — 200, а байты совпадают с
загруженными по SHA-256