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

22 KiB
Raw Blame History

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. Зависимость и настройки

  • 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.

  • 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 — запуск падает.
  • 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. Стенд

  • 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.
  • 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.
  • 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. Клиент хранилища

  • 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. Стенды проверок и нагрузки

  • 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 префикс остался и напечатан;
    • пробные объекты затем удалить.
  • 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.
  • 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. Документы и проверка кода

  • 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 — без ошибок.

  • 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 и отчёт

  • 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/ пуст.

  • 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.

    Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл.

  • 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 после проверки.

  • 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 проходит.
  • 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 не растёт.
  • 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».
  • 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».
  • 7.5 S3. test_readiness_without_object_storage — для stop и pause (параметр): готовность и live 200 быстрее секунды. Проверка: make failure_checks FAULT_ARGS='-k object_storage' — 2 прошли; полный make failure_checks — красное только по списку в шапке.

  • 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, названы лишние порты.
  • 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.