docs: archive s3-storage and sync its specs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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 одновременных загрузок: пик памяти ограничен, механизм объяснён |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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` без секрета
|
||||
@@ -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 задаваться параметром приложения
|
||||
|
||||
@@ -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`,
|
||||
|
||||
@@ -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` удаляет их и начинает заново
|
||||
|
||||
|
||||
Reference in New Issue
Block a user