- 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>
342 lines
22 KiB
Markdown
342 lines
22 KiB
Markdown
# 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`.
|