- upload, metadata and download endpoints for PNG/JPEG attachments:
limits before reading and decompression, type by content,
structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
350 lines
23 KiB
Markdown
350 lines
23 KiB
Markdown
# Tasks
|
||
|
||
Как строить — `design.md` (дальше «решение N»), что должно получиться —
|
||
дельты в `specs/`. Перед первым файлом слоя прочитать его правило:
|
||
`api-contract.md`, `api-layer.md`, `auth.md` (`dependencies.py`,
|
||
`errors.py`), `service-layer.md`, `repo-layer.md`, `dto.md`,
|
||
`migrations.md`, `logging.md`, `settings.md`, `student-tests.md`,
|
||
`bench.md`, `balancer.md` (драйвер и `stop-one.sh`). Evidence снимается с
|
||
закоммиченного кода, коммит — только после подтверждения пользователя
|
||
(`bench.md`, «Измеренное состояние — commit»).
|
||
|
||
Ответы пользователя 2026-10-20 (`PLAN.md`, `### attachments` →
|
||
«Вопросы»):
|
||
- п. 1 — структурная проверка изображения;
|
||
- п. 2 — ответ преподавателя 2026-10-20 (AGENTS.md, «Согласования с
|
||
преподавателем»; design, решение 8): «пустой текст» — и `""`, и текст
|
||
из одних пробелов; с хотя бы одним вложением он допустим (201, текст
|
||
как прислан), без вложений — 400. Валидатор `CreateMessage`,
|
||
сценарий `messages` «Пробелы с вложением» и его тест — под это;
|
||
- п. 3 — `filename` отклоняется только по списку контракта: `/`, `\` и
|
||
управляющие символы категории Cc, остальное принимается.
|
||
|
||
Ожидаемо красное по ходу работы, остальное разбирается по AGENTS.md:
|
||
- до задачи 5.5 (sync дельт) тесты с маркерами новых сценариев падают на
|
||
сверке: «marker points to unknown scenario»;
|
||
- до задачи 9.2 `test_exclusion_evidence_exists`: нет файлов исключений.
|
||
Это четыре файла перехода из AGENTS.md («Переход в следующую лабу»)
|
||
и `evidence/attachments/failover.md`, `storage.md`.
|
||
|
||
## 1. Основа: константы, enum, DTO, исключения, проверка изображения
|
||
|
||
- [x] 1.1 Типы домена по решениям 2, 4 и 10:
|
||
- константы в `src/utils/constants.py`: лимиты, длины `filename`,
|
||
запрещённые символы `filename` (`/`, `\`, категория Cc),
|
||
`MESSAGE_ATTACHMENTS_MAX`, префикс и суффикс ключа объекта;
|
||
- `src/schemas/enums/attachment.py` (`AttachmentStatus`,
|
||
`ImageType`);
|
||
- `src/schemas/dataclasses/attachment.py` (`AttachmentFullDTO`,
|
||
`AttachmentContentDTO`), поле `attachment_ids: tuple[UUID, ...] =
|
||
()` в `MessageFullDTO`;
|
||
- `src/core/exceptions/attachment.py` (`AttachmentNotFound`,
|
||
`PayloadTooLarge`, `UnsupportedMediaType`, `UploadInterrupted`,
|
||
`AttachmentContentMissing`);
|
||
- реэкспорт в `__init__.py` пакетов по алфавиту.
|
||
|
||
Проверка: `make lint`; `uv run python -c "from src.core import
|
||
exceptions; from src.schemas import dataclasses, enums; print(…)"`
|
||
без ошибок.
|
||
- [x] 1.2 `src/utils/image.py` по решению 2: `inspect_image(data, *,
|
||
max_pixels)` → `ImageInfo` (тип, ширина, высота), исключения
|
||
`UnsupportedImage`, `DamagedImage`, `TooManyPixels`. Только stdlib;
|
||
фильтры строк — срезом с шагом строки, конец скана JPEG — регулярным
|
||
выражением. Проверка — разовый скрипт в scratchpad (`uv run
|
||
--no-project --with pillow python -I`), который импортирует модуль по
|
||
пути. Повторить пробу из design, Context:
|
||
- 17 вариантов приняты;
|
||
- повреждённые из списка — `DamagedImage`, хвосты приняты;
|
||
- подмена размеров SOF — `TooManyPixels`;
|
||
- «бомба» 100 × 100 / 200 MiB — `DamagedImage` быстрее 10 мс;
|
||
- PNG 1 × 40 млн и 40 млн RGBA — не дольше 0,5 с, пик `tracemalloc`
|
||
до 5 MiB;
|
||
- корпус из 12 000 случайных PNG и JPEG системы: ни одного файла,
|
||
который загружает Pillow, а модуль отклоняет, кроме лимита пикселей.
|
||
|
||
Итоги — строкой в design, «Уточнения apply».
|
||
|
||
## 2. Схема БД
|
||
|
||
- [x] 2.1 Модели по решению 3: `src/infra/db/models/attachment.py`
|
||
(`Attachment`, `MessageAttachment` с ограничениями и индексом по
|
||
`attachment_id`), новое условие `text_length` в `Message`, экспорт в
|
||
`models/__init__.py`. Проверка: `make revision` даёт ревизию с двумя
|
||
таблицами и индексом. Ослабление CHECK autogenerate не видит
|
||
(`migrations.md`).
|
||
- [x] 2.2 Ревизия руками по решению 3:
|
||
- первая строка `SET LOCAL lock_timeout = '2s'`;
|
||
- CHECK литералами, а не константами `src`;
|
||
- `DROP CONSTRAINT ck_messages_text_length` и `ADD CONSTRAINT … CHECK
|
||
(char_length(text) <= 4000) NOT VALID`;
|
||
- `downgrade` зеркально, строгое ограничение тоже `NOT VALID`.
|
||
|
||
Проверка:
|
||
- `uv run alembic upgrade head --sql` содержит `NOT VALID`;
|
||
- `make upgrade` на рабочей базе, повторный `upgrade head` — без
|
||
изменений;
|
||
- на временной базе (`createdb` в контейнере `postgres`, `DATABASE__NAME`
|
||
в окружении): `upgrade` с нуля → `downgrade -1` → `upgrade`, затем
|
||
`DROP DATABASE`;
|
||
- psql в транзакции с откатом:
|
||
- строка с каждым нарушением CHECK отклонена: размер, SHA-256, тип,
|
||
статус, `filename` с `/`, `\`, U+0001, U+007F, U+0085 и из 256
|
||
символов;
|
||
- допустимая строка принята, в том числе с `filename`, где есть
|
||
U+202E, U+2028 и U+00AD: CHECK не строже API;
|
||
- владелец не участник — отказ FK;
|
||
- удаление вложения со связью — отказ FK;
|
||
- повтор вложения в сообщении и позиция 10 — отказ;
|
||
- `\d attachments`, `\d message_attachments` — по таблице решения 3.
|
||
|
||
## 3. Repo и сервисы
|
||
|
||
- [x] 3.1 Repo по решениям 3, 4 и 8:
|
||
- `src/core/repos/attachment.py`: `insert_attachment`, `mark_ready`
|
||
(`UPDATE … WHERE status = 'pending' RETURNING`), `get_attachment`,
|
||
`get_attachments`;
|
||
- `src/core/repos/attachment_object.py`: `original_key`,
|
||
`put_original`, `open_original` поверх `ObjectStorage`;
|
||
- `src/core/repos/message.py`: `MESSAGE_COLUMNS` с подзапросом
|
||
`ARRAY(...)`, вставка сообщения явными колонками,
|
||
`insert_message_attachments` одной вставкой.
|
||
|
||
В каждой функции одно выражение. Проверка: `make lint`. Поведение —
|
||
через HTTP в группах 4–5; план истории — задача 7.2.
|
||
- [x] 3.2 `src/core/services/attachment.py` — `AttachmentService(db_scope,
|
||
cache, storage)` по решениям 1, 5, 6, 7, 11: `upload`,
|
||
`get_attachment`, `open_content`. Проверка, загрузка, SHA-256 и
|
||
размеры — одним `anyio.to_thread.run_sync`. Каждый шаг с БД — свой
|
||
`async with self.db_scope()`, без вложенных. Журнал без `filename`.
|
||
Проверка: `make lint`, дальше задача 4.3.
|
||
- [x] 3.3 `MessageService.send_message(..., attachment_ids)` по решениям
|
||
8 и 9:
|
||
- проверка вложений до захвата ключа;
|
||
- связи после вставки сообщения, один commit;
|
||
- `message_request_hash(text, attachment_ids)`: пустой список хэш не
|
||
меняет, id — `str(UUID)`;
|
||
- `attachments_count` в записи журнала.
|
||
|
||
Проверка: разовый вызов `message_request_hash` — хэш `{"text": "x"}`
|
||
равен хэшу версии `e1161f7` (`git show e1161f7:src/core/services/
|
||
message.py`), список в верхнем и нижнем регистре даёт один хэш,
|
||
другой порядок — другой.
|
||
|
||
## 4. Слой API
|
||
|
||
- [x] 4.1 `src/api/dependencies.py` по решению 5:
|
||
- `db_session_scope()`;
|
||
- `get_db_session` — обёртка над ним;
|
||
- `get_current_user_brief` и `CurrentUserBrief`;
|
||
- `get_attachment_service` и `AttachmentServiceDep` (глобал
|
||
`object_storage`).
|
||
|
||
`src/api/errors.py` — строки таблицы решения 10. Проверка: `make lint`;
|
||
`make student_test` через LB — те же итоги, что до правки (красное —
|
||
только схема `Message`, сверка и исключения). JSON-ручки не изменились.
|
||
- [x] 4.2 Схемы и ручки по решениям 6, 7, 8, 10:
|
||
- `src/api/schemas/attachment.py`: `DisplayFilename` (отказ на `/`,
|
||
`\`, символы категории Cc и строку из одних пробелов, решение 10),
|
||
`Attachment`;
|
||
- `src/api/schemas/message.py`: `CreateMessage` с `attachment_ids` и
|
||
валидатором, `Message` с `attachment_ids`;
|
||
- `src/api/routers/v1/attachment.py`: загрузка с `openapi_extra`,
|
||
метаданные, `content` со `StreamingResponse`, обёртка над
|
||
`request.stream()` с `UploadInterrupted`;
|
||
- подключение в `routers/v1/__init__.py`, параметр `attachment_ids` в
|
||
ручке сообщения.
|
||
|
||
Проверка: `/openapi.json` запущенного сервера содержит три пути
|
||
контракта, тело загрузки `image/png` / `image/jpeg` и параметр
|
||
`variant` с перечислением `original`.
|
||
- [x] 4.3 Проверка на живом сервере. Консоль — `driver.py start`, стенд
|
||
— `make rolling_update`: одна миграция, затем замена по одной.
|
||
- `make test` против обоих: `PASS: lab4 public API scenario`.
|
||
- Руками через `driver.py req` и curl:
|
||
- 413 по `Content-Length` и частями;
|
||
- 415 на текст и подмену MIME;
|
||
- 400 на `filename` с `/` и с U+0085, 201 на `filename` с U+202E —
|
||
имя в ответе то же;
|
||
- 404 постороннему на загрузку, метаданные и байты;
|
||
- 503 на загрузку и скачивание при `make stop_s3`, метаданные 200;
|
||
- после `make start_s3` — 201 и 200;
|
||
- журнал (`make logs` без `-f`) не содержит переданных `filename`.
|
||
- Разовый скрипт в scratchpad (решение 5): загрузка 10 MiB частями за
|
||
~12 с и скачивание 10 MiB с чтением за ~12 с через LB — 201 и 200
|
||
без «Database is unavailable» в журнале.
|
||
|
||
## 5. Тесты
|
||
|
||
- [x] 5.1 `uv add --dev pillow`. `student-tests/images.py` — генераторы
|
||
по решению 12. Проверка:
|
||
- `uv lock --check`;
|
||
- `docker run --rm mtusi-messenger:lab4 python -c "import PIL"`
|
||
завершается ошибкой: в образе Pillow нет;
|
||
- `uv run python -c` с импортом `images` даёт PNG ровно 10 485 760
|
||
байт, и `inspect_image` его принимает.
|
||
- [x] 5.2 `student-tests/api_client.py` и `contract.py` по решению 12:
|
||
- загрузка, метаданные, байты, `send_message(..., attachment_ids)`;
|
||
- коды 413 и 415, `owner_id`, элементы `attachment_ids`,
|
||
`updated_at`;
|
||
- `assert_content`.
|
||
|
||
Проверка: прежние тесты проходят на коде группы 4.
|
||
- [x] 5.3 `student-tests/test_attachments.py` — сценарии спека
|
||
`attachments`, кроме проверок отказов и исключений, с маркерами
|
||
`spec`. В «Опасном имени» — только символы контракта, в «Символах
|
||
форматирования в имени» — 201 и то же имя в ответе и метаданных.
|
||
«Скачивание через другую реплику» — с фикстурой `replicas`. В
|
||
`test_rubric.py` — пять сценариев рубрики «4» лабы 4. Новые сценарии
|
||
дельт `messages`, `idempotency`, `api-conventions`, `data-storage` — в
|
||
их модулях. Проверка: `make student_test` через LB и `make
|
||
test_isolated` — новые тесты проходят; на рабочем стенде через LB
|
||
`replicas`-тест выполняется, в `test_isolated` пропущен с причиной.
|
||
- [x] 5.4 Проверки отказов по дельте `student-tests`:
|
||
- `test_failures.py`: «Запись в S3 не удалась», «Отклонённая загрузка
|
||
ничего не оставляет», «S3 остановлен», «S3 завис» в `with
|
||
outage(...)`;
|
||
- `fault_hook.py`: действия `count-attachments` и `count-objects`,
|
||
docstring;
|
||
- `run_failures.py`: bucket и имя базы в окружении hook.
|
||
|
||
Проверка: `make failure_checks FAULT_ARGS='-k attachment or
|
||
object_storage'`, затем полный `make failure_checks` — код 0, стенд
|
||
отказов удалён, у рабочего стенда прежний `StartedAt`.
|
||
- [x] 5.5 Сверка покрытия:
|
||
- `attachments` в `CAPABILITIES` (`spec_coverage.py`);
|
||
- исключения «Принявшая реплика остановлена», «Байты не в БД и не на
|
||
диске API», «Рестарт стенда» с причиной и командой по решению 12;
|
||
- синхронизация всех дельт change в основные спеки (`/opsx:sync`),
|
||
как `health` в `s3-storage`.
|
||
|
||
Проверка: `make student_test` — сверка без «no test and no
|
||
exclusion» и «unknown scenario». Красное — только
|
||
`test_exclusion_evidence_exists` по списку в шапке.
|
||
|
||
## 6. Драйвер скилла `run-mtusi-messenger`
|
||
|
||
- [x] 6.1 Команды `upload` и `download` по решению 13. Проверка против
|
||
`driver.py start` и стенда (`--port 8080`): загрузка
|
||
`tests/fixtures/sample.png`, скачивание вторым участником — SHA-256
|
||
`99ea7533…` совпадает; 404 постороннему; `ruff format --check` и
|
||
`make lint` проходят.
|
||
- [x] 6.2 `attachment-failover [--mode stop|kill]` по решению 13.
|
||
Проверка на стенде: оба режима — код 0, скачивание от реплики с
|
||
другим `X-Instance-Id`, SHA-256 совпал, после команды снова
|
||
`API_REPLICAS` реплик `UP` (`make lb_stats`). Отрицательная проверка:
|
||
без балансировщика (`--port` консольного процесса) — код 2 и
|
||
понятное сообщение.
|
||
- [x] 6.3 `attachment-storage` по решению 13. Проверка:
|
||
- на стенде код 0;
|
||
- отрицательная: `s3.anonymous.set -access Read` через `docker compose
|
||
exec s3 weed shell` — код 1 с названной проверкой; `docker compose up
|
||
-d s3-bootstrap` закрывает доступ, и снова код 0.
|
||
- [x] 6.4 `flow` с вложением по решению 13, раздел о вложениях в
|
||
`SKILL.md`: команды, gotchas — `urllib` напрямую к реплике и ранний
|
||
413; S3 нужен только путям вложений. Проверка: `driver.py all` — код
|
||
0, `FAILED: none`.
|
||
|
||
## 7. Стенд `bench/`
|
||
|
||
- [x] 7.1 `rollout_from = "e1161f7"` в профилях `rollout` и
|
||
`rollout_quick` (комментарий профиля — тоже) и проверка commit до
|
||
стенда по решению 14 и дельте `load-benchmark`. Правило в `bench.md`,
|
||
удаление записи из `KNOWN_ISSUES.md`. Проверка:
|
||
- `uv run python bench/run.py --profile rollout_quick --from 0000000`
|
||
— ненулевой код до запуска стенда, в сообщении commit и `--from`;
|
||
- `make bench_rollout_quick` — код 0, в `meta.json` метки
|
||
`from_commit` `e1161f7`;
|
||
- ревизия до замены — `e656d6bbe1a4`, после — новая.
|
||
- [ ] 7.2 Регресс прежних профилей: `make bench_quick`, `make
|
||
bench_failover_quick`, `make bench_restore_quick` — код 0. В
|
||
`explain-10k.txt` пробной метки узел истории — прежний индекс
|
||
`messages`, а `SubPlan` идёт по `pk_message_attachments` (решение 8).
|
||
Пробные метки `quick-*` в git не идут.
|
||
|
||
## 8. Документы и проверка кода
|
||
|
||
- [x] 8.1 Правила:
|
||
- `api-contract.md` — раздел лабы 4: ручки, коды 413 и 415 в
|
||
таблице, порядок проверок загрузки, `filename` (только символы
|
||
контракта, категория Cc), `UuidIn` для id вложений, ранний ответ и
|
||
`urllib`, пустой текст (в том числе из пробелов) с вложением —
|
||
201 по согласованию с преподавателем;
|
||
- `api-layer.md` — роутер с двумя префиксами, `CurrentUserBrief`,
|
||
тело без параметра, `StreamingResponse`, `UploadInterrupted`;
|
||
- `service-layer.md` — `AttachmentService` с `db_scope`, порядок
|
||
записи, проверка вложений сообщения, хэш;
|
||
- `repo-layer.md` — repo вложений, repo объекта S3, подзапрос
|
||
`ARRAY`;
|
||
- `dto.md` — новые DTO и enum;
|
||
- `migrations.md` — таблицы вложений, ослабление CHECK `NOT VALID`,
|
||
почему не `autocommit_block`;
|
||
- `logging.md` — записи `attachment_service`, `filename` не пишется;
|
||
- `student-tests.md` — `test_attachments.py`, `images.py`, Pillow в
|
||
dev, отказы S3 и действия hook, новые исключения;
|
||
- `settings.md` — `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` —
|
||
константы;
|
||
- `bench.md` — `rollout_from`.
|
||
|
||
Ещё AGENTS.md (карта кода, команды драйвера, «Переход в следующую
|
||
лабу» — `rollout_from`, таблица важных файлов) и `PLAN.md`,
|
||
`### attachments` («Решения» из apply). Проверка: `grep -rn
|
||
"c50b721" AGENTS.md .claude bench KNOWN_ISSUES.md` пуст.
|
||
- [x] 8.2 `make lint`, `make check`, `openspec validate attachments
|
||
--strict`, `graphify update .`. После sync дельт имя `attachments` —
|
||
и change, и спек: `openspec validate attachments --type change
|
||
--strict`.
|
||
|
||
## 9. Коммит, evidence, отчёт
|
||
|
||
- [x] 9.1 Финальная проверка на стенде `mtusi-lab4` после `make
|
||
rolling_update`:
|
||
- `make test` — `PASS: lab4`;
|
||
- `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make
|
||
test-failover ACTION_SCRIPT=scripts/stop-one.sh` — PASS, между
|
||
прогонами `make replicas`;
|
||
- `make student_test` и `make test_isolated` — красное только по
|
||
шапке;
|
||
- `make failure_checks` — код 0.
|
||
|
||
Затем показать изменения, предложить сообщение коммита и после
|
||
подтверждения закоммитить.
|
||
- [ ] 9.2 Evidence исключений с закоммиченного кода, без токенов,
|
||
паролей и секретов S3, в каждом файле дата, commit и стенд:
|
||
- четыре файла перехода по AGENTS.md («Переход в следующую лабу»).
|
||
`evidence/replicas/test-persistence.md` — `make test-persistence` с
|
||
`LAB=4`, `StartedAt` до и после, вложение после hook;
|
||
- `evidence/attachments/failover.md` — `attachment-failover`, оба
|
||
режима;
|
||
- `evidence/attachments/storage.md` — `attachment-storage`.
|
||
|
||
Проверка: `make student_test` — `test_exclusion_evidence_exists`
|
||
зелёный; `grep` по значениям секретов из `.env` в `evidence/` пуст.
|
||
Коммит — после подтверждения.
|
||
- [ ] 9.3 Evidence проверок по таблице решения 15:
|
||
- `evidence/tests/` — зелёные `make test_isolated`, `make
|
||
student_test` через LB, `make failure_checks`;
|
||
- `evidence/attachments/smoke.md`, `slow-transfer.md`;
|
||
- `evidence/failover/test-failover.md` — `make test-failover` с
|
||
`LAB=4` для каждой реплики, `STOP_ONE_LOG`, `docker compose ps` до
|
||
и после, между прогонами `make replicas`.
|
||
|
||
Проверка: в каждом файле команда, итог, дата, commit; секретов нет.
|
||
- [ ] 9.4 Желательно: `make bench_rollout ROLLOUT_LABEL=attachments`
|
||
после проверки хоста (`bench.md`, «Результаты»), рабочий стенд на
|
||
время замера остановлен. Проверка: код 0, в `summary.md` ревизии до и
|
||
после, сверка записей сошлась; метка закоммичена.
|
||
- [ ] 9.5 `REPORT.md` по решению 15:
|
||
- раздел о вложениях;
|
||
- соответствие `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS`;
|
||
- ответы на четыре вопроса защиты;
|
||
- строки уровней «3» и «4» с командой, наблюдением и файлом;
|
||
- ограничения;
|
||
- согласование с преподавателем 2026-10-20: текст из одних пробелов
|
||
с вложением — 201, без вложений — 400 (design, решение 8; AGENTS.md,
|
||
«Согласования с преподавателем»).
|
||
|
||
Строку этапа 2 в `PLAN.md` — по факту. Проверка: у каждой новой строки
|
||
таблицы доказательств есть команда, наблюдение и файл; `make lint`,
|
||
`make check`, `openspec validate attachments --strict`. Коммит — после
|
||
подтверждения.
|