docs: propose attachments
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -603,3 +603,121 @@ design) и «Вопросы» (ждут ответа; ответ дописыв
|
||||
разрушающего решения (удалить строку, пометить вложение потерянным)
|
||||
без проверки, что bucket на месте. Это учитывают `upload-consistency`
|
||||
и reconciler трека 2.
|
||||
|
||||
### attachments
|
||||
|
||||
#### Решения
|
||||
|
||||
Приняты 2026-10-20 в `/opsx:propose`, подробности — design change
|
||||
`attachments`.
|
||||
|
||||
1. **Строка `pending` до PUT — уже здесь** (решение 1). Порядок:
|
||||
проверки → `pending` с ключом объекта (commit) → PUT → `ready`
|
||||
(commit) → 201. При отказе S3 или БД после шага `pending` — 503,
|
||||
строка остаётся. `upload-consistency` добавит компенсацию, уборщик и
|
||||
тесты отказов посреди загрузки, порядок шагов не меняя.
|
||||
2. **Проверка изображения — структура без декодирования** (решение 2),
|
||||
своя функция на stdlib:
|
||||
- PNG: CRC чанков, поток IDAT распаковывается ровно в объём по
|
||||
размерам, типы фильтров строк;
|
||||
- JPEG: маркеры, один кадр, скан, EOI;
|
||||
- пиксели — из заголовка до распаковки.
|
||||
|
||||
Проба: 12 000 настоящих файлов без ложных отказов, память проверки
|
||||
до 3,5 MiB, «бомба» отсекается за доли миллисекунды. Pillow — только
|
||||
dev-группа, для JPEG в тестах. Поведение для клиента подтвердил
|
||||
пользователь («Вопросы», п. 1).
|
||||
3. **Схема** (решение 3):
|
||||
- таблицы `attachments` и `message_attachments` — порядок
|
||||
`position`, FK без каскада: вложение со ссылкой из сообщения БД
|
||||
удалить не даст;
|
||||
- ограничение текста сообщения ослаблено до 0–4000 с `NOT VALID`,
|
||||
без скана `messages` под эксклюзивной блокировкой (дельта
|
||||
`db-migrations`);
|
||||
- чат вложения = чат сообщения проверяет сервис в той же транзакции.
|
||||
|
||||
Отвергнуты массив id в `messages`, составной FK с третьим индексом
|
||||
на `messages` и тип `ENUM`.
|
||||
4. **Ключ объекта** — `<база>/attachments/<id>/original`, хранится в
|
||||
`object_key` (уникальный) (решение 4).
|
||||
5. **Загрузка и скачивание не держат сессию БД** (решение 5). Найдено:
|
||||
`get_db_session` держит соединение пула и срок 6 с до конца отправки
|
||||
ответа, и передача 10 MiB медленному клиенту оборвалась бы на 6-й
|
||||
секунде. Поэтому:
|
||||
- `db_session_scope()` на каждый шаг с БД;
|
||||
- вход `CurrentUserBrief` с короткой сессией;
|
||||
- `AttachmentService(db_scope, cache, storage)`.
|
||||
6. **Ответы до чтения тела** (решение 6, проба). Ранние 404, 413 и 415
|
||||
получают httpx, curl и любой клиент через LB. `urllib` напрямую к
|
||||
одной реплике ответ теряет — ограничение в `REPORT.md`. Медленные
|
||||
10 MiB через LB проходят: таймауты HAProxy — простой, а не длительность.
|
||||
7. **Порядок проверок загрузки**: 401 → 400 → 404 → 415 (`Content-Type`)
|
||||
→ 413 (`Content-Length`) → тело (спек «Порядок проверок загрузки»).
|
||||
8. **Скачивание** (решение 7):
|
||||
- поток из S3, отказ S3 — 503 до заголовков;
|
||||
- заголовок `X-Content-Type-Options: nosniff`;
|
||||
- `variant` кроме `original` — 400 по перечислению контракта лабы 4;
|
||||
- строка `ready` без объекта или с другим размером — 500 и `error`
|
||||
в журнале, строка не меняется.
|
||||
9. **Хэш идемпотентности** (решение 9): пустой `attachment_ids` хэш не
|
||||
меняет, id в нижнем регистре, порядок значим.
|
||||
10. **Лимиты 10 MiB и 40 млн пикселей — константы, не настройки**
|
||||
(дельта `service-configuration`), соответствие `MAX_UPLOAD_BYTES` и
|
||||
`MAX_IMAGE_PIXELS` — в `REPORT.md`.
|
||||
11. **`rollout_from = e1161f7`** — последний commit лабы 4 до этого
|
||||
change (решение 14). Проверка commit до стенда, правило — в
|
||||
`bench.md`, запись в `KNOWN_ISSUES.md` удаляется в apply.
|
||||
12. **Дельты синхронизируются в основные спеки в apply**, как `health`
|
||||
в `s3-storage`: сверка покрытия читает только `openspec/specs/`.
|
||||
13. **Проверки отказов вложений** — через hook стенда отказов: счётчики
|
||||
вложений по статусам и объектов в bucket (решение 12).
|
||||
|
||||
#### Вопросы
|
||||
|
||||
1. Что считать «повреждённым изображением» (решение 2, спек
|
||||
`attachments`, «Повреждённое изображение»)? По умолчанию —
|
||||
структурная проверка без декодирования пикселей:
|
||||
- 415 — обрезанный файл, битая CRC, сломанные маркеры, поток zlib не
|
||||
того объёма, «бомба»;
|
||||
- байты после IEND или EOI принимаются как часть оригинала;
|
||||
- изменённый байт внутри данных скана JPEG не ловится. У формата нет
|
||||
контрольной суммы, Pillow его тоже не ловит.
|
||||
|
||||
Альтернатива — полное декодирование Pillow. Оно стоит до 160 МБ на
|
||||
загрузку при лимите реплики 512 МБ, требует семафора уже в этом
|
||||
change и ловит не больше.
|
||||
|
||||
**Ответ пользователя 2026-10-20:** структурная проверка, как по
|
||||
умолчанию. Менять ничего не нужно.
|
||||
2. Текст из одних пробелов вместе с вложением. По умолчанию — 400: общее
|
||||
правило контракта «обязательные строки не состоят только из
|
||||
пробельных символов», а исключение названо только для `text=""`.
|
||||
Фраза «нельзя пустой/пробельный текст без вложений» допускает и
|
||||
прочтение «с вложением можно». Это две трактовки контракта, то есть
|
||||
вопрос преподавателю (AGENTS.md).
|
||||
|
||||
**Ответ пользователя 2026-10-20:** пока 400, как по умолчанию. Это
|
||||
неоднозначность контракта: `contracts/README.md`, строка 18 («нельзя
|
||||
… пробельный текст без вложений») против строк 9 (обязательные строки
|
||||
не из одних пробелов) и 50 (исключение — только `text=""` с
|
||||
вложением). Пользователь спросит преподавателя.
|
||||
|
||||
**Открыт — вопрос преподавателю.** Трактовка временная (design change
|
||||
`attachments`, решение 8). Ответ записать в AGENTS.md, «Согласования с
|
||||
преподавателем». Если он другой, поправить валидатор `CreateMessage`,
|
||||
сценарий `messages` «Пробелы с вложением» и его тест. До ответа
|
||||
трактовка названа в `REPORT.md` как открытый вопрос.
|
||||
3. Опасный `filename`. Контракт называет `/`, `\`, NUL и управляющие
|
||||
символы. По умолчанию 400 и на символы управления направлением
|
||||
текста (U+202A–U+202E, U+2066–U+2069) и разделители строк (U+2028,
|
||||
U+2029): ими подменяют видимое имя (например, U+202E перед
|
||||
`gnp.exe`). ZWJ и остальные форматирующие разрешены: на них держатся
|
||||
emoji и письменности. Оставить так?
|
||||
|
||||
**Ответ пользователя 2026-10-20:** нет, только то, что в контракте:
|
||||
400 на `/`, `\`, NUL и управляющие символы — категория Unicode Cc
|
||||
(U+0000–U+001F, U+007F–U+009F). Символы направления текста,
|
||||
разделители строк U+2028 и U+2029 и прочие символы категорий Cf, Zl и
|
||||
Zp принимаются и возвращаются без изменений. Спеки `attachments`,
|
||||
design (решения 3 и 10) и tasks приведены к этому, отвергнутый вариант
|
||||
с причиной — в design, решение 10.
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-20
|
||||
@@ -0,0 +1,774 @@
|
||||
# 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; текст пустой без вложений или из одних пробелов (непустой) —
|
||||
400 (спек `messages`, «Валидация текста»).
|
||||
|
||||
**Трактовка временная — до ответа преподавателя** (`PLAN.md`,
|
||||
`### attachments` → «Вопросы», п. 2). Текст из одних пробелов вместе с
|
||||
вложением даёт 400: общее правило контракта (`contracts/README.md`,
|
||||
строка 9) и исключение только для `text=""` (строка 50). Строка 18
|
||||
(«нельзя … пробельный текст без вложений») допускает и прочтение «с
|
||||
вложением можно». Ответ преподавателя пойдёт в AGENTS.md,
|
||||
«Согласования с преподавателем». Если он другой, меняются условие
|
||||
валидатора, сценарий `messages` «Пробелы с вложением» и его тест.
|
||||
Остальное решение от этого не зависит.
|
||||
- `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` напрямую,
|
||||
смешанные версии при замене;
|
||||
- открытый вопрос преподавателю: текст из одних пробелов с вложением —
|
||||
пока 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 и снова видны после
|
||||
возврата вперёд.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Текст из одних пробелов вместе с вложением: ответ преподавателя на
|
||||
неоднозначность контракта (решение 8, `PLAN.md`, «Вопросы», п. 2).
|
||||
Пользователь отложил вопрос сам: до ответа — 400. Другой ответ меняет
|
||||
один сценарий `messages`, условие валидатора и тест отдельной правкой.
|
||||
Порядок работ от него не зависит.
|
||||
- Что API отвечает, когда у строки `ready` нет объекта или он другого
|
||||
размера: сейчас 500 и `error` в журнале (решение 7). Пометку таких
|
||||
строк и ответ после неё решит reconciler трека 2. Спеки этого change
|
||||
это не меняет.
|
||||
- Срок PUT большого объекта под одновременной записью: отдельный срок по
|
||||
размеру или общий `[s3] timeout_seconds`. Решит `upload-memory` по
|
||||
замеру.
|
||||
@@ -0,0 +1,140 @@
|
||||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
Рубрика «3» лабы 4 почти целиком про вложения (`README.md`): метаданные
|
||||
в PostgreSQL, байты в приватном bucket, `201 ready` после сохранения,
|
||||
побайтный download только участникам, `attachment_ids` в сообщении,
|
||||
реальные PNG/JPEG с лимитами до чтения и распаковки, файл переживает
|
||||
остановку принявшей его реплики и рестарт стенда. Рубрика «4» требует
|
||||
негативных тестов: большой файл, повреждённое изображение, подмена MIME,
|
||||
чужое `attachment_id`, вложение другого чата, ни одной пользовательской
|
||||
ошибки в 500. Хранилище и клиент S3 готовы (change `s3-storage`), а
|
||||
домена вложений нет.
|
||||
|
||||
Без него красные публичные `make test`, `make test-persistence` и
|
||||
`make test-failover` (с `LAB=4` они загружают файл) и 32 теста `make
|
||||
student_test` (контракт лабы 4 требует `attachment_ids` в `Message`). Сверка
|
||||
покрытия красная, пока четыре файла исключений не сняты на стенде лабы 4.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Домен `attachment` во всех слоях и три ручки контракта:
|
||||
- `POST /api/v1/chats/{chat_id}/attachments?filename=…` — сырые байты
|
||||
PNG/JPEG, `201 Attachment` со `status=ready`;
|
||||
- `GET /api/v1/attachments/{id}` — метаданные;
|
||||
- `GET /api/v1/attachments/{id}/content` — оригинал потоком из S3, с
|
||||
истинным `Content-Type`, без redirect.
|
||||
- Проверки загрузки до чтения и распаковки:
|
||||
- `Content-Length` больше 10 MiB — 413 до чтения тела, без него —
|
||||
счётчик байтов при чтении;
|
||||
- тип — по сигнатуре содержимого, расхождение с `Content-Type` — 415;
|
||||
- число пикселей — из заголовка изображения до распаковки, больше
|
||||
40 млн — 413;
|
||||
- целостность — структурная проверка без декодирования пикселей.
|
||||
Память проверки не зависит от числа пикселей, «бомба» отсекается по
|
||||
заявленному размеру;
|
||||
- опасный `filename` — 400.
|
||||
- Порядок записи: проверка → строка `pending` с ключом объекта (commit)
|
||||
→ PUT в S3 → строка `ready` (commit) → 201. Объект, записанный API,
|
||||
известен БД до записи. Компенсация и уборщик зависших `pending` — change
|
||||
`upload-consistency`.
|
||||
- Ключ объекта назначает сервер: `<имя базы>/attachments/<id>/original`.
|
||||
`filename` только отображается и ни в ключ, ни в путь не попадает.
|
||||
- Загрузка и скачивание не держат соединение пула PostgreSQL на время
|
||||
передачи тела. Короткие транзакции открываются только на шаги с БД.
|
||||
- Сообщение принимает `attachment_ids` (0–10 уникальных). Каждое
|
||||
вложение должно быть готовым вложением этого чата, иначе 404.
|
||||
`text=""` допустим только с вложением. Сообщение, история и повтор по
|
||||
ключу отдают `attachment_ids` в исходном порядке.
|
||||
- Хэш тела для идемпотентности учитывает `attachment_ids`, пустой список
|
||||
его не меняет (`PLAN.md`, решение 6).
|
||||
- Миграция только расширяет схему: таблицы `attachments` и
|
||||
`message_attachments`, ограничение длины текста сообщения ослаблено
|
||||
до 0–4000.
|
||||
- Отказ S3 — 503 только на путях вложений. Метаданные, текстовые
|
||||
сообщения и `/health/ready` работают.
|
||||
- `student-tests/test_attachments.py`: рубрика «4» и все сценарии нового
|
||||
спека. Новые проверки отказов: S3 остановлен и заморожен при загрузке
|
||||
и скачивании.
|
||||
- Драйвер скилла `run-mtusi-messenger`: `upload`, `download` с SHA-256 и
|
||||
сценарий `attachment-failover` — остановить реплику, принявшую файл, и
|
||||
скачать его через другую. `flow` загружает и скачивает вложение.
|
||||
- Профиль `rollout` стенда `bench/` стартует с commit лабы 4 до этого
|
||||
change (`e1161f7`), а не с commit лабы 3 (`KNOWN_ISSUES.md`). Правило
|
||||
выбора commit — в `bench.md`. Evidence замены — со старого образа на
|
||||
схему с вложениями.
|
||||
- Evidence: `evidence/attachments/`; четыре файла исключений сверки
|
||||
переснимаются на стенде лабы 4; `evidence/tests/` — зелёные прогоны.
|
||||
|
||||
Не входит:
|
||||
- компенсация, уборщик и тесты отказов посреди загрузки —
|
||||
`upload-consistency`;
|
||||
- лимит одновременных загрузок, сроки чтения тела и профиль `uploads` —
|
||||
`upload-memory`;
|
||||
- reconciler — трек 2;
|
||||
- presigned upload, lab5 (202, превью).
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `attachments`: вложения-изображения — загрузка с лимитами до чтения и
|
||||
распаковки, тип по содержимому, целостность, `filename`, доступ
|
||||
только участникам, метаданные, побайтный download, где лежат байты и
|
||||
метаданные, порядок записи, отказ S3, доступность через любую реплику
|
||||
и после рестарта.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `api-conventions`: пары 413 — `payload_too_large` и 415 —
|
||||
`unsupported_media_type`; строгий UUID на входе и для
|
||||
`attachment_id` в пути и `attachment_ids` в теле.
|
||||
- `messages`: `attachment_ids` в отправке, ответе и истории; пустой
|
||||
текст с вложением; проверка вложений сообщения.
|
||||
- `idempotency`: тело включает `attachment_ids`. Отсутствующее поле
|
||||
равно `[]`, порядок значим, повтор отдаёт те же вложения.
|
||||
- `data-storage`: метаданные вложений и связи с сообщениями — в
|
||||
PostgreSQL, байты — не в БД; целостность связей в БД; вложения
|
||||
переживают рестарт.
|
||||
- `db-migrations`: ослабление ограничения — допустимое расширение
|
||||
схемы, без скана таблицы под эксклюзивной блокировкой.
|
||||
- `service-logging`: имя файла и байты вложений не пишутся в журнал.
|
||||
- `service-configuration`: лимиты вложений — константы контракта, а не
|
||||
настройки; соответствие `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` — в
|
||||
`REPORT.md`.
|
||||
- `student-tests`: сверка покрытия включает `attachments`; тесты рубрики
|
||||
«4» лабы 4; проверки отказов S3 на путях вложений.
|
||||
- `load-benchmark`: прежний commit профиля замены — commit текущей лабы,
|
||||
без него отказ до стенда.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код:
|
||||
- `src/api/routers/v1/attachment.py`, `src/api/schemas/attachment.py`;
|
||||
`message.py` в API, сервисе, repo и DTO; `dependencies.py` — сессия
|
||||
БД на шаг и вход без удержания сессии; `errors.py` — 413 и 415;
|
||||
- `src/core/services/attachment.py`, `src/core/repos/attachment.py`,
|
||||
`attachment_object.py` (ключ и объект в S3),
|
||||
`src/core/exceptions/attachment.py`;
|
||||
- `src/schemas/` — DTO и enum вложений; `src/utils/image.py` —
|
||||
структурная проверка PNG/JPEG (только stdlib);
|
||||
`src/utils/constants.py` — лимиты контракта;
|
||||
- модели `src/infra/db/models/attachment.py`, ревизия alembic.
|
||||
- Зависимости: `pillow` только в dev-группе — генерация JPEG в тестах. В
|
||||
образ и в приложение не входит.
|
||||
- Тесты: `student-tests/test_attachments.py`, `test_failures.py`,
|
||||
`api_client.py`, `contract.py`, `spec_coverage.py`, `fault_hook.py`.
|
||||
- Стенды:
|
||||
- `bench/run.py` (`rollout_from`);
|
||||
- регресс `make bench_quick` (запрос истории изменился) и быстрых
|
||||
профилей `failover`, `rollout`, `restore`.
|
||||
- Документы:
|
||||
- правила `api-contract.md`, `api-layer.md`, `service-layer.md`,
|
||||
`repo-layer.md`, `dto.md`, `migrations.md`, `logging.md`,
|
||||
`student-tests.md`, `bench.md`, `settings.md`;
|
||||
- `AGENTS.md` и скилл `run-mtusi-messenger`;
|
||||
- `REPORT.md` — вложения, порядок записи, ответы на вопросы защиты,
|
||||
соответствие `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS`;
|
||||
- `KNOWN_ISSUES.md` — запись о `rollout_from` закрывается;
|
||||
- `PLAN.md`.
|
||||
@@ -0,0 +1,88 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Соответствие статусов и кодов ошибок
|
||||
|
||||
Сервис SHALL использовать пары статус — `code`: 400 —
|
||||
`invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 —
|
||||
`conflict`, 413 — `payload_too_large`, 415 — `unsupported_media_type`,
|
||||
500 — `internal_error`, 503 — `unavailable`. Метод, не поддерживаемый
|
||||
путём, SHALL давать 405 с `code` `invalid_request`.
|
||||
|
||||
#### Scenario: Неизвестный путь
|
||||
|
||||
- **WHEN** клиент запрашивает `GET /api/v1/unknown`
|
||||
- **THEN** ответ 404 с `code` `not_found` в формате ошибки
|
||||
|
||||
#### Scenario: Неподдерживаемый метод
|
||||
|
||||
- **WHEN** клиент выполняет `DELETE /api/v1/users`
|
||||
- **THEN** ответ 405 с `code` `invalid_request` в формате ошибки
|
||||
|
||||
#### Scenario: Лимит и тип вложения
|
||||
|
||||
- **WHEN** участник загружает вложение больше 10 MiB, а затем текст с
|
||||
`Content-Type: image/png`
|
||||
- **THEN** ответы 413 с `code` `payload_too_large` и 415 с `code`
|
||||
`unsupported_media_type` в формате ошибки
|
||||
|
||||
### Requirement: UUID на входе
|
||||
|
||||
Идентификатор, который передаёт клиент, SHALL приниматься только как
|
||||
строка UUID в записи 8-4-4-4-12 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`),
|
||||
как `format: uuid` контракта. Это `chat_id` и с лабы 4
|
||||
`attachment_id` в пути, элементы `member_ids` и с лабы 4 элементы
|
||||
`attachment_ids` в теле. Шестнадцатеричные цифры SHALL приниматься в
|
||||
любом регистре: UUID в верхнем регистре обозначает тот же
|
||||
идентификатор, что в нижнем. В ответах идентификаторы остаются в нижнем
|
||||
регистре (требование «Представление времени и идентификаторов»).
|
||||
|
||||
Значение другого типа (массив, объект, число, логическое значение, null)
|
||||
и строка в другой записи (без дефисов, с префиксом `urn:uuid:`, в
|
||||
фигурных скобках, с пробелами) SHALL давать 400 `invalid_request`, а не
|
||||
500 и не успешный ответ. Такой запрос MUST NOT создавать объектов.
|
||||
|
||||
#### Scenario: UUID другого типа в теле
|
||||
|
||||
- **WHEN** Алиса создаёт чат, где `member_ids` содержит её id и ещё один
|
||||
элемент — `[]`, `{}`, `123` или `false`
|
||||
- **THEN** ответ 400 с `code` `invalid_request`, чат не появился в
|
||||
списке чатов Алисы
|
||||
|
||||
#### Scenario: Не UUID в пути
|
||||
|
||||
- **WHEN** пользователь с действующей сессией запрашивает чат, историю
|
||||
чата или отправляет сообщение с верным `Idempotency-Key`, а `chat_id`
|
||||
в пути равен `123`, `false`, `[]` или `{}`
|
||||
- **THEN** ответ 400 с `code` `invalid_request`
|
||||
|
||||
#### Scenario: Другая запись UUID
|
||||
|
||||
- **WHEN** участник передаёт id своего чата в пути или Алиса передаёт id
|
||||
Боба в `member_ids`, записанный без дефисов, с префиксом `urn:uuid:`
|
||||
или в фигурных скобках
|
||||
- **THEN** ответ 400 с `code` `invalid_request`; ни чата, ни сообщения
|
||||
не создано
|
||||
|
||||
#### Scenario: UUID в верхнем регистре в пути
|
||||
|
||||
- **WHEN** участник запрашивает свой чат, его историю и отправляет в
|
||||
него сообщение, записав `chat_id` в верхнем регистре
|
||||
- **THEN** ответы те же, что для `chat_id` в нижнем регистре, а
|
||||
`id` и `chat_id` в них — в нижнем регистре
|
||||
|
||||
#### Scenario: Идентификаторы вложений в другой записи
|
||||
|
||||
- **WHEN** участник запрашивает метаданные и байты вложения, записав
|
||||
`attachment_id` без дефисов, с префиксом `urn:uuid:` или в фигурных
|
||||
скобках, и отправляет сообщение с таким элементом в `attachment_ids`
|
||||
- **THEN** каждый ответ 400 с `code` `invalid_request`, сообщение не
|
||||
создано
|
||||
|
||||
#### Scenario: Идентификаторы вложений в верхнем регистре
|
||||
|
||||
- **WHEN** участник запрашивает метаданные и байты вложения и
|
||||
отправляет сообщение с ним, записав id вложения в верхнем регистре
|
||||
- **THEN** ответы те же, что для id в нижнем регистре, а `id` и
|
||||
`attachment_ids` в них — в нижнем регистре
|
||||
@@ -0,0 +1,456 @@
|
||||
# Spec Delta
|
||||
|
||||
## Purpose
|
||||
|
||||
Вложения-изображения в чатах с лабы 4. Здесь описано:
|
||||
- загрузка PNG и JPEG с лимитами до чтения и распаковки;
|
||||
- проверка типа и целостности по содержимому, правила `filename`;
|
||||
- доступ только участникам чата, метаданные и побайтный download;
|
||||
- где лежат метаданные и байты, порядок записи и отказ S3;
|
||||
- доступность файла через любую реплику и после рестарта стенда.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Загрузка вложения
|
||||
|
||||
`POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` SHALL
|
||||
принимать тело — сырые байты одного изображения PNG или JPEG, не
|
||||
multipart и не JSON, с `Content-Type: image/png` или `image/jpeg`. При
|
||||
успехе ответ SHALL быть 201 с объектом `Attachment` без других полей:
|
||||
- `id` — новый UUID, его назначает сервер;
|
||||
- `chat_id` — чат из пути, `owner_id` — текущий пользователь;
|
||||
- `filename` — переданное имя без изменений;
|
||||
- `content_type` — тип, определённый по содержимому;
|
||||
- `size_bytes` и `sha256` (64 шестнадцатеричных символа в нижнем
|
||||
регистре) — размер и SHA-256 принятых байтов;
|
||||
- `status` — `ready`, `variants` — `[]`, `error_code` — null;
|
||||
- `created_at` и `updated_at` — время сервера в RFC 3339 UTC.
|
||||
|
||||
Ответ 201 SHALL означать, что сохранены и оригинал, и метаданные
|
||||
(требование «Порядок записи»). Загрузку может выполнить любой участник
|
||||
чата.
|
||||
|
||||
#### Scenario: Загрузка PNG
|
||||
|
||||
- **WHEN** Алиса загружает в свой чат публичный fixture
|
||||
`tests/fixtures/sample.png` с `Content-Type: image/png` и
|
||||
`filename=sample.png`
|
||||
- **THEN** ответ 201, `status` `ready`, `variants` `[]`, `error_code`
|
||||
null, `owner_id` — Алиса, `chat_id` — этот чат, `filename`
|
||||
`sample.png`, `content_type` `image/png`, `size_bytes` 111817, а
|
||||
`sha256` равен SHA-256 файла
|
||||
|
||||
#### Scenario: Загрузка JPEG
|
||||
|
||||
- **WHEN** Боб загружает в общий с Алисой чат настоящий JPEG с
|
||||
`Content-Type: image/jpeg`
|
||||
- **THEN** ответ 201, `content_type` `image/jpeg`, `owner_id` — Боб, а
|
||||
`size_bytes` и `sha256` совпадают с размером и SHA-256 файла
|
||||
|
||||
#### Scenario: Разновидности PNG и JPEG
|
||||
|
||||
- **WHEN** участник загружает PNG с палитрой, с альфа-каналом, в
|
||||
оттенках серого с альфа-каналом, 16 и 1 бит на канал, чересстрочный
|
||||
(Adam7), а также JPEG прогрессивный, в оттенках серого, CMYK и с EXIF
|
||||
- **THEN** каждый ответ 201 с `content_type` по формату файла
|
||||
|
||||
### Requirement: Лимит размера до чтения тела
|
||||
|
||||
Тело больше 10 485 760 байт (10 MiB) SHALL отклоняться ответом 413
|
||||
`payload_too_large`, а тело ровно 10 485 760 байт проверку размера
|
||||
SHALL проходить. Если `Content-Length` запроса больше лимита, ответ
|
||||
SHALL отдаваться без чтения тела. Без `Content-Length` (передача
|
||||
частями) тело SHALL читаться потоком со счётчиком. Ответ 413 SHALL
|
||||
отдаваться, как только прочитано больше лимита, остаток тела MUST NOT
|
||||
читаться. На одну загрузку процесс API MUST NOT держать в памяти больше
|
||||
лимита и одного блока чтения тела.
|
||||
|
||||
#### Scenario: Граница размера
|
||||
|
||||
- **WHEN** участник загружает настоящий PNG размером ровно 10 485 760
|
||||
байт, а затем такой же PNG на один байт длиннее
|
||||
- **THEN** первый ответ 201, второй — 413 `payload_too_large`
|
||||
|
||||
#### Scenario: Заявленный размер больше лимита
|
||||
|
||||
- **WHEN** участник загружает 30 MiB с `Content-Length` 31 457 280
|
||||
- **THEN** ответ 413 `payload_too_large` в формате ошибки, а клиент
|
||||
получает его, не дожидаясь отправки всего тела
|
||||
|
||||
#### Scenario: Большое тело без Content-Length
|
||||
|
||||
- **WHEN** участник передаёт 30 MiB частями, без `Content-Length`
|
||||
- **THEN** ответ 413 `payload_too_large` в формате ошибки
|
||||
|
||||
### Requirement: Лимит пикселей до распаковки
|
||||
|
||||
Ширину и высоту изображения сервис SHALL брать из заголовка до
|
||||
распаковки данных: у PNG — из IHDR, у JPEG — из маркера кадра. Больше
|
||||
40 000 000 пикселей — ответ 413 `payload_too_large`, ровно 40 000 000
|
||||
проверку SHALL проходить. Проверка MUST NOT декодировать изображение в
|
||||
память процесса API: распакованные данные PNG SHALL проверяться
|
||||
потоком, их объём MUST NOT превышать следующего из размеров
|
||||
изображения, и память проверки не зависит от числа пикселей. Данные
|
||||
длиннее заявленных размеров — повреждённое изображение (требование
|
||||
«Повреждённое изображение»).
|
||||
|
||||
#### Scenario: Огромные размеры в маленьком файле
|
||||
|
||||
- **WHEN** участник загружает PNG и JPEG по несколько килобайт, в
|
||||
заголовке которых 40 000 001 пиксель и больше
|
||||
- **THEN** каждый ответ 413 `payload_too_large`
|
||||
|
||||
#### Scenario: Ровно 40 млн пикселей
|
||||
|
||||
- **WHEN** участник загружает настоящий PNG 8000 × 5000 пикселей
|
||||
- **THEN** ответ 201
|
||||
|
||||
#### Scenario: Данные длиннее размеров
|
||||
|
||||
- **WHEN** участник загружает PNG 100 × 100, данные изображения
|
||||
которого распаковываются в сотни мегабайт
|
||||
- **THEN** ответ 415 `unsupported_media_type`, а сервис не
|
||||
распаковывает данные дальше заявленного размера изображения
|
||||
|
||||
### Requirement: Тип по содержимому
|
||||
|
||||
Тип вложения SHALL определяться по первым байтам содержимого: сигнатура
|
||||
PNG — `image/png`, маркер начала JPEG — `image/jpeg`. Ответ SHALL быть
|
||||
415 `unsupported_media_type`, если:
|
||||
- `Content-Type` запроса нет или его тип не `image/png` и не
|
||||
`image/jpeg`; параметры типа и регистр букв не учитываются;
|
||||
- содержимое не PNG и не JPEG, в том числе пустое тело;
|
||||
- тип содержимого не совпадает с `Content-Type` запроса (подмена MIME).
|
||||
|
||||
#### Scenario: Не изображение
|
||||
|
||||
- **WHEN** участник загружает текст, тело GIF и пустое тело с
|
||||
`Content-Type: image/png`
|
||||
- **THEN** каждый ответ 415 `unsupported_media_type`
|
||||
|
||||
#### Scenario: Подмена MIME
|
||||
|
||||
- **WHEN** участник загружает настоящий JPEG с `Content-Type: image/png`
|
||||
и настоящий PNG с `Content-Type: image/jpeg`
|
||||
- **THEN** оба ответа 415 `unsupported_media_type`
|
||||
|
||||
#### Scenario: Неподходящий Content-Type
|
||||
|
||||
- **WHEN** участник загружает настоящий PNG с `Content-Type`
|
||||
`application/octet-stream`, `text/plain` и без `Content-Type`, а затем
|
||||
с `Content-Type: IMAGE/PNG; charset=binary`
|
||||
- **THEN** первые три ответа 415, последний — 201
|
||||
|
||||
### Requirement: Повреждённое изображение
|
||||
|
||||
Сервис SHALL проверять целостность структуры изображения без
|
||||
декодирования пикселей и отвечать 415 `unsupported_media_type` на
|
||||
заведомо повреждённое.
|
||||
- PNG:
|
||||
- первым идёт IHDR с допустимыми полями;
|
||||
- каждый чанк целиком в файле, и его CRC верна;
|
||||
- неизвестных критичных чанков нет;
|
||||
- данные изображения (IDAT) идут подряд, их поток zlib завершён и
|
||||
распаковывается ровно в объём, который следует из размеров, глубины
|
||||
цвета и чересстрочности;
|
||||
- тип фильтра каждой строки допустим;
|
||||
- IEND есть.
|
||||
- JPEG:
|
||||
- маркеры и длины сегментов разбираются до конца;
|
||||
- кадр (SOF) один и с ненулевыми размерами;
|
||||
- есть хотя бы один скан;
|
||||
- есть маркер конца EOI.
|
||||
|
||||
Байты после IEND или EOI повреждением не считаются: они входят в
|
||||
оригинал, в его размер и SHA-256. Искажения внутри сжатых данных
|
||||
скана JPEG, которые не нарушают структуру, сервис не обнаруживает: у
|
||||
формата нет контрольной суммы.
|
||||
|
||||
#### Scenario: Обрезанный файл
|
||||
|
||||
- **WHEN** участник загружает PNG и JPEG, обрезанные наполовину и без
|
||||
последних байтов
|
||||
- **THEN** каждый ответ 415 `unsupported_media_type`
|
||||
|
||||
#### Scenario: Испорченные данные PNG
|
||||
|
||||
- **WHEN** участник загружает `sample.png` с одним изменённым байтом
|
||||
внутри IDAT и сигнатуру PNG, за которой случайные байты
|
||||
- **THEN** оба ответа 415 `unsupported_media_type`
|
||||
|
||||
#### Scenario: Хвост после конца изображения
|
||||
|
||||
- **WHEN** участник загружает PNG и JPEG, к которым дописаны байты
|
||||
после IEND и EOI
|
||||
- **THEN** оба ответа 201, `size_bytes` и `sha256` учитывают дописанные
|
||||
байты, а скачанный оригинал содержит их
|
||||
|
||||
### Requirement: Имя файла
|
||||
|
||||
`filename` SHALL содержать от 1 до 255 Unicode code points. Ответ SHALL
|
||||
быть 400 `invalid_request`, если параметра нет, имя пустое, длиннее
|
||||
255 code points, состоит из одних пробельных символов или содержит:
|
||||
- `/` или `\`;
|
||||
- управляющий символ — категория Unicode Cc: U+0000–U+001F, в том числе
|
||||
NUL, или U+007F–U+009F.
|
||||
|
||||
Отказ ограничен этим списком контракта (`contracts/README.md`). Прочие
|
||||
символы SHALL приниматься, в том числе:
|
||||
- символы форматирования и управления направлением текста (категория
|
||||
Cf, например U+202E и U+2066);
|
||||
- разделители строк и абзацев U+2028 и U+2029.
|
||||
|
||||
Принятое имя SHALL храниться и возвращаться без изменений, без обрезки
|
||||
и нормализации. Имя только отображается: оно MUST NOT участвовать в
|
||||
ключе объекта и в пути на диске. Как безопасно показать имя, решает
|
||||
клиент.
|
||||
|
||||
#### Scenario: Опасное имя
|
||||
|
||||
- **WHEN** участник загружает настоящий PNG с `filename`
|
||||
`../x.png`, `a/b.png`, `a\b.png`, с NUL, с переводом строки, с DEL, с
|
||||
управляющим символом C1 U+0085, пустым, из одних пробелов и из 256
|
||||
code points
|
||||
- **THEN** каждый ответ 400 `invalid_request`
|
||||
|
||||
#### Scenario: Имя в Unicode
|
||||
|
||||
- **WHEN** участник загружает файл с `filename` из 255 code points:
|
||||
кириллица, emoji с ZWJ и пробелы по краям
|
||||
- **THEN** ответ 201, а `filename` в ответе загрузки и в метаданных
|
||||
совпадает с переданным
|
||||
|
||||
#### Scenario: Символы форматирования в имени
|
||||
|
||||
- **WHEN** участник загружает файлы, в `filename` которых есть U+202E,
|
||||
U+2066 с U+2069, U+2028 и мягкий перенос U+00AD
|
||||
- **THEN** каждый ответ 201, а `filename` в ответе загрузки и в
|
||||
метаданных совпадает с переданным
|
||||
|
||||
### Requirement: Порядок проверок загрузки
|
||||
|
||||
Если у загрузки несколько ошибок, ответ SHALL определяться первой из
|
||||
них по порядку:
|
||||
1. 401 — нет действительной сессии;
|
||||
2. 400 — неверный `chat_id` или `filename`;
|
||||
3. 404 — чата нет или пользователь в нём не состоит;
|
||||
4. 415 — `Content-Type` запроса;
|
||||
5. 413 — `Content-Length` запроса;
|
||||
6. 413 — число прочитанных байтов;
|
||||
7. 415 или 413 — содержимое: формат и целостность или число пикселей.
|
||||
|
||||
Тело MUST NOT читаться, пока не пройдены проверки 1–5. Ошибка клиента
|
||||
MUST NOT давать 500.
|
||||
|
||||
#### Scenario: Посторонний с большим файлом
|
||||
|
||||
- **WHEN** Ева загружает 30 MiB в чат Алисы и Боба
|
||||
- **THEN** ответ 404 `not_found`, а не 413
|
||||
|
||||
#### Scenario: Без сессии с опасным именем
|
||||
|
||||
- **WHEN** загрузка без `Authorization` идёт с `filename` `a/b.png`, а
|
||||
затем с допустимым именем
|
||||
- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer`
|
||||
|
||||
#### Scenario: Неверный тип и большой размер
|
||||
|
||||
- **WHEN** участник загружает 30 MiB с `Content-Type: text/plain`
|
||||
- **THEN** ответ 415 `unsupported_media_type`
|
||||
|
||||
### Requirement: Доступ к вложению
|
||||
|
||||
Метаданные и байты вложения SHALL быть доступны любому участнику чата
|
||||
вложения, а не только владельцу. Посторонний, неизвестный `id` и
|
||||
вложение, загрузка которого не завершена, SHALL получать одинаковый 404
|
||||
`not_found`. Запрос без действительной сессии — 401, `attachment_id` не
|
||||
UUID — 400 `invalid_request`.
|
||||
|
||||
#### Scenario: Другой участник
|
||||
|
||||
- **WHEN** Алиса загрузила вложение в чат с Бобом, и Боб запрашивает
|
||||
его метаданные и байты
|
||||
- **THEN** оба ответа 200
|
||||
|
||||
#### Scenario: Посторонний и неизвестный id
|
||||
|
||||
- **WHEN** Ева запрашивает метаданные и байты вложения чата Алисы и
|
||||
Боба, а Алиса — по случайному UUID
|
||||
- **THEN** все ответы 404 `not_found` с одинаковым `message`
|
||||
|
||||
#### Scenario: Неверный id вложения
|
||||
|
||||
- **WHEN** участник запрашивает метаданные и байты по `attachment_id`
|
||||
`123` и `abc`
|
||||
- **THEN** каждый ответ 400 `invalid_request`
|
||||
|
||||
#### Scenario: Чтение без сессии
|
||||
|
||||
- **WHEN** метаданные и байты вложения запрашиваются без
|
||||
`Authorization`
|
||||
- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer`
|
||||
|
||||
### Requirement: Метаданные вложения
|
||||
|
||||
`GET /api/v1/attachments/{attachment_id}` SHALL отвечать 200 с
|
||||
объектом `Attachment`, равным ответу на загрузку этого вложения.
|
||||
|
||||
#### Scenario: Метаданные равны ответу загрузки
|
||||
|
||||
- **WHEN** Алиса загрузила вложение, а Боб запрашивает его метаданные
|
||||
- **THEN** ответ 200, JSON совпадает с ответом на загрузку во всех
|
||||
полях
|
||||
|
||||
### Requirement: Скачивание оригинала
|
||||
|
||||
`GET /api/v1/attachments/{attachment_id}/content` SHALL отвечать 200 с
|
||||
байтами оригинала без изменений: их размер и SHA-256 равны `size_bytes`
|
||||
и `sha256` вложения. Заголовки ответа:
|
||||
- `Content-Type` — `content_type` вложения без параметров;
|
||||
- `Content-Length` — размер оригинала;
|
||||
- `X-Content-Type-Options: nosniff`.
|
||||
|
||||
Байты SHALL отдавать API, ответ MUST NOT быть перенаправлением.
|
||||
Параметр `variant` SHALL принимать только `original`, это и значение по
|
||||
умолчанию. Любое другое значение — 400 `invalid_request`. Ключ объекта,
|
||||
адрес и учётные данные S3 MUST NOT попадать ни в тело, ни в заголовки
|
||||
ответов API.
|
||||
|
||||
#### Scenario: Побайтный оригинал
|
||||
|
||||
- **WHEN** Боб скачивает PNG и JPEG, загруженные Алисой
|
||||
- **THEN** каждый ответ 200, не перенаправление, байты совпадают с
|
||||
загруженными, `Content-Type` — `image/png` и `image/jpeg`,
|
||||
`Content-Length` равен размеру, есть `X-Content-Type-Options: nosniff`
|
||||
|
||||
#### Scenario: Вариант original
|
||||
|
||||
- **WHEN** участник скачивает вложение с `variant=original`, а затем с
|
||||
`variant=thumbnail` и с пустым `variant`
|
||||
- **THEN** первый ответ 200 с теми же байтами, остальные — 400
|
||||
`invalid_request`
|
||||
|
||||
#### Scenario: Без следов хранилища в ответе
|
||||
|
||||
- **WHEN** участник загружает вложение, читает метаданные и скачивает
|
||||
байты
|
||||
- **THEN** в телах ответов нет полей вне схемы контракта, а в
|
||||
заголовках нет `Location` и заголовков `x-amz-*`
|
||||
|
||||
### Requirement: Где хранятся вложения
|
||||
|
||||
Метаданные вложения SHALL храниться в PostgreSQL, байты оригинала —
|
||||
одним объектом в приватном bucket S3 (`object-storage`). Байты MUST
|
||||
NOT храниться ни в PostgreSQL, ни в файлах реплики API. Ключ объекта
|
||||
назначает сервер: имя базы, `/attachments/`, `id` вложения и
|
||||
`/original`. Каждая загрузка SHALL создавать новое вложение и новый
|
||||
объект, в том числе повтор той же загрузки: прозрачных повторов
|
||||
загрузки нет (`contracts/README.md`).
|
||||
|
||||
#### Scenario: Байты не в БД и не на диске API
|
||||
|
||||
- **WHEN** после загрузок через балансировщик проверяющий смотрит
|
||||
схему таблиц вложений, ключи объектов в PostgreSQL, объекты в bucket
|
||||
и изменения файловой системы контейнеров реплик API
|
||||
- **THEN** в таблицах нет колонки с байтами изображения, ключ каждого
|
||||
объекта имеет вид `<база>/attachments/<id>/original` и не содержит
|
||||
`filename`, объект с этим ключом есть в bucket, анонимный GET его
|
||||
ключа — 403, а в контейнерах реплик нет файлов оригиналов
|
||||
|
||||
#### Scenario: Повторная загрузка
|
||||
|
||||
- **WHEN** участник дважды загружает один и тот же файл
|
||||
- **THEN** оба ответа 201 с разными `id` и одинаковым `sha256`, и оба
|
||||
вложения скачиваются
|
||||
|
||||
### Requirement: Порядок записи
|
||||
|
||||
Загрузка SHALL выполняться по шагам:
|
||||
1. проверки и чтение тела;
|
||||
2. запись метаданных в статусе «загружается» (`pending`) вместе с
|
||||
ключом объекта, фиксация в PostgreSQL;
|
||||
3. запись объекта в S3;
|
||||
4. статус `ready`, фиксация;
|
||||
5. ответ 201.
|
||||
|
||||
Объект, который записал API, SHALL быть известен PostgreSQL до записи в
|
||||
S3. Вложение не в статусе `ready` MUST NOT быть видно через API: его
|
||||
метаданные и байты — 404, ссылка на него в сообщении — 404. Если не
|
||||
удались запись в S3 или фиксация `ready`, ответ SHALL быть 503
|
||||
`unavailable`, строка «загружается» остаётся. Её и объект убирает
|
||||
уборщик (change `upload-consistency`). Загрузка, отклонённая до шага 2
|
||||
(401, 400, 404, 413, 415), MUST NOT оставлять ни строки, ни объекта.
|
||||
|
||||
#### Scenario: Запись в S3 не удалась
|
||||
|
||||
- **WHEN** S3 остановлен, и участник загружает настоящий PNG
|
||||
- **THEN** ответ 503 `unavailable`, в PostgreSQL на одно вложение в
|
||||
статусе «загружается» больше, готовых — столько же
|
||||
- **AND** текстовое сообщение в тот же чат — 201, а после возврата S3
|
||||
та же загрузка — 201
|
||||
|
||||
#### Scenario: Отклонённая загрузка ничего не оставляет
|
||||
|
||||
- **WHEN** участник и посторонний отправляют загрузки, которые
|
||||
отклоняются с 404, 413 по `Content-Length`, 413 по счётчику, 413 по
|
||||
пикселям, 415 по типу и 415 по целостности
|
||||
- **THEN** число вложений в PostgreSQL в каждом статусе и число
|
||||
объектов вложений в bucket не изменились
|
||||
|
||||
### Requirement: Недоступность S3
|
||||
|
||||
Если S3 недоступен, не ответил за срок вызова или отказал
|
||||
(`object-storage`), загрузка и скачивание байтов SHALL отвечать 503
|
||||
`unavailable` в формате ошибки. Ответ SHALL приходить не позже срока
|
||||
вызова S3 с запасом, а не 500 и не зависанием. Без S3 SHALL работать:
|
||||
- метаданные вложения;
|
||||
- история чата с `attachment_ids`;
|
||||
- отправка сообщений, в том числе со ссылкой на готовое вложение;
|
||||
- `/health/ready`.
|
||||
|
||||
После возврата S3 загрузка и скачивание SHALL проходить без перезапуска
|
||||
API.
|
||||
|
||||
#### Scenario: S3 остановлен
|
||||
|
||||
- **WHEN** вложение загружено, затем S3 остановлен, и участник
|
||||
скачивает байты, читает метаданные, отправляет сообщение с этим
|
||||
вложением и запрашивает `/health/ready`
|
||||
- **THEN** скачивание — 503 `unavailable`, метаданные — 200, сообщение
|
||||
— 201, готовность — 200
|
||||
- **AND** после возврата S3 скачивание — 200 с теми же байтами
|
||||
|
||||
#### Scenario: S3 завис
|
||||
|
||||
- **WHEN** контейнер S3 заморожен (`docker pause`), и участник
|
||||
загружает файл и скачивает байты готового вложения
|
||||
- **THEN** оба ответа 503 `unavailable` не позже срока вызова S3 с
|
||||
запасом, а после разморозки скачивание — 200
|
||||
|
||||
### Requirement: Вложение доступно через любую реплику
|
||||
|
||||
Готовое вложение SHALL скачиваться через любую реплику API за
|
||||
балансировщиком, в том числе после остановки реплики, которая его
|
||||
приняла. Метаданные и оригинал SHALL переживать перезапуск стенда
|
||||
(`scripts/restart.sh`, вместе с S3) с сохранёнными volumes и читаться
|
||||
прежним токеном.
|
||||
|
||||
#### Scenario: Скачивание через другую реплику
|
||||
|
||||
- **WHEN** вложение загружено через балансировщик, ответ дала реплика
|
||||
с одним `X-Instance-Id`
|
||||
- **THEN** байты скачиваются через реплику с другим `X-Instance-Id` и
|
||||
совпадают с загруженными
|
||||
|
||||
#### Scenario: Принявшая реплика остановлена
|
||||
|
||||
- **WHEN** вложение загружено через балансировщик, затем реплика с
|
||||
`X-Instance-Id` ответа на загрузку остановлена `scripts/stop-one.sh`
|
||||
- **THEN** метаданные и байты через балансировщик — 200 от другой
|
||||
реплики, SHA-256 совпадает с загруженным, посторонний получает 404
|
||||
|
||||
#### Scenario: Рестарт стенда
|
||||
|
||||
- **WHEN** вложение загружено, затем выполнен `scripts/restart.sh`
|
||||
- **THEN** прежним токеном метаданные — 200, а байты совпадают с
|
||||
загруженными по SHA-256
|
||||
@@ -0,0 +1,71 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Хранение в PostgreSQL
|
||||
|
||||
Пользователи, чаты, участники чатов, сообщения, сессии, а с лабы 4 —
|
||||
метаданные вложений и связи сообщений с вложениями SHALL храниться в
|
||||
PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные
|
||||
в памяти процесса, файлах или SQLite. Байты вложений SHALL храниться в
|
||||
S3 (capability `attachments`, `object-storage`), а не в PostgreSQL и не
|
||||
в файлах реплик. Подтверждённая запись (ответ 201 или 204) SHALL быть
|
||||
зафиксирована до ответа и видна следующему запросу.
|
||||
|
||||
#### Scenario: Созданное видно сразу
|
||||
|
||||
- **WHEN** клиент зарегистрировался и следующим запросом входит с теми
|
||||
же username и паролем
|
||||
- **THEN** вход успешен, и `GET /api/v1/users/me` с выданным токеном
|
||||
возвращает этого пользователя
|
||||
|
||||
### Requirement: Данные переживают рестарт
|
||||
|
||||
После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее
|
||||
подтверждённые пользователи, чаты, участники и сообщения SHALL быть
|
||||
доступны в прежнем виде. С лабы 4 это относится и к вложениям: их
|
||||
метаданные, `attachment_ids` сообщений и оригиналы переживают и
|
||||
перезапуск S3 с его volume.
|
||||
|
||||
#### Scenario: Прежний пользователь после рестарта
|
||||
|
||||
- **WHEN** стенд перезапущен `scripts/restart.sh`, и клиент использует
|
||||
токен, полученный до рестарта
|
||||
- **THEN** ответ 200, а история чата этого пользователя содержит те же
|
||||
сообщения в том же порядке
|
||||
|
||||
### Requirement: Целостность данных в БД
|
||||
|
||||
Ограничения SHALL проверяться самой БД, а не только сервисом:
|
||||
- уникальность `username`;
|
||||
- существование пользователей и чатов, на которые ссылаются участники
|
||||
и сообщения;
|
||||
- уникальность участника в чате;
|
||||
- членство отправителя в чате сообщения.
|
||||
|
||||
С лабы 4 БД SHALL проверять и вложения:
|
||||
- владелец вложения — участник его чата;
|
||||
- связь сообщения с вложением ссылается на существующие сообщение и
|
||||
вложение;
|
||||
- вложение не повторяется в одном сообщении, у каждого места в порядке
|
||||
одно вложение, мест не больше 10;
|
||||
- вложение, на которое ссылается сообщение, удалить нельзя;
|
||||
- допустимые значения размера, SHA-256, типа, статуса и длины
|
||||
`filename`; ключ объекта уникален.
|
||||
|
||||
Порядок `member_ids`, заданный при создании чата, и порядок
|
||||
`attachment_ids` сообщения SHALL сохраняться. Принадлежность вложения
|
||||
чату сообщения проверяет сервис в той же транзакции: чат вложения и
|
||||
чат сообщения не меняются после записи.
|
||||
|
||||
#### Scenario: Порядок участников
|
||||
|
||||
- **WHEN** чат создан с `member_ids` в порядке `[bob, alice]`
|
||||
- **THEN** `GET` этого чата и список чатов возвращают `member_ids` в
|
||||
том же порядке, в том числе после рестарта стенда
|
||||
|
||||
#### Scenario: Порядок вложений
|
||||
|
||||
- **WHEN** сообщение отправлено с `attachment_ids` `[C, A, B]`
|
||||
- **THEN** ответ на отправку, история чата и повтор с тем же ключом
|
||||
возвращают `[C, A, B]`
|
||||
@@ -0,0 +1,68 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Совместимость миграции с работающей версией
|
||||
|
||||
Миграция SHALL только расширять схему:
|
||||
- новая таблица со своими ограничениями и внешними ключами;
|
||||
- новая колонка, допускающая NULL или со значением по умолчанию;
|
||||
- новый индекс;
|
||||
- ослабление ограничения: новое условие пропускает всё, что пропускало
|
||||
прежнее, поэтому прежняя версия не пишет значений, которые новое
|
||||
условие запретит.
|
||||
|
||||
Ослабленное ограничение SHALL добавляться без проверки существующих
|
||||
строк под эксклюзивной блокировкой таблицы: эти строки уже
|
||||
удовлетворяли более строгому условию.
|
||||
|
||||
Удаление и переименование таблицы, колонки или ограничения (кроме
|
||||
замены ограничения ослабленным), а также новое ограничение, которое
|
||||
нарушит запись прежней версии, MUST NOT входить в ту же поставку, что и
|
||||
код, которому они нужны. Такое изменение выполняется отдельной миграцией
|
||||
после того, как реплик прежней версии не осталось (expand/contract).
|
||||
Если так сделать нельзя, ограничение SHALL описываться в `REPORT.md`.
|
||||
|
||||
Реплики прежнего образа SHALL обслуживать обязательные запросы на
|
||||
схеме после новой миграции. Откат кода к прежнему образу MUST NOT
|
||||
требовать отката схемы.
|
||||
|
||||
Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком.
|
||||
Долгая транзакция приложения не должна заставить миграцию держать
|
||||
очередь за собой и остановить запись остальных реплик. Срок SHALL быть
|
||||
меньше срока запроса приложения к БД (`statement_timeout`): запросы,
|
||||
вставшие в очередь за миграцией, дожидаются её отказа и выполняются, а
|
||||
не завершаются ошибкой вместе с ним. По истечении срока миграция SHALL
|
||||
завершаться ошибкой без изменения схемы, а её повторный запуск SHALL
|
||||
проходить.
|
||||
|
||||
#### Scenario: Старый образ на новой схеме
|
||||
|
||||
- **WHEN** стенд работает на образе прежнего commit, и миграции нового
|
||||
образа применены, а реплики не заменены
|
||||
- **THEN** `make test` и `make student_test` через LB проходят на
|
||||
прежних репликах
|
||||
|
||||
#### Scenario: Запись прежней версии
|
||||
|
||||
- **WHEN** после новой миграции сообщение отправлено через реплику
|
||||
прежнего образа
|
||||
- **THEN** ответ 201, а сообщение видно в истории через реплику любого
|
||||
образа
|
||||
|
||||
#### Scenario: Блокировка не получена
|
||||
|
||||
- **WHEN** таблицу, которую меняет миграция, держит открытая
|
||||
транзакция дольше срока ожидания блокировки
|
||||
- **THEN** миграция завершается ошибкой, схема не меняется, запросы
|
||||
других клиентов, ждавшие за миграцией, получают успешный ответ, а
|
||||
после окончания транзакции повторный запуск применяет миграцию
|
||||
|
||||
#### Scenario: Ослабленное ограничение
|
||||
|
||||
- **WHEN** миграция вложений заменяет ограничение длины текста
|
||||
сообщения (было 1–4000, стало 0–4000) на таблице с сообщениями, а
|
||||
запись идёт через реплики прежнего образа
|
||||
- **THEN** миграция не проверяет существующие строки, записи прежних
|
||||
реплик во время и после неё — 201, а после замены реплик сообщение с
|
||||
пустым текстом и вложением — 201
|
||||
@@ -0,0 +1,67 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Повтор возвращает исходный результат
|
||||
|
||||
Повтор от того же пользователя в тот же чат с тем же ключом и тем же
|
||||
телом в пределах срока ключа SHALL возвращать 201 и тот же `Message`:
|
||||
тот же `id`, `text`, `attachment_ids` и `created_at` до микросекунды.
|
||||
Новое сообщение MUST NOT создаваться. Тела SHALL сравниваться по смыслу,
|
||||
после разбора JSON. На результат не влияют:
|
||||
- запись пробелов и экранирование символов;
|
||||
- порядок полей объекта;
|
||||
- отсутствующий `attachment_ids` вместо `[]`;
|
||||
- регистр букв в идентификаторах вложений.
|
||||
|
||||
Порядок элементов `attachment_ids` значим: это порядок вложений в
|
||||
сообщении. Ключ, сохранённый версией сервиса без вложений, SHALL
|
||||
повторяться тем же телом и после замены реплик на версию с вложениями.
|
||||
|
||||
#### Scenario: Повтор того же тела
|
||||
|
||||
- **WHEN** Алиса отправляет текст T с ключом K и повторяет тот же
|
||||
запрос
|
||||
- **THEN** оба ответа 201 с одинаковым JSON, а в истории чата одно
|
||||
сообщение с текстом T
|
||||
|
||||
#### Scenario: Тот же JSON в другой записи
|
||||
|
||||
- **WHEN** повтор с ключом K несёт то же тело в другой записи: с
|
||||
другими пробелами и с текстом в экранировании `\uXXXX`
|
||||
- **THEN** ответ 201 с тем же `Message`, новое сообщение не создано
|
||||
|
||||
#### Scenario: Вложения по умолчанию
|
||||
|
||||
- **WHEN** Алиса отправила `{"text": T}` с ключом K и повторяет с K
|
||||
тело `{"attachment_ids": [], "text": T}`
|
||||
- **THEN** ответ 201 с тем же `Message`, новое сообщение не создано
|
||||
|
||||
#### Scenario: Повтор сообщения с вложениями
|
||||
|
||||
- **WHEN** Алиса отправила текст с `attachment_ids` `[A, B]` и ключом K,
|
||||
затем повторяет с K то же тело, а потом то же тело с A и B в верхнем
|
||||
регистре
|
||||
- **THEN** оба ответа 201 с тем же `Message` и `attachment_ids`
|
||||
`[A, B]`, в истории одно такое сообщение
|
||||
|
||||
### Requirement: Другое тело с тем же ключом
|
||||
|
||||
Если ключ в своей области уже использован с другим телом и срок не
|
||||
истёк, сервис SHALL отвечать 409 `conflict`. Новое сообщение MUST NOT
|
||||
создаваться, сохранённый результат ключа MUST NOT меняться. Другие
|
||||
вложения или их другой порядок — другое тело.
|
||||
|
||||
#### Scenario: Другой текст
|
||||
|
||||
- **WHEN** Алиса отправила T1 с ключом K, затем отправляет T2 с тем же
|
||||
ключом в тот же чат
|
||||
- **THEN** второй ответ 409 `conflict`, в истории только T1, а повтор
|
||||
T1 с K по-прежнему возвращает исходный `Message`
|
||||
|
||||
#### Scenario: Другие вложения
|
||||
|
||||
- **WHEN** Алиса отправила текст с `attachment_ids` `[A, B]` и ключом
|
||||
K, затем шлёт с K тот же текст с `[B, A]`, а потом без вложений
|
||||
- **THEN** оба ответа 409 `conflict`, в истории одно сообщение с
|
||||
`[A, B]`
|
||||
@@ -0,0 +1,31 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Прежний commit профиля замены
|
||||
|
||||
Commit, с образа которого стартуют реплики профилей `rollout` и
|
||||
`rollout_quick`, SHALL задаваться методикой профиля. Это commit
|
||||
текущей лабы до изменения, которое показывает замена. Сейчас таким
|
||||
изменением SHALL быть миграция вложений: commit — последний перед
|
||||
change `attachments`. Commit SHALL меняться при переходе в следующую
|
||||
лабу (commit прошлой лабы в её истории нет) и когда замена показывает
|
||||
новое изменение схемы. Правило и текущее значение SHALL быть в
|
||||
`.claude/rules/bench.md`, commit — в паспорте метки.
|
||||
|
||||
Если commit методики нет в истории репозитория, команда SHALL
|
||||
завершаться с ненулевым кодом до запуска стенда, назвать commit и
|
||||
подмену `--from <commit>` для отладки.
|
||||
|
||||
#### Scenario: Замена на схему с вложениями
|
||||
|
||||
- **WHEN** выполнен `make bench_rollout_quick` на коде с вложениями
|
||||
- **THEN** реплики стартуют на образе commit до change `attachments`,
|
||||
ревизия схемы до замены — без таблиц вложений, после — с ними, а
|
||||
команда завершается с кодом 0
|
||||
|
||||
#### Scenario: Commit вне истории
|
||||
|
||||
- **WHEN** commit методики не найден в репозитории
|
||||
- **THEN** команда завершается с ненулевым кодом до запуска стенда, а
|
||||
сообщение называет commit и `--from`
|
||||
@@ -0,0 +1,146 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Отправка сообщения
|
||||
|
||||
`POST /api/v1/chats/{chat_id}/messages` SHALL принимать тело
|
||||
`{"text": ..., "attachment_ids": [...]}` с заголовком `Idempotency-Key`.
|
||||
`attachment_ids` необязателен, по умолчанию `[]`. При успехе ответ SHALL
|
||||
быть 201 с объектом `Message`: `id`, `chat_id`, `sender_id`, `text`,
|
||||
`created_at`, `attachment_ids`, без других полей.
|
||||
- `sender_id` SHALL быть текущим пользователем;
|
||||
- `text` SHALL совпадать с отправленным;
|
||||
- `attachment_ids` SHALL совпадать с отправленными, в том же порядке,
|
||||
без поля в запросе — `[]`.
|
||||
|
||||
Формат ключа, повтор и конфликт описаны в capability `idempotency`,
|
||||
проверка вложений — в требовании «Вложения в сообщении».
|
||||
|
||||
#### Scenario: Участник отправляет сообщение
|
||||
|
||||
- **WHEN** Алиса отправляет `"Привет, мир 👋"` в свой чат с новым
|
||||
`Idempotency-Key`
|
||||
- **THEN** ответ 201, `sender_id` — Алиса, `chat_id` — этот чат, `text`
|
||||
равен `"Привет, мир 👋"`, `attachment_ids` — `[]`
|
||||
|
||||
#### Scenario: Сообщение с вложениями
|
||||
|
||||
- **WHEN** Алиса загрузила в чат вложения A и B и отправляет текст с
|
||||
`attachment_ids` `[B, A]`
|
||||
- **THEN** ответ 201, `attachment_ids` — `[B, A]`
|
||||
|
||||
### Requirement: Валидация текста
|
||||
|
||||
`text` SHALL содержать не больше 4000 Unicode code points. Пустая строка
|
||||
SHALL допускаться только вместе с хотя бы одним вложением. Текст из
|
||||
одних пробельных символов MUST NOT приниматься ни с вложениями, ни без
|
||||
них. Поле `sender_id` в теле MUST NOT приниматься. Нарушения SHALL
|
||||
давать 400 `invalid_request`.
|
||||
|
||||
#### Scenario: Пустой текст
|
||||
|
||||
- **WHEN** участник отправляет `{"text": ""}`
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Граница длины
|
||||
|
||||
- **WHEN** текст из 4000 code points, затем из 4001
|
||||
- **THEN** первый запрос даёт 201, второй — 400
|
||||
|
||||
#### Scenario: Попытка подменить отправителя
|
||||
|
||||
- **WHEN** тело содержит `sender_id` другого пользователя
|
||||
- **THEN** ответ 400, сообщение не создаётся
|
||||
|
||||
#### Scenario: Пустой текст с вложением
|
||||
|
||||
- **WHEN** участник отправляет `{"text": "", "attachment_ids": [A]}` с
|
||||
готовым вложением A своего чата
|
||||
- **THEN** ответ 201, `text` — пустая строка, `attachment_ids` — `[A]`
|
||||
|
||||
#### Scenario: Пробелы с вложением
|
||||
|
||||
- **WHEN** участник отправляет `{"text": " ", "attachment_ids": [A]}`
|
||||
- **THEN** ответ 400 `invalid_request`, сообщение не создаётся
|
||||
|
||||
### Requirement: История чата
|
||||
|
||||
`GET /api/v1/chats/{chat_id}/messages` SHALL возвращать сообщения чата
|
||||
в порядке `(created_at, id)` по возрастанию, с постраничным выводом по
|
||||
capability `pagination`. Любой участник SHALL видеть все сообщения
|
||||
чата, в том числе чужие. Каждое сообщение SHALL содержать
|
||||
`attachment_ids` в порядке отправки.
|
||||
|
||||
#### Scenario: Два участника, две страницы
|
||||
|
||||
- **WHEN** Алиса и Боб отправили по сообщению, и Боб читает историю с
|
||||
`limit=1`, а затем продолжает по курсору
|
||||
- **THEN** первая страница содержит одно сообщение и непустой
|
||||
`next_cursor`, вторая — второе сообщение и `next_cursor` null, а
|
||||
порядок совпадает с `(created_at, id)`
|
||||
|
||||
#### Scenario: Вложения в истории
|
||||
|
||||
- **WHEN** Алиса отправила сообщение с `attachment_ids` `[B, A]`, а Боб
|
||||
— текстовое сообщение
|
||||
- **THEN** в истории у первого `attachment_ids` — `[B, A]`, у второго —
|
||||
`[]`
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Вложения в сообщении
|
||||
|
||||
`attachment_ids` SHALL содержать от 0 до 10 уникальных идентификаторов
|
||||
в записи UUID (`api-conventions`, «UUID на входе»). Повтор
|
||||
идентификатора, в том числе в другом регистре букв, больше 10
|
||||
элементов, элемент не UUID и не массив — 400 `invalid_request`.
|
||||
|
||||
Каждое вложение SHALL быть готовым вложением этого чата. Одинаковый 404
|
||||
`not_found` дают:
|
||||
- неизвестное вложение;
|
||||
- вложение другого чата, в том числе чата, где отправитель не состоит;
|
||||
- вложение, загрузка которого не завершена.
|
||||
|
||||
Сообщение при этом MUST NOT создаваться. Сервис SHALL принимать ссылку
|
||||
на вложение чата от любого его участника, а не только от владельца, и
|
||||
одно вложение SHALL входить в несколько сообщений. Сообщение и его
|
||||
связи с вложениями SHALL сохраняться одной транзакцией.
|
||||
|
||||
#### Scenario: Вложение другого участника
|
||||
|
||||
- **WHEN** Алиса загрузила вложение в чат с Бобом, и Боб отправляет
|
||||
сообщение с этим вложением
|
||||
- **THEN** ответ 201
|
||||
|
||||
#### Scenario: Вложение другого чата
|
||||
|
||||
- **WHEN** Алиса состоит в чатах X и Y, загрузила вложение в Y и
|
||||
отправляет в X сообщение с ним
|
||||
- **THEN** ответ 404 `not_found`, в истории X нового сообщения нет
|
||||
|
||||
#### Scenario: Чужое вложение
|
||||
|
||||
- **WHEN** Ева загрузила вложение в свой чат, а Алиса отправляет в свой
|
||||
чат сообщение с ним
|
||||
- **THEN** ответ 404 `not_found`, сообщение не создано
|
||||
|
||||
#### Scenario: Неизвестное вложение
|
||||
|
||||
- **WHEN** участник отправляет сообщение со случайным UUID в
|
||||
`attachment_ids`
|
||||
- **THEN** ответ 404 `not_found`, сообщение не создано
|
||||
|
||||
#### Scenario: Неверный список вложений
|
||||
|
||||
- **WHEN** участник отправляет `attachment_ids` с повтором одного
|
||||
вложения, с тем же вложением в верхнем регистре, из 11 элементов,
|
||||
строкой вместо массива и с элементом `123`
|
||||
- **THEN** каждый ответ 400 `invalid_request`, сообщений не создано
|
||||
|
||||
#### Scenario: Одно вложение в двух сообщениях
|
||||
|
||||
- **WHEN** участник дважды отправляет сообщение с одним и тем же
|
||||
вложением
|
||||
- **THEN** оба ответа 201, у обоих сообщений это вложение в
|
||||
`attachment_ids`
|
||||
@@ -0,0 +1,18 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Лимиты вложений — константы контракта
|
||||
|
||||
Лимиты вложения — 10 485 760 байт на тело и 40 000 000 пикселей — SHALL
|
||||
быть константами приложения, а не настройками: их задаёт контракт, и
|
||||
они одинаковы на всех установках. Ни окружение, ни `.env`, ни
|
||||
`config.toml` MUST NOT их менять. Соответствие имён skeleton
|
||||
`MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` этим константам SHALL быть
|
||||
описано в `REPORT.md`.
|
||||
|
||||
#### Scenario: Окружение не меняет лимит
|
||||
|
||||
- **WHEN** сервис запущен с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1`
|
||||
в окружении, и участник загружает `sample.png`
|
||||
- **THEN** ответ 201: лимиты остались контрактными
|
||||
@@ -0,0 +1,65 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Без содержимого сообщений и личных данных
|
||||
|
||||
Записи MUST NOT содержать текст сообщений, `display_name`, названия
|
||||
чатов, значения `username`, тела запросов и ответов. Записи MUST NOT
|
||||
содержать пароли, токены сессий, их хэши, значение заголовка
|
||||
`Authorization`, значение `Idempotency-Key` и параметры SQL-запросов.
|
||||
Для сообщений допускаются идентификаторы и длина текста. Повтор
|
||||
отправки SHALL быть виден по признаку повтора и `id` сообщения. Для
|
||||
сессий допускаются `id` сессии и `user_id`.
|
||||
|
||||
С лабы 4 записи MUST NOT содержать:
|
||||
- ключи доступа и секретные ключи S3;
|
||||
- ключ подписи служебных вызовов S3;
|
||||
- подписи запросов к S3: их заголовок `Authorization` и параметры
|
||||
подписи;
|
||||
- байты объектов;
|
||||
- `filename` вложений.
|
||||
|
||||
Для обращений к S3 допускаются адрес S3, имя bucket, ключ объекта,
|
||||
размер, длительность и класс ошибки. Для вложений допускаются `id`
|
||||
вложения и чата, размер, тип, ширина и высота изображения, длина
|
||||
`filename` и причина отказа в загрузке.
|
||||
|
||||
#### Scenario: Отправка сообщения
|
||||
|
||||
- **WHEN** участник отправляет сообщение с текстом T
|
||||
- **THEN** ни одна запись журнала не содержит T, а запись о создании
|
||||
сообщения содержит его `id`, `chat_id` и длину текста
|
||||
|
||||
#### Scenario: Повтор с ключом
|
||||
|
||||
- **WHEN** участник отправляет сообщение с ключом K, повторяет запрос,
|
||||
а затем шлёт с K другое тело
|
||||
- **THEN** ни одна запись журнала не содержит K; запись о повторе
|
||||
содержит `id` исходного сообщения и признак повтора, а ответ 409
|
||||
виден в итоговой записи запроса
|
||||
|
||||
#### Scenario: Вход и выход
|
||||
|
||||
- **WHEN** пользователь регистрируется с паролем P, входит, получает
|
||||
токен T и выходит, а затем кто-то пытается войти с неверным паролем
|
||||
- **THEN** ни одна запись журнала не содержит P, T, хэш T и значение
|
||||
`Authorization`; записи о создании и отзыве сессии содержат `user_id`
|
||||
и `id` сессии, а неудачный вход записан с уровнем `warning` без
|
||||
username и пароля
|
||||
|
||||
#### Scenario: Обращение к S3
|
||||
|
||||
- **WHEN** сервис стартует, затем обращается к S3 сначала с верным, а
|
||||
потом с неверным секретом API
|
||||
- **THEN** ни одна запись журнала не содержит ключ доступа, секрет и
|
||||
подпись запроса; запись о старте содержит адрес S3 и имя bucket, а
|
||||
отказ в учётных данных записан с уровнем `error`
|
||||
|
||||
#### Scenario: Загрузка вложения
|
||||
|
||||
- **WHEN** участник загружает изображение с уникальным `filename` F, а
|
||||
затем повреждённый файл с тем же именем
|
||||
- **THEN** ни одна запись журнала не содержит F; запись о загрузке
|
||||
содержит `id` вложения, размер и тип, а запись об отказе — причину
|
||||
отказа без имени файла
|
||||
@@ -0,0 +1,234 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Обязательные сценарии рубрики
|
||||
|
||||
Набор SHALL содержать отдельные тесты для сценариев уровня «4»:
|
||||
неверный JSON, чужой чат, пустое сообщение, дубликат `username`, обход
|
||||
нескольких страниц истории, а с лабы 2 — неверный пароль и logout. С
|
||||
лабы 4 к ним SHALL добавиться слишком большой файл, повреждённое
|
||||
изображение, подмена MIME, чужое `attachment_id` и вложение другого
|
||||
чата. Каждый такой тест SHALL проверять, что ошибка клиента дала
|
||||
статус 4xx в формате контракта, а не 500.
|
||||
|
||||
#### Scenario: Неверный JSON
|
||||
|
||||
- **WHEN** тест отправляет тело `{bad` в эндпоинт, ожидающий JSON
|
||||
- **THEN** проверяется ответ 400 с `code` `invalid_request`
|
||||
|
||||
#### Scenario: Чужой чат
|
||||
|
||||
- **WHEN** пользователь, не состоящий в чате, читает чат, читает
|
||||
историю и пишет в чат
|
||||
- **THEN** проверяется, что все три запроса получают 404 `not_found`
|
||||
|
||||
#### Scenario: Пустое сообщение
|
||||
|
||||
- **WHEN** участник отправляет сообщение с `text` пустым и из пробелов
|
||||
- **THEN** проверяется ответ 400 `invalid_request`, и сообщение не
|
||||
появляется в истории
|
||||
|
||||
#### Scenario: Дубликат username
|
||||
|
||||
- **WHEN** регистрируется `username`, который уже занят
|
||||
- **THEN** проверяется ответ 409 `conflict`
|
||||
|
||||
#### Scenario: Обход нескольких страниц
|
||||
|
||||
- **WHEN** история содержит больше сообщений, чем помещается на одну
|
||||
страницу, и тест обходит её по `next_cursor`, в том числе меняя
|
||||
`limit` между страницами
|
||||
- **THEN** проверяется, что каждое сообщение встречается ровно один раз
|
||||
в порядке `(created_at, id)`, а последняя страница имеет
|
||||
`next_cursor` null
|
||||
|
||||
#### Scenario: Неверный пароль в рубрике
|
||||
|
||||
- **WHEN** зарегистрированный пользователь входит с неверным паролем
|
||||
- **THEN** проверяется ответ 401 с `WWW-Authenticate` схемы `Basic`, и
|
||||
выданного токена в ответе нет
|
||||
|
||||
#### Scenario: Logout в рубрике
|
||||
|
||||
- **WHEN** пользователь выходит, а затем повторяет запрос прежним
|
||||
токеном
|
||||
- **THEN** проверяется ответ 204 на выход и 401 с `WWW-Authenticate`
|
||||
схемы `Bearer` на повтор
|
||||
|
||||
#### Scenario: Слишком большой файл в рубрике
|
||||
|
||||
- **WHEN** участник загружает файл больше 10 MiB с `Content-Length` и
|
||||
частями без него
|
||||
- **THEN** проверяется ответ 413 `payload_too_large` в обоих случаях
|
||||
|
||||
#### Scenario: Повреждённое изображение в рубрике
|
||||
|
||||
- **WHEN** участник загружает обрезанные PNG и JPEG и PNG с изменённым
|
||||
байтом данных
|
||||
- **THEN** проверяется ответ 415 `unsupported_media_type` на каждый
|
||||
|
||||
#### Scenario: Подмена MIME в рубрике
|
||||
|
||||
- **WHEN** участник загружает JPEG с `Content-Type: image/png` и текст с
|
||||
`Content-Type: image/jpeg`
|
||||
- **THEN** проверяется ответ 415 `unsupported_media_type` на оба
|
||||
|
||||
#### Scenario: Чужое attachment_id в рубрике
|
||||
|
||||
- **WHEN** участник отправляет сообщение с вложением чата, где он не
|
||||
состоит, и с неизвестным id вложения, а посторонний читает метаданные
|
||||
и байты вложения
|
||||
- **THEN** проверяется ответ 404 `not_found` на каждый запрос
|
||||
|
||||
#### Scenario: Вложение другого чата в рубрике
|
||||
|
||||
- **WHEN** участник двух чатов отправляет в один из них сообщение с
|
||||
вложением другого
|
||||
- **THEN** проверяется ответ 404 `not_found`, и сообщение не появляется
|
||||
в истории
|
||||
|
||||
### Requirement: Покрытие сценариев основных спеков
|
||||
|
||||
Для каждого сценария основных спеков `api-conventions`,
|
||||
`identification`, `sessions`, `users`, `chats`, `messages`,
|
||||
`pagination`, `data-storage`, `chat-cache`, `health`, `idempotency` и с
|
||||
лабы 4 `attachments`, который воспроизводится по HTTP против
|
||||
работающего сервера, в том числе на стенде отказов, SHALL быть тест. Из
|
||||
имени или описания теста SHALL быть понятно, какой capability и
|
||||
сценарий он проверяет. Сценарий, который проверяет тест отказа, SHALL
|
||||
считаться покрытым, хотя `make student_test` этот тест не выполняет;
|
||||
итог сверки SHALL называть, сколько сценариев покрыто проверками
|
||||
отказов. Сценарии, которые по HTTP не воспроизвести, SHALL быть
|
||||
перечислены с причиной и способом проверки.
|
||||
|
||||
#### Scenario: Сверка покрытия
|
||||
|
||||
- **WHEN** проверяющий берёт любой сценарий перечисленных спеков
|
||||
- **THEN** находится проверяющий его тест либо запись в списке
|
||||
исключений с причиной
|
||||
|
||||
#### Scenario: Сценарий отказа в сверке
|
||||
|
||||
- **WHEN** выполняется `make student_test`
|
||||
- **THEN** сверка считает сценарии проверок отказов покрытыми, не
|
||||
требует для них исключений и печатает их число
|
||||
|
||||
### Requirement: Проверки отказов на отдельном стенде
|
||||
|
||||
Сценарии отказов SHALL проверяться автоматически одной командой
|
||||
`make failure_checks`:
|
||||
- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при
|
||||
запросе с токеном»;
|
||||
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
|
||||
«БД вернулась», «Соединения исчерпаны»;
|
||||
- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище
|
||||
объектов недоступно»;
|
||||
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
|
||||
«Очистка кэша»;
|
||||
- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке»,
|
||||
«Ключ после срока»;
|
||||
- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего
|
||||
не оставляет», «S3 остановлен», «S3 завис».
|
||||
|
||||
Команда SHALL:
|
||||
- собрать образ из рабочего дерева;
|
||||
- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить
|
||||
миграции и bootstrap S3;
|
||||
- запустить два API: с настройками по умолчанию и «тесный» — с
|
||||
коротким сроком сессии и ключа идемпотентности и пулом из одного
|
||||
соединения;
|
||||
- выполнить проверки отказов;
|
||||
- удалить стенд вместе с его данными при любом исходе.
|
||||
|
||||
Hook стенда отказов SHALL уметь сообщить число вложений в PostgreSQL
|
||||
стенда по статусам и число объектов вложений в его bucket. Других
|
||||
сведений о хранилищах проверки вложений не получают.
|
||||
|
||||
Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на
|
||||
хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш,
|
||||
хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода
|
||||
SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка.
|
||||
Параллельный запуск двух прогонов не поддерживается: уборка хвоста в
|
||||
начале второго удаляет стенд первого.
|
||||
|
||||
#### Scenario: Успешный прогон
|
||||
|
||||
- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks`
|
||||
- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и
|
||||
volumes стенда отказов после команды нет, а у контейнеров рабочего
|
||||
стенда прежнее время старта, и рабочий API отвечает
|
||||
|
||||
#### Scenario: Упавшая проверка
|
||||
|
||||
- **WHEN** во время `make failure_checks` падает хотя бы одна проверка
|
||||
- **THEN** код выхода ненулевой, журналы API стенда отказов выведены,
|
||||
стенд отказов удалён
|
||||
|
||||
#### Scenario: Прерывание
|
||||
|
||||
- **WHEN** `make failure_checks` прерван Ctrl+C
|
||||
- **THEN** стенд отказов остановлен и удалён вместе с volumes
|
||||
|
||||
#### Scenario: Хвост прошлого прогона
|
||||
|
||||
- **WHEN** контейнеры или volumes стенда отказов остались от прогона,
|
||||
убитого без уборки
|
||||
- **THEN** следующий `make failure_checks` удаляет их и начинает заново
|
||||
|
||||
### Requirement: Результат прогона сохраняется
|
||||
|
||||
Вывод прогона против контейнера (`make test_isolated`), вывод `make
|
||||
student_test` против стенда с балансировщиком и вывод `make
|
||||
failure_checks` SHALL сохраняться в `evidence/` с командой, датой,
|
||||
commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в
|
||||
строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов,
|
||||
гонка одного ключа через реплики, автоматические проверки истечения
|
||||
сессии и недоступности БД и Valkey, а с лабы 4 — негативные тесты
|
||||
вложений и проверки отказов S3.
|
||||
|
||||
#### Scenario: Доказательство в отчёте
|
||||
|
||||
- **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md`
|
||||
- **THEN** в ней есть команда, наблюдаемый результат и путь к файлу
|
||||
вывода в `evidence/`
|
||||
|
||||
### Requirement: Доказательства исключений сверки в репозитории
|
||||
|
||||
Если способ проверки сценария из списка исключений сверки покрытия
|
||||
ссылается на файл в `evidence/`, этот файл SHALL лежать в репозитории
|
||||
текущей лабы. В нём SHALL быть результат, снятый на стенде этой лабы,
|
||||
команда, дата и commit. Если способ проверки — команда, которая сама
|
||||
снимает доказательство на стенде, исключение SHALL её называть.
|
||||
|
||||
Сверка покрытия SHALL падать, если файла по ссылке исключения нет, и
|
||||
называть сценарий и путь.
|
||||
|
||||
Такое доказательство MUST NOT содержать токенов, паролей и их хэшей
|
||||
целиком, ключей доступа и секретов S3 — только факты, счётчики и
|
||||
префиксы.
|
||||
|
||||
#### Scenario: Ссылка на отсутствующий файл
|
||||
|
||||
- **WHEN** исключение ссылается на файл `evidence/…`, которого нет в
|
||||
репозитории
|
||||
- **THEN** `make student_test` завершается с ненулевым кодом, а
|
||||
сообщение называет сценарий и путь
|
||||
|
||||
#### Scenario: Кэш и хранение секретов на стенде лабы
|
||||
|
||||
- **WHEN** проверяющий открывает файлы, на которые ссылаются исключения
|
||||
`chat-cache` «Чтение из кэша», «Срок записи», «Временная база»,
|
||||
`sessions` «Токена нет в хранилище» и `users` «Хэш в БД»
|
||||
- **THEN** в них вывод названной в исключении команды на стенде с
|
||||
балансировщиком и двумя репликами, дата и commit, а токенов, паролей
|
||||
и полных хэшей нет
|
||||
|
||||
#### Scenario: Вложения на стенде лабы
|
||||
|
||||
- **WHEN** проверяющий открывает файлы, на которые ссылаются исключения
|
||||
`attachments` «Принявшая реплика остановлена», «Байты не в БД и не на
|
||||
диске API» и «Рестарт стенда»
|
||||
- **THEN** в них вывод названной в исключении команды на стенде с
|
||||
балансировщиком, двумя репликами и S3, дата и commit, SHA-256
|
||||
загруженного и скачанного файла, а токенов и секретов S3 нет
|
||||
@@ -0,0 +1,345 @@
|
||||
# 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 — текст из одних пробелов с вложением даёт 400. Это временная
|
||||
трактовка до ответа преподавателя (design, решение 8). Если ответ
|
||||
другой, меняются условие валидатора `CreateMessage`, сценарий
|
||||
`messages` «Пробелы с вложением» и его тест, а ответ записывается в
|
||||
AGENTS.md, «Согласования с преподавателем»;
|
||||
- п. 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 — отказ;
|
||||
- `\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`.
|
||||
- Разовый скрипт в 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` — новые тесты проходят; на рабочем стенде через LB
|
||||
`replicas`-тест выполняется, в `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-256
|
||||
`99ea7533…` совпадает; 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_commit` `e1161f7`;
|
||||
- ревизия до замены — `e656d6bbe1a4`, после — новая.
|
||||
- [ ] 7.2 Регресс прежних профилей: `make bench_quick`, `make
|
||||
bench_failover_quick`, `make bench_restore_quick` — код 0. В
|
||||
`explain-10k.txt` пробной метки узел истории — прежний индекс
|
||||
`messages`, а `SubPlan` идёт по `pk_message_attachments` (решение 8).
|
||||
Пробные метки `quick-*` в git не идут.
|
||||
|
||||
## 8. Документы и проверка кода
|
||||
|
||||
- [ ] 8.1 Правила:
|
||||
- `api-contract.md` — раздел лабы 4: ручки, коды 413 и 415 в
|
||||
таблице, порядок проверок загрузки, `filename` (только символы
|
||||
контракта, категория Cc), `UuidIn` для id вложений, ранний ответ и
|
||||
`urllib`, временная трактовка текста из пробелов с вложением;
|
||||
- `api-layer.md` — роутер с двумя префиксами, `CurrentUserBrief`,
|
||||
тело без параметра, `StreamingResponse`, `UploadInterrupted`;
|
||||
- `service-layer.md` — `AttachmentService` с `db_scope`, порядок
|
||||
записи, проверка вложений сообщения, хэш;
|
||||
- `repo-layer.md` — repo вложений, repo объекта S3, подзапрос
|
||||
`ARRAY`;
|
||||
- `dto.md` — новые DTO и enum;
|
||||
- `migrations.md` — таблицы вложений, ослабление CHECK `NOT VALID`,
|
||||
почему не `autocommit_block`;
|
||||
- `logging.md` — записи `attachment_service`, `filename` не пишется;
|
||||
- `student-tests.md` — `test_attachments.py`, `images.py`, Pillow в
|
||||
dev, отказы S3 и действия hook, новые исключения;
|
||||
- `settings.md` — `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` —
|
||||
константы;
|
||||
- `bench.md` — `rollout_from`.
|
||||
|
||||
Ещё AGENTS.md (карта кода, команды драйвера, «Переход в следующую
|
||||
лабу» — `rollout_from`, таблица важных файлов) и `PLAN.md`,
|
||||
`### attachments` («Решения» из apply). Проверка: `grep -rn
|
||||
"c50b721" AGENTS.md .claude bench KNOWN_ISSUES.md` пуст.
|
||||
- [ ] 8.2 `make lint`, `make check`, `openspec validate attachments
|
||||
--strict`, `graphify update .`.
|
||||
|
||||
## 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/` пуст.
|
||||
Коммит — после подтверждения.
|
||||
- [ ] 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» с командой, наблюдением и файлом;
|
||||
- ограничения;
|
||||
- открытый вопрос преподавателю: текст из одних пробелов с вложением
|
||||
пока даёт 400 (design, решение 8).
|
||||
|
||||
Строку этапа 2 в `PLAN.md` — по факту. Проверка: у каждой новой строки
|
||||
таблицы доказательств есть команда, наблюдение и файл; `make lint`,
|
||||
`make check`, `openspec validate attachments --strict`. Коммит — после
|
||||
подтверждения.
|
||||
Reference in New Issue
Block a user