diff --git a/openspec/changes/add-lab4-image-attachments/.openspec.yaml b/openspec/changes/add-lab4-image-attachments/.openspec.yaml new file mode 100644 index 00000000..1bb6456d --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-28 diff --git a/openspec/changes/add-lab4-image-attachments/design.md b/openspec/changes/add-lab4-image-attachments/design.md new file mode 100644 index 00000000..6581df15 --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/design.md @@ -0,0 +1,155 @@ +## Context + +Мотивация — в `proposal.md`. Решение лабы 3 — две зоны (`identity`, `messaging`) за HAProxy с ≥2 репликами, PostgreSQL как источник истины, Valkey как кэш сессий, ASGI-конвейер с лимитом тела 1 MiB по `Content-Length`, UoW с событиями. Реплики уже не держат состояния; вложения добавляют второе хранилище, где транзакции PostgreSQL не действуют. Инфраструктура S3, хуки и сценарии заранее проверены на заглушке в `.prep/lab4` и встраиваются, а не пишутся заново: MinIO community на arm64 не скачивается (`minio/minio` удалён с Docker Hub, quay отвечает 401), поэтому выбран RustFS 1.0.4 + `rc` v0.1.36. + +## Goals / Non-Goals + +**Goals:** +- Байты — только в bucket, метаданные — только в PostgreSQL; ни одна реплика не держит файл, от которого зависит ответ другой. +- Каждый лимит применяется раньше дорогого шага: заголовок → поток → заголовок изображения → проверка файла. +- `201` ровно тогда, когда обе записи подтверждены; любой сбой оставляет только невидимое клиенту состояние. +- Зоны по-прежнему не импортируют друг друга и не читают чужие таблицы. + +**Non-Goals:** +- Компенсирующий `DeleteObject`, очистка `pending` по grace period, лимит одновременных загрузок и замер памяти — уровень «4». +- Reconciler, карантин и глубокая сверка — трек 2. + +## Decisions + +### D1. Зона `attachments` и связь с `messaging` + +Новая зона `attachments/` со слоями `domain` (агрегат `Attachment`, значения `Filename`, `ImageKind`, `ImageInfo`, ошибки, событие `AttachmentStored`), `application` (команда `UploadAttachment`, запросы `GetAttachment` и `OpenAttachment`, порты), `infrastructure` (PostgreSQL, S3, Pillow) и `entrypoints` (роутер, схемы, DI, журнал, реестр ошибок). + +Зоне нужен один ответ от `messaging`: «входит ли пользователь в чат». Порт `ChatMembership.is_member(chat_id, user_id)` объявлен в `attachments/application/ports.py`; адаптер `MessagingMembership` поверх `ChatDirectory.chat_for_member` зоны `messaging` и его провайдер dishka живут в `main.py` — единственном месте, которое знает обе зоны. Целостность в БД держат внешние ключи, а не чужие `SELECT`: + +- `attachments (chat_id, owner_id) → chat_members (chat_id, user_id)`: загрузить можно только в свой чат, гонка с проверкой порта ловится `ForeignKeyViolationError` → `404`; +- `message_attachments (attachment_id, chat_id) → attachments (id, chat_id) ON DELETE RESTRICT`: сообщение ссылается только на вложение своего чата, а удалить используемое вложение нельзя. Нарушение (`message_attachments_attachment_fkey`) → `UnknownAttachment` зоны `messaging` → `404`. + +Что получаем: SQL каждой зоны читает только свои таблицы, тест графа импортов остаётся строгим, проверка «вложение этого чата» атомарна с `INSERT` сообщения без чтения таблицы `attachments` из `messaging`. Чего стоит: два запроса (строка вложения + членство) вместо одного `JOIN` на метаданных и скачивании, лишний уникальный индекс `(id, chat_id)`. Отвергнуто: `JOIN chat_members` в SQL зоны `attachments` (нарушает границу), проекция членства через события в памяти (не переживает рестарт, расходится между репликами), `SELECT count(*) FROM attachments` из `messaging` (чтение чужой таблицы; внешний ключ даёт то же атомарно). + +### D2. Схема — миграция `0003_attachments.sql` + +```sql +ALTER TABLE messages DROP CONSTRAINT messages_text_check, + ADD CONSTRAINT messages_text_check CHECK (char_length(text) <= 4000); + +CREATE TABLE attachments ( + id uuid PRIMARY KEY, + chat_id uuid NOT NULL, + owner_id uuid NOT NULL, + filename text NOT NULL CHECK (char_length(filename) BETWEEN 1 AND 255), + content_type text NOT NULL CHECK (content_type IN ('image/png', 'image/jpeg')), + size_bytes bigint NOT NULL CHECK (size_bytes BETWEEN 1 AND 10485760), + sha256 text NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'), + width integer NOT NULL CHECK (width > 0), + height integer NOT NULL CHECK (height > 0), + object_key text COLLATE "C" NOT NULL UNIQUE, + status text NOT NULL CHECK (status IN ('pending', 'ready')), + created_at timestamptz NOT NULL, + updated_at timestamptz NOT NULL, + CONSTRAINT attachments_chat_key UNIQUE (id, chat_id), + CONSTRAINT attachments_owner_fkey FOREIGN KEY (chat_id, owner_id) REFERENCES chat_members (chat_id, user_id) +); +CREATE INDEX attachments_pending_idx ON attachments (created_at) WHERE status = 'pending'; + +CREATE TABLE message_attachments ( + message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE, + position smallint NOT NULL CHECK (position BETWEEN 0 AND 9), + chat_id uuid NOT NULL, + attachment_id uuid NOT NULL, + PRIMARY KEY (message_id, position), + UNIQUE (message_id, attachment_id), + CONSTRAINT message_attachments_attachment_fkey FOREIGN KEY (attachment_id, chat_id) + REFERENCES attachments (id, chat_id) ON DELETE RESTRICT +); +CREATE INDEX message_attachments_attachment_idx ON message_attachments (attachment_id); +``` + +Ни одного `bytea`. `object_key` с `COLLATE "C"` — байтовый порядок, как у листинга S3 (пригодится reconciler). Частичный индекс по `pending` обслуживает будущую очистку и не растёт вместе с готовыми вложениями. `UNIQUE (message_id, attachment_id)` запрещает дубль внутри сообщения; одно вложение в нескольких сообщениях допустимо. Индекс по `attachment_id` обслуживает проверку `RESTRICT`. `CHECK` текста ослаблен до `≤ 4000`: пустой текст с вложением легален, а пустой без вложений по-прежнему отсекает домен (`400`). Миграция аддитивна для кода лабы 3: старая версия не пишет пустой текст и не знает новых таблиц. + +Запросы и индексы: метаданные — `SELECT … FROM attachments WHERE id = $1 AND status = 'ready'` (PK); членство — `chat_members` по PK; история и повтор добавляют `ARRAY(SELECT attachment_id FROM message_attachments WHERE message_id = m.id ORDER BY position)` — коррелированный подзапрос по PK `(message_id, position)`, не больше 100 index scan на страницу, без N+1 запросов из приложения. + +### D3. Загрузка: порядок проверок и память + +Эндпоинт не объявляет тела: FastAPI его не читает, обработчик получает `request.stream()`. Команда `UploadAttachment` несёт поток, и все проверки идут в обработчике в порядке «дешёвое раньше»: + +1. `401` — guard конвейера (как в лабе 3); +2. объявленный `Content-Length` больше лимита маршрута → `413` в конвейере, тело не читается; +3. членство через порт → `404`; +4. `Filename` (1–255 code points, не пробельный, без `/`, `\`, категорий `Cc`) → `400`; +5. `Content-Type` (тип без параметров, регистр не важен) ∈ {`image/png`, `image/jpeg`} → иначе `415`; +6. чтение потока в `bytearray` со счётчиком и инкрементальным SHA-256: на байте `MAX_UPLOAD_BYTES + 1` → `413`, дальше не читаем; +7. проверка изображения (D4) → `415`/`413`; +8. запись (D5). + +Лимит тела в конвейере становится зависимым от маршрута: платформа получает пары «шаблон пути → лимит», а `main.py` передаёт шаблон upload из `attachments/entrypoints` и `MAX_UPLOAD_BYTES`; остальным маршрутам остаётся 1 MiB. Память одной загрузки — до 10 MiB буфера без копий: тот же буфер отдаётся и в проверку, и в `PutObject`. Диск не используется (`read_only`, `tmpfs` только для heartbeat). Сколько загрузок идёт одновременно, на уровне «3» не ограничено — лимит и замер на уровне «4». + +### D4. Проверка изображения — Pillow за портом `ImageInspector` + +Адаптер `PillowImageInspector` выполняет проверку в `asyncio.to_thread` под `asyncio.Semaphore(IMAGE_CHECK_CONCURRENCY)`, чтобы не блокировать event loop и не декодировать много файлов разом: + +- `Image.open(..., formats=("PNG", "JPEG"))` читает только заголовок; GIF, WebP, текст, пустое тело → `415`; +- формат по сигнатуре ≠ заявленный `Content-Type` → `415` (подмена MIME); +- `width * height > MAX_IMAGE_PIXELS` → `413` до любого декодирования; `DecompressionBombError`/`Warning` Pillow (выше его собственного порога) тоже → `413`; +- PNG: `verify()` — обход всех чанков с проверкой CRC и `IEND` без распаковки пикселей; JPEG: `draft("RGB", (w/8, h/8))` + `load()` — полное декодирование потока в масштабе 1/8 (≈1/64 памяти). Ошибка → `415`. `LOAD_TRUNCATED_IMAGES` остаётся `False`, обрезанный файл — ошибка. + +Что получаем: тип и целостность по содержимому, память проверки — килобайты для PNG и ≤2 MB для JPEG 40 MP. Чего стоит: `verify()` не распаковывает IDAT, поэтому PNG с правильными CRC, но испорченным zlib-потоком будет принят — оригинал отдаётся побайтно, вреда серверу нет, ограничение записано в отчёт. Отвергнуто: полное декодирование PNG (до 160 MB на 40 MP), `python-magic` (только сигнатура, без структуры). + +### D5. Порядок записи PostgreSQL ↔ S3 + +`UploadAttachmentHandler`: + +1. транзакция: `INSERT attachments (…, status='pending', object_key='attachments/')`, `COMMIT`; +2. `PutObject(Key=object_key, Body=буфер, ContentType)`; +3. транзакция: `UPDATE attachments SET status='ready', updated_at=$2 WHERE id=$1 AND status='pending'`, `COMMIT`; событие `AttachmentStored`; +4. `201 Attachment`. + +| Сбой | Что остаётся | Ответ клиенту | +| --- | --- | --- | +| до шага 1 (обрыв, `413`, `415`) | ничего | ошибка или обрыв | +| шаг 1 | ничего | `503` | +| шаг 2 | строка `pending` без объекта | `503` | +| шаг 3 | строка `pending` и объект | `503` | +| после шага 3 | готовое вложение | `201` (или обрыв уже после фиксации) | + +`pending` не видно ни в метаданных, ни в скачивании (`404`), а сообщение на него сослаться не может: id отдаётся клиенту только в `201`. Намерение до `PUT` гарантирует, что у любого объекта под `attachments/` есть строка с тем же ключом, — поэтому на уровне «4» правило «объект без строки старше grace — мусор» безопасно. Отвергнуто: `PUT` до `INSERT` (объект без строки неотличим от свежей загрузки), одна транзакция вокруг `PUT` (соединение PostgreSQL держится на время сети S3). + +### D6. Адаптер S3 — aiobotocore за портом `ObjectStorage` + +Порт: `put(key, data, content_type)`, `open(key) -> ObjectContent(size, chunks)`, `delete(key)`. Адаптер `S3ObjectStorage` держит один клиент aiobotocore на воркер (scope `APP` dishka, async-генератор закрывает клиент при остановке): `signature_version="s3v4"`, `addressing_style="path"` (RustFS без virtual host), регион из `S3_REGION`, `connect_timeout=1`, `read_timeout=2`, `retries={"mode": "standard", "max_attempts": 2}`, `request_checksum_calculation`/`response_checksum_validation="when_required"` (CRC и aws-chunked botocore ≥1.36 ломают часть S3-совместимых серверов). Худший случай операции — 2 × (1 + 2) = 6 с < `REQUEST_TIMEOUT_SECONDS=8` < `timeout server 10s` HAProxy. `NoSuchKey`/`404` → `ObjectMissing` порта; `BotoCoreError`, прочие `ClientError`, `OSError`, `TimeoutError` → `Unavailable` платформы → `503`. Ключи читаются из `*_FILE` настройками зоны и в журнал не попадают. + +LB не повторяет upload: в лабе 3 `disable-l7-retry` снят только для `GET` и `POST …/messages` с ключом; повтор `PutObject` клиентом botocore безопасен, ключ тот же. + +### D7. Метаданные и скачивание + +`GetAttachment`: строка `ready` по PK → членство → `Attachment`, иначе `404`. `OpenAttachment`: то же + `storage.open(key)` **до** отправки заголовков, поэтому `404` (объект пропал, событие `attachment.object_missing` в журнал) и `503` (S3 недоступен) ещё возможны; затем `StreamingResponse` по кускам 64 KiB с `Content-Type` из метаданных, `Content-Length` из S3, `X-Content-Type-Options: nosniff`, `Cache-Control: private, no-store`. `Accept` не учитывается, redirect нет. `X-Request-Id` и `X-Instance-Id` ставит конвейер на `http.response.start`, значит и на поток. `variant` — `Literal["original"]`, иное → `400`. + +### D8. `attachment_ids` в `messaging` + +- `CreateMessageRequest.attachment_ids: list[UUID] = []` — без `max_length` на границе, чтобы членство (`404`) проверялось раньше содержимого; отпечаток `model_dump_json` включает `attachment_ids`, поэтому отсутствующий и `[]` дают один отпечаток, а порядок значим. +- `Chat.post(..., attachment_ids)`: членство → `404`; больше 10 или повторы → `InvalidAttachmentList` (`400`); `MessageText` разрешает пустую строку, но не пробельную; пустой текст без вложений → `400`. `Message.attachment_ids: tuple[UUID, ...]`. +- `APPEND_MESSAGE` добавляет в тот же оператор `INSERT INTO message_attachments SELECT … FROM unnest($8::uuid[]) WITH ORDINALITY`; внешний ключ проверяется в конце оператора, нарушение откатывает и сообщение, и ключ идемпотентности. `RECEIPT` и история читают `attachment_ids` подзапросом по PK. + +### D9. Стенд + +- `s3`: `rustfs/rustfs:1.0.4@sha256:ed9210d6…`, uid 10001, `read_only` + `tmpfs /tmp`, `cap_drop: ALL`, `RUSTFS_CONSOLE_ENABLE=false`, логи в stdout, root-ключи из `*_FILE`, volume `s3data:/data`, healthcheck `/health/ready`, 1 CPU / 512M, сеть `backend` (internal), портов нет. +- `s3-init`: `rustfs/rc:v0.1.36@sha256:ab024bfe…`, `infra/s3/init.sh` — `bucket create --ignore-existing`, `anonymous set private`, политика `messenger-api` из `infra/s3/api-policy.json` (Get/Put/DeleteObject, multipart abort/list, ListBucket, GetBucketLocation на один bucket), пользователь API, lifecycle «abort incomplete multipart за 1 день», самопроверка. `s3-cli` — тот же образ под профилем `tools`, aliases `root`, `api`, `anon`. +- `api`: якорь `x-s3-env` подмешивается в `environment` (ключ сервиса заменяет ключ якоря целиком, поэтому не через `x-app`), секреты `s3_access_key_id`, `s3_secret_access_key`, `depends_on: s3-init: service_completed_successfully`. +- `scripts/secrets.sh` создаёт hex-секреты S3 (без `:`/`@`, они идут в URL `RC_HOST_*`); `scripts/restart.sh` перезапускает и `s3`, `up --wait` ждёт его `healthy`, поэтому однократное чтение вложения после хука проходит. +- Готовность: `/health/ready` от S3 **не** зависит. Иначе при падении S3 LB вывел бы все реплики и отказали бы даже тексты, а ответы LB не несут `X-Instance-Id`. Upload и скачивание при этом получают `503` от приложения. + +### D10. Сценарии и доказательства + +`scripts/lab4_scenarios.py` (stdlib, Python 3.9, импортирует `tests/client.py` для проверки схем и заголовков): `failover-upload` — upload, `stop-one.sh` по `X-Instance-Id` ответа upload, скачивание через другую реплику и сравнение SHA-256, `--restore`; `s3-outage` — `docker compose stop s3`, коды и время upload/скачивания/метаданных/текста/готовности, возврат S3 и повторное скачивание. `scripts/s3-check.sh` — анонимный доступ, порты, консоль, двойной `s3-init`, права ключа API. `scripts/evidence-attachments.sh` — `\d attachments`, листинг bucket, `ReadonlyRootfs` и mounts реплик, сверка байтов вне API. Цели Makefile: `scenario`, `s3-check`, `attachments-evidence`. + +## Risks / Trade-offs + +- [Строки `pending` после сбоя S3 или `COMMIT` остаются до уровня «4»] → они невидимы клиенту и не мешают ссылкам; компенсация и очистка с grace — следующее изменение. +- [Ранний `413`/`404` до конца тела: клиент, ещё отправляющий 10 MiB, может получить reset] → собственные тесты проверяют `413` через `Content-Length`; поведение описано в отчёте. +- [`verify()` PNG не распаковывает пиксели] → принято осознанно (D4), записано в ограничениях. +- [RustFS молод (GA 2026-09), одиночный узел без parity — SPOF] → версия и digest закреплены, данные на volume, ограничение в отчёте. +- [Одновременные загрузки без лимита держат по 10 MiB каждая] → `API_MEMORY=512m`; лимит параллелизма и замер — уровень «4». + +## Migration Plan + +`make up` на существующем стенде лабы 3: `migrate` применяет `0003` под advisory lock, `s3-init` создаёт bucket, реплики стартуют после обоих. Откат: предыдущий образ работает с новой схемой (новые таблицы ему не нужны, ослабленный `CHECK` его не задевает); `make reset-data` удаляет и `s3data`. diff --git a/openspec/changes/add-lab4-image-attachments/proposal.md b/openspec/changes/add-lab4-image-attachments/proposal.md new file mode 100644 index 00000000..661da02c --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/proposal.md @@ -0,0 +1,36 @@ +## Why + +Решение лабы 3 хранит только текст. Рубрика «3» `README.md` лабы 4 требует вложения-изображения: S3-сервер в общем стенде, метаданные в PostgreSQL, байты в приватном bucket, `201 ready` только после сохранения, побайтное скачивание участником, `404` постороннему, лимиты 10 MiB / 40 млн пикселей и тип по содержимому, переживание остановки обслужившей реплики, рестарта стенда и недоступности S3. Контракт 1.4.0 добавляет три операции и обязательное `Message.attachment_ids`. Изменение закрывает уровень «3» и строки 3.1–3.9 `REPORT.md`. + +## What Changes + +- Новая доменная зона `attachments`: `POST /api/v1/chats/{chat_id}/attachments?filename=…` (сырые байты PNG/JPEG, `201 Attachment` со `status=ready`), `GET /api/v1/attachments/{id}`, `GET /api/v1/attachments/{id}/content?variant=original` (байты через API, без redirect). Доступ — только участникам чата, иначе `404`. +- Лимиты до неограниченного чтения и декодирования: `Content-Length` и потоковый счётчик (`413`), размер по заголовку изображения (`413`), сигнатура и проверка файла (`415`), `filename` (`400`). Object key `attachments/` назначает сервер. +- Порядок записи: строка-намерение `pending` → `PutObject` → `ready` и `COMMIT` → `201`. Недоступный S3 — `503` за ограниченное время; тексты продолжают работать, `/health/ready` от S3 не зависит. +- Зона `messaging`: `attachment_ids` (0–10 уникальных, только вложения этого чата, иначе `400`/`404`) в отправке, ответе, повторе и истории; `text=""` допустим только с вложением; отсутствующий `attachment_ids` и `[]` — одно тело для `Idempotency-Key`. +- Миграция `0003_attachments.sql`: таблицы `attachments` и `message_attachments`, ослабление `messages_text_check` до `≤ 4000`. +- Стенд: RustFS 1.0.4 (`s3`, volume `s3data`, без портов, консоль выключена), одноразовый `s3-init` (`rc`: bucket, anonymous `private`, пользователь API с политикой на один bucket), `s3-cli` под профилем `tools`; S3-переменные и ключи API у `api`; `restart.sh` перезапускает и S3. +- Сценарии `scripts/lab4_scenarios.py` (`failover-upload`, `s3-outage`), `scripts/s3-check.sh`, цели Makefile, сбор доказательств. + +## Capabilities + +### New Capabilities +- `lab4-attachments`: upload, лимиты и проверка содержимого, метаданные, скачивание оригинала, доступ участников, порядок записи PostgreSQL ↔ S3, поведение при недоступном S3. +- `lab4-object-storage`: S3-сервер в стенде, приватный bucket и его bootstrap, раздельные ключи root и API, байты не в БД и не на диске реплики, переживание остановки реплики и рестарта. + +### Modified Capabilities +- `lab1-messenger-history`: «Отправка сообщения» — `attachment_ids` и пустой текст с вложением; «Чтение истории keyset-курсором» — элементы несут `attachment_ids`. +- `lab3-idempotent-messages`: «Повтор возвращает исходный результат» — `attachment_ids` входит в тело, отсутствующий равен `[]`. +- `lab3-load-balancing`: «Рестарт стенда» — хук перезапускает и S3, ждёт его готовности. +- `lab2-persistent-storage`: «Данные и сессии переживают рестарт» — вложения и их байты; «Воспроизводимый стенд» — S3 без портов, root-ключи только у S3-сервисов. + +## Impact + +- Код: новая зона `attachments`, зона `messaging`, платформа (лимит тела по маршруту), `main.py` (порт членства), миграция `0003`; зависимости aiobotocore и Pillow. +- Стенд: `compose.yaml`, `infra/s3/`, `scripts/`, `Makefile`, `.env.example`, CI. +- Тесты: upload и лимиты, подмена MIME, `filename`, доступ, `attachment_ids`, идемпотентность, адаптер S3 против RustFS. +- Отчёт: строки 3.1–3.9 в `REPORT.md`, `evidence/`. + +## Non-goals + +Компенсация сбоя между S3 и БД, очистка `pending`, замер памяти под ≥10 загрузками, доказательство ограниченных ключей — уровень «4»; reconciler — трек 2; оба — следующие изменения. Из Out of scope не появляется ничего: `202 queued`, worker и варианты (лаба 5), presigned upload (трек 1), удаление вложений, TLS (лаба 7). diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab1-messenger-history/spec.md b/openspec/changes/add-lab4-image-attachments/specs/lab1-messenger-history/spec.md new file mode 100644 index 00000000..c74b2085 --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/specs/lab1-messenger-history/spec.md @@ -0,0 +1,108 @@ +## MODIFIED Requirements + +### Requirement: Отправка сообщения + +Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":..., "attachment_ids":[...]}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL быть обязательным, содержать не более 4000 Unicode code points и SHALL NOT состоять только из пробельных символов; пустая строка допустима только при хотя бы одном вложении. `attachment_ids` SHALL быть необязательным списком из 0–10 уникальных UUID (по умолчанию `[]`); каждое вложение SHALL принадлежать этому чату и быть готовым, иначе ответ `404`. Порядок `attachment_ids` SHALL сохраняться, а одно вложение SHALL допускаться в нескольких сообщениях. Каждый `Message` в ответе SHALL содержать `attachment_ids`, у текстового — `[]`. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`. + +#### Scenario: Сообщение отправлено + +- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат с новым `Idempotency-Key` +- **THEN** ответ `201`, тело соответствует схеме `Message`, `attachment_ids` равен `[]` +- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным + +#### Scenario: Сообщение с вложением без текста + +- **WHEN** участник отправляет `{"text":"","attachment_ids":[id]}`, где `id` — готовое вложение этого чата +- **THEN** ответ `201`, `attachment_ids` равен `[id]` + +#### Scenario: Порядок вложений сохраняется + +- **WHEN** участник отправляет три вложения чата в порядке `[c, a, b]` +- **THEN** ответ и история содержат `attachment_ids` в том же порядке `[c, a, b]` + +#### Scenario: Вложение другого чата или неизвестное + +- **WHEN** `attachment_ids` содержит вложение другого чата того же пользователя или несуществующий UUID +- **THEN** ответ `404` с кодом `not_found`, сообщение не сохраняется + +#### Scenario: Слишком много, повторы или не UUID + +- **WHEN** `attachment_ids` содержит 11 элементов, повторяющийся UUID или строку не в формате UUID +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Ключ не передан + +- **WHEN** участник отправляет корректное тело без заголовка `Idempotency-Key` +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Отправитель не берётся из тела запроса + +- **WHEN** тело запроса содержит поле `sender_id` +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Пустой или пробельный текст + +- **WHEN** тело содержит `{"text":""}`, `{"text":"","attachment_ids":[]}` или `{"text":" "}` с вложениями или без +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Текст длиннее предела + +- **WHEN** `text` содержит более 4000 Unicode code points +- **THEN** ответ `400` с кодом `invalid_request` +- **AND** длина считается в code points, а не в байтах UTF-8 + +#### Scenario: Посторонний пишет в чужой чат + +- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение с ключом +- **THEN** ответ `404` с кодом `not_found` +- **AND** сообщение не сохраняется + +#### Scenario: Доступ проверяется раньше содержимого + +- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text` или с 11 вложениями +- **THEN** ответ `404`, а не `400` + +### Requirement: Чтение истории keyset-курсором + +Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Каждый элемент SHALL содержать `attachment_ids` в порядке отправки. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами. + +#### Scenario: Первая страница отдаёт курсор + +- **WHEN** в чате два сообщения и запрошено `?limit=1` +- **THEN** ответ содержит один элемент и непустой `next_cursor` + +#### Scenario: Последняя страница закрывает историю + +- **WHEN** запрошена вторая страница с курсором предыдущей и `limit=1` +- **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null` +- **AND** элемент первой страницы не повторяется + +#### Scenario: Элементы истории несут вложения + +- **WHEN** в чате есть текстовое сообщение и сообщение с вложением +- **THEN** у текстового элемента `attachment_ids` равен `[]`, у второго — список его вложений, и оба элемента совпадают с ответами `201` + +#### Scenario: Курсор не привязан к читателю + +- **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата +- **THEN** страница отдаётся на общих основаниях + +#### Scenario: Курсор от другого чата + +- **WHEN** курсор, выданный для одного чата, предъявлен при чтении другого чата +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Испорченный или подделанный курсор + +- **WHEN** значение `cursor` не является ранее выданным сервером курсором +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Limit вне допустимого диапазона + +- **WHEN** запрос содержит `limit=0` или `limit=101` +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Посторонний читает чужую историю + +- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю +- **THEN** ответ `404` с кодом `not_found` diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab2-persistent-storage/spec.md b/openspec/changes/add-lab4-image-attachments/specs/lab2-persistent-storage/spec.md new file mode 100644 index 00000000..a8048f20 --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/specs/lab2-persistent-storage/spec.md @@ -0,0 +1,34 @@ +## MODIFIED Requirements + +### Requirement: Данные и сессии переживают рестарт + +Пользователи, чаты, участники, сообщения со ссылками на вложения, ключи идемпотентности, метаданные вложений, их байты в bucket и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ, включая S3, с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, подтверждённое сообщение SHALL читаться побайтно тем же, а загруженное вложение SHALL отдавать те же метаданные и те же байты. + +#### Scenario: Полный рестарт стенда + +- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh` +- **THEN** hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`, в том числе после однократного чтения метаданных и байтов вложения + +#### Scenario: Логаут после рестарта + +- **WHEN** после рестарта пользователь отзывает прежний токен +- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401` + +### Requirement: Воспроизводимый стенд из репозитория + +Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников, bucket и доступ к нему создаёт одноразовый bootstrap. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey, S3 и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны (root-ключи S3 — только S3-сервисам), и SHALL NOT появляться в Git, образе и журнале. + +#### Scenario: Подъём из чистого clone + +- **WHEN** в чистом clone выполняются `make secrets` и `make up` +- **THEN** все сервисы становятся `healthy` или завершаются кодом 0 (`migrate`, `s3-init`), а `GET /health/ready` через балансировщик отвечает `200` + +#### Scenario: Опубликован только балансировщик + +- **WHEN** выполняется `docker compose ps --format '{{.Service}} {{.Ports}}'` +- **THEN** опубликованные порты есть только у сервиса `lb` и все они привязаны к `127.0.0.1` + +#### Scenario: Секреты и volumes вне Git + +- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url secrets/s3_root_password .env` +- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab3-idempotent-messages/spec.md b/openspec/changes/add-lab4-image-attachments/specs/lab3-idempotent-messages/spec.md new file mode 100644 index 00000000..feb29d5d --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/specs/lab3-idempotent-messages/spec.md @@ -0,0 +1,40 @@ +## MODIFIED Requirements + +### Requirement: Повтор возвращает исходный результат + +Область ключа SHALL составлять пользователь сессии, метод и путь чата и сам ключ. Тело запроса для сравнения SHALL включать `text` и `attachment_ids` с учётом порядка вложений; отсутствующий `attachment_ids` SHALL считаться равным `[]`, порядок полей JSON SHALL NOT иметь значения. Повтор с тем же ключом и семантически тем же JSON в течение `IDEMPOTENCY_TTL_SECONDS` (не меньше 86 400 с) SHALL возвращать `201` и тот же объект `Message` — те же `id`, `text`, `attachment_ids` и строку `created_at` — без создания нового сообщения. Тот же ключ с другим JSON SHALL давать `409` с кодом `conflict`. Одинаковый ключ у разных пользователей или в разных чатах SHALL действовать независимо. После истечения срока ключ SHALL приниматься как новый. + +#### Scenario: Повтор того же тела + +- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":...}` +- **THEN** ответ `201`, тело равно телу первого ответа целиком, включая `attachment_ids: []`, в истории одно такое сообщение + +#### Scenario: Отсутствующий attachment_ids равен пустому списку + +- **WHEN** первый `POST` содержит `{"text":"x"}`, а повтор с тем же ключом — `{"attachment_ids":[],"text":"x"}` +- **THEN** повтор получает `201` с телом первого ответа + +#### Scenario: Повтор сообщения с вложением + +- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":"","attachment_ids":[id]}` +- **THEN** ответ `201` с тем же `Message` и `attachment_ids` равным `[id]` + +#### Scenario: Тот же ключ, другое тело + +- **WHEN** участник повторяет `POST` с тем же ключом, но другим `text` или другим списком либо порядком `attachment_ids` +- **THEN** ответ `409` с кодом `conflict`, новое сообщение не создаётся + +#### Scenario: Тот же ключ у другого пользователя + +- **WHEN** другой участник того же чата отправляет сообщение с тем же значением ключа +- **THEN** ответ `201` с новым сообщением этого участника + +#### Scenario: Тот же ключ в другом чате + +- **WHEN** участник отправляет в другой свой чат сообщение с уже использованным ключом +- **THEN** ответ `201` с новым сообщением в этом чате + +#### Scenario: Срок ключа истёк + +- **WHEN** с момента первой отправки прошло больше `IDEMPOTENCY_TTL_SECONDS` и участник отправляет с тем же ключом другой текст +- **THEN** ответ `201` с новым сообщением, а не `409` diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab3-load-balancing/spec.md b/openspec/changes/add-lab4-image-attachments/specs/lab3-load-balancing/spec.md new file mode 100644 index 00000000..3a565e39 --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/specs/lab3-load-balancing/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Рестарт стенда + +Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL, Valkey и S3-сервер с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд, включая S3, снова готов: первое же чтение метаданных и байтов вложения после хука SHALL проходить без повторов. + +#### Scenario: Полный рестарт сохраняет сессию + +- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh` +- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres`, `valkey` и `s3` после прогона позже, чем до него diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab4-attachments/spec.md b/openspec/changes/add-lab4-image-attachments/specs/lab4-attachments/spec.md new file mode 100644 index 00000000..63fb5dc7 --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/specs/lab4-attachments/spec.md @@ -0,0 +1,153 @@ +## Purpose + +Определяет вложения-изображения чата: синхронную загрузку оригинала PNG/JPEG с лимитами и проверкой содержимого, метаданные, скачивание оригинала через API, доступ только участникам чата, порядок записи PostgreSQL ↔ S3 и поведение при недоступном S3. + +## ADDED Requirements + +### Requirement: Загрузка оригинала в чат + +Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` от участника чата с телом из сырых байтов одного изображения (не multipart, не JSON) и заголовком `Content-Type: image/png` или `image/jpeg` и возвращать `201` с объектом `Attachment`: `status` `ready`, `variants` `[]`, `error_code` `null`, `chat_id` из пути, `owner_id` вызывающего, `size_bytes` равен длине тела, `sha256` — lowercase hex SHA-256 тела, `content_type` — тип, определённый по содержимому, `filename` — переданное имя. Ответ `201` SHALL выдаваться только после того, как оригинал записан в приватный bucket и метаданные зафиксированы в PostgreSQL. Ключ объекта SHALL назначаться сервером и SHALL NOT зависеть от `filename` и попадать в ответ. Повтор того же запроса SHALL создавать новое вложение. + +#### Scenario: Fixture загружена + +- **WHEN** участник загружает `tests/fixtures/sample.png` с `Content-Type: image/png` и `?filename=sample.png` +- **THEN** ответ `201`, тело соответствует схеме `Attachment`, `status` `ready`, `size_bytes` 111817, `sha256` равен SHA-256 файла, `chat_id` и `owner_id` — чат и загрузивший + +#### Scenario: JPEG загружен + +- **WHEN** участник загружает корректный JPEG с `Content-Type: image/jpeg` +- **THEN** ответ `201`, `content_type` `image/jpeg` + +#### Scenario: Посторонний загружает в чужой чат + +- **WHEN** пользователь, не входящий в чат, или любой пользователь в несуществующий чат отправляет корректное изображение +- **THEN** ответ `404` с кодом `not_found`, ничего не сохраняется + +#### Scenario: Доступ проверяется раньше содержимого + +- **WHEN** посторонний отправляет в чужой чат тело, не являющееся изображением, или опасный `filename` +- **THEN** ответ `404`, а не `400` или `415` + +#### Scenario: Без аутентификации + +- **WHEN** upload приходит без `Authorization` или с `Basic` +- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"` + +### Requirement: Лимиты размера до неограниченного чтения и декодирования + +Тело SHALL быть не больше `MAX_UPLOAD_BYTES` (10 485 760) байт, а изображение — не больше `MAX_IMAGE_PIXELS` (40 000 000) пикселей по заголовку. Превышение SHALL давать `413` с кодом `payload_too_large`. Объявленный `Content-Length` больше лимита SHALL отклоняться без чтения тела, тело без `Content-Length` SHALL читаться не дальше лимита плюс один байт, а число пикселей SHALL проверяться по заголовку изображения до декодирования. Реплика SHALL NOT записывать тело на свой диск. + +#### Scenario: Ровно 10 MiB + +- **WHEN** загружается корректный PNG размером ровно 10 485 760 байт +- **THEN** ответ `201` и `size_bytes` 10485760 + +#### Scenario: На байт больше с Content-Length + +- **WHEN** загружается тело размером 10 485 761 байт с заголовком `Content-Length` +- **THEN** ответ `413` с кодом `payload_too_large` + +#### Scenario: На байт больше без Content-Length + +- **WHEN** тело размером 10 485 761 байт передаётся chunked, без `Content-Length` +- **THEN** ответ `413` с кодом `payload_too_large`, вложение не создаётся + +#### Scenario: Ровно 40 млн пикселей + +- **WHEN** загружается корректный PNG 8000×5000 +- **THEN** ответ `201` + +#### Scenario: Больше 40 млн пикселей + +- **WHEN** загружается PNG 8001×5000 или сжатый PNG огромных размеров весом несколько килобайт +- **THEN** ответ `413` с кодом `payload_too_large`, изображение не декодируется + +### Requirement: Тип определяется по содержимому + +Сервис SHALL принимать только `Content-Type` `image/png` и `image/jpeg` (параметры заголовка и регистр не важны) и SHALL проверять, что сигнатура и структура файла соответствуют заявленному типу, а файл читается без ошибок. Иной или отсутствующий `Content-Type`, несовпадение заявленного типа и содержимого, пустое тело, обрезанный или повреждённый файл, GIF, WebP и текст SHALL давать `415` с кодом `unsupported_media_type`. + +#### Scenario: Подмена MIME + +- **WHEN** JPEG, GIF или текст отправлены с `Content-Type: image/png` +- **THEN** ответ `415` с кодом `unsupported_media_type` + +#### Scenario: Обрезанное изображение + +- **WHEN** отправлена первая половина корректного PNG или JPEG с верным `Content-Type` +- **THEN** ответ `415` + +#### Scenario: Неподдерживаемый Content-Type + +- **WHEN** корректный PNG отправлен с `Content-Type: application/octet-stream` или без `Content-Type` +- **THEN** ответ `415` + +### Requirement: Безопасное отображаемое имя + +`filename` SHALL быть обязательным параметром длиной 1–255 Unicode code points после percent-декодирования, SHALL NOT состоять только из пробельных символов и SHALL NOT содержать `/`, `\`, NUL и другие управляющие символы. Нарушение SHALL давать `400` с кодом `invalid_request`. Имя SHALL использоваться только для отображения и возвращаться без изменений. + +#### Scenario: Опасное имя + +- **WHEN** `filename` равен `../a.png`, `a/b.png`, `a\b.png`, содержит `%00`, `%01` или `%7F` +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Пустое, пробельное, длинное или отсутствующее имя + +- **WHEN** `filename` пустой, из пробелов, длиной 256 code points или не передан +- **THEN** ответ `400` + +#### Scenario: Имя на кириллице + +- **WHEN** `filename` равен `фото 1.png` длиной до 255 code points +- **THEN** ответ `201` и `filename` в ответе совпадает с переданным + +### Requirement: Метаданные и скачивание только участникам + +`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с исходными байтами, `Content-Type` вложения и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`. Параметр `variant` SHALL принимать только `original` (по умолчанию). Посторонний, неизвестный id и ещё не готовое вложение SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и неизвестный `variant` — `400`. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`. + +#### Scenario: Второй участник скачивает оригинал + +- **WHEN** второй участник чата запрашивает `/content` загруженного вложения с `Accept: application/json` +- **THEN** ответ `200`, `Content-Type: image/png`, байты совпадают с загруженными, SHA-256 равен `sha256` метаданных + +#### Scenario: Посторонний + +- **WHEN** пользователь вне чата запрашивает метаданные или `/content` +- **THEN** оба ответа `404` с кодом `not_found` + +#### Scenario: Неизвестный вариант + +- **WHEN** запрошен `/content?variant=thumbnail` +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Объект пропал из хранилища + +- **WHEN** метаданные готового вложения есть, а объекта в bucket нет +- **THEN** `/content` отвечает `404`, событие пишется в журнал без ключа объекта + +### Requirement: Порядок записи PostgreSQL и S3 + +Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. + +#### Scenario: S3 отказал при записи + +- **WHEN** запись объекта завершилась ошибкой +- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях + +#### Scenario: Клиент оборвал загрузку + +- **WHEN** клиент закрыл соединение, отправив часть тела +- **THEN** в bucket нет нового объекта и в PostgreSQL нет новой строки вложения + +### Requirement: Недоступный S3 + +Недоступность S3 SHALL превращаться в `503 unavailable` в общем формате ошибки за ограниченное время (меньше `REQUEST_TIMEOUT_SECONDS`) для upload и скачивания. Метаданные, тексты сообщений и `GET /health/ready` SHALL продолжать работать: готовность реплики от S3 не зависит. После возврата S3 ранее загруженные файлы SHALL скачиваться без изменений. + +#### Scenario: S3 остановлен + +- **WHEN** выполняется `docker compose stop s3` и клиент загружает и скачивает файл, отправляет текст и проверяет готовность +- **THEN** upload и `/content` отвечают `503` с `X-Request-Id` и `X-Instance-Id` быстрее `REQUEST_TIMEOUT_SECONDS`, текстовое сообщение — `201`, метаданные и `/health/ready` — `200` + +#### Scenario: S3 вернулся + +- **WHEN** S3 снова запущен +- **THEN** ранее загруженный файл скачивается с тем же SHA-256 diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab4-object-storage/spec.md b/openspec/changes/add-lab4-image-attachments/specs/lab4-object-storage/spec.md new file mode 100644 index 00000000..71f6266e --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/specs/lab4-object-storage/spec.md @@ -0,0 +1,47 @@ +## Purpose + +Определяет объектное хранилище вложений как часть стенда: S3-совместимый сервер с закреплённой версией и persistent volume, приватный bucket и воспроизводимый bootstrap, раздельные ключи администратора и API, а также то, что байты не живут в БД и на диске реплики и переживают остановку реплики и рестарт стенда. + +## ADDED Requirements + +### Requirement: S3-сервер и приватный bucket в стенде + +Стенд SHALL включать S3-совместимый сервер с образом, закреплённым версией и digest, данными на именованном volume и healthcheck, без опубликованных на хост портов и без доступной административной консоли. Одноразовый bootstrap SHALL создавать bucket `S3_BUCKET` (по умолчанию `messenger-attachments`), делать его приватным для анонимного клиента, создавать пользователя API с политикой только на объекты и листинг этого bucket и завершаться кодом 0; повторный запуск SHALL проходить без ошибок и без изменения состояния. Реплики API SHALL стартовать после успешного bootstrap. + +#### Scenario: Анонимный GET объекта + +- **WHEN** из отдельного контейнера в сети стенда выполняется HTTP GET существующего объекта bucket без подписи +- **THEN** ответ `403`, байты объекта не возвращаются + +#### Scenario: Порты и консоль + +- **WHEN** выполняется `docker compose ps` и запрос к порту консоли внутри контейнера S3 +- **THEN** у сервиса S3 нет опубликованных портов, а консоль не отвечает + +#### Scenario: Повторный bootstrap + +- **WHEN** bootstrap запускается ещё два раза на работающем стенде +- **THEN** оба запуска завершаются кодом 0, а bucket, его анонимная политика, пользователь и политика API не меняются + +### Requirement: Раздельные ключи и места хранения + +Root-ключи S3 SHALL передаваться файлами compose secrets только S3-серверу, bootstrap и операторскому CLI; реплики API SHALL получать отдельный ключ из `S3_ACCESS_KEY_ID_FILE` и `S3_SECRET_ACCESS_KEY_FILE`. Байты вложений SHALL храниться только в bucket: в PostgreSQL SHALL NOT быть столбцов с содержимым файла, у реплик API SHALL NOT быть volume, а корневая файловая система реплики SHALL быть только для чтения. Ключи и адреса хранилища SHALL NOT попадать в ответы API, журнал и Git. + +#### Scenario: Где лежат байты + +- **WHEN** после загрузки выполняются `\d attachments`, листинг bucket и `docker inspect` реплики API +- **THEN** в таблице нет `bytea`, объект лежит в bucket под ключом `attachments/`, у реплики `ReadonlyRootfs=true` и нет volume + +#### Scenario: Ключ API + +- **WHEN** проверяются секреты сервиса `api` в `docker compose config` +- **THEN** у `api` есть только ключ API S3, а root-ключей нет + +### Requirement: Файл переживает остановку обслужившей реплики + +Вложение, загруженное через одну реплику API, SHALL скачиваться через другую реплику после остановки первой с тем же SHA-256. + +#### Scenario: Upload, остановка реплики, download + +- **WHEN** выполняется `python3 scripts/lab4_scenarios.py failover-upload`: upload, остановка реплики из `X-Instance-Id` ответа хуком `scripts/stop-one.sh`, скачивание +- **THEN** скачивание обслуживает другая реплика, SHA-256 совпадает, сценарий печатает `"ok": true` diff --git a/openspec/changes/add-lab4-image-attachments/tasks.md b/openspec/changes/add-lab4-image-attachments/tasks.md new file mode 100644 index 00000000..88d0d938 --- /dev/null +++ b/openspec/changes/add-lab4-image-attachments/tasks.md @@ -0,0 +1,56 @@ +## 1. Схема + +- [ ] 1.1 Миграция `0003_attachments.sql`: `attachments` (статус `pending`/`ready`, `object_key COLLATE "C"`, `UNIQUE (id, chat_id)`, FK на `chat_members`, частичный индекс `pending`), `message_attachments` (FK на `attachments (id, chat_id)` `ON DELETE RESTRICT`, индекс по `attachment_id`), ослабленный `messages_text_check` +- [ ] 1.2 Проверка группы: тест миграций — версия `0003`, повтор без изменений, вложение не участника и ссылка на вложение другого чата отклоняются внешними ключами, пустой текст принимается схемой + +## 2. Зона `attachments`: домен и приложение + +- [ ] 2.1 Домен: `Filename`, `ImageKind`, `ImageInfo`, агрегат `Attachment` (`stage` → `pending`, `store` → `ready` с событием `AttachmentStored`), ошибки зоны +- [ ] 2.2 Порты: `ChatMembership`, `ObjectStorage` (`put`/`open`/`delete`, `ObjectContent`, `ObjectMissing`), `ImageInspector`, `AttachmentsUnitOfWork`, `AttachmentDirectory` +- [ ] 2.3 Команда `UploadAttachment` и обработчик: членство → имя → `Content-Type` → поток со счётчиком и SHA-256 → проверка изображения → `pending` → `put` → `ready`; запросы `GetAttachment`, `OpenAttachment` +- [ ] 2.4 Проверка группы: unit-тесты `Filename` (граничные и опасные имена), агрегата и порядка записи обработчика с фейковыми портами (сбой `put` даёт `503` и не делает вложение готовым) + +## 3. Зона `attachments`: инфраструктура и HTTP + +- [ ] 3.1 Адаптер PostgreSQL: `add`, `save`, `get` готового; нарушение FK членства → `404` +- [ ] 3.2 Адаптер `PillowImageInspector`: открытие только PNG/JPEG, подмена MIME, пиксели по заголовку, PNG `verify`, JPEG `draft` + `load`, `to_thread` под семафором +- [ ] 3.3 Адаптер `S3ObjectStorage` на aiobotocore (path-style, SigV4, таймауты, checksum `when_required`), отображение ошибок в `ObjectMissing`/`Unavailable`; зависимости aiobotocore и Pillow в `uv.lock` +- [ ] 3.4 Настройки зоны (`S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, таймауты, параллелизм проверки), провайдер dishka, схемы `AttachmentOut`, роутер upload/метаданных/скачивания, реестр ошибок, журнал +- [ ] 3.5 Проверка группы: тест адаптера S3 против одноразового RustFS (put/open/delete, пропавший объект, недоступный endpoint → `Unavailable` за ограниченное время) + +## 4. Связь зон и платформа + +- [ ] 4.1 Платформа: лимит тела по шаблону маршрута в конвейере +- [ ] 4.2 `main.py`: зона `attachments`, адаптер `MessagingMembership` для порта `ChatMembership`, лимит upload, поля журнала, реестр ошибок; `create_app` принимает дополнительные провайдеры для тестов +- [ ] 4.3 Проверка группы: тест графа импортов — `attachments` не импортирует `identity`/`messaging`, `messaging` не импортирует `attachments`, `shared` не знает зон + +## 5. Зона `messaging`: `attachment_ids` + +- [ ] 5.1 Домен: `Message.attachment_ids`, `Chat.post` с проверкой списка вложений, `MessageText` с пустой строкой, ошибки `InvalidAttachmentList` и `UnknownAttachment` +- [ ] 5.2 HTTP и команда: `CreateMessageRequest.attachment_ids` (по умолчанию `[]`, отпечаток), `MessageOut.attachment_ids` +- [ ] 5.3 PostgreSQL: запись `message_attachments` в операторе отправки, FK → `404`, `attachment_ids` в повторе и истории подзапросом +- [ ] 5.4 Проверка группы: тесты — пустой текст с вложением, порядок, другой чат и неизвестный id `404`, 11 и повторы `400`, посторонний `404` раньше `400`, повтор с вложением, отсутствующий ≡ `[]`, другой порядок `409`, история с `attachment_ids` + +## 6. API-тесты вложений + +- [ ] 6.1 Генераторы тестовых PNG (произвольный размер в пикселях и байтах) и JPEG, фейковое `ObjectStorage` в `student-tests` +- [ ] 6.2 Тесты: fixture `201` и побайтное скачивание вторым участником, посторонний `404` на метаданных и `/content`, ровно 10 MiB `201`, +1 байт `413` с `Content-Length` и chunked, 40 MP `201` и 40 MP+ `413`, подмена MIME, обрезанные PNG/JPEG, иной и пустой `Content-Type` `415`, опасные и пустые `filename` `400`, `variant=thumbnail` `400`, сбой хранилища `503` без готового вложения, пропавший объект `404`, заголовки на бинарном ответе + +## 7. Стенд + +- [ ] 7.1 `infra/s3/` (`init.sh`, `cli.sh`, `api-policy.json`, `lifecycle.json`) из заготовки +- [ ] 7.2 `compose.yaml`: `s3`, `s3-init`, `s3-cli`, volume `s3data`, секреты S3, якорь `x-s3-env` у `api`, зависимость от `s3-init`; `.env.example` (таймауты S3, параллелизм проверки) +- [ ] 7.3 `scripts/secrets.sh` (секреты S3), `scripts/restart.sh` (S3 в списке хранилищ), `scripts/evidence-stack.sh` (пакеты и образы лабы 4) +- [ ] 7.4 Проверка группы: `docker compose config --quiet`, у `api` только ключ API S3, `make up` из чистого состояния, все сервисы `healthy`, `s3-init` завершился кодом 0, опубликованы только порты `lb` + +## 8. Сценарии отказов и обвязка + +- [ ] 8.1 `scripts/lab4_scenarios.py` (`failover-upload`, `s3-outage`), `scripts/s3-check.sh`, `scripts/evidence-attachments.sh`; цели Makefile `scenario`, `s3-check`, `attachments-evidence`; ruff для новых `scripts/*.py` +- [ ] 8.2 CI-job под лабу 4: сценарии вложений после smoke +- [ ] 8.3 Проверка группы: `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` по обеим репликам с `make restore`, `make scenario SCENARIO=failover-upload`, `make scenario SCENARIO=s3-outage`, `make s3-check` + +## 9. Отчёт + +- [ ] 9.1 `evidence/`: smoke, contract-checks, student-tests, stack, storage-layout, failover-upload, failover по каждой реплике, persistence со `StartedAt` (включая `s3`), s3-outage, s3-security, схема и миграции, окружение +- [ ] 9.2 `REPORT.md`: запуск из чистого clone, архитектура и решения, таблица ролей и сервисов, соответствие переменных `.env.example`, строки уровня «3», таблица отказов уровня «3» +- [ ] 9.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`, `make test` и сценарии зелёные