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` +