From d2744bc1aca84e545d24fb034984f9c063388973 Mon Sep 17 00:00:00 2001 From: Artyom Date: Thu, 29 Oct 2026 00:25:46 +0300 Subject: [PATCH] Archive the upload resilience change Grade 4 of lab 4 is closed. A failed ready commit after the object write is compensated at once under a row lock, intents abandoned by a crash or a lost write are swept with their objects after a 900 s grace period by every replica with SKIP LOCKED, and nothing younger, nothing ready and nothing referenced is touched. A client abort is a 400 and a stalled body a 503 after 8 s, both leaving nothing behind. Three upload slots per worker, capped socket buffers in the balancer and the API and a fixed glibc mmap threshold keep 40 concurrent 10 MiB uploads at 330 of 512 MiB per replica with every upload succeeding, while without the slots the same load hits the limit and loses 37 of 80. 36 user errors through the balancer give no 5xx, and 23 checks prove the bucket private, the API key limited, the console closed and the bootstrap idempotent. For the defence: run make upload-faults to show the negative suite, the compensation, the killed replica with its leftover swept after the grace period while the fresh one stays, and the abort and stall; show the memory summary and make s3-check. The lab4-upload-resilience spec is added, and the write order of lab4-attachments and the console and API key requirements of lab4-object-storage are updated in the main specs. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27 --- .../.openspec.yaml | 2 + .../design.md | 0 .../proposal.md | 0 .../specs/lab4-attachments/spec.md | 0 .../specs/lab4-object-storage/spec.md | 0 .../specs/lab4-upload-resilience/spec.md | 0 .../tasks.md | 0 openspec/specs/lab4-attachments/spec.md | 4 +- openspec/specs/lab4-object-storage/spec.md | 13 ++- openspec/specs/lab4-upload-resilience/spec.md | 80 +++++++++++++++++++ 10 files changed, 93 insertions(+), 6 deletions(-) rename openspec/changes/{add-lab4-upload-resilience => archive/2026-10-29-add-lab4-upload-resilience}/.openspec.yaml (58%) rename openspec/changes/{add-lab4-upload-resilience => archive/2026-10-29-add-lab4-upload-resilience}/design.md (100%) rename openspec/changes/{add-lab4-upload-resilience => archive/2026-10-29-add-lab4-upload-resilience}/proposal.md (100%) rename openspec/changes/{add-lab4-upload-resilience => archive/2026-10-29-add-lab4-upload-resilience}/specs/lab4-attachments/spec.md (100%) rename openspec/changes/{add-lab4-upload-resilience => archive/2026-10-29-add-lab4-upload-resilience}/specs/lab4-object-storage/spec.md (100%) rename openspec/changes/{add-lab4-upload-resilience => archive/2026-10-29-add-lab4-upload-resilience}/specs/lab4-upload-resilience/spec.md (100%) rename openspec/changes/{add-lab4-upload-resilience => archive/2026-10-29-add-lab4-upload-resilience}/tasks.md (100%) create mode 100644 openspec/specs/lab4-upload-resilience/spec.md 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` +