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 <noreply@anthropic.com>
This commit is contained in:
2026-10-20 20:31:35 +03:00
co-authored by Claude Opus 5.5
parent 2e997f9b42
commit 7d340c0673
13 changed files with 997 additions and 15 deletions
+2 -1
View File
@@ -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_<db>/) — до 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
+16 -2
View File
@@ -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`.
+187 -4
View File
@@ -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:::<bucket>/*`) создаётся или
обновляется.
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`.
+143
View File
@@ -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=<new> 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), поэтому
она задана с первого старта.
+97
View File
@@ -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` заменён на `<host>`.
## 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": "<host>", "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": "<host>", "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": "<host>", "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": "<host>", "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": "<host>", "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, <ErrorCode.UNAVAILABLE: 'unavailable'>))
```
## 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": "<host>", "module": "startup", "host": "127.0.0.1", "port": 8080, "run_mode": "<RunModeEnum.CONSOLE: 'console'>", "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` с подписью в журнал не
попадает.
+47
View File
@@ -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`).
+50
View File
@@ -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`.
+185
View File
@@ -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`.
+85
View File
@@ -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`, «Ограничения»).
+90
View File
@@ -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`.
@@ -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_<db>/`, «Хвост прошлого прогона», «Сохранить базу для разбора»).
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 до любых действий.
+4 -3
View File
@@ -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`).
+6 -5
View File
@@ -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 и отчёт.