From adca7c6edc9c917e9fdb41767b229ce14df4213f Mon Sep 17 00:00:00 2001 From: Artyom Date: Fri, 30 Oct 2026 08:53:53 +0300 Subject: [PATCH] Archive the attachment boundaries change Upload checks the token before the declared size, a slow but steady transfer outlives the request timeout while a stalled one is still cut, the API and the reconciler hold separate minimal S3 keys, and the one-off services run as non-root with an init process. On the stand a 3 MiB upload at 256 KiB/s took 12.1 s at the replica and got 201, a 3 MiB download at 192 KiB/s took 12.8 s and matched the SHA-256, the API key is denied a bucket listing, and docker stop ends a hanging reconciler pass in 0.13 s with exit code 143. student-test (345), test-faults (19), persistence, failover and the lab 4 scenarios pass. The requirements are synced into lab4-attachments, lab4-upload-resilience and lab4-object-storage. 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 | 6 ++-- openspec/specs/lab4-object-storage/spec.md | 31 +++++++++++++++---- openspec/specs/lab4-upload-resilience/spec.md | 17 +++++++++- 10 files changed, 46 insertions(+), 10 deletions(-) rename openspec/changes/{tighten-lab4-attachment-boundaries => archive/2026-10-30-tighten-lab4-attachment-boundaries}/.openspec.yaml (58%) rename openspec/changes/{tighten-lab4-attachment-boundaries => archive/2026-10-30-tighten-lab4-attachment-boundaries}/design.md (100%) rename openspec/changes/{tighten-lab4-attachment-boundaries => archive/2026-10-30-tighten-lab4-attachment-boundaries}/proposal.md (100%) rename openspec/changes/{tighten-lab4-attachment-boundaries => archive/2026-10-30-tighten-lab4-attachment-boundaries}/specs/lab4-attachments/spec.md (100%) rename openspec/changes/{tighten-lab4-attachment-boundaries => archive/2026-10-30-tighten-lab4-attachment-boundaries}/specs/lab4-object-storage/spec.md (100%) rename openspec/changes/{tighten-lab4-attachment-boundaries => archive/2026-10-30-tighten-lab4-attachment-boundaries}/specs/lab4-upload-resilience/spec.md (100%) rename openspec/changes/{tighten-lab4-attachment-boundaries => archive/2026-10-30-tighten-lab4-attachment-boundaries}/tasks.md (100%) diff --git a/openspec/changes/tighten-lab4-attachment-boundaries/.openspec.yaml b/openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/.openspec.yaml similarity index 58% rename from openspec/changes/tighten-lab4-attachment-boundaries/.openspec.yaml rename to openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/.openspec.yaml index 4bfa6709..7756d6b7 100644 --- a/openspec/changes/tighten-lab4-attachment-boundaries/.openspec.yaml +++ b/openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/.openspec.yaml @@ -1,2 +1,4 @@ schema: spec-driven created: 2026-10-30 +archived: 2026-10-30 +lab: 4 diff --git a/openspec/changes/tighten-lab4-attachment-boundaries/design.md b/openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/design.md similarity index 100% rename from openspec/changes/tighten-lab4-attachment-boundaries/design.md rename to openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/design.md diff --git a/openspec/changes/tighten-lab4-attachment-boundaries/proposal.md b/openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/proposal.md similarity index 100% rename from openspec/changes/tighten-lab4-attachment-boundaries/proposal.md rename to openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/proposal.md diff --git a/openspec/changes/tighten-lab4-attachment-boundaries/specs/lab4-attachments/spec.md b/openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/specs/lab4-attachments/spec.md similarity index 100% rename from openspec/changes/tighten-lab4-attachment-boundaries/specs/lab4-attachments/spec.md rename to openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/specs/lab4-attachments/spec.md diff --git a/openspec/changes/tighten-lab4-attachment-boundaries/specs/lab4-object-storage/spec.md b/openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/specs/lab4-object-storage/spec.md similarity index 100% rename from openspec/changes/tighten-lab4-attachment-boundaries/specs/lab4-object-storage/spec.md rename to openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/specs/lab4-object-storage/spec.md diff --git a/openspec/changes/tighten-lab4-attachment-boundaries/specs/lab4-upload-resilience/spec.md b/openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/specs/lab4-upload-resilience/spec.md similarity index 100% rename from openspec/changes/tighten-lab4-attachment-boundaries/specs/lab4-upload-resilience/spec.md rename to openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/specs/lab4-upload-resilience/spec.md diff --git a/openspec/changes/tighten-lab4-attachment-boundaries/tasks.md b/openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/tasks.md similarity index 100% rename from openspec/changes/tighten-lab4-attachment-boundaries/tasks.md rename to openspec/changes/archive/2026-10-30-tighten-lab4-attachment-boundaries/tasks.md diff --git a/openspec/specs/lab4-attachments/spec.md b/openspec/specs/lab4-attachments/spec.md index aac57811..c7844f2e 100644 --- a/openspec/specs/lab4-attachments/spec.md +++ b/openspec/specs/lab4-attachments/spec.md @@ -29,12 +29,12 @@ #### Scenario: Без аутентификации -- **WHEN** upload приходит без `Authorization` или с `Basic` -- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"` +- **WHEN** upload приходит без `Authorization` или с `Basic`, в том числе с объявленным `Content-Length` больше `MAX_UPLOAD_BYTES` +- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`, а не `413`: аутентификация проверяется раньше любых проверок запроса ### 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 записывать тело на свой диск. +Тело 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 diff --git a/openspec/specs/lab4-object-storage/spec.md b/openspec/specs/lab4-object-storage/spec.md index 6cc457cd..a04555e4 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 объекта @@ -20,11 +20,11 @@ #### Scenario: Повторный bootstrap - **WHEN** bootstrap запускается ещё два раза на работающем стенде -- **THEN** оба запуска завершаются кодом 0, а bucket, его анонимная политика, пользователь и политика API не меняются +- **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`. Ключ API SHALL разрешать только чтение, запись, удаление объектов и листинг bucket `S3_BUCKET` и SHALL получать `AccessDenied` на создание и удаление bucket, изменение его политики и lifecycle, администрирование пользователей и любые операции с другим bucket. Байты вложений 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, создание и удаление bucket, изменение его политики и lifecycle, администрирование пользователей и любые операции с другим bucket. Сверка хранилищ SHALL получать свой ключ: листинг bucket, чтение и удаление его объектов; запись объектов и любые операции с bucket и IAM этим ключом SHALL получать `AccessDenied`. Байты вложений SHALL храниться только в bucket: в PostgreSQL SHALL NOT быть столбцов с содержимым файла, у реплик API SHALL NOT быть volume, а корневая файловая система реплики SHALL быть только для чтения. Ключи и адреса хранилища SHALL NOT попадать в ответы API, журнал и Git. #### Scenario: Где лежат байты @@ -34,12 +34,17 @@ Root-ключи S3 SHALL передаваться файлами compose secrets #### Scenario: Ключ API - **WHEN** проверяются секреты сервиса `api` в `docker compose config` -- **THEN** у `api` есть только ключ API S3, а root-ключей нет +- **THEN** у `api` есть только ключ API S3, у `reconciler` — только ключ сверки, root-ключей нет ни у одного из них #### Scenario: Права ключа API вне API -- **WHEN** из отдельного контейнера ключом API выполняются запись, чтение, листинг и удаление объекта, а затем создание и удаление bucket, публичная политика, импорт lifecycle, список пользователей, запись и листинг в другом bucket -- **THEN** первые четыре операции разрешены, остальные получают `AccessDenied` +- **WHEN** из отдельного контейнера ключом API выполняются запись, чтение и удаление объекта, а затем листинг bucket, создание и удаление bucket, публичная политика, импорт lifecycle, список пользователей, запись и листинг в другом bucket +- **THEN** первые три операции разрешены, остальные получают `AccessDenied` + +#### Scenario: Права ключа сверки + +- **WHEN** ключом сверки выполняются листинг bucket, чтение и удаление объекта, затем запись объекта и создание bucket +- **THEN** листинг, чтение и удаление разрешены, запись и создание bucket получают `AccessDenied` ### Requirement: Файл переживает остановку обслужившей реплики @@ -50,3 +55,17 @@ Root-ключи S3 SHALL передаваться файлами compose secrets - **WHEN** выполняется `python3 scripts/lab4_scenarios.py failover-upload`: upload, остановка реплики из `X-Instance-Id` ответа хуком `scripts/stop-one.sh`, скачивание - **THEN** скачивание обслуживает другая реплика, SHA-256 совпадает, сценарий печатает `"ok": true` +### Requirement: Одноразовые сервисы стенда + +Одноразовые сервисы стенда (`migrate`, `s3-init`, `s3-cli`, `reconciler`) SHALL работать не от root, с закреплённым образом и лимитами CPU и памяти. Процесс, выполняющий работу `migrate` и `reconciler`, SHALL получать `SIGTERM` через init-процесс контейнера и завершаться без ожидания принудительного `SIGKILL`. + +#### Scenario: Пользователь одноразовых сервисов + +- **WHEN** после `make up` выполняется `docker inspect` контейнеров `migrate` и `s3-init` +- **THEN** у обоих задан ненулевой uid + +#### Scenario: Остановка сверки + +- **WHEN** во время прохода сверки контейнеру `reconciler` посылается `docker stop` +- **THEN** контейнер останавливается быстрее срока `stop_grace_period`, а не убивается по его истечении + diff --git a/openspec/specs/lab4-upload-resilience/spec.md b/openspec/specs/lab4-upload-resilience/spec.md index 98ac8bc3..b5a4f78d 100644 --- a/openspec/specs/lab4-upload-resilience/spec.md +++ b/openspec/specs/lab4-upload-resilience/spec.md @@ -43,7 +43,7 @@ ### Requirement: Обрыв и зависание тела -Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки вложения и SHALL учитываться как ошибка клиента (`400`), а не `500`. Тело, которое перестало поступать, SHALL обрываться не позже `REQUEST_TIMEOUT_SECONDS` с ответом `503` и кодом `unavailable`, без объекта и строки, а занятый им слот загрузки SHALL освобождаться для следующих загрузок. +Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки вложения и SHALL учитываться как ошибка клиента (`400`), а не `500`. Тело, которое перестало поступать или поступает медленнее `MIN_TRANSFER_RATE_BYTES` в секунду (по умолчанию 131 072), SHALL обрываться не позже `REQUEST_TIMEOUT_SECONDS` плюс время, положенное уже переданным байтам по этой скорости, с ответом `503` и кодом `unavailable`, без объекта и строки, а занятый им слот загрузки SHALL освобождаться для следующих загрузок. Передача тела запроса и тела ответа не медленнее `MIN_TRANSFER_RATE_BYTES` SHALL NOT обрываться таймаутом запроса, сколько бы она ни длилась; после последнего полученного байта тела на обработку SHALL оставаться не больше `REQUEST_TIMEOUT_SECONDS`. #### Scenario: Клиент закрыл соединение посреди тела @@ -55,6 +55,21 @@ - **WHEN** клиент отправил заголовки и часть тела и перестал слать байты - **THEN** не позже `REQUEST_TIMEOUT_SECONDS` плюс 2 с приходит `503` с кодом `unavailable`, строки и объекта нет, следующая загрузка проходит +#### Scenario: Медленная, но идущая загрузка + +- **WHEN** клиент через LB загружает PNG 3 MiB со скоростью около 256 KiB/s, дольше `REQUEST_TIMEOUT_SECONDS` +- **THEN** ответ `201`, `sha256` равен SHA-256 тела + +#### Scenario: Медленное скачивание + +- **WHEN** клиент через LB читает `/content` вложения 3 MiB со скоростью около 192 KiB/s, дольше `REQUEST_TIMEOUT_SECONDS` +- **THEN** получены все `Content-Length` байт, SHA-256 равен `sha256` метаданных + +#### Scenario: Тело ползёт медленнее порога + +- **WHEN** клиент шлёт тело заметно медленнее `MIN_TRANSFER_RATE_BYTES` +- **THEN** приходит `503` с кодом `unavailable` примерно через `REQUEST_TIMEOUT_SECONDS`, вложение не создаётся + ### Requirement: Ограниченная память одновременных загрузок Воркер API SHALL держать в памяти тела не более `UPLOAD_CONCURRENCY` загрузок одновременно; остальные загрузки SHALL ждать свободного слота, не читая тело, в пределах `REQUEST_TIMEOUT_SECONDS`. Тело SHALL NOT записываться на диск реплики. Пик памяти реплики при ≥10 одновременных загрузках по 10 MiB SHALL оставаться ниже её лимита памяти без перезапуска процесса, а все корректные загрузки SHALL получать `201`.