Files
mtusi2026labs/openspec/specs/lab4-object-storage/spec.md
T
ArtyomandClaude Opus 5.5 d2744bc1ac 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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
2026-10-29 00:25:46 +03:00

5.8 KiB
Raw Blame History

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. Ключ 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: Где лежат байты

  • WHEN после загрузки выполняются \d attachments, листинг bucket и docker inspect реплики API
  • THEN в таблице нет bytea, объект лежит в bucket под ключом attachments/<uuid>, у реплики ReadonlyRootfs=true и нет volume

Scenario: Ключ API

  • 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.

Scenario: Upload, остановка реплики, download

  • WHEN выполняется python3 scripts/lab4_scenarios.py failover-upload: upload, остановка реплики из X-Instance-Id ответа хуком scripts/stop-one.sh, скачивание
  • THEN скачивание обслуживает другая реплика, SHA-256 совпадает, сценарий печатает "ok": true