- 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>
22 KiB
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 пока нет», имена skeletonS3_*в ней остаются.make env_setupподставляет случайные hex в пять пустых значений нового.env, существующий не трогает. Рабочий.envагент не читает: строки S3 в него добавляет пользователь или агент с его согласия (PLAN.md, «Вопросы»). Проверка:- во временном каталоге с копиями
Makefile,.env.exampleиconfig_example.tomlmake 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:s3healthy, журнал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 shells3.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 s3weed shellfs.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.
Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл.
- роль S3 и её граница (байты вложений с change
-
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: healthchecks3вdocker-compose.ymlиPROBES["s3"]вstudent-tests/fault_hook.pyдобавляют проверку/dir/statusmaster (непустой список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; отсутствующий ключ —headNone,openStoredObjectMissing,deleteбез ошибки; чужой bucket без прав —ObjectStorageUnavailableи «denied access» у всех четырёх,head— не 500; неверный секрет — «rejected credentials».
- до правки: удалённый bucket —
-
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(параметр): готовность иlive200 быстрее секунды. Проверка: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.