# 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_/` в начале и в уборке (`docker compose exec -T s3` + `weed shell` `fs.rm -r`). Префикс собирается только из проверенного имени временной базы, иначе отказ. При `KEEP_TEST_DB=1` префикс остаётся, и команда его печатает. Проверка: - перед прогоном разовым скриптом записать `test_/probe` и `/probe`; - `make test_isolated` (красное — по списку в шапке) — в выводе уборка префикса, `test_/probe` нет, `/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_/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`.