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

72 lines
7.9 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, создание и удаление bucket, изменение его политики и lifecycle, администрирование пользователей и любые операции с другим bucket. Сверка хранилищ SHALL получать свой ключ: листинг bucket, чтение и удаление его объектов; запись объектов и любые операции с bucket и IAM этим ключом SHALL получать `AccessDenied`. Байты вложений 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, у `reconciler` — только ключ сверки, root-ключей нет ни у одного из них
#### Scenario: Права ключа API вне API
- **WHEN** из отдельного контейнера ключом API выполняются запись, чтение и удаление объекта, а затем листинг bucket, создание и удаление bucket, публичная политика, импорт lifecycle, список пользователей, запись и листинг в другом bucket
- **THEN** первые три операции разрешены, остальные получают `AccessDenied`
#### Scenario: Права ключа сверки
- **WHEN** ключом сверки выполняются листинг bucket, чтение и удаление объекта, затем запись объекта и создание bucket
- **THEN** листинг, чтение и удаление разрешены, запись и создание bucket получают `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`
### 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`, а не убивается по его истечении