From e4253eb076aaef0a0c66380de702dcd794a56a9e Mon Sep 17 00:00:00 2001 From: Artyom Date: Wed, 28 Oct 2026 22:20:38 +0300 Subject: [PATCH] Archive the image attachments change Grade 3 of lab 4 is closed. RustFS with a private bucket runs in the stand, metadata lives in PostgreSQL and the bytes only in the bucket, uploads answer 201 ready after the object write and the commit, and the original is served byte for byte to chat members only. The smoke test passes from a fresh clone; limits of 10 MiB and 40 MP, content type by content and dangerous names are covered by 325 own tests; an upload survives the stop of the replica that took it, both replicas fail over under writes in under 3.1 s, a full restart keeps metadata and bytes, and with S3 stopped uploads and downloads answer 503 within 2.6 s while texts, metadata and readiness keep working. 22 checks show the bucket is private outside the API and the API key is limited. For the defence: upload the fixture, send it in a message, download it as the second member and compare SHA-256, get 404 as a stranger and 403 for an anonymous GET in S3, then run persistence, failover and the upload failover scenario. The lab4-attachments and lab4-object-storage specs are added, and message sending, history, idempotent replay, the restart hook and stand persistence are updated in the main specs. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../.openspec.yaml | 2 + .../design.md | 0 .../proposal.md | 0 .../specs/lab1-messenger-history/spec.md | 0 .../specs/lab2-persistent-storage/spec.md | 0 .../specs/lab3-idempotent-messages/spec.md | 0 .../specs/lab3-load-balancing/spec.md | 0 .../specs/lab4-attachments/spec.md | 0 .../specs/lab4-object-storage/spec.md | 0 .../tasks.md | 0 openspec/specs/lab1-messenger-history/spec.md | 35 +++- .../specs/lab2-persistent-storage/spec.md | 10 +- .../specs/lab3-idempotent-messages/spec.md | 16 +- openspec/specs/lab3-load-balancing/spec.md | 4 +- openspec/specs/lab4-attachments/spec.md | 153 ++++++++++++++++++ openspec/specs/lab4-object-storage/spec.md | 47 ++++++ 16 files changed, 252 insertions(+), 15 deletions(-) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/.openspec.yaml (58%) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/design.md (100%) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/proposal.md (100%) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/specs/lab1-messenger-history/spec.md (100%) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/specs/lab2-persistent-storage/spec.md (100%) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/specs/lab3-idempotent-messages/spec.md (100%) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/specs/lab3-load-balancing/spec.md (100%) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/specs/lab4-attachments/spec.md (100%) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/specs/lab4-object-storage/spec.md (100%) rename openspec/changes/{add-lab4-image-attachments => archive/2026-10-28-add-lab4-image-attachments}/tasks.md (100%) create mode 100644 openspec/specs/lab4-attachments/spec.md create mode 100644 openspec/specs/lab4-object-storage/spec.md diff --git a/openspec/changes/add-lab4-image-attachments/.openspec.yaml b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/.openspec.yaml similarity index 58% rename from openspec/changes/add-lab4-image-attachments/.openspec.yaml rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/.openspec.yaml index 1bb6456d..6510b417 100644 --- a/openspec/changes/add-lab4-image-attachments/.openspec.yaml +++ b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/.openspec.yaml @@ -1,2 +1,4 @@ schema: spec-driven created: 2026-10-28 +archived: 2026-10-28 +lab: 4 diff --git a/openspec/changes/add-lab4-image-attachments/design.md b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/design.md similarity index 100% rename from openspec/changes/add-lab4-image-attachments/design.md rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/design.md diff --git a/openspec/changes/add-lab4-image-attachments/proposal.md b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/proposal.md similarity index 100% rename from openspec/changes/add-lab4-image-attachments/proposal.md rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/proposal.md diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab1-messenger-history/spec.md b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab1-messenger-history/spec.md similarity index 100% rename from openspec/changes/add-lab4-image-attachments/specs/lab1-messenger-history/spec.md rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab1-messenger-history/spec.md diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab2-persistent-storage/spec.md b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab2-persistent-storage/spec.md similarity index 100% rename from openspec/changes/add-lab4-image-attachments/specs/lab2-persistent-storage/spec.md rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab2-persistent-storage/spec.md diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab3-idempotent-messages/spec.md b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab3-idempotent-messages/spec.md similarity index 100% rename from openspec/changes/add-lab4-image-attachments/specs/lab3-idempotent-messages/spec.md rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab3-idempotent-messages/spec.md diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab3-load-balancing/spec.md b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab3-load-balancing/spec.md similarity index 100% rename from openspec/changes/add-lab4-image-attachments/specs/lab3-load-balancing/spec.md rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab3-load-balancing/spec.md diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab4-attachments/spec.md b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab4-attachments/spec.md similarity index 100% rename from openspec/changes/add-lab4-image-attachments/specs/lab4-attachments/spec.md rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab4-attachments/spec.md diff --git a/openspec/changes/add-lab4-image-attachments/specs/lab4-object-storage/spec.md b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab4-object-storage/spec.md similarity index 100% rename from openspec/changes/add-lab4-image-attachments/specs/lab4-object-storage/spec.md rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/specs/lab4-object-storage/spec.md diff --git a/openspec/changes/add-lab4-image-attachments/tasks.md b/openspec/changes/archive/2026-10-28-add-lab4-image-attachments/tasks.md similarity index 100% rename from openspec/changes/add-lab4-image-attachments/tasks.md rename to openspec/changes/archive/2026-10-28-add-lab4-image-attachments/tasks.md diff --git a/openspec/specs/lab1-messenger-history/spec.md b/openspec/specs/lab1-messenger-history/spec.md index a8c20c81..f49594d8 100644 --- a/openspec/specs/lab1-messenger-history/spec.md +++ b/openspec/specs/lab1-messenger-history/spec.md @@ -5,14 +5,34 @@ ## Requirements ### Requirement: Отправка сообщения -Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`. +Сервис 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` +- **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` @@ -25,7 +45,7 @@ #### Scenario: Пустой или пробельный текст -- **WHEN** тело содержит `{"text":""}` или `{"text":" "}` +- **WHEN** тело содержит `{"text":""}`, `{"text":"","attachment_ids":[]}` или `{"text":" "}` с вложениями или без - **THEN** ответ `400` с кодом `invalid_request` #### Scenario: Текст длиннее предела @@ -42,7 +62,7 @@ #### Scenario: Доступ проверяется раньше содержимого -- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text` +- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text` или с 11 вложениями - **THEN** ответ `404`, а не `400` ### Requirement: Порядок истории @@ -67,7 +87,7 @@ ### Requirement: Чтение истории keyset-курсором -Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами. +Сервис 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: Первая страница отдаёт курсор @@ -80,6 +100,11 @@ - **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null` - **AND** элемент первой страницы не повторяется +#### Scenario: Элементы истории несут вложения + +- **WHEN** в чате есть текстовое сообщение и сообщение с вложением +- **THEN** у текстового элемента `attachment_ids` равен `[]`, у второго — список его вложений, и оба элемента совпадают с ответами `201` + #### Scenario: Курсор не привязан к читателю - **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата diff --git a/openspec/specs/lab2-persistent-storage/spec.md b/openspec/specs/lab2-persistent-storage/spec.md index 6b771aca..9884db4d 100644 --- a/openspec/specs/lab2-persistent-storage/spec.md +++ b/openspec/specs/lab2-persistent-storage/spec.md @@ -53,12 +53,12 @@ PostgreSQL SHALL хранить пользователей, сессии, чат ### Requirement: Данные и сессии переживают рестарт -Пользователи, чаты, участники, сообщения, ключи идемпотентности и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же. +Пользователи, чаты, участники, сообщения со ссылками на вложения, ключи идемпотентности, метаданные вложений, их байты в 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` +- **THEN** hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`, в том числе после однократного чтения метаданных и байтов вложения #### Scenario: Логаут после рестарта @@ -67,12 +67,12 @@ PostgreSQL SHALL хранить пользователей, сессии, чат ### Requirement: Воспроизводимый стенд из репозитория -Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны, и SHALL NOT появляться в Git, образе и журнале. +Стенд 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, а `GET /health/ready` через балансировщик отвечает `200` +- **THEN** все сервисы становятся `healthy` или завершаются кодом 0 (`migrate`, `s3-init`), а `GET /health/ready` через балансировщик отвечает `200` #### Scenario: Опубликован только балансировщик @@ -81,6 +81,6 @@ PostgreSQL SHALL хранить пользователей, сессии, чат #### Scenario: Секреты и volumes вне Git -- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url .env` +- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url secrets/s3_root_password .env` - **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются diff --git a/openspec/specs/lab3-idempotent-messages/spec.md b/openspec/specs/lab3-idempotent-messages/spec.md index d4728d35..0982b9cd 100644 --- a/openspec/specs/lab3-idempotent-messages/spec.md +++ b/openspec/specs/lab3-idempotent-messages/spec.md @@ -19,16 +19,26 @@ ### Requirement: Повтор возвращает исходный результат -Область ключа SHALL составлять пользователь сессии, метод и путь чата и сам ключ. Повтор с тем же ключом и семантически тем же JSON (порядок полей не важен) в течение `IDEMPOTENCY_TTL_SECONDS` (не меньше 86 400 с) SHALL возвращать `201` и тот же объект `Message` — те же `id`, `text` и строку `created_at` — без создания нового сообщения. Тот же ключ с другим JSON SHALL давать `409` с кодом `conflict`. Одинаковый ключ у разных пользователей или в разных чатах SHALL действовать независимо. После истечения срока ключ SHALL приниматься как новый. +Область ключа 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`, тело равно телу первого ответа целиком, в истории одно такое сообщение +- **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` +- **WHEN** участник повторяет `POST` с тем же ключом, но другим `text` или другим списком либо порядком `attachment_ids` - **THEN** ответ `409` с кодом `conflict`, новое сообщение не создаётся #### Scenario: Тот же ключ у другого пользователя diff --git a/openspec/specs/lab3-load-balancing/spec.md b/openspec/specs/lab3-load-balancing/spec.md index 0cc58663..f5852c69 100644 --- a/openspec/specs/lab3-load-balancing/spec.md +++ b/openspec/specs/lab3-load-balancing/spec.md @@ -75,10 +75,10 @@ ### Requirement: Рестарт стенда -Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL и Valkey с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд снова готов. +Хук `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` после прогона позже, чем до него +- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres`, `valkey` и `s3` после прогона позже, чем до него diff --git a/openspec/specs/lab4-attachments/spec.md b/openspec/specs/lab4-attachments/spec.md new file mode 100644 index 00000000..c4b5a1a4 --- /dev/null +++ b/openspec/specs/lab4-attachments/spec.md @@ -0,0 +1,153 @@ +# lab4-attachments Specification + +## Purpose +Определяет вложения-изображения чата: синхронную загрузку оригинала PNG/JPEG с лимитами и проверкой содержимого, метаданные, скачивание оригинала через API, доступ только участникам чата, порядок записи PostgreSQL ↔ S3 и поведение при недоступном S3. +## 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/specs/lab4-object-storage/spec.md b/openspec/specs/lab4-object-storage/spec.md new file mode 100644 index 00000000..9c43d80f --- /dev/null +++ b/openspec/specs/lab4-object-storage/spec.md @@ -0,0 +1,47 @@ +# lab4-object-storage Specification + +## Purpose +Определяет объектное хранилище вложений как часть стенда: S3-совместимый сервер с закреплённой версией и persistent volume, приватный bucket и воспроизводимый bootstrap, раздельные ключи администратора и API, а также то, что байты не живут в БД и на диске реплики и переживают остановку реплики и рестарт стенда. +## 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` +