14 KiB
Spec Delta
MODIFIED Requirements
Requirement: Метаданные вложения
GET /api/v1/attachments/{attachment_id} SHALL отвечать 200 с объектом
Attachment во всех состояниях queued, processing, ready и failed
(attachment-processing, «Состояния вложения»). Поля id, chat_id,
owner_id, filename, content_type, size_bytes, sha256 и created_at
SHALL совпадать с ответом на загрузку. size_bytes, sha256 и content_type
всегда описывают оригинал, у вариантов — свои поля. status, variants,
error_code и updated_at SHALL отражать текущее состояние. У готового вложения
variants содержит каждый записанный вариант: у вложений этого уровня — thumbnail,
crop и optimized. Вложение, ставшее готовым до обработки вариантов, вариантов не
имеет, а ставшее готовым на уровне 3 — только thumbnail.
Scenario: Метаданные равны ответу загрузки
- WHEN Алиса загрузила вложение, а Боб запрашивает его метаданные
- THEN ответ 200, поля, описывающие оригинал, совпадают с ответом на
загрузку, а когда вложение становится
ready, —error_codenull и непустыеvariants
Requirement: Где хранятся вложения
Метаданные вложения SHALL храниться в PostgreSQL, байты — объектами в
приватном bucket S3 (object-storage). Байты MUST NOT храниться ни в
PostgreSQL, ни в файлах реплики API и worker. Ключ объекта назначает
сервер, filename в него MUST NOT входить:
- устойчивый staging —
<база>/staging/<id>/original, живёт до фиксацииready, а уfailed— до конца срока хранения (storage-consistency, «Очистка staging»); - конечный оригинал —
<база>/attachments/<id>/original; - вариант —
<база>/attachments/<id>/v<pipeline_version>-<вариант>.
Staging и конечный префикс — один и тот же сервер S3 и bucket. Устойчивость
staging — устойчивость этого сервера. Граница называется в REPORT.md:
отказ диска или ВМ теряет и то, и другое.
Каждая загрузка SHALL создавать новое вложение и новые объекты, в том
числе повтор той же загрузки: прозрачных повторов загрузки нет
(contracts/README.md).
Scenario: Байты не в БД и не на диске API
- WHEN после загрузок через балансировщик вложения стали
ready, и проверяющий смотрит схему таблиц вложений, ключи объектов в PostgreSQL, объекты в bucket и изменения файловой системы контейнеров реплик API и worker - THEN в таблицах нет колонки с байтами изображения, ключи объектов
имеют вид из требования и не содержат
filename, объекты с этими ключами есть в bucket, анонимный GET их ключей — 403, а в контейнерах реплик и worker нет файлов оригиналов и вариантов
Scenario: Повторная загрузка
- WHEN участник дважды загружает один и тот же файл
- THEN оба ответа 202 с разными
idи одинаковымsha256, и оба вложения становятсяreadyи скачиваются
Requirement: Порядок записи
Загрузка SHALL выполняться по шагам:
- проверки и чтение тела;
- запись метаданных в статусе «загружается» (
pending) вместе с ключами объектов, фиксация в PostgreSQL; - запись оригинала в staging;
- статус
queuedи задание обработки — одной транзакцией; - ответ 202.
К брокеру загрузка MUST NOT обращаться: задание до него доводит relay
(job-outbox).
Объект, который записал API, SHALL быть известен PostgreSQL до записи в
S3: без зафиксированных метаданных объект не записывается. Вложение в
статусе pending MUST NOT быть видно через API: его метаданные и байты
— 404, ссылка на него в сообщении — 404.
Сбой после шага 2 из-за отказа хранилища SHALL давать 503
unavailable, а не 500. Отказ — S3 или PostgreSQL недоступен, не ответил
за срок или отказал. Метаданные «загружается» при этом
остаются. Их и объект убирает уборщик после grace period (capability
storage-consistency). Компенсация — сверх этого:
- объект записан, а шаг 4 не удался до того, как фиксация отправлена в PostgreSQL. API SHALL удалить записанный объект до ответа. Удаление не гарантировано: если оно не удалось, объект убирает уборщик;
- исход фиксации шага 4 неизвестен: связь оборвалась во время фиксации.
API MUST NOT удалять объект — вложение могло стать
queued, и тогда его доведёт доreadyrelay и worker, хотя клиент получил 503; - к шагу 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 та же загрузка — 202
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: Фиксация задания не удалась
- WHEN объект вложения записан в staging, а PostgreSQL отказывает при
переводе вложения в
queued - THEN ответ 503
unavailable, а не 500, и объекта этого вложения в bucket уже нет, а задания у него нет - AND вложение остаётся в статусе «загружается» до уборщика, а по API его не видно
Scenario: Фиксация ready не удалась
- WHEN worker записал объекты вложения, а PostgreSQL отказывает при
фиксации
ready - THEN вложение не готово: метаданные —
queuedилиprocessing, скачивание — 409conflict, а следующая попытка доводит его доready
Scenario: Исход фиксации неизвестен
- WHEN объект вложения записан в staging, а фиксация перевода в
queuedобрывается отказом PostgreSQL - THEN ответ 503
unavailable, вложение в статусе «загружается» и по API не видно, а его объект в bucket остаётся: API его не удаляет - AND после grace уборщик убирает и метаданные, и объект, а в bucket нет объектов вложений без метаданных
Scenario: Брокер не подтвердил задание
- WHEN брокер остановлен, и участник загружает настоящий PNG
- THEN ответ 202, а не 503, вложение
queued, у его задания нет времени подтверждения брокером, а объект — в staging - AND после запуска брокера вложение становится
ready
Scenario: Обрыв передачи тела
- WHEN клиент обрывает соединение посреди тела загрузки
- THEN нового вложения нет ни в PostgreSQL, ни в bucket, а следующая загрузка того же участника — 202
Requirement: Скачивание варианта
GET /api/v1/attachments/{attachment_id}/content?variant=<имя> у готового вложения
SHALL отвечать 200 с байтами варианта thumbnail, crop или optimized через API, без
перенаправления. Заголовки ответа: Content-Type — content_type варианта,
Content-Length — его размер, X-Content-Type-Options: nosniff. Размер и
SHA-256 байтов равны полям варианта в метаданных. Доступ — как у оригинала
(требование «Доступ к вложению»).
Вариант, которого у готового вложения нет, SHALL давать 404 not_found. Это вложения,
ставшие готовыми раньше: до обработки вариантов — любой вариант, на уровне 3 — crop и
optimized. Нет объекта варианта в S3 или размер другой — 500 internal_error без деталей,
причина в журнале.
Scenario: Скачивание thumbnail
- WHEN Боб скачивает
variant=thumbnailготового вложения, загруженного Алисой - THEN ответ 200, не перенаправление,
Content-Type: image/jpeg,Content-Lengthравенsize_bytesварианта, естьX-Content-Type-Options: nosniff, а SHA-256 равенsha256варианта
Scenario: Скачивание crop и optimized
- WHEN Боб скачивает
variant=cropиvariant=optimizedготового вложения, загруженного Алисой - THEN оба ответа 200, не перенаправление,
Content-Type—image/jpegиimage/webp,Content-Lengthравенsize_bytesварианта, естьX-Content-Type-Options: nosniff, а SHA-256 равенsha256варианта
Scenario: Отсутствующий вариант
- WHEN у готового вложения нет метаданных варианта
crop, потому что оно стало готовым раньше этого уровня, и участник скачиваетvariant=crop - THEN ответ 404
not_foundв формате ошибки, а остальные варианты скачиваются
Scenario: Вариант для постороннего
- WHEN Ева скачивает
variant=thumbnailвложения чата Алисы и Боба - THEN ответ 404
not_foundс тем жеmessage, что у неизвестногоid