Files
mtusi2026lab4/openspec/changes/upload-memory/specs/attachments/spec.md
T
2026-10-21 23:21:42 +03:00

12 KiB
Raw Blame History

MODIFIED Requirements

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 держать в памяти больше лимита и одного блока чтения тела. Это касается всех шагов загрузки, в том числе записи объекта в S3: для отправки тело 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 в формате ошибки

Scenario: Одна копия тела при записи в S3

  • WHEN 10 клиентов одновременно загружают по 10 MiB в одну реплику, у которой лимит одновременных загрузок выше 10 (профиль загрузок стенда bench/, вариант «без лимита»)
  • THEN пик памяти реплики выше её памяти до загрузок не больше чем на 1,5 размера тела на каждую загрузку, а у кода до этого изменения (вариант «до») — больше

Requirement: Порядок проверок загрузки

Если у загрузки несколько ошибок, ответ SHALL определяться первой из них по порядку:

  1. 401 — нет действительной сессии;
  2. 400 — неверный chat_id или filename;
  3. 404 — чата нет или пользователь в нём не состоит;
  4. 415 — Content-Type запроса;
  5. 413 — Content-Length запроса;
  6. 429 — нет места для загрузки (требование «Одновременные загрузки реплики»);
  7. тело: 413 — прочитано больше лимита; 400 — тело не пришло за срок (требование «Срок передачи тела») или клиент оборвал передачу;
  8. 415 или 413 — содержимое: формат и целостность или число пикселей.

Тело MUST NOT читаться, пока не пройдены проверки 1–6. Загрузка, отклонённая на проверках 1–5, MUST NOT ждать места и занимать его. Ошибка клиента 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

Scenario: Отказ раньше очереди

  • WHEN все места загрузки процесса заняты и очередь ожидания полна, и посторонний загружает файл в чат, участник загружает 30 MiB с Content-Length 31 457 280, а затем PNG с Content-Type: text/plain
  • THEN ответы 404, 413 и 415 приходят сразу, без ожидания места, а не 429

ADDED Requirements

Requirement: Одновременные загрузки реплики

Каждый процесс API SHALL обрабатывать одновременно не больше [uploads] max_concurrent загрузок (service-configuration, «Параметры загрузок»): у процесса столько мест загрузки. Загрузка занимает место после проверок 1–5 требования «Порядок проверок загрузки» и до чтения тела. Место SHALL освобождаться при любом исходе загрузки: 201, ошибка, обрыв клиента, истёкший срок, отмена запроса.

Загрузка, которой места нет, SHALL ждать его в очереди процесса по порядку прихода, но не дольше [uploads] wait_timeout_seconds. В очереди SHALL быть не больше [uploads] max_waiting загрузок. Если очередь полна, ответ SHALL отдаваться сразу. Если за срок ожидания место не освободилось, ответ SHALL отдаваться по его истечении. Ответ в обоих случаях — 429 rate_limited в формате ошибки с заголовком Retry-After — положительным целым числом секунд. Такая загрузка MUST NOT оставлять ни метаданных, ни объекта. Ожидающая загрузка MUST NOT держать соединение с PostgreSQL.

Места считает каждый процесс отдельно. Балансировщик ответ 429 на другой реплике не повторяет (load-balancing), загрузку повторяет клиент после Retry-After.

Память загрузок процесса SHALL ограничиваться числом мест, а не числом клиентов. Ожидающее или отклонённое соединение SHALL держать в памяти процесса и в буферах его сокетов не больше 1 MiB, каким бы ни было тело.

Scenario: Загрузки в пределах лимита

  • WHEN 10 участников одного чата одновременно загружают по настоящему PNG около 1 MiB, а параметры загрузок — по умолчанию
  • THEN все ответы 201 с разными id, и каждое вложение скачивается с тем же SHA-256

Scenario: Все места заняты

  • WHEN все места загрузки процесса заняты загрузками, тела которых ещё идут, приходит ещё одна загрузка, и место за срок ожидания не освобождается
  • THEN ответ 429 rate_limited с Retry-After не меньше 1 приходит не раньше срока ожидания, а нового вложения нет ни в PostgreSQL, ни в bucket

Scenario: Очередь ожидания полна

  • WHEN все места загрузки процесса заняты, и очередь ожидания полна
  • THEN следующая загрузка сразу получает 429 rate_limited с Retry-After, без ожидания

Scenario: Ожидание места

  • WHEN место занято загрузкой, которая заканчивается раньше срока ожидания, а следующая загрузка ждёт его в очереди
  • THEN ожидавшая загрузка получает 201, и её вложение скачивается с тем же SHA-256

Scenario: Место освобождается

  • WHEN загрузка на единственном месте процесса заканчивается 413 по счётчику, 415 по содержимому, 400 по сроку тела, обрывом клиента или 503 при остановленном S3
  • THEN после каждой такой загрузки следующая получает место сразу: ответ 201 без ожидания (после 503 — когда S3 вернулся)

Scenario: Память не растёт с числом загрузок

  • WHEN 10, 20 и 40 клиентов одновременно и без пауз загружают по 10 MiB в одну реплику с параметрами по умолчанию (профиль загрузок стенда bench/, вариант «с лимитом»)
  • THEN пик памяти реплики в каждом случае не больше половины лимита контейнера, при 20 и 40 клиентах он выше, чем при 10, не больше чем на 1 MiB на каждого клиента сверх 10, реплика не завершена из-за памяти, лишние загрузки получают 429, а ответов 5xx нет

Requirement: Срок передачи тела

Тело загрузки SHALL приходить целиком не позже [uploads] body_timeout_seconds после того, как загрузка заняла место. Иначе ответ SHALL быть 400 invalid_request в формате ошибки. Загрузка при этом MUST NOT оставлять ни метаданных, ни объекта, и её место освобождается. Тело, которое пришло в срок, SHALL приниматься, как бы мелко его ни делил клиент и какие бы паузы ни делал.

Scenario: Медленный клиент

  • WHEN участник шлёт настоящий PNG частями так, что тело идёт дольше срока передачи
  • THEN ответ 400 invalid_request, нового вложения нет ни в PostgreSQL, ни в bucket, а следующая загрузка — 201 без ожидания места

Scenario: Медленная передача в срок

  • WHEN участник шлёт настоящий PNG мелкими частями с паузами и укладывается в срок передачи
  • THEN ответ 201, а size_bytes и sha256 совпадают с файлом