141 lines
9.8 KiB
Markdown
141 lines
9.8 KiB
Markdown
# 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`.
|