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
72 lines
7.9 KiB
Markdown
72 lines
7.9 KiB
Markdown
# 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`, а не убивается по его истечении
|
||
|