feat: add image attachments to messages

- upload, metadata and download endpoints for PNG/JPEG attachments:
  limits before reading and decompression, type by content,
  structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
  per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
  whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
  CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
  rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-21 01:08:56 +03:00
co-authored by Claude Opus 5.5
parent 73779f7acd
commit 116d8d3bf0
72 changed files with 5546 additions and 247 deletions
+67 -9
View File
@@ -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.
+33
View File
@@ -27,6 +27,10 @@ FastAPI, один процесс на реплику; реплик ≥2 за HAP
Вложенный ресурс — префикс с параметром: `message.py` →
`prefix="/chats/{chat_id}/messages"`. Логгер модуля
`module="api_<domain>_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`.
+17 -7
View File
@@ -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 <commit>`): `git archive
<commit> | docker build`
под тегом `mtusi-messenger:bench-from`, затем `docker tag` на
`mtusi-messenger:bench`. Рабочее дерево не трогается; тег снимается
при уборке. `--from <commit>` — отладка (`overrides`).
- Реплики стартуют на образе `Profile.rollout_from`: `git archive
<commit> | docker build` под тегом `mtusi-messenger:bench-from`, затем
`docker tag` на `mtusi-messenger:bench`. Рабочее дерево не трогается;
тег снимается при уборке. `--from <commit>` — отладка (`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>^{commit}`): нет в истории — код 2, сообщение называет commit
и `--from`. Commit — в паспорте метки (`rollout.from_commit`).
- Замену делает **тот же** `scripts/rolling-update.sh`, что у рабочего
стенда. Правило «`-p mtusi-bench`, оба `-f`, `--env-file`»
выполняется переменными `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`,
+8
View File
@@ -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, ...] = ()` — значение по
умолчанию последним полем.
+11
View File
@@ -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 — только в лог, никогда в ответ.
## Где логировать
+17
View File
@@ -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 вместе с ним:
+19
View File
@@ -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` собирает `<namespace>/attachments/<id>/
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) живут здесь. Ключ включает
+27
View File
@@ -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 — не ошибка, а
+9 -2
View File
@@ -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 процесса (один раз, при
+44
View File
@@ -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` (каталоги `<id>` под `/buckets/<bucket>/<база>/
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`,
+36 -8
View File
@@ -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 <token из ответа выше>
python3 $D req POST /api/v1/chats/<chat>/messages --token <token> --data '{"text":"hi"}'
# печатает idempotency-key; повтор той же отправки — тот же запрос с --key <ключ>
python3 $D upload --token <token> --chat <chat> --file tests/fixtures/sample.png
# 201, x-instance-id, Attachment, SHA-256 файла и «sha256 matches: True»
python3 $D download --token <token> --attachment <id> [--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:<port> — ~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:<id>` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_<db>`) базы. Код 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/<id>/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` находит реплику). Другое значение —
@@ -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/<id>/
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/<id>/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,
+43 -21
View File
@@ -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 <LB> attachment-failover [--mode stop\|kill]` | вложение через LB, `stop-one.sh` принявшей реплики, скачивание через другую (тот же SHA-256), 404 постороннему, затем `make replicas`; доказательство исключения `attachments` «Принявшая реплика остановлена» |
| `driver.py --port <LB> 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/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py)
schemas/<domain>.py # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12
dependencies.py # сессия БД, фабрики сервисов (с кэшем), разбор Basic, текущая сессия по Bearer, пагинация
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra), метаданные, байты StreamingResponse
schemas/<domain>.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/<domain>.py # атомарный доступ к хранилищу, модульные функции
repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата
repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ и сообщение одной транзакцией
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing
repos/attachment.py # строки вложений: вставка pending, mark_ready (pending → ready RETURNING), чтение одной и до 10
repos/attachment_object.py # оригинал в S3: ключ <база>/attachments/<id>/original, put, open
repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией
services/attachment.py # AttachmentService(db_scope, cache, storage): загрузка (проверки → тело со счётчиком → структура и SHA-256 в потоке → pending → PUT → ready), метаданные, отдача потоком
exceptions/<domain>.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/<domain>.py # DTO между repo → service → api
enums/<domain>.py # StrEnum доменов, RunModeEnum
enums/<domain>.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_<db>, уборка базы и префикса test_<db>/ в 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 <LB> attachment-failover` (оба режима)
→ `evidence/attachments/failover.md` и `driver.py --port <LB>
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, потом править код. Обновить этот файл: номер лабы,
таблицу важных файлов, новые правила.
+23 -16
View File
@@ -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 `<NOSRV>` от 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)»
+26 -5
View File
@@ -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,
+41 -6
View File
@@ -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 <commit> 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"
@@ -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")
+61 -19
View File
@@ -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
@@ -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: История чата
+36 -32
View File
@@ -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`,
+33 -9
View File
@@ -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` в них — в нижнем регистре
+456
View File
@@ -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/<id>/original` и не содержит
`filename`, объект с этим ключом есть в bucket, анонимный GET его
ключа — 403, а в контейнерах реплик нет файлов оригиналов
#### Scenario: Повторная загрузка
- **WHEN** участник дважды загружает один и тот же файл
- **THEN** оба ответа 201 с разными `id` и одинаковым `sha256`, и оба
вложения скачиваются
### Requirement: Порядок записи
Загрузка SHALL выполняться по шагам:
1. проверки и чтение тела;
2. запись метаданных в статусе «загружается» (`pending`) вместе с
ключом объекта, фиксация в PostgreSQL;
3. запись объекта в S3;
4. статус `ready`, фиксация;
5. ответ 201.
Объект, который записал API, SHALL быть известен PostgreSQL до записи в
S3. Вложение не в статусе `ready` MUST NOT быть видно через API: его
метаданные и байты — 404, ссылка на него в сообщении — 404. Если не
удались запись в S3 или фиксация `ready`, ответ SHALL быть 503
`unavailable`, строка «загружается» остаётся. Её и объект убирает
уборщик (change `upload-consistency`). Загрузка, отклонённая до шага 2
(401, 400, 404, 413, 415), MUST NOT оставлять ни строки, ни объекта.
#### Scenario: Запись в S3 не удалась
- **WHEN** S3 остановлен, и участник загружает настоящий PNG
- **THEN** ответ 503 `unavailable`, в PostgreSQL на одно вложение в
статусе «загружается» больше, готовых — столько же
- **AND** текстовое сообщение в тот же чат — 201, а после возврата S3
та же загрузка — 201
#### Scenario: Отклонённая загрузка ничего не оставляет
- **WHEN** участник и посторонний отправляют загрузки, которые
отклоняются с 404, 413 по `Content-Length`, 413 по счётчику, 413 по
пикселям, 415 по типу и 415 по целостности
- **THEN** число вложений в PostgreSQL в каждом статусе и число
объектов вложений в bucket не изменились
### Requirement: Недоступность S3
Если S3 недоступен, не ответил за срок вызова или отказал
(`object-storage`), загрузка и скачивание байтов SHALL отвечать 503
`unavailable` в формате ошибки. Ответ SHALL приходить не позже срока
вызова S3 с запасом, а не 500 и не зависанием. Без S3 SHALL работать:
- метаданные вложения;
- история чата с `attachment_ids`;
- отправка сообщений, в том числе со ссылкой на готовое вложение;
- `/health/ready`.
После возврата S3 загрузка и скачивание SHALL проходить без перезапуска
API.
#### Scenario: S3 остановлен
- **WHEN** вложение загружено, затем S3 остановлен, и участник
скачивает байты, читает метаданные, отправляет сообщение с этим
вложением и запрашивает `/health/ready`
- **THEN** скачивание — 503 `unavailable`, метаданные — 200, сообщение
— 201, готовность — 200
- **AND** после возврата S3 скачивание — 200 с теми же байтами
#### Scenario: S3 завис
- **WHEN** контейнер S3 заморожен (`docker pause`), и участник
загружает файл и скачивает байты готового вложения
- **THEN** оба ответа 503 `unavailable` не позже срока вызова S3 с
запасом, а после разморозки скачивание — 200
### Requirement: Вложение доступно через любую реплику
Готовое вложение SHALL скачиваться через любую реплику API за
балансировщиком, в том числе после остановки реплики, которая его
приняла. Метаданные и оригинал SHALL переживать перезапуск стенда
(`scripts/restart.sh`, вместе с S3) с сохранёнными volumes и читаться
прежним токеном.
#### Scenario: Скачивание через другую реплику
- **WHEN** вложение загружено через балансировщик, ответ дала реплика
с одним `X-Instance-Id`
- **THEN** байты скачиваются через реплику с другим `X-Instance-Id` и
совпадают с загруженными
#### Scenario: Принявшая реплика остановлена
- **WHEN** вложение загружено через балансировщик, затем реплика с
`X-Instance-Id` ответа на загрузку остановлена `scripts/stop-one.sh`
- **THEN** метаданные и байты через балансировщик — 200 от другой
реплики, SHA-256 совпадает с загруженным, посторонний получает 404
#### Scenario: Рестарт стенда
- **WHEN** вложение загружено, затем выполнен `scripts/restart.sh`
- **THEN** прежним токеном метаданные — 200, а байты совпадают с
загруженными по SHA-256
+36 -10
View File
@@ -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 выполняться одной
+24 -8
View File
@@ -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 применять миграции
+34 -5
View File
@@ -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 быть уникален в пределах пользователя и чата: метод и путь
+28
View File
@@ -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 <commit>` для отладки.
#### Scenario: Замена на схему с вложениями
- **WHEN** выполнен `make bench_rollout_quick` на коде с вложениями
- **THEN** реплики стартуют на образе commit до change `attachments`,
ревизия схемы до замены — без таблиц вложений, после — с ними, а
команда завершается с кодом 0
#### Scenario: Commit вне истории
- **WHEN** commit методики не найден в репозитории
- **THEN** команда завершается с ненулевым кодом до запуска стенда, а
сообщение называет commit и `--from`
+106 -10
View File
@@ -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`
@@ -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: лимиты остались контрактными
+13 -2
View File
@@ -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`,
+67 -14
View File
@@ -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
+3
View File
@@ -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]
+61 -4
View File
@@ -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
+9
View File
@@ -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),
+2
View File
@@ -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",
+153
View File
@@ -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),
)
+1
View File
@@ -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)
+3
View File
@@ -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",
+64
View File
@@ -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
+24 -7
View File
@@ -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):
+12
View File
@@ -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",
]
+39
View File
@@ -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"
+107
View File
@@ -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]
+49
View File
@@ -0,0 +1,49 @@
"""Оригинал вложения в S3: ключ объекта и операции над ним.
Repo над хранилищем объектов, как `chat_cache.py` над Valkey: первый
параметр — `storage`, один вызов на функцию. Ключ —
`<имя базы>/attachments/<id>/original` (design change `attachments`,
решение 4): назначает сервер, `filename` в него не входит; объекты
`make test_isolated` лежат под `test_<db>/`. Ключ хранится в строке
вложения и при чтении берётся оттуда.
"""
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)
+5 -6
View File
@@ -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),
)
+70 -7
View File
@@ -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]
+2
View File
@@ -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",
+293
View File
@@ -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,
)
+74 -11
View File
@@ -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,
*,
+3
View File
@@ -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",
]
+117
View File
@@ -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"))
+6 -6
View File
@@ -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) > (...)
+3
View File
@@ -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",
+43
View File
@@ -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]]
+2
View File
@@ -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)
+3
View File
@@ -1,5 +1,8 @@
from .attachment import AttachmentStatus, ImageType
from .settings import RunModeEnum
__all__ = [
"AttachmentStatus",
"ImageType",
"RunModeEnum",
]
+20
View File
@@ -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"
+24
View File
@@ -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/<id>/original`
ATTACHMENT_KEY_PREFIX = "attachments"
ATTACHMENT_ORIGINAL_SUFFIX = "original"
# блок чтения тела загрузки не больше этого, байты
ATTACHMENT_READ_CHUNK_BYTES = 64 * 1024
# пагинация
PAGE_LIMIT_MIN = 1
+393
View File
@@ -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")
+94 -3
View File
@@ -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,
+45 -3
View File
@@ -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", "")
+57 -2
View File
@@ -28,15 +28,25 @@
db-sessions pg_stat_database.sessions базы стенда:
сколько сессий PostgreSQL приняла за всё
время (учитывает и сессию самого вызова)
count-attachments вложения в базе стенда по статусам:
`pending=N ready=M`
count-objects число вложений с объектами в bucket стенда:
каталоги `<id>` под `<база>/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`
свой каталог `<id>`. Нет префикса — 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}")
+227
View File
@@ -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),
}
+21 -6
View File
@@ -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",
+21
View File
@@ -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 <LB> 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 <LB> 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 <LB> auth-storage: префикс $argon2id$ и "
+69
View File
@@ -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"]]
+657
View File
@@ -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,
)
+35 -1
View File
@@ -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
+163
View File
@@ -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",
)
+90
View File
@@ -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,
+215 -2
View File
@@ -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", "Граница длины")
+147
View File
@@ -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"]) == []
Generated
+24
View File
@@ -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"