Files
mtusi2026lab5/openspec/changes/pipeline-reliability/specs/attachments/spec.md
T
2026-10-31 10:08:03 +03:00

14 KiB
Raw Blame History

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_code null и непустые 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 выполняться по шагам:

  1. проверки и чтение тела;
  2. запись метаданных в статусе «загружается» (pending) вместе с ключами объектов, фиксация в PostgreSQL;
  3. запись оригинала в staging;
  4. статус queued и задание обработки — одной транзакцией;
  5. ответ 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, и тогда его доведёт до ready relay и 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, скачивание — 409 conflict, а следующая попытка доводит его до 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