56 KiB
Design
Context
Мотивация — proposal.md, раздел Why. Требования — дельты спеков
graceful-shutdown, student-tests и load-benchmark. Ниже — то, что
выяснено разведкой на f74a3f3, по записям KNOWN_ISSUES.md.
Запись 1. Исключения сверки покрытия.
- В
student-tests/spec_coverage.py,EXCLUDED, пять записей ссылаются наevidence/cache/hits.mdиevidence/auth/passwords-and-tokens.md. - В лабе 2 эти файлы снял разовый stdlib-скрипт, который в репозиторий
не попал: в шапках файлов лабы 2 так и написано — «Клиент: разовый
stdlib-скрипт».
evidence/в новую лабу не переносится (AGENTS.md), и ссылки повисли. test_coverage.pyпроверяет, что у исключения есть причина и способ проверки, но не что файл по ссылке есть. Две другие ссылки исключений живые:evidence/replicas/test-persistence.mdиevidence/idempotency/replay-after-restart.md.- На стенде лабы 3 две реплики делят один Valkey. Карточку пишет реплика, создавшая чат, а читают обе: в лабе 2 этого не было.
Факты для методики, те же, что в лабе 2:
- Простаивающий backend PostgreSQL сбрасывает счётчики таблиц не
сразу, а до 10 с спустя (
PGSTAT_IDLE_INTERVAL). Поэтому снимки — через 11 с после запросов. - Ключ карточки —
messenger:v1:<база>:chat:<id>:CACHE_KEY_PREFIX,chat_cache._key,Cache.namespaceравен имени базы. Уmake test_isolatedбаза —test_<db>. - Токен —
secrets.token_urlsafe(32), 43 символа. Вsessions.token_hashлежит его SHA-256:bytea, 32 байта. - Пароль хранится строкой Argon2id в
users.password_hash. Первые 31 символ —$argon2id$v=19$m=65536,t=3,p=4$: это параметры, соли в них нет.
Запись 2. SIGTERM на старте.
-
Ядро не доставляет процессу init пространства PID сигнал, для которого у того нет обработчика. Исключения — SIGKILL и SIGSTOP от процесса-предка (
pid_namespaces(7)). Сигнал не откладывается, а отбрасывается. -
Путь запуска:
python -m src→src/__main__.py→from src.main import main→main()→uvicorn.run. Импортsrc.mainтянет FastAPI, pydantic, SQLAlchemy, asyncpg, redis, argon2, structlog и настройки. Python сам ставит обработчик только на SIGINT (KeyboardInterrupt); у SIGTERM до uvicorn —SIG_DFL. -
uvicorn 0.54,
uvicorn/server.py:uvicorn.run→Config(...)→config.load_app()→Server.run()→asyncio_run(serve());serve()входит вcapture_signals():signal.signal(sig, handle_exit)для SIGINT и SIGTERM, прежние обработчики сохраняются;- внутри
_serve:config.load()(классы протоколов, ~35 мс на хосте) → «Started server process» →startup(): lifespan startup («Waiting for application startup.», «Started API», «Application startup complete.»),create_server, «Uvicorn running on»; - дальше
if not self.should_exit: main_loop(), затемshutdown(): «Shutting down» → закрыть listener →shutdownсоединениям → ждать задачи доtimeout_graceful_shutdown→ lifespan shutdown → «Finished server process»; - на выходе из
capture_signalsuvicorn возвращает прежние обработчики и повторяет пойманные сигналыsignal.raise_signal. У PID 1 сSIG_DFLповтор ни на что не влияет, и процесс выходит с кодом 0. Так сейчас и завершаются работающие реплики: «exit 0» в строкахrolling-update.sh.
-
Замер на рабочем стенде — журналы реплик после
make run_docker, 2026-10-13:- от
StartedAtконтейнера до «Started server process» — 0,71 с у обеих реплик (лимит 1 CPU); - от него до «Uvicorn running on» — 0,05–0,07 с;
- импорт
src.mainна хосте — 0,54–0,83 с.
Почти весь старт — импорт, и окно, где SIGTERM теряется, — ~0,7 с из ~0,8.
- от
-
Консоль с reload (
make run_dev):uvicorn.runв родителе связывает сокет и запускаетChangeReload.BaseReload.startup()ставит свои обработчики SIGINT и SIGTERM и прежние не возвращает;- воркер порождается через
multiprocessingspawn. Spawn не выполняет__main__пакета в дочернем процессе (multiprocessing.spawn._fixup_main_from_nameпропускает*.__main__). Приложение воркер импортирует уже внутриcapture_signalsсвоегоServer.
-
Обход в
scripts/rolling-update.sh, функцияremove_new:- слот новой реплики, если DNS его уже отдал, — в
maint; - реплика
UP—docker stop --timeout 10; - иначе сразу
docker rm -f. Комментарий ссылается наKNOWN_ISSUES.md.
- слот новой реплики, если DNS его уже отдал, — в
Запись 3. События фазы failover.
Bench.run_phaseпосле фазы зовётstand.events(target_id, started - 5, ended + 1), то естьdocker events --since … --until … --filter container=<id>. Разбор —failover.parse_events. Действие —ACTIONS[mode]:killуstopиkill,pauseуpause; возврат —RESTORES[mode].- Профиль
rolloutуже читает потокStand.project_events(решение 8 designrolling-update). - Демон хранит последние 256 событий всех контейнеров. Проверки здоровья
PostgreSQL, Valkey и HAProxy стенда —
docker execраз в 5 с, по три события (exec_create,exec_start,exec_die): ~1,8 события в секунду. К ним добавляютсяdocker execоркестратора: статистика LB вwait_ready. - Окно от
started - 5до запроса — ~35 с у быстрой фазы, ~60 с у полной.
Запись 4. Стенд отказов.
fault_hook.py,FILL_SHзапускается черезdocker compose exec -dи держитpsql … &детьми своегоsh.CLEAR_FILL_SHубивает этотsh, затем backend'ы сокета ([local]).- Родитель exec-процесса — shim вне пространства PID контейнера.
Поэтому осиротевшие
psqlядро отдаёт init пространства, то есть postmaster с PID 1. psql, чей backend завершён с FATAL, выходит с кодом 2. postmaster PostgreSQL 18 (process_pm_child_exit) считает аварией неизвестного потомка с кодом не 0 и не 1:HandleChildCrash→ «terminating any other active server processes» → «all server processes terminated; reinitializing» → восстановление и сбросpg_stat_database.- Журнал стенда отказов, 2026-10-11:
untracked child process (PID 79) exited with exit code 2сразу послеclear-connections. - Стенд удаляется вместе с журналом:
run_failures.py,cleanup→down -v.
Запись 5. Паспорт метки.
bench/run.py, конецmain():if state.get("swapouts") is not None and end_state.get("swapouts"):. ПриSwapouts0 в конце прогона поле не пишется.swap_warningиbench/compare.pyсчитают прирост сами, изstartиend, и не страдают. Ячейки серий (host_swapouts) проверяютis not Noneверно.
Goals / Non-Goals
Goals:
- Каждое исправление доказано «до/после» на закоммиченном коде: дефект воспроизведён, затем его нет.
- Поведение работающей реплики, LB, compose, контракт и методика
bench/не меняются. - Доказательства исключений сверки в следующей лабе снимаются одной командой на файл.
Non-Goals:
- Unit-тесты кода приложения. В проекте только black-box по HTTP
(
student-tests.md); ранний обработчик проверяют команда драйвера и журналы. - Постоянная сверка событий Docker с буфером демона: она нужна один раз, как доказательство (решение 10).
- Правка логики выгрузок в ячейках серий: она верна.
- Автоматическая пересъёмка доказательств исключений в CI: CI skeleton приложение не запускает.
Decisions
1. Исключения сверки — команды драйвера cache-check и auth-storage
Две новые команды .claude/skills/run-mtusi-messenger/driver.py:
- только stdlib и синтаксис Python 3.9;
- только против стенда с LB:
no_lb(port)→ код 1, как уhang-key; - проект — рабочий стенд из
docker-compose.yml, помощникcompose().
cache-check — сценарии «Чтение из кэша», «Срок записи»,
«Временная база»:
-
Два синтетических пользователя (
alice_<метка>,bob_<метка>), вход обоих по Basic. alice создаёт чат с участниками[bob, alice]. -
Ключ —
messenger:v1:<POSTGRES_DB>:chat:<chat_id>:- начало ключа — копия
CACHE_KEY_PREFIX, как вfault_hook.py; - имя базы —
printenv POSTGRES_DBконтейнера postgres.
Сразу после 201:
EXISTS→ 1: карточка записана после commit;TTL→ t₀;- настроенный срок —
[cache] chat_ttl_seconds, прочитанный в реплике (docker compose exec -T api python -c …): это значение с учётом смонтированногоconfig.toml; - значение: ключи JSON — ровно
id,title,member_ids,created_at, порядокmember_idsкак в ответе на создание. Печать — да/нет, без названия чата.
- начало ключа — копия
-
DELключа: первое чтение будет промахом, как в лабе 2. Ожидание 11 с, затем снимок:seq_scan + idx_scanтаблицыchats(pg_stat_user_tables);keyspace_hitsиkeyspace_misses(INFO stats).
-
50 ×
GET /api/v1/chats/{id}от bob через LB:- все 200 и равны ответу на создание;
- распределение по
X-Instance-Id: читали обе реплики.
Между снимками драйвер к ключу не обращается:
EXISTS,TTLиGETValkey тоже считает вkeyspace_hits. -
Ожидание 11 с, второй снимок, приросты. Ожидается: чтений
chats— 1,keyspace_hits— +49,keyspace_misses— +1. -
Срок после окна:
TTL(tₐ), ещё 10 чтений через LB, сноваTTL(t_b). Чтения срок не продлевают: t_b ≤ tₐ. Если бы продлевали, t_b вернулся бы почти к настроенному сроку, а tₐ к этому моменту уже на ≥ 11 с меньше его. -
Число ключей по префиксам
messenger:v1:<db>:chat:*иmessenger:v1:test_<db>:chat:*(--scan --pattern, счётчики попаданий не трогает). -
Код 0, только если:
- чтений таблицы
chatsне больше 1; keyspace_hitsвыросли не меньше чем на 49, промахов не больше 1;- все 60 ответов — 200 и равны ответу на создание;
- 0 < t₀ ≤ настроенного срока, t_b ≤ tₐ < t₀;
- не меньше двух
X-Instance-Id.
Иначе — код 1 и название нарушенного факта.
- чтений таблицы
Для «Временной базы» перед командой нужен make test_isolated при
запущенном рабочем стенде. Его ключи лежат под test_<db> до часа
(TTL): база удалена, ключи остались. Рабочий ключ добавляет сама
cache-check.
auth-storage — сценарии «Токена нет в хранилище» и «Хэш в БД»:
- Синтетический пароль P: случайный, не короче 24 символов, с
:и кириллицей; живёт только в памяти. Два пользователя с P, вход первого → токен T. - psql, SQL через stdin. Значения — синтетические username
(
[a-z0-9_]) и hex, их можно вставлять в текст, как вhang-key. Что читается:left(password_hash, 31)иlength(password_hash)обоих;- неравенство двух хэшей;
count(*)иoctet_length(token_hash)строк, гдеtoken_hash = decode('<SHA-256(T) hex>', 'hex').
pg_dump --data-onlyрабочей базы — в память. Что печатается: число блоковCOPY, встречается ли T (текстом и в hex), встречается ли P — да/нет. Сам дамп никуда не пишется.- Код 0, только если:
- оба префикса —
$argon2id$; - хэши различаются;
- ровно одна сессия,
token_hash32 байта и равен SHA-256(T); - ни T, ни P нет в дампе.
- оба префикса —
Вывод обеих команд. Без T, P, хэшей и их частей длиннее
31-символьного префикса. Username — началом с многоточием (alice_…).
Абсолютных путей нет. Пользователи и чаты остаются в рабочей базе, как
у остальных команд драйвера.
Почему драйвер, а не команды в tasks:
- Секреты не покидают память процесса. В shell они оказались бы в переменных, командных строках и журнале агента, и evidence пришлось бы чистить руками.
- Корень дефекта — разовый скрипт лабы 2, который не переехал. Теперь в следующей лабе каждое исключение снова доказывается одной командой (вместе с решением 2).
- Тонкости методики записаны один раз: ожидание 11 с,
DELперед чтениями, оба счётчика таблицы, ключи по префиксам. - В драйвере уже есть помощники стенда (
compose,PSQL,call,no_lb). Прецедент прямого доступа к psql и контейнерам —hang-keyиidle-conns.
Альтернативы:
- Команды psql, valkey-cli и curl в tasks — отвергнуто: секреты в shell и журнале, проверка не воспроизводится.
- Ссылка на файлы репозитория лабы 2 с commit — отвергнуто: там другой стенд (одна реплика без LB), а доказательства каждой лабы лежат в её репозитории.
- Тесты
student-tests/с доступом к docker — отвергнуто: набор только black-box (student-tests.md). Исключения и существуют потому, что этого по HTTP не увидеть. - Одна команда на оба файла — отвергнуто: разные сценарии и файлы, отказ одной части не должен прятать другую.
2. Сверка покрытия падает на ссылке на отсутствующий файл
spec_coverage.missing_evidence(excluded, root)находит вExclusion.checkпути видаevidence/….md(регулярное выражение) и возвращает проблемы для отсутствующих файлов: «exclusion refers to missing <путь>: / <сценарий>».test_coverage.py:- тест на настоящем
EXCLUDEDи репозитории; - тест функции на временном каталоге: нет файла — проблема, есть —
нет. Образец —
test_stale_exclusion_fails.
- тест на настоящем
- Тесты идут в
make student_testиmake test_isolated. HTTP им не нужен, но сессионная фикстура_server_reachableпо-прежнему требует живой сервер. - Тексты
checkпяти исключений называют команды:driver.py --port <LB> cache-check,auth-storage, а для «Временной базы» —make test_isolated, затемcache-check. - Новые сценарии дельт этого change — в
graceful-shutdown,student-testsиload-benchmark. Этих capability нет вCAPABILITIESсверки, поэтому тестов и исключений для них не нужно, и числа сверки (137 / 125 / 12) не меняются.
Следствие для лабы 4: evidence/ не переносится, и сверка будет
красной, пока доказательства не сняты на новом стенде. Так задумано:
дефект появился именно из-за тихо повисших ссылок. В AGENTS.md,
«Переход в следующую лабу», — какие команды снимают каждый файл.
Альтернативы:
- Предупреждение вместо падения — отвергнуто: строки вывода и пропуски не читают, и это та же тишина.
- Проверка в
make check— отвергнуто: это цель skeleton, её не меняем. - Без проверки — отвергнуто: дефект повторится при переносе.
3. Ранний обработчик — модуль src/infra/early_stop.py
-
Только stdlib:
os,signal,json,time. Ни настроек, ни логгера, ни других модулейsrc. Функцииinstall()иdisarm()и флаг модуля. -
Почему
src/infra/. Это инфраструктура процесса, аsrc/infra/__init__.pyпустой: импорт стоит только сам модуль. Клиентом хранилища модуль не является: глобального клиента нет,dependencies.pyего не импортирует. -
Почему не в самом
src/__main__.py.disarm()зовёт lifespan вsrc/main.py, а приpython -mмодульsrc/__main__.py— это__main__. Импортsrc.__main__изmain.pyвыполнил бы вторую копию модуля. -
src/__main__.py:if __name__ == "__main__": from src.infra import early_stop early_stop.install() from src.main import main main()Импорты внутри
if: правило E402 ruff смотрит на уровень модуля, а простой импортsrc.__main__обработчики не ставит. -
disarm()— первая строкаlifespanвsrc/main.py. Lifespan — первый код приложения, который выполняется внутриcapture_signalsuvicorn: и в контейнере, и в воркере reload. Вызов вmain()передuvicorn.runбыл бы рано: доcapture_signalsещё создаютсяConfig,Serverи цикл событий, и в этом окне сигнал снова терялся бы.
Альтернативы:
- Флаг, который uvicorn проверит после старта (
KNOWN_ISSUES.md) — отвергнуто:uvicorn.runне отдаёт объектServer: пришлось бы собиратьConfigиServerсамим и отдельно поддерживать путь reload;- выход ждал бы конца импорта (~0,7 с), хотя дожидаться нечего.
init: true(tini) уapi— отвергнуто: сервер перестаёт быть PID 1, а этого требуютdocker.mdи спекcontainer-image.- Другой сигнал остановки (
STOPSIGNAL) — не помогает: PID 1 теряет любой сигнал без обработчика.
4. Семантика по окнам старта
| Окно | Обработчик | Что происходит | До выхода | Код |
|---|---|---|---|---|
0. Запуск интерпретатора до install(), десятки мс |
нет: SIG_DFL у PID 1 |
сигнал отброшен, как сейчас; страховка — решение 7 | — | — |
A. Импорт приложения, Config, Server, создание цикла; ~0,7 с в контейнере с 1 CPU |
early_stop |
запись info, os._exit(0). Listener нет, соединения с БД и Valkey ленивые и не открыты, запросов нет — дожидаться нечего |
миллисекунды | 0 |
B. От capture_signals до «Uvicorn running on»; ~0,05–0,1 с |
uvicorn | should_exit, старт доводится, main_loop пропущен, сразу shutdown(). В журнале «Shutting down», «Stopped API», «Finished server process» |
~0,2 с | 0 |
| C. Работа | uvicorn | как сейчас: дренаж до graceful_shutdown_seconds |
как сейчас | 0 |
D. После выхода из capture_signals |
early_stop (его вернул uvicorn), снят disarm() |
повтор сигнала uvicorn raise_signal → обработчик ничего не делает → uvicorn.run и main() возвращаются |
— | 0 |
- B. Listener живёт миллисекунды. Слот LB начинает в
DOWN(init-state down) и включается послеrise 2проверок, поэтому запрос до реплики не доходит. Окно B и до change обрабатывал uvicorn. - D. Без
disarm()возвращённый обработчик после штатной остановки записал бы «до старта» и вызвалos._exit, а это неверно. С ним работающая реплика выходит, как раньше, с кодом 0. Раньше у PID 1 так же ничего не делалraise_signal. - Граница внутри
capture_signals. Обработчики SIGINT и SIGTERM uvicorn ставит по очереди. Сигнал в этот миг попадает тому обработчику, что стоит сейчас; оба исхода — остановка с кодом 0.
5. Выход — os._exit(0), код 0, запись info
-
os._exit, а неsys.exit. Обработчик может сработать посреди импорта.SystemExitраскручивался бы через частично инициализированные модули, его мог бы пойматьexcept BaseExceptionбиблиотеки, сработали быatexitполуимпортированных пакетов. В окне A закрывать нечего: ни сокетов, ни соединений, ни буферов — запись уходит черезos.write. -
Код 0:
- работающая реплика с PID 1 выходит с кодом 0: повтор SIGTERM uvicorn игнорируется. Один код у «остановлена по запросу» на любом этапе;
rolling-update.shчитает 0 как штатную остановку, 137 — как SIGKILL по сроку;- 143 (128 + SIGTERM) инструменты, которые смотрят на код выхода
(
--exit-code-from,service_completed_successfully), приняли бы за сбой. Нового это не сообщает: что остановка была до старта, говорит запись журнала; - в консоли SIGINT на старте теперь даёт 0 вместо traceback
KeyboardInterruptи кода 130.
-
Запись — одна строка JSON:
{"event": "Stopped API before startup", "instance_id": "…", "module": "startup", "signal": "SIGTERM", "level": "info", "timestamp": "…Z"}- Порядок ключей — как у записей structlog:
reorder_keysставитeventиinstance_idпервыми. instance_id—APP__INSTANCE_IDиз окружения илиos.uname().nodename. По умолчанию это то же значение, что[app] instance_id:settings.mdзапрещает задавать его вconfig.toml,.envи compose. В compose это короткий ID контейнера, то естьX-Instance-Id.timestamp—time.time()в ISO 8601 UTC с микросекундами иZ, как уTimeStamper(fmt="iso", utc=True).
- Порядок ключей — как у записей structlog:
-
Почему не structlog и не
get_logger(). Логгер настраивается при первомget_logger(), то есть во время импорта настроек. Сигнал может прийти посреди импорта именно этих модулей, и импорт в обработчике получил бы частично инициализированные модули. Запись — по возможности: ошибка записи не мешает выходу (try/finally). -
Уровень
info. Остановку запросил оператор, и она выполнена верно; исправлять нечего.warningвlogging.md— «обработано, но требует внимания». Тот же уровень, что у «Started API» и «Stopped API». -
Спек
service-loggingвыполняется: JSON сtimestamp,level,eventиinstance_id.
6. Консоль и reload
install()выполняется только в главном процессе: блокif __name__ == "__main__".make run_dev:- родитель-reloader импортирует приложение под ранним обработчиком. Ctrl+C на старте даёт код 0 и запись вместо traceback;
- затем
BaseReload.startup()ставит свои обработчики, и reload и Ctrl+C работают как раньше; - воркер
src/__main__.pyне выполняет, обработчики у него — из своегоcapture_signals.disarm()в его lifespan только ставит флаг в его копии модуля.
- Пути
driver.py start/stop,make test_isolatedиmake failure_checksне меняются: они останавливают уже работающий процесс. - Проверка:
driver.py allв консоли;- reload по
touch src/main.py; - SIGTERM и SIGINT консольному процессу во время импорта.
7. rolling-update.sh: docker rm -f остаётся только для реплики без слота
Сейчас remove_new делает так: есть слот — maint; реплика UP —
штатная остановка; иначе — docker rm -f. Причина rm -f — потерянный
SIGTERM.
Станет:
- Слот есть →
maint→docker stop --timeout 10→docker rm -f→ адрес ушёл из слота →ready.- С ранним обработчиком стартующая реплика выходит за миллисекунды (окно A) или за ~0,2 с (B). Работающая, но не готовая — дорабатывает запросы.
- Запросы, которые LB успел отправить на слот между чтением его
состояния и
maint, получают ответ, а не 502 от убитого процесса. Слот мог статьUPв эти ~0,2 с — например, при Ctrl+C во время ожидания готовности.
- Слота нет → сразу
docker rm -f:- без слота LB запросов не посылал, и kill безопасен;
- это страховка на окно 0 (до
install()), где SIGTERM по-прежнему отброшен. Адрес в слот LB берёт из DNS при очередном разрешении (раз в ~1 с), а окно 0 — десятки миллисекунд. Поэтому сбой замены в окне 0 почти всегда застаёт реплику без слота.
- Если окно 0 всё же совпало со слотом, слот уже в
maint:docker stopдождётся срока 10 с и SIGKILL, но запросов на реплике нет. Это только дольше, не ошибка клиента. - Строка скрипта:
removed new <id> (slot api-N: stop Ns, exit N);- или
removed new <id> (no slot: docker rm -f).
- Требование
load-balancing«Сбой поочерёдной замены» выполняется, как раньше: новая реплика удалена, код ненулевой, работаютAPI_REPLICASрепликUP, слоты без ручного состояния.
Альтернативы:
- Только правка комментария — отвергнуто: гонка с запросами в полёте
остаётся, а причина
rm -fдля пути со слотом больше не верна. - Убрать
rm -fсовсем — отвергнуто: остаются окно 0 и зависший старт.
8. Воспроизведение — команда драйвера stop-at-start
driver.py stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]:
-
Контейнер.
docker run -d --network none --cpus 1 --memory 512m --memory-swap 512m --label mtusi.stop-at-start=<метка> --name mtusi-stop-at-start-<метка>-<n> <образ>.- Лимиты — как у реплики
apiв compose. - Без сети: приложение стартует без БД (соединения ленивые),
/health/readyотвечает 503 — здесь он не нужен. config.tomlне монтируется: без него приложение стартует на дефолтах (docker.md).- Проекты compose команда не трогает. Её контейнеры удаляются в
finally(docker rm -fпо метке).
- Лимиты — как у реплики
-
Момент остановки:
- пауза после возврата
docker run; - или с
--server-start—docker logs -fдо строки «Started server process» и сразуdocker stop(окно B).
docker stop— со сроком по умолчанию 10 с, какstop_grace_period. Время команды измеряется. - пауза после возврата
-
Часы — ВМ Docker:
- поток
docker eventsпо метке, запущенный до первого контейнера:start,killс сигналом 15,dieсexitCode; timestampстрок журнала (часы контейнера — те же часы ВМ).
Отсюда «сигнал через» (
kill−start) и «выход после сигнала» (die−kill). - поток
-
Класс попытки — по моменту
killи журналу:- до «Started server process» или без этой строки —
import; - между ним и «Uvicorn running on» —
server-start; - после —
running.
Паузы
import— не дольше 0,4 с: «Started server process» на стенде появляется через ~0,7 с, а до него ещё ~35–80 мс идётconfig.load()уже под обработчиками uvicorn. - до «Started server process» или без этой строки —
-
Кто остановил:
early— в журнале «Stopped API before startup»;uvicorn— «Shutting down», «Stopped API», «Finished server process». -
Строка попытки: номер, «сигнал через», время
docker stop, «выход после сигнала», код выхода, класс, кто остановил, последовательностьeventжурнала (только имена событий). -
PASS — код 0:
- у каждой попытки код выхода 0 и
docker stopне дольше 1 с; - у
server-startиrunningостановилuvicorn; - у
import—early, а записей старта сервера нет. Исключение — узкое окноconfig.load(): сигнал пришёл до первой строки uvicorn, но уже под его обработчиками. Тогда остановилuvicornс полной последовательностью записей, и это тоже PASS; - есть хотя бы одна попытка
import, остановленнаяearly, и однаrunning. Число попавших вserver-startпечатается.
Иначе — код 1 и причины.
- у каждой попытки код выхода 0 и
-
«До» — образ
mtusi-messenger:stop-before, собранныйgit archive <commit до исправления> | docker build -t … -. Ожидается: попыткиimport— ~10 с и код 137, записей остановки нет (дефект воспроизведён);running— код 0. -
«После» — образ
mtusi-messenger:lab3послеmake rolling_update.
Почему команда драйвера. Проверка повторяется в каждой лабе:
остановка по SIGTERM — пункт уровня «4». Драйвер — stdlib, рядом
kill-inflight и hang-key.
Почему не на стенде compose. Это свойство процесса, а образ и
лимиты те же. Рабочий стенд не дёргается. Путь через compose проверяют
make rolling_update и его ветка сбоя (решение 7).
9. События фазы failover — поток по контейнеру цели
Stand.container_events(container, path) -> Popen:docker events --filter container=<id> --format '{{.TimeNano}} {{.Action}} {{index .Actor.Attributes "signal"}}'в файлwork_dir. Фильтр и формат те же, что у прежнегоStand.events, поэтомуfailover.parse_events,ACTIONS,RESTORESи выбор действия и возврата не меняются.run_phase:- поток запускается после
wait_ready()и выбора цели, доk6_console. До действия ≥failover_before_s(5 / 15 с) — CLI успевает подключиться; - поток останавливается (
terminate+wait) послеwait_readyпосле фазы, вfinally, чтобы не утёк при ошибке; - файл разбирается после остановки потока;
Stand.events(буфер) удаляется.
- поток запускается после
- Не найдено действие или возврат — прежний
BenchError«docker events of not found». Это сценарий «Событие не получено» дельтыload-benchmark. - Почему фильтр по контейнеру, а не поток проекта. Сохраняются
прежний набор событий и разбор. У
project_eventsпрофиляrolloutсвой список действий (create,start,kill,die,destroy,exec_start), безpauseиunpause; расширять его — менять путьrollout. - Методика профиля (нагрузка, окна, лимиты, пороги) не меняется, метки
остаются сравнимыми.
baselineиresourcesне переснимаются (proposal, Non-goals).
10. Сверка двух способов на одном прогоне
- Временный commit. В
run_phaseпосле событий из потока — тот же запрос к буферу, что раньше: метод возвращается в этом commit. Сверка TimeNano действия и возврата:- равны — строка «cross-check: stream = buffer» с моментами;
- в буфере их нет — «cross-check: buffer lost the events»;
- различаются —
BenchError.
- Прогон 1:
make bench_failover_quickбез помех. Ожидается «stream = buffer» во всех четырёх фазах. Величины фазы считаются от этих моментов, значит, они те же, что дал бы прежний способ. - Прогон 2: то же под шумом — цикл
docker exec mtusi-bench-valkey trueбез паузы всё время прогона. Это ~30 событий в секунду, буфер покрывает ~8 с. Ожидается хотя бы одна фаза с «buffer lost»: прежний способ упал бы на «docker events … not found». Фазы при этом завершаются. - Затем
git revertвременного commit и итоговыйmake bench_failover_quickна окончательном коде. - Почему временный commit и revert, а не постоянная сверка.
Окончательный код от буфера не зависит вовсе. Порядок «пробное
изменение — отдельный commit, откат —
git revert» уже принят (bench.md, «Измеренное состояние — commit»). Commit сверки воспроизводим из истории. - Почему шум на Valkey. Он не на горячем пути (кэш карточки), в
образе Debian есть
true, имя контейнера постоянное (mtusi-bench-valkey).
11. Стенд отказов — init: true у PostgreSQL
failures.compose.yml:postgres: init: true. Docker запускаетdocker-init(tini) с PID 1, entrypoint и postmaster — его потомки. Сирот пространства PID подбирает tini и молча их реапит. postmaster видит только своих потомков.- Сигналы и действия hook:
docker compose stop postgresшлётSTOPSIGNALобраза (SIGINT) tini, тот передаёт его потомку → fast shutdown, как раньше;pause/unpause— заморозка cgroup, init её не меняет;KILL_TCP_SHиCLEAR_FILL_SHищут процессы с заголовкомpostgres: …; командная строка tini под шаблон не попадает.
- Только стенд отказов. Рабочий стенд и
bench/фоновых процессов в контейнере PostgreSQL не запускают:docker exec … psql— на переднем плане, сэмплер — в своём контейнере.
Альтернативы:
waitвFILL_SHи kill группы процессов вCLEAR_FILL_SH— отвергнуто:- kill группы убивает
sh, покаpsqlещё живы, и они снова сироты, теперь убитые сигналом — та же авария; - ловушка TERM с циклом
waitдаёт гонку: цикл успевает запустить ещё одинpsqlпосле освобождения слотов, и тот держит слот$1секунд; - кода больше, а закрывает только это действие.
- kill группы убивает
psqlна переднем плане без фона — невозможно: нужны N параллельных сессий.init: trueвdocker-compose.ymlвсем сервисам — отвергнуто: меняет рабочий стенд без нужды.
Правило docker.md «сервер — PID 1» касается образа API. Почему у
PostgreSQL стенда отказов init — в student-tests.md и в шапке
override.
12. Проверка журнала PostgreSQL в run_failures.py
- Когда. После pytest и до уборки, только если pytest запускался: не при сбое подготовки и не при прерывании.
- Что.
docker compose -p <проект> -f … logs --no-log-prefix postgres, число строк с признаками аварии:untracked child process;terminating any other active server processes;reinitializing;automatic recovery in progress.
- Сводка печатается после каждого прогона проверок, с признаками и
без:
postgres log: N lines, crash markers 0; "too many clients" X, "administrator command" Y. Два последних числа доказывают, чтоfill-connectionsиclear-connectionsправда работали. - Признаки есть — найденные строки (не больше 20),
results["postgres"] = 1и ненулевой код.
Почему постоянная проверка, а не опция «сохранить журнал»:
- доказательство — в обычном выводе команды;
- защита от регрессии: любой будущий фоновый процесс в контейнере PostgreSQL проявится сразу;
- новой переменной
Makefileне нужно.
«До» — на закоммиченном коде. Сначала commit проверки: прогон
красный, признаки найдены. Затем init: true: зелёный.
В журнале PostgreSQL секретов нет: log_connections выключен,
выражения — с $n, данные синтетические. Выводятся только строки
признаков.
13. swapouts_delta
swapouts_delta(start, end) -> int | None:None, если одного из счётчиков нет; иначеend − start, в том числе 0.swap_warningсчитает через неё, результаты прежние.main()пишет поле, когда значение неNone.- Проверка:
- однострочник с импортом
bench/run.py, какlevel4_budgetв tasksprofile-resources; meta.jsonитоговой быстрой метки.
- однострочник с импортом
- Код ячеек серий не трогается. Метки не правятся (proposal, Non-goals).
14. Порядок, коммиты, evidence, документы
Порядок задан потребностями стендов:
bench/, записи 5 и 3. Рабочий стенд на время прогонов остановлен, дерево чистое: паспорт пишетgit.dirty.- Стенд отказов, запись 4. От рабочего стенда не зависит.
- Приложение, запись 2:
- сначала команда
stop-at-start, «до» — на commit с ней; - затем исправление,
make rolling_updateрабочего стенда под нагрузкой, «после», проверки консоли.
- сначала команда
- Исключения, запись 1: команды драйвера, затем
make test_isolatedи команды на окончательном коде приложения; сверка ссылок — commit, красный прогон; затем файлы evidence — зелёный. - Регрессия на итоговом коде, документы, проверка из чистого clone,
шапка
REPORT.md.
Коммиты — английский conventional style, последняя строка
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>:
| # | Содержимое | Сообщение |
|---|---|---|
| 1 | swapouts_delta |
fix: record a zero swap-out delta in bench passports |
| 2 | поток событий failover |
fix: stream docker events during failover phases |
| 3 | временная сверка | test: cross-check failover events against the daemon buffer |
| 4 | откат 3 | revert: drop the failover events cross-check |
| 5 | проверка журнала PostgreSQL | test: fail fault checks when the stand postgres crashes |
| 6 | init: true |
fix: run the fault stand postgres under an init process |
| 7 | stop-at-start |
feat: add a driver command that stops a starting replica |
| 8 | ранний обработчик, rolling-update.sh |
fix: exit at once on SIGTERM before the server starts |
| 9 | cache-check, auth-storage |
feat: collect cache and auth storage facts with driver commands |
| 10 | сверка ссылок исключений, тексты исключений | test: require evidence files behind coverage exclusions |
| 11 | evidence записи 1 | docs: collect cache and auth evidence on the lab 3 stand |
| 12 | документы и evidence проверок | docs: close the known issues fixed by fix-known-issues |
| 13 | проверка из чистого clone | docs: repeat the clean clone check on the fixed code |
Между коммитами 10 и 11 make student_test красный: это и есть
воспроизведение дефекта записи 1 на закоммиченном коде. Других
прогонов между ними нет.
Evidence:
| Файл | Что показывает |
|---|---|
evidence/cache/hits.md |
make test_isolated, затем cache-check: запись после commit, TTL, 50 чтений через LB, ключи по префиксам баз |
evidence/auth/passwords-and-tokens.md |
auth-storage: префиксы Argon2id, разные хэши, token_hash = SHA-256, ни T, ни P в дампе |
evidence/failover/stop-at-start.md |
stop-at-start «до» и «после»; ветка сбоя rolling-update.sh с новой строкой; коды выхода старых реплик при замене |
evidence/tests/fix-known-issues-checks.md |
самопроверка swapouts_delta; прогоны сверки событий; красный и зелёный make failure_checks; проверки консоли; регрессия на итоговом коде |
evidence/tests/clean-clone-final.md |
переписан на итоговый commit; прошлая проверка — в истории файла |
Документы: правила (решения 2, 5, 7, 9, 11, 12), SKILL.md,
AGENTS.md, REPORT.md, KNOWN_ISSUES.md. Какие факты где — в
tasks.
Risks / Trade-offs
- [Окно 0 остаётся] → это первые десятки миллисекунд жизни процесса,
до первых строк точки входа. Закрыть его может только init. Страховка
—
docker rm -fреплики без слота (решение 7). Ограничение — вREPORT.mdи спеке. - [Запись ранней остановки — не structlog] → набор полей — как у
записей structlog, формат проверяет
stop-at-start(строка разбирается как JSON, естьtimestamp,level,event,instance_id). Исключение описано вlogging.md. - [
os._exitпропускаетatexitи сброс буферов] → в окне A буферов и соединений нет, запись идёт черезos.write. В окне D обработчик снят, и выход штатный. - [
cache-checkсмотрит на счётчики всей таблицы и всего Valkey] → во время команды на рабочем стенде не идут тесты и нагрузка (порядок tasks). Проверки здоровья HAProxy (SELECT 1)chatsне читают. - [Сверка ссылок evidence краснеет в лабе 4 до пересъёмки] → так
задумано, команды пересъёмки названы в
AGENTS.md. - [У PostgreSQL стенда отказов другое дерево процессов, чем на рабочем стенде] → проверяется поведение API, а не PostgreSQL. Различие описано в правиле и в override.
- [Ложное срабатывание проверки журнала] → признаки узкие.
Штатные
stop/startдают «database system was shut down», а не «not properly». Обрыв backend по SIGTERM — FATAL, а не авария. - [Временный commit сверки в истории] → откат — следующим commit, оба названы в evidence.
- [Шум
docker execво время быстрого профиля] → только в прогоне сверки, меткаquick-*в git не идёт. В evidence — частота шума и какие фазы потеряли события в буфере. - [Окно B не попало в выборку
stop-at-start] →--server-startловит его по журналу. Если за 3 попытки ни однойserver-start, повтор с 10. - [
docker stopдольше 1 с на перегруженном хосте] → перед воспроизведением — проверка хоста. На стенде старт B ~0,1 с и остановка ~0,2 с: запас больше двух раз. - [
pg_dumpрабочей базы в памяти драйвера] → в нём хэши; дамп никуда не пишется, печатаются только да/нет и счётчики. - [Проверка из чистого clone удаляет данные рабочего стенда] → как в прошлый раз; бриф это разрешает, стенд поднимается заново.
Найдено в apply
- Срок
docker stopвstop-at-start. Без--timeoutdocker stopконтейнераdocker runна Docker Desktop 29.8.2 ждёт ~3,1 с, а не 10 с (проба: процесс-PID 1 без обработчика,StopTimeoutне задан). Первый прогон «до» дал 3,1 с и код 137. Команда шлётdocker stop --timeout 10(stop_grace_periodcompose) — отдельный commitf6052f6между 7 и 8 (решение 14); «до» переснят на нём: 10,1 с. endedвrun_phase. После перехода на поток переменная не нужна (ruff F841) и удалена в commit 2; временная сверка (commit 3) берёт конец окна буфера какtime.time() + 1в момент сверки — та же точка послеwait_ready.- Посторонний контейнер и батарея. Пользователь разрешил прогоны
bench/иstop-at-startот батареи и рядом сdomains-postgres-1. Его проверка здоровья — раз в 1 с, 2,8 события в секунду в буфере демона, больше проверок стендаbench/(~1,8/с). В прогоне 1 сверки (без помех) буфер всё же держал все 4 фазы (покрытие ~55 с при окне ~35 с); под шумомdocker execпотерял все 4. - Давление памяти уровня 2 держалось ~35 мин посреди apply
(
Swapoutsбез роста). Первый «после»stop-at-startснят при нём — PASS; переснят при уровне 1 послеmake rolling_update, который заодно вернул общий образ тегу и репликам: неуспешные запуски 5.8 пересобирают тег (docker compose buildдаёт новый.Imageи без изменений кода), и.Imageтега расходился с репликами. - Ветка сбоя
rolling-update.sh. ПриROLLOUT_READY_TIMEOUT=1и2оба раза сработал путь со слотом (maint,stop 0s, exit 0): к моменту уборки DNS уже отдал слот. Путь «no slot» в прогонах не выпал. - driver.py на Python 3.9:
zip(strict=)(B905 ruff) недоступен — цикл по одной последовательности.
Migration Plan
- Рабочий стенд. Новый код —
make rolling_update, без простоя; миграций и схемы change не трогает. Стенд отказов иbench/берут изменения при следующем прогоне. - Откат.
git revertкоммитов change иmake rolling_update. Схема и данные не меняются, поэтому откат кода безопасен в любую сторону. - Следующая лаба. Переносятся
src/infra/early_stop.py, команды драйвера, правки тестов и стендов. Доказательства исключений снимаются заново на её стенде: иначе сверка покрытия не пройдёт.