770 lines
54 KiB
Markdown
770 lines
54 KiB
Markdown
# 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`, команды
|
||
драйвера, правки тестов и стендов. Доказательства исключений
|
||
снимаются заново на её стенде: иначе сверка покрытия не пройдёт.
|