Files
mtusi2026lab4/openspec/changes/s3-storage/tasks.md
T
ricoromaandClaude Opus 5.5 f57635a5fb fix: address s3-storage verify findings
- s3 healthcheck and fault hook probe wait for the volume server to
  register with master (first write after restart no longer waits ~5 s)
- s3-bootstrap mounts /data as tmpfs: no anonymous volume per container
- S3 client: NoSuchBucket and AccessDenied are 503 with their own error
  logs, not a missing object or rejected credentials; delete ignores only
  a missing key
- test_isolated verifies prefix removal (weed shell exits 0 on errors)
- s3_check derives ports from listening sockets in the s3 container
- readiness without S3 is also checked with s3 paused

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 21:23:38 +03:00

342 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Tasks
Как строить — `design.md` (дальше «решение N»), что должно получиться —
дельты в `specs/`. Перед первым файлом слоя прочитать его правило:
`infra.md`, `settings.md`, `docker.md`, `run-modes.md`, `logging.md`,
`api-layer.md`, `api-contract.md`, `student-tests.md`, `bench.md`,
`balancer.md`. Evidence снимается с закоммиченного кода, коммит —
только после подтверждения пользователя (`bench.md`, «Измеренное
состояние — commit»).
До change `attachments` ожидаемо красные (design, Context):
- публичный smoke (`make test`);
- `make test-persistence` и `make test-failover` — загрузка вложения с
`LAB=4`;
- `test_exclusion_evidence_exists` в `make student_test`;
- поэтому и итог `make test_isolated`;
- найдено в apply (design, «Уточнения apply», п. 5): тесты, которые
проверяют схему `Message` / `MessagePage` контракта лабы 4
(`attachment_ids` обязателен): в `make student_test` через LB — 32
упавших и 2 ошибки фикстуры, в `make test_isolated` — 29 и 2 (тесты
реплик там пропущены); в `make failure_checks` — 5 упавших. Поэтому `make
failure_checks` до `attachments` тоже ненулевой.
Другие падения — дефект, их разбирают по AGENTS.md.
## 1. Зависимость и настройки
- [x] 1.1 Добавить зависимость: `uv add "aiobotocore>=3.9.2,<4"` в
основную группу, с комментарием «клиент S3 (SeaweedFS), решение 6».
Проверка: `uv lock --check`; `uv run python -c "import aiobotocore,
botocore; print(aiobotocore.__version__, botocore.__version__)"` —
3.9.x и 1.43.x.
- [x] 1.2 Секция `S3` в `src/config/settings.py` по решению 5:
- поля, `endpoint_url`, валидатор имени bucket по
`S3_BUCKET_NAME_PATTERN` в `src/utils/constants.py`;
- сроки `gt=0`, пул `ge=1`;
- `config_example.toml` и рабочий `config.toml` — `[s3]` без адреса,
bucket и ключей.
Проверка:
- `uv run python -c "from src.config import settings; s =
settings.s3; print(s.endpoint_url, s.bucket, s.timeout_seconds)"`
без `.env` даёт значения по умолчанию;
- `S3__BUCKET=Bad_Bucket` — запуск падает, в выводе есть `bucket`;
- `S3__TIMEOUT_SECONDS=0` — запуск падает.
- [x] 1.3 Блок S3 в `.env.example` по решениям 3 и 5: `S3_HOST`,
`S3_PORT`, `S3_OUT_PORT`, `S3__BUCKET`, пустые `S3_ROOT_*`, `S3_API_*`
и `S3_JWT_SIGNING_KEY`, мосты `S3__HOST`, `S3__PORT`,
`S3__ACCESS_KEY_ID`, `S3__SECRET_ACCESS_KEY`. Шапка шаблона — без
«строк S3 пока нет», имена skeleton `S3_*` в ней остаются. `make
env_setup` подставляет случайные hex в пять пустых значений нового
`.env`, существующий не трогает. Рабочий `.env` агент не читает:
строки S3 в него добавляет пользователь или агент с его согласия
(`PLAN.md`, «Вопросы»). Проверка:
- во временном каталоге с копиями `Makefile`, `.env.example` и
`config_example.toml` `make env_setup` дважды (с удалением `.env`
между ними) даёт непустые и разные значения пяти переменных, при
этом печатаются только их имена;
- существующий `.env` после `make env_setup` не изменился
(контрольная сумма).
## 2. Стенд
- [x] 2.1 `infra/s3/bootstrap.sh` (режим по умолчанию) и сервисы `s3`,
`s3-bootstrap` в `docker-compose.yml` по решениям 1–4:
- пин тега и digest;
- аргументы `weed server`, `GOMEMLIMIT`, healthcheck,
`stop_grace_period: 20s`, лимиты;
- volume `s3_data`, алиас `${S3_HOST}`, публикация
`127.0.0.1:${S3_OUT_PORT}`;
- якорь `x-s3-env` с сообщениями `:?` «copy S3 lines from
.env.example»;
- `api` ждёт `s3-bootstrap: service_completed_successfully`;
- секреты по сервисам — таблица решения 3.
Проверка:
- `docker compose --env-file .env config --quiet`;
- `make run_docker` на пустом volume S3: `s3` `healthy`, журнал
`s3-bootstrap` — «created» и «checks passed», реплики стартовали
после него;
- `docker compose up -d` и `docker compose run --rm s3-bootstrap` —
«exists», код 0;
- `docker compose run --rm -e S3_BUCKET=Bad_Bucket s3-bootstrap` —
код 1, шаг назван, секретов нет;
- `docker port` — только S3 на `127.0.0.1`;
- из одноразового контейнера в сети стенда `nc -z` — открыты только
8333 и 18333;
- `docker compose config` — секреты только у сервисов из таблицы;
- `docker inspect` — лимиты у `s3` и `s3-bootstrap`.
- [x] 2.2 Makefile и hook по решению 9:
- `start_s3` (`up -d --wait s3 s3-bootstrap`) и `stop_s3`;
- `run_dev: upgrade start_cache start_s3`;
- `test_isolated: … start_s3`;
- `wipe_data` называет volumes Postgres и S3;
- `scripts/restart.sh` — S3 в `restart` и `up --wait`.
Проверка:
- `make -n` для целей;
- `scripts/restart.sh` — у `s3` и остальных контейнеров новый
`StartedAt`, тот же ID; hook укладывается в 90 с (время записать);
`s3-bootstrap` после рестарта — «exists»;
- `docker compose stop s3` — код выхода контейнера 0, не 137.
- [x] 2.3 `make s3_check` по решению 8: режим `check` в
`infra/s3/bootstrap.sh` (проверочный объект, временный чужой bucket,
административные запросы ключом API) и команда `driver.py s3-check`
скилла (stdlib): анонимные запросы с хоста и из сети стенда, порты из
сети, таблица «проверка → ожидаемо → получено». Проверка:
- на стенде — код 0;
- после команды нет проверочных объектов и bucket (`weed shell`
`s3.bucket.list` и `fs.ls` в контейнере `s3`);
- отрицательная проверка: `s3.anonymous.set -access Read` через
`docker compose exec s3 weed shell` — `make s3_check` код 1 и
называет анонимное чтение; `docker compose up -d s3-bootstrap`
снова закрывает доступ, и `make s3_check` — код 0.
## 3. Клиент хранилища
- [x] 3.1 Клиент по решению 7:
- `src/core/exceptions/storage.py` (`ObjectStorageUnavailable`,
`StoredObjectMissing`) с реэкспортом;
- `src/infra/s3/client.py` и `instance.py` (`namespace` — имя базы),
константы ключа объекта;
- lifespan: `start()`, `aclose()`, `warning` о пустых ключах, поля
`s3_host`, `s3_port`, `s3_bucket` в «Started API»;
- логгеры `botocore`, `aiobotocore`, `aiohttp` — `WARNING` в
`src/infra/logger.py`.
Проверка — `make lint` и разовый скрипт в scratchpad (`uv run
python`, настройки консоли) против S3 стенда:
- `put`, `head`, `open` (SHA-256 совпал) и `delete` проходят;
`head` отсутствующего — `None`, `open` — `StoredObjectMissing`,
`delete` отсутствующего — без ошибки;
- `stop s3` — `ObjectStorageUnavailable` быстрее 0,1 с; `pause` —
в пределах срока ±0,1 с; после `start` / `unpause` следующий вызов
проходит без пересоздания клиента;
- `S3__SECRET_ACCESS_KEY=wrong` — `ObjectStorageUnavailable` и одна
запись `error` без секрета;
- в журнале скрипта и `make run_dev` нет ни секретов, ни ключей
доступа (grep по значениям из `.env`), а «Started API» называет
адрес и bucket.
## 4. Стенды проверок и нагрузки
- [x] 4.1 `make test_isolated` по решению 9: `run_isolated.py` удаляет
префикс `test_<db>/` в начале и в уборке (`docker compose exec -T s3`
+ `weed shell` `fs.rm -r`). Префикс собирается только из проверенного
имени временной базы, иначе отказ. При `KEEP_TEST_DB=1` префикс
остаётся, и команда его печатает. Проверка:
- перед прогоном разовым скриптом записать `test_<db>/probe` и
`<db>/probe`;
- `make test_isolated` (красное — по списку в шапке) — в выводе
уборка префикса, `test_<db>/probe` нет, `<db>/probe` на месте;
- с `KEEP_TEST_DB=1` префикс остался и напечатан;
- пробные объекты затем удалить.
- [x] 4.2 `make failure_checks` по решению 9:
- `run_failures.py` поднимает `s3` и `s3-bootstrap`;
- `failures.compose.yml` — у `s3` порты сброшены,
`stop_grace_period: 2s`;
- `fault_hook.py` — сервис `s3` с пробой healthcheck, действия
`stop` / `start` / `pause` / `unpause`, docstring;
- `test_readiness_without_object_storage` с маркером `spec("health",
"Хранилище объектов недоступно")`.
Проверка:
- `make failure_checks FAULT_ARGS='-k object_storage'`, затем полный
`make failure_checks` — код 0, контейнеров и volumes проекта
`-failures` нет, у рабочего стенда прежний `StartedAt`;
- `make student_test` — сверка покрытия считает сценарий покрытым
проверкой отказа, красный только `test_exclusion_evidence_exists`.
- [x] 4.3 `bench/` по решению 9:
- `compose_env` генерирует пять секретов S3;
- фильтр `app_env` паспорта убирает имена с `PASSWORD`, `SECRET`,
`ACCESS_KEY`;
- `bench.env` — `S3_HOST`, `S3_PORT`, `S3__BUCKET=bench`;
- override `s3`: `container_name: mtusi-bench-s3`, `restart: "no"`,
порты сброшены.
Проверка:
- `make bench_quick`, `make bench_failover_quick` и `make
bench_rollout_quick` — код 0;
- контейнера `mtusi-bench-s3` не было (поток `docker events` по
метке проекта или `docker ps -a` во время прогона);
- `grep -rn "SECRET\|ACCESS_KEY\|PASSWORD"` по каталогам пробных
меток пуст: в `stand.app_env` паспорта нет ни секретов, ни ключей.
## 5. Документы и проверка кода
- [x] 5.1 Правила, AGENTS.md и скилл:
- `infra.md` — клиент S3, ошибки, `instance.py`;
- `docker.md` — сервисы `s3`, `s3-bootstrap`, healthcheck, срок
остановки, порядок `restart.sh`;
- `settings.md` — `[s3]`, переменные S3, имена skeleton; пример
«пароли MinIO» заменить на S3;
- `run-modes.md` — `start_s3`, `run_dev`, `test_isolated`,
`s3_check`;
- `logging.md` — логгеры botocore, что нельзя писать о S3;
- `student-tests.md` — префикс временной базы, S3 стенда отказов,
действие hook;
- `bench.md` — S3 описан, но профили лаб 2–3 его не поднимают;
фильтр секретов паспорта;
- `balancer.md` — схема, «что стенд не переживает», bootstrap и
поочерёдная замена;
- `AGENTS.md` — карта кода, команды, окружение, «Переход в следующую
лабу» (`infra/s3/`);
- скилл: `driver.py start` поднимает S3, `SKILL.md`.
Проверка: `grep -rn "Строк S3\|пароли MinIO" AGENTS.md .claude
.env.example` пуст; `openspec validate s3-storage --strict` — без
ошибок.
- [x] 5.2 Финальная проверка кода:
- `make lint`, `make check`, `openspec validate s3-storage
--strict`;
- на стенде `make run_docker`: `make s3_check` — код 0, `make
student_test` через LB — красное только по списку в шапке;
- `make failure_checks` — код 0.
Затем показать изменения, предложить сообщение коммита и после
подтверждения закоммитить.
## 6. Evidence и отчёт
- [x] 6.1 Evidence по таблице решения 10 с закоммиченного кода, без
секретов, в каждом файле дата, commit и стенд:
- `bootstrap.md`, `privacy.md`, `restart.md`, `client.md` и
`memory.md` (20 одновременных PUT по 10 MiB ключом API, анонимная
память контейнера S3, OOM нет);
- `grpc-admin.md` — разовая проба: protobuf SeaweedFS ревизии образа,
одноразовый контейнер в сети стенда;
- вывод `make failure_checks` и строки уборки `make test_isolated` —
в `evidence/tests/`.
Проверка: `grep` по значениям секретов из `.env` в `evidence/s3/`
пуст.
- [x] 6.2 `REPORT.md`:
- роль S3 и её граница (байты вложений с change `attachments`);
- таблица роль → сервис → версия/digest → healthcheck → volume →
сеть/порт → способ передачи credentials для всех сервисов
(`infra/README.md`);
- bootstrap и его безопасный повтор, смена секрета;
- критичные и некритичные зависимости готовности;
- соответствие имён skeleton `S3_*`;
- строки уровней «3» и «4» (S3 в стенде, закреплённая версия, volume,
создание приватного bucket; идемпотентный bootstrap, отдельные
ограниченные учётные данные, консоль не в сети, проверка
приватности вне API) с командой, наблюдением и файлом;
- ограничения: одна нода, плавная остановка 15 с;
- шаг оператора про строки S3 в существующем `.env`.
Проверка: у каждой новой строки таблицы доказательств есть команда,
наблюдение и файл.
- [x] 6.3 `make lint`, `make check`, `openspec validate s3-storage
--strict`, `graphify update .`; показать изменения и после
подтверждения закоммитить evidence и отчёт.
## 7. Замечания проверки
Находки `/opsx:verify` (2026-10-20), все решено исправить. Решения —
design, «Уточнения apply», п. 8–13. Временный стенд проверок — проект
compose `mtusi-lab4-s3fresh` с S3 на tmpfs (новых volumes не создаёт),
`down` без `-v` после проверки.
- [x] 7.1 W1. S3 `healthy`, только когда master видит data node:
healthcheck `s3` в `docker-compose.yml` и `PROBES["s3"]` в
`student-tests/fault_hook.py` добавляют проверку `/dir/status` master
(непустой список `DataNodes`); сценарий «Первая запись после
healthy» в требовании «S3-хранилище в стенде» дельты `object-storage`;
числа в design (Context, решения 1 и 7), комментарий у `api`
в compose, `docker.md`, `student-tests.md`. Проверка:
- формат `/dir/status` сверен на стенде: сразу после старта
`DataNodes` нет, после регистрации тома — есть;
- `first_write.py` (scratchpad, срок вызова 30 с): до правки и после
— 12 рестартов `s3` с ожиданием `healthy`, первая запись после
правки быстрее 1 с во всех;
- `make failure_checks FAULT_ARGS='-k object_storage'` — проба hook
после `unpause` проходит.
- [x] 7.2 W2. `tmpfs: [/tmp, /data]` у `s3-bootstrap`: volume образа
`/data` больше не создаётся анонимным volume. В override стенда
отказов и `bench/` сервиса нет — они наследуют. Проверка:
- `docker inspect` контейнера `s3-bootstrap` — у `/data` тип `tmpfs`,
volume нет;
- число volumes (`docker volume ls -q | wc -l`) после `docker compose
up -d s3 s3-bootstrap` и `docker compose run --rm s3-bootstrap`
не растёт.
- [x] 7.3 S1. Клиент различает отсутствующий ключ и отсутствующий
bucket (`src/infra/s3/client.py`): `NoSuchBucket` —
`ObjectStorageUnavailable` и `error` «Object storage bucket is
missing»; `AccessDenied` и 403 без тела (HEAD) —
`ObjectStorageUnavailable` и `error` «Object storage denied access»
(не «rejected credentials»); `delete` глушит только отсутствующий
ключ. Сценарий «Bucket нет» в требовании «Клиент хранилища в
приложении» дельты `object-storage`; таблица ошибок design (решение
7), `infra.md`, `logging.md`. Проверка — разовый скрипт против
временного стенда:
- до правки: удалённый bucket — `open` и `delete` бросают
`StoredObjectMissing`, `put` пишет «rejected credentials»
(`AccessDenied`);
- после правки: удалённый bucket — `put`, `head`, `open`, `delete` —
`ObjectStorageUnavailable` и запись `error` о bucket; отсутствующий
ключ — `head` `None`, `open` `StoredObjectMissing`, `delete` без
ошибки; чужой bucket без прав — `ObjectStorageUnavailable` и
«denied access» у всех четырёх, `head` — не 500; неверный секрет —
«rejected credentials».
- [x] 7.4 S2. `run_isolated.py` после `fs.rm -r` проверяет `fs.ls`
префикса: остались записи или вывод `weed shell` с ошибкой — уборка
неуспешна, код 1, команда называет префикс. Проверка:
- разовым скриптом записать `test_<db>/probe`: проверка остатков до
удаления сообщает об остатке, после `remove_objects` — нет;
- `weed shell` с ошибкой при коде 0 (временный стенд) — `remove_objects`
бросает;
- `make test_isolated` — уборка префикса в выводе, без
«cleanup failed».
- [x] 7.5 S3. `test_readiness_without_object_storage` — для `stop` и
`pause` (параметр): готовность и `live` 200 быстрее секунды. Проверка:
`make failure_checks FAULT_ARGS='-k object_storage'` — 2 прошли; полный
`make failure_checks` — красное только по списку в шапке.
- [x] 7.6 S4. `make s3_check` берёт слушающие сокеты контейнера `s3`
(`netstat -tln` в контейнере) вместо списка `S3_CLOSED_PORTS`:
слушающие не на loopback — ровно {`S3_PORT`, `S3_PORT` + 10000},
остальные слушающие порты из сети стенда закрыты (`nc -z`). Проверка:
- на стенде — код 0, в таблице список слушающих портов;
- отрицательная: временный стенд с `-ip.bind=0.0.0.0` у `s3` —
код 1, названы лишние порты.
- [x] 7.7 `make lint`, `make check`, `openspec validate s3-storage
--strict`, `make s3_check`, `make failure_checks`, `make
test_isolated` (красное — по списку в шапке); стенд `mtusi-lab4`
работает. Затем показать изменения, предложить сообщение коммита и
остановиться: evidence снимается с закоммиченного кода.
- [ ] 7.8 Evidence с закоммиченного кода группы 7, без секретов, с
датой, commit и стендом:
- `evidence/s3/restart.md` — первая запись после рестарта и `kill`
(`first_write.py`);
- `evidence/s3/client.md` — удалённый bucket, отказ в доступе,
отсутствующий ключ (`s1_check.py` на временном стенде);
- `evidence/s3/privacy.md` — `make s3_check` со слушающими портами и
отрицательная проверка;
- `evidence/tests/` — `make failure_checks` (оба варианта новой
проверки) и строки уборки `make test_isolated`;
- строки `REPORT.md`, которые ссылаются на эти файлы.
Проверка: `grep` по значениям секретов из `.env` в `evidence/` пуст;
`make lint`, `make check`, `openspec validate s3-storage --strict`.