From 7d340c067334af94eaa61258ea05f525cf1d346f Mon Sep 17 00:00:00 2001 From: roman Date: Tue, 20 Oct 2026 20:31:35 +0300 Subject: [PATCH] docs: add s3-storage evidence and report - evidence/s3: bootstrap, privacy (make s3_check), gRPC without token, restart and SIGKILL, client failures, memory of 20 concurrent uploads - evidence/tests: failure_checks with own S3, test_isolated prefix cleanup (red tests: no attachment_ids until attachments) - REPORT.md: S3 role, services table, bootstrap, readiness dependencies, skeleton S3_* names, evidence rows, limitations - refine expected-red counts in tasks, design and PLAN Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 3 +- PLAN.md | 18 +- REPORT.md | 191 ++++++++++++++++++++- evidence/s3/bootstrap.md | 143 +++++++++++++++ evidence/s3/client.md | 97 +++++++++++ evidence/s3/grpc-admin.md | 47 +++++ evidence/s3/memory.md | 50 ++++++ evidence/s3/privacy.md | 185 ++++++++++++++++++++ evidence/s3/restart.md | 85 +++++++++ evidence/tests/failure-checks.md | 90 ++++++++++ evidence/tests/test-isolated-s3-cleanup.md | 85 +++++++++ openspec/changes/s3-storage/design.md | 7 +- openspec/changes/s3-storage/tasks.md | 11 +- 13 files changed, 997 insertions(+), 15 deletions(-) create mode 100644 evidence/s3/bootstrap.md create mode 100644 evidence/s3/client.md create mode 100644 evidence/s3/grpc-admin.md create mode 100644 evidence/s3/memory.md create mode 100644 evidence/s3/privacy.md create mode 100644 evidence/s3/restart.md create mode 100644 evidence/tests/failure-checks.md create mode 100644 evidence/tests/test-isolated-s3-cleanup.md diff --git a/AGENTS.md b/AGENTS.md index fa3c7a93..6e3e30fb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -397,11 +397,12 @@ Dockerfile # builder (uv sync --locked) → runtime: .venv + s docker-compose.yml # проект mtusi-lab4: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), migrate, s3-bootstrap, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env) .dockerignore config_example.toml, .env.example +evidence/s3/ # change s3-storage: bootstrap.md (первый запуск, повтор, смена секрета, ошибка шага, до bootstrap), privacy.md (make s3_check, нарушение и исправление, порты, секреты по сервисам), grpc-admin.md (gRPC шлюза без токена), restart.md (restart.sh и SIGKILL S3), client.md (операции, pause/stop, неверный секрет, журнал), memory.md (20 × 10 MiB PUT) evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга evidence/migrations/ # миграции с нуля и повторно, ошибка миграции evidence/auth/ # passwords-and-tokens.md — driver.py auth-storage на стенде текущей лабы: Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump (исключения сверки покрытия) evidence/cache/ # hits.md — make test_isolated + driver.py cache-check на стенде текущей лабы: одно чтение chats на 50 через LB, TTL, ключи двух баз (исключения сверки покрытия) -evidence/tests/ # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md; profile-resources-checks.md — проверки сэмплера, быстрые профили, сторож, хост и сравнение меток resources с baseline; fix-known-issues-checks.md — сверка событий поток/буфер, красный и зелёный failure_checks, консоль, сверка ссылок исключений, регрессия; strict-id-validation-checks.md — красный и зелёный прогоны курсора и UUID на входе, пересмотр проверки курсора, замена реплик, клон во временном проекте +evidence/tests/ # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md; лаба 4: failure-checks.md (стенд отказов со своим S3, новая проверка готовности без S3), test-isolated-s3-cleanup.md (уборка префикса test_/) — до attachments с ожидаемо красными тестами схемы Message; лаба 3 (в этом репозитории пока нет): profile-resources-checks.md — проверки сэмплера, быстрые профили, сторож, хост и сравнение меток resources с baseline; fix-known-issues-checks.md — сверка событий поток/буфер, красный и зелёный failure_checks, консоль, сверка ссылок исключений, регрессия; strict-id-validation-checks.md — красный и зелёный прогоны курсора и UUID на входе, пересмотр проверки курсора, замена реплик, клон во временном проекте evidence/idempotency/ # повтор, 409, гонка, таблица ключей, X-Instance-Id evidence/replicas/ # стенд с LB: порты, лимиты и их цена для Argon2id, окружение, распределение, ответы LB (нет реплик, зависшая, без PostgreSQL), test-persistence, чистый clone на нестандартных портах evidence/failover/ # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh; замер обнаружения, keep-alive, зависшая реплика и ключ; stop-at-start.md — docker stop стартующей реплики «до/после» раннего обработчика и ветка сбоя rolling-update.sh diff --git a/PLAN.md b/PLAN.md index bb3c3858..e2cf3e11 100644 --- a/PLAN.md +++ b/PLAN.md @@ -533,8 +533,9 @@ design) и «Вопросы» (ждут ответа; ответ дописыв ключи в botocore передаются всегда, даже пустые. 15. **Ожидаемо красные шире списка tasks**: контракт лабы 4 требует `attachment_ids` в `Message`, код лабы 3 его не отдаёт — до - `attachments` красные 30 тестов (и 2 ошибки) `make student_test` и - 5 проверок `make failure_checks`. От S3 не зависит. + `attachments` красные 32 теста (и 2 ошибки) `make student_test` + через LB (в `make test_isolated` — 29 и 2) и 5 проверок `make + failure_checks`. От S3 не зависит. 16. **Дельта `health` синхронизирована в основной спек в apply**, как в `scaling-bench`: иначе маркер нового сценария — ссылка на неизвестный сценарий в сверке покрытия. @@ -560,3 +561,16 @@ design) и «Вопросы» (ждут ответа; ответ дописыв `.env.example` вместе с секретами S3, переносить нечего. Для уже существующего `.env` остаётся (а), как в design; (в) — только по просьбе пользователя. +2. `attachment_ids` отсутствует в ответах Message (код лабы 3), и + поэтому до change `attachments` красные 32 теста `make student_test` + и 5 тестов `make failure_checks` (решение 15). Добавлять ли пустой + список раньше? + + **Ответ пользователя 2026-10-20:** нет, красное до `attachments`. + Поле приходит целиком в `attachments` (запрос, ответ, хэш + идемпотентности), там же evidence тестов переснимается зелёным. +3. Когда чинить `rollout_from c50b721` (решение 17, `KNOWN_ISSUES.md`)? + + **Ответ пользователя 2026-10-20:** в change `attachments`: он + добавляет миграцию, и rollout со старого образа на новую схему — нужное + evidence. До тех пор запись остаётся в `KNOWN_ISSUES.md`. diff --git a/REPORT.md b/REPORT.md index 9ad2b84f..35a45c2b 100644 --- a/REPORT.md +++ b/REPORT.md @@ -9,17 +9,174 @@ TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +### S3 (change `s3-storage`) + +`make env_setup` создаёт новый `.env` из `.env.example` со случайными +паролями PostgreSQL и Valkey и пятью секретами S3 и печатает только их +имена. Существующий `.env` он не трогает. + +**Шаг оператора для `.env`, созданного до change `s3-storage`.** +Перенесите блок S3 из `.env.example` руками. Пять пустых секретов +(`S3_ROOT_ACCESS_KEY`, `S3_ROOT_SECRET_KEY`, `S3_JWT_SIGNING_KEY`, +`S3_API_ACCESS_KEY`, `S3_API_SECRET_KEY`) заполните значениями `openssl +rand -hex 32`. Без них любая команда compose останавливается с +сообщением «… is empty, copy S3 lines from .env.example». + +- `make run_docker`. Порядок старта: + - postgres, valkey и s3 до `healthy`; + - одноразовые `migrate` и `s3-bootstrap` (приватный bucket, + пользователь API, проверки приватности); + - `api` × 2 после успешного завершения обоих; + - haproxy на `127.0.0.1:8080`. + + Проверки — `make test`, `make student_test`, `make s3_check`. +- `make run_dev`. Цепочка `make upgrade`, `make start_cache` и `make + start_s3`: `up -d --wait s3`, затем `up --no-deps --exit-code-from + s3-bootstrap s3-bootstrap`, код bootstrap — код цели. Затем сервис на + `127.0.0.1:8080`. В консоли S3 доступен на `127.0.0.1:8334`. +- `make stop` останавливает S3 плавно, ~15 с. `make down` volumes не + трогает. +- `make wipe_data` удаляет volumes `mtusi-lab4_postgres_data` и + `mtusi-lab4_s3_data` только после ввода `yes`, оба тома запрос + называет по имени. + ## Архитектура и решения TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +клиент → 127.0.0.1:8080 → haproxy → api × 2 → postgres (метаданные, сессии, ключи идемпотентности) + → valkey (кэш карточек чатов) + → s3 (байты вложений; SeaweedFS, приватный bucket) + migrate (один раз) ──→ postgres + s3-bootstrap (один раз, в сетевом пространстве s3) ──→ s3 +``` + +### Роль S3 и её граница + +S3 хранит только байты вложений, метаданные лежат в PostgreSQL. Пишет и +читает S3 только API своим ключом. Ручки вложений, `attachment_ids`, +компенсация и уборщик — следующие changes (`attachments`, +`upload-consistency`, `upload-memory`). Change `s3-storage` даёт сервер, +bootstrap, клиент `src/infra/s3/` и стенды. + +Сервер — SeaweedFS 4.48. Выбор и проба — `PLAN.md` (решение 1) и +design change `s3-storage`. Три места, где SeaweedFS по умолчанию не +приватен, закрыты: +- без учётных записей S3 открыт анониму — административная пара задана + в окружении сервера с первого старта; +- master, filer и volume слушают все интерфейсы — `-ip.bind=127.0.0.1`; +- gRPC шлюза без ключа подписи принимает учётную запись администратора + — ключ подписи обязателен. + +Телеметрия, Iceberg, Lance и встроенный IAM API выключены. + +### Сервисы стенда + +| Роль | Сервис | Версия / digest индекса | Health / readiness | Volume | Сеть / порт | Credentials | +| --- | --- | --- | --- | --- | --- | --- | +| load_balancer | `haproxy` | `haproxy:3.4.6-trixie@sha256:e2739156…db26` | `/lb/ready` на `:8404` изнутри: есть готовая реплика | — | `127.0.0.1:8080` → `8080`; `:8404` только в сети | нет | +| api × 2 | `api` | образ из `Dockerfile`, база `python:3.12.14-slim-trixie@sha256:f77ac9e4…e51f` | HEALTHCHECK образа: `/health/ready` | — (`config.toml` read-only) | `8080` только в сети | пароли PostgreSQL и Valkey, ключи пользователя API в S3 — мосты `DATABASE__PASSWORD`, `CACHE__PASSWORD`, `S3__ACCESS_KEY_ID`, `S3__SECRET_ACCESS_KEY` из `.env` | +| миграции | `migrate` | образ API | код выхода 0 (`service_completed_successfully`) | — | сеть | пароль PostgreSQL | +| postgres | `postgres` | `postgres:18.6-trixie@sha256:5a5a84b1…9722` | `pg_isready -h 127.0.0.1` | `postgres_data` | `127.0.0.1:5433` → `5432` | `POSTGRES_PASSWORD` | +| кэш (необязательная роль) | `valkey` | `valkey/valkey:9.1.2-trixie@sha256:418652cf…9dfd` | `valkey-cli ping` с паролем | — (persistence выключен) | `127.0.0.1:6380` → `6379` | `VALKEY_PASSWORD` | +| s3 | `s3` | `chrislusf/seaweedfs:4.48@sha256:4e61d15f…7872d` | `wget`: `/cluster/healthz` master, `/healthz` filer и шлюза (loopback) | `s3_data:/data` | `127.0.0.1:8334` → `8333` (только API S3); в сети — `8333` и gRPC шлюза `18333`, служебные порты на loopback | административная пара (`AWS_*` из `S3_ROOT_*`) и ключ подписи (`WEED_JWT_FILER_SIGNING_KEY` из `S3_JWT_SIGNING_KEY`) — окружением | +| bootstrap S3 | `s3-bootstrap` | тот же образ S3 | код выхода 0; реплики ждут `service_completed_successfully` | — (`/tmp` — tmpfs) | `network_mode: service:s3`, портов нет | ключ подписи и ключи API — окружением; в `weed shell` через stdin, в `curl` файлом на tmpfs | + +Лимиты: +- postgres 2 CPU / 1 ГБ, valkey 0,5 / 128 МБ, s3 1 / 512 МБ; +- `s3-bootstrap` 0,5 / 128 МБ, `migrate` 0,5 / 256 МБ; +- `api` 1 / 512 МБ на реплику, haproxy 1 / 256 МБ. + +Сумма — 7,5 CPU / 3,25 ГиБ, без одноразовых сервисов — 6,5 CPU / +2,9 ГиБ. Секреты по сервисам проверены в `evidence/s3/privacy.md` +(раздел 4). + +### Bootstrap S3 и его безопасный повтор + +Сервис `s3-bootstrap` выполняет `infra/s3/bootstrap.sh` в режиме +`apply`. Каждый шаг можно повторять: + +1. Bucket: есть — «exists», нет — создаётся. +2. Анонимный доступ — `none`. Если он открыт, bootstrap его закрывает. +3. Политика `api-objects` (`s3:GetObject`, `s3:PutObject`, + `s3:DeleteObject` на `arn:aws:s3:::/*`) создаётся или + обновляется. +4. Пользователь `api`: если его нет, создаётся с ключами из `.env`; + политика привязывается. +5. Чужие ключи пользователя удаляются, нужный создаётся, если его нет. +6. Проверка ключом API: PUT, GET и DELETE проверочного объекта. + `SignatureDoesNotMatch` значит, что секрет в `.env` сменился, — + ключ пересоздаётся. +7. Проверки приватности: ключ API получает 403 на список и создание + bucket, аноним — 403 на чтение и список. Расхождение — `FAILED: + <шаг>`, код 1, реплики не стартуют. + +Повтор не меняет правильное состояние: bucket и объекты сохраняются, +пользователь не пересоздаётся (`evidence/s3/bootstrap.md`, раздел 2). + +Смена секрета API: новое значение в `.env`, затем `make run_docker`. +Bootstrap пересоздаёт ключ, прежний секрет перестаёт действовать +(раздел 3), а реплики с новым окружением пересоздаёт compose. + +Bootstrap работает не административной парой S3, а `weed shell` на +loopback сервера с ключом подписи. Административная пара есть только у +сервера. `make rolling_update` bootstrap не запускает: он, как +миграции, только расширяет права. Его изменения применяет `docker +compose up -d s3-bootstrap` или `make run_docker`. + +### Критичные и некритичные зависимости готовности + +- PostgreSQL **критичен**: в нём источник истины и сессии. + `/health/ready` выполняет `SELECT 1` со сроком 2 с, без него — 503. +- Valkey **не критичен**: это кэш, без него обязательные запросы идут в + PostgreSQL. +- S3 **не критичен**: без него недоступны только пути вложений (503 + `unavailable`), текст работает. `/health/ready` к S3 не обращается: + иначе отказ S3 вывел бы из LB все реплики, и текст перестал бы + работать тоже. Проверка — `test_readiness_without_object_storage` в + `make failure_checks`. + +### Соответствие имён skeleton `S3_*` + +| Имя `.env.example` skeleton | Реальная конфигурация | +| --- | --- | +| `S3_ENDPOINT` | `S3__HOST` и `S3__PORT`: в консоли — мосты `127.0.0.1` и `${S3_OUT_PORT}`, в docker — `S3_HOST` и `S3_PORT` через `x-s3-env` | +| `S3_REGION` | `[s3] region` в `config.toml` (`us-east-1`, нужен подписи SigV4) | +| `S3_BUCKET` | `S3__BUCKET` в `.env`: читают приложение и bootstrap | +| `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` | мосты `S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY}` и `S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY}`: значения из `.env`, а не файлы, как с `DATABASE_URL_FILE` | +| `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | change `attachments` | + ## Доказательства критериев +Строки S3 (change `s3-storage`) сняты с commit `2e997f9` на стенде `make +run_docker`, если не сказано иное. + +**До change `attachments` красные:** +- публичный smoke, `make test-persistence` и `make test-failover`: они + загружают вложение; +- тесты схемы `Message` в `make student_test` и `make failure_checks` — + список уточнён в шапке `tasks.md` change `s3-storage`. + +Причина одна: контракт лабы 4 требует `attachment_ids`, а код лабы 3 его +не отдаёт. Чинит change `attachments` (ответ пользователя 2026-10-20, +`PLAN.md`). Строки про вложения появятся с ним. + | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | +| Публичный smoke | make test | TODO после `attachments`; сейчас `FAIL: response: missing required fields` (нет `attachment_ids`) | `evidence/tests/test-isolated-s3-cleanup.md` | +| «3»: S3-сервер в общем стенде, закреплённая версия | `make run_docker`, `docker compose ps` | `s3` на `chrislusf/seaweedfs:4.48@sha256:…` в состоянии `healthy`, `s3-bootstrap` — `Exited (0)`, реплики стартуют после него | `evidence/s3/privacy.md` (раздел 3), `evidence/s3/bootstrap.md` (раздел 1) | +| «3»: persistent volume S3 | `scripts/restart.sh`; `docker kill -s KILL` сервера S3 | ID контейнеров прежние, `StartedAt` новый, hook — 25 с; объекты клиента читаются с тем же SHA-256: 3/3 после рестарта, 20/20 после SIGKILL | `evidence/s3/restart.md` | +| «3»: создание приватного bucket описано | `docker compose logs s3-bootstrap` на пустом volume | «bucket messenger created», «user api created», «checks passed» | `evidence/s3/bootstrap.md` (раздел 1), «Архитектура и решения» → «Bootstrap S3» | +| «4»: bootstrap идемпотентен | `docker compose run --rm s3-bootstrap` дважды; повтор с новым секретом; `S3_BUCKET=Bad_Bucket` | повтор — «exists», код 0, объекты на месте; новый секрет работает, прежний — 503; ошибка — код 1, «FAILED: bucket create», реплики не стартуют | `evidence/s3/bootstrap.md` | +| «4»: отдельные ограниченные credentials API | `make s3_check` (строки `api key …`); секреты по сервисам из `docker compose config` | ключ API: объекты своего bucket — 200 / 204; список, bucket, политика, ACL, чужой bucket — 403; административной пары у API нет | `evidence/s3/privacy.md` (разделы 1, 4) | +| «4»: административная консоль не в общей сети | `nc -z` из сети стенда (`make s3_check`); `docker port`; gRPC без токена | открыты только 8333 и 18333; master, filer, volume и admin UI закрыты; на хосте — только `127.0.0.1:8334`; `PutIdentity` без токена — `UNAUTHENTICATED` | `evidence/s3/privacy.md`, `evidence/s3/grpc-admin.md` | +| «4»: проверка private bucket вне API | `make s3_check`; затем открыть чтение `s3.anonymous.set -access Read` | 52 проверки, код 0; после открытия чтения — 10 FAIL с названиями; следующий bootstrap закрывает доступ, снова PASS | `evidence/s3/privacy.md` | +| «4»: S3 недоступен — ограниченная ошибка, текст работает | `make failure_checks` (`test_readiness_without_object_storage`); клиент при `pause` и `stop` S3 | без S3 `/health/ready` и `/health/live` — 200 быстрее 1 с; вызов клиента — 503 за 8 мс (`stop`) или за срок 5 с (`pause`), после возврата проходит | `evidence/tests/failure-checks.md`, `evidence/s3/client.md` | +| «4»: память S3 при одновременных загрузках | 20 одновременных PUT по 10 MiB ключом API | все подтверждены, анонимная память не больше 379 MiB из 512, OOM нет; подбор лимитов API — `upload-memory` | `evidence/s3/memory.md` | +| Логи без секретов S3 | `grep -F` значений секретов по журналу клиента и `make run_dev` | 0 совпадений; отказ в учётных данных — одна запись `error` без секрета | `evidence/s3/client.md` | +| Остальные пункты уровня 3 | TODO (`attachments`) | TODO | TODO | +| Все пункты уровня 4, если заявлен | TODO (`attachments`, `upload-consistency`, `upload-memory`) | TODO | TODO | | Выбранный трек 5, если заявлен | TODO | TODO | TODO | TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. @@ -30,8 +187,34 @@ TODO: гипотеза, hardware/лимиты, версии, объём данн | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `docker pause` сервера S3 | вызов клиента — 503 не позже срока 5 с | 5 007–5 008 мс, `TimeoutError` → 503, без повторов | после `unpause` следующий вызов — 9 мс; потерь нет | +| `docker compose stop s3` | плавная остановка без SIGKILL; вызовы — 503 сразу | остановка 15,6 с, код 0; вызов — 503 за 2–8 мс | после `start` первый вызов тем же клиентом проходит | +| SIGKILL сервера S3 сразу после 20 подтверждённых PUT | подтверждённое не теряется | 20/20 с тем же SHA-256 | `healthy` через 3 с; потерь нет | +| `scripts/restart.sh` | все хранилища и реплики перезапущены, данные целы | 25 с; bootstrap — «exists»; 3/3 объекта с тем же SHA-256 | — | +| Неверный секрет API у приложения | 503 и запись `error` без секрета | `SignatureDoesNotMatch` → 503, одна запись `error` | — | +| 20 одновременных PUT по 10 MiB | без OOM | анонимная память не больше 379 MiB; последний PUT подтверждён через 7,2 с (очередь лимита загрузок 64 МБ) | — | ## Ограничения и следующие шаги TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. + +S3 (change `s3-storage`): +- **Одна нода S3 без репликации и fsync.** SIGKILL процесса + подтверждённых объектов не теряет (`evidence/s3/restart.md`). Отказ + диска или ВМ теряет объекты, и запись, подтверждённая перед падением + ВМ, может пропасть. Учебное упрощение, как один PostgreSQL. +- **Плавная остановка SeaweedFS ~15 с**: срок зашит в filer. Поэтому + `stop_grace_period: 20s`, а `make stop` и `scripts/restart.sh` дольше + на ~15 с. На стенде отказов — 2 с: там проверяется отказ. +- **gRPC шлюза открыт в сети стенда**: отдельно его не закрыть, он + защищён ключом подписи (`evidence/s3/grpc-admin.md`). +- **Секреты S3 видны в `docker inspect`** контейнеров `s3` и + `s3-bootstrap`, как `POSTGRES_PASSWORD`. Стенд локальный, порты только + на `127.0.0.1`. TLS — лаба 7. +- **Лимит загрузок шлюза ставит запросы в очередь.** 20 одновременных + загрузок по 10 MiB заканчиваются через 7,2 с, это больше срока вызова + клиента (5 с). Подбор лимитов и сроков — change `upload-memory`. +- **Отказ S3 — 503 на путях вложений, а не отказ сервиса.** Отказ хоста, + LB и PostgreSQL стенд не переживает (`.claude/rules/balancer.md`). +- **Профиль `rollout` стенда `bench/` ссылается на commit лабы 3** + (`KNOWN_ISSUES.md`), чинится в change `attachments`. diff --git a/evidence/s3/bootstrap.md b/evidence/s3/bootstrap.md new file mode 100644 index 00000000..b2683c9b --- /dev/null +++ b/evidence/s3/bootstrap.md @@ -0,0 +1,143 @@ +# Bootstrap S3: первый запуск, повтор, смена секрета, ошибка шага + +- Дата: 2026-10-20, 17:19–17:21 UTC. +- Commit: `2e997f9`. +- Стенд: временный проект compose `mtusi-lab4-s3fresh` с тем же + `docker-compose.yml` и `.env`, на новых volumes. Внешние порты сдвинуты + окружением: `APP_OUT_PORT=18180`, `POSTGRES_OUT_PORT=15433`, + `VALKEY_OUT_PORT=16380`, `S3_OUT_PORT=18334`. Рабочий стенд + `mtusi-lab4` в это время работал и не затрагивался. +- Docker Desktop 29.8.2, compose 5.5.1, Apple M3 Pro. +- Спек `object-storage`: «Приватный bucket создаёт bootstrap» (первый + и повторный запуск, новый секрет API, ошибка), «Запрет анонимного + доступа» («До bootstrap»); `container-run`: «Bootstrap S3 один раз». + Design change `s3-storage`, решения 3–4. + +## 1. Первый запуск на пустых volumes + +``` +$ docker compose -p mtusi-lab4-s3fresh up -d (fresh volumes, ports shifted) +up -d exit=0 in 9 s +LB ready after 12 s +mtusi-lab4-s3fresh_postgres_data +mtusi-lab4-s3fresh_s3_data +s3 started 2026-10-20T17:19:25.999144958Z finished 0001-01-01T00:00:00Z exit 0 +s3-bootstrap started 2026-10-20T17:19:30.649598544Z finished 2026-10-20T17:19:34.176309754Z exit 0 +migrate started 2026-10-20T17:19:28.497465917Z finished 2026-10-20T17:19:30.952969252Z exit 0 +api started 2026-10-20T17:19:34.36139567Z finished 0001-01-01T00:00:00Z exit 0 +api started 2026-10-20T17:19:34.259315212Z finished 0001-01-01T00:00:00Z exit 0 +haproxy started 2026-10-20T17:19:34.481840962Z finished 0001-01-01T00:00:00Z exit 0 +$ docker compose logs -t s3-bootstrap +2026-10-20T17:19:31.154643710Z s3-bootstrap: bucket messenger created +2026-10-20T17:19:32.245046586Z s3-bootstrap: user api created +2026-10-20T17:19:34.173270295Z s3-bootstrap: checks passed (api key put/get/delete; api key list and bucket create, anonymous get and list denied) +``` + +- Сервер `s3` стал `healthy` за 4,7 с (`s3` started → `s3-bootstrap` + started). +- Bootstrap занял 3,5 с, из них ~1,9 с — проверка: первая запись после + старта сервера ждёт регистрации тома (design, Context). +- Реплики `api` стартовали через 0,1 с после завершения bootstrap + (17:19:34.176 → 17:19:34.259). Bootstrap прошёл один раз, на свой + прогон. + +## 2. Повторный запуск дважды: ничего не меняет + +Перед повтором клиент приложения записал 3 объекта, после — прочитал их. +Скрипт `persist_probe.py` (scratchpad): клиент `src/infra/s3`, +`S3__PORT=18334`. + +``` +$ persist_probe.py write 3 (S3__PORT=18334) +written and confirmed: 3 objects +$ docker compose run --rm s3-bootstrap # repeat 1 +s3-bootstrap: bucket messenger exists +s3-bootstrap: user api exists +s3-bootstrap: checks passed (api key put/get/delete; api key list and bucket create, anonymous get and list denied) +exit=0, 2.9 s +$ docker compose run --rm s3-bootstrap # repeat 2 +s3-bootstrap: bucket messenger exists +s3-bootstrap: user api exists +s3-bootstrap: checks passed (api key put/get/delete; api key list and bucket create, anonymous get and list denied) +exit=0, 2.9 s +$ persist_probe.py verify +read back with the same SHA-256: 3/3; deleted +``` + +## 3. Новый секрет API: прежний перестаёт действовать + +Новый секрет — случайный hex в переменной shell, разовый `run -e`. +Проверка — один PUT и DELETE клиентом приложения: с секретом из `.env` +(«old») и с новым (окружение `S3__SECRET_ACCESS_KEY`). Скрипт +`put_once.py`, значения не печатаются. + +``` +$ docker compose run --rm -e S3_API_SECRET_KEY= s3-bootstrap +s3-bootstrap: bucket messenger exists +s3-bootstrap: user api exists +s3-bootstrap: key of api recreated (secret changed) +s3-bootstrap: checks passed (api key put/get/delete; api key list and bucket create, anonymous get and list denied) +exit=0 +old secret (.env): ObjectStorageUnavailable (503) +new secret: PUT and DELETE ok +$ docker compose run --rm s3-bootstrap # back to the .env secret +s3-bootstrap: bucket messenger exists +s3-bootstrap: user api exists +s3-bootstrap: key of api recreated (secret changed) +s3-bootstrap: checks passed (api key put/get/delete; api key list and bucket create, anonymous get and list denied) +exit=0 +old secret (.env): PUT and DELETE ok +new secret: ObjectStorageUnavailable (503) +``` + +Смену секрета bootstrap распознаёт по ответу `SignatureDoesNotMatch` +своей проверки: ключ есть, секрет другой. Тогда он пересоздаёт ключ, +пользователь и политика остаются. + +## 4. Ошибка шага: код 1, шаг назван, реплики не стартуют + +``` +$ docker compose run --rm -e S3_BUCKET=Bad_Bucket s3-bootstrap +s3-bootstrap: error: bucket name can only contain lower case characters, numbers, dots, and hyphens +s3-bootstrap: FAILED: bucket create +exit=1 +``` + +Реплики удалены (`rm -sf api haproxy`), затем стенд поднят с +недопустимым именем bucket: + +``` +api containers before: 0 +$ S3__BUCKET=Bad_Bucket docker compose up -d api + Container mtusi-lab4-s3fresh-s3-bootstrap-1 Error service "s3-bootstrap" didn't complete successfully: exit 1 +service "s3-bootstrap" didn't complete successfully: exit 1 +exit=1 +api containers after: 2 created, 0 running +s3-bootstrap: error: bucket name can only contain lower case characters, numbers, dots, and hyphens +s3-bootstrap: FAILED: bucket create +``` + +Секретов в выводе нет: `weed shell` получает их через stdin, `curl` — +файлом на tmpfs. Вывод команд с секретами bootstrap не печатает. + +Затем `docker compose -p mtusi-lab4-s3fresh down --remove-orphans`: +контейнеры и сеть удалены. Volumes `mtusi-lab4-s3fresh_postgres_data` и +`mtusi-lab4-s3fresh_s3_data` остались: удалить их агенту не разрешено, +это сделает пользователь (`docker volume rm`). + +## 5. До bootstrap анонимного окна нет + +Одноразовый сервер (`docker run --rm`, анонимный volume, в сеть не +подключён) с теми же аргументами `weed server`, что у сервиса `s3`, и +случайной административной парой. Bootstrap не запускался: + +``` +healthy after ~4 s, bootstrap not run +anonymous create bucket: 403 +anonymous put object: 403 +anonymous list buckets: 403 +``` + +`s3.bucket.list` — bucket `messenger` не создан. Без административной +пары в окружении сервер открыт анониму целиком (design, Context), поэтому +она задана с первого старта. diff --git a/evidence/s3/client.md b/evidence/s3/client.md new file mode 100644 index 00000000..8fed2994 --- /dev/null +++ b/evidence/s3/client.md @@ -0,0 +1,97 @@ +# Клиент S3 приложения: операции, отказы, отказ в учётных данных + +- Дата: 2026-10-20, 17:15–17:16 UTC. +- Commit: `2e997f9`. +- Стенд: `make run_docker`, проект `mtusi-lab4`. Клиент запущен в + консоли (`uv run python`, настройки из `.env` и `config.toml` по + умолчанию): `127.0.0.1:8334`, bucket `messenger`, `[s3] + timeout_seconds` 5, `connect_timeout_seconds` 1, без повторов. +- Скрипт `probe_client.py` (scratchpad) вызывает `src.infra.s3` + (`ObjectStorage`) и docker compose (`pause`, `stop`, `start` сервиса + `s3`). +- Спек `object-storage`: «Клиент хранилища в приложении» — «S3 + остановлен», «S3 завис», «S3 вернулся», «Объекта нет», «Учётные данные + отклонены»; `service-logging`: «Обращение к S3». Design change + `s3-storage`, решение 7. +- Hostname машины в поле `instance_id` заменён на ``. + +## 1. Операции + +``` +$ uv run python probe_client.py ops +put 3 MiB: ok in 139 ms +head: ok in 3 ms + head: size=3145745 content_type=image/png + open: size=3145745 content_type=image/png +open+read: ok in 63 ms + sha256 equal: True +delete: ok in 2 ms +head missing -> None +open missing: StoredObjectMissing in 2 ms +delete missing: ok in 1 ms +``` + +Отсутствующий объект отличается от недоступности: `head` → `None`, `open` +→ `StoredObjectMissing`, `delete` → не ошибка. + +## 2. S3 завис, остановлен, вернулся — без перезапуска клиента + +``` +$ uv run python probe_client.py outage +healthy put: ok in 15 ms +timeout_seconds=5.0 +{"event": "Object storage is unavailable", "instance_id": "", "module": "object_storage", "operation": "put_object", "endpoint": "127.0.0.1:8334", "bucket": "messenger", "key": "messenger/probe/outage", "duration_ms": 5003, "error_type": "TimeoutError", "level": "warning", "timestamp": "2026-10-20T17:16:00.590525Z", "filename": "client.py", "lineno": 348, "func_name": "_failure"} +paused put: ObjectStorageUnavailable in 5008 ms +{"event": "Object storage is unavailable", "instance_id": "", "module": "object_storage", "operation": "head_object", "endpoint": "127.0.0.1:8334", "bucket": "messenger", "key": "messenger/probe/outage", "duration_ms": 5005, "error_type": "TimeoutError", "level": "warning", "timestamp": "2026-10-20T17:16:05.598635Z", "filename": "client.py", "lineno": 348, "func_name": "_failure"} +paused head: ObjectStorageUnavailable in 5007 ms +unpaused put: ok in 9 ms +docker compose stop s3: 15.6 s +{"event": "Object storage is unavailable", "instance_id": "", "module": "object_storage", "operation": "put_object", "endpoint": "127.0.0.1:8334", "bucket": "messenger", "key": "messenger/probe/outage", "duration_ms": 7, "error_type": "EndpointConnectionError", "level": "warning", "timestamp": "2026-10-20T17:16:21.444762Z", "filename": "client.py", "lineno": 348, "func_name": "_failure"} +stopped put: ObjectStorageUnavailable in 8 ms +{"event": "Object storage is unavailable", "instance_id": "", "module": "object_storage", "operation": "head_object", "endpoint": "127.0.0.1:8334", "bucket": "messenger", "key": "messenger/probe/outage", "duration_ms": 2, "error_type": "EndpointConnectionError", "level": "warning", "timestamp": "2026-10-20T17:16:21.447111Z", "filename": "client.py", "lineno": 348, "func_name": "_failure"} +stopped head: ObjectStorageUnavailable in 2 ms +started put: ok in 18 ms +started delete: ok in 7 ms +``` + +- Сервер заморожен (`docker pause`): вызов обрывается сроком через + 5,007–5,008 с при сроке 5 с, повторов нет. +- Сервер остановлен: отказ соединения за 2–8 мс, это меньше 0,1 с. +- После `unpause` и `start` следующий вызов проходит тем же клиентом, + без пересоздания. + +## 3. Неверный секрет — 503 и одна запись `error` + +``` +$ uv run python probe_client.py wrong-secret +{"event": "Object storage rejected credentials", "instance_id": "", "module": "object_storage", "error_code": "SignatureDoesNotMatch", "operation": "put_object", "endpoint": "127.0.0.1:8334", "bucket": "messenger", "key": "messenger/probe/wrong", "duration_ms": 13, "error_type": "ClientError", "level": "error", "timestamp": "2026-10-20T17:16:27.071569Z", "func_name": "_failure", "lineno": 332, "filename": "client.py"} +wrong secret put: ObjectStorageUnavailable in 13 ms +``` + +`ObjectStorageUnavailable` — наследник `ServiceUnavailable`: таблица +`src/api/errors.py` отдаёт на него 503 `unavailable`. + +``` +$ uv run python -c "from src.api.errors import DOMAIN_ERRORS; from src.core.exceptions import ObjectStorageUnavailable as E; print(next((c.__name__, DOMAIN_ERRORS[c]) for c in E.__mro__ if c in DOMAIN_ERRORS))" +('ServiceUnavailable', (503, )) +``` + +## 4. Секретов в журнале нет + +Значения пяти секретов S3 из `.env` (административные ключ и секрет, ключ +подписи, ключ и секрет API) проверены `grep -F` по выводу трёх прогонов: + +``` +secret/key values found in client logs: 0 +``` + +В apply тем же способом проверен журнал `make run_dev`, к пяти значениям +добавлены пароли PostgreSQL и Valkey: 0 совпадений. Запись старта: + +``` +{"event": "Started API", "instance_id": "", "module": "startup", "host": "127.0.0.1", "port": 8080, "run_mode": "", "database_host": "127.0.0.1", "database_port": 5433, "database_name": "messenger", "cache_host": "127.0.0.1", "cache_port": 6380, "s3_host": "127.0.0.1", "s3_port": 8334, "s3_bucket": "messenger", "level": "info", ...} +``` + +Логгеры `botocore`, `aiobotocore` и `aiohttp` стоят на `WARNING` +(`src/infra/logger.py`): заголовок `Authorization` с подписью в журнал не +попадает. diff --git a/evidence/s3/grpc-admin.md b/evidence/s3/grpc-admin.md new file mode 100644 index 00000000..f95faf65 --- /dev/null +++ b/evidence/s3/grpc-admin.md @@ -0,0 +1,47 @@ +# gRPC шлюза S3: учётную запись без токена не принять + +- Дата: 2026-10-20, ~17:22 UTC. +- Commit: `2e997f9`. +- Стенд: `make run_docker`, проект `mtusi-lab4`. Сервер S3 запущен с + `WEED_JWT_FILER_SIGNING_KEY`. +- Спек `object-storage`: «Служебные интерфейсы вне сети», сценарий + «Учётная запись через gRPC-порт без токена». Design change + `s3-storage`, решение 8 и Risks («gRPC-порт шлюза открыт в сети»). + +Порт gRPC шлюза (`S3_PORT` + 10000 = 18333) открыт в сети стенда +(`privacy.md`, раздел 1). Своего адреса привязки и выключателя у него +нет, без ключа подписи он принимал `PutIdentity` от любого контейнера +(design, Context). + +## Проба + +Разовая проба, в проект и `uv.lock` она не входит: +- одноразовый контейнер + `python:3.12.14-slim-trixie@sha256:f77ac9e4…` в сети + `mtusi-lab4_default`; +- `grpcio` 1.84.0, `protobuf` 7.35.1, `boto3` 1.43.115; +- клиент сгенерирован в пробе propose из `iam.proto` и `s3.proto` + SeaweedFS (`weed/pb`, сервис `SeaweedS3IamCache`) той же ревизии 4.48; +- скрипт `evil.py` из scratchpad, смонтирован только на чтение. + +Скрипт без токена вызывает `PutIdentity` с учётной записью «evil» +(`actions: ["Admin"]`, свои ключ и секрет). Затем этими ключами +запрашивает список bucket-ов и объекты `messenger`. + +``` +$ docker run --rm --network mtusi-lab4_default … python:3.12.14-slim-trixie … \ + sh -c 'pip install grpcio==1.84.0 protobuf==7.35.1 boto3; python evil.py s3:18333 http://s3:8333' +grpcio 1.84.0 protobuf 7.35.1 boto3 1.43.115 +PutIdentity without token: UNAUTHENTICATED missing authorization metadata +evil S3 access: InvalidAccessKeyId +``` + +- Вызов отклонён как неаутентифицированный: токена, подписанного ключом + стенда, нет. +- Ключи «злоумышленника» S3 не знает (`InvalidAccessKeyId`), учётные + записи сервера не изменились. + +Для сравнения — без `WEED_JWT_FILER_SIGNING_KEY` у сервера (проба +propose, design, Context): `PutIdentity` принят, «evil» стал +администратором и увидел все bucket-ы. Поэтому `S3_JWT_SIGNING_KEY` +обязателен: compose без него не стартует (`:?` в `docker-compose.yml`). diff --git a/evidence/s3/memory.md b/evidence/s3/memory.md new file mode 100644 index 00000000..a80662ce --- /dev/null +++ b/evidence/s3/memory.md @@ -0,0 +1,50 @@ +# Память S3: 20 одновременных PUT по 10 MiB + +- Дата: 2026-10-20, 17:16–17:17 UTC. +- Commit: `2e997f9`. +- Стенд: `make run_docker`, проект `mtusi-lab4`. Сервис `s3`: лимит + 1 CPU / 512 МБ, `GOMEMLIMIT=400MiB`, `-s3.concurrentUploadLimitMB=64` + (design change `s3-storage`, решение 2). ВМ Docker — 12 CPU / + 7,75 ГиБ, Apple M3 Pro. +- Нагрузка — скрипт `burst_memory.py` (scratchpad): + - aiobotocore ключом API из настроек приложения, пул 20, без + повторов, `read_timeout` 60 с; + - 20 случайных тел по 10 MiB уходят в `put_object` одновременно + (`asyncio.gather`), затем 20 одновременных GET со сверкой SHA-256, + затем удаление; + - раз в ~0,4 с (`docker compose exec`, 23 выборки) читаются + `memory.current` и `anon` из `memory.stat` cgroup контейнера; до и + после — `memory.peak` и `oom_kill` из `memory.events`. +- Спек `object-storage`: «Одновременная запись». + +``` +before: StartedAt 2026-10-20T17:16:21.637346137Z RestartCount 0 OOMKilled false +before: memory.peak 149 MiB, oom_kill 0 +20 x 10 MiB PUT at once: all confirmed in 7.21 s +20 x GET at once in 1.57 s: 20/20 with the same size and SHA-256 +20 probe objects deleted +during: 23 samples every 0.2 s; max memory.current 503 MiB, max anon 379 MiB (limit 512 MiB, GOMEMLIMIT 400 MiB) +after: memory.peak 512 MiB, oom_kill 0 +after: StartedAt 2026-10-20T17:16:21.637346137Z RestartCount 0 OOMKilled false Status running Health healthy +``` + +В строке `during` написано «every 0.2 s» — это пауза между выборками; с +учётом `docker compose exec` выборка выходила раз в ~0,4 с. + +## Вывод + +- Все 20 записей подтверждены и прочитаны с тем же SHA-256. Контейнер не + перезапускался (`StartedAt`, `RestartCount 0`), OOM-kill не было + (`oom_kill 0`, `OOMKilled false`). +- Анонимная память процесса — не больше 379 MiB: ниже `GOMEMLIMIT` и + лимита. `memory.current` и `memory.peak` доходят до лимита за счёт + страничного кэша записанных томов, ядро вытесняет его без OOM. Поэтому + считать надо анонимную память (design, Risks). +- Без `GOMEMLIMIT` и лимита загрузок те же 20 загрузок давали OOM-kill + (проба propose, design, Context). +- **Для change `upload-memory`.** Лимит загрузок шлюза (64 МБ) ставит + запросы в очередь, и последняя из 20 записей подтверждена через 7,2 с. + Это больше срока вызова клиента приложения (`[s3] timeout_seconds` + 5 с): у API при 20 одновременных загрузках по 10 MiB часть закончится + 503. Подбор лимита API на одновременные загрузки и сроков — задача + `upload-memory`. diff --git a/evidence/s3/privacy.md b/evidence/s3/privacy.md new file mode 100644 index 00000000..ab8a9691 --- /dev/null +++ b/evidence/s3/privacy.md @@ -0,0 +1,185 @@ +# Приватность bucket и изоляция S3 вне API + +- Дата: 2026-10-20, 17:15–17:16 UTC. +- Commit: `2e997f9` (рабочее дерево — только `PLAN.md` вне кода). +- Стенд: `make run_docker`, проект `mtusi-lab4`. Docker Desktop 29.8.2, + compose 5.5.1, ВМ Docker 12 CPU / 7,75 ГиБ, Apple M3 Pro. S3 — + `chrislusf/seaweedfs:4.48@sha256:4e61d15f…7872d`. +- Спек `object-storage`: «Проверка приватности вне API», «Запрет + анонимного доступа», «Ограниченные учётные данные API», «Служебные + интерфейсы вне сети»; спек `container-run`: «Публикация только на + localhost», «Секреты по сервисам». Design change `s3-storage`, + решения 1, 3, 8. + +## 1. `make s3_check` + +Без приложения: bootstrap в режиме `check` (строки `server`), анонимные +запросы с хоста на `127.0.0.1:8334` (`host`) и из одноразового +контейнера в сети `mtusi-lab4_default` (`network`), порты контейнера S3 +из сети, затем режим `cleanup` и `weed shell` — остатков нет. + +``` +$ make s3_check +python3 .claude/skills/run-mtusi-messenger/driver.py s3-check +S3 s3:8333 (host 127.0.0.1:8334), bucket messenger, image chrislusf/seaweedfs:4.48 +where check expected got verdict +server anonymous access setting none none ok +server api key put object 200 200 ok +server api key get object 200 200 ok +server api key head object 200 200 ok +server api key get missing object 404 404 ok +server api key list objects 403 403 ok +server api key create bucket 403 403 ok +server api key delete bucket 403 403 ok +server api key get bucket policy 403 403 ok +server api key put bucket policy 403 403 ok +server api key get bucket acl 403 403 ok +server api key put bucket acl public-read 403 403 ok +server api key put object acl public-read 403 403 ok +server api key put object to other bucket 403 403 ok +server api key get object from other bucket 403 403 ok +server api key list other bucket 403 403 ok +server api key delete other bucket 403 403 ok +server anonymous get object 403 403 ok +server anonymous head object 403 403 ok +server anonymous get missing object 403 403 ok +server anonymous list objects 403 403 ok +server anonymous list buckets 403 403 ok +server anonymous put object 403 403 ok +server anonymous create bucket 403 403 ok +host anonymous get object 403 403 ok +host anonymous head object 403 403 ok +host anonymous get missing object 403 403 ok +host anonymous list objects 403 403 ok +host anonymous list buckets 403 403 ok +host anonymous put object 403 403 ok +network anonymous get object 403 403 ok +network anonymous head object 403 403 ok +network anonymous get missing object 403 403 ok +network anonymous list objects 403 403 ok +network anonymous list buckets 403 403 ok +network anonymous put object 403 403 ok +network port 8333 (S3 API / gRPC of gateway) open open ok +network port 18333 (S3 API / gRPC of gateway) open open ok +network port 9333 closed closed ok +network port 19333 closed closed ok +network port 8888 closed closed ok +network port 18888 closed closed ok +network port 8080 closed closed ok +network port 18080 closed closed ok +network port 23646 closed closed ok +network port 8181 closed closed ok +network port 9101 closed closed ok +network port 7333 closed closed ok +network port 8111 closed closed ok +network port 6060 closed closed ok +server temporary buckets left 0 0 ok +server probe objects left 0 0 ok +PASS: 52 checks, bucket messenger is private +exit=0 +``` + +Наблюдения: +- аноним получает 403 на существующий и на отсутствующий ключ: наличие + объекта не раскрывается; +- ключ API читает, пишет и удаляет только объекты своего bucket + (отсутствующий ключ — 404). Список, операции с bucket, политика, ACL, + публичный ACL объекта и чужой bucket — 403; +- закрыты порты master (9333/19333), filer (8888/18888), volume + (8080/18080), admin UI (23646), Iceberg (8181), Lance (9101), а также + 7333, 8111 и pprof (6060). Открыты только API S3 и gRPC шлюза. gRPC + шлюза закрыт ключом подписи — `grpc-admin.md`. + +## 2. Нарушение обнаруживается, bootstrap его исправляет + +Анонимное чтение открыто административной командой мимо bootstrap: + +``` +$ printf "s3.anonymous.set -bucket messenger -access Read\n" | docker compose exec -T s3 weed shell +Set anonymous access on bucket "messenger" to: Read +$ make s3_check (only FAIL lines) +server anonymous access setting none Read FAIL +server anonymous get object 403 200 FAIL +server anonymous head object 403 200 FAIL +server anonymous get missing object 403 404 FAIL +host anonymous get object 403 200 FAIL +host anonymous head object 403 200 FAIL +host anonymous get missing object 403 404 FAIL +network anonymous get object 403 200 FAIL +network anonymous head object 403 200 FAIL +network anonymous get missing object 403 404 FAIL +FAIL: 10 check(s) failed: server: anonymous access setting; server: anonymous get object; server: anonymous head object; server: anonymous get missing object; host: anonymous get object; host: anonymous head object; host: anonymous get missing object; network: anonymous get object; network: anonymous head object; network: anonymous get missing object +exit=2 +$ docker compose up -d s3-bootstrap; docker compose logs s3-bootstrap (last run) +s3-bootstrap: bucket messenger exists +s3-bootstrap: anonymous access to messenger closed +s3-bootstrap: user api exists +s3-bootstrap: checks passed (api key put/get/delete; api key list and bucket create, anonymous get and list denied) +$ make s3_check | tail -1 +PASS: 52 checks, bucket messenger is private +exit=0 +``` + +`exit=2` — это код `make`: драйвер вернул 1, и make на ошибке рецепта +отвечает 2. + +## 3. Публикация портов + +``` +$ docker compose ps -a +SERVICE STATUS PORTS +api Up 5 minutes (healthy) 8080/tcp +api Up 5 minutes (healthy) 8080/tcp +haproxy Up 5 minutes (healthy) 127.0.0.1:8080->8080/tcp +migrate Exited (0) 13 seconds ago +postgres Up 5 minutes (healthy) 127.0.0.1:5433->5432/tcp +s3 Up 5 minutes (healthy) 127.0.0.1:8334->8333/tcp +s3-bootstrap Exited (0) 14 seconds ago +valkey Up 5 minutes (healthy) 127.0.0.1:6380->6379/tcp + +$ docker port (each container) +mtusi-lab4-api-1: +mtusi-lab4-api-2: +mtusi-lab4-haproxy-1: 8080/tcp -> 127.0.0.1:8080 +mtusi-lab4-migrate-1: +mtusi-lab4-postgres-1: 5432/tcp -> 127.0.0.1:5433 +mtusi-lab4-s3-1: 8333/tcp -> 127.0.0.1:8334 +mtusi-lab4-s3-bootstrap-1: +mtusi-lab4-valkey-1: 6379/tcp -> 127.0.0.1:6380 +``` + +У S3 на хосте опубликован только порт API S3 и только на `127.0.0.1`. +Консоли и UI нет ни на хосте, ни в сети (раздел 1). + +## 4. Секреты по сервисам + +Значения секретов из `.env` сопоставлены с окружением каждого сервиса в +`docker compose config` (разовый скрипт). Печатаются только имена: + +``` +api: POSTGRES_PASSWORD as DATABASE__PASSWORD, VALKEY_PASSWORD as CACHE__PASSWORD, S3_API_ACCESS_KEY as S3__ACCESS_KEY_ID, S3_API_SECRET_KEY as S3__SECRET_ACCESS_KEY +haproxy: - +migrate: POSTGRES_PASSWORD as DATABASE__PASSWORD +postgres: POSTGRES_PASSWORD as POSTGRES_PASSWORD +s3: S3_ROOT_ACCESS_KEY as AWS_ACCESS_KEY_ID, S3_ROOT_SECRET_KEY as AWS_SECRET_ACCESS_KEY, S3_JWT_SIGNING_KEY as WEED_JWT_FILER_SIGNING_KEY +s3-bootstrap: S3_JWT_SIGNING_KEY as WEED_JWT_FILER_SIGNING_KEY, S3_API_ACCESS_KEY as S3_API_ACCESS_KEY, S3_API_SECRET_KEY as S3_API_SECRET_KEY +valkey: VALKEY_PASSWORD as VALKEYCLI_AUTH, VALKEY_PASSWORD as VALKEY_PASSWORD +``` + +- Административная пара S3 есть только у `s3`. +- Ключ подписи — у `s3` и `s3-bootstrap`. +- Ключи API — у `s3-bootstrap` и реплик `api`. +- У LB нет ни одного секрета, у `migrate` — только пароль PostgreSQL. + +## 5. Внешних соединений нет + +``` +$ docker compose exec -T s3 sh -c 'netstat -tn | awk "NR>2 {print \$5}" | sed "s/:[0-9]*$//" | sort | uniq -c' + 223 127.0.0.1 + 13 ::ffff:127.0.0.1 + 18 ::ffff:192.168.0.1 +``` + +Подсеть `mtusi-lab4_default` — `192.168.0.0/20`, `192.168.0.1` — её шлюз +(через него приходят запросы с опубликованного порта хоста). Других +адресов нет. В описании сервиса — `-master.telemetry=false`. diff --git a/evidence/s3/restart.md b/evidence/s3/restart.md new file mode 100644 index 00000000..8c666b78 --- /dev/null +++ b/evidence/s3/restart.md @@ -0,0 +1,85 @@ +# Рестарт стенда с S3 и SIGKILL сервера S3 + +- Дата: 2026-10-20, 17:17–17:18 UTC. +- Commit: `2e997f9`. +- Стенд: `make run_docker`, проект `mtusi-lab4`. Docker Desktop + 29.8.2, compose 5.5.1, Apple M3 Pro. +- Спек `container-run`: «Рестарт hook-ом»; `object-storage`: «Рестарт + стенда», «Принудительное завершение». Design change `s3-storage`, + решение 9. +- Публичный `make test-persistence` до change `attachments` красный: он + загружает вложение до вызова hook (design, Context). Поэтому hook + проверен напрямую. +- Объекты пишет и читает клиент приложения `src/infra/s3` в консоли + (`persist_probe.py`, scratchpad) ключом API. Размеры объектов — + 200 000 + i × 50 000 байт. + +## 1. `scripts/restart.sh` + +``` +$ persist_probe.py write 3 +written and confirmed: 3 objects +--- before +mtusi-lab4-api-1 7accadadfcdf 2026-10-20T17:09:56.87103075Z running +mtusi-lab4-api-2 27dc0f625cba 2026-10-20T17:09:56.957602042Z running +mtusi-lab4-haproxy-1 1d3b522e85fa 2026-10-20T17:09:57.069310542Z running +mtusi-lab4-migrate-1 beb1346b3d64 2026-10-20T17:14:53.472596304Z exited +mtusi-lab4-postgres-1 29c7b37863c1 2026-10-20T17:09:49.559951594Z running +mtusi-lab4-s3-1 53a2a1cd172f 2026-10-20T17:16:21.637346137Z running +mtusi-lab4-s3-bootstrap-1 d05a07be6b40 2026-10-20T17:15:30.66585646Z exited +mtusi-lab4-valkey-1 bd4329833fcc 2026-10-20T17:09:49.272486844Z running +$ time scripts/restart.sh +exit=0, 25 s +--- after +mtusi-lab4-api-1 7accadadfcdf 2026-10-20T17:17:47.007431801Z running +mtusi-lab4-api-2 27dc0f625cba 2026-10-20T17:17:47.076103343Z running +mtusi-lab4-haproxy-1 1d3b522e85fa 2026-10-20T17:17:47.188104885Z running +mtusi-lab4-migrate-1 beb1346b3d64 2026-10-20T17:17:44.385383967Z exited +mtusi-lab4-postgres-1 29c7b37863c1 2026-10-20T17:17:24.183151596Z running +mtusi-lab4-s3-1 53a2a1cd172f 2026-10-20T17:17:39.223372464Z running +mtusi-lab4-s3-bootstrap-1 d05a07be6b40 2026-10-20T17:17:44.2638513Z exited +mtusi-lab4-valkey-1 bd4329833fcc 2026-10-20T17:17:24.158704555Z running +$ docker compose logs --since 60s --no-log-prefix s3-bootstrap +s3-bootstrap: bucket messenger exists +s3-bootstrap: user api exists +s3-bootstrap: checks passed (api key put/get/delete; api key list and bucket create, anonymous get and list denied) +health/ready via LB: {"status":"ok"} +$ persist_probe.py verify +read back with the same SHA-256: 3/3; deleted +``` + +- Перезапущены LB, обе реплики, PostgreSQL, Valkey и S3: ID контейнеров + прежние, `StartedAt` у всех новый. `migrate` и `s3-bootstrap` снова + выполнены как зависимости `start api`. +- Hook занял 25 с при сроке 90 с, из них ~15 с — плавная остановка + SeaweedFS (`stop_grace_period: 20s`). +- Bootstrap после рестарта ничего не изменил («exists»), объекты + прочитаны с тем же SHA-256. +- В выводе hook нет ни `secret`, ни `password`, ни `key=`: grep по нему + дал 0 строк. + +## 2. Плавная остановка S3 + +Из пробы клиента (`client.md`, 17:16): + +``` +docker compose stop s3: 15.6 s +``` + +Тот же стенд в apply (2026-10-20): `docker compose stop s3` — 15 с, +`ExitCode 0`, `OOMKilled false`. SIGKILL по сроку не понадобился. + +## 3. SIGKILL сразу после подтверждённых записей + +``` +$ persist_probe.py write 20 && docker kill -s KILL mtusi-lab4-s3-1 +written and confirmed: 20 objects +after kill: status exited, exit 137 +$ docker compose up -d --wait s3 +healthy in 3 s +$ persist_probe.py verify +read back with the same SHA-256: 20/20; deleted +``` + +Все 20 подтверждённых объектов пережили SIGKILL процесса. Отказ диска или +ВМ этим не покрыт: одна нода без реплик (`REPORT.md`, «Ограничения»). diff --git a/evidence/tests/failure-checks.md b/evidence/tests/failure-checks.md new file mode 100644 index 00000000..7c0888c9 --- /dev/null +++ b/evidence/tests/failure-checks.md @@ -0,0 +1,90 @@ +# `make failure_checks` со своим S3 + +- Дата: 2026-10-20, 17:21:58–17:23:29 UTC. +- Commit: `2e997f9`. +- Стенд отказов: проект `mtusi-lab4-failures` (Postgres, Valkey, S3 с + bootstrap, без портов хранилищ), два API на `127.0.0.1`. Рабочий стенд + `mtusi-lab4` в это время запущен. Docker Desktop 29.8.2, Apple M3 Pro. +- Новая проверка change `s3-storage` — + `test_readiness_without_object_storage`: спек `health`, «Хранилище + объектов недоступно». + +## Итог: код 2, пять красных — ожидаемо до change `attachments` + +Красны 5 проверок из уточнённого списка в шапке `tasks.md` change +`s3-storage`, у всех одна причина: + +``` + 5 E AssertionError: Message schema: /: 'attachment_ids' is a required property +``` + +Контракт лабы 4 требует поле `attachment_ids` в `Message`, а код лабы 3 +его не отдаёт (в `src/` поля нет). Эти тесты проверяют схему ответа на +отправку сообщения. Чинит change `attachments` (ответ пользователя +2026-10-20, `PLAN.md`, `s3-storage`, «Вопросы», п. 2), там этот файл +переснимается зелёным. S3 и стенд отказов здесь ни при чём: остальные +13 проверок, включая новую, прошли. + +## Вывод (строки оркестратора и pytest) + +``` +$ make failure_checks +[failure_checks] project=mtusi-lab4-failures (working stand: mtusi-lab4) +[failure_checks] build image +[failure_checks] start postgres, valkey and s3 +[failure_checks] migrations +[failure_checks] s3 bootstrap +s3-bootstrap-1 | s3-bootstrap: bucket messenger created +s3-bootstrap-1 | s3-bootstrap: user api created +s3-bootstrap-1 | s3-bootstrap: checks passed (api key put/get/delete; api key list and bucket create, anonymous get and list denied) +[failure_checks] start api containers +[failure_checks] ready: api=http://127.0.0.1:59374 tight=http://127.0.0.1:59382 +[failure_checks] pytest -m fault +student-tests/test_failures.py::test_expired_token PASSED [ 5%] +student-tests/test_failures.py::test_use_does_not_extend_session PASSED [ 11%] +student-tests/test_failures.py::test_token_while_database_stopped PASSED [ 16%] +student-tests/test_failures.py::test_members_failure_rolls_back_chat PASSED [ 22%] +student-tests/test_failures.py::test_database_stopped_and_back FAILED [ 27%] +student-tests/test_failures.py::test_pool_exhausted PASSED [ 33%] +student-tests/test_failures.py::test_connection_limit_reached PASSED [ 38%] +student-tests/test_failures.py::test_pool_keeps_connections PASSED [ 44%] +student-tests/test_failures.py::test_readiness_without_database PASSED [ 50%] +student-tests/test_failures.py::test_readiness_without_cache PASSED [ 55%] +student-tests/test_failures.py::test_readiness_without_object_storage PASSED [ 61%] +student-tests/test_failures.py::test_flush_cache PASSED [ 66%] +student-tests/test_failures.py::test_valkey_stopped FAILED [ 72%] +student-tests/test_failures.py::test_valkey_paused PASSED [ 77%] +student-tests/test_failures.py::test_valkey_back PASSED [ 83%] +student-tests/test_failures.py::test_message_failure_keeps_key_free FAILED [ 88%] +student-tests/test_failures.py::test_database_outage_keeps_key_free FAILED [ 94%] +student-tests/test_failures.py::test_key_free_after_ttl FAILED [100%] +=========== 5 failed, 13 passed, 142 deselected in 69.48s (0:01:09) ============ +[failure_checks] postgres log: 380 lines, crash markers 0; "too many clients" 25, "administrator command" 129 +[failure_checks] last 50 lines of mtusi-lab4-failures-api +[failure_checks] last 50 lines of mtusi-lab4-failures-api-tight +[failure_checks] cleanup +[failure_checks] results: {'fault': 1, 'postgres': 0} +exit=2 +``` + +Журналы API стенда отказов, которые печатает оркестратор, здесь опущены. + +## Уборка и рабочий стенд + +``` +working stand StartedAt unchanged +left: containers 0, volumes 0 +``` + +- `StartedAt` всех контейнеров `mtusi-lab4` до и после прогона совпали. +- У проекта `mtusi-lab4-failures` не осталось ни контейнеров, ни + volumes, включая volume S3. + +## Новая проверка + +`test_readiness_without_object_storage`: hook останавливает `s3` стенда +отказов (`stop_grace_period: 2s`). `GET /health/ready` и `GET +/health/live` отвечают 200 `{"status": "ok"}` быстрее 1 с, после этого +`s3` запускается снова. Отдельный прогон `make failure_checks +FAULT_ARGS='-k object_storage'` в apply: `1 passed`, код 0, стенд отказов +убран, у рабочего стенда прежний `StartedAt`. diff --git a/evidence/tests/test-isolated-s3-cleanup.md b/evidence/tests/test-isolated-s3-cleanup.md new file mode 100644 index 00000000..a7152584 --- /dev/null +++ b/evidence/tests/test-isolated-s3-cleanup.md @@ -0,0 +1,85 @@ +# `make test_isolated`: уборка объектов S3 временной базы + +- Дата: 2026-10-20, 17:23:36–17:25:14 UTC. +- Commit: `2e997f9`. +- Стенд: рабочий `mtusi-lab4` (`make run_docker`). Временная база + `test_messenger`, S3 и Valkey стенда общие. +- Спек `student-tests`: «Прогон на временной базе» (уборка префикса + `test_/`, «Хвост прошлого прогона», «Сохранить базу для разбора»). + Design change `s3-storage`, решение 9. + +## Итог прогона: код 2, красное — ожидаемо до change `attachments` + +- Smoke: `FAIL: response: missing required fields`. Схема ответа + контракта лабы 4 требует поле `attachment_ids`, которого в коде лабы 3 + нет. Загрузки вложения тоже ещё нет. +- `make student_test EXPECT_REPLICAS=1`: `30 failed, 106 passed, 4 + skipped, 18 deselected, 2 errors`. + - 29 упавших и 2 ошибки фикстуры (`test_tampered_cursor`) — с одной + причиной: `Message` / `MessagePage schema: 'attachment_ids' is a + required property`. + - Ещё одна — `test_exclusion_evidence_exists`: файлы исключений сверки + покрытия снимаются заново на стенде лабы 4, после `attachments`. + - `test_every_scenario_is_covered` прошёл. + +Список совпадает с уточнённым в шапке `tasks.md` change `s3-storage`. +Чинит change `attachments` (ответ пользователя 2026-10-20, `PLAN.md`), +там прогон переснимается зелёным. + +## Уборка префикса + +Перед прогоном разовым скриптом `prefix_probe.py` (клиент `src/infra/s3`) +записаны объекты `test_messenger/probe` (будто хвост прошлого прогона) и +`messenger/probe` (рабочая база). + +``` +$ prefix_probe.py put +test_messenger/probe: present +messenger/probe: present +$ make test_isolated +[test_isolated] database=test_messenger objects=/buckets/messenger/test_messenger/ container=mtusi-lab4-test-api base_url=http://127.0.0.1:18088 +[test_isolated] remove objects /buckets/messenger/test_messenger/ +[test_isolated] build image +[test_isolated] create database test_messenger +[test_isolated] migrations +[test_isolated] start api container +[test_isolated] ready +[test_isolated] make test +FAIL: response: missing required fields +[test_isolated] make student_test += 30 failed, 106 passed, 4 skipped, 18 deselected, 2 errors in 81.02s (0:01:21) = +[test_isolated] last 50 lines of mtusi-lab4-test-api +[test_isolated] cleanup +[test_isolated] remove objects /buckets/messenger/test_messenger/ +[test_isolated] results: {'test': 2, 'student_test': 2} +exit=2 +$ prefix_probe.py show +test_messenger/probe: absent +messenger/probe: present +``` + +- Префикс `test_messenger/` удалён в начале (хвост) и в уборке. Объект + рабочей базы на месте, затем удалён вручную. +- База `test_messenger` удалена (`pg_database`: 0 строк), тестового + контейнера нет. + +## `KEEP_TEST_DB=1` (apply, 2026-10-20, тот же код) + +Объект `test_messenger/probe` записан, пока шёл прогон (после строки +`ready`): + +``` +[test_isolated] remove objects /buckets/messenger/test_messenger/ +… +[test_isolated] kept database test_messenger and objects /buckets/messenger/test_messenger/ +[test_isolated] results: {'test': 2, 'student_test': 2} +test_messenger/probe: present +messenger/probe: present +``` + +Префикс и база остались, команда напечатала оба. Потом их убрали вручную: +`DROP DATABASE` и `weed shell fs.rm -r`. + +Префикс собирается только из имени, прошедшего `^test_[a-z0-9_]+$`, и +проверенного имени bucket (`run_isolated.py`, `object_prefix`). Иначе — +код 2 до любых действий. diff --git a/openspec/changes/s3-storage/design.md b/openspec/changes/s3-storage/design.md index 46a3e495..a1a47ee8 100644 --- a/openspec/changes/s3-storage/design.md +++ b/openspec/changes/s3-storage/design.md @@ -544,9 +544,10 @@ PostgreSQL change не трогает. 5. **Ожидаемо красные шире списка tasks.md.** Контракт лабы 4 сделал `attachment_ids` обязательным полем `Message`, а код лабы 3 его не отдаёт (в `src/` его нет с `5d5d8f9`). До change `attachments` - падают все тесты, которые проверяют схему сообщения: в `make - student_test` (и `make test_isolated`) — 30 упавших и 2 ошибки - фикстуры с одной причиной «'attachment_ids' is a required property», + падают все тесты, которые проверяют схему сообщения, с одной причиной + «'attachment_ids' is a required property»: в `make student_test` + через LB — 32 упавших и 2 ошибки фикстуры, в `make test_isolated` — + 29 и 2 (тесты реплик там пропущены), в `make failure_checks` — 5 (`test_database_stopped_and_back`, `test_valkey_stopped`, `test_message_failure_keeps_key_free`, `test_database_outage_keeps_key_free`, `test_key_free_after_ttl`). diff --git a/openspec/changes/s3-storage/tasks.md b/openspec/changes/s3-storage/tasks.md index 7de5f9bf..d75e10c7 100644 --- a/openspec/changes/s3-storage/tasks.md +++ b/openspec/changes/s3-storage/tasks.md @@ -16,8 +16,9 @@ - поэтому и итог `make test_isolated`; - найдено в apply (design, «Уточнения apply», п. 5): тесты, которые проверяют схему `Message` / `MessagePage` контракта лабы 4 - (`attachment_ids` обязателен), — 30 упавших и 2 ошибки в `make - student_test`, 5 упавших в `make failure_checks`. Поэтому `make + (`attachment_ids` обязателен): в `make student_test` через LB — 32 + упавших и 2 ошибки фикстуры, в `make test_isolated` — 29 и 2 (тесты + реплик там пропущены); в `make failure_checks` — 5 упавших. Поэтому `make failure_checks` до `attachments` тоже ненулевой. Другие падения — дефект, их разбирают по AGENTS.md. @@ -218,7 +219,7 @@ ## 6. Evidence и отчёт -- [ ] 6.1 Evidence по таблице решения 10 с закоммиченного кода, без +- [x] 6.1 Evidence по таблице решения 10 с закоммиченного кода, без секретов, в каждом файле дата, commit и стенд: - `bootstrap.md`, `privacy.md`, `restart.md`, `client.md` и `memory.md` (20 одновременных PUT по 10 MiB ключом API, анонимная @@ -230,7 +231,7 @@ Проверка: `grep` по значениям секретов из `.env` в `evidence/s3/` пуст. -- [ ] 6.2 `REPORT.md`: +- [x] 6.2 `REPORT.md`: - роль S3 и её граница (байты вложений с change `attachments`); - таблица роль → сервис → версия/digest → healthcheck → volume → сеть/порт → способ передачи credentials для всех сервисов @@ -247,6 +248,6 @@ Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл. -- [ ] 6.3 `make lint`, `make check`, `openspec validate s3-storage +- [x] 6.3 `make lint`, `make check`, `openspec validate s3-storage --strict`, `graphify update .`; показать изменения и после подтверждения закоммитить evidence и отчёт.