switch_api recreated the API replica with the same IP while HAProxy still showed the old container's slot UP, so restore_check hit 503 <NOSRV> before the new process listened. Wait until each new replica answers /health/ready from inside its container, then for LB UP. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
61 KiB
Design
Context
Мотивация — proposal.md, раздел Why. Требования — specs/.
Код — состояние после s3-storage (e1161f7):
- клиент S3
src/infra/s3/(put,openс чтением блоками,head,delete; срок на вызов и на блок, отказ — 503, ключи с префиксом имени базы); - отправка сообщения — одна транзакция: ключ идемпотентности,
затем сообщение (
MessageService.send_message); - история — keyset по индексу
(chat_id, created_at, id); - ограничение
ck_messages_text_length—char_length(text) BETWEEN 1 AND 4000.
Вложений нет ни в одном слое. Контракт лабы 4 сделал attachment_ids
обязательным полем Message. Поэтому сейчас красные публичные make test, make test-persistence, make test-failover и 32 теста make student_test (PLAN.md, s3-storage → «Решения», п. 15).
Что найдено в коде до решений
Сессия БД держится весь запрос. get_db_session — зависимость с
yield и областью «запрос». В FastAPI 0.141 такая зависимость
закрывается после отправки ответа целиком: стек fastapi_inner_astack
в fastapi/routing.py охватывает и await response(...).
asyncio.timeout([database] request_timeout_seconds) (6 с) внутри неё
покрывает всё: чтение тела, запись в S3, отдачу потока. authenticate
делает SELECT без commit, и соединение пула остаётся занятым
(«idle in transaction») до конца запроса. Для загрузки и скачивания
10 MiB это значит:
- медленный клиент обрывается на 6-й секунде, и в журнале это
«Database is unavailable» (срок даёт
TimeoutError, аis_db_unavailableсчитает его отказом БД); - через 10 с простоя транзакции PostgreSQL убивает соединение
(
idle_in_transaction_session_timeout); - 10 одновременных медленных передач занимают весь пул реплики (10 соединений), и остальные запросы получают 503 по сроку ожидания пула.
Отсюда решение 5.
Пробы (2026-10-20, scratchpad, проект compose attprobe, удалён)
Ранний ответ без чтения тела. Приложение-заглушка на образе
mtusi-messenger:lab4 за HAProxy с infra/haproxy/haproxy.cfg проекта.
Ответы 413 и 404 отдавались до чтения тела, по три прогона:
| Клиент | Напрямую к uvicorn | Через HAProxy |
|---|---|---|
httpx (клиент student-tests), тело 11 и 30 MiB с Content-Length и частями |
ответ получен, соединение переиспользуется | ответ получен |
curl с Expect: 100-continue |
413, тело не отправлено (size_upload 0) |
так же |
urllib (публичные проверки), 30 MiB |
BrokenPipe или ConnectionReset, ответ потерян |
ответ получен |
Отказ по счётчику (413 после 10 MiB + 1) — тот же результат. HAProxy сам дочитывает остаток тела клиента, поэтому через LB ответ доходит до любого клиента.
Медленная передача через HAProxy. 9 MiB загрузки за 12,3 с и 10 MiB
скачивания за 12,3 с прошли, коды 201 и 200. timeout server и
timeout client считают простой, а данные шли. Значит, предел
передачи — в приложении (выше), а не в LB.
Структурная проверка изображения. Прототип на stdlib (zlib,
struct, re), Pillow 13.0.0 — для сравнения и генерации вариантов:
-
17 настоящих вариантов приняты, все загружаются и Pillow:
- PNG: RGB, RGBA, палитра, 1 бит, LA, 16 бит, чересстрочный;
- JPEG: baseline, прогрессивный, с маркерами рестарта, серый, CMYK, 4:4:4, с EXIF;
-
отклонены как повреждённые: PNG и JPEG, обрезанные наполовину; PNG без последнего байта и без IEND (Pillow их грузит); изменённый байт IDAT (CRC); мусор после сигнатуры; JPEG без EOI; обрезанный прогрессивный; только заголовок;
-
приняты и прототипом, и Pillow: хвост после IEND и EOI; изменённый байт в данных скана JPEG — у формата нет контрольной суммы;
-
JPEG с подменёнными в SOF размерами 10000 × 5000 — 413 по заголовку. Pillow декодирует такой файл целиком: 150 МБ памяти из нескольких килобайт;
-
память и время прототипа на пиковых входах:
Вход Итог Время Пик памяти PNG 1 × 40 000 000, 1 бит, «узкий» принят 305 мс 3,3 MiB PNG 8000 × 5000 RGBA из нулей, 160 МБ после распаковки принят 40 мс 3,5 MiB PNG 100 × 100, IDAT распаковывается в 200 MiB отклонён 0,4 мс 2,4 MiB JPEG, 10 MiB вставок FF 00принят 111 мс 0 настоящий PNG 7,6 МБ принят 20 мс 0,3 MiB Пик памяти —
tracemallocповерх тела. -
корпус: 12 000 случайных PNG и JPEG из
/System/Library,/Libraryи/ApplicationsmacOS:- 11 947 приняты и прототипом, и Pillow;
- 38 отклонены обоими;
- 2 отклонены только по лимиту пикселей: 8192 × 8192, 67 млн;
- прототип не принял ни одного файла, который не загрузил бы Pillow.
Первая версия проверяла фильтры строк циклом Python и на PNG 1 × 40 млн тратила десятки секунд. Срез с шагом строки сократил это до 0,3 с, конец данных скана JPEG ищет регулярное выражение — оба в C.
Goals / Non-Goals
Goals:
- Все пункты рубрики «3» о вложениях и негативные тесты рубрики «4»
(
PLAN.md, этап 2), с зелёными публичными проверками лабы 4. - Порядок записи
upload-consistencyрасширяет, а не переписывает: строка-намерение есть с первого дня. - Память одной загрузки ограничена телом и не зависит от числа пикселей. Ни одно соединение пула PostgreSQL не занято на время передачи байтов.
- Прежние профили
bench/и проверки лаб 2–3 работают,rolloutпоказывает замену на схему с вложениями.
Non-Goals:
- Компенсация после PUT, уборщик, его S3-пользователь и частичный
индекс зависших
pending, тесты отказов посреди загрузки —upload-consistency. - Лимит одновременных загрузок, сроки чтения тела, подбор срока PUT
под очередь S3, профиль
uploads—upload-memory. - Декодирование пикселей и варианты (
thumbnail) — lab5. Проверка здесь структурная (решение 2). Range,ETag,Content-Dispositionи кэширование ответа download: контракт их не требует.
Decisions
1. Порядок записи и граница с upload-consistency
Загрузка (AttachmentService.upload):
- Проверки до чтения: членство в чате,
Content-Type,Content-Length. - Чтение тела со счётчиком (решение 6).
- Проверка содержимого и SHA-256 в потоке (решение 2).
- Транзакция 1: строка
attachmentsв статусеpendingсobject_key, commit. PUTобъекта.- Транзакция 2:
UPDATE … SET status = 'ready', updated_at = now WHERE id = … AND status = 'pending' RETURNING …, commit. - 201 с этой строкой.
Отказы:
| Где | Ответ | Что остаётся |
|---|---|---|
| шаги 1–3 (401, 400, 404, 413, 415, обрыв тела) | 4xx | ничего: до шага 4 запись не идёт |
| шаг 4 (БД) | 503 | ничего |
| шаг 5 (S3 недоступен, срок, отказ) | 503 | строка pending; объекта нет, или он записан после истечения срока |
| шаг 6 (БД) | 503 | строка pending и объект |
Строку pending API не показывает: метаданные и байты — 404, ссылка в
сообщении — 404. В этом change её никто не убирает. upload-consistency
добавит компенсацию (DELETE объекта после неудачи на шагах 5–6, без
гарантии), уборщик с grace period и тесты отказов посреди загрузки. Он
меняет только ветки ошибок, порядок шагов остаётся. Если шаг 6 не нашёл
строку pending, значит её удалил кто-то другой. Без уборщика это
невозможно, поэтому RuntimeError (500), как «Idempotency key
disappeared» в send_message. Ветку переопределяет upload-consistency.
Ответ на вопрос защиты «PUT прошёл, COMMIT нет»: строка pending с
ключом уже в БД, объект не «вечный неучтённый», его найдёт уборщик по
строке. Объект без строки возможен только мимо API — класс расхождений
трека 2.
Альтернатива: PUT, затем одна вставка строки ready. Отвергнута:
сбой commit оставляет объект, о котором БД не знает. Найти его можно
только списком bucket, а у ключа API права List нет. upload-consistency
пришлось бы переписывать поток и миграцию. Альтернатива: транзакция,
открытая на время PUT. Отвергнута: соединение и блокировка держатся до
5 с, а сбой commit после PUT всё равно оставляет объект. Альтернатива:
компенсация уже здесь. Отвергнута: без уборщика и тестов отказов
посреди загрузки это половина механизма. Её тесты — upload-consistency.
2. Проверка изображения: структура без декодирования
Чистая функция inspect_image(data, *, max_pixels) -> ImageInfo в
src/utils/image.py, только stdlib. По образцу src/utils/cursor.py
она бросает свои исключения (UnsupportedImage, DamagedImage,
TooManyPixels от ImageError(ValueError)), а сервис переводит их в
доменные (415, 415, 413). Порядок:
- Сигнатура:
\x89PNG\r\n\x1a\n— PNG,FF D8 FF— JPEG, иначеUnsupportedImage. - PNG:
- IHDR первым, 13 байт, глубина допустима для типа цвета, методы сжатия и фильтра 0, чересстрочность 0 или 1;
- размеры больше 40 млн пикселей —
TooManyPixelsдо любой распаковки; - каждый чанк: длина в пределах файла, CRC (
zlib.crc32); - неизвестный критичный чанк (первая буква заглавная) — повреждение;
- PLTE до IDAT и обязателен для типа 3;
- IDAT подряд, поток распаковывается
zlib.decompressobjблоками сmax_length1 MiB. Выход больше ожидаемого — повреждение, сразу. Ожидаемое — строки × (1 + байт в строке), по проходам Adam7 для чересстрочного; - тип фильтра строки ≤ 4: срез распакованного блока с шагом длины строки, проверка в C, без цикла Python по строкам;
- на IEND: поток завершён (
eof) и распакован ровно в ожидаемый объём. Остаток после конца потока zlib в IDAT допускается: libpng считает его безвредным.
- JPEG:
- сегменты с длинами, байты-заполнители
FF; - один SOF (C0–C3, C5–C7, C9–CB, CD–CF), ненулевые размеры, 1–4 компонента, длина сегмента сходится с числом компонент;
- больше 40 млн пикселей —
TooManyPixelsсразу на SOF; - SOS после SOF; конец данных скана — первая серия
FF, за которой не00и не RST0–7, ищется регулярным выражением; - EOI обязателен.
- сегменты с длинами, байты-заполнители
- Байты после IEND или EOI допускаются и остаются частью оригинала.
Проверка, SHA-256 и подсчёт идут одним вызовом
anyio.to_thread.run_sync. Распаковка zlib и SHA-256 отпускают GIL,
event loop не стоит. Свой лимитер, как у KDF, здесь не нужен: память
проверки — единицы MiB (Context). Лимит одновременных загрузок —
upload-memory.
Что это значит для клиента, записано в спеке attachments,
«Повреждённое изображение»:
- обрезанный файл, битая CRC, сломанная структура маркеров, поток zlib не того объёма и «бомба» — 415;
- изменённый байт внутри данных скана JPEG не ловится. Его не ловит и Pillow: libjpeg выдаёт предупреждение и рисует мусор;
- хвост после конца изображения допускается.
Подтверждено пользователем 2026-10-20 (PLAN.md, ### attachments
→ «Вопросы», п. 1): структурная проверка, без полного декодирования.
Альтернатива: полное декодирование Pillow (Image.load()).
Отвергнута:
- 40 млн пикселей RGBA — 160 МБ на загрузку при лимите реплики 512 МБ;
- нужен семафор уже в этом change;
- Pillow не ловит ни битый скан JPEG, ни отсутствие IEND (Context);
- ещё ~10 МБ нативных библиотек в образе.
Pillow понадобится worker лабы 5, у него будет свой бюджет памяти.
Альтернатива: Pillow verify(). Отвергнута: для JPEG почти ничего не
проверяет, для PNG не распаковывает IDAT, «бомбу» не видит.
Альтернатива: только сигнатура и размеры из заголовка. Отвергнута:
обрезанный файл проходил бы, а рубрика «4» требует теста на
повреждённое изображение. Альтернатива: pypng и аналоги. Отвергнута:
чистый Python построчно — секунды на 40 млн пикселей.
3. Схема БД
Ревизия alembic поверх e656d6bbe1a4, первая строка — SET LOCAL lock_timeout = '2s' (migrations.md).
attachments:
| Колонка | Тип | Ограничения |
|---|---|---|
id |
uuid |
PK, назначает сервис |
chat_id, owner_id |
uuid |
FK (chat_id, owner_id) → chat_members(chat_id, user_id): владелец — участник чата |
filename |
text |
char_length 1–255; без /, \ и управляющих символов категории Cc — U+0001–U+001F и U+007F–U+009F, NUL в text PostgreSQL не бывает (то же правило, что в API, решение 10; литерал регулярного выражения проверяется в apply вставками через psql) |
content_type |
text |
IN ('image/png', 'image/jpeg') |
size_bytes |
integer |
1–10 485 760 |
sha256 |
bytea |
octet_length = 32, как request_hash и token_hash |
object_key |
text |
уникальный, octet_length 1–1024 (предел ключа S3) |
status |
text |
IN ('pending', 'ready'); lab5 расширит список заменой CHECK |
created_at, updated_at |
timestamptz |
updated_at >= created_at |
message_attachments — связь с порядком:
| Колонка | Тип | Ограничения |
|---|---|---|
message_id |
uuid |
FK → messages(id) |
position |
smallint |
0–9, PK (message_id, position) |
attachment_id |
uuid |
FK → attachments(id), уникальна пара (message_id, attachment_id), индекс по attachment_id |
created_at |
timestamptz |
время сообщения, как chat_members.created_at — время чата (Base даёт колонку всем моделям) |
Индекс по attachment_id нужен двум вещам: удалению строки pending
уборщиком (иначе проверка FK — полный просмотр связей) и вопросу «на
вложение ссылаются сообщения?» reconciler-а трека 2. FK без ON DELETE: вложение, на которое ссылается сообщение, БД удалить не даст.
Это гипотеза безопасности 5 трека 2 на уровне ограничения.
messages: ck_messages_text_length заменяется ограничением с тем же
именем и условием char_length(text) <= 4000, NOT VALID. Модель —
CheckConstraint(..., name="text_length") с новым условием. Прежние
строки удовлетворяли более строгому условию, проверять их нечего.
VALIDATE держал бы ACCESS EXCLUSIVE, пока идёт полный просмотр
таблицы, а это все реплики без записи. Вне транзакции миграции его не
сделать: autocommit_block alembic зафиксирует DDL раньше
alembic_version, и сбой оставил бы неповторяемую миграцию. Новые
строки NOT VALID проверяет так же. Отметка «не проверено» в каталоге
— цена, она описывается в REPORT.md. Это ослабление ограничения,
поэтому дельта db-migrations разрешает его как расширение. Правило
«непустой текст или хотя бы одно вложение» — в сервисе: в одной строке
messages числа вложений нет.
Принадлежность вложения чату сообщения проверяет сервис в той же транзакции, что и вставку связи. Чат вложения и чат сообщения не меняются, поэтому проверка не устаревает до commit.
Альтернатива: массив uuid[] в messages. Отвергнута: у элементов
массива нет FK, и БД не держит ни существование вложения, ни запрет
удаления используемого. Обратный поиск — только GIN-индекс.
Альтернатива: chat_id в связи и составные FK на attachments(id, chat_id) и messages(id, chat_id). Отвергнута: второму FK нужен
уникальный индекс (id, chat_id) на messages, третий индекс на самой
горячей таблице. Он дорожает каждую запись, в том числе без вложений,
ради правила, которое сервис держит на неизменяемых данных.
Альтернатива: тип ENUM для статуса. Отвергнута: ALTER TYPE … ADD VALUE нельзя использовать в той же транзакции, text + CHECK проще
расширять.
4. Ключ объекта
<namespace>/attachments/<attachment_id>/original:
namespace— имя базы (ObjectStorage.namespace,s3-storage);id—uuid4()сервиса;originalоставляет место вариантам lab5 под тем же префиксом.
Ключ собирает repo src/core/repos/attachment_object.py (repo над S3,
как chat_cache.py над Valkey) и хранится в attachments.object_key.
Путь в S3 не выводится из строки при каждом чтении, поэтому:
- уборщик и reconciler читают ключ из строки, а страница LIST
сверяется запросом
object_key = ANY(...)по уникальному индексу (PLAN.md, гипотеза 2 трека 5); - смена схемы ключей в lab5 (staging-префикс) не трогает прежние строки.
filename в ключ не входит, ключ в ответы API не попадает.
make test_isolated пишет под test_<db>/attachments/… и убирает
префикс test_<db>/ (s3-storage).
Альтернатива: отдельный случайный ключ, не связанный с id.
Отвергнута: bucket приватный, у ключа API нет List, а ключ, связанный с
id, ещё и читается reconciler-ом без БД. Альтернатива: ключ не
хранить, вычислять из id. Отвергнута по двум пунктам выше.
5. Длинные запросы без сессии БД на всё время
db_session_scope()вsrc/api/dependencies.py— асинхронный контекст с телом нынешнегоget_db_session:asyncio.timeout([database] request_timeout_seconds),is_db_unavailable→invalidate(),warningиServiceUnavailable.get_db_sessionпревращается в обёртку над ним, поведение остальных ручек прежнее.get_current_user_brief(типCurrentUserBrief): Bearer из той жеbearer_scheme→async with db_session_scope()→SessionService.authenticate→ выход из контекста (откат, соединение в пул) →current_user_idи пользователь. Это обычная функция, а не генератор: сессия закрыта до тела запроса.AttachmentService(db_scope, cache, storage):db_scope— вызываемый объект, возвращающий такой контекст (db_session_scope);storage— глобалobject_storage. Его, как и прежде, импортирует толькоdependencies.py;- каждый шаг с БД — свой короткий
async with self.db_scope(); - вложенных контекстов нет: в каждый момент на запрос не больше одного соединения пула, взаимной блокировки пула быть не может.
- Ручки вложений — загрузка, метаданные, байты — берут только
CurrentUserBriefиAttachmentServiceDep, безDbSessionDep.
Срок 6 с остаётся на каждом шаге с БД. Передача байтов ограничена
сроками S3 ([s3] timeout_seconds на вызов и на блок чтения) и
таймаутами LB. Срок чтения тела от клиента — upload-memory.
Правило service-layer.md «__init__ принимает db_session» для
AttachmentService меняется: правка правила — задача apply.
Альтернатива: сессия запроса и commit() сразу после проверки
токена. Отвергнута: соединение вернётся, но asyncio.timeout в
get_db_session по-прежнему охватывает передачу (Context).
Альтернатива: Depends(get_db_session, scope="function"). Отвергнута:
контекст закрывается после выхода из функции ручки, а чтение тела и PUT
идут внутри неё. Альтернатива: поднять request_timeout_seconds.
Отвергнута: слабеет защита от зависшего PostgreSQL у всех ручек, а
соединение всё равно занято передачей. Альтернатива: срок на каждый
вызов repo во всех сервисах. Отвергнута: большая переделка без нужды
для коротких JSON-ручек.
6. Чтение тела, ответы до чтения
- Ручка передаёт сервису
media_typeизContent-Type(часть до;, без пробелов, в нижнем регистре),Content-Length(intилиNone) и асинхронный итератор тела. Итератор — обёртка надrequest.stream(), которая переводитClientDisconnectStarlette в доменноеUploadInterrupted(400). Клиента уже нет, но в итоговой записи запроса будет 400, а не 500 с traceback. - Сервис:
media_typeне PNG и не JPEG — 415 до тела;Content-Lengthбольше лимита — 413 до тела;- чтение в
bytearrayсо счётчиком: больше лимита — 413 сразу, без дочитывания; - затем один
bytes(...).
- Пик памяти загрузки — около двух тел (буфер и копия), пока не
отработал PUT. botocore считает CRC32 потоком, без копии. Сколько
таких загрузок помещается в 512 МБ и чем их ограничить —
upload-memory. Content-Length: 0и пустое тело — 415 (не изображение).- Ответы 404, 413 и 415 до чтения тела доходят до httpx, до curl и до
любого клиента через LB (Context).
urllibнапрямую к одной реплике ответ теряет: ограничение, записывается вREPORT.md. Публичные проверки больших тел не шлют. - Порядок проверок — спек «Порядок проверок загрузки». 401 и 400
(
chat_id,filename) даёт FastAPI: параметры проверяются после зависимостей, как у сообщений (api-contract.md). 404 и остальное — сервис.
7. Скачивание
- Сервис
open_content:- Короткая транзакция: строка вложения в статусе
readyи членство в его чате черезChatService.get_chat_for_member(кэш карточки). Нет строки, неreadyили не участник —AttachmentNotFound(404). - Вне транзакции:
object_storage.open(key)— GET с заголовками. Отказ S3 — 503 ещё до заголовков ответа API. - Нет объекта (
StoredObjectMissing) или размер в S3 не равенsize_bytes—error«Attachment content is missing» или «…size differs» сattachment_idи ключом, затемAttachmentContentMissing(500internal_error). Строку сервис не меняет: промах не основание для разрушающего решения (PLAN.md,s3-storage→ «Вопросы», п. 4). Как помечать такие строки, решит reconciler трека 2. - DTO с типом, размером и асинхронным генератором блоков
StoredObject.iter_chunks()(срок на блок — клиент S3).
- Короткая транзакция: строка вложения в статусе
- Ручка —
StreamingResponse:media_type—content_typeвложения: уimage/*Starlette не добавляетcharset;Content-Lengthизsize_bytes,X-Content-Type-Options: nosniff;variant: Literal["original"] = "original": иное значение — 400 по схеме, как перечисление контракта лабы 4.
- Генератор закрывает объект в
finally, когда поток дочитан, оборван клиентом или упал. Если генератор так и не начался, тот же закрыватель вызывает фоновая задача ответа. Закрытие повторно безопасно. - Отказ S3 посреди потока: статус уже ушёл. Соединение обрывается,
клиент получает тело короче
Content-Length, в журнале — запись клиента S3 и ошибка ASGI. Иначе нельзя без буферизации всего файла.
Альтернатива: прочитать объект целиком и отдать Response.
Отвергнута: до 10 MiB в памяти на каждое скачивание.
Альтернатива: redirect на подписанный URL. Отвергнута: контракт
требует отдачи без redirect, S3 вне сети клиента.
8. Сообщения с вложениями
-
CreateMessage:text: StrictStr, до 4000 code points;attachment_ids: list[UuidIn], по умолчанию[],max_length10;- валидатор модели: повтор id (сравнение
UUID, регистр не важен) — 400; пустой текст —""или из одних пробельных символов (not text.strip()) — без вложений 400, с хотя бы одним вложением допустим (спекmessages, «Валидация текста»). Текст не обрезается и не нормализуется.
Согласовано с преподавателем 2026-10-20 (AGENTS.md, «Согласования с преподавателем»;
PLAN.md,### attachments→ «Вопросы», п. 2). Контракт был неоднозначен: общее правило «обязательные строки не из одних пробелов» (contracts/README.md, строка 9) против «нельзя … пробельный текст без вложений» (строка 18). Ответ: «пустой текст» — и"", и строка из одних пробелов; с вложением он допустим, без вложений — 400. До ответа действовала временная трактовка «пробелы с вложением — 400»; её сменила эта. -
MessageService.send_message(..., attachment_ids):- членство;
- вложения:
attachment_repo.get_attachments(ids)— не больше 10 строк по первичному ключу. Все найдены, у всех чат этого сообщения, статусready. ИначеAttachmentNotFound(404) до захвата ключа: ошибка не занимает ключ; - хэш, захват ключа, вставка сообщения;
message_repo.insert_message_attachments— одна многострочная вставка сposition;- один commit.
-
MessageFullDTOполучаетattachment_ids: tuple[UUID, ...] = (). Вставка сообщения перечисляет свои колонки явно, а не**asdict(message). -
Чтение: в
MESSAGE_COLUMNS— коррелированный подзапросARRAY(SELECT attachment_id FROM message_attachments WHERE message_id = messages.id ORDER BY position) AS attachment_ids. Это одно выражение на страницу (repo-layer.md), им же читает сохранённый результатidempotency_repo.get_key_result. План —SubPlanс индексомpk_message_attachmentsна каждую строку страницы, индекс истории прежний. В apply проверяетсяEXPLAIN (ANALYZE, BUFFERS). -
Разбор журнала
bench/run.pyс новым запросом сверен по коду:INDEX_NODE_REберёт первый узел индекса:SubPlanEXPLAIN печатает после потомков, поэтому первым остаётся индексmessages;or_cursorменяет только условиеWHERE;plan_summaryищет узелon messages, аon message_attachmentsс ним не совпадает.
Регресс —
make bench_quick. -
Журнал:
Created messageполучаетattachments_count.
9. Хэш идемпотентности
message_request_hash(text, attachment_ids):
- канонический JSON
{"text": t}, при непустом списке — ещё"attachment_ids": [str(id), …]; str(UUID)пишет нижний регистр, поэтому регистр в запросе хэш не меняет, а порядок элементов меняет;- пустой список не меняет хэш: ключ, сохранённый версией
e1161f7, повторяется послеmake rolling_updateбез 409 (PLAN.md, решение 6).
Повтор отдаёт сохранённое сообщение с его attachment_ids (решение 8).
10. Слой API и ошибки
-
src/api/routers/v1/attachment.py:APIRouter(tags=["attachments"])с полными путями/chats/{chat_id}/attachmentsи/attachments/{attachment_id}[/content], подключение вrouters/v1/__init__.py. Два префикса в одном роутере — отличие отapi-layer.md, правило дополняется. -
Загрузка:
-
request: Requestбез параметра тела — FastAPI тело не читает; -
openapi_extraсrequestBodyimage/pngиimage/jpeg(format: binary), как в контракте: так/docsпоказывает загрузку; -
filename—Query(min_length=1, max_length=255)над типомDisplayFilenameвsrc/api/schemas/attachment.py. ЕгоAfterValidatorотклоняет/,\, управляющие символы категории Cc (U+0000–U+001F, U+007F–U+009F;unicodedata.category(ch) == "Cc") и строку из одних пробелов. Остальное принимается: символы форматирования и направления текста (Cf), разделители U+2028 и U+2029 (Zl, Zp), ZWJ.Альтернатива: отказ ещё и на символы направления текста (U+202A–U+202E, U+2066–U+2069) и разделители строк (U+2028, U+2029). Ими подменяют видимое имя: U+202E перед
gnp.exeпоказывает его задом наперёд. Отвергнута решением пользователя 2026-10-20 (PLAN.md,### attachments→ «Вопросы», п. 3):- контракт называет только
/,\, NUL и управляющие символы, и отказ сверх списка — расхождение с ним; - эти символы встречаются и в законных именах на языках с письмом справа налево;
- имя только отображается, ни в ключ, ни в путь не попадает, а изолировать направление текста при показе может клиент.
- контракт называет только
-
-
Модель ответа
Attachment:sha256— hex изbytesDTO;status: Literal["ready"],variants— всегда[],error_code: None;- времена —
UtcDatetime; - лишних полей нет,
object_keyв модель не входит.
-
Доменные исключения в
src/core/exceptions/attachment.pyи строки таблицыerrors.py:Исключение Ответ AttachmentNotFound404 not_found, «Not found»PayloadTooLarge413 payload_too_largeUnsupportedMediaType415 unsupported_media_typeUploadInterrupted400 invalid_requestAttachmentContentMissing500 internal_error, «Internal server error»Тексты — на английском, без внутренних деталей.
-
Константы в
src/utils/constants.py:- лимиты:
ATTACHMENT_MAX_BYTES10 485 760,ATTACHMENT_MAX_PIXELS40 000 000, длиныfilename,MESSAGE_ATTACHMENTS_MAX10; - ключ объекта: префикс
attachments, суффиксoriginal; - запрещённые символы
filename:/,\и категория Cc.
- лимиты:
-
Enum
AttachmentStatus(pending,ready) иImageType(image/png,image/jpeg) —src/schemas/enums/attachment.py. DTOAttachmentFullDTO,AttachmentContentDTO—src/schemas/dataclasses/ attachment.py. -
MAX_UPLOAD_BYTESиMAX_IMAGE_PIXELSskeleton — эти константы, не настройки (дельтаservice-configuration). Соответствие — вREPORT.md,.env.exampleих не заводит.
11. Журнал
- Модуль
attachment_service:info«Uploaded attachment»:attachment_id,chat_id,size_bytes,content_type,width,height,duration_ms;info«Rejected attachment»: причина (type,declared_size,size,content_mismatch,damaged,pixels,interrupted),chat_idи длинаfilename;errorо пропавшем объекте — решение 7.
filenameи байты не пишутся (дельтаservice-logging), ключ объекта допустим (logging.md).
12. Тесты
-
pillow— только dev-группа (uv add --dev pillow): генерация JPEG разных видов в памяти теста. В образ (uv sync --no-dev) и в приложение не входит. -
student-tests/images.py— генераторы:- PNG на stdlib с любыми IHDR и IDAT, Adam7, чанком-заполнителем
tEXtдо точного размера (10 485 760 и +1), «бомбой», порчей CRC, обрезкой и хвостом; - JPEG через Pillow с подменой размеров в SOF, обрезкой и хвостом.
Большие и «бомбы» в git не попадают (
tests/fixtures/README.md). - PNG на stdlib с любыми IHDR и IDAT, Adam7, чанком-заполнителем
-
test_attachments.py— сценарии спекаattachments, маркерыspec. «Скачивание через другую реплику» — с фикстуройreplicas: скачивать, пока ответ не придёт с другимX-Instance-Id. -
test_rubric.py— пять сценариев рубрики «4» лабы 4 (дельтаstudent-tests) с маркерами сценариевattachmentsиmessages. -
Дополняются:
test_messages.py,test_idempotency.py,test_api_conventions.py,test_data_storage.py— новые сценарии дельт;api_client.py— загрузка, метаданные, байты,send_message(..., attachment_ids=…);contract.py:- коды 413 и 415;
owner_idи элементыattachment_ids— UUID в нижнем регистре,updated_at— время;assert_contentдля бинарного ответа.
-
Проверки отказов (
test_failures.py): «Запись в S3 не удалась», «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 завис».- Новые действия hook:
count-attachments(pending=N ready=Mчерез psql) иcount-objects(число каталогов вложений в/buckets/<bucket>/<db>/attachmentsчерез filer на loopback контейнераs3). Bucket и базу hook получает отrun_failures.pyв окружении. - Срок «S3 завис» —
[s3] timeout_seconds(5 с) плюс запас.
- Новые действия hook:
-
Сверка покрытия:
attachmentsвCAPABILITIES. Исключения с доказательствами:- «Принявшая реплика остановлена» →
driver.py attachment-failover,evidence/attachments/failover.md; - «Байты не в БД и не на диске API» →
driver.py attachment-storage,evidence/attachments/storage.md; - «Рестарт стенда» →
make test-persistence,evidence/replicas/test-persistence.md: публичная проверка сLAB=4скачивает оригинал после hook.
- «Принявшая реплика остановлена» →
-
Дельты, на сценарии которых ставят маркеры, синхронизируются в основные спеки в apply (
/opsx:sync), какhealthвs3-storage: сверка читает толькоopenspec/specs/.
13. Драйвер скилла run-mtusi-messenger
Только stdlib, Python 3.9.
-
upload --token T --chat C --file F [--type …] [--filename …]— статус,X-Instance-Id, тело, SHA-256 файла. -
download --token T --attachment A [--out F] [--variant …]— статус,X-Instance-Id,Content-Type, размер, SHA-256 полученного. -
attachment-failover [--mode stop|kill]— стенд с LB:- синтетические Алиса, Боб, Ева, чат;
- загрузка
tests/fixtures/sample.png, реплика A; - сообщение со ссылкой;
scripts/stop-one.shсTARGET_INSTANCE_ID=A;- Боб скачивает через LB: ответ от B ≠ A, SHA-256 совпадает;
- Ева — 404;
- в
finally—make replicas.
Вывод —
docker compose psдо и после и таблица без токенов. Код 1 при любом расхождении. -
attachment-storage— стенд с LB:- загрузки через LB;
- psql: колонки и типы таблиц вложений (нет колонки с байтами, кроме
32-байтного SHA-256), вид
object_key,filenameне в ключе; weed shell/ filer: объект есть;- анонимный GET ключа с
127.0.0.1:S3_OUT_PORT: 403; docker diffкаждой реплики: файлов оригиналов нет.
Пункты 2 и 4 сценария защиты.
-
flowзагружает fixture, отправляет сообщение с вложением, скачивает его как Боб (SHA-256) и проверяет 404 Евы.
14. Профиль rollout и rollout_from
Profile.rollout_from = "e1161f7": последний commit лабы 4 доattachments. Замена показывает миграцию вложений с ослаблением ограничения под нагрузкой.- До сборки стенда —
git rev-parse <commit>^{commit}. Commit не найден —BenchErrorс commit и подсказкой--from(дельтаload-benchmark), а не падение на шестой секунде. - Правило в
bench.mdи AGENTS.md («Переход в следующую лабу»):rollout_fromменяется при переходе в лабу и когда замена должна показать новое изменение схемы. - Запись
KNOWN_ISSUES.mdоc50b721удаляется. - Evidence —
make bench_rollout ROLLOUT_LABEL=attachments(желательно,PLAN.md): старые реплики на новой схеме, одна миграция, ошибки по секундам. - Нагрузка профиля — запись и чтение сообщений, S3 стенд
bench/не запускает. Методика прежняя (bench.md).
15. Evidence и отчёт
| Файл | Что |
|---|---|
evidence/attachments/smoke.md |
make test (PASS: lab4), driver.py upload / download Бобом с SHA-256, 404 Евы на метаданные и байты |
evidence/attachments/failover.md |
driver.py attachment-failover в режимах stop и kill |
evidence/attachments/storage.md |
driver.py attachment-storage: схема, ключи, объект, анонимный 403, docker diff |
evidence/attachments/slow-transfer.md |
разовый скрипт: 10 MiB загрузки и скачивания через LB дольше 6 с проходят (решение 5) |
evidence/failover/test-failover.md |
make test-failover с LAB=4 для каждой реплики, STOP_ONE_LOG, docker compose ps до и после |
evidence/cache/hits.md, evidence/auth/passwords-and-tokens.md, evidence/replicas/test-persistence.md, evidence/idempotency/replay-after-restart.md |
исключения сверки, сняты на стенде лабы 4 (AGENTS.md, «Переход в следующую лабу») |
evidence/tests/ |
зелёные make test_isolated, make student_test через LB, make failure_checks |
evidence/rollout/attachments/ |
make bench_rollout с e1161f7 на схему с вложениями (желательно) |
REPORT.md:
- раздел о вложениях: схема потока, порядок записи и таблица отказов, проверка изображения и её граница, схема БД и ключ;
- соответствие
MAX_UPLOAD_BYTES,MAX_IMAGE_PIXELS; - ответы на четыре вопроса защиты;
- строки уровней «3» и «4» с командой, наблюдением и файлом;
- ограничения: структурная проверка,
NOT VALID,urllibнапрямую, смешанные версии при замене; - согласование с преподавателем 2026-10-20: текст из одних пробелов с вложением — 201, без вложений — 400 (решение 8, AGENTS.md, «Согласования с преподавателем»).
Risks / Trade-offs
- [Структурная проверка не ловит искажения внутри данных скана JPEG] →
граница названа в спеке и
REPORT.md. Pillow её тоже не ловит. Lab5 декодирует оригинал в worker, и такой файл получит статусfailed. - [Свой разборщик отклонит настоящий файл] → корпус 12 000 файлов без
ложных отказов (Context); в тестах матрица вариантов; в apply корпус
гоняется ещё раз на готовом
src/utils/image.py. - [CPU проверки: до ~0,3 с на «узкий» PNG и ~0,1 с на JPEG из вставок]
→ в потоке, event loop не стоит. Лимит параллельных загрузок —
upload-memory. - [Память загрузки ~2 × тело без лимита конкурентности: около 30
одновременных загрузок по 10 MiB доводят реплику 512 МБ до OOM] →
граница описана, лимит и замер —
upload-memory. До него нагрузочные прогоны загрузок не запускаются. - [PUT 10 MiB со сроком 5 с: под очередью S3 последняя из 20
одновременных записей подтверждена через 7,2 с] → 503 и строка
pending, клиент повторяет загрузку. Срок PUT и лимит конкурентности —upload-memory, объекты таких отказов —upload-consistency. - [После тела LB ждёт ответа
timeout server(10 с), а худший путь — шаг БД, PUT до 5 с и ещё шаг БД] → обычно десятки миллисекунд. В худшем случае клиент получает 504 от LB, а API может довести загрузку доready. Повтор клиента создаёт второе вложение — контракт это допускает. Цепочку пересматриваетupload-memory. - [Нет срока чтения тела: медленный клиент держит загрузку] → ни
соединения пула, ни транзакции он не держит (решение 5), память — до
лимита. Срок —
upload-memory. - [Строки
pendingкопятся до уборщика] → только при отказах S3 и БД посреди загрузки. Их видно счётчиком hook. Уборщик —upload-consistency, следующий change. - [Смешанные версии при
make rolling_update: старая реплика отвечает 404 на пути вложений и 400 наattachment_ids, а сообщения отдаёт безattachment_ids] → окно замены; описывается вREPORT.md. Откат наe1161f7(MIGRATE=0) прячет вложения и показывает пустые тексты сообщений с вложениями: схема при этом не откатывается. - [
NOT VALIDв каталоге] → смысл ограничения тот же. Проверить существующие строки можно отдельной миграцией, когда это понадобится. - [
urllibнапрямую к одной реплике теряет ранний 413] → через LB доходит; тесты на httpx; ограничение вREPORT.md. - [Дельты синхронизируются в основные спеки до archive] → если
/opsx:verifyпоменяет дельты, sync повторяется; archive не дублирует требования. - [Обрыв S3 посреди скачивания обрывает ответ после заголовков] →
клиент видит тело короче
Content-Length, в журнале — причина.
Migration Plan
- Константы, enum, DTO, исключения,
src/utils/image.py. - Модели и ревизия alembic: autogenerate, затем руками ограничение
NOT VALIDиlock_timeout. Проверки — с нуля, повторно и под записью прежней версии. - Repo, сервисы, зависимости, ошибки, схемы и ручки API.
- Драйвер, тесты, hook стенда отказов, sync дельт,
make lint, прогоны. rollout_from, регрессbench/.- Правила, AGENTS.md, скилл,
KNOWN_ISSUES.md,PLAN.md. - Commit после подтверждения пользователя, затем evidence, затем
REPORT.md— каждый шаг отдельным commit с подтверждения.
На рабочем стенде новый код — make rolling_update: одна миграция,
затем замена по одной. Bootstrap S3 не меняется, переменных в .env
не добавляется.
Откат — make rolling_update COMMIT=e1161f7 MIGRATE=0. Схема остаётся:
прежний код таблиц вложений не знает, ослабленное ограничение ему не
мешает. Загруженные вложения остаются в БД и S3 и снова видны после
возврата вперёд.
Уточнения apply
src/utils/image.pyна готовом модуле (задача 1.2, 2026-10-20, scratchpad, Pillow 13.0.0 черезuv run --no-project --with pillow): 17 вариантов приняты (PNG RGB, RGBA, палитра, 1 и 2 бита, LA, 16 бит, серый, Adam7; JPEG baseline, прогрессивный, с RST, серый, CMYK, 4:4:4, EXIF); повреждённые из Context —DamagedImage(PNG без последнего байта и без IEND Pillow грузит); хвосты и байт скана JPEG приняты; SOF 10000 × 5000 и IHDR 40 000 001 —TooManyPixels; «бомба» — 1,0 мс, PNG 1 × 40 млн — 56 мс, 8000 × 5000 RGBA — 27 мс, JPEG изFF 0010 MiB — 40 мс, пикtracemalloc≤ 3,2 MiB; корпус 12 000 файлов: 11 964 приняты обоими, 34 отклонены обоими, 2 — только по лимиту пикселей, ложных отказов 0. Вход IDAT подаётся кусками по 64 KiB: иначеunconsumed_tailкопирует остаток большого чанка на каждом блоке выхода.- План истории (задача 7.2): на стенде
bench/таблицаmessage_attachmentsпуста, иSubPlanидётSeq Scanпо пустой таблице (0 страниц) — индекс истории прежний (explain-10k.txtпробной метки). С данными (20 000 сообщений, 40 000 связей в откатываемой транзакции на рабочей базе)SubPlan—Bitmap Index Scan on pk_message_attachments, 51 цикл, страница 0,2 мс. Решение 8 этим подтверждено; формулировку задачи 7.2 («SubPlanпоpk_message_attachments») пустая таблица стенда не показывает. - Причины отказа загрузки в журнале (решение 11): к списку
добавлена
content— содержимое не PNG и не JPEG (UnsupportedImage), отдельно отdamaged(структура нарушена) иcontent_mismatch(тип содержимого не совпал сContent-Type). variantв/openapi.json:Literal["original"]pydantic пишет какconst;Query(json_schema_extra={"enum": ["original"]})добавляет перечисление контракта.- Тест «S3 завис»: клиент
Apiнабора со сроком 5 с обрывал запрос раньше ответа API (503 через 5,0 с). Тест берёт клиента со сроком 15 с — дефект теста, не приложения. - Имя ограничения в ревизии:
drop_constraintбезop.f(...)применял шаблон имён и искалck_messages_ck_messages_text_length(видно вupgrade --sql); исправлено до применения. - Тексты из пробелов с вложением — ответ преподавателя 2026-10-20 пришёл во время apply (решение 8): валидатор сразу написан под 201; «сначала красный» тест на прежнем валидаторе не показывался — прежней версии с вложениями не было.
bench_restore_quick(задача 7.2) падал из-за гонки стенда, не кода вложений:switch_apiпересоздаёт реплику с тем же IP, иwait_readyвидел устаревшийUPслота от прежнего контейнера (3 из 4 полных прогонов на размере 10k; журнал LB:ECONNREFUSED→DOWN→ 503<NOSRV>на запросы k6, процесс поднялся через ~0,7 с).- Исправление гонки — в этом change (решение основной сессии
2026-10-21: PLAN.md требует, чтобы возможности лаб 2–3, в том числе
bench_restore, работали после каждого change, а 7.2 — задача этого change).switch_apiпослеup --force-recreateсначала ждёт, что процесс каждой новой реплики сам отвечает на/health/ready(Stand.wait_processes_ready:docker execтой же команды, что HEALTHCHECK образа, — только docker CLI), и лишь потомwait_ready. После готовности процесса проверки LB успешны: слот, помеченныйDOWNдо неё, дождётся сноваUP, а не помеченный ведёт на готовый процесс. Альтернатива: ответ через LB сX-Instance-Idнового контейнера — нужен запрос из сети стенда (контейнер k6) на каждое ожидание, а оркестратор управляет только docker CLI. Альтернатива: ждать перехода слота вDOWN— не наступит, если процесс успел подняться до следующей проверки LB, и ожидание зависло бы. Проверка:make bench_restore_quickтрижды подряд и--sizes 10000трижды — код 0;bench_quick,bench_failover_quick,bench_rollout_quick— код 0.
Open Questions
Текст из одних пробелов вместе с вложением— закрыт 2026-10-20 ответом преподавателя: 201 с вложением, 400 без (решение 8).- Что API отвечает, когда у строки
readyнет объекта или он другого размера: сейчас 500 иerrorв журнале (решение 7). Пометку таких строк и ответ после неё решит reconciler трека 2. Спеки этого change это не меняет. - Срок PUT большого объекта под одновременной записью: отдельный срок по
размеру или общий
[s3] timeout_seconds. Решитupload-memoryпо замеру.