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

Rewrite AGENTS.md and the openspec context and rules for lab 5: upload
answers 202 queued after the original is in a private staging prefix
and the attachment, the job and the outbox row are committed in one
transaction, a separate relay publishes the outbox to RabbitMQ with
publisher confirms, a separate worker built from the same image
consumes the queue through FastStream with a manual ack after the
result commit, PostgreSQL stays the source of truth for job states,
Out of scope moves to labs 6-7, track 1 and broker HA, and the rules
add the failure windows between PostgreSQL and the broker, the effect
key and the lease to specs and designs.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-29 00:32:37 +03:00

53 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`