Files
mtusi2026lab4/openspec/changes/attachments/proposal.md
T
2026-10-20 23:44:50 +03:00

9.8 KiB
Raw Blame History

Proposal

Why

Рубрика «3» лабы 4 почти целиком про вложения (README.md): метаданные в PostgreSQL, байты в приватном bucket, 201 ready после сохранения, побайтный download только участникам, attachment_ids в сообщении, реальные PNG/JPEG с лимитами до чтения и распаковки, файл переживает остановку принявшей его реплики и рестарт стенда. Рубрика «4» требует негативных тестов: большой файл, повреждённое изображение, подмена MIME, чужое attachment_id, вложение другого чата, ни одной пользовательской ошибки в 500. Хранилище и клиент S3 готовы (change s3-storage), а домена вложений нет.

Без него красные публичные make test, make test-persistence и make test-failover (с LAB=4 они загружают файл) и 32 теста make student_test (контракт лабы 4 требует attachment_ids в Message). Сверка покрытия красная, пока четыре файла исключений не сняты на стенде лабы 4.

What Changes

  • Домен attachment во всех слоях и три ручки контракта:
    • POST /api/v1/chats/{chat_id}/attachments?filename=… — сырые байты PNG/JPEG, 201 Attachment со status=ready;
    • GET /api/v1/attachments/{id} — метаданные;
    • GET /api/v1/attachments/{id}/content — оригинал потоком из S3, с истинным Content-Type, без redirect.
  • Проверки загрузки до чтения и распаковки:
    • Content-Length больше 10 MiB — 413 до чтения тела, без него — счётчик байтов при чтении;
    • тип — по сигнатуре содержимого, расхождение с Content-Type — 415;
    • число пикселей — из заголовка изображения до распаковки, больше 40 млн — 413;
    • целостность — структурная проверка без декодирования пикселей. Память проверки не зависит от числа пикселей, «бомба» отсекается по заявленному размеру;
    • опасный filename — 400.
  • Порядок записи: проверка → строка pending с ключом объекта (commit) → PUT в S3 → строка ready (commit) → 201. Объект, записанный API, известен БД до записи. Компенсация и уборщик зависших pending — change upload-consistency.
  • Ключ объекта назначает сервер: <имя базы>/attachments/<id>/original. filename только отображается и ни в ключ, ни в путь не попадает.
  • Загрузка и скачивание не держат соединение пула PostgreSQL на время передачи тела. Короткие транзакции открываются только на шаги с БД.
  • Сообщение принимает attachment_ids (0–10 уникальных). Каждое вложение должно быть готовым вложением этого чата, иначе 404. text="" допустим только с вложением. Сообщение, история и повтор по ключу отдают attachment_ids в исходном порядке.
  • Хэш тела для идемпотентности учитывает attachment_ids, пустой список его не меняет (PLAN.md, решение 6).
  • Миграция только расширяет схему: таблицы attachments и message_attachments, ограничение длины текста сообщения ослаблено до 0–4000.
  • Отказ S3 — 503 только на путях вложений. Метаданные, текстовые сообщения и /health/ready работают.
  • student-tests/test_attachments.py: рубрика «4» и все сценарии нового спека. Новые проверки отказов: S3 остановлен и заморожен при загрузке и скачивании.
  • Драйвер скилла run-mtusi-messenger: upload, download с SHA-256 и сценарий attachment-failover — остановить реплику, принявшую файл, и скачать его через другую. flow загружает и скачивает вложение.
  • Профиль rollout стенда bench/ стартует с commit лабы 4 до этого change (e1161f7), а не с commit лабы 3 (KNOWN_ISSUES.md). Правило выбора commit — в bench.md. Evidence замены — со старого образа на схему с вложениями.
  • Evidence: evidence/attachments/; четыре файла исключений сверки переснимаются на стенде лабы 4; evidence/tests/ — зелёные прогоны.

Не входит:

  • компенсация, уборщик и тесты отказов посреди загрузки — upload-consistency;
  • лимит одновременных загрузок, сроки чтения тела и профиль uploads — upload-memory;
  • reconciler — трек 2;
  • presigned upload, lab5 (202, превью).

Capabilities

New Capabilities

  • attachments: вложения-изображения — загрузка с лимитами до чтения и распаковки, тип по содержимому, целостность, filename, доступ только участникам, метаданные, побайтный download, где лежат байты и метаданные, порядок записи, отказ S3, доступность через любую реплику и после рестарта.

Modified Capabilities

  • api-conventions: пары 413 — payload_too_large и 415 — unsupported_media_type; строгий UUID на входе и для attachment_id в пути и attachment_ids в теле.
  • messages: attachment_ids в отправке, ответе и истории; пустой текст с вложением; проверка вложений сообщения.
  • idempotency: тело включает attachment_ids. Отсутствующее поле равно [], порядок значим, повтор отдаёт те же вложения.
  • data-storage: метаданные вложений и связи с сообщениями — в PostgreSQL, байты — не в БД; целостность связей в БД; вложения переживают рестарт.
  • db-migrations: ослабление ограничения — допустимое расширение схемы, без скана таблицы под эксклюзивной блокировкой.
  • service-logging: имя файла и байты вложений не пишутся в журнал.
  • service-configuration: лимиты вложений — константы контракта, а не настройки; соответствие MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS — в REPORT.md.
  • student-tests: сверка покрытия включает attachments; тесты рубрики «4» лабы 4; проверки отказов S3 на путях вложений.
  • load-benchmark: прежний commit профиля замены — commit текущей лабы, без него отказ до стенда.

Impact

  • Код:
    • src/api/routers/v1/attachment.py, src/api/schemas/attachment.py; message.py в API, сервисе, repo и DTO; dependencies.py — сессия БД на шаг и вход без удержания сессии; errors.py — 413 и 415;
    • src/core/services/attachment.py, src/core/repos/attachment.py, attachment_object.py (ключ и объект в S3), src/core/exceptions/attachment.py;
    • src/schemas/ — DTO и enum вложений; src/utils/image.py — структурная проверка PNG/JPEG (только stdlib); src/utils/constants.py — лимиты контракта;
    • модели src/infra/db/models/attachment.py, ревизия alembic.
  • Зависимости: pillow только в dev-группе — генерация JPEG в тестах. В образ и в приложение не входит.
  • Тесты: student-tests/test_attachments.py, test_failures.py, api_client.py, contract.py, spec_coverage.py, fault_hook.py.
  • Стенды:
    • bench/run.py (rollout_from);
    • регресс make bench_quick (запрос истории изменился) и быстрых профилей failover, rollout, restore.
  • Документы:
    • правила api-contract.md, api-layer.md, service-layer.md, repo-layer.md, dto.md, migrations.md, logging.md, student-tests.md, bench.md, settings.md;
    • AGENTS.md и скилл run-mtusi-messenger;
    • REPORT.md — вложения, порядок записи, ответы на вопросы защиты, соответствие MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS;
    • KNOWN_ISSUES.md — запись о rollout_from закрывается;
    • PLAN.md.