Files
mtusi2026lab3/openspec/changes/fix-known-issues/design.md
T
2026-10-13 17:54:29 +03:00

56 KiB
Raw Blame History

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_signals uvicorn возвращает прежние обработчики и повторяет пойманные сигналы 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 и прежние не возвращает;
    • воркер порождается через multiprocessing spawn. 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.

Запись 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 design rolling-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"):. При Swapouts 0 в конце прогона поле не пишется.
  • 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 — сценарии «Чтение из кэша», «Срок записи», «Временная база»:

  1. Два синтетических пользователя (alice_<метка>, bob_<метка>), вход обоих по Basic. alice создаёт чат с участниками [bob, alice].

  2. Ключ — 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 как в ответе на создание. Печать — да/нет, без названия чата.
  3. DEL ключа: первое чтение будет промахом, как в лабе 2. Ожидание 11 с, затем снимок:

    • seq_scan + idx_scan таблицы chats (pg_stat_user_tables);
    • keyspace_hits и keyspace_misses (INFO stats).
  4. 50 × GET /api/v1/chats/{id} от bob через LB:

    • все 200 и равны ответу на создание;
    • распределение по X-Instance-Id: читали обе реплики.

    Между снимками драйвер к ключу не обращается: EXISTS, TTL и GET Valkey тоже считает в keyspace_hits.

  5. Ожидание 11 с, второй снимок, приросты. Ожидается: чтений chats — 1, keyspace_hits — +49, keyspace_misses — +1.

  6. Срок после окна: TTL (tₐ), ещё 10 чтений через LB, снова TTL (t_b). Чтения срок не продлевают: t_b ≤ tₐ. Если бы продлевали, t_b вернулся бы почти к настроенному сроку, а tₐ к этому моменту уже на ≥ 11 с меньше его.

  7. Число ключей по префиксам messenger:v1:<db>:chat:* и messenger:v1:test_<db>:chat:* (--scan --pattern, счётчики попаданий не трогает).

  8. Код 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 — сценарии «Токена нет в хранилище» и «Хэш в БД»:

  1. Синтетический пароль P: случайный, не короче 24 символов, с : и кириллицей; живёт только в памяти. Два пользователя с P, вход первого → токен T.
  2. 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').
  3. pg_dump --data-only рабочей базы — в память. Что печатается: число блоков COPY, встречается ли T (текстом и в hex), встречается ли P — да/нет. Сам дамп никуда не пишется.
  4. Код 0, только если:
    • оба префикса — $argon2id$;
    • хэши различаются;
    • ровно одна сессия, token_hash 32 байта и равен 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_signals uvicorn: и в контейнере, и в воркере 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 и не 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.

  • Кто остановил: 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 и причины.

  • «До» — образ 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 секунд;
    • кода больше, а закрывает только это действие.
  • 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 в tasks profile-resources;
    • meta.json итоговой быстрой метки.
  • Код ячеек серий не трогается. Метки не правятся (proposal, Non-goals).

14. Порядок, коммиты, evidence, документы

Порядок задан потребностями стендов:

  1. bench/, записи 5 и 3. Рабочий стенд на время прогонов остановлен, дерево чистое: паспорт пишет git.dirty.
  2. Стенд отказов, запись 4. От рабочего стенда не зависит.
  3. Приложение, запись 2:
    • сначала команда stop-at-start, «до» — на commit с ней;
    • затем исправление, make rolling_update рабочего стенда под нагрузкой, «после», проверки консоли.
  4. Исключения, запись 1: команды драйвера, затем make test_isolated и команды на окончательном коде приложения; сверка ссылок — commit, красный прогон; затем файлы evidence — зелёный.
  5. Регрессия на итоговом коде, документы, проверка из чистого 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. Без --timeout docker stop контейнера docker run на Docker Desktop 29.8.2 ждёт ~3,1 с, а не 10 с (проба: процесс-PID 1 без обработчика, StopTimeout не задан). Первый прогон «до» дал 3,1 с и код 137. Команда шлёт docker stop --timeout 10 (stop_grace_period compose) — отдельный commit f6052f6 между 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, команды драйвера, правки тестов и стендов. Доказательства исключений снимаются заново на её стенде: иначе сверка покрытия не пройдёт.