Propose image attachments as an openspec change
Plan grade 3 of lab 4 as one change: a third domain zone for attachments that takes the raw bytes of one PNG or JPEG, applies the size limit before reading the whole body and the pixel limit before decoding, checks the type by content, writes a pending row, the object and then the ready row and only then answers 201, and serves metadata and the original only to chat members through the API. Messages gain attachment_ids, linked by a foreign key to attachments of the same chat so the messaging zone never reads the attachments table, and the zone asks messaging about membership through a port wired in main.py. The stand gains RustFS with a private bucket, a one-off bootstrap with a separate API key, and a restart hook that waits for S3. The specs add lab4-attachments and lab4-object-storage and modify message sending, history, idempotent replay, the restart hook and stand persistence. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
bf8e4e3cd1
commit
d7fb96bb70
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
@@ -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/<uuid7>')`, `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`.
|
||||
@@ -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/<uuid>` назначает сервер.
|
||||
- Порядок записи: строка-намерение `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).
|
||||
@@ -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`
|
||||
@@ -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** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||||
@@ -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`
|
||||
@@ -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` после прогона позже, чем до него
|
||||
@@ -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
|
||||
@@ -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/<uuid>`, у реплики `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`
|
||||
@@ -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` и сценарии зелёные
|
||||
Reference in New Issue
Block a user