- 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>
817 lines
59 KiB
Markdown
817 lines
59 KiB
Markdown
# 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`
|
||
и `/Applications` macOS:
|
||
- 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`):
|
||
1. Проверки до чтения: членство в чате, `Content-Type`,
|
||
`Content-Length`.
|
||
2. Чтение тела со счётчиком (решение 6).
|
||
3. Проверка содержимого и SHA-256 в потоке (решение 2).
|
||
4. Транзакция 1: строка `attachments` в статусе `pending` с
|
||
`object_key`, commit.
|
||
5. `PUT` объекта.
|
||
6. Транзакция 2: `UPDATE … SET status = 'ready', updated_at = now
|
||
WHERE id = … AND status = 'pending' RETURNING …`, commit.
|
||
7. 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). Порядок:
|
||
1. Сигнатура: `\x89PNG\r\n\x1a\n` — PNG, `FF D8 FF` — JPEG, иначе
|
||
`UnsupportedImage`.
|
||
2. PNG:
|
||
- IHDR первым, 13 байт, глубина допустима для типа цвета, методы
|
||
сжатия и фильтра 0, чересстрочность 0 или 1;
|
||
- размеры больше 40 млн пикселей — `TooManyPixels` до любой
|
||
распаковки;
|
||
- каждый чанк: длина в пределах файла, CRC (`zlib.crc32`);
|
||
- неизвестный критичный чанк (первая буква заглавная) — повреждение;
|
||
- PLTE до IDAT и обязателен для типа 3;
|
||
- IDAT подряд, поток распаковывается `zlib.decompressobj` блоками с
|
||
`max_length` 1 MiB. Выход больше ожидаемого — повреждение, сразу.
|
||
Ожидаемое — строки × (1 + байт в строке), по проходам Adam7 для
|
||
чересстрочного;
|
||
- тип фильтра строки ≤ 4: срез распакованного блока с шагом длины
|
||
строки, проверка в C, без цикла Python по строкам;
|
||
- на IEND: поток завершён (`eof`) и распакован ровно в ожидаемый
|
||
объём. Остаток после конца потока zlib в IDAT допускается: libpng
|
||
считает его безвредным.
|
||
3. JPEG:
|
||
- сегменты с длинами, байты-заполнители `FF`;
|
||
- один SOF (C0–C3, C5–C7, C9–CB, CD–CF), ненулевые размеры, 1–4
|
||
компонента, длина сегмента сходится с числом компонент;
|
||
- больше 40 млн пикселей — `TooManyPixels` сразу на SOF;
|
||
- SOS после SOF; конец данных скана — первая серия `FF`, за которой
|
||
не `00` и не RST0–7, ищется регулярным выражением;
|
||
- EOI обязателен.
|
||
4. Байты после 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()`,
|
||
которая переводит `ClientDisconnect` Starlette в доменное
|
||
`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`:
|
||
1. Короткая транзакция: строка вложения в статусе `ready` и членство
|
||
в его чате через `ChatService.get_chat_for_member` (кэш карточки).
|
||
Нет строки, не `ready` или не участник — `AttachmentNotFound`
|
||
(404).
|
||
2. Вне транзакции: `object_storage.open(key)` — GET с заголовками.
|
||
Отказ S3 — 503 ещё до заголовков ответа API.
|
||
3. Нет объекта (`StoredObjectMissing`) или размер в S3 не равен
|
||
`size_bytes` — `error` «Attachment content is missing» или «…size
|
||
differs» с `attachment_id` и ключом, затем `AttachmentContentMissing`
|
||
(500 `internal_error`). Строку сервис не меняет: промах не основание
|
||
для разрушающего решения (`PLAN.md`, `s3-storage` → «Вопросы»,
|
||
п. 4). Как помечать такие строки, решит reconciler трека 2.
|
||
4. 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_length` 10;
|
||
- валидатор модели: повтор 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)`:
|
||
1. членство;
|
||
2. вложения: `attachment_repo.get_attachments(ids)` — не больше 10
|
||
строк по первичному ключу. Все найдены, у всех чат этого
|
||
сообщения, статус `ready`. Иначе `AttachmentNotFound` (404) до
|
||
захвата ключа: ошибка не занимает ключ;
|
||
3. хэш, захват ключа, вставка сообщения;
|
||
4. `message_repo.insert_message_attachments` — одна многострочная
|
||
вставка с `position`;
|
||
5. один 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` берёт первый узел индекса: `SubPlan` EXPLAIN
|
||
печатает после потомков, поэтому первым остаётся индекс `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` с `requestBody` `image/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 из `bytes` DTO;
|
||
- `status: Literal["ready"]`, `variants` — всегда `[]`,
|
||
`error_code: None`;
|
||
- времена — `UtcDatetime`;
|
||
- лишних полей нет, `object_key` в модель не входит.
|
||
- Доменные исключения в `src/core/exceptions/attachment.py` и строки
|
||
таблицы `errors.py`:
|
||
|
||
| Исключение | Ответ |
|
||
|---|---|
|
||
| `AttachmentNotFound` | 404 `not_found`, «Not found» |
|
||
| `PayloadTooLarge` | 413 `payload_too_large` |
|
||
| `UnsupportedMediaType` | 415 `unsupported_media_type` |
|
||
| `UploadInterrupted` | 400 `invalid_request` |
|
||
| `AttachmentContentMissing` | 500 `internal_error`, «Internal server error» |
|
||
|
||
Тексты — на английском, без внутренних деталей.
|
||
- Константы в `src/utils/constants.py`:
|
||
- лимиты: `ATTACHMENT_MAX_BYTES` 10 485 760, `ATTACHMENT_MAX_PIXELS`
|
||
40 000 000, длины `filename`, `MESSAGE_ATTACHMENTS_MAX` 10;
|
||
- ключ объекта: префикс `attachments`, суффикс `original`;
|
||
- запрещённые символы `filename`: `/`, `\` и категория Cc.
|
||
- Enum `AttachmentStatus` (`pending`, `ready`) и `ImageType`
|
||
(`image/png`, `image/jpeg`) — `src/schemas/enums/attachment.py`. DTO
|
||
`AttachmentFullDTO`, `AttachmentContentDTO` — `src/schemas/dataclasses/
|
||
attachment.py`.
|
||
- `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` skeleton — эти константы, не
|
||
настройки (дельта `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`).
|
||
- `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 с) плюс запас.
|
||
- Сверка покрытия: `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:
|
||
1. синтетические Алиса, Боб, Ева, чат;
|
||
2. загрузка `tests/fixtures/sample.png`, реплика A;
|
||
3. сообщение со ссылкой;
|
||
4. `scripts/stop-one.sh` с `TARGET_INSTANCE_ID=A`;
|
||
5. Боб скачивает через LB: ответ от B ≠ A, SHA-256 совпадает;
|
||
6. Ева — 404;
|
||
7. в `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
|
||
|
||
1. Константы, enum, DTO, исключения, `src/utils/image.py`.
|
||
2. Модели и ревизия alembic: autogenerate, затем руками ограничение
|
||
`NOT VALID` и `lock_timeout`. Проверки — с нуля, повторно и под
|
||
записью прежней версии.
|
||
3. Repo, сервисы, зависимости, ошибки, схемы и ручки API.
|
||
4. Драйвер, тесты, hook стенда отказов, sync дельт, `make lint`,
|
||
прогоны.
|
||
5. `rollout_from`, регресс `bench/`.
|
||
6. Правила, AGENTS.md, скилл, `KNOWN_ISSUES.md`, `PLAN.md`.
|
||
7. Commit после подтверждения пользователя, затем evidence, затем
|
||
`REPORT.md` — каждый шаг отдельным commit с подтверждения.
|
||
|
||
На рабочем стенде новый код — `make rolling_update`: одна миграция,
|
||
затем замена по одной. Bootstrap S3 не меняется, переменных в `.env`
|
||
не добавляется.
|
||
|
||
Откат — `make rolling_update COMMIT=e1161f7 MIGRATE=0`. Схема остаётся:
|
||
прежний код таблиц вложений не знает, ослабленное ограничение ему не
|
||
мешает. Загруженные вложения остаются в БД и S3 и снова видны после
|
||
возврата вперёд.
|
||
|
||
## Уточнения apply
|
||
|
||
1. **`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 00` 10 MiB — 40 мс, пик `tracemalloc` ≤ 3,2 MiB; корпус
|
||
12 000 файлов: 11 964 приняты обоими, 34 отклонены обоими, 2 — только
|
||
по лимиту пикселей, ложных отказов 0. Вход IDAT подаётся кусками по
|
||
64 KiB: иначе `unconsumed_tail` копирует остаток большого чанка на
|
||
каждом блоке выхода.
|
||
2. **План истории** (задача 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`») пустая таблица стенда не показывает.
|
||
3. **Причины отказа загрузки в журнале** (решение 11): к списку
|
||
добавлена `content` — содержимое не PNG и не JPEG (`UnsupportedImage`),
|
||
отдельно от `damaged` (структура нарушена) и `content_mismatch`
|
||
(тип содержимого не совпал с `Content-Type`).
|
||
4. **`variant` в `/openapi.json`**: `Literal["original"]` pydantic пишет
|
||
как `const`; `Query(json_schema_extra={"enum": ["original"]})`
|
||
добавляет перечисление контракта.
|
||
5. **Тест «S3 завис»**: клиент `Api` набора со сроком 5 с обрывал
|
||
запрос раньше ответа API (503 через 5,0 с). Тест берёт клиента со
|
||
сроком 15 с — дефект теста, не приложения.
|
||
6. **Имя ограничения в ревизии**: `drop_constraint` без `op.f(...)`
|
||
применял шаблон имён и искал `ck_messages_ck_messages_text_length`
|
||
(видно в `upgrade --sql`); исправлено до применения.
|
||
7. **Тексты из пробелов с вложением** — ответ преподавателя 2026-10-20
|
||
пришёл во время apply (решение 8): валидатор сразу написан под 201;
|
||
«сначала красный» тест на прежнем валидаторе не показывался — прежней
|
||
версии с вложениями не было.
|
||
8. **`bench_restore_quick`** (задача 7.2) нестабилен из-за гонки стенда,
|
||
не кода вложений: `switch_api` пересоздаёт реплику с тем же IP, и
|
||
`wait_ready` видит устаревший `UP` слота (`KNOWN_ISSUES.md`).
|
||
|
||
## Open Questions
|
||
|
||
- ~~Текст из одних пробелов вместе с вложением~~ — закрыт 2026-10-20
|
||
ответом преподавателя: 201 с вложением, 400 без (решение 8).
|
||
- Что API отвечает, когда у строки `ready` нет объекта или он другого
|
||
размера: сейчас 500 и `error` в журнале (решение 7). Пометку таких
|
||
строк и ответ после неё решит reconciler трека 2. Спеки этого change
|
||
это не меняет.
|
||
- Срок PUT большого объекта под одновременной записью: отдельный срок по
|
||
размеру или общий `[s3] timeout_seconds`. Решит `upload-memory` по
|
||
замеру.
|