docs: archive s3-storage and sync its specs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-20 21:51:36 +03:00
co-authored by Claude Opus 5.5
parent 1471f07a0e
commit e1161f7e6b
17 changed files with 566 additions and 100 deletions
+9 -6
View File
@@ -9,9 +9,10 @@ S3-совместимое хранилище и вложения-изображ
`contracts/README.md`, раздел «Вложения (с lab4)»). Код перенесён из
лабы 3 (репозиторий `mtusi2026lab3-safronov`, ветка
`solution/bvt2301-safronov`, commit `ce89eba`) по разделу «Переход в
следующую лабу». S3 в стенде — change `s3-storage`: SeaweedFS с
приватным bucket, bootstrap и клиент `src/infra/s3/`; вложений (ручек,
`attachment_ids`) ещё нет. План работ, решения и
следующую лабу». S3 в стенде — change `s3-storage` (заархивирован
2026-10-20, `openspec/changes/archive/2026-10-20-s3-storage/`):
SeaweedFS с приватным bucket, bootstrap и клиент `src/infra/s3/`;
вложений (ручек, `attachment_ids`) ещё нет. План работ, решения и
трек «5» — `PLAN.md`. Из лабы 2: PostgreSQL
как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш
карточек чатов. Из лабы 3: HAProxy перед ≥2 репликами API
@@ -22,9 +23,11 @@ S3-совместимое хранилище и вложения-изображ
строгие курсор и UUID на входе (`strict-id-validation`). Стенд `bench/`
— трек 2 лабы 2 (план запроса и восстановление), профили `failover` и
`rollout`, серии трека 1 лабы 3 (`scaling-bench`, `scaling-improvement`,
`profile-resources`). Changes лаб 2 и 3 — в `openspec/changes/archive/`,
спеки синхронизированы, активных changes нет; `KNOWN_ISSUES.md` без
открытых записей. Отчёт, evidence и рабочий план лабы 3 остались в её
`profile-resources`). Changes лаб 2 и 3 и `s3-storage` лабы 4 — в
`openspec/changes/archive/`, спеки синхронизированы (с `s3-storage` —
новая capability `object-storage`), активных changes нет; в
`KNOWN_ISSUES.md` две открытые записи (профиль `rollout`, bootstrap
после удаления bucket). Отчёт, evidence и рабочий план лабы 3 остались в её
репозитории (`REPORT.md`, `evidence/`, `git show 063eedb:PLAN.md`).
Стек: Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings,
structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
+1 -1
View File
@@ -227,7 +227,7 @@ RustFS. В `.claude/rules/settings.md` MinIO упомянут только пр
| № | Change | Уровень | Что происходит | Готово, когда |
|---|---|---|---|---|
| 0 | — (подготовка) | — | этот план; выбор трека и S3-сервера | план сохранён 2026-10-20; трек 2, SeaweedFS, решения 3 и 7 подтверждены 2026-10-20 |
| 1 | `s3-storage` | 3 (+4: bootstrap, права, консоль, приватность) | S3 в стенде, bootstrap, клиент в `src/infra/s3/`, настройки, все стенды знают о S3 | bootstrap дважды без ошибок, анонимный GET / LIST → 403, ключ API не может admin-операций, `make test-persistence` перезапускает и S3 |
| 1 | `s3-storage` | 3 (+4: bootstrap, права, консоль, приватность) | S3 в стенде, bootstrap, клиент в `src/infra/s3/`, настройки, все стенды знают о S3 | bootstrap дважды без ошибок, анонимный GET / LIST → 403, ключ API не может admin-операций, `make test-persistence` перезапускает и S3; **заархивирован 2026-10-20** — `openspec/changes/archive/2026-10-20-s3-storage/` |
| 2 | `attachments` | 3 (+4: тесты) | миграция, домен `attachment`, ручки, `attachment_ids` в сообщениях, тесты | зелёные `make test`, `test-persistence`, `test-failover`, свой сценарий отказа загрузившей реплики; негативные тесты; evidence исключений переснят |
| 3 | `upload-consistency` | 4 | намерение до PUT, компенсация, уборщик с grace period, тесты отказов | `make failure_checks` с отказами S3 и БД посреди загрузки: нет 500, нет неучтённых объектов старше grace period |
| 4 | `upload-memory` | 4 | лимит загрузок на реплику, сроки тела, профиль `uploads` | замер ≥ 10 одновременных загрузок: пик памяти ограничен, механизм объяснён |
+100 -56
View File
@@ -3,30 +3,39 @@
## Purpose
Как стенд сервиса запускается и настраивается: compose с PostgreSQL,
Valkey, одноразовыми миграциями и API (`make run_docker`), публикация
портов только на localhost, конфигурация на старте, сохранность данных
при рестарте стенда и явное удаление учебных данных.
Valkey, сервером S3, одноразовыми миграциями и bootstrap S3 и API
(`make run_docker`), публикация портов только на localhost,
конфигурация на старте, сохранность данных при рестарте стенда и явное
удаление учебных данных.
## Requirements
### Requirement: Запуск через compose
`make run_docker` SHALL собирать образ и поднимать стенд через
`docker compose`: PostgreSQL, Valkey, одноразовый сервис миграций,
`API_REPLICAS` реплик API (capability `load-balancing`) и балансировщик
(LB). Реплики API SHALL стартовать после готовности PostgreSQL и Valkey
и успешных миграций. Миграции SHALL выполняться один раз за запуск
отдельным сервисом, а не репликами. Перед этим цель SHALL создавать
недостающие `.env` и `config.toml` из шаблонов (`make env_setup`) и
MUST NOT перезаписывать существующие. `make stop` SHALL останавливать
сервисы, `make down` — удалять контейнеры, сохраняя volume, `make logs`
— показывать журнал всех реплик API.
`docker compose`. В стенд входят:
- PostgreSQL и Valkey;
- сервер S3 (capability `object-storage`);
- одноразовые сервисы миграций и bootstrap S3;
- `API_REPLICAS` реплик API (capability `load-balancing`);
- балансировщик (LB).
Реплики API SHALL стартовать после готовности PostgreSQL и Valkey,
успешных миграций и успешного bootstrap S3. Миграции и bootstrap SHALL
выполняться один раз за запуск отдельными сервисами, а не репликами.
Перед этим цель SHALL создавать недостающие `.env` и `config.toml` из
шаблонов (`make env_setup`) и MUST NOT перезаписывать существующие.
`make stop` SHALL останавливать сервисы, `make down` — удалять
контейнеры, сохраняя volumes, `make logs` — показывать журнал всех
реплик API.
#### Scenario: Штатный запуск
- **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** сервис отвечает через LB на
`http://localhost:8080/health/ready`, работают две реплики API, и
`http://localhost:8080/health/ready`, работают две реплики API, сервер
S3 в состоянии `healthy`, bootstrap S3 завершился с кодом 0, и
`make student_test` проходит
#### Scenario: Миграции один раз
@@ -35,6 +44,12 @@ MUST NOT перезаписывать существующие. `make stop` SHAL
- **THEN** журнал сервиса миграций содержит один прогон, а в журналах
реплик API нет запуска миграций
#### Scenario: Bootstrap S3 один раз
- **WHEN** выполнен `make run_docker` с двумя репликами
- **THEN** журнал bootstrap S3 содержит один прогон, завершённый до
старта реплик, а в журналах реплик API нет создания bucket
### Requirement: Порты из .env
Порты стенда и консольного запуска SHALL браться из одного `.env`:
@@ -49,13 +64,16 @@ MUST NOT перезаписывать существующие. `make stop` SHAL
- внешний порт PostgreSQL — `POSTGRES_OUT_PORT`: порт на `127.0.0.1`
хоста для запуска в консоли;
- порт Valkey внутри сети compose — `VALKEY_PORT`, внешний —
`VALKEY_OUT_PORT` на `127.0.0.1` для запуска в консоли.
`VALKEY_OUT_PORT` на `127.0.0.1` для запуска в консоли;
- порт API S3 внутри сети compose — `S3_PORT`, его слушает сам сервер
S3, используют API в docker и bootstrap; внешний — `S3_OUT_PORT` на
`127.0.0.1` для запуска в консоли.
Если переменная порта API не задана, SHALL действовать 8080. Параметры
приложения в `.env` SHALL записываться в формате настроек
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
которые приложение не читает. Адреса и порты PostgreSQL и Valkey MUST
NOT быть записаны в compose литералами.
которые приложение не читает. Адреса и порты PostgreSQL, Valkey и S3
MUST NOT быть записаны в compose литералами.
#### Scenario: Другой внешний порт
@@ -85,35 +103,50 @@ NOT быть записаны в compose литералами.
- **THEN** `make run_docker` и `make run_dev` подключаются к Valkey на
новых портах, и кэш работает
#### Scenario: Другой порт S3
- **WHEN** в `.env` заданы другие `S3_PORT` и `S3_OUT_PORT`, а compose
не правился
- **THEN** сервер S3 слушает `S3_PORT` и становится `healthy`, bootstrap
проходит, `make s3_check` проходит, а приложение в консоли обращается
к S3 на `127.0.0.1:$S3_OUT_PORT`
### Requirement: Оба способа запуска описаны в REPORT.md
Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два
способа запуска стенда: `make run_docker` (всё в compose) и
`make run_dev` (Postgres в compose, сервис на хосте). Для каждого SHALL
быть указаны подготовка (`make env_setup`), команды, которые выполняет
цель Makefile, применение миграций, ожидание готовности, проверки и
остановка.
способа запуска стенда:
- `make run_docker` — всё в compose;
- `make run_dev` — PostgreSQL, Valkey и S3 с bootstrap в compose,
сервис на хосте.
Для каждого SHALL быть указаны подготовка (`make env_setup`), команды,
которые выполняет цель Makefile, применение миграций и bootstrap S3,
ожидание готовности, проверки и остановка.
#### Scenario: Запуск по отчёту
- **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md`
для любого из двух способов
- **THEN** `/health/ready` отвечает 200, а `make student_test` проходит
- **THEN** `/health/ready` отвечает 200, а `make student_test` и
`make s3_check` проходят
### Requirement: Публикация только на localhost
Порты LB, PostgreSQL и Valkey SHALL публиковаться в compose только на
`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не
переменной. Реплики API MUST NOT публиковать порты на хосте: к ним
Порты LB, PostgreSQL и Valkey и порт API S3 SHALL публиковаться в
compose только на `127.0.0.1` хоста. Адрес публикации SHALL быть
записан литералом, а не переменной. Другие порты сервера S3 (консоль,
UI, внутренние серверы хранилища) MUST NOT публиковаться. Реплики API и
одноразовые сервисы MUST NOT публиковать порты на хосте: к репликам
ходят только LB и контейнеры сети compose. Учебный стенд MUST NOT быть
доступен с других машин сети.
#### Scenario: Адрес публикации
- **WHEN** для запущенных контейнеров LB, API, Postgres и Valkey
- **WHEN** для запущенных контейнеров LB, API, Postgres, Valkey и S3
выполняется `docker port`
- **THEN** порты LB, Postgres и Valkey опубликованы на `127.0.0.1`, а
не на `0.0.0.0`, а у контейнеров API опубликованных портов нет
- **THEN** порты LB, Postgres, Valkey и порт API S3 опубликованы на
`127.0.0.1`, а не на `0.0.0.0`; других портов у S3 не опубликовано, а
у контейнеров API опубликованных портов нет
### Requirement: Конфигурация на старте
@@ -144,24 +177,27 @@ compose, и приложению, SHALL передаваться через `env
### Requirement: Данные переживают рестарт стенда
Данные PostgreSQL SHALL храниться в именованном volume. Скрипт
Данные PostgreSQL и S3 SHALL храниться в именованных volumes. Скрипт
`scripts/restart.sh` SHALL перезапускать LB, все реплики API и все
используемые хранилища — PostgreSQL и Valkey. Volume, схема и данные
SHALL сохраняться: без удаления volume, очистки и повторного
наполнения. Число реплик после рестарта SHALL оставаться прежним.
Скрипт SHALL быть исполняемым, завершаться с кодом 0 только после
перезапуска, укладываться в 90 с и MUST NOT печатать секреты.
Публичная проверка `make test-persistence
ACTION_SCRIPT=scripts/restart.sh` SHALL проходить через LB.
используемые хранилища — PostgreSQL, Valkey и S3. Volumes, схема,
bucket, учётные записи S3 и данные SHALL сохраняться: без удаления
volumes, очистки и повторного наполнения. Bootstrap S3, который снова
выполняется при старте реплик, состояние хранилища не меняет. Число
реплик после рестарта SHALL оставаться прежним. Скрипт SHALL быть
исполняемым, завершаться с кодом 0 только после перезапуска,
укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка
`make test-persistence ACTION_SCRIPT=scripts/restart.sh` SHALL
проходить через LB.
#### Scenario: Рестарт hook-ом
- **WHEN** пользователь вошёл, отправил сообщение, затем выполнен
`scripts/restart.sh`
- **THEN** контейнеры LB, всех реплик API, Postgres и Valkey
- **THEN** контейнеры LB, всех реплик API, Postgres, Valkey и S3
перезапущены: те же ID и новое время старта в `docker inspect`. После
готовности запрос с прежним токеном через LB получает 200 и видит
своё сообщение
своё сообщение, а bootstrap S3 после рестарта сообщает, что bucket и
пользователь уже есть
#### Scenario: Публичная проверка сохранности
@@ -171,20 +207,22 @@ ACTION_SCRIPT=scripts/restart.sh` SHALL проходить через LB.
### Requirement: Удаление учебных данных
`make stop` и `make down` MUST NOT удалять volume с данными. Удаление
данных стенда SHALL выполняться отдельной явной командой
`make wipe_data`, которая запрашивает подтверждение.
`make stop` и `make down` MUST NOT удалять volumes с данными PostgreSQL
и S3. Удаление данных стенда SHALL выполняться отдельной явной командой
`make wipe_data`, которая запрашивает подтверждение и называет
удаляемые данные.
#### Scenario: down сохраняет данные
- **WHEN** выполнены `make down`, затем `make run_docker`
- **THEN** ранее созданные пользователи и сообщения на месте
- **THEN** ранее созданные пользователи, сообщения и объекты S3 на месте
#### Scenario: Явное удаление
- **WHEN** выполнен `make wipe_data` и удаление подтверждено
- **THEN** volume Postgres удалён, и следующий `make run_docker`
поднимает пустую базу со схемой из миграций
- **THEN** volumes Postgres и S3 удалены, и следующий `make run_docker`
поднимает пустую базу со схемой из миграций и пустой приватный bucket,
созданный bootstrap
### Requirement: Журнал контейнера
@@ -209,32 +247,38 @@ MUST NOT затрагивать ресурсы проектов прошлых
- **WHEN** на машине есть volume `mtusi-lab3_postgres_data`, и в этом
репозитории выполнены `make run_docker`, затем `make wipe_data` с
подтверждением
- **THEN** стенд создаёт и затем удаляет только
`mtusi-lab4_postgres_data`, а `mtusi-lab3_postgres_data` остаётся с
прежней датой создания
- **THEN** стенд создаёт и затем удаляет только volumes своего проекта
(`mtusi-lab4_postgres_data`, `mtusi-lab4_s3_data`), а
`mtusi-lab3_postgres_data` остаётся с прежней датой создания
### Requirement: Лимиты ресурсов и секреты по сервисам
Каждый сервис стенда SHALL иметь лимиты CPU и памяти: LB, реплики API,
сервис миграций, PostgreSQL и Valkey. Сумма лимитов и расчёт
соединений PostgreSQL для заявленного числа реплик SHALL быть описаны
в `REPORT.md`. Секреты SHALL передаваться только тем сервисам, которым
они нужны:
сервисы миграций и bootstrap S3, PostgreSQL, Valkey и сервер S3. Сумма
лимитов и расчёт соединений PostgreSQL для заявленного числа реплик
SHALL быть описаны в `REPORT.md`. Секреты SHALL передаваться только тем
сервисам, которым они нужны:
- пароль PostgreSQL — PostgreSQL, репликам API и сервису миграций;
- пароль Valkey — Valkey и репликам API;
- LB MUST NOT получать ни одного секрета.
- административные ключ и секрет S3 — только серверу S3;
- ключ подписи служебных вызовов S3 — серверу S3 и bootstrap;
- ключи пользователя API в S3 — bootstrap и репликам API;
- LB MUST NOT получать ни одного секрета, а сервис миграций, PostgreSQL
и Valkey MUST NOT получать секретов S3.
#### Scenario: Лимиты у всех контейнеров
- **WHEN** для каждого контейнера запущенного стенда выполняется
`docker inspect` (`HostConfig.NanoCpus`, `HostConfig.Memory`)
- **THEN** у LB, каждой реплики API, сервиса миграций, PostgreSQL и
Valkey оба значения больше нуля
- **THEN** у LB, каждой реплики API, сервисов миграций и bootstrap S3,
PostgreSQL, Valkey и сервера S3 оба значения больше нуля
#### Scenario: Секреты по сервисам
- **WHEN** проверяющий смотрит окружение сервисов в
`docker compose config`
- **THEN** у LB нет ни одного пароля, у сервиса миграций нет пароля
Valkey, а пароль Valkey есть только у Valkey и реплик API
- **THEN** у LB нет ни одного секрета; у сервиса миграций нет пароля
Valkey и секретов S3; пароль Valkey есть только у Valkey и реплик API;
административные ключи S3 — только у сервера S3, ключ подписи — у
сервера S3 и bootstrap, ключи API в S3 — у bootstrap и реплик API
+333
View File
@@ -0,0 +1,333 @@
# object-storage Specification
## Purpose
S3-хранилище байтов стенда с лабы 4. Здесь описано:
- сервер, его закрепление и служебные интерфейсы вне сети;
- идемпотентный bootstrap приватного bucket;
- запрет анонимного доступа и ограниченные учётные данные API;
- проверка приватности вне API и сохранность данных при рестарте;
- клиент приложения: сроки вызовов, ошибки и ключи объектов по имени
базы.
## Requirements
### Requirement: S3-хранилище в стенде
Рабочий стенд compose (`make run_docker`) SHALL включать один
S3-совместимый сервер. Его образ SHALL быть закреплён тегом с версией и
digest индекса. Данные сервера SHALL
храниться в именованном volume. Сервису SHALL быть заданы:
- healthcheck, который проверяет готовность обслуживать запросы S3, в
том числе запись объекта: `healthy` MUST NOT наступать раньше, чем
хранилище томов готово принять запись;
- лимиты CPU и памяти;
- перезапуск после сбоя;
- срок остановки, за который сервер завершается сам, без принудительного
завершения.
Сервер SHALL выдерживать одновременную запись 20 объектов по 10 MiB без
превышения лимита памяти. Сервер MUST NOT отправлять сведения о стенде
внешним сервисам, в том числе анонимную статистику.
#### Scenario: Сервис S3 запущен
- **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** контейнер S3 в состоянии `healthy`, его образ указан тегом с
версией и digest, а данные лежат в именованном volume проекта
#### Scenario: Первая запись после healthy
- **WHEN** контейнер S3 перезапущен с сохранённым volume и стал
`healthy`, и сразу после этого ключом API записывается объект
- **THEN** первая запись проходит заметно быстрее срока вызова клиента
(`[s3] timeout_seconds`), а не ждёт регистрации хранилища томов
#### Scenario: Остановка сервера
- **WHEN** выполняется `docker compose stop s3`
- **THEN** контейнер S3 завершается с кодом 0 раньше срока остановки,
а не принудительно
#### Scenario: Одновременная запись
- **WHEN** 20 клиентов одновременно записывают ключом API по объекту
10 MiB, затем читают их
- **THEN** все записи подтверждены и прочитаны с тем же размером, а
контейнер S3 не перезапускался и не был завершён из-за памяти
#### Scenario: Без внешней статистики
- **WHEN** стенд работает
- **THEN** у процесса S3 нет соединений с адресами вне сети стенда,
а отправка статистики выключена в описании сервиса
### Requirement: Служебные интерфейсы вне сети
Из контейнера S3 в сеть compose SHALL быть открыты только порт API S3 и
служебный gRPC-порт шлюза S3, без которого шлюз не работает. Консоль
администратора, UI и внутренние серверы хранилища (координатор,
метаданные, тома) MUST NOT быть доступны ни из сети compose, ни с хоста.
Порт API S3 SHALL публиковаться только на `127.0.0.1` хоста, другие
порты сервера MUST NOT публиковаться.
Изменение учётных записей и политик через служебный gRPC-порт SHALL
требовать токен, подписанный секретным ключом стенда. Без токена вызов
MUST NOT менять учётные записи сервера.
#### Scenario: Порты из сети стенда
- **WHEN** из другого контейнера сети compose проверяются порты
контейнера S3
- **THEN** открыты только порт API S3 и gRPC-порт шлюза, а порты
консоли, UI, координатора, метаданных и томов закрыты
#### Scenario: Порты на хосте
- **WHEN** для запущенного контейнера S3 выполняется `docker port`
- **THEN** опубликован только порт API S3 и только на `127.0.0.1`
#### Scenario: Учётная запись через gRPC-порт без токена
- **WHEN** клиент из сети стенда без токена передаёт шлюзу S3 через
gRPC-порт новую учётную запись с правами администратора
- **THEN** вызов отклонён как неаутентифицированный, а запросы S3 с
ключами этой записи получают отказ
### Requirement: Приватный bucket создаёт bootstrap
Bucket приложения SHALL создавать одноразовый сервис bootstrap стенда.
Bootstrap SHALL:
- создать bucket, если его нет;
- запретить анонимный доступ к bucket;
- завести пользователя API с политикой доступа (требование
«Ограниченные учётные данные API») и ключами из `.env`.
На рабочем стенде реплики API MUST NOT стартовать, пока bootstrap не
завершился успешно. Стенды проверок с S3 (`make test_isolated`, `make
failure_checks`) запускают bootstrap до своих контейнеров API.
Повторный запуск SHALL завершаться успешно и не менять уже правильное
состояние: bucket и его объекты сохраняются, пользователь не
пересоздаётся. Если в `.env` изменился секрет API, повторный запуск
SHALL привести к нему учётные данные пользователя, а прежний секрет
SHALL перестать действовать.
Вывод bootstrap MUST NOT содержать секретов. Ошибка любого шага SHALL
давать ненулевой код выхода и сообщение, которое называет шаг.
#### Scenario: Первый запуск
- **WHEN** стенд поднимается на пустом volume S3
- **THEN** bootstrap создаёт bucket и пользователя API и завершается с
кодом 0, и только после этого стартуют реплики API
#### Scenario: Повторный запуск
- **WHEN** на работающем стенде bootstrap запускается ещё дважды подряд
- **THEN** оба запуска завершаются с кодом 0 и сообщают, что bucket и
пользователь уже есть, а записанные ранее объекты читаются
#### Scenario: Новый секрет API
- **WHEN** в `.env` изменён секрет API, и bootstrap запущен снова
- **THEN** запросы S3 с новым секретом проходят, а с прежним получают
отказ
#### Scenario: Ошибка bootstrap
- **WHEN** bootstrap не может выполнить шаг, например имя bucket
недопустимо
- **THEN** он завершается с ненулевым кодом и сообщением о шаге, реплики
API не стартуют, а в выводе нет секретов
### Requirement: Запрет анонимного доступа
Bucket SHALL быть приватным с первого старта сервера. Анонимный запрос
SHALL получать 403 на:
- чтение объекта и его метаданных;
- список объектов bucket и список bucket-ов;
- запись объекта и создание bucket.
Для несуществующего ключа ответ SHALL быть тем же 403: он MUST NOT
показывать, есть ли объект. Сервер MUST NOT работать без учётных
записей ни в какой момент, в том числе до первого запуска bootstrap.
#### Scenario: Анонимное чтение
- **WHEN** аноним с хоста или из сети стенда запрашивает существующий
объект bucket и его метаданные
- **THEN** оба ответа 403, байтов объекта в ответе нет
#### Scenario: Анонимный список и запись
- **WHEN** аноним запрашивает список объектов bucket, список bucket-ов
или записывает объект
- **THEN** каждый ответ 403, и объект не создан
#### Scenario: Несуществующий ключ
- **WHEN** аноним запрашивает ключ, которого в bucket нет
- **THEN** ответ 403, как для существующего ключа
#### Scenario: До bootstrap
- **WHEN** сервер только что запущен на пустом volume, а bootstrap ещё
не выполнялся
- **THEN** анонимное создание bucket и запись объекта получают 403
### Requirement: Ограниченные учётные данные API
У API SHALL быть свои учётные данные S3, отдельные от административных.
Пользователю API SHALL быть разрешены только чтение, запись и удаление
объектов своего bucket. Ему MUST NOT быть разрешены:
- список объектов;
- операции с bucket: создание, удаление, политика, ACL;
- публичный ACL объекта;
- управление учётными записями;
- любой доступ к другим bucket.
Административные учётные данные S3 MUST NOT передаваться репликам API.
#### Scenario: Работа с объектами
- **WHEN** ключом API в своём bucket записывается объект, читаются он
и его метаданные, затем объект удаляется
- **THEN** все операции проходят, а прочитанные байты совпадают с
записанными по SHA-256
#### Scenario: Запрещённые операции
- **WHEN** ключом API запрашиваются список объектов, создание и
удаление bucket, политика и ACL bucket и публичный ACL объекта
- **THEN** каждый запрос получает 403, а bucket и его доступ не
меняются
#### Scenario: Чужой bucket
- **WHEN** на сервере есть другой bucket, и ключом API в нём читается
объект, записывается объект и запрашивается список
- **THEN** каждый запрос получает 403
#### Scenario: Ключи реплик API
- **WHEN** проверяющий смотрит окружение реплик API в `docker compose
config`
- **THEN** там есть ключи пользователя API и нет административных
ключей S3 и ключа подписи
### Requirement: Проверка приватности вне API
Приватность bucket и права ключа API SHALL проверяться без участия
приложения двумя способами.
1. Каждый запуск bootstrap. Ключ API записывает, читает и удаляет
проверочный объект и получает отказ на список и на создание bucket.
Аноним получает отказ на чтение существующего объекта и на список.
При нарушении bootstrap завершается с ненулевым кодом, и реплики API
не стартуют.
2. Отдельная команда `make s3_check` на запущенном стенде. Она
повторяет проверки bootstrap и добавляет:
- анонимные запросы с хоста и из сети стенда;
- запросы ключа API к чужому bucket;
- административные запросы ключа API.
Команда SHALL печатать по каждой проверке ожидаемый и полученный код
ответа без секретов. При любом нарушении код выхода SHALL быть
ненулевым. Свои проверочные объекты и bucket команда SHALL удалять.
#### Scenario: Проверка командой
- **WHEN** на запущенном стенде выполняется `make s3_check`
- **THEN** каждая проверка напечатана с полученным кодом ответа, код
выхода 0, а проверочных объектов и bucket после команды нет
#### Scenario: Bucket стал публичным
- **WHEN** на bucket открыт анонимный доступ на чтение, например
административной командой мимо bootstrap
- **THEN** `make s3_check` завершается с ненулевым кодом и называет
нарушенную проверку, а следующий запуск bootstrap снова закрывает
доступ
### Requirement: Данные хранилища переживают рестарт
Bucket, учётные записи и объекты SHALL переживать перезапуск сервера S3
и всего стенда с сохранённым volume. Объекты с подтверждённой записью
SHALL сохраняться и после принудительного завершения процесса S3.
#### Scenario: Рестарт стенда
- **WHEN** объект записан ключом API, затем выполнен
`scripts/restart.sh`
- **THEN** контейнер S3 перезапущен (новое время старта), объект
читается тем же ключом с тем же SHA-256, bucket и пользователь API на
месте
#### Scenario: Принудительное завершение
- **WHEN** сразу после подтверждённых записей контейнер S3 завершён
сигналом KILL и запущен снова
- **THEN** все подтверждённые объекты читаются с тем же SHA-256
### Requirement: Клиент хранилища в приложении
Приложение SHALL обращаться к S3 с учётными данными API из секции
`[s3]`. Клиент SHALL уметь записать объект, прочитать его потоком,
получить метаданные и удалить. Удаление отсутствующего объекта — не
ошибка. Каждый вызов SHALL быть ограничен сроком из настроек. После
отказа или истечения срока вызов MUST NOT повторяться автоматически.
Ошибкой недоступности, которую API отдаёт как 503 `unavailable` в
формате контракта, SHALL заканчиваться вызов, если S3:
- недоступен;
- не ответил за срок;
- отклонил учётные данные;
- отказал ключу API в доступе или не нашёл bucket.
Такой вызов MUST NOT давать 500 или зависать. Отсутствующий объект SHALL
отличаться от недоступности: отсутствующий bucket MUST NOT выдаваться за
отсутствующий объект у записи, чтения и удаления. После возврата S3 вызовы SHALL проходить
без перезапуска приложения. Соединения с S3 SHALL открываться при
первом вызове, а при остановке сервиса клиент SHALL закрываться.
Ключ объекта SHALL начинаться с имени базы PostgreSQL процесса и `/`.
Так объекты прогона на временной базе (`make test_isolated`) отделены
от объектов рабочей базы.
#### Scenario: S3 остановлен
- **WHEN** S3 остановлен, и приложение записывает объект
- **THEN** вызов за доли секунды завершается ошибкой недоступности, без
повторов
#### Scenario: S3 завис
- **WHEN** контейнер S3 заморожен (`docker pause`), и приложение
записывает объект
- **THEN** вызов завершается ошибкой недоступности не позже срока
вызова
#### Scenario: S3 вернулся
- **WHEN** S3 снова доступен, а приложение не перезапускалось
- **THEN** следующий вызов проходит
#### Scenario: Объекта нет
- **WHEN** приложение читает ключ, которого в bucket нет
- **THEN** клиент сообщает, что объекта нет, а не недоступность S3
#### Scenario: Bucket нет
- **WHEN** bucket приложения удалён мимо bootstrap, и приложение
записывает, читает или удаляет объект
- **THEN** каждый вызов завершается ошибкой недоступности, а не
сообщением «объекта нет», и в журнале есть запись уровня `error`
#### Scenario: Учётные данные отклонены
- **WHEN** секрет API у приложения не совпадает с секретом на сервере
S3
- **THEN** вызов завершается ошибкой недоступности, а в журнале есть
запись уровня `error` без секрета
+55 -3
View File
@@ -126,8 +126,8 @@ SHALL быть в `REPORT.md`.
Переключение между запуском в консоли и в docker MUST NOT требовать
правки `.env`, `config.toml` или compose, в том числе
комментирования и раскомментирования блоков. В консоли сервис SHALL
подключаться к PostgreSQL и Valkey по адресам публикации на хосте из
`.env`, в docker — по адресам и портам внутри сети compose, которые
подключаться к PostgreSQL, Valkey и S3 по адресам публикации на хосте
из `.env`, в docker — по адресам и портам внутри сети compose, которые
compose передаёт в окружение контейнера из переменных `.env`.
#### Scenario: Консоль, затем docker
@@ -135,7 +135,9 @@ compose передаёт в окружение контейнера из пер
- **WHEN** выполнен `make run_dev`, затем он остановлен и выполнен
`make run_docker`, а файлы конфигурации между запусками не менялись
- **THEN** оба запуска доходят до `/health/ready` 200, видят одни и те
же данные и пишут карточки чатов в Valkey
же данные и пишут карточки чатов в Valkey, а запись о старте называет
S3 стенда: в консоли — адрес публикации на хосте, в docker — адрес в
сети compose
### Requirement: Подключение к Valkey
@@ -157,6 +159,56 @@ SHALL получать случайный пароль. Пароль MUST NOT п
недоступности
- **THEN** в журнале нет значения пароля
### Requirement: Подключение к S3
Параметры S3 SHALL задаваться в секции `[s3]`:
- адрес и порт;
- имя bucket;
- ключи пользователя API;
- регион;
- срок вызова и срок установки соединения;
- размер пула соединений клиента.
Секрет API SHALL иметь один источник — переменную `.env`, которую
читает и bootstrap S3; приложение получает его мостом. Имя bucket
читают и приложение, и bootstrap, поэтому в `.env` оно записывается в
формате настроек. Новый `.env` из `make env_setup` SHALL получать
случайные секреты S3: административный секрет, секрет API и ключ
подписи. Секреты S3 MUST NOT попадать в журнал.
Имя bucket SHALL соответствовать правилам имён bucket S3: 3–63 символа,
строчные латинские буквы, цифры, `.` и `-`, первый и последний символ —
буква или цифра. Сроки SHALL быть положительными числами. Иначе сервис
MUST NOT стартовать (требование «Некорректное значение останавливает
запуск»).
Соответствие имён skeleton `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`,
`S3_ACCESS_KEY_ID_FILE` и `S3_SECRET_ACCESS_KEY_FILE` реальной
конфигурации SHALL быть описано в `REPORT.md`.
#### Scenario: Секрет API в одном месте
- **WHEN** в `.env` меняется секрет API S3, и стенд поднимается заново
- **THEN** bootstrap приводит к нему пользователя API, а сервис в
консоли и в docker использует новый секрет без правки других файлов
#### Scenario: Секреты в новом .env
- **WHEN** `make env_setup` дважды выполняется в каталоге без `.env`, и
между запусками `.env` удаляется
- **THEN** секреты S3 в обоих `.env` непустые и различаются
#### Scenario: Секреты S3 не в журнале
- **WHEN** сервис стартует и обращается к S3, в том числе с неверным
секретом
- **THEN** в журнале нет ни секретов S3, ни ключей доступа
#### Scenario: Недопустимое имя bucket
- **WHEN** сервис запускается с `S3__BUCKET=Bad_Bucket`
- **THEN** сервис не стартует, а в выводе упомянут `bucket`
### Requirement: Срок жизни сессии
Срок жизни сессии SHALL задаваться параметром приложения
+18
View File
@@ -79,6 +79,16 @@
отправки SHALL быть виден по признаку повтора и `id` сообщения. Для
сессий допускаются `id` сессии и `user_id`.
С лабы 4 записи MUST NOT содержать:
- ключи доступа и секретные ключи S3;
- ключ подписи служебных вызовов S3;
- подписи запросов к S3: их заголовок `Authorization` и параметры
подписи;
- байты объектов.
Для обращений к S3 допускаются адрес S3, имя bucket, ключ объекта,
размер, длительность и класс ошибки.
#### Scenario: Отправка сообщения
- **WHEN** участник отправляет сообщение с текстом T
@@ -102,6 +112,14 @@
и `id` сессии, а неудачный вход записан с уровнем `warning` без
username и пароля
#### Scenario: Обращение к S3
- **WHEN** сервис стартует, затем обращается к S3 сначала с верным, а
потом с неверным секретом API
- **THEN** ни одна запись журнала не содержит ключ доступа, секрет и
подпись запроса; запись о старте содержит адрес S3 и имя bucket, а
отказ в учётных данных записан с уровнем `error`
### Requirement: Непредвиденные ошибки в журнале
Непредвиденное исключение SHALL записываться с уровнем `error`,
+50 -34
View File
@@ -254,53 +254,67 @@ commit, адресом стенда и итогом. `REPORT.md` SHALL ссыл
`make test_isolated` SHALL проверять образ, собранный из рабочего
дерева, в связке compose на временной базе `test_<имя рабочей базы>` в
PostgreSQL стенда, с Valkey стенда. Команда SHALL: поднять PostgreSQL и
Valkey, собрать образ, создать базу заново, применить к ней миграции
сервисом миграций compose, запустить отдельный контейнер API из
определения сервиса compose, в котором подменено только имя базы,
опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`, дождаться
готовности, выполнить публичный smoke (`make test`) и весь набор
(`make student_test`) против этого контейнера, затем остановить и
удалить контейнер и удалить базу. Это один процесс API без
балансировщика: набор SHALL запускаться с `EXPECT_REPLICAS=1`, и тесты
реплик пропускаются с причиной. Код выхода SHALL быть ненулевым, если
не прошёл smoke, набор или уборка. Рабочая база и рабочие контейнеры
стенда MUST NOT затрагиваться, а карточки чатов тестового прогона в
Valkey отделены от рабочих именем базы в ключе (capability
`chat-cache`). Параллельный запуск двух прогонов не поддерживается.
PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по порядку:
1. поднять PostgreSQL, Valkey и S3 с bootstrap;
2. собрать образ и создать базу заново;
3. применить к ней миграции сервисом миграций compose;
4. запустить отдельный контейнер API из определения сервиса compose, в
котором подменено только имя базы, и опубликовать его на
`127.0.0.1:TEST_APP_PORT` из `.env`;
5. дождаться готовности и выполнить публичный smoke (`make test`) и
весь набор (`make student_test`) против этого контейнера;
6. остановить и удалить контейнер, удалить базу и объекты S3 под
префиксом `test_<db>/`.
Это один процесс API без балансировщика: набор SHALL запускаться с
`EXPECT_REPLICAS=1`, и тесты реплик пропускаются с причиной. Код
выхода SHALL быть ненулевым, если не прошёл smoke, набор или уборка.
Рабочая база и рабочие контейнеры стенда MUST NOT затрагиваться.
Тестовый прогон отделён от рабочего именем базы:
- карточки чатов в Valkey — именем базы в ключе (capability
`chat-cache`);
- объекты в S3 — префиксом имени базы в ключе объекта (capability
`object-storage`).
Объекты рабочей базы при уборке MUST NOT удаляться. Параллельный
запуск двух прогонов не поддерживается.
#### Scenario: Успешный прогон
- **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и
выполнен `make test_isolated`
- **THEN** smoke и набор прошли, тесты реплик пропущены с причиной,
код выхода 0, ни базы `test_<db>`, ни тестового контейнера после
команды нет, число строк в таблицах рабочей базы не изменилось, а
код выхода 0, ни базы `test_<db>`, ни тестового контейнера, ни
объектов под префиксом `test_<db>/` после команды нет, число строк в
таблицах рабочей базы и объекты рабочей базы не изменились, а
рабочий стенд продолжает отвечать через балансировщик
#### Scenario: Упавшие тесты
- **WHEN** во время `make test_isolated` падает хотя бы один тест
- **THEN** код выхода ненулевой, журнал тестового контейнера выведен,
контейнер удалён, база `test_<db>` удалена
контейнер удалён, база `test_<db>` и объекты под префиксом
`test_<db>/` удалены
#### Scenario: Прерывание
- **WHEN** `make test_isolated` прерван Ctrl+C
- **THEN** тестовый контейнер остановлен и удалён, база `test_<db>`
удалена
- **THEN** тестовый контейнер остановлен и удалён, база `test_<db>` и
объекты под префиксом `test_<db>/` удалены
#### Scenario: Хвост прошлого прогона
- **WHEN** тестовый контейнер или база `test_<db>` остались от прогона,
убитого без уборки
- **WHEN** тестовый контейнер, база `test_<db>` или объекты под
префиксом `test_<db>/` остались от прогона, убитого без уборки
- **THEN** следующий `make test_isolated` удаляет их и начинает заново
#### Scenario: Сохранить базу для разбора
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
- **THEN** после прогона тестовый контейнер удалён, база `test_<db>`
остаётся, а команда печатает её имя
- **THEN** после прогона тестовый контейнер удалён, база `test_<db>` и
объекты под префиксом `test_<db>/` остаются, а команда печатает имя
базы и префикс
### Requirement: Проверки отказов на отдельном стенде
@@ -310,7 +324,8 @@ Valkey отделены от рабочих именем базы в ключе
запросе с токеном»;
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны»;
- `health`: «Хранилище не готово», «Кэш недоступен»;
- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище
объектов недоступно»;
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
«Очистка кэша»;
- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке»,
@@ -318,25 +333,26 @@ Valkey отделены от рабочих именем базы в ключе
Команда SHALL:
- собрать образ из рабочего дерева;
- поднять отдельный стенд со своими PostgreSQL и Valkey, применить
миграции;
- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить
миграции и bootstrap S3;
- запустить два API: с настройками по умолчанию и «тесный» — с
коротким сроком сессии и ключа идемпотентности и пулом из одного
соединения;
- выполнить проверки отказов;
- удалить стенд вместе с его данными при любом исходе.
Порты PostgreSQL и Valkey этого стенда MUST NOT публиковаться на хосте,
API — только на `127.0.0.1`. Рабочий стенд, его база, кэш и контейнеры
MUST NOT затрагиваться. Код выхода SHALL быть ненулевым, если не прошла
хотя бы одна проверка или уборка. Параллельный запуск двух прогонов не
поддерживается: уборка хвоста в начале второго удаляет стенд первого.
Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на
хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш,
хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода
SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка.
Параллельный запуск двух прогонов не поддерживается: уборка хвоста в
начале второго удаляет стенд первого.
#### Scenario: Успешный прогон
- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks`
- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и
volume стенда отказов после команды нет, а у контейнеров рабочего
volumes стенда отказов после команды нет, а у контейнеров рабочего
стенда прежнее время старта, и рабочий API отвечает
#### Scenario: Упавшая проверка
@@ -348,11 +364,11 @@ MUST NOT затрагиваться. Код выхода SHALL быть нену
#### Scenario: Прерывание
- **WHEN** `make failure_checks` прерван Ctrl+C
- **THEN** стенд отказов остановлен и удалён вместе с volume
- **THEN** стенд отказов остановлен и удалён вместе с volumes
#### Scenario: Хвост прошлого прогона
- **WHEN** контейнеры или volume стенда отказов остались от прогона,
- **WHEN** контейнеры или volumes стенда отказов остались от прогона,
убитого без уборки
- **THEN** следующий `make failure_checks` удаляет их и начинает заново