- keep one upload body in memory: BytesIO + getvalue() without copy, fixed glibc mmap threshold in the image (no realloc copy on growth) - stop PNG inflate at expected size + 1 byte - reject filename that is not valid UTF-8 after percent-decoding (400) - failure stand: env limit variables do not change attachment limits; history with attachment_ids while S3 is stopped - drop dead constants; restate "old image on new schema" scenario Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
28 KiB
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, исключения, проверка изображения
-
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(…)"без ошибок. - константы в
-
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. Схема БД
-
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). -
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 — отказ;
- строка с каждым нарушением CHECK отклонена: размер, SHA-256, тип,
статус,
\d attachments,\d message_attachments— по таблице решения 3.
- первая строка
3. Repo и сервисы
-
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. -
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. -
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
-
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-ручки не изменились. -
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. -
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.
- 413 по
- Разовый скрипт в scratchpad (решение 5): загрузка 10 MiB частями за ~12 с и скачивание 10 MiB с чтением за ~12 с через LB — 201 и 200 без «Database is unavailable» в журнале.
5. Тесты
-
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его принимает.
-
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.
- загрузка, метаданные, байты,
-
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— новые тесты проходят; на рабочем стенде через LBreplicas-тест выполняется, вtest_isolatedпропущен с причиной. -
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. -
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
- 6.1 Команды
uploadиdownloadпо решению 13. Проверка противdriver.py startи стенда (--port 8080): загрузкаtests/fixtures/sample.png, скачивание вторым участником — SHA-25699ea7533…совпадает; 404 постороннему;ruff format --checkиmake lintпроходят. - 6.2
attachment-failover [--mode stop|kill]по решению 13. Проверка на стенде: оба режима — код 0, скачивание от реплики с другимX-Instance-Id, SHA-256 совпал, после команды сноваAPI_REPLICASрепликUP(make lb_stats). Отрицательная проверка: без балансировщика (--portконсольного процесса) — код 2 и понятное сообщение. - 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.
- 6.4
flowс вложением по решению 13, раздел о вложениях вSKILL.md: команды, gotchas —urllibнапрямую к реплике и ранний 413; S3 нужен только путям вложений. Проверка:driver.py all— код 0,FAILED: none.
7. Стенд bench/
- 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_commite1161f7;- ревизия до замены —
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 не идут. Уточнения apply 2, 8, 9: на пустой таблице стендаSubPlan—Seq Scan, с данными —pk_message_attachments; гонкаswitch_apiвbench_restoreисправлена в этом change (restore_quickтрижды и--sizes 10000трижды — код 0).
8. Документы и проверка кода
-
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— таблицы вложений, ослабление CHECKNOT 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пуст. -
8.2
make lint,make check,openspec validate attachments --strict,graphify update .. После sync дельт имяattachments— и change, и спек:openspec validate attachments --type change --strict.
9. Коммит, evidence, отчёт
-
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/пуст. Коммит — после подтверждения. - четыре файла перехода по AGENTS.md («Переход в следующую лабу»).
-
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. Коммит — после подтверждения.
10. Замечания проверки
Находки /opsx:verify 2026-10-21, все решено исправить. Требования
меняются и в дельте change, и в основном спеке (они синхронизированы).
Порядок: код и документы 10.1–10.3, 10.5–10.8 → проверки 10.9 → commit
основной сессией → 10.4 на чистом дереве. Невидимость pending через
API (S6) — задача change upload-consistency (PLAN.md).
- 10.1 W1. Тело загрузки без второй копии:
_read_bodyкопит блоки вio.BytesIOи отдаётgetvalue()—bytesнад тем же буфером, без копии;inspect_image,hashlibи botocore (PutObjectоборачиваетbytesвBytesIOбез копии,bytearrayкопирует) получаютbytes. В образеMALLOC_MMAP_THRESHOLD_=131072: с динамическим порогом glibc вторая загрузка росла в куче с копией вrealloc. Design (решение 6, Risks), правилоdocker.md; строкаREPORT.md(«~2 тела») — в 10.4, после commit. Проверка: пик памяти чтения тела 10 MiB блоками по 64 KiB с проверкой и SHA-256 до и после —tracemallocиVmHWMв образе API (Linux, CPython образа), три загрузки подряд, итог — в design, «Уточнения apply», п. 10. - 10.2 W2.
_IdatStream._inflate:max_length = min(предел блока, ожидаемое − распаковано + 1), выход из цикла — по этомуmax_length. Проверка: пробаprobe_inflate.py(scratchpad) — «бомба» распакована не больше ожидаемого + 1; корпус задачи 1.2 без новых отказов;test_attachments.pyзелёный. - 10.3 W3. Сценарий
db-migrations«Старый образ на новой схеме» (дельта и основной спек): проверки, которые прежний образ проходил на прежней схеме, проходят и на новой; запись и история через прежние реплики — 201 и 200; доказательство —evidence/rollout/attachments/summary.md. Проверка:openspec validatechange и спеков. - 10.4 S1. Пересъёмка
evidence/rollout/attachments/с чистого дерева после commit правок: старую метку удалить, проверка хоста, рабочий стенд —make stop,make bench_rollout ROLLOUT_LABEL=attachments, стенд вернуть; строкиREPORT.md— замена реплик по новым данным и память загрузки («~2 тела» → ~1,2 тела по замеру 10.1,MALLOC_MMAP_THRESHOLD_), новый сценарий «Имя не в UTF-8», если отчёт перечисляет сценарииfilename. Проверка:git.dirtyвmeta.json—false, код 0, ревизии до и после, сверка записей. - 10.5 S2.
src/utils/constants.py:MESSAGE_TEXT_MIN_LENGTHиATTACHMENT_READ_CHUNK_BYTESудалены (размер блока задаёт uvicorn). Проверка:grepпоsrc/пуст,make lint. - 10.6 S3.
filenameс неверным UTF-8 после процент-декодирования (a%FFb.png) — 400 вместо 201 с U+FFFD: ручка строго разбираетscope["query_string"]. Новый сценарий спекаattachments«Имя не в UTF-8» (дельта и основной спек) и тест вtest_attachments.py. Проверка: тест красный на коде до правки (201), зелёный после. - 10.7 S4. «Окружение не меняет лимит» (
service-configuration): обычный API стенда отказов запускается сMAX_UPLOAD_BYTES=1иMAX_IMAGE_PIXELS=1, тестfaultпроверяет, что переменные заданы, и грузитsample.png— 201. Проверка:make failure_checks. - 10.8 S5.
test_object_storage_stopped: при остановленном S3 история чата сattachment_ids— 200 (api.all_messages), в ней сообщение со ссылкой на вложение. Проверка:make failure_checks. - 10.9 Проверки:
make lint,make check,openspec validate attachments --type change --strict,openspec validate --specs,make rolling_update,make test,make student_testчерез LB,make failure_checks. Затем отчёт и сообщение commit основной сессии.