Files
mtusi2026labs/openspec/specs/lab4-object-storage/spec.md
T
ArtyomandClaude Opus 5.5 a0d3947710 Carry over the agent context and openspec history from lab 5
Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 5 specs and the
archived lab 1 to lab 5 changes into the lab 6 skeleton, so lab 6
continues the same spec history instead of starting from scratch. The
files come from the lab 5 solution commit 64d5c67.

Rewrite AGENTS.md and the openspec context and rules for lab 6: the
business API stays at contract 1.6.0, API, relay and worker start the
OpenTelemetry SDK in every process after fork and export OTLP over HTTP
to a separate Collector, Prometheus, Loki and Tempo store metrics, logs
and traces on volumes, Grafana only reads them through provisioning
kept in Git, telemetry never blocks a request and never feeds
/health/ready, metric labels stay low-cardinality and message bodies
and secrets never leave the process. Out of scope moves to lab 7,
track 2 and clustered telemetry backends.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-29 03:46:20 +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