# 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:`: `CACHE_KEY_PREFIX`, `chat_cache._key`, `Cache.namespace` равен имени базы. У `make test_isolated` база — `test_`. - Токен — `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=`. Разбор — `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::chat:`: - начало ключа — копия `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::chat:*` и `messenger:v1:test_: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_` до часа (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('', '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 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`: ```python 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:** ```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 (slot api-N: stop Ns, exit N)`; - или `removed new (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-<метка>- <образ>`. - Лимиты — как у реплики `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 | 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= --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 `: | # | Содержимое | Сообщение | |---|---|---| | 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 удаляет данные рабочего стенда]** → как в прошлый раз; бриф это разрешает, стенд поднимается заново. ## Migration Plan - **Рабочий стенд.** Новый код — `make rolling_update`, без простоя; миграций и схемы change не трогает. Стенд отказов и `bench/` берут изменения при следующем прогоне. - **Откат.** `git revert` коммитов change и `make rolling_update`. Схема и данные не меняются, поэтому откат кода безопасен в любую сторону. - **Следующая лаба.** Переносятся `src/infra/early_stop.py`, команды драйвера, правки тестов и стендов. Доказательства исключений снимаются заново на её стенде: иначе сверка покрытия не пройдёт.