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

770 lines
54 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <путь>: <capability> / <сценарий>».
- `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`:
```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 <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 <instance> 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 удаляет данные рабочего стенда]** → как в
прошлый раз; бриф это разрешает, стенд поднимается заново.
## Migration Plan
- **Рабочий стенд.** Новый код — `make rolling_update`, без простоя;
миграций и схемы change не трогает. Стенд отказов и `bench/` берут
изменения при следующем прогоне.
- **Откат.** `git revert` коммитов change и `make rolling_update`.
Схема и данные не меняются, поэтому откат кода безопасен в любую
сторону.
- **Следующая лаба.** Переносятся `src/infra/early_stop.py`, команды
драйвера, правки тестов и стендов. Доказательства исключений
снимаются заново на её стенде: иначе сверка покрытия не пройдёт.