diff --git a/AGENTS.md b/AGENTS.md index a8c8dab9..85a4d31e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/PLAN.md b/PLAN.md index 244ef593..ba0664ae 100644 --- a/PLAN.md +++ b/PLAN.md @@ -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 одновременных загрузок: пик памяти ограничен, механизм объяснён | diff --git a/openspec/changes/s3-storage/.openspec.yaml b/openspec/changes/archive/2026-10-20-s3-storage/.openspec.yaml similarity index 100% rename from openspec/changes/s3-storage/.openspec.yaml rename to openspec/changes/archive/2026-10-20-s3-storage/.openspec.yaml diff --git a/openspec/changes/s3-storage/design.md b/openspec/changes/archive/2026-10-20-s3-storage/design.md similarity index 100% rename from openspec/changes/s3-storage/design.md rename to openspec/changes/archive/2026-10-20-s3-storage/design.md diff --git a/openspec/changes/s3-storage/proposal.md b/openspec/changes/archive/2026-10-20-s3-storage/proposal.md similarity index 100% rename from openspec/changes/s3-storage/proposal.md rename to openspec/changes/archive/2026-10-20-s3-storage/proposal.md diff --git a/openspec/changes/s3-storage/specs/container-run/spec.md b/openspec/changes/archive/2026-10-20-s3-storage/specs/container-run/spec.md similarity index 100% rename from openspec/changes/s3-storage/specs/container-run/spec.md rename to openspec/changes/archive/2026-10-20-s3-storage/specs/container-run/spec.md diff --git a/openspec/changes/s3-storage/specs/health/spec.md b/openspec/changes/archive/2026-10-20-s3-storage/specs/health/spec.md similarity index 100% rename from openspec/changes/s3-storage/specs/health/spec.md rename to openspec/changes/archive/2026-10-20-s3-storage/specs/health/spec.md diff --git a/openspec/changes/s3-storage/specs/object-storage/spec.md b/openspec/changes/archive/2026-10-20-s3-storage/specs/object-storage/spec.md similarity index 100% rename from openspec/changes/s3-storage/specs/object-storage/spec.md rename to openspec/changes/archive/2026-10-20-s3-storage/specs/object-storage/spec.md diff --git a/openspec/changes/s3-storage/specs/service-configuration/spec.md b/openspec/changes/archive/2026-10-20-s3-storage/specs/service-configuration/spec.md similarity index 100% rename from openspec/changes/s3-storage/specs/service-configuration/spec.md rename to openspec/changes/archive/2026-10-20-s3-storage/specs/service-configuration/spec.md diff --git a/openspec/changes/s3-storage/specs/service-logging/spec.md b/openspec/changes/archive/2026-10-20-s3-storage/specs/service-logging/spec.md similarity index 100% rename from openspec/changes/s3-storage/specs/service-logging/spec.md rename to openspec/changes/archive/2026-10-20-s3-storage/specs/service-logging/spec.md diff --git a/openspec/changes/s3-storage/specs/student-tests/spec.md b/openspec/changes/archive/2026-10-20-s3-storage/specs/student-tests/spec.md similarity index 100% rename from openspec/changes/s3-storage/specs/student-tests/spec.md rename to openspec/changes/archive/2026-10-20-s3-storage/specs/student-tests/spec.md diff --git a/openspec/changes/s3-storage/tasks.md b/openspec/changes/archive/2026-10-20-s3-storage/tasks.md similarity index 100% rename from openspec/changes/s3-storage/tasks.md rename to openspec/changes/archive/2026-10-20-s3-storage/tasks.md diff --git a/openspec/specs/container-run/spec.md b/openspec/specs/container-run/spec.md index c6ef55ac..0b5dd396 100644 --- a/openspec/specs/container-run/spec.md +++ b/openspec/specs/container-run/spec.md @@ -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 diff --git a/openspec/specs/object-storage/spec.md b/openspec/specs/object-storage/spec.md new file mode 100644 index 00000000..e035724a --- /dev/null +++ b/openspec/specs/object-storage/spec.md @@ -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` без секрета diff --git a/openspec/specs/service-configuration/spec.md b/openspec/specs/service-configuration/spec.md index 9998fc7f..d61f7535 100644 --- a/openspec/specs/service-configuration/spec.md +++ b/openspec/specs/service-configuration/spec.md @@ -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 задаваться параметром приложения diff --git a/openspec/specs/service-logging/spec.md b/openspec/specs/service-logging/spec.md index dd6b4df0..eeea1372 100644 --- a/openspec/specs/service-logging/spec.md +++ b/openspec/specs/service-logging/spec.md @@ -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`, diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index 939c5366..3d74ac40 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -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_/`. + +Это один процесс 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_`, ни тестового контейнера после - команды нет, число строк в таблицах рабочей базы не изменилось, а + код выхода 0, ни базы `test_`, ни тестового контейнера, ни + объектов под префиксом `test_/` после команды нет, число строк в + таблицах рабочей базы и объекты рабочей базы не изменились, а рабочий стенд продолжает отвечать через балансировщик #### Scenario: Упавшие тесты - **WHEN** во время `make test_isolated` падает хотя бы один тест - **THEN** код выхода ненулевой, журнал тестового контейнера выведен, - контейнер удалён, база `test_` удалена + контейнер удалён, база `test_` и объекты под префиксом + `test_/` удалены #### Scenario: Прерывание - **WHEN** `make test_isolated` прерван Ctrl+C -- **THEN** тестовый контейнер остановлен и удалён, база `test_` - удалена +- **THEN** тестовый контейнер остановлен и удалён, база `test_` и + объекты под префиксом `test_/` удалены #### Scenario: Хвост прошлого прогона -- **WHEN** тестовый контейнер или база `test_` остались от прогона, - убитого без уборки +- **WHEN** тестовый контейнер, база `test_` или объекты под + префиксом `test_/` остались от прогона, убитого без уборки - **THEN** следующий `make test_isolated` удаляет их и начинает заново #### Scenario: Сохранить базу для разбора - **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1` -- **THEN** после прогона тестовый контейнер удалён, база `test_` - остаётся, а команда печатает её имя +- **THEN** после прогона тестовый контейнер удалён, база `test_` и + объекты под префиксом `test_/` остаются, а команда печатает имя + базы и префикс ### 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` удаляет их и начинает заново