diff --git a/openspec/changes/add-lab4-upload-resilience/.openspec.yaml b/openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/.openspec.yaml similarity index 58% rename from openspec/changes/add-lab4-upload-resilience/.openspec.yaml rename to openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/.openspec.yaml index 1bb6456d..c918d0b7 100644 --- a/openspec/changes/add-lab4-upload-resilience/.openspec.yaml +++ b/openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/.openspec.yaml @@ -1,2 +1,4 @@ schema: spec-driven created: 2026-10-28 +archived: 2026-10-29 +lab: 4 diff --git a/openspec/changes/add-lab4-upload-resilience/design.md b/openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/design.md similarity index 100% rename from openspec/changes/add-lab4-upload-resilience/design.md rename to openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/design.md diff --git a/openspec/changes/add-lab4-upload-resilience/proposal.md b/openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/proposal.md similarity index 100% rename from openspec/changes/add-lab4-upload-resilience/proposal.md rename to openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/proposal.md diff --git a/openspec/changes/add-lab4-upload-resilience/specs/lab4-attachments/spec.md b/openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/specs/lab4-attachments/spec.md similarity index 100% rename from openspec/changes/add-lab4-upload-resilience/specs/lab4-attachments/spec.md rename to openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/specs/lab4-attachments/spec.md diff --git a/openspec/changes/add-lab4-upload-resilience/specs/lab4-object-storage/spec.md b/openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/specs/lab4-object-storage/spec.md similarity index 100% rename from openspec/changes/add-lab4-upload-resilience/specs/lab4-object-storage/spec.md rename to openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/specs/lab4-object-storage/spec.md diff --git a/openspec/changes/add-lab4-upload-resilience/specs/lab4-upload-resilience/spec.md b/openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/specs/lab4-upload-resilience/spec.md similarity index 100% rename from openspec/changes/add-lab4-upload-resilience/specs/lab4-upload-resilience/spec.md rename to openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/specs/lab4-upload-resilience/spec.md diff --git a/openspec/changes/add-lab4-upload-resilience/tasks.md b/openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/tasks.md similarity index 100% rename from openspec/changes/add-lab4-upload-resilience/tasks.md rename to openspec/changes/archive/2026-10-29-add-lab4-upload-resilience/tasks.md diff --git a/openspec/specs/lab4-attachments/spec.md b/openspec/specs/lab4-attachments/spec.md index c4b5a1a4..c981e3b7 100644 --- a/openspec/specs/lab4-attachments/spec.md +++ b/openspec/specs/lab4-attachments/spec.md @@ -125,12 +125,12 @@ ### Requirement: Порядок записи PostgreSQL и S3 -Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. +Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. Намерение и объект, оставшиеся после сбоя, SHALL удаляться компенсацией сразу или уборкой по истечении grace period (capability `lab4-upload-resilience`), поэтому объект без строки-намерения в bucket не остаётся. #### Scenario: S3 отказал при записи - **WHEN** запись объекта завершилась ошибкой -- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях +- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях, а строка-намерение удаляется уборкой после grace period #### Scenario: Клиент оборвал загрузку diff --git a/openspec/specs/lab4-object-storage/spec.md b/openspec/specs/lab4-object-storage/spec.md index 9c43d80f..6cc457cd 100644 --- a/openspec/specs/lab4-object-storage/spec.md +++ b/openspec/specs/lab4-object-storage/spec.md @@ -5,7 +5,7 @@ ## Requirements ### Requirement: S3-сервер и приватный bucket в стенде -Стенд SHALL включать S3-совместимый сервер с образом, закреплённым версией и digest, данными на именованном volume и healthcheck, без опубликованных на хост портов и без доступной административной консоли. Одноразовый bootstrap SHALL создавать bucket `S3_BUCKET` (по умолчанию `messenger-attachments`), делать его приватным для анонимного клиента, создавать пользователя API с политикой только на объекты и листинг этого bucket и завершаться кодом 0; повторный запуск SHALL проходить без ошибок и без изменения состояния. Реплики API SHALL стартовать после успешного bootstrap. +Стенд SHALL включать S3-совместимый сервер с образом, закреплённым версией и digest, данными на именованном volume и healthcheck, без опубликованных на хост портов и без доступной административной консоли — ни внутри контейнера, ни из сети стенда. Одноразовый bootstrap SHALL создавать bucket `S3_BUCKET` (по умолчанию `messenger-attachments`), делать его приватным для анонимного клиента, создавать пользователя API с политикой только на объекты и листинг этого bucket и завершаться кодом 0; повторный запуск SHALL проходить без ошибок и без изменения состояния. Реплики API SHALL стартовать после успешного bootstrap. #### Scenario: Анонимный GET объекта @@ -14,8 +14,8 @@ #### Scenario: Порты и консоль -- **WHEN** выполняется `docker compose ps` и запрос к порту консоли внутри контейнера S3 -- **THEN** у сервиса S3 нет опубликованных портов, а консоль не отвечает +- **WHEN** выполняется `docker compose ps`, запрос к порту консоли внутри контейнера S3 и запрос к тому же порту из отдельного контейнера сети стенда +- **THEN** у сервиса S3 нет опубликованных портов, а консоль не отвечает ни там, ни там #### Scenario: Повторный bootstrap @@ -24,7 +24,7 @@ ### 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. +Root-ключи S3 SHALL передаваться файлами compose secrets только S3-серверу, bootstrap и операторскому CLI; реплики API SHALL получать отдельный ключ из `S3_ACCESS_KEY_ID_FILE` и `S3_SECRET_ACCESS_KEY_FILE`. Ключ API SHALL разрешать только чтение, запись, удаление объектов и листинг bucket `S3_BUCKET` и SHALL получать `AccessDenied` на создание и удаление bucket, изменение его политики и lifecycle, администрирование пользователей и любые операции с другим bucket. Байты вложений SHALL храниться только в bucket: в PostgreSQL SHALL NOT быть столбцов с содержимым файла, у реплик API SHALL NOT быть volume, а корневая файловая система реплики SHALL быть только для чтения. Ключи и адреса хранилища SHALL NOT попадать в ответы API, журнал и Git. #### Scenario: Где лежат байты @@ -36,6 +36,11 @@ Root-ключи S3 SHALL передаваться файлами compose secrets - **WHEN** проверяются секреты сервиса `api` в `docker compose config` - **THEN** у `api` есть только ключ API S3, а root-ключей нет +#### Scenario: Права ключа API вне API + +- **WHEN** из отдельного контейнера ключом API выполняются запись, чтение, листинг и удаление объекта, а затем создание и удаление bucket, публичная политика, импорт lifecycle, список пользователей, запись и листинг в другом bucket +- **THEN** первые четыре операции разрешены, остальные получают `AccessDenied` + ### Requirement: Файл переживает остановку обслужившей реплики Вложение, загруженное через одну реплику API, SHALL скачиваться через другую реплику после остановки первой с тем же SHA-256. diff --git a/openspec/specs/lab4-upload-resilience/spec.md b/openspec/specs/lab4-upload-resilience/spec.md new file mode 100644 index 00000000..98ac8bc3 --- /dev/null +++ b/openspec/specs/lab4-upload-resilience/spec.md @@ -0,0 +1,80 @@ +# lab4-upload-resilience Specification + +## Purpose +Определяет устойчивость загрузки вложений: что остаётся после сбоя между записью объекта и фиксацией метаданных и кто это убирает, какой grace period защищает идущие загрузки, как обрываются прерванные и зависшие загрузки, сколько памяти занимают одновременные загрузки и что пользовательские ошибки файлов не превращаются в `500`. +## Requirements +### Requirement: Компенсация сбоя после записи объекта + +Если объект записан в bucket, а перевод вложения в готовое не зафиксирован, сервис SHALL ответить `503` с кодом `unavailable` и до ответа SHALL попытаться удалить объект и строку-намерение. Строку, которая к этому моменту уже готова, сервис SHALL NOT удалять вместе с её объектом. Если строку-намерение к моменту перевода в готовое уже убрали, сервис SHALL ответить `503` и удалить записанный объект, а не возвращать `201`. Неудача компенсации SHALL оставлять строку-намерение для уборки по grace period. + +#### Scenario: Отказ COMMIT после записи объекта + +- **WHEN** запись объекта прошла, а фиксация статуса `ready` в PostgreSQL отклонена +- **THEN** ответ `503` с кодом `unavailable`, сразу после ответа нет ни строки вложения, ни объекта с его ключом, в журнале есть событие удаления намерения с причиной `compensation` + +#### Scenario: Намерение снято раньше, чем загрузка завершилась + +- **WHEN** во время записи объекта строку-намерение удалили +- **THEN** ответ `503`, объект с ключом этой загрузки удалён, готового вложения не появилось + +### Requirement: Уборка брошенных загрузок по grace period + +Сервис SHALL без участия оператора и не реже чем раз в `UPLOAD_SWEEP_INTERVAL_SECONDS` удалять сначала объект, затем строку каждого намерения `pending`, созданного раньше чем `UPLOAD_GRACE_SECONDS` назад. Grace period SHALL быть не меньше 60 с и много больше `REQUEST_TIMEOUT_SECONDS`, чтобы идущая загрузка не была убрана. Уборка SHALL NOT трогать намерения моложе grace period, готовые вложения и вложения, на которые ссылаются сообщения, SHALL быть безопасной при одновременной работе на нескольких репликах и повторяемой: следующий проход после полного SHALL ничего не удалять. Если S3 недоступен, намерение SHALL оставаться до следующего прохода. + +#### Scenario: Процесс упал между записью объекта и фиксацией + +- **WHEN** процесс реплики убит после записи объекта, но до фиксации `ready`, а затем намерение становится старше grace period +- **THEN** до истечения grace period строка `pending` и объект остаются невидимыми клиентам; после — уборка удаляет и объект, и строку + +#### Scenario: Свежее намерение переживает уборку + +- **WHEN** проход уборки выполняется, пока одно брошенное намерение старше grace period, а другое моложе +- **THEN** удалено только старое, свежее остаётся вместе со своим объектом + +#### Scenario: Готовые и используемые вложения не трогаются + +- **WHEN** проход уборки выполняется после того, как время создания готового вложения, на которое ссылается сообщение, сдвинуто далеко в прошлое +- **THEN** вложение по-прежнему скачивается участником с тем же SHA-256 + +#### Scenario: Несколько уборок одновременно + +- **WHEN** два прохода уборки одновременно обрабатывают пять брошенных намерений +- **THEN** вместе они удаляют ровно пять, без ошибок, а следующий проход удаляет ноль + +### Requirement: Обрыв и зависание тела + +Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки вложения и SHALL учитываться как ошибка клиента (`400`), а не `500`. Тело, которое перестало поступать, SHALL обрываться не позже `REQUEST_TIMEOUT_SECONDS` с ответом `503` и кодом `unavailable`, без объекта и строки, а занятый им слот загрузки SHALL освобождаться для следующих загрузок. + +#### Scenario: Клиент закрыл соединение посреди тела + +- **WHEN** клиент объявил `Content-Length` 5 MiB, отправил 256 KiB и закрыл соединение +- **THEN** строка вложения не создавалась, объект не появился, реплика записала в журнал статус `400` + +#### Scenario: Тело зависло + +- **WHEN** клиент отправил заголовки и часть тела и перестал слать байты +- **THEN** не позже `REQUEST_TIMEOUT_SECONDS` плюс 2 с приходит `503` с кодом `unavailable`, строки и объекта нет, следующая загрузка проходит + +### Requirement: Ограниченная память одновременных загрузок + +Воркер API SHALL держать в памяти тела не более `UPLOAD_CONCURRENCY` загрузок одновременно; остальные загрузки SHALL ждать свободного слота, не читая тело, в пределах `REQUEST_TIMEOUT_SECONDS`. Тело SHALL NOT записываться на диск реплики. Пик памяти реплики при ≥10 одновременных загрузках по 10 MiB SHALL оставаться ниже её лимита памяти без перезапуска процесса, а все корректные загрузки SHALL получать `201`. + +#### Scenario: Ожидание слота + +- **WHEN** при `UPLOAD_CONCURRENCY=1` одна загрузка держит слот, а вторая приходит следом +- **THEN** тело второй не читается, пока первая не завершилась, затем обе получают `201` + +#### Scenario: Замер одновременных загрузок + +- **WHEN** через LB идут 10, 20 и 40 одновременных загрузок PNG по 1 MiB и по 10 MiB, а пик памяти каждой реплики снимается из cgroup +- **THEN** при лимите слотов все загрузки получают `201`, пик памяти реплики ниже `API_MEMORY` и не растёт пропорционально числу одновременных загрузок + +### Requirement: Пользовательские ошибки файлов не дают 500 + +Ни одна ошибка клиента при загрузке, чтении вложения или ссылке на него SHALL NOT давать ответ `5xx` или строку журнала реплики со статусом `500`. Через балансировщик против настоящих PostgreSQL и S3 SHALL проверяться: тело на байт больше лимита (с `Content-Length` и chunked) — `413`; декомпрессионная бомба — `413`; обрезанный PNG и JPEG — `415`; подмена MIME (JPEG, GIF, текст как `image/png`, PNG как `image/jpeg`) и отсутствующий или иной `Content-Type` — `415`; опасный и пустой `filename` — `400`; метаданные и `/content` чужого вложения — `404`; ссылка на чужое, неизвестное вложение и вложение другого чата — `404`; 11 и повторяющиеся `attachment_ids`, невалидный UUID и неизвестный `variant` — `400`. + +#### Scenario: Негативный suite через балансировщик + +- **WHEN** все перечисленные запросы отправлены на стенд через LB +- **THEN** каждый ответ имеет ожидаемый код и тело ошибки по схеме `Error`, ни один не `5xx`, в журнале реплик за время прогона нет статуса `500`, а строк вложений в чате ровно столько, сколько было ответов `201` +