diff --git a/.claude/rules/api-contract.md b/.claude/rules/api-contract.md index 621a7b36..337736a6 100644 --- a/.claude/rules/api-contract.md +++ b/.claude/rules/api-contract.md @@ -78,12 +78,13 @@ FastAPI 0.141 из `uv.lock`: | 401 | `unauthorized` | вход: неверные username или пароль, битый Basic; остальное: нет Bearer, токен неизвестен, истёк или отозван, пришёл Basic. Всегда с `WWW-Authenticate` (`auth.md`) | | 404 | `not_found` | объекта нет **или** он чужой; неизвестный путь | | 409 | `conflict` | `username` занят; с лабы 3 — тот же `Idempotency-Key` с другим телом сообщения | -| 500 | `internal_error` | необработанное исключение, без деталей | -| 503 | `unavailable` | недоступен Postgres или хранилище сессий: ограниченная ошибка вместо 500 (`infra.md`) | +| 413 | `payload_too_large` | с лабы 4: тело загрузки больше 10 MiB (по `Content-Length` или счётчику) или изображение больше 40 млн пикселей (`PayloadTooLarge`) | +| 415 | `unsupported_media_type` | с лабы 4: `Content-Type` не PNG/JPEG, содержимое не PNG/JPEG, подмена MIME, повреждённое изображение (`UnsupportedMediaType`) | +| 500 | `internal_error` | необработанное исключение, без деталей; с лабы 4 ещё у готового вложения нет объекта в S3 или он другого размера (`AttachmentContentMissing`, причина — `error` в журнале) | +| 503 | `unavailable` | недоступен Postgres или хранилище сессий: ограниченная ошибка вместо 500 (`infra.md`); с лабы 4 — недоступен S3 на путях байтов вложений | -`413`, `415`, `429` в схеме есть, но на лабе 3 обязательной причины для -них нет. Для 429 нужен `Retry-After`. `DELETE /auth/sessions/current` -отвечает 204 без тела. +`429` в схеме есть, но обязательной причины для него нет. Для 429 нужен +`Retry-After`. `DELETE /auth/sessions/current` отвечает 204 без тела. - Время — RFC 3339 UTC с `Z`, назначает сервер. Формат отдавать явно через `src/utils/utc.py`, а не полагаться на сериализацию по @@ -106,11 +107,12 @@ FastAPI 0.141 из `uv.lock`: `limit=5` приходит строкой. - Malformed JSON и не-объект вместо объекта → 400. FastAPI отдаёт их как 422 `json_invalid`, это переводится общим обработчиком. -- Обязательные строки (`display_name`, `title`, `text`, `password`) не +- Обязательные строки (`display_name`, `title`, `password`) не могут состоять только из пробельных символов (`str.strip()` пустой → - 400). Само значение не обрезать. + 400). Само значение не обрезать. `text` сообщения с лабы 4 — особый + случай (раздел «Вложения» ниже). - Длины считаются в Unicode code points: `len(str)` в Python как раз они. - `display_name` и `title` — 1–100, `text` — 1–4000, `password` — + `display_name` и `title` — 1–100, `text` — до 4000, `password` — 12–128. - `username` — строго `^[a-z0-9_]{3,32}$` на всю строку. В ручной проверке `re.fullmatch`: `re.match` с `$` пропускает `\n` в конце. @@ -249,4 +251,60 @@ ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook — `student-tests/`, а не считать доказанным. - Прозрачных повторов других `POST` нет ни в API, ни в LB: создание чата или регистрация при повторе создали бы второй объект - (`balancer.md`, повторы LB только на отказ соединения). + (`balancer.md`, повторы LB только на отказ соединения). Загрузка + вложения тоже не идемпотентна: повтор — второе вложение. + +## Вложения (лаба 4) + +Семантика — `contracts/README.md`, «Вложения (с lab4)», и спек +`attachments`; устройство — design change `attachments`. + +- Ручки: `POST /api/v1/chats/{chat_id}/attachments?filename=…` — сырые + байты одного PNG/JPEG (не multipart, не JSON), `201 Attachment` со + `status=ready`, `variants=[]`, `error_code=null` только после записи + объекта в S3 и `ready` в PostgreSQL; `GET /api/v1/attachments/{id}` — + метаданные, равные ответу загрузки; `GET …/{id}/content` — байты + оригинала потоком, `Content-Type` вложения без параметров, + `Content-Length`, `X-Content-Type-Options: nosniff`, без redirect. + `variant` — только `original` (иное — 400). Ключ объекта, адрес и + ключи S3 в ответ не попадают. +- Доступ — любой участник чата вложения. Посторонний, неизвестный id и + вложение в статусе `pending` — одинаковый 404 «Not found». +- Порядок проверок загрузки: 401 → 400 (`chat_id`, `filename`, их + проверяет FastAPI после зависимостей) → 404 (членство) → 415 + (`Content-Type`: тип до `;`, без регистра) → 413 (`Content-Length`) → + 413 (счётчик прочитанного) → 415/413 (содержимое: сигнатура и подмена + MIME, целостность, пиксели). Тело не читается до пройденных 1–5. + Пустое тело — 415. +- Лимиты — константы `ATTACHMENT_MAX_BYTES` (10 485 760) и + `ATTACHMENT_MAX_PIXELS` (40 млн), не настройки (`settings.md`). Ровно + лимит проходит. +- Целостность — структурная проверка без декодирования пикселей + (`src/utils/image.py`): у PNG CRC чанков, поток IDAT ровно в объём по + размерам, типы фильтров строк, IEND; у JPEG маркеры, один SOF, скан, + EOI. Хвост после IEND/EOI — часть оригинала. Байт внутри данных скана + JPEG не ловится — граница, она названа в спеке и `REPORT.md`. +- `filename` — 1–255 code points; 400 только по списку контракта: `/`, + `\`, управляющие символы категории Unicode Cc (U+0000–U+001F, + U+007F–U+009F) и строка из одних пробелов. Символы форматирования и + направления текста (Cf, U+202E, U+2066), U+2028/U+2029 принимаются и + возвращаются без изменений (решение пользователя 2026-10-20). Имя + только отображается: ни в ключ, ни в путь, ни в журнал. +- `attachment_id` в пути и элементы `attachment_ids` в теле — `UuidIn` + (раздел «Валидация → 400»). `attachment_ids`: 0–10, без повторов (и в + другом регистре), иначе 400; каждое — готовое вложение этого чата, + иначе 404 до захвата ключа идемпотентности. Ответы — id в нижнем + регистре, в порядке отправки. +- Текст сообщения: до 4000 code points; пустой текст — `""` или строка + из одних пробельных символов — допустим только с хотя бы одним + вложением, без вложений 400. Сохраняется как прислан, без обрезки + (согласовано с преподавателем 2026-10-20, AGENTS.md). Правило держит + валидатор `CreateMessage`; CHECK в БД — только верхняя граница. +- Ранний ответ: 404, 413 и 415 отдаются, не дочитав тело. httpx и `curl` + получают его и напрямую, через LB — любой клиент (HAProxy дочитывает + тело сам). `urllib` напрямую к одной реплике ранний ответ на большом + теле теряет (`BrokenPipe`) — ограничение, оно в `REPORT.md`; тесты на + httpx. +- Отказ S3 — 503 только на загрузке и скачивании байтов. Метаданные, + сообщения (в том числе со ссылкой на готовое вложение), история и + `/health/ready` работают без S3. diff --git a/.claude/rules/api-layer.md b/.claude/rules/api-layer.md index 5cc314bb..54e0a764 100644 --- a/.claude/rules/api-layer.md +++ b/.claude/rules/api-layer.md @@ -27,6 +27,10 @@ FastAPI, один процесс на реплику; реплик ≥2 за HAP Вложенный ресурс — префикс с параметром: `message.py` → `prefix="/chats/{chat_id}/messages"`. Логгер модуля `module="api__router"`. +- Исключение — `attachment.py` (лаба 4): один роутер домена с двумя + префиксами путей, `APIRouter(tags=["attachments"])` и полные пути + `/chats/{chat_id}/attachments`, `/attachments/{attachment_id}` и + `/attachments/{attachment_id}/content` в декораторах. - Версию задаёт `v1_router` (`API_V1_PREFIX` из `src/utils/constants.py`) в `routers/v1/__init__.py`. Регистрация домена — импорт и `v1_router.include_router(...)` там, больше нигде. @@ -51,6 +55,35 @@ FastAPI, один процесс на реплику; реплик ≥2 за HAP глобального `session_factory` (`src/infra/db/session.py`): одна на запрос, закрывается после ответа, вся работа с БД ограничена сроком, отказ БД — 503 (`infra.md`). Commit делает сервис (`service-layer.md`). +- Длинная передача байтов (вложения, лаба 4; design change + `attachments`, решение 5). `get_db_session` — зависимость с `yield`, и + FastAPI закрывает её после отправки ответа целиком: её срок + (`request_timeout_seconds`, 6 с) и соединение пула охватили бы чтение + тела 10 MiB, PUT в S3 и отдачу потока. Поэтому ручки вложений: + - вход — `CurrentUserBrief` (`get_current_user_brief`): Bearer, короткий + `async with db_session_scope()` вокруг `SessionService.authenticate`, + соединение вернулось в пул до тела запроса; обычная функция, не + генератор; + - сервис — `AttachmentServiceDep` без `DbSessionDep`: он получает + фабрику `db_session_scope` (контекст на один шаг с БД, тот же срок и + перевод отказа в 503, что у `get_db_session`), кэш и глобал + `object_storage`; + - загрузка объявляет `request: Request` и не объявляет параметр тела — + FastAPI тело не читает; схема тела (`image/png`, `image/jpeg`, + `format: binary`) — в `openapi_extra`. Тело уходит в сервис + асинхронным итератором поверх `request.stream()`, обёртка переводит + `ClientDisconnect` в доменное `UploadInterrupted` (400): в итоговой + записи 400, а не 500 с traceback. `Content-Type` — тип до `;`, без + пробелов, в нижнем регистре; `Content-Length` — `int` или `None`; + - скачивание — `StreamingResponse` над генератором блоков объекта S3: + `media_type` вложения (у `image/*` Starlette `charset` не добавляет), + `Content-Length`, `X-Content-Type-Options: nosniff`; генератор сам + закрывает объект в `finally`, тот же закрыватель — фоновой задачей + ответа на случай, если генератор не начался; + - `variant` — `Literal["original"]` с `Query(json_schema_extra={"enum": + ["original"]})`: Literal из одного значения pydantic пишет как + `const`, а контракт — `enum`. + JSON-ручки по-прежнему на `get_db_session`. - Ошибки — доменные исключения из сервиса. `HTTPException` не бросать. Статус, `code` и заголовки ответа (`WWW-Authenticate` у 401) назначает одна таблица в `errors.py`. diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index fa2d958f..e0aab84a 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -250,13 +250,23 @@ change `s3-storage`, решение 9): старт стенда перечисл сверка — как у `failover` (`k6/failover.js`, `k6/retry.js`, поля `failover_*` профиля). Окна — `rollout_before_s` до запуска скрипта, бюджет замены `rollout_budget_s`, ещё `rollout_after_s`. -- Реплики стартуют на образе `Profile.rollout_from` (сейчас `c50b721`, - последний commit до change в репозитории лабы 3; в лабе 4 его нет — - `KNOWN_ISSUES.md`, до правки — `--from `): `git archive - | docker build` - под тегом `mtusi-messenger:bench-from`, затем `docker tag` на - `mtusi-messenger:bench`. Рабочее дерево не трогается; тег снимается - при уборке. `--from ` — отладка (`overrides`). +- Реплики стартуют на образе `Profile.rollout_from`: `git archive + | docker build` под тегом `mtusi-messenger:bench-from`, затем + `docker tag` на `mtusi-messenger:bench`. Рабочее дерево не трогается; + тег снимается при уборке. `--from ` — отладка (`overrides`). +- **Какой commit** (спек `load-benchmark`, «Прежний commit профиля + замены»; design change `attachments`, решение 14): commit текущей лабы + до изменения, которое показывает замена. Сейчас — `e1161f7`, последний + commit лабы 4 до change `attachments`: замена показывает миграцию + вложений (две таблицы и ослабление `ck_messages_text_length` с `NOT + VALID`), ревизия `e656d6bbe1a4` → `ef25d50b01a8`. Commit меняется: + - при переходе в следующую лабу — commit прошлой лабы в её истории нет + (AGENTS.md, «Переход в следующую лабу»); + - когда замена должна показать новое изменение схемы. + + `run.py` проверяет commit до стенда (`git rev-parse --verify + ^{commit}`): нет в истории — код 2, сообщение называет commit + и `--from`. Commit — в паспорте метки (`rollout.from_commit`). - Замену делает **тот же** `scripts/rolling-update.sh`, что у рабочего стенда. Правило «`-p mtusi-bench`, оба `-f`, `--env-file`» выполняется переменными `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, diff --git a/.claude/rules/dto.md b/.claude/rules/dto.md index 83b0663c..593d2f0e 100644 --- a/.claude/rules/dto.md +++ b/.claude/rules/dto.md @@ -38,3 +38,11 @@ paths: - Короткий docstring на русском, если назначение не очевидно из имени. - Enum-ы — `StrEnum`. Значение хранится в БД, поэтому переименование значения = миграция (`migrations.md`). +- Вложения (лаба 4): `AttachmentStatus` (`pending`, `ready`; новое + значение — замена CHECK) и `ImageType` (`image/png`, `image/jpeg`) в + `enums/attachment.py`. `AttachmentFullDTO` — все колонки строки, в + том числе `object_key` и `sha256` байтами: ключ в API не уходит, hex + собирает модель ответа. `AttachmentContentDTO` — не снимок строки, а + поток на отдачу: тип, размер, асинхронный итератор блоков и `close`. + `MessageFullDTO.attachment_ids: tuple[UUID, ...] = ()` — значение по + умолчанию последним полем. diff --git a/.claude/rules/logging.md b/.claude/rules/logging.md index 3cb6165f..9ce94f55 100644 --- a/.claude/rules/logging.md +++ b/.claude/rules/logging.md @@ -134,6 +134,17 @@ paths: storage bucket is missing» (`NoSuchBucket`), `debug` на успешный вызов; текста исключения botocore в записи нет. Запись «Started API» — с `s3_host`, `s3_port`, `s3_bucket`; пустые ключи — `warning`. +- С лабы 4 — `filename` вложений (его выбирает пользователь) и байты + изображений. Модуль `attachment_service` пишет `info` «Uploaded + attachment» (`attachment_id`, `chat_id`, `size_bytes`, + `content_type`, `width`, `height`, `duration_ms`), `info` «Rejected + attachment» с `reason` (`type`, `declared_size`, `size`, `content`, + `content_mismatch`, `damaged`, `pixels`, `interrupted`), `chat_id` и + `filename_length`, `error` «Attachment content is missing» / «…size + differs» с `attachment_id` и `object_key`. `MessageService` пишет + `attachments_count` в «Created message» и «Rejected message + attachments». Поле `filename` у записей — место вызова в коде + (`CallsiteParameterAdder`), а не имя файла вложения. - Stack trace — только в лог, никогда в ответ. ## Где логировать diff --git a/.claude/rules/migrations.md b/.claude/rules/migrations.md index 0c5fa7da..d619349d 100644 --- a/.claude/rules/migrations.md +++ b/.claude/rules/migrations.md @@ -48,6 +48,23 @@ paths: все новые запросы к таблице, и чужая долгая транзакция остановила бы запись всех реплик. По сроку миграция падает без изменений, замена не начинается, повтор проходит. + - Ревизия `ef25d50b01a8` (лаба 4, design change `attachments`, + решение 3): таблицы `attachments` (составной FK `(chat_id, + owner_id) → chat_members`, CHECK размера, SHA-256 32 байта, типа, + статуса, длины и символов `filename` — `!~ '[/\\\u0001-\u001f\u007f-\u009f]'`, + уникальный `object_key`) и `message_attachments` (PK `(message_id, + position)`, `position` 0–9, уникальная пара `(message_id, + attachment_id)`, индекс по `attachment_id`, FK без `ON DELETE`). + Плюс **ослабление** `ck_messages_text_length` с `1–4000` до + `<= 4000`: `DROP CONSTRAINT` и `ADD CONSTRAINT … NOT VALID` в той же + транзакции. Прежние строки строже нового условия, проверять их + нечего, а `VALIDATE` держал бы `ACCESS EXCLUSIVE` на время полного + просмотра `messages`. Не `autocommit_block`: он зафиксировал бы DDL + раньше `alembic_version`, и сбой оставил бы неповторяемую миграцию. + Отметка «не проверено» в каталоге — цена, она в `REPORT.md`. + `downgrade` — зеркально, строгое ограничение тоже `NOT VALID`. + Autogenerate изменение CHECK не видит; имя ограничения — через + `op.f(...)`, иначе шаблон имён даст `ck_messages_ck_messages_…`. - `lock_timeout` миграции меньше `[database] statement_timeout_ms` приложения (5 с) с запасом. Запросы в очереди за миграцией ждут её отказа, и при равных сроках все они получали 503 вместе с ним: diff --git a/.claude/rules/repo-layer.md b/.claude/rules/repo-layer.md index 74fc99a3..15446993 100644 --- a/.claude/rules/repo-layer.md +++ b/.claude/rules/repo-layer.md @@ -49,6 +49,25 @@ paths: Порог `expired_before`, решение «повтор или 409» и commit — в сервисе. Ключ в исключения и логи не попадает. +- Repo вложений (лаба 4, design change `attachments`, решения 3, 4, 8): + - `attachment.py`: `insert_attachment`, `mark_ready` (`UPDATE … WHERE + status = 'pending' RETURNING`, `None` — строки `pending` нет), + `get_attachment`, `get_attachments` (до 10 строк по первичному + ключу). Значения `content_type` и `status` — `.value` enum на + записи и enum в DTO на чтении; + - `attachment_object.py` — repo над S3, как `chat_cache.py` над + Valkey: первый параметр `storage: ObjectStorage`, один вызов на + функцию. `original_key` собирает `/attachments// + original` (namespace — имя базы, `filename` не входит), + `put_original`, `open_original` (контекст объекта). Ключ хранится в + строке и при чтении берётся из неё, не вычисляется заново; + - `message.py`: `MESSAGE_COLUMNS` с коррелированным подзапросом + `ARRAY(SELECT attachment_id … ORDER BY position)` — одно выражение на + страницу и на сохранённый результат ключа; план — `SubPlan` по + `pk_message_attachments` на строку страницы, индекс истории прежний. + DTO — `to_message_dto` (массив → кортеж). Вставка сообщения + перечисляет свои колонки, связи — `insert_message_attachments` одной + многострочной вставкой с `position`. - Repo кэша (`chat_cache.py`) — то же правило над Valkey: первый параметр `cache: Cache`, одна команда на функцию, ключ и формат значения (JSON ↔ DTO) живут здесь. Ключ включает diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index 4bc24254..94e28369 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -67,6 +67,33 @@ paths: транзиентной ошибки не сохраняется; - лог: `Created message` или `Replayed message` с `message_id` и `replayed`, без ключа и текста (`logging.md`). +- Вложения (лаба 4, design change `attachments`, решения 1, 5–9): + - `AttachmentService(db_scope, cache, storage)` — отличие от правила + выше: вместо `db_session` фабрика короткой сессии на шаг + (`db_session_scope`), каждый шаг с БД — свой `async with + self.db_scope()`, без вложенных: соединение пула не занято передачей + тела, на запрос не больше одного соединения. `storage` — глобал + `object_storage` из зависимости; + - порядок записи загрузки: проверки (членство, `Content-Type`, + `Content-Length`) → чтение тела со счётчиком → структура + изображения и SHA-256 одним `anyio.to_thread.run_sync` → строка + `pending` с `object_key` (commit) → PUT (`attachment_object_repo`) → + `mark_ready` (commit) → DTO. Отказ S3 или БД после `pending` — 503, + строка остаётся до уборщика (`upload-consistency`); `mark_ready` не + нашёл `pending` — `RuntimeError`. Отклонённая до `pending` загрузка + ничего не пишет; + - чтение: `pending`, нет строки, не участник — одно + `AttachmentNotFound`; скачивание — `open_original` вне транзакции, + нет объекта или другой размер — `error` в журнале и + `AttachmentContentMissing` (500), строка не меняется; + - `MessageService.send_message(..., attachment_ids)`: членство → + `get_attachments` (все найдены, чат этого сообщения, `ready`; иначе + `AttachmentNotFound` до захвата ключа) → хэш → ключ → сообщение → + `insert_message_attachments` (если список непустой) → один commit; + - хэш: `message_request_hash(text, attachment_ids)` — `attachment_ids` + в каноническом JSON только непустым, id — `str(UUID)` (нижний + регистр), порядок значим. Пустой список хэш версии `e1161f7` не + меняет: ключ, сохранённый до замены реплик, повторяется. - Недоступность Postgres (там же хранятся сессии) — доменное `ServiceUnavailable` (→ 503), не 500 и никогда не пропуск запроса без аутентификации (`infra.md`). Недоступность Valkey — не ошибка, а diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index ceeec431..ac11e5e2 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -51,7 +51,7 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда | `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL сессии, таймауты, пул и срок записей `[cache]`, регион, сроки и пул `[s3]`, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` | | `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*`, `VALKEY_*` и `S3_*` (адрес, порты, учётные данные, секреты S3 с лабы 4), пароль брокера с лабы 5; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольные адреса Postgres, Valkey и S3 | нет; шаблон `.env.example` | | окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — | -| `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50), пути: одинаковы на всех установках | да | +| `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50; с лабы 4 — 10 MiB и 40 млн пикселей вложения, 10 вложений в сообщении, `filename` 1–255), пути: одинаковы на всех установках | да | Схему согласовали с преподавателем 2026-09-29 (AGENTS.md, «Согласования с преподавателем»). Секреты в `config.toml` допустимы. Запрет @@ -200,7 +200,14 @@ Skeleton lab4 добавил имена `S3_*` (буквально не заво - `S3_BUCKET` → `S3__BUCKET`; - `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` → мосты из `S3_API_*`: значения, а не файлы, как с `DATABASE_URL_FILE`; -- `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` — change `attachments`. +- `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` — **константы, не настройки** + (спек `service-configuration`, «Лимиты вложений — константы + контракта»; design change `attachments`, решение 10): + `ATTACHMENT_MAX_BYTES` (10 485 760) и `ATTACHMENT_MAX_PIXELS` + (40 000 000) в `src/utils/constants.py`. Их задаёт контракт, они + одинаковы на всех установках, поэтому ни окружение, ни `.env`, ни + `config.toml` их не меняют, и в `.env.example` они не заводятся. + Соответствие имён — в `REPORT.md`. `X-Instance-Id` берётся из `[app] instance_id`: по умолчанию пусто, и тогда валидатор поля подставляет hostname процесса (один раз, при diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index e892dc16..4bc5f429 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -70,6 +70,50 @@ paths: значение, через LB каждое значение повторяется, и вторая серия не приносит новых. Опирается на round-robin LB. +Лаба 4 добавляет (спек `attachments`, design change `attachments`, +решение 12): + +- `test_attachments.py` — сценарии спека `attachments`, кроме проверок + отказов и исключений: загрузка PNG/JPEG и разновидностей, граница + размера, 413 по `Content-Length` и частями, пиксели, «бомба», тип по + содержимому и подмена MIME, повреждения и хвост, `filename` (400 только + по списку контракта, Cf/Zl принимаются как есть), порядок проверок, + доступ, метаданные, побайтный оригинал, `variant`, следы хранилища, + повторная загрузка; «Скачивание через другую реплику» — с фикстурой + `replicas`. Новые сценарии `messages`, `idempotency`, + `api-conventions`, `data-storage` — в их модулях; пять сценариев + рубрики «4» лабы 4 — в `test_rubric.py` (сценарий `student-tests` — в + докстринге, маркеры — на сценарии `attachments` и `messages`); +- `images.py` — генераторы: PNG на stdlib (любые IHDR и IDAT, Adam7, + точный размер чанком `tEXt`, «бомба», огромные размеры, порча байта + IDAT), JPEG через Pillow (разновидности, подмена размеров в SOF), + обрезка и хвост. Большие файлы и «бомбы» живут в памяти теста, в git + не попадают. Pillow — только dev-группа (`uv add --dev pillow`): в + образе (`uv sync --no-dev`) и в `src` его нет; +- `api_client.py`: `post_attachment` (байты или итератор — частями, + без `Content-Length`; `None` — без заголовка или параметра), + `upload` (201 и проверка размера, SHA-256, `owner_id`, `filename`), + `attachment_meta`, `attachment_content`, `send_message(..., + attachment_ids=…)`. `contract.py`: коды 413 и 415, `owner_id` и + элементы `attachment_ids` — UUID в нижнем регистре, `updated_at` — + время, `assert_content` (байты, тип, длина, `nosniff`, без `Location` + и `x-amz-*`); +- проверки отказов (`test_failures.py`): «Запись в S3 не удалась», + «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 + завис». Hook — `count-attachments` (`pending=N ready=M` через psql) и + `count-objects` (каталоги `` под `/buckets//<база>/ + attachments` через `weed shell` в контейнере `s3`; bucket и база — + `FAULT_S3_BUCKET`, `FAULT_DATABASE` от `run_failures.py` из + конфигурации compose стенда). Срок «S3 завис» — `[s3] + timeout_seconds` (5 с) плюс запас; клиент теста — со сроком больше + этого, иначе httpx оборвёт раньше ответа; +- исключения сверки: «Принявшая реплика остановлена» — `driver.py + attachment-failover` → `evidence/attachments/failover.md`; «Байты не в + БД и не на диске API» — `driver.py attachment-storage` → + `evidence/attachments/storage.md`; «Рестарт стенда» — `make + test-persistence` (с `LAB=4` публичная проверка скачивает оригинал + после hook) → `evidence/replicas/test-persistence.md`. + Проверки отказов реплик (остановка, kill, зависание, rolling update) — не pytest, а `make test-failover`, профиль `failover` стенда `bench/` (`make bench_failover`, `bench.md`), команды драйвера `kill-inflight`, diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 7fa5c543..6e090500 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -20,7 +20,11 @@ HAProxy на `APP_OUT_PORT` перед репликами API) работают реплика, `hang-key` — повтор ключа после зависшей реплики, `cache-check` и `auth-storage` — доказательства исключений сверки покрытия (кэш, хранение паролей и токенов), `s3-check` (`make -s3_check`) — приватность bucket вне API. `stop-at-start` — остановка +s3_check`) — приватность bucket вне API, `attachment-failover` и +`attachment-storage` — доказательства исключений `attachments` +(остановка реплики, принявшей файл; где лежат байты). `upload` и +`download` — загрузка и скачивание вложения с SHA-256 на любом +сервере. `stop-at-start` — остановка контейнеров образа во время старта, без стенда. Только стандартная библиотека Python 3.9+: `make instances` запускает драйвер системным `python3` (на macOS — 3.9), поэтому без `datetime.UTC`, @@ -55,8 +59,9 @@ make env_setup # .env (случайные POSTGRES_PASSWORD, VALKEY_PASS Нужен запущенный Docker: Postgres, Valkey и S3 живут в compose. Без Postgres сервер стартует, но `/health/ready` отвечает 503; без Valkey всё работает, но мимо кэша (`warning` «Cache is unavailable» в логе); -без S3 `/health/ready` — 200, а пути вложений (с change `attachments`) -— 503. `driver.py start` сам делает `make upgrade start_cache +без S3 `/health/ready` — 200, а загрузка и скачивание байтов +вложений — 503 (метаданные, сообщения и история работают). S3 нужен +только путям вложений. `driver.py start` сам делает `make upgrade start_cache start_s3`. В `.env`, созданном до `membership-cache` или `s3-storage`, нет строк Valkey или S3: их переносят из `.env.example` руками, иначе compose падает с `… is empty, copy … lines from .env.example`. @@ -77,12 +82,18 @@ python3 $D status # listeners: [pid reloader, pid worker], ready: True python3 $D flow # ~60 проверок: регистрация с паролем, вход, 409, неверный пароль, # 401 с WWW-Authenticate, X-User-Id игнорируется, чат, 5 сообщений, # пагинация limit=2 по курсору, чужой → 404, 400-е, повтор с ключом, - # 409 на другое тело, без ключа → 400, logout; X-Instance-Id везде + # 409 на другое тело, без ключа → 400, вложение: загрузка fixture, + # сообщение со ссылкой, оригинал Бобу (SHA-256), 404 Еве; logout; + # X-Instance-Id везде python3 $D req POST /api/v1/users --data '{"username":"zoe_demo","display_name":"Зоя","password":"Zoe-password-1"}' python3 $D req POST /api/v1/auth/sessions --basic zoe_demo:Zoe-password-1 python3 $D req GET /api/v1/users/me --token python3 $D req POST /api/v1/chats//messages --token --data '{"text":"hi"}' # печатает idempotency-key; повтор той же отправки — тот же запрос с --key <ключ> +python3 $D upload --token --chat --file tests/fixtures/sample.png + # 201, x-instance-id, Attachment, SHA-256 файла и «sha256 matches: True» +python3 $D download --token --attachment [--out /tmp/x.png] + # 200, Content-Type, размер, SHA-256 полученного (99ea7533… у fixture) python3 $D smoke # публичный tests/smoke.py против этого порта python3 $D student # make student_test BASE_URL=http://localhost: — ~20 с python3 $D --port 8080 instances # стенд через LB: X-Instance-Id 12 запросов одной сессии @@ -104,6 +115,10 @@ python3 $D stop | `cache-check [--require-test-keys]` | только стенд с LB (`--port 8080`): сценарии `chat-cache` «Чтение из кэша», «Срок записи», «Временная база». Два синтетических пользователя и чат; ключ `messenger:v1:<база>:chat:` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_`) базы. Код 0 — чтений `chats` ≤ 1, hits ≥ +49, промахов ≤ 1, ответы равны ответу на создание, TTL не продлевается, ≥ 2 `X-Instance-Id`. Для «Временной базы» перед ней — `make test_isolated`: без ключей тестовой базы строка `PASS` заканчивается «temporary database: not checked», с `--require-test-keys` — код 1 (доказательство сценария снимается с флагом). На стенде в это время ничего другого не должно идти. Вывод — `evidence/cache/hits.md` | | `auth-storage` | только стенд с LB: сценарии `users` «Хэш в БД» и `sessions` «Токена нет в хранилище». Пароль P (с `:` и кириллицей) и токен T — только в памяти; через psql — префикс `$argon2id$…` до соли и длина у двух пользователей с одним P, неравенство хэшей, строка `sessions` с `token_hash` = SHA-256(T) (32 байта); `pg_dump --data-only` в память — нет ли T (текстом и в hex) и P. Код 0 — всё так. Вывод — `evidence/auth/passwords-and-tokens.md` | | `s3-check` | стенд compose (`make s3_check`), без приложения: спек `object-storage` «Проверка приватности вне API». `docker compose run --rm --no-deps s3-bootstrap check` — права ключа API (PUT/GET/HEAD объекта, 404 отсутствующего; 403 на список, создание и удаление bucket, политику и ACL bucket, публичный ACL объекта), временный чужой bucket (403 на всё), аноним изнутри сервера (403); анонимные запросы с хоста (`127.0.0.1:S3_OUT_PORT`) и из сети стенда (одноразовый контейнер образа S3), порты контейнера S3: слушающие сокеты из `netstat -tuln` в контейнере — вне loopback ровно API S3 и gRPC шлюза, а остальные слушающие порты из сети закрыты (`nc -z`); затем `s3-bootstrap cleanup` и `weed shell` — проверочных объектов и bucket не осталось. Таблица «где → проверка → ожидаемо → получено» без секретов, код 1 при расхождении (печатает нарушенные). Вывод — `evidence/s3/privacy.md` | +| `upload --token T --chat C --file F [--type …] [--filename …]` | загрузка файла сырыми байтами (`urllib`): статус, `x-instance-id`, тело `Attachment`, размер и SHA-256 файла, совпал ли `sha256` ответа. `--type` по умолчанию — по сигнатуре (PNG, JPEG, иначе `application/octet-stream`), `--filename` — имя файла. Код 2 при статусе ≥ 400 | +| `download --token T --attachment A [--out F] [--variant …]` | скачивание оригинала: статус, `x-instance-id`, `Content-Type`, `Content-Length`, размер и SHA-256 полученного; `--out` сохраняет байты. Код 2 при статусе ≠ 200 (тело ошибки печатается) | +| `attachment-failover [--mode stop\|kill]` | только стенд с LB: спек `attachments` «Принявшая реплика остановлена». Синтетические Алиса, Боб, Ева и чат; загрузка `tests/fixtures/sample.png` через LB (реплика A — `X-Instance-Id` ответа), сообщение со ссылкой, `scripts/stop-one.sh` с `TARGET_INSTANCE_ID=A` и `STOP_MODE`, Боб скачивает через LB (до 30 попыток), пока не ответит другая реплика: SHA-256 совпадает, метаданные равны ответу загрузки; Ева — 404 на метаданные и байты. В `finally` — `make replicas`, затем ожидание, пока LB снова видит все реплики `UP`. Печатает `docker compose ps` до и после и таблицу «шаг → ожидаемо → получено → реплика» без токенов. Код 1 при расхождении, без LB (порт консольного процесса драйвера) — код 2. Вывод — `evidence/attachments/failover.md` | +| `attachment-storage` | только стенд с LB: спек `attachments` «Байты не в БД и не на диске API». Две загрузки fixture через LB; psql — колонки `attachments` и `message_attachments` (из `bytea` только 32-байтный `sha256`), `object_key` = `<база>/attachments//original` без `filename`; `weed shell fs.ls -l` — объект в bucket и его размер; анонимный GET ключа с `127.0.0.1:S3_OUT_PORT` — 403; скачивание участником — тот же SHA-256; `docker diff` каждой реплики — ни одного файла оригинала. Код 1 с названной проверкой, без LB — код 2. Вывод — `evidence/attachments/storage.md` | | `stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]` | спек `graceful-shutdown` «Остановка во время старта»: контейнеры образа (по умолчанию `mtusi-messenger:lab4`) с лимитами реплики (1 CPU / 512 МиБ без swap), без сети и `config.toml`; `docker stop --timeout 10` через паузу после `docker run` и сразу по строке «Started server process». По потоку `docker events` и журналу: «сигнал через», время `docker stop`, «выход после сигнала», код выхода, этап (`import` / `server-start` / `running`), кто остановил (`early` / `uvicorn`). Код 0 — каждая попытка с кодом 0 и `docker stop` ≤ 1 с, есть `import`, остановленный ранним обработчиком, и `running`. Проекты compose не трогает, свои контейнеры удаляет по метке `mtusi.stop-at-start`. Вывод — `evidence/failover/stop-at-start.md` | | `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает | | `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` | @@ -150,6 +165,8 @@ python3 $D --port 8080 idle-conns # простаивающие сое python3 $D --port 8080 hang-key # зависшая реплика держит ключ: повтор получает 201 после прерывания транзакции make test_isolated && python3 $D --port 8080 cache-check --require-test-keys # кэш карточки: одно чтение chats на 50, TTL, ключи двух баз python3 $D --port 8080 auth-storage # Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump +python3 $D --port 8080 attachment-failover --mode kill # реплика, принявшая файл, убита: скачивание через другую, тот же SHA-256 +python3 $D --port 8080 attachment-storage # байты только в приватном bucket: схема, ключ, объект, аноним 403, docker diff python3 $D stop-at-start # docker stop стартующей реплики: ~0,06 с и код 0 (раньше 10 с и 137) make bench_failover_quick # отказ каждой реплики под нагрузкой на своём стенде mtusi-bench, ~2 мин make rolling_update # новый код на реплики без простоя: сборка, миграции один раз, по одной: новая UP → старая drain → stop → rm @@ -249,10 +266,10 @@ make lint # ruff; затрагивает и dr Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none` у `flow`, smoke — `PASS: lab4 public API scenario...`, student — все прошли (тесты `fault` — `deselected`), `All checks passed!`; `all`, -`test_isolated` и `failure_checks` — код 0. **До change `attachments`** -smoke (загрузка вложения) и тесты со схемой `Message` (контракт лабы 4 -требует `attachment_ids`) красные — список в `tasks.md` change -`s3-storage`. +`test_isolated` и `failure_checks` — код 0. Пока файлы `evidence/`, на +которые ссылаются исключения сверки покрытия, не сняты на стенде лабы +(AGENTS.md, «Переход в следующую лабу»), красный только +`test_exclusion_evidence_exists` — он называет сценарий и путь. Проверки отказов (`student-tests/test_failures.py`, маркер `fault`) останавливают и замораживают Postgres, Valkey и S3, поэтому идут только на @@ -323,6 +340,17 @@ smoke (загрузка вложения) и тесты со схемой `Messa без `Idempotency-Key` получит 400, а не 404. Порядок 401 → 400 → 404 → 409 — штатный для FastAPI (`api-contract.md`). Ключ в журнал сервера не пишется: повтор виден по `"replayed": true` и `message_id`. +- **Ранний 413 на большой загрузке `urllib` напрямую к процессу + теряет.** API отвечает 413 (и 404, 415), не дочитывая тело; uvicorn + закрывает соединение, а `urllib` всё ещё пишет тело и получает + `BrokenPipe` / `ConnectionReset` вместо ответа. Через LB ответ + доходит (HAProxy дочитывает тело сам), httpx и `curl` получают его и + напрямую. Поэтому `driver.py upload` большие тела проверять через + `--port 8080`, а в консоли — `curl -H 'Content-Type: image/png' + --data-binary @big.png`. +- **Скачивание через LB может прийти не от той реплики, что загрузку** + — это и есть проверка «байты не на диске API»: оригинал отдаёт любая + реплика из S3. `X-Instance-Id` ответа загрузки — у `upload`. - **`X-Instance-Id` в консоли — hostname машины**, в контейнере — короткий ID контейнера (начало `docker compose ps -q api`, по нему `scripts/stop-one.sh` находит реплику). Другое значение — diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index 6ec18746..361f56a1 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -68,6 +68,24 @@ сигнала и выхода, код выхода, этап старта, кто остановил (ранний обработчик или uvicorn); код 1, если стартующий контейнер останавливается дольше 1 с или не с кодом 0 + 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: спек + attachments «Принявшая реплика остановлена» — загрузка + tests/fixtures/sample.png через LB, сообщение со ссылкой, + scripts/stop-one.sh реплики, принявшей файл, скачивание Бобом + через другую реплику (SHA-256 совпадает), 404 Еве; в finally + — make replicas; docker compose ps до и после, таблица без + токенов; код 1 при расхождении, без LB — код 2 + attachment-storage только стенд с LB: спек attachments «Байты не в + БД и не на диске API» — колонки таблиц вложений (байты — только + 32-байтный SHA-256), object_key вида <база>/attachments// + original без filename, объект в bucket (weed shell), анонимный + GET ключа с хоста — 403, docker diff реплик без файлов + оригиналов; код 1 при расхождении, без LB — код 2 stop остановить свой экземпляр на порту all start → flow → smoke → student (если есть student-tests/) → stop @@ -103,6 +121,7 @@ import sys import threading import time import urllib.error +import urllib.parse import urllib.request import uuid from collections import Counter @@ -571,6 +590,65 @@ def cmd_flow(port: int) -> int: listed = [item["id"] for item in chats["items"]] flow.check("bob sees the chat", chat["id"] in listed) + # вложения (лаба 4): загрузка fixture, сообщение со ссылкой, оригинал + # Бобу побайтно, 404 Еве + data = FIXTURE_PNG.read_bytes() + status, hdrs, attachment = upload_bytes( + port, + alice, + chat["id"], + data, + content_type="image/png", + filename=FIXTURE_PNG.name, + ) + uploaded = status == 201 and isinstance(attachment, dict) + flow.check( + f"POST {CHATS}/…/attachments -> 201 (upload fixture)", + uploaded and attachment.get("sha256") == sha256_hex(data), + f"{status} {hdrs.get('x-instance-id')}", + ) + if uploaded: + attachment_path = f"{ATTACHMENTS}/{attachment['id']}" + with_file = flow.expect( + "message with attachment", + "POST", + msgs, + 201, + token=alice, + body={"text": "", "attachment_ids": [attachment["id"]]}, + extra=key_header(), + ) + flow.check( + "attachment_ids in message", + isinstance(with_file, dict) + and with_file.get("attachment_ids") == [attachment["id"]], + ) + status, hdrs, payload = call_bytes( + port, + "GET", + f"{attachment_path}/content", + token=bob, + ) + flow.check( + f"GET {ATTACHMENTS}/…/content -> 200 (bob, same sha256)", + status == 200 and sha256_hex(payload) == sha256_hex(data), + f"{status} {hdrs.get('content-type')} {len(payload)} bytes", + ) + flow.expect( + "outsider metadata", + "GET", + attachment_path, + 404, + token=eve, + ) + flow.expect( + "outsider content", + "GET", + f"{attachment_path}/content", + 404, + token=eve, + ) + flow.expect("logout", "DELETE", f"{SESSIONS}/current", 204, token=eve) flow.expect( "token after logout", @@ -1868,6 +1946,493 @@ def cmd_s3_check() -> int: return 0 +# вложения (лаба 4): публичный fixture и пути API +FIXTURE_PNG = ROOT / "tests" / "fixtures" / "sample.png" +ATTACHMENTS = "/api/v1/attachments" +PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n" +JPEG_SIGNATURE = b"\xff\xd8\xff" +# сколько раз скачивать через LB после остановки реплики: первые запросы +# может принять слот остановленной, пока LB её не исключил +FAILOVER_ATTEMPTS = 30 +FAILOVER_PAUSE_S = 0.5 +# сколько ждать, пока LB снова пометит вернувшуюся реплику UP +LB_UP_WAIT_S = 20 +# ключ объекта: <база>/attachments//original (design change +# attachments, решение 4) +ATTACHMENT_KEY_PREFIX = "attachments" +ATTACHMENT_ORIGINAL = "original" + + +def call_bytes( + port: int, + method: str, + path: str, + *, + token: str | None = None, + data: bytes | None = None, + content_type: str | None = None, + timeout: float = 30, +) -> tuple[int, dict[str, str], bytes]: + """Запрос с сырыми байтами в теле или ответе (загрузка, скачивание). + + `urllib` напрямую к одной реплике ранний 413 на большом теле теряет + (обрыв при отправке): через LB ответ доходит (SKILL.md, Gotchas). + """ + headers = {} + if token is not None: + headers["Authorization"] = f"Bearer {token}" + if content_type is not None: + headers["Content-Type"] = content_type + request = urllib.request.Request( + base_url(port) + path, + data=data, + method=method, + headers=headers, + ) + try: + with urllib.request.urlopen(request, timeout=timeout) as response: + status, hdrs = response.status, dict(response.headers) + payload = response.read() + except urllib.error.HTTPError as error: + status, hdrs, payload = error.code, dict(error.headers), error.read() + return status, {k.lower(): v for k, v in hdrs.items()}, payload + + +def image_type(data: bytes) -> str: + if data.startswith(PNG_SIGNATURE): + return "image/png" + if data.startswith(JPEG_SIGNATURE): + return "image/jpeg" + return "application/octet-stream" + + +def upload_bytes( + port: int, + token: str, + chat_id: str, + data: bytes, + *, + content_type: str, + filename: str, +) -> tuple[int, dict[str, str], object]: + query = urllib.parse.urlencode({"filename": filename}) + status, hdrs, payload = call_bytes( + port, + "POST", + f"{CHATS}/{chat_id}/attachments?{query}", + token=token, + data=data, + content_type=content_type, + ) + try: + parsed: object = json.loads(payload) if payload else None + except json.JSONDecodeError: + parsed = payload.decode(errors="replace") + return status, hdrs, parsed + + +def sha256_hex(data: bytes) -> str: + return hashlib.sha256(data).hexdigest() + + +def cmd_upload(port: int, args: argparse.Namespace) -> int: + """Загрузка файла: статус, `X-Instance-Id`, тело, SHA-256 файла.""" + data = Path(args.file).read_bytes() + content_type = args.type or image_type(data) + status, hdrs, payload = upload_bytes( + port, + args.token, + args.chat, + data, + content_type=content_type, + filename=args.filename or Path(args.file).name, + ) + print(status, "x-instance-id:", hdrs.get("x-instance-id")) + print(json.dumps(payload, ensure_ascii=False, indent=2)) + print(f"file: {len(data)} bytes, sha256 {sha256_hex(data)}") + if status == 201 and isinstance(payload, dict): + print("sha256 matches:", payload.get("sha256") == sha256_hex(data)) + return 0 if status < 400 else 2 + + +def cmd_download(port: int, args: argparse.Namespace) -> int: + """Скачивание оригинала: статус, тип, размер, SHA-256 полученного.""" + path = f"{ATTACHMENTS}/{args.attachment}/content" + if args.variant is not None: + path += "?" + urllib.parse.urlencode({"variant": args.variant}) + status, hdrs, payload = call_bytes(port, "GET", path, token=args.token) + print( + status, + "x-instance-id:", + hdrs.get("x-instance-id"), + "content-type:", + hdrs.get("content-type"), + "content-length:", + hdrs.get("content-length"), + ) + if status != 200: + print(payload.decode(errors="replace")) + return 2 + print(f"received: {len(payload)} bytes, sha256 {sha256_hex(payload)}") + if args.out: + Path(args.out).write_bytes(payload) + print(f"saved to {args.out}") + return 0 + + +def attachment_people( + port: int, + tag: str, +) -> tuple[dict[str, str], dict[str, str], str] | None: + """Синтетические Алиса, Боб, Ева и чат Алисы и Боба: (id, токены, + id чата). Пароли и токены не печатаются.""" + ids: dict[str, str] = {} + tokens: dict[str, str] = {} + for name in ("alice", "bob", "eve"): + made = synthetic_user(port, f"{tag}{name}", f"Pw-{uuid.uuid4().hex}") + if made is None: + return None + ids[name], tokens[name] = str(made[0]["id"]), made[1] + status, _, chat = call( + port, + "POST", + CHATS, + token=tokens["alice"], + body={ + "title": "attachments", + "member_ids": [ids["alice"], ids["bob"]], + }, + ) + if status != 201 or not isinstance(chat, dict): + print(f"create chat: {status}") + return None + return ids, tokens, str(chat["id"]) + + +def compose_ps() -> str: + return compose( + "ps", + "--format", + "table {{.Name}}\t{{.Status}}", + ).strip() + + +def cmd_attachment_failover(port: int, mode: str) -> int: + """Спек `attachments`, «Принявшая реплика остановлена» (design change + `attachments`, решение 13): загрузка через LB, `scripts/stop-one.sh` + реплики, принявшей файл, скачивание через другую с тем же SHA-256, + 404 постороннему; в `finally` — `make replicas`.""" + if no_lb(port): + print("attachment-failover needs the stand with the load balancer") + return 2 + data = FIXTURE_PNG.read_bytes() + print(f"mode: {mode}; fixture {FIXTURE_PNG.name}: {len(data)} bytes") + print("docker compose ps (before):") + print(compose_ps()) + people = attachment_people(port, "af") + if people is None: + return 1 + _, tokens, chat_id = people + rows: list[tuple[str, str, str, str]] = [] + problems: list[str] = [] + status, hdrs, attachment = upload_bytes( + port, + tokens["alice"], + chat_id, + data, + content_type="image/png", + filename=FIXTURE_PNG.name, + ) + accepted_by = hdrs.get("x-instance-id", "") + rows.append(("alice uploads", "201", str(status), accepted_by)) + if status != 201 or not isinstance(attachment, dict): + print(f"FAIL: upload {status}") + return 1 + attachment_id = str(attachment["id"]) + uploaded_sha = str(attachment["sha256"]) + status, hdrs, message = call( + port, + "POST", + f"{CHATS}/{chat_id}/messages", + token=tokens["alice"], + body={"text": "", "attachment_ids": [attachment_id]}, + extra=key_header(), + ) + rows.append( + ( + "alice sends message", + "201", + str(status), + hdrs.get("x-instance-id", ""), + ), + ) + try: + hook = subprocess.run( + [str(ROOT / "scripts" / "stop-one.sh")], + cwd=ROOT, + env=os.environ + | {"TARGET_INSTANCE_ID": accepted_by, "STOP_MODE": mode}, + capture_output=True, + text=True, + check=False, + ) + rows.append( + ("stop-one.sh " + mode, "0", str(hook.returncode), accepted_by), + ) + downloaded = b"" + served_by = "" + meta_status = 0 + for _ in range(FAILOVER_ATTEMPTS): + status, hdrs, payload = call_bytes( + port, + "GET", + f"{ATTACHMENTS}/{attachment_id}/content", + token=tokens["bob"], + ) + if status == 200: + downloaded, served_by = payload, hdrs.get("x-instance-id", "") + break + time.sleep(FAILOVER_PAUSE_S) + rows.append(("bob downloads", "200", str(status), served_by)) + meta_status, hdrs, meta = call( + port, + "GET", + f"{ATTACHMENTS}/{attachment_id}", + token=tokens["bob"], + ) + rows.append( + ( + "bob reads metadata", + "200", + str(meta_status), + hdrs.get("x-instance-id", ""), + ), + ) + for label, path in ( + ("eve reads metadata", f"{ATTACHMENTS}/{attachment_id}"), + ("eve downloads", f"{ATTACHMENTS}/{attachment_id}/content"), + ): + status, hdrs, _ = call_bytes( + port, + "GET", + path, + token=tokens["eve"], + ) + rows.append( + (label, "404", str(status), hdrs.get("x-instance-id", "")), + ) + if hook.returncode != 0: + problems.append(f"stop-one.sh: {hook.stderr.strip()}") + if served_by in ("", accepted_by): + problems.append("download was not served by another replica") + print(f"sha256 uploaded: {uploaded_sha}") + print(f"sha256 downloaded: {sha256_hex(downloaded)}") + if sha256_hex(downloaded) != uploaded_sha: + problems.append("sha256 of the downloaded original differs") + if isinstance(meta, dict) and meta != attachment: + problems.append("metadata differs from the upload response") + finally: + restore = subprocess.run( + ["make", "replicas"], + cwd=ROOT, + capture_output=True, + text=True, + check=False, + ) + rows.append(("make replicas", "0", str(restore.returncode), "")) + print("docker compose ps (after):") + print(compose_ps()) + # make replicas ждёт healthy контейнера, а LB видит его по своим + # проверкам на секунды позже + replicas = len(compose("ps", "-q", "--status", "running", "api").split()) + deadline = time.monotonic() + LB_UP_WAIT_S + up = 0 + while time.monotonic() < deadline: + up = sum(1 for slot in lb_slots() if slot.get("status") == "UP") + if up >= replicas: + break + time.sleep(FAILOVER_PAUSE_S) + rows.append(("LB slots UP", str(replicas), str(up), "")) + width = max(len(step) for step, _, _, _ in rows) + print(f"{'step':<{width}} expected got x-instance-id") + failed = 0 + for step, expected, got, instance in rows: + ok = expected == got + failed += not ok + print( + f"{step:<{width}} {expected:<8} {got:<4} {instance}" + + ("" if ok else " FAIL"), + ) + for problem in problems: + print(f"FAIL: {problem}") + if failed or problems: + return 1 + print( + f"PASS: accepted by {accepted_by}, served by {served_by} after " + f"{mode}, sha256 matches, outsider gets 404", + ) + return 0 + + +def cmd_attachment_storage(port: int) -> int: + """Спек `attachments`, «Байты не в БД и не на диске API» (design change + `attachments`, решение 13): колонки таблиц вложений, вид + `object_key`, объект в bucket, анонимный GET — 403, `docker diff` + реплик без файлов оригиналов.""" + if no_lb(port): + print("attachment-storage needs the stand with the load balancer") + return 2 + try: + stand = s3_stand() + config = json.loads(compose("config", "--format", "json")) + database = str( + config["services"]["api"]["environment"]["DATABASE__NAME"], + ) + except (RuntimeError, KeyError, StopIteration, ValueError) as e: + print(f"FAIL: compose config of the stand: {e}") + return 1 + people = attachment_people(port, "as") + if people is None: + return 1 + _, tokens, chat_id = people + data = FIXTURE_PNG.read_bytes() + uploads = [] + for number in range(2): + filename = f"storage-check-{uuid.uuid4().hex[:8]}-{number}.png" + status, hdrs, attachment = upload_bytes( + port, + tokens["alice"], + chat_id, + data, + content_type="image/png", + filename=filename, + ) + if status != 201 or not isinstance(attachment, dict): + print(f"FAIL: upload {status}") + return 1 + uploads.append((attachment, filename, hdrs.get("x-instance-id", ""))) + rows: list[tuple[str, str, str]] = [] + columns = stand_psql( + "SELECT table_name, column_name, data_type " + "FROM information_schema.columns WHERE table_schema = 'public' " + "AND table_name IN ('attachments', 'message_attachments') " + "ORDER BY table_name, ordinal_position;\n", + ).splitlines() + print("columns of attachment tables:") + for line in columns: + print(" " + line.replace("|", " ")) + binary = [ + line.split("|")[1] for line in columns if line.endswith("|bytea") + ] + rows.append(("bytea columns", "sha256", ",".join(binary) or "-")) + # id — UUID ответа API: безопасны в тексте SQL + ids = ", ".join(f"'{a['id']}'" for a, _, _ in uploads) + sha_length = stand_psql( + "SELECT coalesce(max(octet_length(sha256)), 0) FROM attachments " + f"WHERE id IN ({ids});\n", + ).strip() + rows.append(("octet_length(sha256)", "32", sha_length)) + keys = dict( + line.split("|") + for line in stand_psql( + f"SELECT id, object_key FROM attachments WHERE id IN ({ids});\n", + ).splitlines() + ) + for attachment, filename, instance in uploads: + attachment_id = str(attachment["id"]) + key = keys.get(attachment_id, "") + expected = "/".join( + ( + database, + ATTACHMENT_KEY_PREFIX, + attachment_id, + ATTACHMENT_ORIGINAL, + ), + ) + print(f"upload via {instance}: object_key {key}") + rows.append(("object_key form", expected, key)) + rows.append( + ("filename not in key", "no", "yes" if filename in key else "no"), + ) + listing = weed_shell( + f"fs.ls -l /buckets/{stand['bucket']}/{database}/" + f"{ATTACHMENT_KEY_PREFIX}/{attachment_id}", + ) + # «-rw-rw---- 1 seaweed seaweed <размер> <полный путь>» + sizes = [ + parts[-2] + for parts in (line.split() for line in listing.splitlines()) + if len(parts) > 2 + and parts[-1] == f"/buckets/{stand['bucket']}/{key}" + ] + rows.append( + ( + "object in bucket, bytes", + str(attachment["size_bytes"]), + sizes[0] if sizes else "missing", + ), + ) + url = f"http://127.0.0.1:{stand['out_port']}/{stand['bucket']}/{key}" + rows.append(("anonymous GET of the key", "403", anonymous_code(url))) + status, _, payload = call_bytes( + port, + "GET", + f"{ATTACHMENTS}/{attachment_id}/content", + token=tokens["bob"], + ) + print( + f" sha256 uploaded {attachment['sha256']}, downloaded by a " + f"member ({status}) {sha256_hex(payload)}", + ) + rows.append( + ( + "downloaded sha256 = uploaded", + "yes", + "yes" if sha256_hex(payload) == attachment["sha256"] else "no", + ), + ) + replicas = compose("ps", "-q", "api").split() + for container in replicas: + diff = subprocess.run( + ["docker", "diff", container], + capture_output=True, + text=True, + check=False, + ).stdout.splitlines() + suspicious = [ + line + for line in diff + if any( + str(a["id"]) in line or name in line for a, name, _ in uploads + ) + or line.lower().endswith((".png", ".jpg", ".jpeg", "/original")) + ] + print(f"docker diff {container[:12]}: {len(diff)} changes") + for line in diff: + print(" " + line) + rows.append( + (f"original files in {container[:12]}", "0", str(len(suspicious))), + ) + width = max(len(check) for check, _, _ in rows) + failed = 0 + for check, expected, got in rows: + ok = expected == got + failed += not ok + print( + f"{check:<{width}} expected {expected} got {got}" + + ("" if ok else " FAIL"), + ) + print(f"sha256 of the fixture: {sha256_hex(data)}") + if failed: + print(f"FAIL: {failed} check(s) failed") + return 1 + print( + "PASS: metadata in PostgreSQL, bytes only in the private bucket " + f"{stand['bucket']}, none in the API containers", + ) + return 0 + + # stop-at-start: записи журнала, по которым видны этапы старта и остановки STARTED_SERVER = "Started server process" SERVER_RUNNING = "Uvicorn running on" @@ -2233,6 +2798,23 @@ def main() -> int: ) sub.add_parser("auth-storage") sub.add_parser("s3-check") + upload = sub.add_parser("upload") + upload.add_argument("--token", required=True) + upload.add_argument("--chat", required=True) + upload.add_argument("--file", required=True) + upload.add_argument( + "--type", + help="Content-Type; по умолчанию — по сигнатуре", + ) + upload.add_argument("--filename", help="по умолчанию — имя файла") + download = sub.add_parser("download") + download.add_argument("--token", required=True) + download.add_argument("--attachment", required=True) + download.add_argument("--out", help="сохранить полученные байты") + download.add_argument("--variant") + failover = sub.add_parser("attachment-failover") + failover.add_argument("--mode", choices=("stop", "kill"), default="stop") + sub.add_parser("attachment-storage") stop = sub.add_parser("stop-at-start") stop.add_argument("--image", default="mtusi-messenger:lab4") stop.add_argument( @@ -2305,6 +2887,14 @@ def main() -> int: return cmd_auth_storage(port) if args.cmd == "s3-check": return cmd_s3_check() + if args.cmd == "upload": + return cmd_upload(port, args) + if args.cmd == "download": + return cmd_download(port, args) + if args.cmd == "attachment-failover": + return cmd_attachment_failover(port, args.mode) + if args.cmd == "attachment-storage": + return cmd_attachment_storage(port) if args.cmd == "stop-at-start": return cmd_stop_at_start( args.image, diff --git a/AGENTS.md b/AGENTS.md index 85a4d31e..d4b9ff47 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,8 +11,10 @@ S3-совместимое хранилище и вложения-изображ `solution/bvt2301-safronov`, commit `ce89eba`) по разделу «Переход в следующую лабу». S3 в стенде — change `s3-storage` (заархивирован 2026-10-20, `openspec/changes/archive/2026-10-20-s3-storage/`): -SeaweedFS с приватным bucket, bootstrap и клиент `src/infra/s3/`; -вложений (ручек, `attachment_ids`) ещё нет. План работ, решения и +SeaweedFS с приватным bucket, bootstrap и клиент `src/infra/s3/`. +Вложения — change `attachments` (активный): ручки загрузки, метаданных +и скачивания, структурная проверка PNG/JPEG, `attachment_ids` в +сообщениях, таблицы `attachments` и `message_attachments`. План работ, решения и трек «5» — `PLAN.md`. Из лабы 2: PostgreSQL как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш карточек чатов. Из лабы 3: HAProxy перед ≥2 репликами API @@ -25,9 +27,10 @@ SeaweedFS с приватным bucket, bootstrap и клиент `src/infra/s3/ `rollout`, серии трека 1 лабы 3 (`scaling-bench`, `scaling-improvement`, `profile-resources`). Changes лаб 2 и 3 и `s3-storage` лабы 4 — в `openspec/changes/archive/`, спеки синхронизированы (с `s3-storage` — -новая capability `object-storage`), активных changes нет; в -`KNOWN_ISSUES.md` две открытые записи (профиль `rollout`, bootstrap -после удаления bucket). Отчёт, evidence и рабочий план лабы 3 остались в её +новая capability `object-storage`); дельты активного `attachments` +уже синхронизированы в основные спеки (новая capability `attachments`); +в `KNOWN_ISSUES.md` две открытые записи (гонка переключения API в +профиле `restore`, bootstrap после удаления bucket). Отчёт, evidence и рабочий план лабы 3 остались в её репозитории (`REPORT.md`, `evidence/`, `git show 063eedb:PLAN.md`). Стек: Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore @@ -136,6 +139,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore |---|---|---| | 2026-09-26 | Лабы можно делать на FastAPI, несмотря на расхождения с контрактом (лишний 422, другой порядок кодов ошибок). Публичный smoke при этом должен проходить | `.claude/rules/api-contract.md`, раздел «FastAPI» | | 2026-09-29 | Конфиг через pydantic-settings: окружение → `.env` → `config.toml` → дефолты. `config.toml` не в git и не в образе, монтируется read-only при запуске. Это подходит под «конфигурация приходит из окружения» (README лабы 1, п. 3) и п. 6 `Dockerfile.example`. Требование «только env» — упрощение курса, `config.toml` можно использовать | `.claude/rules/settings.md`, `.claude/rules/docker.md` | +| 2026-10-20 | Лаба 4: «пустой текст» сообщения — это и `""`, и текст только из пробельных символов. Допустимы: вложение + непустой текст, без вложения + непустой текст, вложение + пустой текст. Значит, `" "` с хотя бы одним вложением — 201, без вложений — 400 | спек `messages` (change `attachments`, сценарий «Пробелы с вложением»), design `attachments`, решение 8; `.claude/rules/api-contract.md` | ## Задание и контракт: важные файлы @@ -145,7 +149,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `PLAN.md` | наш план лабы 4 на «5»: рубрика → change, ключевые решения (S3-сервер, порядок записи, память), трек 2, порядок changes, риски; удаляется, когда все changes закрыты | | `COURSE.md` | карта семи лаб, три объявленных перехода API (1→2, 2→3, 4→5), правила честных измерений | | `contracts/openapi.json` | нормативный OpenAPI 3.1: пути, схемы, коды ответов | -| `contracts/README.md` | нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв, с lab3 — `Idempotency-Key` и `X-Instance-Id`, с lab4 — вложения: сырые bytes PNG/JPEG ≤10 MiB и ≤40 млн пикселей, `201 Attachment` (`ready`), `attachment_ids` в сообщении, download только участникам; разделы lab5+ — на будущее | +| `contracts/README.md` | нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв, с lab3 — `Idempotency-Key` и `X-Instance-Id`, с lab4 — вложения: сырые bytes PNG/JPEG ≤10 MiB и ≤40 млн пикселей, `201 Attachment` (`ready`), `attachment_ids` в сообщении, download только участникам; пустой текст (в том числе из пробелов) — только с вложением (согласование 2026-10-20); разделы lab5+ — на будущее; как это сделано — `api-contract.md`, «Вложения (лаба 4)» | | `contracts/examples.json`, `infrastructure.json` | примеры тел (проверяет `make validate`); роли инфраструктуры лабы: api ×2+ без локального состояния, postgres, load_balancer, s3 (одно из MinIO, SeaweedFS, RustFS; приватный bucket, persistent volume); Redis/Valkey — необязательно; внутренние порты реплик в обход LB не публикуются | | `lab.json` | номер лабы (4); по нему `tests/client.py` выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer; с лабы 3 — идемпотентность; с лабы 4 — вложение, 201 вместо 202 с лабы 5) | | `tests/smoke.py`, `tests/client.py` | публичный сквозной сценарий `make test`; с лабы 4 — загрузка `tests/fixtures/sample.png`, сообщение с `attachment_ids`, SHA-256 скачанного оригинала, 404 постороннему; что он проверяет и чего нет — `tests/README.md` | @@ -287,6 +291,9 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `make logs` | журнал всех реплик API, каждая строка — JSON (`--no-log-prefix`), реплика — поле `instance_id` | | `make replicas [API_REPLICAS=N]` | вернуть остановленные реплики (те же ID) и выставить их число, ждать `healthy` (`balancer.md`) | | `make instances` | вход одним синтетическим пользователем, 12 × `GET /users/me` через LB: `X-Instance-Id` каждого ответа и итог по репликам | +| `driver.py upload` / `download` | загрузка файла и скачивание оригинала с SHA-256 на любом сервере (`.claude/skills/run-mtusi-messenger/SKILL.md`) | +| `driver.py --port attachment-failover [--mode stop\|kill]` | вложение через LB, `stop-one.sh` принявшей реплики, скачивание через другую (тот же SHA-256), 404 постороннему, затем `make replicas`; доказательство исключения `attachments` «Принявшая реплика остановлена» | +| `driver.py --port attachment-storage` | схема таблиц вложений, вид `object_key`, объект в bucket, анонимный GET — 403, `docker diff` реплик; доказательство исключения «Байты не в БД и не на диске API» | | `make lb_stats` | слоты HAProxy: адрес, состояние проверки (`DRAIN`, `MAINT` при замене), запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB) | | `make rolling_update [COMMIT=...] [MIGRATE=0]` | поочерёдная замена реплик без простоя (`scripts/rolling-update.sh`, `balancer.md`): сборка из рабочего дерева (или файлов `COMMIT` через `git archive`), миграции один раз, затем по одной — новая `healthy` и `UP` в LB, старая `drain` → запросов в полёте 0 → `maint` → stop → rm → слот `ready`. Нужен штатный стенд (`make replicas`) без слотов LB в ручном `drain` / `maint` (иначе код 2 и команда `set server … state ready`); сбой и Ctrl+C — `API_REPLICAS` готовых реплик, повтор доводит; `MIGRATE=0` — откат на прежний образ (после него `docker compose up` без сборки не запускать: `migrate` прежнего образа упадёт на новой ревизии) | | `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` | @@ -305,7 +312,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `make bench_restore_quick` | то же на 1k / 5k / 10k (~1,5 мин), метка `quick-restore-<время>`, в git не идёт; сценарий защиты трека 2 | | `make bench_failover [FAILOVER_LABEL=...]` | уровень 4, отказ реплик под нагрузкой (~6 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` с HAProxy и двумя репликами с лимитами рабочего стенда, k6 — 100 записей с ключом и 100 чтений в секунду; каждая реплика в режимах `stop`, `kill`, `pause` с возвратом. Посекундная шкала, время исключения из LB и восстановления, сверка записей после повтора с тем же ключом, CPU и память каждого компонента по окнам фазы (сэмплер `scan`, `resources.csv`, `samples.csv`; CPU на запрос — только до действия) — `evidence/failover/<метка>/`. Перед запуском — проверка хоста (`bench.md`): питание, давление памяти, `Swapouts` без роста; сумма лимитов на пике больше CPU ВМ — код 2 | | `make bench_failover_quick` | то же короче, режимы `stop` и `kill` (~2 мин), с ресурсами, метка `quick-failover-<время>`, в git не идёт | -| `make bench_rollout [ROLLOUT_LABEL=...]` | уровень 4, поочерёдная замена под нагрузкой (~3 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` как у `bench_failover`, реплики на образе прежнего commit (`Profile.rollout_from`, `git archive`; сейчас commit лабы 3, которого здесь нет — `KNOWN_ISSUES.md`, обход `--from`), та же нагрузка; посреди неё `scripts/rolling-update.sh` меняет их на образ текущего checkout. Посекундная шкала с ответами старых и новых реплик, шаги по репликам, контейнеры, образы и ревизия до и после, сверка записей, CPU и память каждой старой и новой реплики, миграции и остальных компонентов по окнам до / подготовка / замена / после (CPU на запрос — до и после) — `evidence/rollout/<метка>/`. Перед запуском — проверка хоста (`bench.md`) | +| `make bench_rollout [ROLLOUT_LABEL=...]` | уровень 4, поочерёдная замена под нагрузкой (~3 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` как у `bench_failover`, реплики на образе прежнего commit (`Profile.rollout_from`, `git archive`; сейчас `e1161f7` — последний до change `attachments`, правило выбора — `bench.md`; commit вне истории — код 2 до стенда, отладка `--from`), та же нагрузка; посреди неё `scripts/rolling-update.sh` меняет их на образ текущего checkout. Посекундная шкала с ответами старых и новых реплик, шаги по репликам, контейнеры, образы и ревизия до и после, сверка записей, CPU и память каждой старой и новой реплики, миграции и остальных компонентов по окнам до / подготовка / замена / после (CPU на запрос — до и после) — `evidence/rollout/<метка>/`. Перед запуском — проверка хоста (`bench.md`) | | `make bench_rollout_quick` | то же с короткими окнами (~2 мин), с ресурсами, метка `quick-rollout-<время>`, в git не идёт | | `make bench_scaling SERIES=a\|b\|pool\|ab\|db\|db4 [SCALING_LABEL=...] [RESUME=1]` | уровень 5, трек 1: серия на стенде `mtusi-bench` (метка `scaling-<серия>` по умолчанию). `a` — бюджет 4 CPU: 1 × 4, 2 × 2, 4 × 1 (~50 мин); `b` — 1…6 реплик по 1 CPU (~100 мин); `pool` — 4 реплики при `max_connections` 100 и 50 (~35 мин); `ab` — 1 × 1 и 6 × 1 для «до/после» и A/A (~35 мин); `db` — 1, 2, 4 реплики при PostgreSQL 0,5 CPU и контроль 4 × 1 при 2 CPU (~50 мин); `db4` — только 4 × 1 при 0,5 и 2 CPU (~25 мин, «до/после» `scaling-improvement`); `db_quick` — самопроверка серии `db` (~4 мин, метка `quick-*`). Ячейка — конфигурация × повтор (3), свежий стенд; открытая модель 70/20/10, фиксированные 250 и 500/с и поиск R* по SLO; сэмплер контейнеров, ВМ, LB и PostgreSQL. `RESUME=1` — продолжить прерванную метку на том же commit. Перед запуском — проверка хоста, рабочий стенд — `make stop`; метку коммитить до следующей серии (`bench.md`) | | `make bench_scaling_quick` | самопроверка серий: 1 × 1 и 2 × 1 при `max_connections` 50, короткие окна (~4 мин), метка `quick-scaling-<время>`, в git не идёт | @@ -331,17 +338,21 @@ src/ config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds api/ routers/health.py # /health/live, /health/ready: вне версии, без идентификации - routers/v1/.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py) - schemas/.py # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12 - dependencies.py # сессия БД, фабрики сервисов (с кэшем), разбор Basic, текущая сессия по Bearer, пагинация + routers/v1/.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra), метаданные, байты StreamingResponse + schemas/.py # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12; attachment.py — DisplayFilename (отказ на / \ Cc и пробелы) и Attachment; message.py — CreateMessage с attachment_ids и валидатором пустого текста + dependencies.py # db_session_scope (сессия на шаг) и get_db_session поверх него, фабрики сервисов (с кэшем; вложения — без сессии запроса), разбор Basic, текущая сессия по Bearer, CurrentUserBrief (вход с короткой сессией), пагинация errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; у 500 — X-Request-Id и X-Instance-Id middlewares/ # X-Request-Id, X-Instance-Id и access-лог core/ repos/.py # атомарный доступ к хранилищу, модульные функции repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO - services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ и сообщение одной транзакцией - exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing + repos/attachment.py # строки вложений: вставка pending, mark_ready (pending → ready RETURNING), чтение одной и до 10 + repos/attachment_object.py # оригинал в S3: ключ <база>/attachments//original, put, open + repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой + services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией + services/attachment.py # AttachmentService(db_scope, cache, storage): загрузка (проверки → тело со счётчиком → структура и SHA-256 в потоке → pending → PUT → ready), метаданные, отдача потоком + exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва, 500 пропавшего объекта infra/ early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped API before startup» и выход 0; disarm() — первая строка lifespan logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи @@ -349,22 +360,25 @@ src/ db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping db/session.py # глобалы engine и session_factory процесса API db/errors.py # is_db_unavailable: какие ошибки драйвера — 503 - db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit + db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit; attachment.py — Attachment и MessageAttachment (порядок position, FK без каскада) cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск cache/instance.py # глобал cache процесса API s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put / head / open (чтение блоками) / delete, срок на вызов и блок, ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo, StoredObject s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan schemas/ dataclasses/.py # DTO между repo → service → api - enums/.py # StrEnum доменов, RunModeEnum + enums/.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType utils/ - constants.py # лимиты контракта, размер страницы, префиксы путей, имя bucket S3, разделитель ключа объекта, keep-alive клиента S3 + constants.py # лимиты контракта (с лабы 4 — 10 MiB, 40 млн пикселей, filename, 10 вложений), размер страницы, префиксы путей, имя bucket S3, разделитель и части ключа объекта, keep-alive клиента S3 + image.py # inspect_image: структурная проверка PNG/JPEG без декодирования пикселей (stdlib), тип, размеры, UnsupportedImage / DamagedImage / TooManyPixels utc.py # utcnow() (aware UTC), формат RFC 3339 с Z cursor.py # непрозрачный keyset-курсор: кодирование и разбор; поля проверяются по отдельности, незнакомые игнорируются, смена формата — новая CURSOR_VERSION student-tests/ # black-box тесты по HTTP (уровень 4): make student_test conftest.py # BASE_URL, EXPECT_REPLICAS и фикстура replicas (пропуск против одного процесса), проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook - api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message — с Idempotency-Key - contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, X-Instance-Id, assert_error, assert_errors (статусы всех вариантов запроса разом), assert_replicas + api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message (с attachment_ids) — с Idempotency-Key; post_attachment/upload, attachment_meta, attachment_content + contract.py # тела по схемам contracts/openapi.json, форматы id, attachment_ids и времени, X-Instance-Id, assert_error (с 413 и 415), assert_errors (статусы всех вариантов запроса разом), assert_content (байты, тип, nosniff, без Location и x-amz-*), assert_replicas + images.py # изображения для тестов: PNG на stdlib (любые IHDR, Adam7, точный размер, бомба, огромные размеры, порча байта), JPEG через Pillow (dev), обрезка и хвост + test_attachments.py # спек attachments: загрузка, лимиты, тип и целостность, filename, доступ, метаданные, оригинал, variant, повтор, другая реплика test_idempotency.py # спек idempotency: ключ, повтор, 409, область, порядок кодов, повтор через другую реплику (гонка — test_race.py, отказы — test_failures.py) test_load_balancing.py # спек load-balancing (вне сверки покрытия): одна сессия на разных репликах, запись видна через другую реплику spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия; missing_evidence — файл evidence по ссылке исключения должен быть в репозитории @@ -373,7 +387,7 @@ student-tests/ # black-box тесты по HTTP (уровень 4) test_failures.py # проверки отказов (маркер fault): только make failure_checks run_isolated.py # make test_isolated: образ на временной базе test_, уборка базы и префикса test_/ в S3 (weed shell fs.rm, затем проверка fs.ls: код 0 weed shell успеха не значит; префикс только из проверенного имени) (stdlib) run_failures.py # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap), два API, pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), уборка (stdlib) - fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников и сообщений, заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions (stdlib) + fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников и сообщений, заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, count-attachments (по статусам) и count-objects (каталоги вложений в bucket) (stdlib) failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, S3, LB), stop_grace_period 2 с у S3, healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster) bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json @@ -400,6 +414,7 @@ Dockerfile # builder (uv sync --locked) → runtime: .venv + s docker-compose.yml # проект mtusi-lab4: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), migrate, s3-bootstrap, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env) .dockerignore config_example.toml, .env.example +evidence/attachments/ # change attachments: smoke.md, failover.md (driver.py attachment-failover stop и kill), storage.md (driver.py attachment-storage), slow-transfer.md (10 MiB через LB дольше 6 с) evidence/s3/ # change s3-storage: bootstrap.md (первый запуск, повтор, смена секрета, ошибка шага, до bootstrap), privacy.md (make s3_check, нарушение и исправление, порты, секреты по сервисам), grpc-admin.md (gRPC шлюза без токена), restart.md (restart.sh и SIGKILL S3), client.md (операции, pause/stop, неверный секрет, журнал), memory.md (20 × 10 MiB PUT) evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга evidence/migrations/ # миграции с нуля и повторно, ошибка миграции @@ -515,10 +530,17 @@ KNOWN_ISSUES.md # найденные попутно дефекты, test-persistence ACTION_SCRIPT=scripts/restart.sh` → `evidence/replicas/test-persistence.md` (или путь, который назовёт исключение); повтор отправки с ключом после `docker compose up -d - --force-recreate api` → `evidence/idempotency/replay-after-restart.md` + --force-recreate api` → `evidence/idempotency/replay-after-restart.md`; + с лабы 4 ещё `driver.py --port attachment-failover` (оба режима) + → `evidence/attachments/failover.md` и `driver.py --port + attachment-storage` → `evidence/attachments/storage.md` (`student-tests.md`). Файлы `evidence/` этой лабы в новую лабу не - копировать, даже эти четыре: сверка проверяет только наличие файла и - с копией останется зелёной без пересъёмки. + копировать, даже эти: сверка проверяет только наличие файла и с + копией останется зелёной без пересъёмки. +- `Profile.rollout_from` в `bench/run.py` (профили `rollout`, + `rollout_quick`) поменять на commit новой лабы до изменения, которое + должна показать замена: commit этой лабы в истории новой нет, и + команда откажет до стенда (`bench.md`, профиль `rollout`). - Сначала прочитать переходы API в `COURSE.md` и `contracts/README.md` нового skeleton, потом править код. Обновить этот файл: номер лабы, таблицу важных файлов, новые правила. diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index 3cb5cba1..af27725a 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -3,23 +3,30 @@ Найдены попутно, не исправлены без отдельной просьбы (AGENTS.md). Исправленные удаляются отсюда, история — в git. -## Профиль `rollout` ссылается на commit лабы 3 +## `bench_restore_quick`: переключение API на восстановленную базу не ждёт новую реплику -- **Где:** `bench/run.py`, профили `rollout` и `rollout_quick`: - `rollout_from="c50b721"`. -- **Что:** commit `c50b721` — из репозитория лабы 3 - (`mtusi2026lab3-safronov`), в истории лабы 4 его нет. `make - bench_rollout_quick` и `make bench_rollout` падают за 6 с: `git - rev-parse c50b721^{commit}` — «Needed a single revision», exit 128. - Найдено в apply change `s3-storage` (2026-10-20); от S3 не зависит: - код перенесён так в `5d5d8f9`. -- **Обход:** `uv run python bench/run.py --profile rollout_quick --label - quick-rollout-<время> --from 5d5d8f9` — код 0 на рабочем дереве - `s3-storage`. -- **Предложение:** `rollout_from` — последний commit лабы 4 до - измеряемого изменения (сейчас `5d5d8f9`, перенос кода лабы 3), а в - `bench.md` — правило менять его при переходе в следующую лабу - (раздел «Переход в следующую лабу» AGENTS.md). +- **Где:** `bench/run.py`, `Stand.switch_api` → `Stand.wait_ready`. +- **Что:** `switch_api` пересоздаёт реплику (`up -d --no-deps + --force-recreate api`) и ждёт, пока LB видит `UP` слот с адресом + реплики. Новый контейнер получает **тот же IP**, а LB ещё держит слот + этого адреса `UP` от прежнего контейнера: `wait_ready` возвращается + сразу, до старта нового процесса. Затем LB ловит `ECONNREFUSED`, + помечает слот `DOWN` («backend api has no server available»), и k6 + `restore_check.js` получает 503 `` от LB на все запросы фазы + `stale` — «restore check failed: … reader session 503 …». Новый + процесс поднимается через ~0,7 с, но LB возвращает слот только после + двух проверок. Найдено в apply change `attachments` (задача 7.2, + 2026-10-21): `make bench_restore_quick` упал 3 раза из 4 на размере + 10k (1k и 5k прошли), `--sizes 10000` — 2 из 3; журнал LB и реплики + снят во время прогона. К коду вложений не относится: запросы до API не + доходят, а стенд `bench/` S3 не запускает. +- **Чем грозит:** профиль трека 2 `restore*` нестабилен; ложный отказ + стенда, а не приложения. +- **Предложение:** в `switch_api` дождаться, что LB видит слот адреса не + `UP` или что ответ через LB пришёл с `X-Instance-Id` нового контейнера + (например, `GET /health/ready` через LB из сети стенда), и только потом + `wait_ready`; либо сравнивать не адрес, а `check_status`/`lastchg` + слота после времени пересоздания. ## Bootstrap после удаления bucket: «api key put (code 500)» diff --git a/PLAN.md b/PLAN.md index d6ec06aa..4e646c9d 100644 --- a/PLAN.md +++ b/PLAN.md @@ -672,6 +672,23 @@ design) и «Вопросы» (ждут ответа; ответ дописыв 13. **Проверки отказов вложений** — через hook стенда отказов: счётчики вложений по статусам и объектов в bucket (решение 12). +Уточнения apply (2026-10-20/21, design change `attachments`, «Уточнения +apply»): + +14. **Текст из пробелов с вложением — 201** по ответу преподавателя + («Вопросы», п. 2); без вложений — 400. Текст не нормализуется. +15. **Проверка изображения на готовом модуле** повторила пробу: 17 + вариантов, корпус 12 000 файлов без ложных отказов, «бомба» за 1 мс, + пик памяти ≤ 3,2 MiB. Вход IDAT — кусками по 64 KiB. +16. **План истории**: на пустой `message_attachments` стенда `bench/` + `SubPlan` — `Seq Scan` пустой таблицы; с данными — + `pk_message_attachments`, индекс истории прежний. +17. **`variant` в `/openapi.json`** — `enum ["original"]` через + `json_schema_extra`: Literal pydantic пишет `const`. +18. **`bench_restore_quick` нестабилен** из-за гонки стенда (реплика + пересоздаётся с тем же IP, LB держит устаревший `UP`), не из-за + вложений: запись в `KNOWN_ISSUES.md`, исправление — отдельно. + #### Вопросы 1. Что считать «повреждённым изображением» (решение 2, спек @@ -702,11 +719,15 @@ design) и «Вопросы» (ждут ответа; ответ дописыв не из одних пробелов) и 50 (исключение — только `text=""` с вложением). Пользователь спросит преподавателя. - **Открыт — вопрос преподавателю.** Трактовка временная (design change - `attachments`, решение 8). Ответ записать в AGENTS.md, «Согласования с - преподавателем». Если он другой, поправить валидатор `CreateMessage`, - сценарий `messages` «Пробелы с вложением» и его тест. До ответа - трактовка названа в `REPORT.md` как открытый вопрос. + **Ответ преподавателя 2026-10-20 — вопрос закрыт.** «Пустой текст» — + это и `""`, и текст только из пробельных символов. Допустимы: + вложение + непустой текст, без вложения + непустой текст, вложение + + пустой текст. Итог: текст из одних пробелов с хотя бы одним + вложением — 201 (текст сохраняется и возвращается как прислан), без + вложений — 400. Записано в AGENTS.md, «Согласования с + преподавателем»; в apply поправлены валидатор `CreateMessage`, + сценарий `messages` «Пробелы с вложением» и его тест (design change + `attachments`, решение 8), в `REPORT.md` — как согласование. 3. Опасный `filename`. Контракт называет `/`, `\`, NUL и управляющие символы. По умолчанию 400 и на символы управления направлением текста (U+202A–U+202E, U+2066–U+2069) и разделители строк (U+2028, diff --git a/bench/run.py b/bench/run.py index 4dc7ec31..95919065 100644 --- a/bench/run.py +++ b/bench/run.py @@ -481,10 +481,11 @@ PROFILES = { sample_resources=True, ), # поочерёдная замена под нагрузкой (уровень 4): та же нагрузка и - # лимиты, что у failover; реплики стартуют на образе c50b721 — - # последнего commit до change rolling-update (без колонки - # messages.instance_id) — и заменяются на образ текущего checkout. - # Решение 8 design change rolling-update + # лимиты, что у failover; реплики стартуют на образе e1161f7 — + # последнего commit лабы 4 до change attachments (без таблиц вложений + # и с прежним ограничением текста) — и заменяются на образ текущего + # checkout. Решение 8 design change rolling-update, commit — решение + # 14 design change attachments; правило выбора — bench.md "rollout": Profile( name="rollout", sizes=(1_000,), @@ -504,7 +505,7 @@ PROFILES = { replicas=2, failover_write_rate=100, failover_read_rate=100, - rollout_from="c50b721", + rollout_from="e1161f7", rollout_before_s=15, rollout_budget_s=90, rollout_after_s=15, @@ -529,7 +530,7 @@ PROFILES = { replicas=2, failover_write_rate=100, failover_read_rate=100, - rollout_from="c50b721", + rollout_from="e1161f7", rollout_before_s=5, rollout_budget_s=60, rollout_after_s=8, @@ -5649,6 +5650,33 @@ def resume_problems( return found +def rollout_commit_problem(commit: str) -> str | None: + """Commit прежнего образа профиля замены есть в истории; иначе — + сообщение с commit и подменой `--from` (design change `attachments`, + решение 14).""" + found = subprocess.run( + [ + "git", + "-C", + str(ROOT), + "rev-parse", + "--verify", + "--quiet", + f"{commit}^{{commit}}", + ], + capture_output=True, + text=True, + check=False, + ) + if found.returncode == 0: + return None + return ( + f"rollout commit {commit!r} is not in this repository history: " + "update Profile.rollout_from (.claude/rules/bench.md) or pass " + "--from for debugging" + ) + + def apply_overrides( profile: Profile, args: argparse.Namespace, @@ -5700,6 +5728,13 @@ def main(argv: list[str]) -> int: if args.resume and not profile.is_series: print("--resume: track 1 series profiles only", flush=True) return 2 + if profile.is_rollout: + # commit методики — до стенда, а не на шестой секунде сборки + # (спек load-benchmark, «Прежний commit профиля замены») + problem = rollout_commit_problem(profile.rollout_from) + if problem: + print(problem, flush=True) + return 2 # профиль отказа реплик — доказательство уровня 4, рядом с прогонами # make test-failover (решение 7 design change graceful-failover) kind = "failover" if profile.is_failover else "bench" diff --git a/migrations/versions/2026_10_20_2351-ef25d50b01a8_added_attachments_tables.py b/migrations/versions/2026_10_20_2351-ef25d50b01a8_added_attachments_tables.py new file mode 100644 index 00000000..357c172f --- /dev/null +++ b/migrations/versions/2026_10_20_2351-ef25d50b01a8_added_attachments_tables.py @@ -0,0 +1,163 @@ +"""added attachments tables + +Revision ID: ef25d50b01a8 +Revises: e656d6bbe1a4 +Create Date: 2026-10-20 23:51:07.270829 + +""" + +from collections.abc import Sequence + +import sqlalchemy as sa +from alembic import op + +# revision identifiers, used by Alembic. +revision: str = "ef25d50b01a8" +down_revision: str | Sequence[str] | None = "e656d6bbe1a4" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + # expand (design change attachments, решение 3): две новые таблицы и + # ослабленное ограничение текста сообщения. Внешние ключи новых таблиц + # берут блокировку на messages и chat_members, замена CHECK — ACCESS + # EXCLUSIVE на messages: чужая долгая транзакция не должна заставить + # миграцию держать очередь запросов. По сроку — ошибка без изменений + # схемы, повтор проходит; срок меньше statement_timeout приложения (5 с) + op.execute("SET LOCAL lock_timeout = '2s'") + op.create_table( + "attachments", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column("chat_id", sa.Uuid(), nullable=False), + sa.Column("owner_id", sa.Uuid(), nullable=False), + sa.Column("filename", sa.Text(), nullable=False), + sa.Column("content_type", sa.Text(), nullable=False), + sa.Column("size_bytes", sa.Integer(), nullable=False), + sa.Column("sha256", sa.LargeBinary(), nullable=False), + sa.Column("object_key", sa.Text(), nullable=False), + sa.Column("status", sa.Text(), nullable=False), + sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False), + sa.CheckConstraint( + "content_type IN ('image/png', 'image/jpeg')", + name=op.f("ck_attachments_content_type"), + ), + # без `/`, `\` и управляющих символов (категория Cc); внутри + # скобок ARE `\\` — обратная косая, `\uXXXX` — символ + sa.CheckConstraint( + r"filename !~ '[/\\\u0001-\u001f\u007f-\u009f]'", + name=op.f("ck_attachments_filename_chars"), + ), + sa.CheckConstraint( + "status IN ('pending', 'ready')", + name=op.f("ck_attachments_status"), + ), + sa.CheckConstraint( + "char_length(filename) BETWEEN 1 AND 255", + name=op.f("ck_attachments_filename_length"), + ), + sa.CheckConstraint( + "octet_length(object_key) BETWEEN 1 AND 1024", + name=op.f("ck_attachments_object_key_length"), + ), + sa.CheckConstraint( + "octet_length(sha256) = 32", + name=op.f("ck_attachments_sha256_length"), + ), + sa.CheckConstraint( + "size_bytes BETWEEN 1 AND 10485760", + name=op.f("ck_attachments_size_bytes"), + ), + sa.CheckConstraint( + "updated_at >= created_at", + name=op.f("ck_attachments_updated_after_created"), + ), + # владелец — участник чата вложения + sa.ForeignKeyConstraint( + ["chat_id", "owner_id"], + ["chat_members.chat_id", "chat_members.user_id"], + name=op.f("fk_attachments_chat_id_owner_id_chat_members"), + ), + sa.PrimaryKeyConstraint("id", name=op.f("pk_attachments")), + sa.UniqueConstraint( + "object_key", + name=op.f("uq_attachments_object_key"), + ), + ) + op.create_table( + "message_attachments", + sa.Column("message_id", sa.Uuid(), nullable=False), + sa.Column("position", sa.SmallInteger(), nullable=False), + sa.Column("attachment_id", sa.Uuid(), nullable=False), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False), + sa.CheckConstraint( + "position BETWEEN 0 AND 9", + name=op.f("ck_message_attachments_position_range"), + ), + # без ON DELETE: вложение со ссылкой из сообщения не удалить + sa.ForeignKeyConstraint( + ["attachment_id"], + ["attachments.id"], + name=op.f("fk_message_attachments_attachment_id_attachments"), + ), + sa.ForeignKeyConstraint( + ["message_id"], + ["messages.id"], + name=op.f("fk_message_attachments_message_id_messages"), + ), + sa.PrimaryKeyConstraint( + "message_id", + "position", + name=op.f("pk_message_attachments"), + ), + sa.UniqueConstraint( + "message_id", + "attachment_id", + name=op.f("uq_message_attachments_message_id_attachment_id"), + ), + ) + op.create_index( + op.f("ix_message_attachments_attachment_id"), + "message_attachments", + ["attachment_id"], + unique=False, + ) + # ослабление: было 1–4000, стало 0–4000 (пустой текст — только с + # вложением, правило в сервисе). Прежние строки удовлетворяли более + # строгому условию, поэтому NOT VALID: без полного просмотра messages + # под ACCESS EXCLUSIVE. Новые строки NOT VALID проверяет так же. + # VALIDATE вне транзакции (autocommit_block) зафиксировал бы DDL раньше + # alembic_version, и сбой оставил бы неповторяемую миграцию. + # Autogenerate изменение CHECK не видит + # op.f: имя готовое, шаблон имён ограничений к нему не применяется + op.drop_constraint( + op.f("ck_messages_text_length"), + "messages", + type_="check", + ) + op.execute( + "ALTER TABLE messages ADD CONSTRAINT ck_messages_text_length " + "CHECK (char_length(text) <= 4000) NOT VALID", + ) + + +def downgrade() -> None: + # прежнее строгое ограничение — тоже NOT VALID: строки с пустым текстом + # и вложением, записанные новой версией, остаются в таблице + op.execute("SET LOCAL lock_timeout = '2s'") + op.drop_constraint( + op.f("ck_messages_text_length"), + "messages", + type_="check", + ) + op.execute( + "ALTER TABLE messages ADD CONSTRAINT ck_messages_text_length " + "CHECK (char_length(text) BETWEEN 1 AND 4000) NOT VALID", + ) + op.drop_index( + op.f("ix_message_attachments_attachment_id"), + table_name="message_attachments", + ) + op.drop_table("message_attachments") + op.drop_table("attachments") diff --git a/openspec/changes/attachments/design.md b/openspec/changes/attachments/design.md index e8275646..c8024b12 100644 --- a/openspec/changes/attachments/design.md +++ b/openspec/changes/attachments/design.md @@ -439,18 +439,19 @@ VALUE` нельзя использовать в той же транзакции - `text: StrictStr`, до 4000 code points; - `attachment_ids: list[UuidIn]`, по умолчанию `[]`, `max_length` 10; - валидатор модели: повтор id (сравнение `UUID`, регистр не важен) — - 400; текст пустой без вложений или из одних пробелов (непустой) — - 400 (спек `messages`, «Валидация текста»). + 400; пустой текст — `""` или из одних пробельных символов (`not + text.strip()`) — без вложений 400, с хотя бы одним вложением + допустим (спек `messages`, «Валидация текста»). Текст не + обрезается и не нормализуется. - **Трактовка временная — до ответа преподавателя** (`PLAN.md`, - `### attachments` → «Вопросы», п. 2). Текст из одних пробелов вместе с - вложением даёт 400: общее правило контракта (`contracts/README.md`, - строка 9) и исключение только для `text=""` (строка 50). Строка 18 - («нельзя … пробельный текст без вложений») допускает и прочтение «с - вложением можно». Ответ преподавателя пойдёт в AGENTS.md, - «Согласования с преподавателем». Если он другой, меняются условие - валидатора, сценарий `messages` «Пробелы с вложением» и его тест. - Остальное решение от этого не зависит. + **Согласовано с преподавателем 2026-10-20** (AGENTS.md, «Согласования + с преподавателем»; `PLAN.md`, `### attachments` → «Вопросы», п. 2). + Контракт был неоднозначен: общее правило «обязательные строки не из + одних пробелов» (`contracts/README.md`, строка 9) против «нельзя … + пробельный текст без вложений» (строка 18). Ответ: «пустой текст» — + и `""`, и строка из одних пробелов; с вложением он допустим, без + вложений — 400. До ответа действовала временная трактовка «пробелы с + вложением — 400»; её сменила эта. - `MessageService.send_message(..., attachment_ids)`: 1. членство; 2. вложения: `attachment_repo.get_attachments(ids)` — не больше 10 @@ -686,9 +687,9 @@ VALUE` нельзя использовать в той же транзакции - строки уровней «3» и «4» с командой, наблюдением и файлом; - ограничения: структурная проверка, `NOT VALID`, `urllib` напрямую, смешанные версии при замене; -- открытый вопрос преподавателю: текст из одних пробелов с вложением — - пока 400 (решение 8). После ответа — строка в AGENTS.md, «Согласования - с преподавателем», и упоминание в отчёте. +- согласование с преподавателем 2026-10-20: текст из одних пробелов с + вложением — 201, без вложений — 400 (решение 8, AGENTS.md, + «Согласования с преподавателем»). ## Risks / Trade-offs @@ -758,13 +759,54 @@ VALUE` нельзя использовать в той же транзакции мешает. Загруженные вложения остаются в БД и S3 и снова видны после возврата вперёд. +## Уточнения apply + +1. **`src/utils/image.py` на готовом модуле** (задача 1.2, 2026-10-20, + scratchpad, Pillow 13.0.0 через `uv run --no-project --with pillow`): + 17 вариантов приняты (PNG RGB, RGBA, палитра, 1 и 2 бита, LA, 16 + бит, серый, Adam7; JPEG baseline, прогрессивный, с RST, серый, CMYK, + 4:4:4, EXIF); повреждённые из Context — `DamagedImage` (PNG без + последнего байта и без IEND Pillow грузит); хвосты и байт скана JPEG + приняты; SOF 10000 × 5000 и IHDR 40 000 001 — `TooManyPixels`; + «бомба» — 1,0 мс, PNG 1 × 40 млн — 56 мс, 8000 × 5000 RGBA — 27 мс, + JPEG из `FF 00` 10 MiB — 40 мс, пик `tracemalloc` ≤ 3,2 MiB; корпус + 12 000 файлов: 11 964 приняты обоими, 34 отклонены обоими, 2 — только + по лимиту пикселей, ложных отказов 0. Вход IDAT подаётся кусками по + 64 KiB: иначе `unconsumed_tail` копирует остаток большого чанка на + каждом блоке выхода. +2. **План истории** (задача 7.2): на стенде `bench/` таблица + `message_attachments` пуста, и `SubPlan` идёт `Seq Scan` по пустой + таблице (0 страниц) — индекс истории прежний + (`explain-10k.txt` пробной метки). С данными (20 000 сообщений, 40 000 + связей в откатываемой транзакции на рабочей базе) `SubPlan` — `Bitmap + Index Scan on pk_message_attachments`, 51 цикл, страница 0,2 мс. + Решение 8 этим подтверждено; формулировку задачи 7.2 («`SubPlan` по + `pk_message_attachments`») пустая таблица стенда не показывает. +3. **Причины отказа загрузки в журнале** (решение 11): к списку + добавлена `content` — содержимое не PNG и не JPEG (`UnsupportedImage`), + отдельно от `damaged` (структура нарушена) и `content_mismatch` + (тип содержимого не совпал с `Content-Type`). +4. **`variant` в `/openapi.json`**: `Literal["original"]` pydantic пишет + как `const`; `Query(json_schema_extra={"enum": ["original"]})` + добавляет перечисление контракта. +5. **Тест «S3 завис»**: клиент `Api` набора со сроком 5 с обрывал + запрос раньше ответа API (503 через 5,0 с). Тест берёт клиента со + сроком 15 с — дефект теста, не приложения. +6. **Имя ограничения в ревизии**: `drop_constraint` без `op.f(...)` + применял шаблон имён и искал `ck_messages_ck_messages_text_length` + (видно в `upgrade --sql`); исправлено до применения. +7. **Тексты из пробелов с вложением** — ответ преподавателя 2026-10-20 + пришёл во время apply (решение 8): валидатор сразу написан под 201; + «сначала красный» тест на прежнем валидаторе не показывался — прежней + версии с вложениями не было. +8. **`bench_restore_quick`** (задача 7.2) нестабилен из-за гонки стенда, + не кода вложений: `switch_api` пересоздаёт реплику с тем же IP, и + `wait_ready` видит устаревший `UP` слота (`KNOWN_ISSUES.md`). + ## Open Questions -- Текст из одних пробелов вместе с вложением: ответ преподавателя на - неоднозначность контракта (решение 8, `PLAN.md`, «Вопросы», п. 2). - Пользователь отложил вопрос сам: до ответа — 400. Другой ответ меняет - один сценарий `messages`, условие валидатора и тест отдельной правкой. - Порядок работ от него не зависит. +- ~~Текст из одних пробелов вместе с вложением~~ — закрыт 2026-10-20 + ответом преподавателя: 201 с вложением, 400 без (решение 8). - Что API отвечает, когда у строки `ready` нет объекта или он другого размера: сейчас 500 и `error` в журнале (решение 7). Пометку таких строк и ответ после неё решит reconciler трека 2. Спеки этого change diff --git a/openspec/changes/attachments/specs/messages/spec.md b/openspec/changes/attachments/specs/messages/spec.md index 795e3e4c..d9918ce9 100644 --- a/openspec/changes/attachments/specs/messages/spec.md +++ b/openspec/changes/attachments/specs/messages/spec.md @@ -32,11 +32,14 @@ ### Requirement: Валидация текста -`text` SHALL содержать не больше 4000 Unicode code points. Пустая строка -SHALL допускаться только вместе с хотя бы одним вложением. Текст из -одних пробельных символов MUST NOT приниматься ни с вложениями, ни без -них. Поле `sender_id` в теле MUST NOT приниматься. Нарушения SHALL -давать 400 `invalid_request`. +`text` SHALL содержать не больше 4000 Unicode code points. Пустой +текст — пустая строка или строка из одних пробельных символов — SHALL +допускаться только вместе с хотя бы одним вложением, без вложений он MUST +NOT приниматься (согласовано с преподавателем 2026-10-20, AGENTS.md, +«Согласования с преподавателем»). Текст SHALL сохраняться и +возвращаться как прислан, без обрезки и нормализации. Поле `sender_id` +в теле MUST NOT приниматься. Нарушения SHALL давать 400 +`invalid_request`. #### Scenario: Пустой текст @@ -62,7 +65,11 @@ SHALL допускаться только вместе с хотя бы одни #### Scenario: Пробелы с вложением - **WHEN** участник отправляет `{"text": " ", "attachment_ids": [A]}` -- **THEN** ответ 400 `invalid_request`, сообщение не создаётся + с готовым вложением A своего чата, а затем `{"text": " "}` без + вложений +- **THEN** первый ответ 201, `text` — те же три пробела, + `attachment_ids` — `[A]`; второй — 400 `invalid_request`, и это + сообщение не создаётся ### Requirement: История чата diff --git a/openspec/changes/attachments/tasks.md b/openspec/changes/attachments/tasks.md index dd334035..784747a0 100644 --- a/openspec/changes/attachments/tasks.md +++ b/openspec/changes/attachments/tasks.md @@ -12,11 +12,11 @@ Ответы пользователя 2026-10-20 (`PLAN.md`, `### attachments` → «Вопросы»): - п. 1 — структурная проверка изображения; -- п. 2 — текст из одних пробелов с вложением даёт 400. Это временная - трактовка до ответа преподавателя (design, решение 8). Если ответ - другой, меняются условие валидатора `CreateMessage`, сценарий - `messages` «Пробелы с вложением» и его тест, а ответ записывается в - AGENTS.md, «Согласования с преподавателем»; +- п. 2 — ответ преподавателя 2026-10-20 (AGENTS.md, «Согласования с + преподавателем»; design, решение 8): «пустой текст» — и `""`, и текст + из одних пробелов; с хотя бы одним вложением он допустим (201, текст + как прислан), без вложений — 400. Валидатор `CreateMessage`, + сценарий `messages` «Пробелы с вложением» и его тест — под это; - п. 3 — `filename` отклоняется только по списку контракта: `/`, `\` и управляющие символы категории Cc, остальное принимается. @@ -29,7 +29,7 @@ ## 1. Основа: константы, enum, DTO, исключения, проверка изображения -- [ ] 1.1 Типы домена по решениям 2, 4 и 10: +- [x] 1.1 Типы домена по решениям 2, 4 и 10: - константы в `src/utils/constants.py`: лимиты, длины `filename`, запрещённые символы `filename` (`/`, `\`, категория Cc), `MESSAGE_ATTACHMENTS_MAX`, префикс и суффикс ключа объекта; @@ -46,7 +46,7 @@ Проверка: `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, *, +- [x] 1.2 `src/utils/image.py` по решению 2: `inspect_image(data, *, max_pixels)` → `ImageInfo` (тип, ширина, высота), исключения `UnsupportedImage`, `DamagedImage`, `TooManyPixels`. Только stdlib; фильтры строк — срезом с шагом строки, конец скана JPEG — регулярным @@ -66,13 +66,13 @@ ## 2. Схема БД -- [ ] 2.1 Модели по решению 3: `src/infra/db/models/attachment.py` +- [x] 2.1 Модели по решению 3: `src/infra/db/models/attachment.py` (`Attachment`, `MessageAttachment` с ограничениями и индексом по `attachment_id`), новое условие `text_length` в `Message`, экспорт в `models/__init__.py`. Проверка: `make revision` даёт ревизию с двумя таблицами и индексом. Ослабление CHECK autogenerate не видит (`migrations.md`). -- [ ] 2.2 Ревизия руками по решению 3: +- [x] 2.2 Ревизия руками по решению 3: - первая строка `SET LOCAL lock_timeout = '2s'`; - CHECK литералами, а не константами `src`; - `DROP CONSTRAINT ck_messages_text_length` и `ADD CONSTRAINT … CHECK @@ -99,7 +99,7 @@ ## 3. Repo и сервисы -- [ ] 3.1 Repo по решениям 3, 4 и 8: +- [x] 3.1 Repo по решениям 3, 4 и 8: - `src/core/repos/attachment.py`: `insert_attachment`, `mark_ready` (`UPDATE … WHERE status = 'pending' RETURNING`), `get_attachment`, `get_attachments`; @@ -111,13 +111,13 @@ В каждой функции одно выражение. Проверка: `make lint`. Поведение — через HTTP в группах 4–5; план истории — задача 7.2. -- [ ] 3.2 `src/core/services/attachment.py` — `AttachmentService(db_scope, +- [x] 3.2 `src/core/services/attachment.py` — `AttachmentService(db_scope, cache, storage)` по решениям 1, 5, 6, 7, 11: `upload`, `get_attachment`, `open_content`. Проверка, загрузка, SHA-256 и размеры — одним `anyio.to_thread.run_sync`. Каждый шаг с БД — свой `async with self.db_scope()`, без вложенных. Журнал без `filename`. Проверка: `make lint`, дальше задача 4.3. -- [ ] 3.3 `MessageService.send_message(..., attachment_ids)` по решениям +- [x] 3.3 `MessageService.send_message(..., attachment_ids)` по решениям 8 и 9: - проверка вложений до захвата ключа; - связи после вставки сообщения, один commit; @@ -132,7 +132,7 @@ ## 4. Слой API -- [ ] 4.1 `src/api/dependencies.py` по решению 5: +- [x] 4.1 `src/api/dependencies.py` по решению 5: - `db_session_scope()`; - `get_db_session` — обёртка над ним; - `get_current_user_brief` и `CurrentUserBrief`; @@ -142,7 +142,7 @@ `src/api/errors.py` — строки таблицы решения 10. Проверка: `make lint`; `make student_test` через LB — те же итоги, что до правки (красное — только схема `Message`, сверка и исключения). JSON-ручки не изменились. -- [ ] 4.2 Схемы и ручки по решениям 6, 7, 8, 10: +- [x] 4.2 Схемы и ручки по решениям 6, 7, 8, 10: - `src/api/schemas/attachment.py`: `DisplayFilename` (отказ на `/`, `\`, символы категории Cc и строку из одних пробелов, решение 10), `Attachment`; @@ -157,7 +157,7 @@ Проверка: `/openapi.json` запущенного сервера содержит три пути контракта, тело загрузки `image/png` / `image/jpeg` и параметр `variant` с перечислением `original`. -- [ ] 4.3 Проверка на живом сервере. Консоль — `driver.py start`, стенд +- [x] 4.3 Проверка на живом сервере. Консоль — `driver.py start`, стенд — `make rolling_update`: одна миграция, затем замена по одной. - `make test` против обоих: `PASS: lab4 public API scenario`. - Руками через `driver.py req` и curl: @@ -175,21 +175,21 @@ ## 5. Тесты -- [ ] 5.1 `uv add --dev pillow`. `student-tests/images.py` — генераторы +- [x] 5.1 `uv add --dev pillow`. `student-tests/images.py` — генераторы по решению 12. Проверка: - `uv lock --check`; - `docker run --rm mtusi-messenger:lab4 python -c "import PIL"` завершается ошибкой: в образе Pillow нет; - `uv run python -c` с импортом `images` даёт PNG ровно 10 485 760 байт, и `inspect_image` его принимает. -- [ ] 5.2 `student-tests/api_client.py` и `contract.py` по решению 12: +- [x] 5.2 `student-tests/api_client.py` и `contract.py` по решению 12: - загрузка, метаданные, байты, `send_message(..., attachment_ids)`; - коды 413 и 415, `owner_id`, элементы `attachment_ids`, `updated_at`; - `assert_content`. Проверка: прежние тесты проходят на коде группы 4. -- [ ] 5.3 `student-tests/test_attachments.py` — сценарии спека +- [x] 5.3 `student-tests/test_attachments.py` — сценарии спека `attachments`, кроме проверок отказов и исключений, с маркерами `spec`. В «Опасном имени» — только символы контракта, в «Символах форматирования в имени» — 201 и то же имя в ответе и метаданных. @@ -199,7 +199,7 @@ их модулях. Проверка: `make student_test` через LB и `make test_isolated` — новые тесты проходят; на рабочем стенде через LB `replicas`-тест выполняется, в `test_isolated` пропущен с причиной. -- [ ] 5.4 Проверки отказов по дельте `student-tests`: +- [x] 5.4 Проверки отказов по дельте `student-tests`: - `test_failures.py`: «Запись в S3 не удалась», «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 завис» в `with outage(...)`; @@ -210,7 +210,7 @@ Проверка: `make failure_checks FAULT_ARGS='-k attachment or object_storage'`, затем полный `make failure_checks` — код 0, стенд отказов удалён, у рабочего стенда прежний `StartedAt`. -- [ ] 5.5 Сверка покрытия: +- [x] 5.5 Сверка покрытия: - `attachments` в `CAPABILITIES` (`spec_coverage.py`); - исключения «Принявшая реплика остановлена», «Байты не в БД и не на диске API», «Рестарт стенда» с причиной и командой по решению 12; @@ -223,30 +223,30 @@ ## 6. Драйвер скилла `run-mtusi-messenger` -- [ ] 6.1 Команды `upload` и `download` по решению 13. Проверка против +- [x] 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. +- [x] 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. Проверка: +- [x] 6.3 `attachment-storage` по решению 13. Проверка: - на стенде код 0; - отрицательная: `s3.anonymous.set -access Read` через `docker compose exec s3 weed shell` — код 1 с названной проверкой; `docker compose up -d s3-bootstrap` закрывает доступ, и снова код 0. -- [ ] 6.4 `flow` с вложением по решению 13, раздел о вложениях в +- [x] 6.4 `flow` с вложением по решению 13, раздел о вложениях в `SKILL.md`: команды, gotchas — `urllib` напрямую к реплике и ранний 413; S3 нужен только путям вложений. Проверка: `driver.py all` — код 0, `FAILED: none`. ## 7. Стенд `bench/` -- [ ] 7.1 `rollout_from = "e1161f7"` в профилях `rollout` и +- [x] 7.1 `rollout_from = "e1161f7"` в профилях `rollout` и `rollout_quick` (комментарий профиля — тоже) и проверка commit до стенда по решению 14 и дельте `load-benchmark`. Правило в `bench.md`, удаление записи из `KNOWN_ISSUES.md`. Проверка: @@ -263,11 +263,12 @@ ## 8. Документы и проверка кода -- [ ] 8.1 Правила: +- [x] 8.1 Правила: - `api-contract.md` — раздел лабы 4: ручки, коды 413 и 415 в таблице, порядок проверок загрузки, `filename` (только символы контракта, категория Cc), `UuidIn` для id вложений, ранний ответ и - `urllib`, временная трактовка текста из пробелов с вложением; + `urllib`, пустой текст (в том числе из пробелов) с вложением — + 201 по согласованию с преподавателем; - `api-layer.md` — роутер с двумя префиксами, `CurrentUserBrief`, тело без параметра, `StreamingResponse`, `UploadInterrupted`; - `service-layer.md` — `AttachmentService` с `db_scope`, порядок @@ -288,12 +289,14 @@ лабу» — `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 .`. +- [x] 8.2 `make lint`, `make check`, `openspec validate attachments + --strict`, `graphify update .`. После sync дельт имя `attachments` — + и change, и спек: `openspec validate attachments --type change + --strict`. ## 9. Коммит, evidence, отчёт -- [ ] 9.1 Финальная проверка на стенде `mtusi-lab4` после `make +- [x] 9.1 Финальная проверка на стенде `mtusi-lab4` после `make rolling_update`: - `make test` — `PASS: lab4`; - `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make @@ -336,8 +339,9 @@ - ответы на четыре вопроса защиты; - строки уровней «3» и «4» с командой, наблюдением и файлом; - ограничения; - - открытый вопрос преподавателю: текст из одних пробелов с вложением - пока даёт 400 (design, решение 8). + - согласование с преподавателем 2026-10-20: текст из одних пробелов + с вложением — 201, без вложений — 400 (design, решение 8; AGENTS.md, + «Согласования с преподавателем»). Строку этапа 2 в `PLAN.md` — по факту. Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл; `make lint`, diff --git a/openspec/specs/api-conventions/spec.md b/openspec/specs/api-conventions/spec.md index e4d52a14..1f121426 100644 --- a/openspec/specs/api-conventions/spec.md +++ b/openspec/specs/api-conventions/spec.md @@ -113,8 +113,9 @@ Unicode code points. Сервис SHALL использовать пары статус — `code`: 400 — `invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 — -`conflict`, 500 — `internal_error`, 503 — `unavailable`. Метод, не -поддерживаемый путём, SHALL давать 405 с `code` `invalid_request`. +`conflict`, 413 — `payload_too_large`, 415 — `unsupported_media_type`, +500 — `internal_error`, 503 — `unavailable`. Метод, не поддерживаемый +путём, SHALL давать 405 с `code` `invalid_request`. #### Scenario: Неизвестный путь @@ -126,6 +127,13 @@ Unicode code points. - **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: Невалидный запрос даёт 400 Сервис SHALL отвечать 400 `invalid_request`, а не 422, когда тело не @@ -186,13 +194,14 @@ Unicode code points. ### Requirement: UUID на входе -Идентификатор, который передаёт клиент, — `chat_id` в пути и элементы -`member_ids` в теле — SHALL приниматься только как строка UUID в записи -8-4-4-4-12 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`), как `format: uuid` -контракта. Шестнадцатеричные цифры SHALL приниматься в любом регистре: -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:`, в @@ -227,3 +236,18 @@ UUID в верхнем регистре обозначает тот же иде него сообщение, записав `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` в них — в нижнем регистре diff --git a/openspec/specs/attachments/spec.md b/openspec/specs/attachments/spec.md new file mode 100644 index 00000000..e4a40dc6 --- /dev/null +++ b/openspec/specs/attachments/spec.md @@ -0,0 +1,456 @@ +# attachments Specification + +## Purpose + +Вложения-изображения в чатах с лабы 4. Здесь описано: +- загрузка PNG и JPEG с лимитами до чтения и распаковки; +- проверка типа и целостности по содержимому, правила `filename`; +- доступ только участникам чата, метаданные и побайтный download; +- где лежат метаданные и байты, порядок записи и отказ S3; +- доступность файла через любую реплику и после рестарта стенда. + +## 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//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 diff --git a/openspec/specs/data-storage/spec.md b/openspec/specs/data-storage/spec.md index d7d1d05f..16c0d950 100644 --- a/openspec/specs/data-storage/spec.md +++ b/openspec/specs/data-storage/spec.md @@ -11,11 +11,13 @@ PostgreSQL как источник истины, сохранность посл ### Requirement: Хранение в PostgreSQL -Пользователи, чаты, участники чатов, сообщения и сессии SHALL храниться -в PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные -в памяти процесса, файлах или SQLite. Подтверждённая запись (ответ 201 -или 204) SHALL быть зафиксирована в БД до ответа и видна следующему -запросу. +Пользователи, чаты, участники чатов, сообщения, сессии, а с лабы 4 — +метаданные вложений и связи сообщений с вложениями SHALL храниться в +PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные +в памяти процесса, файлах или SQLite. Байты вложений SHALL храниться в +S3 (capability `attachments`, `object-storage`), а не в PostgreSQL и не +в файлах реплик. Подтверждённая запись (ответ 201 или 204) SHALL быть +зафиксирована до ответа и видна следующему запросу. #### Scenario: Созданное видно сразу @@ -28,7 +30,9 @@ PostgreSQL как источник истины, сохранность посл После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее подтверждённые пользователи, чаты, участники и сообщения SHALL быть -доступны в прежнем виде. +доступны в прежнем виде. С лабы 4 это относится и к вложениям: их +метаданные, `attachment_ids` сообщений и оригиналы переживают и +перезапуск S3 с его volume. #### Scenario: Прежний пользователь после рестарта @@ -60,10 +64,26 @@ PostgreSQL как источник истины, сохранность посл ### Requirement: Целостность данных в БД Ограничения SHALL проверяться самой БД, а не только сервисом: -уникальность `username`, существование пользователей и чатов, на -которые ссылаются участники и сообщения, уникальность участника в -чате, членство отправителя в чате сообщения. Порядок `member_ids`, -заданный при создании чата, SHALL сохраняться. +- уникальность `username`; +- существование пользователей и чатов, на которые ссылаются участники + и сообщения; +- уникальность участника в чате; +- членство отправителя в чате сообщения. + +С лабы 4 БД SHALL проверять и вложения: +- владелец вложения — участник его чата; +- связь сообщения с вложением ссылается на существующие сообщение и + вложение; +- вложение не повторяется в одном сообщении, у каждого места в порядке + одно вложение, мест не больше 10; +- вложение, на которое ссылается сообщение, удалить нельзя; +- допустимые значения размера, SHA-256, типа, статуса и длины + `filename`; ключ объекта уникален. + +Порядок `member_ids`, заданный при создании чата, и порядок +`attachment_ids` сообщения SHALL сохраняться. Принадлежность вложения +чату сообщения проверяет сервис в той же транзакции: чат вложения и +чат сообщения не меняются после записи. #### Scenario: Порядок участников @@ -71,6 +91,12 @@ PostgreSQL как источник истины, сохранность посл - **THEN** `GET` этого чата и список чатов возвращают `member_ids` в том же порядке, в том числе после рестарта стенда +#### Scenario: Порядок вложений + +- **WHEN** сообщение отправлено с `attachment_ids` `[C, A, B]` +- **THEN** ответ на отправку, история чата и повтор с тем же ключом + возвращают `[C, A, B]` + ### Requirement: Составная операция в одной транзакции Создание чата вместе с участниками SHALL выполняться одной diff --git a/openspec/specs/db-migrations/spec.md b/openspec/specs/db-migrations/spec.md index dbdf2d93..17c977e8 100644 --- a/openspec/specs/db-migrations/spec.md +++ b/openspec/specs/db-migrations/spec.md @@ -91,16 +91,23 @@ ### Requirement: Совместимость миграции с работающей версией Миграция SHALL только расширять схему: -- новая таблица; +- новая таблица со своими ограничениями и внешними ключами; - новая колонка, допускающая NULL или со значением по умолчанию; -- новый индекс. +- новый индекс; +- ослабление ограничения: новое условие пропускает всё, что пропускало + прежнее, поэтому прежняя версия не пишет значений, которые новое + условие запретит. -Удаление и переименование таблицы, колонки или ограничения, а также -новое ограничение, которое нарушит запись прежней версии, MUST NOT -входить в ту же поставку, что и код, которому они нужны. Такое -изменение выполняется отдельной миграцией после того, как реплик -прежней версии не осталось (expand/contract). Если так сделать нельзя, -ограничение SHALL описываться в `REPORT.md`. +Ослабленное ограничение SHALL добавляться без проверки существующих +строк под эксклюзивной блокировкой таблицы: эти строки уже +удовлетворяли более строгому условию. + +Удаление и переименование таблицы, колонки или ограничения (кроме +замены ограничения ослабленным), а также новое ограничение, которое +нарушит запись прежней версии, MUST NOT входить в ту же поставку, что и +код, которому они нужны. Такое изменение выполняется отдельной миграцией +после того, как реплик прежней версии не осталось (expand/contract). +Если так сделать нельзя, ограничение SHALL описываться в `REPORT.md`. Реплики прежнего образа SHALL обслуживать обязательные запросы на схеме после новой миграции. Откат кода к прежнему образу MUST NOT @@ -137,6 +144,15 @@ других клиентов, ждавшие за миграцией, получают успешный ответ, а после окончания транзакции повторный запуск применяет миграцию +#### Scenario: Ослабленное ограничение + +- **WHEN** миграция вложений заменяет ограничение длины текста + сообщения (было 1–4000, стало 0–4000) на таблице с сообщениями, а + запись идёт через реплики прежнего образа +- **THEN** миграция не проверяет существующие строки, записи прежних + реплик во время и после неё — 201, а после замены реплик сообщение с + пустым текстом и вложением — 201 + ### Requirement: Однократные миграции при замене реплик Поочерёдная замена реплик (`load-balancing`) SHALL применять миграции diff --git a/openspec/specs/idempotency/spec.md b/openspec/specs/idempotency/spec.md index 1812df7e..a5719812 100644 --- a/openspec/specs/idempotency/spec.md +++ b/openspec/specs/idempotency/spec.md @@ -48,10 +48,17 @@ Повтор от того же пользователя в тот же чат с тем же ключом и тем же телом в пределах срока ключа SHALL возвращать 201 и тот же `Message`: -тот же `id`, `text` и `created_at` до микросекунды. Новое сообщение -MUST NOT создаваться. Тела SHALL сравниваться по смыслу, после разбора -JSON: запись пробелов, экранирование символов и порядок полей на -результат не влияют. +тот же `id`, `text`, `attachment_ids` и `created_at` до микросекунды. +Новое сообщение MUST NOT создаваться. Тела SHALL сравниваться по смыслу, +после разбора JSON. На результат не влияют: +- запись пробелов и экранирование символов; +- порядок полей объекта; +- отсутствующий `attachment_ids` вместо `[]`; +- регистр букв в идентификаторах вложений. + +Порядок элементов `attachment_ids` значим: это порядок вложений в +сообщении. Ключ, сохранённый версией сервиса без вложений, SHALL +повторяться тем же телом и после замены реплик на версию с вложениями. #### Scenario: Повтор того же тела @@ -66,11 +73,26 @@ JSON: запись пробелов, экранирование символов другими пробелами и с текстом в экранировании `\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 меняться. +создаваться, сохранённый результат ключа MUST NOT меняться. Другие +вложения или их другой порядок — другое тело. #### Scenario: Другой текст @@ -79,6 +101,13 @@ JSON: запись пробелов, экранирование символов - **THEN** второй ответ 409 `conflict`, в истории только T1, а повтор T1 с K по-прежнему возвращает исходный `Message` +#### Scenario: Другие вложения + +- **WHEN** Алиса отправила текст с `attachment_ids` `[A, B]` и ключом + K, затем шлёт с K тот же текст с `[B, A]`, а потом без вложений +- **THEN** оба ответа 409 `conflict`, в истории одно сообщение с + `[A, B]` + ### Requirement: Область ключа Ключ SHALL быть уникален в пределах пользователя и чата: метод и путь diff --git a/openspec/specs/load-benchmark/spec.md b/openspec/specs/load-benchmark/spec.md index 4937fa83..da19c0b2 100644 --- a/openspec/specs/load-benchmark/spec.md +++ b/openspec/specs/load-benchmark/spec.md @@ -1796,3 +1796,31 @@ SHALL описывать трек 1: - **WHEN** поток не получил события действия или возврата фазы - **THEN** команда завершается с ненулевым кодом, называет фазу и реплику и удаляет стенд + +### 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 ` для отладки. + +#### Scenario: Замена на схему с вложениями + +- **WHEN** выполнен `make bench_rollout_quick` на коде с вложениями +- **THEN** реплики стартуют на образе commit до change `attachments`, + ревизия схемы до замены — без таблиц вложений, после — с ними, а + команда завершается с кодом 0 + +#### Scenario: Commit вне истории + +- **WHEN** commit методики не найден в репозитории +- **THEN** команда завершается с ненулевым кодом до запуска стенда, а + сообщение называет commit и `--from` diff --git a/openspec/specs/messages/spec.md b/openspec/specs/messages/spec.md index 4f19691c..1054e82b 100644 --- a/openspec/specs/messages/spec.md +++ b/openspec/specs/messages/spec.md @@ -10,24 +10,41 @@ ### Requirement: Отправка сообщения `POST /api/v1/chats/{chat_id}/messages` SHALL принимать тело -`{"text": ...}` с заголовком `Idempotency-Key` и при успехе отвечать -201 с объектом `Message`: `id`, `chat_id`, `sender_id`, `text`, -`created_at`, без других полей. `sender_id` SHALL быть текущим -пользователем, `text` SHALL совпадать с отправленным. Формат ключа, -повтор и конфликт описаны в capability `idempotency`. +`{"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 содержать от 1 до 4000 Unicode code points и MUST NOT -состоять только из пробельных символов. Поле `sender_id` в теле MUST NOT -приниматься. Нарушения SHALL давать 400 `invalid_request`. +`text` SHALL содержать не больше 4000 Unicode code points. Пустой +текст — пустая строка или строка из одних пробельных символов — SHALL +допускаться только вместе с хотя бы одним вложением, без вложений он MUST +NOT приниматься (согласовано с преподавателем 2026-10-20, AGENTS.md, +«Согласования с преподавателем»). Текст SHALL сохраняться и +возвращаться как прислан, без обрезки и нормализации. Поле `sender_id` +в теле MUST NOT приниматься. Нарушения SHALL давать 400 +`invalid_request`. #### Scenario: Пустой текст @@ -44,6 +61,21 @@ - **WHEN** тело содержит `sender_id` другого пользователя - **THEN** ответ 400, сообщение не создаётся +#### Scenario: Пустой текст с вложением + +- **WHEN** участник отправляет `{"text": "", "attachment_ids": [A]}` с + готовым вложением A своего чата +- **THEN** ответ 201, `text` — пустая строка, `attachment_ids` — `[A]` + +#### Scenario: Пробелы с вложением + +- **WHEN** участник отправляет `{"text": " ", "attachment_ids": [A]}` + с готовым вложением A своего чата, а затем `{"text": " "}` без + вложений +- **THEN** первый ответ 201, `text` — те же три пробела, + `attachment_ids` — `[A]`; второй — 400 `invalid_request`, и это + сообщение не создаётся + ### Requirement: Писать и читать могут только участники Отправка и чтение истории SHALL быть доступны только участникам чата. @@ -65,7 +97,8 @@ `GET /api/v1/chats/{chat_id}/messages` SHALL возвращать сообщения чата в порядке `(created_at, id)` по возрастанию, с постраничным выводом по capability `pagination`. Любой участник SHALL видеть все сообщения -чата, в том числе чужие. +чата, в том числе чужие. Каждое сообщение SHALL содержать +`attachment_ids` в порядке отправки. #### Scenario: Два участника, две страницы @@ -75,6 +108,13 @@ capability `pagination`. Любой участник SHALL видеть все `next_cursor`, вторая — второе сообщение и `next_cursor` null, а порядок совпадает с `(created_at, id)` +#### Scenario: Вложения в истории + +- **WHEN** Алиса отправила сообщение с `attachment_ids` `[B, A]`, а Боб + — текстовое сообщение +- **THEN** в истории у первого `attachment_ids` — `[B, A]`, у второго — + `[]` + ### Requirement: Подтверждённое сообщение сразу видно Сообщение, на которое сервис ответил 201, SHALL присутствовать в @@ -84,3 +124,59 @@ capability `pagination`. Любой участник SHALL видеть все - **WHEN** участник получил 201 на отправку и сразу читает историю - **THEN** сообщение есть в истории + +### 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` diff --git a/openspec/specs/service-configuration/spec.md b/openspec/specs/service-configuration/spec.md index d61f7535..93f802c7 100644 --- a/openspec/specs/service-configuration/spec.md +++ b/openspec/specs/service-configuration/spec.md @@ -340,3 +340,18 @@ MUST NOT стартовать. Как эти сроки согласованы `DATABASE__IDLE_IN_TRANSACTION_TIMEOUT_MS=5000` при `request_timeout_seconds` 6 - **THEN** сервис не стартует, ошибка называет оба параметра + +### 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: лимиты остались контрактными diff --git a/openspec/specs/service-logging/spec.md b/openspec/specs/service-logging/spec.md index eeea1372..04cadb04 100644 --- a/openspec/specs/service-logging/spec.md +++ b/openspec/specs/service-logging/spec.md @@ -84,10 +84,13 @@ - ключ подписи служебных вызовов S3; - подписи запросов к S3: их заголовок `Authorization` и параметры подписи; -- байты объектов. +- байты объектов; +- `filename` вложений. Для обращений к S3 допускаются адрес S3, имя bucket, ключ объекта, -размер, длительность и класс ошибки. +размер, длительность и класс ошибки. Для вложений допускаются `id` +вложения и чата, размер, тип, ширина и высота изображения, длина +`filename` и причина отказа в загрузке. #### Scenario: Отправка сообщения @@ -120,6 +123,14 @@ подпись запроса; запись о старте содержит адрес S3 и имя bucket, а отказ в учётных данных записан с уровнем `error` +#### Scenario: Загрузка вложения + +- **WHEN** участник загружает изображение с уникальным `filename` F, а + затем повреждённый файл с тем же именем +- **THEN** ни одна запись журнала не содержит F; запись о загрузке + содержит `id` вложения, размер и тип, а запись об отказе — причину + отказа без имени файла + ### Requirement: Непредвиденные ошибки в журнале Непредвиденное исключение SHALL записываться с уровнем `error`, diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index 3d74ac40..e93fc1c4 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -76,7 +76,11 @@ MUST завершаться ошибкой с указанием этой ком Набор SHALL содержать отдельные тесты для сценариев уровня «4»: неверный JSON, чужой чат, пустое сообщение, дубликат `username`, обход -нескольких страниц истории, а с лабы 2 — неверный пароль и logout. +нескольких страниц истории, а с лабы 2 — неверный пароль и logout. С +лабы 4 к ним SHALL добавиться слишком большой файл, повреждённое +изображение, подмена MIME, чужое `attachment_id` и вложение другого +чата. Каждый такой тест SHALL проверять, что ошибка клиента дала +статус 4xx в формате контракта, а не 500. #### Scenario: Неверный JSON @@ -122,6 +126,38 @@ MUST завершаться ошибкой с указанием этой ком - **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: Тест гонок Набор SHALL содержать тест гонок с реальной параллельностью: запросы @@ -198,15 +234,15 @@ MUST NOT считаться пройденными. При `EXPECT_REPLICAS` ≥ Для каждого сценария основных спеков `api-conventions`, `identification`, `sessions`, `users`, `chats`, `messages`, -`pagination`, `data-storage`, `chat-cache`, `health` и `idempotency`, -который воспроизводится по HTTP против работающего сервера, в том числе -на стенде отказов, SHALL быть тест. Из имени или описания теста SHALL -быть понятно, какой capability и сценарий он проверяет. Сценарий, -который проверяет тест отказа, SHALL считаться покрытым, хотя `make -student_test` этот тест не выполняет; итог сверки SHALL называть, -сколько сценариев покрыто проверками отказов. Сценарии, которые по HTTP -не воспроизвести, SHALL быть перечислены с причиной и способом -проверки. +`pagination`, `data-storage`, `chat-cache`, `health`, `idempotency` и с +лабы 4 `attachments`, который воспроизводится по HTTP против +работающего сервера, в том числе на стенде отказов, SHALL быть тест. Из +имени или описания теста SHALL быть понятно, какой capability и +сценарий он проверяет. Сценарий, который проверяет тест отказа, SHALL +считаться покрытым, хотя `make student_test` этот тест не выполняет; +итог сверки SHALL называть, сколько сценариев покрыто проверками +отказов. Сценарии, которые по HTTP не воспроизвести, SHALL быть +перечислены с причиной и способом проверки. #### Scenario: Сверка покрытия @@ -241,8 +277,9 @@ student_test` против стенда с балансировщиком и в failure_checks` SHALL сохраняться в `evidence/` с командой, датой, commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов, -гонка одного ключа через реплики и автоматические проверки истечения -сессии и недоступности БД и Valkey. +гонка одного ключа через реплики, автоматические проверки истечения +сессии и недоступности БД и Valkey, а с лабы 4 — негативные тесты +вложений и проверки отказов S3. #### Scenario: Доказательство в отчёте @@ -329,7 +366,9 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по - `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся», «Очистка кэша»; - `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке», - «Ключ после срока». + «Ключ после срока»; +- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего + не оставляет», «S3 остановлен», «S3 завис». Команда SHALL: - собрать образ из рабочего дерева; @@ -341,6 +380,10 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по - выполнить проверки отказов; - удалить стенд вместе с его данными при любом исходе. +Hook стенда отказов SHALL уметь сообщить число вложений в PostgreSQL +стенда по статусам и число объектов вложений в его bucket. Других +сведений о хранилищах проверки вложений не получают. + Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш, хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода @@ -384,7 +427,8 @@ SHALL быть ненулевым, если не прошла хотя бы од называть сценарий и путь. Такое доказательство MUST NOT содержать токенов, паролей и их хэшей -целиком — только факты, счётчики и префиксы. +целиком, ключей доступа и секретов S3 — только факты, счётчики и +префиксы. #### Scenario: Ссылка на отсутствующий файл @@ -402,6 +446,15 @@ SHALL быть ненулевым, если не прошла хотя бы од балансировщиком и двумя репликами, дата и commit, а токенов, паролей и полных хэшей нет +#### Scenario: Вложения на стенде лабы + +- **WHEN** проверяющий открывает файлы, на которые ссылаются исключения + `attachments` «Принявшая реплика остановлена», «Байты не в БД и не на + диске API» и «Рестарт стенда» +- **THEN** в них вывод названной в исключении команды на стенде с + балансировщиком, двумя репликами и S3, дата и commit, SHA-256 + загруженного и скачанного файла, а токенов и секретов S3 нет + ### Requirement: PostgreSQL стенда отказов без аварийных перезапусков Проверки отказов MUST NOT приводить к аварийному перезапуску PostgreSQL diff --git a/pyproject.toml b/pyproject.toml index fab235ef..d74792ac 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -66,6 +66,9 @@ dev = [ "pytest>=9.1.1,<10", "httpx>=0.28.1,<1", "jsonschema>=4.26.0,<5", + # student-tests: JPEG разных видов в памяти теста; в образ (uv sync + # --no-dev) и в приложение не входит + "pillow>=13.0.0,<14", ] [tool.pytest.ini_options] diff --git a/src/api/dependencies.py b/src/api/dependencies.py index 23048998..9ca75d36 100644 --- a/src/api/dependencies.py +++ b/src/api/dependencies.py @@ -1,7 +1,8 @@ """Зависимости ручек: сессия БД, сервисы, вход и текущая сессия, страница. Сервисы получают сессию БД, а чаты и сообщения — ещё и кэш процесса -(`src/infra/cache/instance.py`). +(`src/infra/cache/instance.py`). Вложения — фабрику короткой сессии на +шаг, кэш и хранилище объектов (`src/infra/s3/instance.py`). """ import asyncio @@ -9,6 +10,7 @@ import base64 import binascii import re from collections.abc import AsyncIterator +from contextlib import asynccontextmanager from dataclasses import dataclass from typing import Annotated @@ -20,6 +22,7 @@ from sqlalchemy.ext.asyncio import AsyncSession from src.config import settings from src.core import exceptions from src.core.services import ( + AttachmentService, ChatService, MessageService, SessionService, @@ -29,6 +32,7 @@ from src.infra.cache.instance import cache from src.infra.db import is_db_unavailable, ping from src.infra.db.session import engine, session_factory from src.infra.logger import AbstractLogger, current_user_id, get_logger +from src.infra.s3.instance import object_storage from src.schemas import dataclasses from src.utils.constants import ( PAGE_LIMIT_DEFAULT, @@ -43,10 +47,11 @@ from src.utils.constants import ( logger: AbstractLogger = get_logger().bind(module="api_dependencies") -async def get_db_session() -> AsyncIterator[AsyncSession]: - """Одна сессия БД на запрос; commit делает сервис. +@asynccontextmanager +async def db_session_scope() -> AsyncIterator[AsyncSession]: + """Сессия БД на один шаг; commit делает сервис. - Незакоммиченное при выходе откатывается. Вся работа запроса с БД + Незакоммиченное при выходе откатывается. Работа с БД внутри ограничена `[database] request_timeout_seconds`: зависший Postgres не держит запрос бесконечно. Недоступность БД (`is_db_unavailable`) — 503 `unavailable`, а соединение не возвращается в пул: его состояние @@ -70,6 +75,19 @@ async def get_db_session() -> AsyncIterator[AsyncSession]: raise exceptions.ServiceUnavailable from e +async def get_db_session() -> AsyncIterator[AsyncSession]: + """Одна сессия БД на запрос — `db_session_scope` на весь запрос. + + Зависимость с `yield` FastAPI закрывает после отправки ответа, поэтому + срок и соединение пула охватывают и отдачу тела. Ручкам с длинной + передачей (вложения) она не подходит: им — `CurrentUserBrief` и + сервис с `db_session_scope` на шаг (design change `attachments`, + решение 5). + """ + async with db_session_scope() as db_session: + yield db_session + + DbSessionDep = Annotated[AsyncSession, Depends(get_db_session)] @@ -101,10 +119,23 @@ async def get_session_service(db_session: DbSessionDep) -> SessionService: return SessionService(db_session=db_session) +async def get_attachment_service() -> AttachmentService: + """Без сессии запроса: сервис открывает `db_session_scope` на шаг.""" + return AttachmentService( + db_scope=db_session_scope, + cache=cache, + storage=object_storage, + ) + + UserServiceDep = Annotated[UserService, Depends(get_user_service)] ChatServiceDep = Annotated[ChatService, Depends(get_chat_service)] MessageServiceDep = Annotated[MessageService, Depends(get_message_service)] SessionServiceDep = Annotated[SessionService, Depends(get_session_service)] +AttachmentServiceDep = Annotated[ + AttachmentService, + Depends(get_attachment_service), +] # схемы basicAuth и bearerAuth из contracts/openapi.json: объявлены в @@ -204,6 +235,32 @@ async def get_current_user( CurrentUser = Annotated[dataclasses.UserFullDTO, Depends(get_current_user)] +async def get_current_user_brief( + credentials: Annotated[ + HTTPAuthorizationCredentials | None, + Security(bearer_scheme), + ], +) -> dataclasses.UserFullDTO: + """Пользователь по Bearer-токену с короткой сессией БД; иначе 401. + + Обычная функция, а не генератор: сессия закрыта и соединение + вернулось в пул до тела запроса. Для ручек с длинной передачей байтов + (design change `attachments`, решение 5). + """ + async with db_session_scope() as db_session: + current = await SessionService(db_session=db_session).authenticate( + token=credentials.credentials if credentials else None, + ) + current_user_id.set(str(current.user.id)) + return current.user + + +CurrentUserBrief = Annotated[ + dataclasses.UserFullDTO, + Depends(get_current_user_brief), +] + + @dataclass(frozen=True, slots=True) class PageQuery: limit: int diff --git a/src/api/errors.py b/src/api/errors.py index ab72fa8d..4352b2af 100644 --- a/src/api/errors.py +++ b/src/api/errors.py @@ -28,8 +28,17 @@ DOMAIN_ERRORS: dict[type[exceptions.DomainError], tuple[int, ErrorCode]] = { exceptions.UsernameTaken: (409, ErrorCode.CONFLICT), exceptions.IdempotencyConflict: (409, ErrorCode.CONFLICT), exceptions.ChatNotFound: (404, ErrorCode.NOT_FOUND), + exceptions.AttachmentNotFound: (404, ErrorCode.NOT_FOUND), exceptions.InvalidChatMembers: (400, ErrorCode.INVALID_REQUEST), exceptions.InvalidCursor: (400, ErrorCode.INVALID_REQUEST), + exceptions.UploadInterrupted: (400, ErrorCode.INVALID_REQUEST), + exceptions.PayloadTooLarge: (413, ErrorCode.PAYLOAD_TOO_LARGE), + exceptions.UnsupportedMediaType: ( + 415, + ErrorCode.UNSUPPORTED_MEDIA_TYPE, + ), + # расхождение БД и S3, а не ошибка клиента: причина — в журнале + exceptions.AttachmentContentMissing: (500, ErrorCode.INTERNAL_ERROR), exceptions.ServiceUnavailable: (503, ErrorCode.UNAVAILABLE), # доменная ошибка без своей строки — некорректный запрос exceptions.DomainError: (400, ErrorCode.INVALID_REQUEST), diff --git a/src/api/routers/v1/__init__.py b/src/api/routers/v1/__init__.py index 8e02a304..bba4caf1 100644 --- a/src/api/routers/v1/__init__.py +++ b/src/api/routers/v1/__init__.py @@ -8,6 +8,7 @@ from fastapi import APIRouter from src.utils.constants import API_V1_PREFIX +from .attachment import router as attachment_router from .chat import router as chat_router from .message import router as message_router from .session import router as session_router @@ -18,6 +19,7 @@ v1_router.include_router(user_router) v1_router.include_router(session_router) v1_router.include_router(chat_router) v1_router.include_router(message_router) +v1_router.include_router(attachment_router) __all__ = [ "v1_router", diff --git a/src/api/routers/v1/attachment.py b/src/api/routers/v1/attachment.py new file mode 100644 index 00000000..63290e2f --- /dev/null +++ b/src/api/routers/v1/attachment.py @@ -0,0 +1,153 @@ +"""Вложения: загрузка, метаданные, байты оригинала. + +Один роутер с двумя префиксами путей — `/chats/{chat_id}/attachments` и +`/attachments/{attachment_id}`: домен один. Сессии БД на весь запрос +нет: вход — `CurrentUserBrief`, сервис открывает короткую сессию на +каждый шаг (design change `attachments`, решение 5). +""" + +from collections.abc import AsyncIterator +from typing import Annotated, Literal + +from fastapi import APIRouter, Query, Request +from fastapi.responses import StreamingResponse +from starlette.background import BackgroundTask +from starlette.requests import ClientDisconnect + +from src.api.dependencies import AttachmentServiceDep, CurrentUserBrief +from src.api.schemas import Attachment, DisplayFilename, UuidIn +from src.core import exceptions +from src.schemas.enums import ImageType +from src.utils.constants import ( + ATTACHMENT_FILENAME_MAX_LENGTH, + ATTACHMENT_FILENAME_MIN_LENGTH, +) + +router = APIRouter(tags=["attachments"]) + +_BINARY = {"schema": {"type": "string", "format": "binary"}} +# тело загрузки — сырые байты, параметра тела у ручки нет (FastAPI его не +# читает): схему для /openapi.json и /docs задаём как в контракте +_UPLOAD_BODY = { + "requestBody": { + "required": True, + "description": "Raw bytes of one PNG or JPEG image, not multipart.", + "content": {image_type.value: _BINARY for image_type in ImageType}, + }, +} +_DOWNLOAD_RESPONSES = { + 200: { + "description": "Original bytes", + "content": {image_type.value: _BINARY for image_type in ImageType}, + }, +} + +FilenameQuery = Annotated[ + DisplayFilename, + Query( + min_length=ATTACHMENT_FILENAME_MIN_LENGTH, + max_length=ATTACHMENT_FILENAME_MAX_LENGTH, + ), +] + + +def _media_type(request: Request) -> str | None: + """Тип из `Content-Type` без параметров и пробелов, в нижнем регистре.""" + value = request.headers.get("content-type") + if value is None: + return None + return value.split(";", 1)[0].strip().lower() or None + + +def _content_length(request: Request) -> int | None: + value = request.headers.get("content-length") + return int(value) if value is not None and value.isdigit() else None + + +async def _body(request: Request) -> AsyncIterator[bytes]: + """Тело блоками по мере прихода; обрыв клиента — `UploadInterrupted`.""" + try: + async for chunk in request.stream(): + if chunk: + yield chunk + except ClientDisconnect as e: + raise exceptions.UploadInterrupted from e + + +@router.post( + "/chats/{chat_id}/attachments", + status_code=201, + response_model=Attachment, + openapi_extra=_UPLOAD_BODY, +) +async def upload_attachment( + user: CurrentUserBrief, + chat_id: UuidIn, + filename: FilenameQuery, + request: Request, + attachments: AttachmentServiceDep, +) -> Attachment: + """201 — оригинал в S3 и метаданные в PostgreSQL сохранены. + + Тело не читается, пока не пройдены вход, параметры, членство, + `Content-Type` и `Content-Length` (спек «Порядок проверок загрузки»). + """ + attachment = await attachments.upload( + chat_id=chat_id, + owner_id=user.id, + filename=filename, + media_type=_media_type(request), + content_length=_content_length(request), + body=_body(request), + ) + return Attachment.model_validate(attachment) + + +@router.get("/attachments/{attachment_id}", response_model=Attachment) +async def get_attachment( + user: CurrentUserBrief, + attachment_id: UuidIn, + attachments: AttachmentServiceDep, +) -> Attachment: + attachment = await attachments.get_attachment( + attachment_id=attachment_id, + user_id=user.id, + ) + return Attachment.model_validate(attachment) + + +@router.get( + "/attachments/{attachment_id}/content", + response_class=StreamingResponse, + responses=_DOWNLOAD_RESPONSES, +) +async def download_attachment( + user: CurrentUserBrief, + attachment_id: UuidIn, + attachments: AttachmentServiceDep, + # проверка значения — по схеме; вариант на лабе 4 один. enum — как в + # контракте: Literal из одного значения pydantic пишет как const + variant: Annotated[ # noqa: ARG001 + Literal["original"], + Query(json_schema_extra={"enum": ["original"]}), + ] = "original", +) -> StreamingResponse: + """Байты оригинала потоком из S3, без redirect. + + `variant` — только `original` (перечисление контракта лабы 4). + Отказ S3 до заголовков — 503; посреди потока соединение обрывается. + """ + content = await attachments.open_content( + attachment_id=attachment_id, + user_id=user.id, + ) + return StreamingResponse( + content.chunks, + media_type=content.content_type.value, + headers={ + "Content-Length": str(content.size_bytes), + "X-Content-Type-Options": "nosniff", + }, + # генератор сам закрывает объект; это — если он не начался + background=BackgroundTask(content.close), + ) diff --git a/src/api/routers/v1/message.py b/src/api/routers/v1/message.py index 4ebf3a44..fa07c6e7 100644 --- a/src/api/routers/v1/message.py +++ b/src/api/routers/v1/message.py @@ -41,6 +41,7 @@ async def send_message( sender_id=user.id, text=body.text, idempotency_key=idempotency_key, + attachment_ids=body.attachment_ids, ) return Message.model_validate(message) diff --git a/src/api/schemas/__init__.py b/src/api/schemas/__init__.py index fe1a3616..48fc9fd3 100644 --- a/src/api/schemas/__init__.py +++ b/src/api/schemas/__init__.py @@ -1,3 +1,4 @@ +from .attachment import Attachment, DisplayFilename from .chat import Chat, ChatPage, CreateChat from .common import Error, ErrorBody, ErrorCode, Health, UuidIn from .message import CreateMessage, Message, MessagePage @@ -5,11 +6,13 @@ from .session import Session from .user import CreateUser, User __all__ = [ + "Attachment", "Chat", "ChatPage", "CreateChat", "CreateMessage", "CreateUser", + "DisplayFilename", "Error", "ErrorBody", "ErrorCode", diff --git a/src/api/schemas/attachment.py b/src/api/schemas/attachment.py new file mode 100644 index 00000000..1859aa90 --- /dev/null +++ b/src/api/schemas/attachment.py @@ -0,0 +1,64 @@ +import unicodedata +from typing import Annotated, Any, Literal +from uuid import UUID + +from pydantic import AfterValidator, BaseModel, BeforeValidator, ConfigDict + +from src.api.schemas.common import UtcDatetime +from src.schemas.enums import ImageType +from src.utils.constants import ( + ATTACHMENT_FILENAME_FORBIDDEN_CATEGORY, + ATTACHMENT_FILENAME_FORBIDDEN_CHARS, +) + + +def _check_filename(value: str) -> str: + """Отображаемое имя: отказ только по списку контракта. + + `/`, `\\`, управляющие символы категории Cc (U+0000–U+001F, + U+007F–U+009F) и строка из одних пробелов — 400. Символы + форматирования и направления текста (Cf), разделители строк и абзацев + принимаются (design change `attachments`, решение 10). Значение не + меняется. + """ + if not value.strip(): + raise ValueError("must not be blank") + for char in value: + if ( + char in ATTACHMENT_FILENAME_FORBIDDEN_CHARS + or unicodedata.category(char) + == ATTACHMENT_FILENAME_FORBIDDEN_CATEGORY + ): + raise ValueError( + "must not contain path separators or control characters", + ) + return value + + +def _sha256_hex(value: object) -> object: + """SHA-256 из DTO — байты; в ответе — hex в нижнем регистре.""" + return value.hex() if isinstance(value, bytes) else value + + +# длина 1–255 — в Query ручки: так она есть в /openapi.json +DisplayFilename = Annotated[str, AfterValidator(_check_filename)] + + +class Attachment(BaseModel): + """Схема контракта `Attachment`; ключа объекта в ней нет.""" + + model_config = ConfigDict(from_attributes=True) + + id: UUID + chat_id: UUID + owner_id: UUID + filename: str + content_type: ImageType + size_bytes: int + sha256: Annotated[str, BeforeValidator(_sha256_hex)] + # API показывает только готовые вложения; варианты — с лабы 5 + status: Literal["ready"] + variants: list[dict[str, Any]] = [] + error_code: None = None + created_at: UtcDatetime + updated_at: UtcDatetime diff --git a/src/api/schemas/message.py b/src/api/schemas/message.py index b8109859..2c23f5f3 100644 --- a/src/api/schemas/message.py +++ b/src/api/schemas/message.py @@ -1,24 +1,40 @@ +from typing import Self from uuid import UUID -from pydantic import BaseModel, ConfigDict, Field +from pydantic import BaseModel, ConfigDict, Field, StrictStr, model_validator -from src.api.schemas.common import NonBlankStr, UtcDatetime +from src.api.schemas.common import UtcDatetime, UuidIn from src.utils.constants import ( + MESSAGE_ATTACHMENTS_MAX, MESSAGE_TEXT_MAX_LENGTH, - MESSAGE_TEXT_MIN_LENGTH, ) class CreateMessage(BaseModel): - """Отправитель берётся из идентификации; поле sender_id — 400.""" + """Отправитель берётся из идентификации; поле sender_id — 400. + + Пустой текст — `""` или из одних пробельных символов — допустим + только с хотя бы одним вложением (согласовано с преподавателем + 2026-10-20, AGENTS.md). Текст не обрезается и не нормализуется. + """ model_config = ConfigDict(extra="forbid") - text: NonBlankStr = Field( - min_length=MESSAGE_TEXT_MIN_LENGTH, - max_length=MESSAGE_TEXT_MAX_LENGTH, + text: StrictStr = Field(max_length=MESSAGE_TEXT_MAX_LENGTH) + # элементы — запись UUID контракта; повтор (и в другом регистре) — 400 + attachment_ids: list[UuidIn] = Field( + default_factory=list, + max_length=MESSAGE_ATTACHMENTS_MAX, ) + @model_validator(mode="after") + def _check_text_and_attachments(self) -> Self: + if len(set(self.attachment_ids)) != len(self.attachment_ids): + raise ValueError("attachment_ids must be unique") + if not self.text.strip() and not self.attachment_ids: + raise ValueError("text must not be blank without attachments") + return self + class Message(BaseModel): model_config = ConfigDict(from_attributes=True) @@ -28,6 +44,7 @@ class Message(BaseModel): sender_id: UUID text: str created_at: UtcDatetime + attachment_ids: list[UUID] class MessagePage(BaseModel): diff --git a/src/core/exceptions/__init__.py b/src/core/exceptions/__init__.py index 78f6176c..3708c219 100644 --- a/src/core/exceptions/__init__.py +++ b/src/core/exceptions/__init__.py @@ -1,3 +1,10 @@ +from .attachment import ( + AttachmentContentMissing, + AttachmentNotFound, + PayloadTooLarge, + UnsupportedMediaType, + UploadInterrupted, +) from .base import DomainError from .chat import ChatNotFound, InvalidChatMembers from .idempotency import IdempotencyConflict @@ -8,6 +15,8 @@ from .storage import ObjectStorageUnavailable, StoredObjectMissing from .user import UsernameTaken __all__ = [ + "AttachmentContentMissing", + "AttachmentNotFound", "ChatNotFound", "DomainError", "IdempotencyConflict", @@ -15,8 +24,11 @@ __all__ = [ "InvalidCredentials", "InvalidCursor", "ObjectStorageUnavailable", + "PayloadTooLarge", "ServiceUnavailable", "StoredObjectMissing", "Unauthenticated", + "UnsupportedMediaType", + "UploadInterrupted", "UsernameTaken", ] diff --git a/src/core/exceptions/attachment.py b/src/core/exceptions/attachment.py new file mode 100644 index 00000000..28348ff5 --- /dev/null +++ b/src/core/exceptions/attachment.py @@ -0,0 +1,39 @@ +from .base import DomainError + + +class AttachmentNotFound(DomainError): + """Вложения нет, оно чужое или ещё не готово (`pending`). + + Все случаи — одно исключение и одинаковый 404: ответ не раскрывает + существование чужого вложения. + """ + + default_message = "Not found" + + +class PayloadTooLarge(DomainError): + """Тело больше 10 MiB или изображение больше 40 млн пикселей.""" + + default_message = "Payload too large" + + +class UnsupportedMediaType(DomainError): + """Не PNG и не JPEG, подмена MIME или повреждённое изображение.""" + + default_message = "Unsupported media type" + + +class UploadInterrupted(DomainError): + """Клиент оборвал передачу тела загрузки.""" + + default_message = "Upload interrupted" + + +class AttachmentContentMissing(DomainError): + """У готового вложения нет объекта в S3 или его размер другой. + + Расхождение хранилищ, а не ошибка клиента: 500 без деталей, причина — + в журнале сервиса. + """ + + default_message = "Internal server error" diff --git a/src/core/repos/attachment.py b/src/core/repos/attachment.py new file mode 100644 index 00000000..2c788fb4 --- /dev/null +++ b/src/core/repos/attachment.py @@ -0,0 +1,107 @@ +"""Метаданные вложений в PostgreSQL. + +Строка пишется в статусе `pending` до записи объекта и переводится в +`ready` после неё (design change `attachments`, решение 1). Видимость +`pending` решает сервис: repo отдаёт строку как есть. +""" + +from collections.abc import Collection +from datetime import datetime +from uuid import UUID + +from sqlalchemy import Row, insert, select, update +from sqlalchemy.ext.asyncio import AsyncSession + +from src.infra.db.models import Attachment +from src.schemas import dataclasses +from src.schemas.enums import AttachmentStatus, ImageType + +_ATTACHMENT_COLUMNS = ( + Attachment.id, + Attachment.chat_id, + Attachment.owner_id, + Attachment.filename, + Attachment.content_type, + Attachment.size_bytes, + Attachment.sha256, + Attachment.object_key, + Attachment.status, + Attachment.created_at, + Attachment.updated_at, +) + + +def _to_dto(row: Row) -> dataclasses.AttachmentFullDTO: + fields = dict(row._mapping) + fields["content_type"] = ImageType(fields["content_type"]) + fields["status"] = AttachmentStatus(fields["status"]) + return dataclasses.AttachmentFullDTO(**fields) + + +async def insert_attachment( + db_session: AsyncSession, + *, + attachment: dataclasses.AttachmentFullDTO, +) -> dataclasses.AttachmentFullDTO: + """Строка вложения со всеми колонками DTO.""" + await db_session.execute( + insert(Attachment).values( + id=attachment.id, + chat_id=attachment.chat_id, + owner_id=attachment.owner_id, + filename=attachment.filename, + content_type=attachment.content_type.value, + size_bytes=attachment.size_bytes, + sha256=attachment.sha256, + object_key=attachment.object_key, + status=attachment.status.value, + created_at=attachment.created_at, + updated_at=attachment.updated_at, + ), + ) + return attachment + + +async def mark_ready( + db_session: AsyncSession, + *, + attachment_id: UUID, + updated_at: datetime, +) -> dataclasses.AttachmentFullDTO | None: + """`pending` → `ready`; `None` — строки в статусе `pending` нет.""" + statement = ( + update(Attachment) + .where( + Attachment.id == attachment_id, + Attachment.status == AttachmentStatus.PENDING.value, + ) + .values(status=AttachmentStatus.READY.value, updated_at=updated_at) + .returning(*_ATTACHMENT_COLUMNS) + ) + row = (await db_session.execute(statement)).one_or_none() + return None if row is None else _to_dto(row) + + +async def get_attachment( + db_session: AsyncSession, + *, + attachment_id: UUID, +) -> dataclasses.AttachmentFullDTO | None: + statement = select(*_ATTACHMENT_COLUMNS).where( + Attachment.id == attachment_id, + ) + row = (await db_session.execute(statement)).one_or_none() + return None if row is None else _to_dto(row) + + +async def get_attachments( + db_session: AsyncSession, + *, + attachment_ids: Collection[UUID], +) -> list[dataclasses.AttachmentFullDTO]: + """Найденные строки по первичному ключу, в любом порядке.""" + statement = select(*_ATTACHMENT_COLUMNS).where( + Attachment.id.in_(attachment_ids), + ) + rows = (await db_session.execute(statement)).all() + return [_to_dto(row) for row in rows] diff --git a/src/core/repos/attachment_object.py b/src/core/repos/attachment_object.py new file mode 100644 index 00000000..dcf1c539 --- /dev/null +++ b/src/core/repos/attachment_object.py @@ -0,0 +1,49 @@ +"""Оригинал вложения в S3: ключ объекта и операции над ним. + +Repo над хранилищем объектов, как `chat_cache.py` над Valkey: первый +параметр — `storage`, один вызов на функцию. Ключ — +`<имя базы>/attachments//original` (design change `attachments`, +решение 4): назначает сервер, `filename` в него не входит; объекты +`make test_isolated` лежат под `test_/`. Ключ хранится в строке +вложения и при чтении берётся оттуда. +""" + +from contextlib import AbstractAsyncContextManager +from uuid import UUID + +from src.infra.s3 import ObjectStorage, StoredObject +from src.utils.constants import ( + ATTACHMENT_KEY_PREFIX, + ATTACHMENT_ORIGINAL_SUFFIX, + S3_KEY_SEPARATOR, +) + + +def original_key(storage: ObjectStorage, *, attachment_id: UUID) -> str: + return S3_KEY_SEPARATOR.join( + ( + storage.namespace, + ATTACHMENT_KEY_PREFIX, + str(attachment_id), + ATTACHMENT_ORIGINAL_SUFFIX, + ), + ) + + +async def put_original( + storage: ObjectStorage, + *, + key: str, + data: bytes, + content_type: str, +) -> None: + await storage.put(key, data, content_type=content_type) + + +def open_original( + storage: ObjectStorage, + *, + key: str, +) -> AbstractAsyncContextManager[StoredObject]: + """Объект на чтение блоками; нет объекта — `StoredObjectMissing`.""" + return storage.open(key) diff --git a/src/core/repos/idempotency.py b/src/core/repos/idempotency.py index 241a87b1..5d229da6 100644 --- a/src/core/repos/idempotency.py +++ b/src/core/repos/idempotency.py @@ -12,7 +12,7 @@ from sqlalchemy import select from sqlalchemy.dialects.postgresql import insert as pg_insert from sqlalchemy.ext.asyncio import AsyncSession -from src.core.repos.message import MESSAGE_COLUMNS +from src.core.repos.message import MESSAGE_COLUMNS, to_message_dto from src.infra.db.models import IdempotencyKey, Message from src.schemas import dataclasses @@ -69,7 +69,8 @@ async def get_key_result( chat_id: UUID, key: str, ) -> dataclasses.IdempotencyRecordDTO | None: - """Хэш тела и сообщение, сохранённые под ключом; None — ключа нет.""" + """Хэш тела и сообщение с вложениями, сохранённые под ключом; None — + ключа нет.""" statement = ( select(IdempotencyKey.request_hash, *MESSAGE_COLUMNS) .join(Message, Message.id == IdempotencyKey.message_id) @@ -82,9 +83,7 @@ async def get_key_result( row = (await db_session.execute(statement)).one_or_none() if row is None: return None - fields = dict(row._mapping) - request_hash = fields.pop("request_hash") return dataclasses.IdempotencyRecordDTO( - request_hash=request_hash, - message=dataclasses.MessageFullDTO(**fields), + request_hash=row.request_hash, + message=to_message_dto(row._mapping), ) diff --git a/src/core/repos/message.py b/src/core/repos/message.py index a8c6d920..4de711e2 100644 --- a/src/core/repos/message.py +++ b/src/core/repos/message.py @@ -1,13 +1,27 @@ -from dataclasses import asdict +from collections.abc import Mapping +from typing import Any from uuid import UUID -from sqlalchemy import insert, select, tuple_ +from sqlalchemy import Uuid, func, insert, select, tuple_ +from sqlalchemy.dialects.postgresql import ARRAY from sqlalchemy.ext.asyncio import AsyncSession -from src.infra.db.models import Message +from src.infra.db.models import Message, MessageAttachment from src.schemas import dataclasses from src.utils.cursor import CursorKey +# вложения сообщения в порядке отправки: коррелированный подзапрос по +# первичному ключу `(message_id, position)` на каждую строку страницы, +# индекс истории прежний (design change `attachments`, решение 8). Нет +# вложений — пустой массив, а не NULL +_ATTACHMENT_IDS = func.array( + select(MessageAttachment.attachment_id) + .where(MessageAttachment.message_id == Message.id) + .order_by(MessageAttachment.position) + .scalar_subquery(), + type_=ARRAY(Uuid()), +).label("attachment_ids") + # колонки MessageFullDTO; их же выбирает чтение сохранённого результата # ключа идемпотентности MESSAGE_COLUMNS = ( @@ -16,23 +30,72 @@ MESSAGE_COLUMNS = ( Message.sender_id, Message.text, Message.created_at, + _ATTACHMENT_IDS, ) +def to_message_dto(fields: Mapping[str, Any]) -> dataclasses.MessageFullDTO: + """DTO из колонок `MESSAGE_COLUMNS`.""" + return dataclasses.MessageFullDTO( + id=fields["id"], + chat_id=fields["chat_id"], + sender_id=fields["sender_id"], + text=fields["text"], + created_at=fields["created_at"], + attachment_ids=tuple(fields["attachment_ids"]), + ) + + async def insert_message( db_session: AsyncSession, *, message: dataclasses.MessageFullDTO, instance_id: str, ) -> dataclasses.MessageFullDTO: - """Вставка сообщения; `instance_id` — реплика, которая его записала - (колонка только для диагностики, в DTO и ответ не попадает).""" + """Строка сообщения; `instance_id` — реплика, которая его записала + (колонка только для диагностики, в DTO и ответ не попадает). Связи с + вложениями пишет `insert_message_attachments`.""" await db_session.execute( - insert(Message).values(**asdict(message), instance_id=instance_id), + insert(Message).values( + id=message.id, + chat_id=message.chat_id, + sender_id=message.sender_id, + text=message.text, + created_at=message.created_at, + instance_id=instance_id, + ), ) return message +async def insert_message_attachments( + db_session: AsyncSession, + *, + message: dataclasses.MessageFullDTO, +) -> int: + """Все связи одной вставкой; `position` — место в `attachment_ids`. + + Вызывается только с непустым `attachment_ids`. `created_at` связи — + время сообщения. + """ + result = await db_session.execute( + insert(MessageAttachment).values( + [ + { + "message_id": message.id, + "position": position, + "attachment_id": attachment_id, + "created_at": message.created_at, + } + for position, attachment_id in enumerate( + message.attachment_ids, + ) + ], + ), + ) + return result.rowcount + + async def get_chat_messages_page( db_session: AsyncSession, *, @@ -56,4 +119,4 @@ async def get_chat_messages_page( tuple_(Message.created_at, Message.id) > tuple_(*after), ) rows = (await db_session.execute(statement)).all() - return [dataclasses.MessageFullDTO(**row._mapping) for row in rows] + return [to_message_dto(row._mapping) for row in rows] diff --git a/src/core/services/__init__.py b/src/core/services/__init__.py index e25f760e..4b149188 100644 --- a/src/core/services/__init__.py +++ b/src/core/services/__init__.py @@ -1,9 +1,11 @@ +from .attachment import AttachmentService from .chat import ChatService from .message import MessageService from .session import SessionService from .user import UserService __all__ = [ + "AttachmentService", "ChatService", "MessageService", "SessionService", diff --git a/src/core/services/attachment.py b/src/core/services/attachment.py new file mode 100644 index 00000000..de1a3eb8 --- /dev/null +++ b/src/core/services/attachment.py @@ -0,0 +1,293 @@ +import hashlib +import time +from collections.abc import AsyncIterator, Callable +from contextlib import AbstractAsyncContextManager, AsyncExitStack +from uuid import UUID, uuid4 + +import anyio.to_thread +from sqlalchemy.ext.asyncio import AsyncSession + +from src.core import exceptions +from src.core.repos import attachment as attachment_repo +from src.core.repos import attachment_object as attachment_object_repo +from src.core.services.chat import ChatService +from src.infra.cache import Cache +from src.infra.logger import AbstractLogger, get_logger +from src.infra.s3 import ObjectStorage +from src.schemas import dataclasses +from src.schemas.enums import AttachmentStatus, ImageType +from src.utils.constants import ATTACHMENT_MAX_BYTES, ATTACHMENT_MAX_PIXELS +from src.utils.image import ( + DamagedImage, + ImageInfo, + TooManyPixels, + UnsupportedImage, + inspect_image, +) +from src.utils.utc import utcnow + +logger: AbstractLogger = get_logger().bind(module="attachment_service") + +# Content-Type загрузки: тип без параметров, в нижнем регистре +_ACCEPTED_MEDIA_TYPES = frozenset(image_type.value for image_type in ImageType) + +# короткая сессия БД на один шаг: `db_session_scope` слоя API +type DbScope = Callable[[], AbstractAsyncContextManager[AsyncSession]] + + +def _inspect(data: bytes) -> tuple[ImageInfo, bytes]: + """Структура изображения и SHA-256 — одним вызовом в потоке.""" + info = inspect_image(data, max_pixels=ATTACHMENT_MAX_PIXELS) + return info, hashlib.sha256(data).digest() + + +class AttachmentService: + """Вложения: загрузка в S3 с метаданными в PostgreSQL, чтение, отдача. + + Сессии на весь запрос нет: каждый шаг с БД — свой короткий + `async with self.db_scope()`, без вложенных, поэтому ни одно + соединение пула не занято передачей тела (design change + `attachments`, решение 5). `filename` в журнал не пишется. + """ + + def __init__( + self, + db_scope: DbScope, + cache: Cache, + storage: ObjectStorage, + ) -> None: + self.db_scope = db_scope + self.cache = cache + self.storage = storage + + async def _require_member( + self, + *, + db_session: AsyncSession, + chat_id: UUID, + user_id: UUID, + ) -> None: + await ChatService( + db_session=db_session, + cache=self.cache, + ).get_chat_for_member(chat_id=chat_id, user_id=user_id) + + async def upload( + self, + *, + chat_id: UUID, + owner_id: UUID, + filename: str, + media_type: str | None, + content_length: int | None, + body: AsyncIterator[bytes], + ) -> dataclasses.AttachmentFullDTO: + """Загрузка оригинала; 201 только после `ready` в БД. + + Порядок проверок — спек «Порядок проверок загрузки»: членство + (404), `Content-Type` (415), `Content-Length` (413), затем тело со + счётчиком (413) и содержимое (415 или 413). Порядок записи + (решение 1): строка `pending` с ключом объекта — commit, PUT, + `ready` — commit. Отказ S3 или БД после строки `pending` — 503, + строка остаётся до уборщика (`upload-consistency`). + """ + started = time.monotonic() + log = logger.bind( + method="upload", + chat_id=chat_id, + filename_length=len(filename), + ) + async with self.db_scope() as db_session: + await self._require_member( + db_session=db_session, + chat_id=chat_id, + user_id=owner_id, + ) + if media_type not in _ACCEPTED_MEDIA_TYPES: + log.info("Rejected attachment", reason="type") + raise exceptions.UnsupportedMediaType + if ( + content_length is not None + and content_length > ATTACHMENT_MAX_BYTES + ): + log.info( + "Rejected attachment", + reason="declared_size", + declared_size=content_length, + ) + raise exceptions.PayloadTooLarge + data = await self._read_body(body=body, log=log) + try: + info, sha256 = await anyio.to_thread.run_sync(_inspect, data) + except TooManyPixels as e: + log.info("Rejected attachment", reason="pixels") + raise exceptions.PayloadTooLarge from e + except DamagedImage as e: + log.info("Rejected attachment", reason="damaged") + raise exceptions.UnsupportedMediaType from e + except UnsupportedImage as e: + log.info("Rejected attachment", reason="content") + raise exceptions.UnsupportedMediaType from e + if info.content_type != media_type: + log.info("Rejected attachment", reason="content_mismatch") + raise exceptions.UnsupportedMediaType + + attachment_id = uuid4() + now = utcnow() + pending = dataclasses.AttachmentFullDTO( + id=attachment_id, + chat_id=chat_id, + owner_id=owner_id, + filename=filename, + content_type=info.content_type, + size_bytes=len(data), + sha256=sha256, + object_key=attachment_object_repo.original_key( + self.storage, + attachment_id=attachment_id, + ), + status=AttachmentStatus.PENDING, + created_at=now, + updated_at=now, + ) + async with self.db_scope() as db_session: + await attachment_repo.insert_attachment( + db_session=db_session, + attachment=pending, + ) + await db_session.commit() + await attachment_object_repo.put_original( + self.storage, + key=pending.object_key, + data=data, + content_type=pending.content_type.value, + ) + async with self.db_scope() as db_session: + ready = await attachment_repo.mark_ready( + db_session=db_session, + attachment_id=attachment_id, + updated_at=utcnow(), + ) + await db_session.commit() + if ready is None: + # строку pending удалить некому, пока нет уборщика: ветку + # переопределит change upload-consistency + raise RuntimeError("Pending attachment disappeared before ready") + log.info( + "Uploaded attachment", + attachment_id=attachment_id, + size_bytes=ready.size_bytes, + content_type=ready.content_type, + width=info.width, + height=info.height, + duration_ms=round((time.monotonic() - started) * 1000), + ) + return ready + + async def _read_body( + self, + *, + body: AsyncIterator[bytes], + log: AbstractLogger, + ) -> bytes: + """Тело целиком; больше лимита — 413 сразу, без дочитывания.""" + buffer = bytearray() + try: + async for chunk in body: + if len(buffer) + len(chunk) > ATTACHMENT_MAX_BYTES: + log.info( + "Rejected attachment", + reason="size", + size=len(buffer) + len(chunk), + ) + raise exceptions.PayloadTooLarge + buffer += chunk + except exceptions.UploadInterrupted: + log.info("Rejected attachment", reason="interrupted") + raise + return bytes(buffer) + + async def get_attachment( + self, + *, + attachment_id: UUID, + user_id: UUID, + ) -> dataclasses.AttachmentFullDTO: + """Готовое вложение для участника его чата; иначе 404. + + Нет строки, она `pending` или пользователь не участник — + одинаковый `AttachmentNotFound`. + """ + async with self.db_scope() as db_session: + attachment = await attachment_repo.get_attachment( + db_session=db_session, + attachment_id=attachment_id, + ) + if ( + attachment is None + or attachment.status != AttachmentStatus.READY + ): + raise exceptions.AttachmentNotFound + try: + await self._require_member( + db_session=db_session, + chat_id=attachment.chat_id, + user_id=user_id, + ) + except exceptions.ChatNotFound as e: + raise exceptions.AttachmentNotFound from e + return attachment + + async def open_content( + self, + *, + attachment_id: UUID, + user_id: UUID, + ) -> dataclasses.AttachmentContentDTO: + """Оригинал потоком из S3 (решение 7). + + Отказ S3 — 503 до заголовков ответа. Нет объекта или размер в S3 + другой — `error` в журнале и 500; строку сервис не меняет. + """ + attachment = await self.get_attachment( + attachment_id=attachment_id, + user_id=user_id, + ) + log = logger.bind( + method="open_content", + attachment_id=attachment_id, + object_key=attachment.object_key, + ) + stack = AsyncExitStack() + try: + stored = await stack.enter_async_context( + attachment_object_repo.open_original( + self.storage, + key=attachment.object_key, + ), + ) + except exceptions.StoredObjectMissing as e: + log.error("Attachment content is missing") + raise exceptions.AttachmentContentMissing from e + if stored.size != attachment.size_bytes: + await stack.aclose() + log.error( + "Attachment content size differs", + size_bytes=attachment.size_bytes, + stored_size=stored.size, + ) + raise exceptions.AttachmentContentMissing + + async def chunks() -> AsyncIterator[bytes]: + try: + async for chunk in stored.iter_chunks(): + yield chunk + finally: + await stack.aclose() + + return dataclasses.AttachmentContentDTO( + content_type=attachment.content_type, + size_bytes=attachment.size_bytes, + chunks=chunks(), + close=stack.aclose, + ) diff --git a/src/core/services/message.py b/src/core/services/message.py index b9606bb6..fff5bc06 100644 --- a/src/core/services/message.py +++ b/src/core/services/message.py @@ -1,5 +1,6 @@ import hashlib import json +from collections.abc import Sequence from datetime import timedelta from uuid import UUID, uuid4 @@ -7,6 +8,7 @@ from sqlalchemy.ext.asyncio import AsyncSession from src.config import settings from src.core import exceptions +from src.core.repos import attachment as attachment_repo from src.core.repos import idempotency as idempotency_repo from src.core.repos import message as message_repo from src.core.services.chat import ChatService @@ -14,22 +16,33 @@ from src.core.services.pagination import decode_page_cursor, split_page from src.infra.cache import Cache from src.infra.logger import AbstractLogger, get_logger from src.schemas import dataclasses +from src.schemas.enums import AttachmentStatus from src.utils.cursor import chat_messages_scope from src.utils.utc import utcnow logger: AbstractLogger = get_logger().bind(module="message_service") -def message_request_hash(*, text: str) -> bytes: +def message_request_hash( + *, + text: str, + attachment_ids: Sequence[UUID] = (), +) -> bytes: """SHA-256 канонического JSON тела отправки сообщения. Тело собирается из аргументов сервиса, то есть уже разобранное: - пробелы, экранирование и порядок полей запроса на хэш не влияют. Новое - поле тела (с лабы 4 — `attachment_ids`) добавляется сюда со - значением по умолчанию, чтобы отсутствующее поле равнялось явному. + пробелы, экранирование и порядок полей запроса на хэш не влияют. + `attachment_ids` входит в тело только непустым: отсутствующее поле + равно `[]`, и ключ, сохранённый версией без вложений, повторяется + после замены реплик. id — `str(UUID)`, нижний регистр: регистр в + запросе хэш не меняет, порядок элементов меняет (design change + `attachments`, решение 9). """ + body: dict[str, object] = {"text": text} + if attachment_ids: + body["attachment_ids"] = [str(item) for item in attachment_ids] canonical = json.dumps( - {"text": text}, + body, ensure_ascii=False, sort_keys=True, separators=(",", ":"), @@ -54,15 +67,22 @@ class MessageService: sender_id: UUID, text: str, idempotency_key: str, + attachment_ids: Sequence[UUID] = (), ) -> dataclasses.MessageFullDTO: """Отправка с ключом идемпотентности. - Ключ и сообщение пишутся одной транзакцией, ключ — первым. Повтор - того же тела возвращает сохранённое сообщение, другое тело — - `IdempotencyConflict` (design change `instance-id-idempotency`, - решения 2–5). Ключ не логируется. + Ключ, сообщение и его связи с вложениями пишутся одной + транзакцией, ключ — первым. Повтор того же тела возвращает + сохранённое сообщение, другое тело — `IdempotencyConflict` + (design change `instance-id-idempotency`, решения 2–5). Вложения + проверяются до захвата ключа: ошибка его не занимает (design + change `attachments`, решение 8). Ключ не логируется. """ - log = logger.bind(method="send_message", chat_id=chat_id) + log = logger.bind( + method="send_message", + chat_id=chat_id, + attachments_count=len(attachment_ids), + ) # состав чата не меняется, поэтому проверка членства (в том числе # по кэшу) не устареет; составные внешние ключи сообщения и ключа # идемпотентности — страховка на уровне БД. Повтор проходит её @@ -71,14 +91,24 @@ class MessageService: chat_id=chat_id, user_id=sender_id, ) + if attachment_ids: + await self._require_ready_attachments( + chat_id=chat_id, + attachment_ids=attachment_ids, + log=log, + ) now = utcnow() - request_hash = message_request_hash(text=text) + request_hash = message_request_hash( + text=text, + attachment_ids=attachment_ids, + ) message = dataclasses.MessageFullDTO( id=uuid4(), chat_id=chat_id, sender_id=sender_id, text=text, created_at=now, + attachment_ids=tuple(attachment_ids), ) claimed = await idempotency_repo.claim_key( db_session=self.db_session, @@ -97,6 +127,11 @@ class MessageService: message=message, instance_id=settings.app.instance_id, ) + if attachment_ids: + await message_repo.insert_message_attachments( + db_session=self.db_session, + message=message, + ) # отложенная проверка ссылки ключа на сообщение — здесь await self.db_session.commit() log.info( @@ -128,6 +163,34 @@ class MessageService: ) return saved.message + async def _require_ready_attachments( + self, + *, + chat_id: UUID, + attachment_ids: Sequence[UUID], + log: AbstractLogger, + ) -> None: + """Каждое вложение — готовое вложение этого чата; иначе 404. + + Неизвестное, другого чата и `pending` неразличимы. Чат вложения не + меняется, а `ready` не откатывается, поэтому проверка в этой же + транзакции не устареет до commit; существование держит ещё и + внешний ключ связи. + """ + found = await attachment_repo.get_attachments( + db_session=self.db_session, + attachment_ids=attachment_ids, + ) + ready = { + attachment.id + for attachment in found + if attachment.chat_id == chat_id + and attachment.status == AttachmentStatus.READY + } + if not ready.issuperset(attachment_ids): + log.info("Rejected message attachments") + raise exceptions.AttachmentNotFound + async def list_messages( self, *, diff --git a/src/infra/db/models/__init__.py b/src/infra/db/models/__init__.py index 98241372..744aa030 100644 --- a/src/infra/db/models/__init__.py +++ b/src/infra/db/models/__init__.py @@ -1,6 +1,7 @@ """Модели БД. Новая модель импортируется здесь, иначе autogenerate её не видит.""" +from src.infra.db.models.attachment import Attachment, MessageAttachment from src.infra.db.models.base import Base from src.infra.db.models.chat import Chat, ChatMember from src.infra.db.models.idempotency import IdempotencyKey @@ -9,11 +10,13 @@ from src.infra.db.models.session import Session from src.infra.db.models.user import User __all__ = [ + "Attachment", "Base", "Chat", "ChatMember", "IdempotencyKey", "Message", + "MessageAttachment", "Session", "User", ] diff --git a/src/infra/db/models/attachment.py b/src/infra/db/models/attachment.py new file mode 100644 index 00000000..783ae5c0 --- /dev/null +++ b/src/infra/db/models/attachment.py @@ -0,0 +1,117 @@ +from datetime import datetime +from uuid import UUID + +from sqlalchemy import ( + CheckConstraint, + DateTime, + ForeignKey, + ForeignKeyConstraint, + Index, + Integer, + LargeBinary, + SmallInteger, + Text, + UniqueConstraint, +) +from sqlalchemy.orm import Mapped, mapped_column + +from src.infra.db.models.base import Base +from src.utils.constants import ( + ATTACHMENT_FILENAME_MAX_LENGTH, + ATTACHMENT_FILENAME_MIN_LENGTH, + ATTACHMENT_MAX_BYTES, + ATTACHMENT_SHA256_BYTES, + MESSAGE_ATTACHMENTS_MAX, + OBJECT_KEY_MAX_BYTES, +) + + +class Attachment(Base): + """Метаданные вложения; байты — объект `object_key` в S3. + + Строка пишется в статусе `pending` до записи объекта и становится + `ready` после неё (design change `attachments`, решение 1). Владелец — + участник чата вложения: проверяет сама БД. + """ + + __tablename__ = "attachments" + __table_args__ = ( + ForeignKeyConstraint( + ["chat_id", "owner_id"], + ["chat_members.chat_id", "chat_members.user_id"], + ), + CheckConstraint( + "char_length(filename) BETWEEN " + f"{ATTACHMENT_FILENAME_MIN_LENGTH} " + f"AND {ATTACHMENT_FILENAME_MAX_LENGTH}", + name="filename_length", + ), + # контракт: без `/`, `\` и управляющих символов (Cc); NUL в text + # PostgreSQL не бывает. Внутри скобок ARE `\\` — обратная косая + CheckConstraint( + r"filename !~ '[/\\\u0001-\u001f\u007f-\u009f]'", + name="filename_chars", + ), + CheckConstraint( + "content_type IN ('image/png', 'image/jpeg')", + name="content_type", + ), + CheckConstraint( + f"size_bytes BETWEEN 1 AND {ATTACHMENT_MAX_BYTES}", + name="size_bytes", + ), + CheckConstraint( + f"octet_length(sha256) = {ATTACHMENT_SHA256_BYTES}", + name="sha256_length", + ), + CheckConstraint( + f"octet_length(object_key) BETWEEN 1 AND {OBJECT_KEY_MAX_BYTES}", + name="object_key_length", + ), + CheckConstraint( + "status IN ('pending', 'ready')", + name="status", + ), + CheckConstraint( + "updated_at >= created_at", + name="updated_after_created", + ), + ) + + id: Mapped[UUID] = mapped_column(primary_key=True) + chat_id: Mapped[UUID] + owner_id: Mapped[UUID] + filename: Mapped[str] = mapped_column(Text) + content_type: Mapped[str] = mapped_column(Text) + size_bytes: Mapped[int] = mapped_column(Integer) + sha256: Mapped[bytes] = mapped_column(LargeBinary) + object_key: Mapped[str] = mapped_column(Text, unique=True) + status: Mapped[str] = mapped_column(Text) + updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + + +class MessageAttachment(Base): + """Вложение в сообщении; `position` — место в `attachment_ids`. + + Внешние ключи без каскада: вложение, на которое ссылается сообщение, + БД удалить не даст. Индекс по `attachment_id` — для удаления строки + вложения (проверка FK) и вопроса «на вложение ссылаются сообщения?». + `created_at` — время сообщения, как у участников чата — время чата. + """ + + __tablename__ = "message_attachments" + __table_args__ = ( + UniqueConstraint("message_id", "attachment_id"), + CheckConstraint( + f"position BETWEEN 0 AND {MESSAGE_ATTACHMENTS_MAX - 1}", + name="position_range", + ), + Index(None, "attachment_id"), + ) + + message_id: Mapped[UUID] = mapped_column( + ForeignKey("messages.id"), + primary_key=True, + ) + position: Mapped[int] = mapped_column(SmallInteger, primary_key=True) + attachment_id: Mapped[UUID] = mapped_column(ForeignKey("attachments.id")) diff --git a/src/infra/db/models/message.py b/src/infra/db/models/message.py index 2473d2a8..80497bb0 100644 --- a/src/infra/db/models/message.py +++ b/src/infra/db/models/message.py @@ -4,10 +4,7 @@ from sqlalchemy import CheckConstraint, ForeignKeyConstraint, Index, Text from sqlalchemy.orm import Mapped, mapped_column from src.infra.db.models.base import Base -from src.utils.constants import ( - MESSAGE_TEXT_MAX_LENGTH, - MESSAGE_TEXT_MIN_LENGTH, -) +from src.utils.constants import MESSAGE_TEXT_MAX_LENGTH class Message(Base): @@ -18,9 +15,12 @@ class Message(Base): ["chat_id", "sender_id"], ["chat_members.chat_id", "chat_members.user_id"], ), + # с лабы 4 пустой текст допустим вместе с вложением; правило + # «текст или вложение» держит сервис: числа вложений в строке нет. + # Ограничение ослаблено миграцией с NOT VALID (design change + # `attachments`, решение 3) CheckConstraint( - "char_length(text) BETWEEN " - f"{MESSAGE_TEXT_MIN_LENGTH} AND {MESSAGE_TEXT_MAX_LENGTH}", + f"char_length(text) <= {MESSAGE_TEXT_MAX_LENGTH}", name="text_length", ), # keyset истории: WHERE chat_id = ... AND (created_at, id) > (...) diff --git a/src/schemas/dataclasses/__init__.py b/src/schemas/dataclasses/__init__.py index 21b3e5ae..04118f17 100644 --- a/src/schemas/dataclasses/__init__.py +++ b/src/schemas/dataclasses/__init__.py @@ -1,3 +1,4 @@ +from .attachment import AttachmentContentDTO, AttachmentFullDTO from .chat import ChatFullDTO, ChatPageDTO from .idempotency import IdempotencyRecordDTO from .message import MessageFullDTO, MessagePageDTO @@ -5,6 +6,8 @@ from .session import CurrentSessionDTO, SessionFullDTO, SessionTokenDTO from .user import UserCredentialsDTO, UserFullDTO __all__ = [ + "AttachmentContentDTO", + "AttachmentFullDTO", "ChatFullDTO", "ChatPageDTO", "CurrentSessionDTO", diff --git a/src/schemas/dataclasses/attachment.py b/src/schemas/dataclasses/attachment.py new file mode 100644 index 00000000..ae5ccc78 --- /dev/null +++ b/src/schemas/dataclasses/attachment.py @@ -0,0 +1,43 @@ +from collections.abc import AsyncIterator, Awaitable, Callable +from dataclasses import dataclass +from datetime import datetime +from uuid import UUID + +from src.schemas.enums import AttachmentStatus, ImageType + + +@dataclass(frozen=True, slots=True) +class AttachmentFullDTO: + """Строка вложения: метаданные и ключ объекта в S3. + + `object_key` и статус `pending` в API не попадают; `sha256` — байты + SHA-256 оригинала, hex собирает модель ответа. + """ + + id: UUID + chat_id: UUID + owner_id: UUID + filename: str + content_type: ImageType + size_bytes: int + sha256: bytes + object_key: str + status: AttachmentStatus + created_at: datetime + updated_at: datetime + + +@dataclass(frozen=True, slots=True) +class AttachmentContentDTO: + """Оригинал вложения на отдачу потоком. + + `chunks` — блоки объекта из S3; `close` освобождает соединение с S3, + вызов повторно безопасен. Генератор вызывает его сам, когда поток + дочитан, оборван или упал; ответ — ещё раз фоновой задачей, если + генератор так и не начался. + """ + + content_type: ImageType + size_bytes: int + chunks: AsyncIterator[bytes] + close: Callable[[], Awaitable[None]] diff --git a/src/schemas/dataclasses/message.py b/src/schemas/dataclasses/message.py index 873e1320..a58290e6 100644 --- a/src/schemas/dataclasses/message.py +++ b/src/schemas/dataclasses/message.py @@ -10,6 +10,8 @@ class MessageFullDTO: sender_id: UUID text: str created_at: datetime + # вложения в порядке отправки; в БД — таблица message_attachments + attachment_ids: tuple[UUID, ...] = () @dataclass(frozen=True, slots=True) diff --git a/src/schemas/enums/__init__.py b/src/schemas/enums/__init__.py index 27e394de..a3c6b217 100644 --- a/src/schemas/enums/__init__.py +++ b/src/schemas/enums/__init__.py @@ -1,5 +1,8 @@ +from .attachment import AttachmentStatus, ImageType from .settings import RunModeEnum __all__ = [ + "AttachmentStatus", + "ImageType", "RunModeEnum", ] diff --git a/src/schemas/enums/attachment.py b/src/schemas/enums/attachment.py new file mode 100644 index 00000000..a3d95ef5 --- /dev/null +++ b/src/schemas/enums/attachment.py @@ -0,0 +1,20 @@ +from enum import StrEnum + + +class AttachmentStatus(StrEnum): + """Состояние вложения в БД. + + `pending` — строка-намерение до записи объекта в S3, наружу не видна; + `ready` — оригинал и метаданные сохранены. Значения хранятся в БД + (`CHECK`), новое значение — миграция. + """ + + PENDING = "pending" + READY = "ready" + + +class ImageType(StrEnum): + """Тип изображения, определённый по содержимому.""" + + PNG = "image/png" + JPEG = "image/jpeg" diff --git a/src/utils/constants.py b/src/utils/constants.py index ee5e60d9..4f58e474 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -56,8 +56,32 @@ CHAT_MEMBERS_MIN = 1 CHAT_MEMBERS_MAX = 100 # сообщение +# пустой текст допустим только вместе с вложением: правило — в сервисе и +# схеме API, CHECK в БД — только верхняя граница (design change +# `attachments`, решение 3) MESSAGE_TEXT_MIN_LENGTH = 1 MESSAGE_TEXT_MAX_LENGTH = 4000 +MESSAGE_ATTACHMENTS_MAX = 10 + +# вложение (с лабы 4): лимиты контракта, это не настройки — skeleton +# называет их MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS +ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024 +ATTACHMENT_MAX_PIXELS = 40_000_000 +ATTACHMENT_FILENAME_MIN_LENGTH = 1 +ATTACHMENT_FILENAME_MAX_LENGTH = 255 +# запрещённые в filename символы по контракту: разделители пути и +# управляющие символы (категория Unicode Cc: U+0000–U+001F, U+007F–U+009F) +ATTACHMENT_FILENAME_FORBIDDEN_CHARS = frozenset({"/", "\\"}) +ATTACHMENT_FILENAME_FORBIDDEN_CATEGORY = "Cc" +# SHA-256 оригинала в БД — 32 байта +ATTACHMENT_SHA256_BYTES = 32 +# предел длины ключа объекта S3, байты +OBJECT_KEY_MAX_BYTES = 1024 +# ключ объекта: `<имя базы>/attachments//original` +ATTACHMENT_KEY_PREFIX = "attachments" +ATTACHMENT_ORIGINAL_SUFFIX = "original" +# блок чтения тела загрузки не больше этого, байты +ATTACHMENT_READ_CHUNK_BYTES = 64 * 1024 # пагинация PAGE_LIMIT_MIN = 1 diff --git a/src/utils/image.py b/src/utils/image.py new file mode 100644 index 00000000..6e9e8ee2 --- /dev/null +++ b/src/utils/image.py @@ -0,0 +1,393 @@ +"""Структурная проверка PNG и JPEG без декодирования пикселей. + +Тип — по сигнатуре, размеры — из заголовка до распаковки (IHDR у PNG, +кадр SOF у JPEG). Целостность (design change `attachments`, решение 2): + +- PNG: IHDR первым и с допустимыми полями, длина и CRC каждого чанка, + нет неизвестных критичных чанков, PLTE на своём месте, IDAT подряд, + поток zlib завершён и распакован ровно в объём по размерам, глубине и + чересстрочности, тип фильтра каждой строки ≤ 4, есть IEND; +- JPEG: маркеры и длины сегментов до EOI, один кадр с ненулевыми + размерами, хотя бы один скан после кадра, EOI есть. + +Байты после IEND и EOI допускаются: они часть оригинала. Искажение внутри +сжатых данных скана JPEG не обнаруживается: у формата нет контрольной +суммы. + +Память не зависит от числа пикселей: IDAT распаковывается блоками не +больше `_INFLATE_OUT_BYTES`, а вход подаётся кусками `_INFLATE_IN_BYTES`. +Строки проверяются срезом с шагом длины строки, конец данных скана JPEG +ищет регулярное выражение — оба в C, без цикла Python по строкам и +байтам. Только stdlib, без логов: бросает свои исключения, сервис +переводит их в доменные. +""" + +import re +import struct +import zlib +from dataclasses import dataclass + +from src.schemas.enums import ImageType + +PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n" +JPEG_SIGNATURE = b"\xff\xd8\xff" + +# выход распаковки за один вызов и кусок входа: пик памяти проверки — +# единицы MiB при любом числе пикселей +_INFLATE_OUT_BYTES = 1024 * 1024 +_INFLATE_IN_BYTES = 64 * 1024 + +# предел длины чанка PNG и размера по спецификации: 2^31 - 1 +_PNG_MAX_UINT = 2**31 - 1 +# допустимая глубина по типу цвета и число каналов +_PNG_DEPTHS: dict[int, frozenset[int]] = { + 0: frozenset({1, 2, 4, 8, 16}), + 2: frozenset({8, 16}), + 3: frozenset({1, 2, 4, 8}), + 4: frozenset({8, 16}), + 6: frozenset({8, 16}), +} +_PNG_CHANNELS = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4} +_PNG_PALETTE_TYPE = 3 +# PLTE запрещён у серых изображений +_PNG_NO_PALETTE_TYPES = frozenset({0, 4}) +# проходы Adam7: (x0, y0, dx, dy) +_ADAM7 = ( + (0, 0, 8, 8), + (4, 0, 8, 8), + (0, 4, 4, 8), + (2, 0, 4, 4), + (0, 2, 2, 4), + (1, 0, 2, 2), + (0, 1, 1, 2), +) +# типы фильтра строки 0–4: всё, что не они, остаётся после translate +_PNG_FILTER_TYPES = bytes(range(5)) + +# маркеры кадра: SOF0–3, 5–7, 9–11, 13–15 (C4 — DHT, C8 — JPG, CC — DAC) +_JPEG_SOF = frozenset( + {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7} + | {0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}, +) +_JPEG_SOI = 0xD8 +_JPEG_EOI = 0xD9 +_JPEG_SOS = 0xDA +_JPEG_TEM = 0x01 +_JPEG_RST = frozenset(range(0xD0, 0xD8)) +# конец данных скана: FF, за которым не 00 (вставка) и не RST0–7 +_JPEG_SCAN_END = re.compile(rb"\xff[^\x00\xd0-\xd7]") + + +class ImageError(ValueError): + """Изображение не прошло проверку.""" + + +class UnsupportedImage(ImageError): + """Не PNG и не JPEG.""" + + +class DamagedImage(ImageError): + """Структура изображения нарушена.""" + + +class TooManyPixels(ImageError): + """В заголовке больше пикселей, чем допускает лимит.""" + + +@dataclass(frozen=True, slots=True) +class ImageInfo: + content_type: ImageType + width: int + height: int + + +def inspect_image(data: bytes, *, max_pixels: int) -> ImageInfo: + """Тип и размеры изображения после проверки структуры. + + `UnsupportedImage` — сигнатура не PNG и не JPEG (в том числе пустые + данные), `TooManyPixels` — больше `max_pixels` по заголовку, + `DamagedImage` — нарушена структура. + """ + if data.startswith(PNG_SIGNATURE): + return _inspect_png(data, max_pixels=max_pixels) + if data.startswith(JPEG_SIGNATURE): + return _inspect_jpeg(data, max_pixels=max_pixels) + raise UnsupportedImage("unknown signature") + + +def _check_pixels(width: int, height: int, *, max_pixels: int) -> None: + if width * height > max_pixels: + raise TooManyPixels("too many pixels") + + +# --- PNG --------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class _Segment: + """Строки одного прохода в распакованном потоке: [start, end), шаг.""" + + start: int + end: int + stride: int + + +def _png_segments( + width: int, + height: int, + *, + bits_per_pixel: int, + interlaced: bool, +) -> list[_Segment]: + """Где в распакованном потоке строки и какой они длины. + + Строка — байт фильтра и `ceil(ширина × бит на пиксель / 8)` байт. + Пустой проход Adam7 (ширина или высота 0) строк не даёт. + """ + passes = _ADAM7 if interlaced else ((0, 0, 1, 1),) + segments = [] + start = 0 + for x0, y0, dx, dy in passes: + pass_width = (width - x0 + dx - 1) // dx if width > x0 else 0 + pass_height = (height - y0 + dy - 1) // dy if height > y0 else 0 + if not pass_width or not pass_height: + continue + stride = 1 + (pass_width * bits_per_pixel + 7) // 8 + end = start + stride * pass_height + segments.append(_Segment(start=start, end=end, stride=stride)) + start = end + return segments + + +class _IdatStream: + """Поток IDAT: распаковка блоками, объём и типы фильтров строк.""" + + def __init__(self, segments: list[_Segment]) -> None: + self._segments = segments + self._expected = segments[-1].end + self._inflater = zlib.decompressobj() + self._total = 0 + + def feed(self, chunk: memoryview) -> None: + for offset in range(0, len(chunk), _INFLATE_IN_BYTES): + if self._inflater.eof: + # остаток после конца потока zlib libpng тоже пропускает + return + self._inflate(chunk[offset : offset + _INFLATE_IN_BYTES]) + + def finish(self) -> None: + if not self._inflater.eof or self._total != self._expected: + raise DamagedImage("image data size differs") + + def _inflate(self, piece: memoryview | bytes) -> None: + while True: + try: + out = self._inflater.decompress(piece, _INFLATE_OUT_BYTES) + except zlib.error as e: + raise DamagedImage("broken image data stream") from e + self._check_rows(out) + if self._inflater.eof: + return + piece = self._inflater.unconsumed_tail + # вход кончился, а выход не упёрся в предел — буфер пуст + if not piece and len(out) < _INFLATE_OUT_BYTES: + return + + def _check_rows(self, out: bytes) -> None: + begin = self._total + self._total += len(out) + # «бомба» и лишние данные: выход больше, чем дают размеры + if self._total > self._expected: + raise DamagedImage("image data longer than dimensions") + for segment in self._segments: + low = max(begin, segment.start) + high = min(self._total, segment.end) + if low >= high: + continue + # первый байт фильтра в [low, high) по сетке строк прохода + first = low + (-(low - segment.start) % segment.stride) + filters = out[first - begin : high - begin : segment.stride] + if filters.translate(None, _PNG_FILTER_TYPES): + raise DamagedImage("unknown row filter") + + +def _inspect_png(data: bytes, *, max_pixels: int) -> ImageInfo: + view = memoryview(data) + size = len(data) + pos = len(PNG_SIGNATURE) + width = height = 0 + color_type = -1 + stream: _IdatStream | None = None + seen_palette = False + idat_state = "before" # before → inside → after + first = True + while True: + if pos + 8 > size: + raise DamagedImage("truncated chunk header") + length, chunk_type = struct.unpack_from(">I4s", data, pos) + if length > _PNG_MAX_UINT or not chunk_type.isalpha(): + raise DamagedImage("bad chunk") + body_end = pos + 8 + length + if body_end + 4 > size: + raise DamagedImage("truncated chunk") + (crc,) = struct.unpack_from(">I", data, body_end) + if zlib.crc32(view[pos + 4 : body_end]) != crc: + raise DamagedImage("chunk CRC mismatch") + body = view[pos + 8 : body_end] + pos = body_end + 4 + + if first: + if chunk_type != b"IHDR": + raise DamagedImage("IHDR is not first") + first = False + width, height, color_type, bits_per_pixel, interlaced = ( + _parse_ihdr(body) + ) + _check_pixels(width, height, max_pixels=max_pixels) + stream = _IdatStream( + _png_segments( + width, + height, + bits_per_pixel=bits_per_pixel, + interlaced=interlaced, + ), + ) + continue + + if chunk_type == b"IDAT": + if idat_state == "after": + raise DamagedImage("IDAT chunks are not consecutive") + if color_type == _PNG_PALETTE_TYPE and not seen_palette: + raise DamagedImage("PLTE is missing") + idat_state = "inside" + stream.feed(body) + continue + if idat_state == "inside": + idat_state = "after" + + if chunk_type == b"IEND": + if length or idat_state == "before": + raise DamagedImage("bad IEND") + stream.finish() + return ImageInfo( + content_type=ImageType.PNG, + width=width, + height=height, + ) + if chunk_type == b"PLTE": + if ( + seen_palette + or idat_state != "before" + or color_type in _PNG_NO_PALETTE_TYPES + or not length + or length % 3 + or length > 3 * 256 + ): + raise DamagedImage("bad PLTE") + seen_palette = True + continue + if chunk_type == b"IHDR" or chunk_type[0:1].isupper(): + # второй IHDR или неизвестный критичный чанк + raise DamagedImage("unexpected critical chunk") + # вспомогательный чанк: проверена только CRC + + +def _parse_ihdr(body: memoryview) -> tuple[int, int, int, int, bool]: + """Ширина, высота, тип цвета, бит на пиксель, чересстрочность.""" + if len(body) != 13: + raise DamagedImage("bad IHDR length") + width, height, depth, color_type, compression, filtering, interlace = ( + struct.unpack(">IIBBBBB", body) + ) + if ( + not 0 < width <= _PNG_MAX_UINT + or not 0 < height <= _PNG_MAX_UINT + or depth not in _PNG_DEPTHS.get(color_type, ()) + or compression + or filtering + or interlace not in (0, 1) + ): + raise DamagedImage("bad IHDR") + bits_per_pixel = depth * _PNG_CHANNELS[color_type] + return width, height, color_type, bits_per_pixel, interlace == 1 + + +# --- JPEG -------------------------------------------------------------- + + +def _inspect_jpeg(data: bytes, *, max_pixels: int) -> ImageInfo: + size = len(data) + pos = 2 + frame: tuple[int, int] | None = None + scans = 0 + while True: + if pos >= size or data[pos] != 0xFF: + raise DamagedImage("marker expected") + # байты-заполнители FF перед маркером + while pos < size and data[pos] == 0xFF: + pos += 1 + if pos >= size: + raise DamagedImage("truncated marker") + marker = data[pos] + pos += 1 + + if marker == _JPEG_EOI: + if frame is None or not scans: + raise DamagedImage("no frame or scan") + width, height = frame + return ImageInfo( + content_type=ImageType.JPEG, + width=width, + height=height, + ) + if marker == _JPEG_TEM: + continue + if marker in (0x00, _JPEG_SOI) or marker in _JPEG_RST: + raise DamagedImage("unexpected marker") + + if pos + 2 > size: + raise DamagedImage("truncated segment") + (length,) = struct.unpack_from(">H", data, pos) + if length < 2 or pos + length > size: + raise DamagedImage("bad segment length") + segment = data[pos + 2 : pos + length] + pos += length + + if marker in _JPEG_SOF: + if frame is not None: + raise DamagedImage("more than one frame") + frame = _parse_sof(segment) + _check_pixels(*frame, max_pixels=max_pixels) + elif marker == _JPEG_SOS: + if frame is None: + raise DamagedImage("scan before frame") + _check_sos(segment) + scans += 1 + # данные скана: до первого маркера, кроме вставок и RST + found = _JPEG_SCAN_END.search(data, pos) + if found is None: + raise DamagedImage("scan data is not terminated") + pos = found.start() + + +def _parse_sof(segment: bytes) -> tuple[int, int]: + """Ширина и высота кадра; длина сегмента сходится с числом компонент.""" + if len(segment) < 6: + raise DamagedImage("bad frame header") + _, height, width, components = struct.unpack_from(">BHHB", segment) + if ( + not width + or not height + or not 1 <= components <= 4 + or len(segment) != 6 + 3 * components + ): + raise DamagedImage("bad frame header") + return width, height + + +def _check_sos(segment: bytes) -> None: + if not segment: + raise DamagedImage("bad scan header") + components = segment[0] + if not 1 <= components <= 4 or len(segment) != 4 + 2 * components: + raise DamagedImage("bad scan header") diff --git a/student-tests/api_client.py b/student-tests/api_client.py index f217901d..4d1371d5 100644 --- a/student-tests/api_client.py +++ b/student-tests/api_client.py @@ -2,6 +2,7 @@ import base64 import dataclasses +import hashlib import secrets import uuid from collections.abc import Callable, Sequence @@ -231,15 +232,105 @@ class Api: text: str, *, key: str | None = None, + attachment_ids: Sequence[str] | None = None, ) -> dict[str, Any]: - """Успешная отправка: 201 и `Message`; без `key` — новый ключ.""" + """Успешная отправка: 201 и `Message`; без `key` — новый ключ. + + `attachment_ids=None` — поля в теле нет. + """ + body: dict[str, Any] = {"text": text} + if attachment_ids is not None: + body["attachment_ids"] = list(attachment_ids) resp = self.post_message( actor, chat_id, key=new_key() if key is None else key, - json={"text": text}, + json=body, + ) + message = assert_ok(resp, 201, "Message") + if attachment_ids is not None: + assert message["attachment_ids"] == [ + item.lower() for item in attachment_ids + ], "attachment_ids differ from sent" + return message + + def post_attachment( + self, + actor: Actor | None, + chat_id: str, + data: Any, + *, + content_type: str | None = "image/png", + filename: str | None = "image.png", + headers: dict[str, str] | None = None, + ) -> httpx.Response: + """Загрузка как есть: сырые байты (или итератор — частями, без + `Content-Length`); `None` — без заголовка или параметра.""" + merged = dict(headers or {}) + if content_type is not None: + merged["Content-Type"] = content_type + params = {} if filename is None else {"filename": filename} + return self.request( + "POST", + f"{API}/chats/{chat_id}/attachments", + actor=actor, + headers=merged, + params=params, + content=data, + ) + + def upload( + self, + actor: Actor, + chat_id: str, + data: bytes, + *, + content_type: str = "image/png", + filename: str = "image.png", + ) -> dict[str, Any]: + """Успешная загрузка: 201 и `Attachment` с размером и SHA-256.""" + resp = self.post_attachment( + actor, + chat_id, + data, + content_type=content_type, + filename=filename, + ) + attachment = assert_ok(resp, 201, "Attachment") + assert attachment["size_bytes"] == len(data), "size_bytes differs" + assert attachment["sha256"] == hashlib.sha256(data).hexdigest(), ( + "sha256 differs" + ) + assert attachment["chat_id"] == chat_id.lower(), "chat_id differs" + assert attachment["owner_id"] == actor.id, "owner_id differs" + assert attachment["filename"] == filename, "filename changed" + return attachment + + def attachment_meta( + self, + actor: Actor | None, + attachment_id: str, + ) -> httpx.Response: + return self.request( + "GET", + f"{API}/attachments/{attachment_id}", + actor=actor, + ) + + def attachment_content( + self, + actor: Actor | None, + attachment_id: str, + *, + variant: str | None = None, + ) -> httpx.Response: + params = {} if variant is None else {"variant": variant} + return self.request( + "GET", + f"{API}/attachments/{attachment_id}/content", + actor=actor, + params=params, ) - return assert_ok(resp, 201, "Message") def messages_page( self, diff --git a/student-tests/contract.py b/student-tests/contract.py index 37ee964b..b8dc6cf2 100644 --- a/student-tests/contract.py +++ b/student-tests/contract.py @@ -23,8 +23,10 @@ UUID_RE = re.compile( ) # RFC 3339 в UTC: шесть знаков долей секунды и суффикс Z CREATED_AT_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z$") -ID_KEYS = frozenset({"id", "chat_id", "sender_id"}) -TIME_KEYS = frozenset({"created_at", "expires_at"}) +ID_KEYS = frozenset({"id", "chat_id", "sender_id", "owner_id"}) +# списки UUID в ответах: участники чата и с лабы 4 вложения сообщения +ID_LIST_KEYS = frozenset({"member_ids", "attachment_ids"}) +TIME_KEYS = frozenset({"created_at", "expires_at", "updated_at"}) # WWW-Authenticate у 401 (contracts/README.md): вход и остальные запросы BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"' BEARER_CHALLENGE = 'Bearer realm="messenger"' @@ -40,6 +42,8 @@ ERROR_CODES = { 404: "not_found", 405: "invalid_request", 409: "conflict", + 413: "payload_too_large", + 415: "unsupported_media_type", 500: "internal_error", 503: "unavailable", } @@ -86,7 +90,7 @@ def check_formats(value: Any, path: str = "") -> None: where = f"{path}/{key}" if key in ID_KEYS: assert_uuid(item, where) - elif key == "member_ids": + elif key in ID_LIST_KEYS: for number, member in enumerate(item): assert_uuid(member, f"{where}/{number}") elif key in TIME_KEYS: @@ -173,6 +177,44 @@ def assert_unauthorized( return error +def assert_no_storage_traces(resp: httpx.Response) -> None: + """Ни перенаправления, ни заголовков S3 в ответе API.""" + assert "location" not in resp.headers, describe(resp, "has Location") + amz = [name for name in resp.headers if name.lower().startswith("x-amz-")] + assert not amz, describe(resp, f"S3 headers {amz}") + + +def assert_content( + resp: httpx.Response, + data: bytes, + content_type: str, +) -> None: + """Байты оригинала: 200, тип без параметров, длина, `nosniff`, те же + байты, без перенаправления и следов S3.""" + assert resp.status_code == 200, describe(resp, "expected 200") + assert resp.headers.get("X-Request-Id", "").strip(), describe( + resp, + "no X-Request-Id", + ) + assert_instance_id(resp) + assert resp.headers.get("Content-Type") == content_type, describe( + resp, + f"Content-Type is not {content_type}", + ) + assert resp.headers.get("Content-Length") == str(len(data)), describe( + resp, + f"Content-Length is not {len(data)}", + ) + assert resp.headers.get("X-Content-Type-Options") == "nosniff", describe( + resp, + "no X-Content-Type-Options: nosniff", + ) + assert_no_storage_traces(resp) + assert resp.content == data, ( + f"downloaded {len(resp.content)} bytes differ from {len(data)} sent" + ) + + def assert_instance_id(resp: httpx.Response) -> str: """Непустой `X-Instance-Id` допустимого формата; возвращает значение.""" instance_id = resp.headers.get("X-Instance-Id", "") diff --git a/student-tests/fault_hook.py b/student-tests/fault_hook.py index 6ee96aa2..bfc5dc72 100755 --- a/student-tests/fault_hook.py +++ b/student-tests/fault_hook.py @@ -28,15 +28,25 @@ db-sessions pg_stat_database.sessions базы стенда: сколько сессий PostgreSQL приняла за всё время (учитывает и сессию самого вызова) + count-attachments вложения в базе стенда по статусам: + `pending=N ready=M` + count-objects число вложений с объектами в bucket стенда: + каталоги `` под `<база>/attachments/` + (filer через `weed shell` на loopback + контейнера s3) -Пароли не печатает: valkey-cli берёт пароль из VALKEYCLI_AUTH -контейнера, psql работает от POSTGRES_USER контейнера. Только stdlib. +Bucket и имя базы для count-objects — FAULT_S3_BUCKET и FAULT_DATABASE, +их задаёт run_failures.py. Пароли и ключи не печатает: valkey-cli берёт +пароль из VALKEYCLI_AUTH контейнера, psql работает от POSTGRES_USER +контейнера, weed shell — с ключом подписи из окружения контейнера s3. +Только stdlib. """ from __future__ import annotations import json import os +import re import subprocess import sys import time @@ -168,6 +178,20 @@ for d in /proc/[0-9]*; do esac done """ +COUNT_ATTACHMENTS_SQL = """\ +SELECT 'pending=' || count(*) FILTER (WHERE status = 'pending') + || ' ready=' || count(*) FILTER (WHERE status = 'ready') +FROM attachments; +""" +# как S3_BUCKET_NAME_PATTERN в src/utils/constants.py; имя базы — как в +# run_isolated.py: путь filer собирается только из проверенных имён +BUCKET_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$") +DB_NAME_RE = re.compile(r"^[a-z0-9_]+$") +# каталог вложения в filer — его id; копия ATTACHMENT_KEY_PREFIX +ATTACHMENT_DIR_RE = re.compile( + r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", +) +ATTACHMENT_KEY_PREFIX = "attachments" PROBE_SQL_SH = ( 'exec psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq -c "SELECT 1"' ) @@ -383,6 +407,33 @@ def clear_connections(project: str) -> str: raise HookError(f"connections are not freed in {FILL_TIMEOUT_S}s") +def count_objects(project: str) -> str: + """Каталоги вложений в bucket стенда: у каждого объекта `original` + свой каталог ``. Нет префикса — 0 (fs.ls ничего не печатает).""" + bucket = os.environ.get("FAULT_S3_BUCKET", "") + database = os.environ.get("FAULT_DATABASE", "") + if not BUCKET_NAME_RE.fullmatch(bucket): + raise HookError(f"FAULT_S3_BUCKET is not a bucket name: {bucket!r}") + if not DB_NAME_RE.fullmatch(database): + raise HookError(f"FAULT_DATABASE is not a database name: {database!r}") + listing = compose( + project, + "exec", + "-T", + "s3", + "sh", + "-c", + "exec weed shell -master=127.0.0.1:9333 2>&1", + stdin=f"fs.ls /buckets/{bucket}/{database}/{ATTACHMENT_KEY_PREFIX}\n", + ) + return str( + sum( + bool(ATTACHMENT_DIR_RE.fullmatch(line.strip())) + for line in listing.splitlines() + ), + ) + + def run(project: str, action: str, args: list[str]) -> str: """Выполнить действие; синтаксис без match: hook запускают и 3.9.""" if action in ("stop", "pause") and len(args) == 1: @@ -415,6 +466,10 @@ def run(project: str, action: str, args: list[str]) -> str: return clear_connections(project) if action == "db-sessions" and not args: return psql(project, DB_SESSIONS_SQL) + if action == "count-attachments" and not args: + return psql(project, COUNT_ATTACHMENTS_SQL) + if action == "count-objects" and not args: + return count_objects(project) raise HookError(f"unknown action or arguments: {action} {args}") diff --git a/student-tests/images.py b/student-tests/images.py new file mode 100644 index 00000000..51a233c9 --- /dev/null +++ b/student-tests/images.py @@ -0,0 +1,227 @@ +"""Изображения для тестов вложений: настоящие, повреждённые, огромные. + +PNG собираются на stdlib — любые IHDR и IDAT, Adam7, точный размер файла +чанком-заполнителем `tEXt`, «бомба», порча CRC. JPEG — через Pillow +(dev-группа): прогрессивный, серый, CMYK, с EXIF, с подменой размеров в +SOF. Большие файлы и «бомбы» живут только в памяти теста и в git не +попадают (`tests/fixtures/README.md`). +""" + +import functools +import io +import struct +import zlib +from pathlib import Path + +PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n" +SAMPLE_PNG_PATH = ( + Path(__file__).resolve().parents[1] / "tests" / "fixtures" / "sample.png" +) +# лимиты контракта лабы 4 +MAX_BYTES = 10 * 1024 * 1024 +MAX_PIXELS = 40_000_000 + +_CHANNELS = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4} +_ADAM7 = ( + (0, 0, 8, 8), + (4, 0, 8, 8), + (0, 4, 4, 8), + (2, 0, 4, 4), + (0, 2, 2, 4), + (1, 0, 2, 2), + (0, 1, 1, 2), +) + + +@functools.cache +def sample_png() -> bytes: + """Публичный fixture `tests/fixtures/sample.png` (320 × 200).""" + return SAMPLE_PNG_PATH.read_bytes() + + +def chunk(kind: bytes, body: bytes) -> bytes: + """Чанк PNG с верной CRC.""" + crc = zlib.crc32(kind + body) + return struct.pack(">I", len(body)) + kind + body + struct.pack(">I", crc) + + +def _rows( + width: int, + height: int, + *, + bits_per_pixel: int, + interlace: bool, +) -> bytes: + """Распакованные данные: строки с фильтром 0 и узором в пикселях.""" + passes = _ADAM7 if interlace else ((0, 0, 1, 1),) + out = bytearray() + for x0, y0, dx, dy in passes: + pass_width = (width - x0 + dx - 1) // dx if width > x0 else 0 + pass_height = (height - y0 + dy - 1) // dy if height > y0 else 0 + if not pass_width or not pass_height: + continue + row_bytes = (pass_width * bits_per_pixel + 7) // 8 + row = bytes((i * 7) % 256 for i in range(row_bytes)) + out += (b"\x00" + row) * pass_height + return bytes(out) + + +def png( + width: int = 64, + height: int = 48, + *, + color: int = 2, + depth: int = 8, + interlace: bool = False, + idat: bytes | None = None, +) -> bytes: + """Настоящий PNG: IHDR, PLTE для палитры, IDAT, IEND. + + `idat` — готовый сжатый поток вместо строк по размерам (огромные + размеры в маленьком файле, «бомба»). + """ + ihdr = struct.pack( + ">IIBBBBB", + width, + height, + depth, + color, + 0, + 0, + 1 if interlace else 0, + ) + if idat is None: + idat = zlib.compress( + _rows( + width, + height, + bits_per_pixel=depth * _CHANNELS[color], + interlace=interlace, + ), + 9, + ) + palette = chunk(b"PLTE", bytes(range(48))) if color == 3 else b"" + return ( + PNG_SIGNATURE + + chunk(b"IHDR", ihdr) + + palette + + chunk(b"IDAT", idat) + + chunk(b"IEND", b"") + ) + + +def png_of_size(size: int) -> bytes: + """Настоящий PNG 64 × 48 ровно `size` байт: добор чанком `tEXt`.""" + base = png() + filler = size - len(base) - 12 + assert filler >= 2, f"size {size} is too small" + text = chunk(b"tEXt", b"k\x00" + b"x" * (filler - 2)) + # tEXt — после IHDR (8 + 25 байт), до IDAT + data = base[:33] + text + base[33:] + assert len(data) == size + return data + + +def png_huge(width: int, height: int) -> bytes: + """Несколько килобайт с огромными размерами в IHDR.""" + return png( + width, + height, + color=0, + depth=1, + idat=zlib.compress(bytes(4096)), + ) + + +def png_bomb(unpacked_mib: int = 200) -> bytes: + """PNG 100 × 100, IDAT которого распаковывается в `unpacked_mib` MiB.""" + compressor = zlib.compressobj(9) + block = bytes(1024 * 1024) + stream = b"".join(compressor.compress(block) for _ in range(unpacked_mib)) + return png(100, 100, idat=stream + compressor.flush()) + + +def flip_byte(data: bytes, offset: int) -> bytes: + damaged = bytearray(data) + damaged[offset] ^= 0x55 + return bytes(damaged) + + +def png_idat_byte_changed(data: bytes | None = None) -> bytes: + """Изменённый байт внутри первого IDAT (CRC чанка не сходится).""" + data = data or sample_png() + return flip_byte(data, data.index(b"IDAT") + 40) + + +def truncated(data: bytes, keep: float = 0.5) -> bytes: + return data[: int(len(data) * keep)] + + +def with_tail(data: bytes, tail: bytes = b"TAIL" * 64) -> bytes: + """Байты после IEND или EOI.""" + return data + tail + + +def _pillow_image(mode: str, size: tuple[int, int]) -> object: + from PIL import Image # noqa: PLC0415 — Pillow только для JPEG + + width, height = size + image = Image.new("RGB", size) + image.putdata( + [ + ((x * 7) % 256, (y * 13) % 256, (x * y) % 256) + for y in range(height) + for x in range(width) + ], + ) + return image.convert(mode) + + +def jpeg( + mode: str = "RGB", + size: tuple[int, int] = (64, 48), + **save: object, +) -> bytes: + """Настоящий JPEG через Pillow; `save` — параметры `Image.save`.""" + from PIL import Image # noqa: PLC0415 + + buffer = io.BytesIO() + image = _pillow_image(mode, size) + if "exif" in save and save["exif"] is True: + exif = Image.Exif() + exif[0x010F] = "student-tests" + exif[0x0112] = 1 + save["exif"] = exif + image.save(buffer, "JPEG", **save) + return buffer.getvalue() + + +def jpeg_huge(width: int, height: int) -> bytes: + """Маленький JPEG с подменёнными размерами в SOF0.""" + data = bytearray(jpeg()) + sof = data.index(b"\xff\xc0") + data[sof + 5 : sof + 9] = struct.pack(">HH", height, width) + return bytes(data) + + +def png_variants() -> dict[str, bytes]: + """Разновидности PNG спека: палитра, альфа, серый с альфой, 16 и 1 + бит, Adam7.""" + return { + "palette": png(color=3, depth=8), + "rgba": png(color=6), + "gray-alpha": png(color=4), + "rgb-16-bit": png(color=2, depth=16), + "gray-1-bit": png(color=0, depth=1), + "adam7": png(37, 29, interlace=True), + } + + +def jpeg_variants() -> dict[str, bytes]: + """Разновидности JPEG спека: прогрессивный, серый, CMYK, с EXIF.""" + return { + "progressive": jpeg(progressive=True), + "gray": jpeg("L"), + "cmyk": jpeg("CMYK"), + "exif": jpeg(exif=True), + } diff --git a/student-tests/run_failures.py b/student-tests/run_failures.py index 5a9b0dfa..846dde34 100644 --- a/student-tests/run_failures.py +++ b/student-tests/run_failures.py @@ -118,6 +118,17 @@ def app_port() -> str: return "8080" +def storage_names(project: str) -> dict[str, str]: + """Bucket и имя базы стенда — из окружения сервиса `api` в его + конфигурации compose: по ним hook считает объекты вложений.""" + config = dc(project, "config", "--format", "json", quiet=True) + environment = json.loads(config.stdout)["services"]["api"]["environment"] + return { + "FAULT_S3_BUCKET": environment["S3__BUCKET"], + "FAULT_DATABASE": environment["DATABASE__NAME"], + } + + def free_port() -> int: with socket.socket() as sock: sock.bind(("127.0.0.1", 0)) @@ -276,12 +287,16 @@ def main() -> int: base_url = start_api(project, default_name, free_port(), {}) tight_url = start_api(project, tight_name, free_port(), TIGHT_ENV) say(f"ready: api={base_url} tight={tight_url}") - env = os.environ | { - "BASE_URL": base_url, - "FAULT_TIGHT_BASE_URL": tight_url, - "FAULT_HOOK": str(FAULT_HOOK), - "FAULT_PROJECT": project, - } + env = ( + os.environ + | { + "BASE_URL": base_url, + "FAULT_TIGHT_BASE_URL": tight_url, + "FAULT_HOOK": str(FAULT_HOOK), + "FAULT_PROJECT": project, + } + | storage_names(project) + ) say("pytest -m fault") results["fault"] = run( "uv", diff --git a/student-tests/spec_coverage.py b/student-tests/spec_coverage.py index 7507c0db..b191e6d4 100644 --- a/student-tests/spec_coverage.py +++ b/student-tests/spec_coverage.py @@ -23,6 +23,7 @@ CAPABILITIES = ( "chat-cache", "health", "idempotency", + "attachments", ) SCENARIO_RE = re.compile(r"^#### Scenario: (.+?)\s*$", re.MULTILINE) @@ -105,6 +106,26 @@ EXCLUDED: dict[Scenario, Exclusion] = { check="make test-persistence ACTION_SCRIPT=scripts/restart.sh — " "evidence/replicas/test-persistence.md", ), + ("attachments", "Принявшая реплика остановлена"): Exclusion( + reason="нужно остановить реплику API, тесты стенд не трогают", + check="driver.py --port attachment-failover [--mode stop|kill] " + "скилла run-mtusi-messenger: загрузка через LB, scripts/stop-one.sh " + "реплики ответа, скачивание через другую с тем же SHA-256, 404 " + "постороннему — evidence/attachments/failover.md", + ), + ("attachments", "Байты не в БД и не на диске API"): Exclusion( + reason="нужен взгляд в схему PostgreSQL, bucket S3 и файловые " + "системы контейнеров, а тесты ходят по HTTP", + check="driver.py --port attachment-storage: колонки таблиц " + "вложений, вид object_key, объект в bucket, анонимный GET — 403, " + "docker diff реплик — evidence/attachments/storage.md", + ), + ("attachments", "Рестарт стенда"): Exclusion( + reason="нужен рестарт стенда, тесты сервер не трогают", + check="make test-persistence ACTION_SCRIPT=scripts/restart.sh: с " + "LAB=4 проверка скачивает тот же оригинал прежним токеном — " + "evidence/replicas/test-persistence.md", + ), ("users", "Хэш в БД"): Exclusion( reason="нужен доступ к таблице users, а тесты ходят по HTTP", check="driver.py --port auth-storage: префикс $argon2id$ и " diff --git a/student-tests/test_api_conventions.py b/student-tests/test_api_conventions.py index 44824a8a..7d96f6f4 100644 --- a/student-tests/test_api_conventions.py +++ b/student-tests/test_api_conventions.py @@ -10,6 +10,7 @@ from typing import Any import httpx import pytest +import images from api_client import ( API, Actor, @@ -19,6 +20,7 @@ from api_client import ( unique_username, ) from contract import ( + assert_content, assert_created_at, assert_error, assert_errors, @@ -389,3 +391,70 @@ def test_upper_case_uuid_in_path( "MessagePage", ) assert upper_page == lower_page == {"items": [sent], "next_cursor": None} + + +@pytest.mark.spec("api-conventions", "Лимит и тип вложения") +def test_attachment_limit_and_type_codes( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + over = images.png_of_size(images.MAX_BYTES + 1) + assert_error(api.post_attachment(alice, chat["id"], over), 413) + text = "не картинка".encode() + assert_error(api.post_attachment(alice, chat["id"], text), 415) + + +def attachment_requests( + api: Api, + actor: Actor, + attachment_id: str, +) -> dict[str, httpx.Response]: + quoted = urllib.parse.quote(attachment_id, safe="") + return { + "meta": api.attachment_meta(actor, quoted), + "content": api.attachment_content(actor, quoted), + } + + +@pytest.mark.spec("api-conventions", "Идентификаторы вложений в другой записи") +def test_attachment_ids_in_other_forms( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + attachment = api.upload(alice, chat["id"], images.sample_png()) + responses = { + f"{name} / {form}": resp + for form, value in other_uuid_forms(attachment["id"]).items() + for name, resp in attachment_requests(api, alice, value).items() + } + responses |= { + f"attachment_ids / {form}": api.post_message( + alice, + chat["id"], + json={"text": "x", "attachment_ids": [value]}, + ) + for form, value in other_uuid_forms(attachment["id"]).items() + } + assert_errors(responses, 400) + assert api.all_messages(alice, chat["id"]) == [] + + +@pytest.mark.spec( + "api-conventions", + "Идентификаторы вложений в верхнем регистре", +) +def test_attachment_ids_in_upper_case( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + attachment = api.upload(alice, chat["id"], data) + upper = attachment["id"].upper() + meta = assert_ok(api.attachment_meta(alice, upper), 200, "Attachment") + assert meta == attachment + assert_content(api.attachment_content(alice, upper), data, "image/png") + message = api.send_message(alice, chat["id"], "x", attachment_ids=[upper]) + assert message["attachment_ids"] == [attachment["id"]] diff --git a/student-tests/test_attachments.py b/student-tests/test_attachments.py new file mode 100644 index 00000000..da85cce9 --- /dev/null +++ b/student-tests/test_attachments.py @@ -0,0 +1,657 @@ +"""Спек `attachments`: загрузка, лимиты, тип и целостность, имя файла, +доступ, метаданные, скачивание, повтор, реплики. + +Проверки отказов S3 — `test_failures.py`; сценарии, которым нужен стенд +(остановка реплики, рестарт, взгляд в БД и bucket), — исключения сверки +покрытия (`spec_coverage.py`). +""" + +import hashlib +import urllib.parse +import uuid +from collections.abc import Iterator +from typing import Any + +import pytest + +import images +from api_client import Actor, Api +from contract import ( + BEARER_CHALLENGE, + assert_content, + assert_error, + assert_errors, + assert_instance_id, + assert_no_storage_traces, + assert_ok, + assert_replicas, + assert_unauthorized, +) + +# больше лимита в 3 раза: 30 MiB +BIG_BYTES = 30 * 1024 * 1024 +# сколько скачиваний ждать ответа другой реплики (round-robin LB) +REPLICA_ATTEMPTS = 20 + + +def chunks(data: bytes, size: int = 1024 * 1024) -> Iterator[bytes]: + """Тело частями: httpx шлёт его без `Content-Length`.""" + for offset in range(0, len(data), size): + yield data[offset : offset + size] + + +def big_body() -> bytes: + """30 MiB, которые начинаются как PNG.""" + return images.PNG_SIGNATURE + bytes(BIG_BYTES - len(images.PNG_SIGNATURE)) + + +@pytest.mark.spec("attachments", "Загрузка PNG") +def test_upload_png(api: Api, alice: Actor, chat: dict[str, Any]) -> None: + data = images.sample_png() + attachment = api.upload(alice, chat["id"], data, filename="sample.png") + assert attachment["status"] == "ready" + assert attachment["variants"] == [] + assert attachment["error_code"] is None + assert attachment["content_type"] == "image/png" + assert attachment["size_bytes"] == 111817 + assert attachment["sha256"] == ( + "99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75" + ) + + +@pytest.mark.spec("attachments", "Загрузка JPEG") +def test_upload_jpeg(api: Api, bob: Actor, chat: dict[str, Any]) -> None: + data = images.jpeg(size=(320, 200)) + attachment = api.upload( + bob, + chat["id"], + data, + content_type="image/jpeg", + filename="photo.jpg", + ) + assert attachment["content_type"] == "image/jpeg" + + +@pytest.mark.spec("attachments", "Разновидности PNG и JPEG") +def test_image_kinds(api: Api, alice: Actor, chat: dict[str, Any]) -> None: + kinds = [ + ("image/png", name, data) + for name, data in images.png_variants().items() + ] + [ + ("image/jpeg", name, data) + for name, data in images.jpeg_variants().items() + ] + for content_type, name, data in kinds: + attachment = api.upload( + alice, + chat["id"], + data, + content_type=content_type, + filename=f"{name}.img", + ) + assert attachment["content_type"] == content_type, name + + +@pytest.mark.spec("attachments", "Граница размера") +def test_size_boundary(api: Api, alice: Actor, chat: dict[str, Any]) -> None: + exact = images.png_of_size(images.MAX_BYTES) + api.upload(alice, chat["id"], exact) + over = images.png_of_size(images.MAX_BYTES + 1) + assert_error(api.post_attachment(alice, chat["id"], over), 413) + + +@pytest.mark.spec("attachments", "Заявленный размер больше лимита") +def test_declared_size_over_limit( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + resp = api.post_attachment(alice, chat["id"], big_body()) + assert resp.request.headers["Content-Length"] == str(BIG_BYTES) + assert_error(resp, 413) + + +@pytest.mark.spec("attachments", "Большое тело без Content-Length") +def test_chunked_body_over_limit( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + resp = api.post_attachment(alice, chat["id"], chunks(big_body())) + assert "Content-Length" not in resp.request.headers + assert_error(resp, 413) + + +@pytest.mark.spec("attachments", "Огромные размеры в маленьком файле") +def test_huge_dimensions(api: Api, alice: Actor, chat: dict[str, Any]) -> None: + assert_errors( + { + "png 8000x5001": api.post_attachment( + alice, + chat["id"], + images.png_huge(8000, 5001), + ), + "png 1x40000001": api.post_attachment( + alice, + chat["id"], + images.png_huge(1, 40_000_001), + ), + "jpeg 10000x4001": api.post_attachment( + alice, + chat["id"], + images.jpeg_huge(10000, 4001), + content_type="image/jpeg", + ), + "jpeg 65535x65535": api.post_attachment( + alice, + chat["id"], + images.jpeg_huge(65535, 65535), + content_type="image/jpeg", + ), + }, + 413, + ) + + +@pytest.mark.spec("attachments", "Ровно 40 млн пикселей") +def test_exactly_max_pixels( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.png(8000, 5000, color=0, depth=1) + api.upload(alice, chat["id"], data) + + +@pytest.mark.spec("attachments", "Данные длиннее размеров") +def test_decompression_bomb( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + assert_error( + api.post_attachment(alice, chat["id"], images.png_bomb()), + 415, + ) + + +@pytest.mark.spec("attachments", "Не изображение") +def test_not_an_image(api: Api, alice: Actor, chat: dict[str, Any]) -> None: + assert_errors( + { + name: api.post_attachment(alice, chat["id"], data) + for name, data in ( + ("text", "просто текст".encode()), + ("gif", b"GIF89a" + bytes(64)), + ("empty", b""), + ) + }, + 415, + ) + + +@pytest.mark.spec("attachments", "Подмена MIME") +def test_mime_spoofing(api: Api, alice: Actor, chat: dict[str, Any]) -> None: + assert_errors( + { + "jpeg as png": api.post_attachment( + alice, + chat["id"], + images.jpeg(), + content_type="image/png", + ), + "png as jpeg": api.post_attachment( + alice, + chat["id"], + images.sample_png(), + content_type="image/jpeg", + ), + }, + 415, + ) + + +@pytest.mark.spec("attachments", "Неподходящий Content-Type") +def test_unsuitable_content_type( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + assert_errors( + { + str(content_type): api.post_attachment( + alice, + chat["id"], + data, + content_type=content_type, + ) + for content_type in ( + "application/octet-stream", + "text/plain", + None, + ) + }, + 415, + ) + resp = api.post_attachment( + alice, + chat["id"], + data, + content_type="IMAGE/PNG; charset=binary", + ) + assert assert_ok(resp, 201, "Attachment")["content_type"] == "image/png" + + +@pytest.mark.spec("attachments", "Обрезанный файл") +def test_truncated_files(api: Api, alice: Actor, chat: dict[str, Any]) -> None: + png, jpeg = images.sample_png(), images.jpeg(size=(320, 200)) + assert_errors( + { + "png half": api.post_attachment( + alice, + chat["id"], + images.truncated(png), + ), + "png -1 byte": api.post_attachment(alice, chat["id"], png[:-1]), + "jpeg half": api.post_attachment( + alice, + chat["id"], + images.truncated(jpeg), + content_type="image/jpeg", + ), + "jpeg -2 bytes": api.post_attachment( + alice, + chat["id"], + jpeg[:-2], + content_type="image/jpeg", + ), + }, + 415, + ) + + +@pytest.mark.spec("attachments", "Испорченные данные PNG") +def test_damaged_png_data( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + garbage = images.PNG_SIGNATURE + uuid.uuid4().bytes * 256 + assert_errors( + { + "idat byte": api.post_attachment( + alice, + chat["id"], + images.png_idat_byte_changed(), + ), + "garbage": api.post_attachment(alice, chat["id"], garbage), + }, + 415, + ) + + +@pytest.mark.spec("attachments", "Хвост после конца изображения") +def test_tail_after_end( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + for content_type, data in ( + ("image/png", images.with_tail(images.sample_png())), + ("image/jpeg", images.with_tail(images.jpeg())), + ): + attachment = api.upload( + alice, + chat["id"], + data, + content_type=content_type, + ) + assert_content( + api.attachment_content(bob, attachment["id"]), + data, + content_type, + ) + + +@pytest.mark.spec("attachments", "Опасное имя") +def test_dangerous_filename( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + names = { + "dot-dot": "../x.png", + "slash": "a/b.png", + "backslash": "a\\b.png", + "nul": "a\x00b.png", + "newline": "a\nb.png", + "del": "a\x7fb.png", + "c1 nel": "a\x85b.png", + "empty": "", + "spaces": " ", + "256": "я" * 256, + } + assert_errors( + { + name: api.post_attachment(alice, chat["id"], data, filename=value) + for name, value in names.items() + } + | { + "missing": api.post_attachment( + alice, + chat["id"], + data, + filename=None, + ), + }, + 400, + ) + + +def assert_name_kept( + api: Api, + actor: Actor, + chat_id: str, + filename: str, +) -> None: + attachment = api.upload( + actor, + chat_id, + images.sample_png(), + filename=filename, + ) + meta = assert_ok( + api.attachment_meta(actor, attachment["id"]), + 200, + "Attachment", + ) + assert meta["filename"] == attachment["filename"] == filename + + +@pytest.mark.spec("attachments", "Имя в Unicode") +def test_unicode_filename( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + family = "👨‍👩‍👧" + core = f"фото {family} отпуска" + name = " " + core + "ё" * (253 - len(core)) + " " + assert len(name) == 255 + assert_name_kept(api, alice, chat["id"], name) + + +@pytest.mark.spec("attachments", "Символы форматирования в имени") +def test_format_characters_in_filename( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + for name in ( + "‮gnp.exe", + "⁦שלום⁩.png", + "строка
вторая.png", + "пере­нос.png", + ): + assert_name_kept(api, alice, chat["id"], name) + + +@pytest.mark.spec("attachments", "Посторонний с большим файлом") +def test_outsider_with_big_file( + api: Api, + eve: Actor, + chat: dict[str, Any], +) -> None: + assert_error(api.post_attachment(eve, chat["id"], big_body()), 404) + + +@pytest.mark.spec("attachments", "Без сессии с опасным именем") +def test_no_session_with_dangerous_name( + api: Api, + chat: dict[str, Any], +) -> None: + for filename in ("a/b.png", "ok.png"): + resp = api.post_attachment( + None, + chat["id"], + images.sample_png(), + filename=filename, + ) + assert_unauthorized(resp, BEARER_CHALLENGE) + + +@pytest.mark.spec("attachments", "Неверный тип и большой размер") +def test_wrong_type_and_big_size( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + resp = api.post_attachment( + alice, + chat["id"], + big_body(), + content_type="text/plain", + ) + assert_error(resp, 415) + + +@pytest.mark.spec("attachments", "Другой участник") +def test_other_member_reads( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + attachment = api.upload(alice, chat["id"], data) + assert_ok(api.attachment_meta(bob, attachment["id"]), 200, "Attachment") + assert_content( + api.attachment_content(bob, attachment["id"]), + data, + "image/png", + ) + + +@pytest.mark.spec("attachments", "Посторонний и неизвестный id") +def test_outsider_and_unknown_id( + api: Api, + alice: Actor, + eve: Actor, + chat: dict[str, Any], +) -> None: + attachment = api.upload(alice, chat["id"], images.sample_png()) + unknown = str(uuid.uuid4()) + responses = { + "eve meta": api.attachment_meta(eve, attachment["id"]), + "eve content": api.attachment_content(eve, attachment["id"]), + "unknown meta": api.attachment_meta(alice, unknown), + "unknown content": api.attachment_content(alice, unknown), + } + assert_errors(responses, 404) + messages = {resp.json()["error"]["message"] for resp in responses.values()} + assert len(messages) == 1, messages + + +@pytest.mark.spec("attachments", "Неверный id вложения") +def test_bad_attachment_id(api: Api, alice: Actor) -> None: + assert_errors( + { + f"{kind} {value}": call(alice, value) + for value in ("123", "abc") + for kind, call in ( + ("meta", api.attachment_meta), + ("content", api.attachment_content), + ) + }, + 400, + ) + + +@pytest.mark.spec("attachments", "Чтение без сессии") +def test_read_without_session( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + attachment = api.upload(alice, chat["id"], images.sample_png()) + for resp in ( + api.attachment_meta(None, attachment["id"]), + api.attachment_content(None, attachment["id"]), + ): + assert_unauthorized(resp, BEARER_CHALLENGE) + + +@pytest.mark.spec("attachments", "Метаданные равны ответу загрузки") +def test_meta_equals_upload( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + attachment = api.upload(alice, chat["id"], images.sample_png()) + meta = assert_ok( + api.attachment_meta(bob, attachment["id"]), + 200, + "Attachment", + ) + assert meta == attachment + + +@pytest.mark.spec("attachments", "Побайтный оригинал") +def test_original_bytes( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + for content_type, data in ( + ("image/png", images.sample_png()), + ("image/jpeg", images.jpeg(size=(320, 200))), + ): + attachment = api.upload( + alice, + chat["id"], + data, + content_type=content_type, + ) + resp = api.attachment_content(bob, attachment["id"]) + assert not resp.is_redirect + assert_content(resp, data, content_type) + assert hashlib.sha256(resp.content).hexdigest() == attachment["sha256"] + + +@pytest.mark.spec("attachments", "Вариант original") +def test_variant_original( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + attachment = api.upload(alice, chat["id"], data) + assert_content( + api.attachment_content(alice, attachment["id"], variant="original"), + data, + "image/png", + ) + assert_errors( + { + variant or "empty": api.attachment_content( + alice, + attachment["id"], + variant=variant, + ) + for variant in ("thumbnail", "") + }, + 400, + ) + + +@pytest.mark.spec("attachments", "Без следов хранилища в ответе") +def test_no_storage_traces( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + upload = api.post_attachment(alice, chat["id"], data) + # assert_ok сверяет тело со схемой контракта: лишних полей нет + attachment = assert_ok(upload, 201, "Attachment") + meta = api.attachment_meta(alice, attachment["id"]) + assert_ok(meta, 200, "Attachment") + content = api.attachment_content(alice, attachment["id"]) + assert_content(content, data, "image/png") + for resp in (upload, meta, content): + assert_no_storage_traces(resp) + + +@pytest.mark.spec("attachments", "Повторная загрузка") +def test_repeated_upload( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + first = api.upload(alice, chat["id"], data) + second = api.upload(alice, chat["id"], data) + assert first["id"] != second["id"] + assert first["sha256"] == second["sha256"] + for attachment in (first, second): + assert_content( + api.attachment_content(bob, attachment["id"]), + data, + "image/png", + ) + + +@pytest.mark.spec("attachments", "Скачивание через другую реплику") +def test_download_through_other_replica( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], + replicas: int, +) -> None: + data = images.sample_png() + upload = api.post_attachment(alice, chat["id"], data) + attachment = assert_ok(upload, 201, "Attachment") + uploaded_via = assert_instance_id(upload) + seen = {uploaded_via} + for _ in range(REPLICA_ATTEMPTS): + resp = api.attachment_content(bob, attachment["id"]) + assert_content(resp, data, "image/png") + seen.add(assert_instance_id(resp)) + if assert_instance_id(resp) != uploaded_via: + break + assert_replicas(seen, replicas) + print(f"uploaded via {uploaded_via}, downloaded via {sorted(seen)}") + + +def test_upload_path_with_quoted_chat_id( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Спек `api-conventions`, «UUID на входе»: `chat_id` загрузки в + другой записи — 400, как у остальных ручек чата.""" + data = images.sample_png() + value = chat["id"] + assert_errors( + { + form: api.post_attachment( + alice, + urllib.parse.quote(raw, safe=""), + data, + ) + for form, raw in ( + ("no hyphens", value.replace("-", "")), + ("urn", f"urn:uuid:{value}"), + ("braces", f"{{{value}}}"), + ("number", "123"), + ) + }, + 400, + ) diff --git a/student-tests/test_data_storage.py b/student-tests/test_data_storage.py index 45634aab..8df9d012 100644 --- a/student-tests/test_data_storage.py +++ b/student-tests/test_data_storage.py @@ -4,9 +4,12 @@ `spec_coverage.py`. """ +from typing import Any + import pytest -from api_client import API, Actor, Api +import images +from api_client import API, Actor, Api, new_key from contract import assert_ok @@ -35,3 +38,34 @@ def test_member_order_kept(api: Api, alice: Actor, bob: Actor) -> None: for chat in page["items"] } assert listed[created["id"]] == expected + + +@pytest.mark.spec("data-storage", "Порядок вложений") +def test_attachment_order_kept( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + a, b, c = ( + api.upload(alice, chat["id"], images.sample_png())["id"] + for _ in range(3) + ) + key = new_key() + order = [c, a, b] + sent = api.send_message( + alice, + chat["id"], + "порядок", + key=key, + attachment_ids=order, + ) + assert sent["attachment_ids"] == order + assert api.all_messages(alice, chat["id"]) == [sent] + replay = api.send_message( + alice, + chat["id"], + "порядок", + key=key, + attachment_ids=order, + ) + assert replay["attachment_ids"] == order diff --git a/student-tests/test_failures.py b/student-tests/test_failures.py index 9d3f97f7..e3d398b5 100644 --- a/student-tests/test_failures.py +++ b/student-tests/test_failures.py @@ -18,9 +18,11 @@ from typing import Any import httpx import pytest +import images from api_client import API, Actor, Api, new_key from contract import ( BEARER_CHALLENGE, + assert_content, assert_error, assert_ok, assert_unauthorized, @@ -45,6 +47,8 @@ READINESS_TIMEOUT_S = 2 # health без S3: проверка к S3 не обращается, ответ быстрее секунды (спек # health, «Хранилище объектов недоступно»); срок вызова S3 — 5 с OBJECT_STORAGE_HEALTH_S = 1 +# [s3] timeout_seconds по умолчанию: срок одного вызова S3 +S3_TIMEOUT_S = 5 # сколько секунд hook держит слоты max_connections; clear-connections # освобождает их раньше FILL_HOLD_S = 30 @@ -526,3 +530,162 @@ def test_key_free_after_ttl(tight_api: Api) -> None: assert second["id"] != first["id"] history = tight_api.all_messages(alice, chat["id"]) assert [item["id"] for item in history] == [first["id"], second["id"]] + + +# --------------------------------------------------------------------------- +# Вложения: S3 остановлен или заморожен, счётчики строк и объектов — hook +# --------------------------------------------------------------------------- + + +def attachment_counts(stand: Stand) -> dict[str, int]: + """Вложения стенда по статусам: `pending=N ready=M` от hook.""" + return { + name: int(value) + for name, value in ( + item.split("=") for item in stand("count-attachments").split() + ) + } + + +def object_count(stand: Stand) -> int: + return int(stand("count-objects")) + + +def upload_raw( + api: Api, + actor: Actor, + chat: dict[str, Any], + data: Any, + **kwargs: Any, +) -> httpx.Response: + return api.post_attachment(actor, chat["id"], data, **kwargs) + + +@pytest.mark.spec("attachments", "Запись в S3 не удалась") +def test_upload_with_object_storage_stopped( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + before = attachment_counts(stand) + with outage(stand, "stop", "s3"): + resp, elapsed = timed(lambda: upload_raw(api, alice, chat, data)) + assert_error(resp, 503) + assert elapsed < S3_TIMEOUT_S + SLACK_S, f"503 after {elapsed:.2f}s" + after = attachment_counts(stand) + # строка-намерение осталась, готовых не прибавилось; её уберёт + # уборщик change upload-consistency + assert after == { + "pending": before["pending"] + 1, + "ready": before["ready"], + } + api.send_message(alice, chat["id"], "текст без S3") + api.upload(alice, chat["id"], data) + + +@pytest.mark.spec("attachments", "Отклонённая загрузка ничего не оставляет") +def test_rejected_uploads_leave_nothing( + api: Api, + stand: Stand, + alice: Actor, + eve: Actor, + chat: dict[str, Any], +) -> None: + big = images.PNG_SIGNATURE + bytes(images.MAX_BYTES * 2) + + def chunked() -> Iterator[bytes]: + for offset in range(0, len(big), 1024 * 1024): + yield big[offset : offset + 1024 * 1024] + + # хотя бы одно готовое вложение: счётчики hook не нулевые случайно + api.upload(alice, chat["id"], images.sample_png()) + before = (attachment_counts(stand), object_count(stand)) + assert before[0]["ready"] >= 1, before + assert before[1] >= 1, before + rejected = ( + (404, upload_raw(api, eve, chat, images.sample_png())), + (413, upload_raw(api, alice, chat, big)), + (413, upload_raw(api, alice, chat, chunked())), + (413, upload_raw(api, alice, chat, images.png_huge(8000, 5001))), + ( + 415, + upload_raw( + api, + alice, + chat, + images.sample_png(), + content_type="text/plain", + ), + ), + (415, upload_raw(api, alice, chat, images.png_idat_byte_changed())), + ) + for status, resp in rejected: + assert_error(resp, status) + assert (attachment_counts(stand), object_count(stand)) == before + + +@pytest.mark.spec("attachments", "S3 остановлен") +def test_object_storage_stopped( + api: Api, + stand: Stand, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + attachment = api.upload(alice, chat["id"], data) + with outage(stand, "stop", "s3"): + resp, elapsed = timed( + lambda: api.attachment_content(bob, attachment["id"]), + ) + assert_error(resp, 503) + assert elapsed < S3_TIMEOUT_S + SLACK_S, f"503 after {elapsed:.2f}s" + meta = assert_ok( + api.attachment_meta(bob, attachment["id"]), + 200, + "Attachment", + ) + assert meta == attachment + api.send_message( + bob, + chat["id"], + "", + attachment_ids=[attachment["id"]], + ) + assert_ok(api.request("GET", "/health/ready"), 200, "Health") + assert_content( + api.attachment_content(bob, attachment["id"]), + data, + "image/png", + ) + + +@pytest.mark.spec("attachments", "S3 завис") +def test_object_storage_paused( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + attachment = api.upload(alice, chat["id"], data) + # срок клиента больше срока вызова S3: ждём ответ API, а не свой обрыв + slow = Api(str(api.client.base_url), timeout=3 * S3_TIMEOUT_S) + with slow, outage(stand, "pause", "s3"): + for call in ( + lambda: upload_raw(slow, alice, chat, data), + lambda: slow.attachment_content(alice, attachment["id"]), + ): + resp, elapsed = timed(call) + assert_error(resp, 503) + # срок вызова S3 и немного на шаги с БД, а не зависание + assert elapsed < S3_TIMEOUT_S + 2 * SLACK_S, ( + f"503 after {elapsed:.2f}s" + ) + assert_content( + api.attachment_content(alice, attachment["id"]), + data, + "image/png", + ) diff --git a/student-tests/test_idempotency.py b/student-tests/test_idempotency.py index 401a01ba..f9d91d06 100644 --- a/student-tests/test_idempotency.py +++ b/student-tests/test_idempotency.py @@ -11,6 +11,7 @@ from typing import Any import pytest +import images from api_client import ( API, IDEMPOTENCY_KEY, @@ -148,6 +149,95 @@ def test_other_body_conflict( assert api.send_message(alice, chat["id"], "первое", key=key) == first +def two_attachments(api: Api, actor: Actor, chat_id: str) -> list[str]: + return [ + api.upload(actor, chat_id, images.sample_png())["id"] for _ in range(2) + ] + + +@pytest.mark.spec("idempotency", "Вложения по умолчанию") +def test_replay_with_default_attachments( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + key = new_key() + first = api.send_message(alice, chat["id"], "без файлов", key=key) + again = api.send_message( + alice, + chat["id"], + "без файлов", + key=key, + attachment_ids=[], + ) + assert again == first + assert texts(api, alice, chat["id"]) == ["без файлов"] + + +@pytest.mark.spec("idempotency", "Повтор сообщения с вложениями") +def test_replay_with_attachments( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + first_id, second_id = two_attachments(api, alice, chat["id"]) + key = new_key() + ids = [first_id, second_id] + first = api.send_message( + alice, + chat["id"], + "файлы", + key=key, + attachment_ids=ids, + ) + again = api.send_message( + alice, + chat["id"], + "файлы", + key=key, + attachment_ids=ids, + ) + upper = api.send_message( + alice, + chat["id"], + "файлы", + key=key, + attachment_ids=[item.upper() for item in ids], + ) + assert first == again == upper + assert first["attachment_ids"] == ids + history = api.all_messages(alice, chat["id"]) + assert [item["id"] for item in history] == [first["id"]] + + +@pytest.mark.spec("idempotency", "Другие вложения") +def test_other_attachments_conflict( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + first_id, second_id = two_attachments(api, alice, chat["id"]) + key = new_key() + first = api.send_message( + alice, + chat["id"], + "файлы", + key=key, + attachment_ids=[first_id, second_id], + ) + for body in ( + {"text": "файлы", "attachment_ids": [second_id, first_id]}, + {"text": "файлы"}, + ): + assert_error( + api.post_message(alice, chat["id"], key=key, json=body), + 409, + ) + history = api.all_messages(alice, chat["id"]) + assert history == [first] + assert history[0]["attachment_ids"] == [first_id, second_id] + + @pytest.mark.spec("idempotency", "Другой пользователь") def test_same_key_other_user( api: Api, diff --git a/student-tests/test_messages.py b/student-tests/test_messages.py index 77b5d04e..461b7597 100644 --- a/student-tests/test_messages.py +++ b/student-tests/test_messages.py @@ -1,12 +1,14 @@ -"""Спек `messages`: отправка, валидация текста, история.""" +"""Спек `messages`: отправка, валидация текста, история, вложения.""" +import uuid from typing import Any import httpx import pytest +import images from api_client import Actor, Api, order_key -from contract import assert_error, assert_ok +from contract import assert_error, assert_errors, assert_ok def send_raw( @@ -30,6 +32,217 @@ def test_member_sends( assert message["sender_id"] == alice.id assert message["chat_id"] == chat["id"] assert message["text"] == "Привет, мир 👋" + assert message["attachment_ids"] == [] + + +def upload(api: Api, actor: Actor, chat_id: str) -> str: + """Готовое вложение чата; id.""" + return api.upload(actor, chat_id, images.sample_png())["id"] + + +@pytest.mark.spec("messages", "Сообщение с вложениями") +def test_message_with_attachments( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + first, second = ( + upload(api, alice, chat["id"]), + upload(api, alice, chat["id"]), + ) + message = api.send_message( + alice, + chat["id"], + "два файла", + attachment_ids=[second, first], + ) + assert message["attachment_ids"] == [second, first] + + +@pytest.mark.spec("messages", "Пустой текст с вложением") +def test_empty_text_with_attachment( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + attachment_id = upload(api, alice, chat["id"]) + message = api.send_message( + alice, + chat["id"], + "", + attachment_ids=[attachment_id], + ) + assert message["text"] == "" + assert message["attachment_ids"] == [attachment_id] + + +@pytest.mark.spec("messages", "Пробелы с вложением") +def test_blank_text_with_attachment( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Согласовано с преподавателем 2026-10-20: пустой текст — и `""`, и + из одних пробелов; с вложением допустим и не нормализуется.""" + attachment_id = upload(api, alice, chat["id"]) + message = api.send_message( + alice, + chat["id"], + " ", + attachment_ids=[attachment_id], + ) + assert message["text"] == " " + assert message["attachment_ids"] == [attachment_id] + assert_error(send_raw(api, alice, chat["id"], {"text": " "}), 400) + assert [item["id"] for item in api.all_messages(alice, chat["id"])] == [ + message["id"], + ] + + +@pytest.mark.spec("messages", "Вложения в истории") +def test_attachments_in_history( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + first, second = ( + upload(api, alice, chat["id"]), + upload(api, alice, chat["id"]), + ) + with_files = api.send_message( + alice, + chat["id"], + "с файлами", + attachment_ids=[second, first], + ) + plain = api.send_message(bob, chat["id"], "без файлов") + history = api.all_messages(bob, chat["id"]) + assert history == sorted([with_files, plain], key=order_key) + by_id = {item["id"]: item["attachment_ids"] for item in history} + assert by_id == {with_files["id"]: [second, first], plain["id"]: []} + + +@pytest.mark.spec("messages", "Вложение другого участника") +def test_attachment_of_other_member( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + attachment_id = upload(api, alice, chat["id"]) + api.send_message(bob, chat["id"], "ответ", attachment_ids=[attachment_id]) + + +@pytest.mark.spec("messages", "Вложение другого чата") +def test_attachment_of_other_chat( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + other = api.create_chat(alice, bob, title="Y") + attachment_id = upload(api, alice, other["id"]) + resp = send_raw( + api, + alice, + chat["id"], + {"text": "чужой чат", "attachment_ids": [attachment_id]}, + ) + assert_error(resp, 404) + assert api.all_messages(alice, chat["id"]) == [] + + +@pytest.mark.spec("messages", "Чужое вложение") +def test_foreign_attachment( + api: Api, + alice: Actor, + eve: Actor, + chat: dict[str, Any], +) -> None: + eve_chat = api.create_chat(eve, title="Ева") + attachment_id = upload(api, eve, eve_chat["id"]) + resp = send_raw( + api, + alice, + chat["id"], + {"text": "", "attachment_ids": [attachment_id]}, + ) + assert_error(resp, 404) + assert api.all_messages(alice, chat["id"]) == [] + + +@pytest.mark.spec("messages", "Неизвестное вложение") +def test_unknown_attachment( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + resp = send_raw( + api, + alice, + chat["id"], + {"text": "x", "attachment_ids": [str(uuid.uuid4())]}, + ) + assert_error(resp, 404) + assert api.all_messages(alice, chat["id"]) == [] + + +@pytest.mark.spec("messages", "Неверный список вложений") +def test_bad_attachment_list( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + attachment_id = upload(api, alice, chat["id"]) + bodies = { + "repeat": [attachment_id, attachment_id], + "repeat upper": [attachment_id, attachment_id.upper()], + "eleven": [str(uuid.uuid4()) for _ in range(11)], + "string": attachment_id, + "number item": [123], + "123 item": ["123"], + } + assert_errors( + { + name: send_raw( + api, + alice, + chat["id"], + {"text": "x", "attachment_ids": value}, + ) + for name, value in bodies.items() + }, + 400, + ) + assert api.all_messages(alice, chat["id"]) == [] + + +@pytest.mark.spec("messages", "Одно вложение в двух сообщениях") +def test_one_attachment_in_two_messages( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + attachment_id = upload(api, alice, chat["id"]) + first = api.send_message( + alice, + chat["id"], + "раз", + attachment_ids=[attachment_id], + ) + second = api.send_message( + alice, + chat["id"], + "два", + attachment_ids=[attachment_id], + ) + assert first["id"] != second["id"] + history = api.all_messages(alice, chat["id"]) + assert [item["attachment_ids"] for item in history] == [ + [attachment_id], + [attachment_id], + ] @pytest.mark.spec("messages", "Граница длины") diff --git a/student-tests/test_rubric.py b/student-tests/test_rubric.py index 5697c4e7..2d009024 100644 --- a/student-tests/test_rubric.py +++ b/student-tests/test_rubric.py @@ -1,15 +1,18 @@ """Обязательные сценарии уровня «4» (README.md, рубрика).""" import uuid +from collections.abc import Iterator from typing import Any import pytest +import images from api_client import API, Actor, Api, key_headers, order_key, registration from contract import ( BASIC_CHALLENGE, BEARER_CHALLENGE, assert_error, + assert_errors, assert_unauthorized, ) @@ -134,3 +137,147 @@ def test_history_walk_across_pages( items = [item for page in pages for item in page["items"]] assert len({item["id"] for item in items}) == len(sent) assert items == sorted(sent, key=order_key) + + +# --- лаба 4: негативные тесты вложений (спек student-tests) ------------- + + +def _chunks(data: bytes, size: int = 1024 * 1024) -> Iterator[bytes]: + for offset in range(0, len(data), size): + yield data[offset : offset + size] + + +@pytest.mark.spec("attachments", "Заявленный размер больше лимита") +@pytest.mark.spec("attachments", "Большое тело без Content-Length") +def test_rubric_too_big_file( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Спек `student-tests`, «Слишком большой файл в рубрике»: больше + 10 MiB с `Content-Length` и частями — 413 в формате контракта.""" + data = images.png_of_size(images.MAX_BYTES + 1024 * 1024) + assert_errors( + { + "content-length": api.post_attachment(alice, chat["id"], data), + "chunked": api.post_attachment(alice, chat["id"], _chunks(data)), + }, + 413, + ) + + +@pytest.mark.spec("attachments", "Обрезанный файл") +@pytest.mark.spec("attachments", "Испорченные данные PNG") +def test_rubric_damaged_image( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Спек `student-tests`, «Повреждённое изображение в рубрике»: + обрезанные PNG и JPEG и PNG с изменённым байтом данных — 415.""" + assert_errors( + { + "png cut": api.post_attachment( + alice, + chat["id"], + images.truncated(images.sample_png()), + ), + "jpeg cut": api.post_attachment( + alice, + chat["id"], + images.truncated(images.jpeg()), + content_type="image/jpeg", + ), + "png byte": api.post_attachment( + alice, + chat["id"], + images.png_idat_byte_changed(), + ), + }, + 415, + ) + + +@pytest.mark.spec("attachments", "Подмена MIME") +@pytest.mark.spec("attachments", "Не изображение") +def test_rubric_mime_spoofing( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Спек `student-tests`, «Подмена MIME в рубрике»: JPEG как PNG и + текст как JPEG — 415.""" + assert_errors( + { + "jpeg as png": api.post_attachment( + alice, + chat["id"], + images.jpeg(), + content_type="image/png", + ), + "text as jpeg": api.post_attachment( + alice, + chat["id"], + b"plain text, not an image", + content_type="image/jpeg", + ), + }, + 415, + ) + + +@pytest.mark.spec("messages", "Чужое вложение") +@pytest.mark.spec("messages", "Неизвестное вложение") +@pytest.mark.spec("attachments", "Посторонний и неизвестный id") +def test_rubric_foreign_attachment_id( + api: Api, + alice: Actor, + eve: Actor, + chat: dict[str, Any], +) -> None: + """Спек `student-tests`, «Чужое attachment_id в рубрике»: сообщение с + вложением чужого чата и с неизвестным id, чтение постороннего — 404.""" + eve_chat = api.create_chat(eve, title="Ева") + eve_attachment = api.upload(eve, eve_chat["id"], images.sample_png()) + alice_attachment = api.upload(alice, chat["id"], images.sample_png()) + assert_errors( + { + "foreign in message": api.post_message( + alice, + chat["id"], + json={"text": "x", "attachment_ids": [eve_attachment["id"]]}, + ), + "unknown in message": api.post_message( + alice, + chat["id"], + json={"text": "x", "attachment_ids": [str(uuid.uuid4())]}, + ), + "outsider meta": api.attachment_meta(eve, alice_attachment["id"]), + "outsider content": api.attachment_content( + eve, + alice_attachment["id"], + ), + }, + 404, + ) + assert api.all_messages(alice, chat["id"]) == [] + + +@pytest.mark.spec("messages", "Вложение другого чата") +def test_rubric_attachment_of_other_chat( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + """Спек `student-tests`, «Вложение другого чата в рубрике»: участник + двух чатов шлёт в один вложение другого — 404, в истории пусто.""" + other = api.create_chat(alice, bob, title="Второй чат") + attachment = api.upload(alice, other["id"], images.sample_png()) + resp = api.post_message( + alice, + chat["id"], + json={"text": "", "attachment_ids": [attachment["id"]]}, + ) + assert_error(resp, 404) + assert api.all_messages(alice, chat["id"]) == [] diff --git a/uv.lock b/uv.lock index 073ebc78..3186e69b 100644 --- a/uv.lock +++ b/uv.lock @@ -769,6 +769,7 @@ dev = [ { name = "httpx" }, { name = "jsonschema" }, { name = "openapi-spec-validator" }, + { name = "pillow" }, { name = "pre-commit" }, { name = "pytest" }, ] @@ -796,6 +797,7 @@ dev = [ { name = "httpx", specifier = ">=0.28.1,<1" }, { name = "jsonschema", specifier = ">=4.26.0,<5" }, { name = "openapi-spec-validator", specifier = "==0.7.2" }, + { name = "pillow", specifier = ">=13.0.0,<14" }, { name = "pre-commit", specifier = ">=4.5.0" }, { name = "pytest", specifier = ">=9.1.1,<10" }, ] @@ -903,6 +905,28 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f1/d9/7fb5aa316bc299258e68c73ba3bddbc499654a07f151cba08f6153988714/pathspec-1.1.1-py3-none-any.whl", hash = "sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189", size = 57328, upload-time = "2026-04-27T01:46:07.06Z" }, ] +[[package]] +name = "pillow" +version = "13.0.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ce/a4/9cc30690a394a8305e8be4c9036aa16d0dfddadd09079860b582f562496d/pillow-13.0.0.tar.gz", hash = "sha256:cdcd1ba258178f7356d74170c9a81ba4eab6a5d55748bc402a5a2a6fe6be3510", size = 47058631, upload-time = "2026-10-16T22:18:09.718Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/7a/b8/58d79332229482eb0d27c82973850808c19d37e5bdc14443d3417bd373f5/pillow-13.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:67c8d44ad89fa7eb88de5d6ef6199b1e03dd24974f85a67639fc8badb801fe79", size = 5568643, upload-time = "2026-10-16T22:15:44.474Z" }, + { url = "https://files.pythonhosted.org/packages/39/4b/f2ed53d83aa44ac19599ac0a54897f867fafb95f406980d1e24083f8cbe3/pillow-13.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fc481f742ccda20e9ed760b8f978dff50f2a4e9bc253ac167fb0a05b0783ef52", size = 4852329, upload-time = "2026-10-16T22:15:46.284Z" }, + { url = "https://files.pythonhosted.org/packages/3b/bb/9e30e8ed18c20800ee327a12107d5249ad8dc444867b3adfcc21654e3c71/pillow-13.0.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8bf295fe459343bc6093c8e5e0df60bfa189e0fcb775a22e2c2488fdeccc6c0d", size = 6519309, upload-time = "2026-10-16T22:15:48.14Z" }, + { url = "https://files.pythonhosted.org/packages/e6/99/fdf65cc539e266ab93546c261bdf98411fe165c6e4e13f9dbf597097192b/pillow-13.0.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:42d63be3af4f9b951b199b0a9d23365d37ab14687e6d77b74940432c8515c4ca", size = 7144542, upload-time = "2026-10-16T22:15:50.093Z" }, + { url = "https://files.pythonhosted.org/packages/26/9b/f38b7c4d8f599537e2d1a6d546cec9beef7536ff8f5c49a3f9c78179d8ac/pillow-13.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:4bd024d567eca931b668978d672dba914d4b8e2628e2c3073a2ad178de8a2620", size = 6618042, upload-time = "2026-10-16T22:15:52.054Z" }, + { url = "https://files.pythonhosted.org/packages/a8/7c/45ee28531f89ee4582967d8a17f7a26d71ca64cd902b93c269590cd60a00/pillow-13.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:23edf4ec4b6f4f240e8df6e4985e9ee2ced86474632433e55fb1e2548744bf40", size = 7228137, upload-time = "2026-10-16T22:15:54.009Z" }, + { url = "https://files.pythonhosted.org/packages/01/bc/9c2a969cb1b70201d04fa17fd5aedf02a732870b8da86bceaaa30b0ca385/pillow-13.0.0-cp312-cp312-win32.whl", hash = "sha256:02464da86f561f410e13b061ec37c3068a9cb557a095494157742d07b3c24a27", size = 6515423, upload-time = "2026-10-16T22:15:56.25Z" }, + { url = "https://files.pythonhosted.org/packages/ff/cd/73a79ecdc822076002eb24b5e1e4a530b0bb5310fcb6d239abbec877110b/pillow-13.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:ff3fe9eb621fbb9db4c4be33ab946f6bac5f98ab50ca8d3260503653656c961b", size = 7272166, upload-time = "2026-10-16T22:15:58.597Z" }, + { url = "https://files.pythonhosted.org/packages/4a/a3/be5a1236efd085b3984e4305da8f179ae9dab80c991d2ad78f2bd5c4c843/pillow-13.0.0-cp312-cp312-win_arm64.whl", hash = "sha256:c3bc8ee0271387e0b1e3ad0ff893645990a656e79bf9c42f4f734a3642b11d51", size = 2698943, upload-time = "2026-10-16T22:16:00.637Z" }, + { url = "https://files.pythonhosted.org/packages/60/da/f6d644e631c5b370c5d0b899f3ccadd2780aab070b29a110527cf4e1fd2c/pillow-13.0.0-pp312-pypy312_pp80-macosx_10_15_x86_64.whl", hash = "sha256:8619685cad8efc4c38c66d3b36aad854523297c43d748b3b6f0cc03c90ba3463", size = 5523188, upload-time = "2026-10-16T22:17:59.334Z" }, + { url = "https://files.pythonhosted.org/packages/e4/b0/2594f202d743a35d4fe80682bfd96f277e5ca7aecb27cf64ef5bfc1d000b/pillow-13.0.0-pp312-pypy312_pp80-macosx_11_0_arm64.whl", hash = "sha256:7e91e97a929232cdb828889ee6ad0e48d7f40f4ec38818f4e4a8968b2b1af22e", size = 4806808, upload-time = "2026-10-16T22:18:01.188Z" }, + { url = "https://files.pythonhosted.org/packages/8e/ed/d504165ef79af6fafe25c76726cf30f544cc236002f7ed054f1d51adc4ff/pillow-13.0.0-pp312-pypy312_pp80-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:93ff9c9c3663ce23aaa5d0b6b6abac55359e2a0c06c7e30f3771829af816be63", size = 5464358, upload-time = "2026-10-16T22:18:02.779Z" }, + { url = "https://files.pythonhosted.org/packages/7b/fe/a10aba5503ca13e9e009b8bd0a1a4ce5584bdce246245fd6f3a83701369c/pillow-13.0.0-pp312-pypy312_pp80-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e65dd6e75de67b2362a4fa3e16aa627595f65054dc4ec73d64680c84d592fa61", size = 6043514, upload-time = "2026-10-16T22:18:04.538Z" }, + { url = "https://files.pythonhosted.org/packages/c0/37/66b12dc476041fe523bca29c9d58fbf1ea92a4eaf73acfb9e993948f1191/pillow-13.0.0-pp312-pypy312_pp80-win_amd64.whl", hash = "sha256:567f20f1c75897d7663830da6ea8af719e03d712b1d9ee7f813319f9ece42e5a", size = 7366030, upload-time = "2026-10-16T22:18:06.638Z" }, +] + [[package]] name = "platformdirs" version = "4.11.13"