docs: close the known issues fixed by fix-known-issues

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-13 17:54:29 +03:00
co-authored by Claude Opus 5.5
parent 949bea4222
commit 8fa12f56f7
15 changed files with 680 additions and 201 deletions
+12 -2
View File
@@ -271,8 +271,18 @@ api`, `stop` / `start api`), а не к имени контейнера. `make d
`failover` дренаж не делают: они имитируют отказ.
**Сбой на середине** (`trap` на `EXIT`, `INT`, `TERM`): новая не стала
`UP` за срок — её слот (если DNS уже отдал) в `maint`, `docker rm -f`,
слот `ready`; новая уже `UP` — вывод текущей старой доводится до конца.
`UP` за срок — её убирает `remove_new` (design change
`fix-known-issues`, решение 7):
- слот есть (DNS уже отдал) → `maint` → `docker stop --timeout 10` →
`docker rm -f` → адрес ушёл → `ready`; строка `removed new <id> (slot
api-N: stop Ns, exit N)`. Стартующая реплика выходит сразу по раннему
обработчику SIGTERM (`run-modes.md`), работающая — дорабатывает
запросы, которые LB успел отправить на слот до `maint`;
- слота нет → сразу `docker rm -f`, строка `removed new <id> (no slot:
docker rm -f)`: запросов на ней не было, а это ещё и страховка на окно
запуска интерпретатора, где SIGTERM некому принять.
Новая уже `UP` — вывод текущей старой доводится до конца.
Прерывание внутри `up --scale`, когда ID новой ещё не известен: уборка
находит её сама — контейнер, которого не было до команды. ID новой
прежнего шага сбрасывается до перехода в это состояние: иначе уборка
+15 -1
View File
@@ -171,6 +171,17 @@ paths:
(`docker events`), исключение и возврат в LB — строки журнала HAProxy
(`docker logs -t`), запросы — `Date.now()` k6 при отправке. Часы хоста
с ними не сравниваются.
- События цели — **поток** `Stand.container_events` (`docker events
--filter container=<id>` в `work_dir/<фаза>-events.log`), запущенный
после выбора цели и до k6 и остановленный после возврата в LB, а не
`docker events --since … --until …` после фазы: демон хранит только 256
последних событий всех контейнеров, и проверки здоровья, `docker exec`
оркестратора и чужих проектов их вытесняют. Сверка обоих способов на
одном прогоне: без помех моменты совпали до наносекунды, под шумом
`docker exec` буфер потерял события всех четырёх фаз, поток — ни
одного (design change `fix-known-issues`, решения 9–10;
`evidence/tests/fix-known-issues-checks.md`). Нет события действия
или возврата — отказ с фазой и репликой.
- Каждый запрос — строка `fo,…` в файл консоли k6 (`--console-output`),
а не в вывод `docker exec`: там в самопроверке пропали две строки из
4 601. Число строк сверяется с итерациями сценариев из итога k6,
@@ -486,7 +497,10 @@ paths:
Занятый swap сам по себе не помеха (указание пользователя 2026-10-10):
в него уходят неактивные страницы. Помеха — выгрузка во время прогона:
`run.py` пишет счётчик `Swapouts` (`vm_stat`) в начале и в конце
(`host_state.swapouts`) и предупреждает о приросте; у серий — ещё по
(`host_state.swapouts`), прирост — `host_state.swapouts_delta`
(`swapouts_delta`: пишется и при 0, нет — только без одного из
счётчиков; до change `fix-known-issues` при `Swapouts` 0 в конце поле
пропадало, так у меток `scaling-db-*2`) и предупреждает о приросте; у серий — ещё по
ячейке и ступени (`host_swapouts`, пометка `host_swap`). Давление на
память или батарея — перезагрузить или подключить питание. Состояние
записывается в паспорт (`host_state`), в отчёте оно указывается по
+11
View File
@@ -46,6 +46,17 @@ paths:
- `CMD` в exec-форме: `["python", "-m", "src"]`. Тогда сервер — PID 1 и
сам получает SIGTERM. Не `sh -c "... && ..."` и не `uv run`: это
лишний процесс между docker и сервером.
- PID 1 ядро не доставляет сигнал без обработчика — он отбрасывается.
Поэтому `src/__main__.py` ставит ранний обработчик SIGTERM и SIGINT
(`src/infra/early_stop.py`) до импорта приложения: импорт — почти
весь старт (~0,7 с из ~0,8 при 1 CPU), и без него `docker stop`
стартующей реплики ждал 10 с и кончался SIGKILL
(`evidence/failover/stop-at-start.md`). Окна старта — `run-modes.md`.
- `init: true` (tini) у `api` не ставится: сервер перестал бы быть
PID 1. Остаётся окно запуска интерпретатора — десятки миллисекунд до
первых строк точки входа; `rolling-update.sh` убирает реплику без
слота LB `docker rm -f` (`balancer.md`). У PostgreSQL стенда отказов
init есть — по другой причине (`student-tests.md`).
- `ENV APP__RUN_MODE=docker PYTHONUNBUFFERED=1
PYTHONDONTWRITEBYTECODE=1`, `EXPOSE 8080`.
- `HEALTHCHECK` на `/health/ready` через `python -c "import
+8
View File
@@ -29,6 +29,14 @@ paths:
- `cache/`: `client.py` — фабрика `create_cache` и обёртка `Cache`;
`instance.py` — глобал `cache`. Ключи и формат значений — в repo
(`src/core/repos/chat_cache.py`), не здесь.
- `early_stop.py` — ранний обработчик SIGTERM и SIGINT процесса
(`install()`, `disarm()`): только stdlib, ни настроек, ни логгера, ни
других модулей `src`; клиентом хранилища не является, глобала клиента
нет, `dependencies.py` его не импортирует. Импортируется в
`src/__main__.py` до приложения; `disarm()` — первая строка lifespan
`src/main.py` (а не `main()` перед `uvicorn.run`: до
`capture_signals` сигнал снова терялся бы). Окна старта —
`run-modes.md`, запись — `logging.md`.
- Источник истины — PostgreSQL. SQLite, файлы и память процесса его не
заменяют (`README.md`, п. 2). Кэш не хранит ничего, чего нет в
Postgres: сессии в Valkey не лежат (`auth.md`).
+16
View File
@@ -94,6 +94,21 @@ paths:
`log_config=None` uvicorn при старте применит свой `LOGGING_CONFIG`
поверх нашего. Access-лог пишет свой middleware (`api-layer.md`).
### Исключение: запись ранней остановки
`src/infra/early_stop.py` пишет одну запись мимо structlog: сигнал
пришёл во время импорта приложения, а логгер настраивается при первом
`get_logger()` — как раз во время импорта настроек, и обработчик застал
бы модули полуинициализированными. Запись — одна строка JSON через
`os.write` в stdout, затем `os._exit(0)`; ошибка записи выходу не мешает.
Поля — как у записей structlog: `event` «Stopped API before startup» и
`instance_id` первыми, `module` `startup`, `signal` (`SIGTERM` /
`SIGINT`), `level` `info`, `timestamp` ISO 8601 UTC с микросекундами и
`Z`. `instance_id` — `APP__INSTANCE_ID` или hostname, то же значение по
умолчанию, что `[app] instance_id`. Уровень `info`: остановку запросил
оператор, и она выполнена верно (design change `fix-known-issues`,
решение 5).
## Чего в логах быть не должно
Рубрика уровня 4: логи полезные, но **без содержимого сообщений**.
@@ -119,6 +134,7 @@ paths:
| `api/errors.py` | не логирует: 4xx — штатные ответы, а traceback непредвиденной ошибки пишет uvicorn (`uvicorn.error`, с `request_id` из contextvar) после повторного броска исключения Starlette | нет |
| `infra/<client>.py` | подключение, закрытие, ошибки; запросы к внешним API (`debug`) | `module="<client>"` |
| `main.py` | старт (host, port, режим), начало и конец shutdown | `module="startup"` |
| `infra/early_stop.py` | только остановка до старта сервера, одна запись без structlog (раздел выше) | нет, поле `module` — `startup` |
| чистые функции | не логируют, бросают доменные исключения | нет |
Строки старта и shutdown нужны на защите: по ним видно, что SIGTERM
+27 -4
View File
@@ -27,10 +27,12 @@ README слушал `0.0.0.0`) и литерал в `environment` compose; дл
## Точка входа
`python -m src` → `src/__main__.py` → `src.main:main()` →
`python -m src` → `src/__main__.py` → `early_stop.install()`
(`src/infra/early_stop.py`, до импорта приложения) → `src.main:main()` →
`uvicorn.run("src.main:app", host=..., port=..., reload=...,
timeout_graceful_shutdown=..., timeout_keep_alive=..., log_config=None,
access_log=False)`.
access_log=False)`. Импорты в `src/__main__.py` — внутри `if __name__ ==
"__main__"`: простой импорт модуля обработчики не ставит.
Хост выбирается по режиму, как в bp_proxies. `log_config=None` нужен,
чтобы uvicorn не перетёр JSON-логирование (`logging.md`).
@@ -44,8 +46,29 @@ access_log=False)`.
через 10 с, в compose — `stop_grace_period`. Shutdown в lifespan
только логирует и закрывает клиенты (`engine.dispose()`,
`cache.aclose()`), долгих операций в нём нет.
Рубрика уровня 4 требует завершения не дольше 10 с. С лабы 3 закрытый
сокет остановленной реплики HAProxy видит как отказ соединения и
Рубрика уровня 4 требует завершения не дольше 10 с.
Сигнал на старте (спек `graceful-shutdown`, «Остановка во время
старта»; design change `fix-known-issues`, решения 3–6):
- **окно 0** — запуск интерпретатора до `install()`, десятки мс:
обработчика нет, PID 1 сигнал теряет. Это ограничение;
- **A** — импорт приложения, `Config`, `Server`, цикл событий (~0,7 с
в контейнере с 1 CPU): ранний обработчик пишет одну запись `info`
«Stopped API before startup» и делает `os._exit(0)` — запросов и
соединений ещё нет;
- **B** — от `capture_signals` uvicorn до «Uvicorn running on»:
uvicorn доводит старт и сразу штатно останавливается («Shutting
down», «Stopped API», «Finished server process»), код 0;
- **C** — работа: как описано выше;
- **D** — после выхода из `capture_signals` uvicorn возвращает ранний
обработчик и повторяет пойманный сигнал; `early_stop.disarm()`
(первая строка lifespan) его уже снял, и процесс выходит с кодом 0.
В консоли с reload ранний обработчик есть только у родителя-reloader
(до `BaseReload.startup()`): Ctrl+C на старте — код 0 и та же запись
вместо traceback. Воркер `src/__main__.py` не выполняет (spawn), его
сигналы — от uvicorn. Проверка — `driver.py stop-at-start`.
С лабы 3 закрытый сокет остановленной реплики HAProxy видит как отказ соединения и
перенаправляет запрос на живую; новые запросы на неё перестают идти
после проваленных проверок (`balancer.md`, цепочка таймаутов). Под
нагрузкой `docker stop` реплики ошибок от её недоступности не даёт —
+29 -2
View File
@@ -119,8 +119,21 @@ paths:
- два API на свободных портах `127.0.0.1`: обычный (`BASE_URL`) и
«тесный» (`FAULT_TIGHT_BASE_URL`: сроки сессии и ключа
идемпотентности 2 с, пул 1, короткие таймауты);
- `pytest -m fault`, затем удаление стенда с volume при любом
исходе. Рабочий стенд не трогается;
- `pytest -m fault`, затем журнал PostgreSQL стенда: сводка `postgres
log: N lines, crash markers M; "too many clients" X, "administrator
command" Y` после каждого прогона и ненулевой код при признаках
аварийного перезапуска («untracked child process», «terminating any
other active server processes», «reinitializing», «automatic
recovery in progress») — найденные строки печатаются;
- у `postgres` в override — `init: true`: `fill-connections` держит
`psql` в фоне `sh` из `docker compose exec`, после
`clear-connections` они сироты пространства PID. Без init их
наследовал postmaster (PID 1), считал выход с кодом 2 аварией и
перезапускал PostgreSQL посреди набора (design change
`fix-known-issues`, решения 11–12). Правило `docker.md` «сервер —
PID 1» — про образ API;
- затем удаление стенда с volume при любом исходе. Рабочий стенд не
трогается;
- **два прогона одновременно не запускать** (терминал, IDE, агент):
уборка хвоста в начале второго делает `down -v` стенда первого, и
оба падают с конфликтом имён контейнеров. Блокировки нет намеренно.
@@ -185,6 +198,20 @@ paths:
основном спеке без теста роняет `test_coverage.py`. Если его нельзя
проверить по HTTP даже на стенде отказов, добавить запись в
`EXCLUDED` (`spec_coverage.py`) с причиной и способом проверки.
- **Доказательство исключения — в репозитории этой лабы.** Файл
`evidence/….md`, на который ссылается `check` исключения, должен
существовать: `test_exclusion_evidence_exists` (`missing_evidence`)
падает и называет сценарий и путь. `evidence/` в следующую лабу не
переносится, поэтому там сверка красная, пока файлы не сняты заново
на её стенде. Способ проверки называет команду, которая снимает
доказательство: `driver.py --port <LB> cache-check` (после `make
test_isolated` — для «Временной базы») → `evidence/cache/hits.md`,
`driver.py --port <LB> auth-storage` →
`evidence/auth/passwords-and-tokens.md`; `make test-persistence` →
`evidence/replicas/test-persistence.md`; повтор после `docker compose
up -d --force-recreate api` → `evidence/idempotency/replay-after-restart.md`.
В доказательстве — только факты, счётчики и префиксы, без токенов,
паролей и полных хэшей.
Сценарии тестов `fault` сверка считает покрытыми и печатает их число.
- Модуль сверки называется `spec_coverage.py`, а не `coverage.py`:
каталог набора стоит в `pythonpath`, и `coverage.py` затенил бы
+10 -1
View File
@@ -15,7 +15,10 @@ HAProxy на `APP_OUT_PORT` перед репликами API) работают
драйвера, кроме `start`/`stop`, плюс `instances` — распределение одной
сессии по репликам, `kill-inflight` — kill реплики с запросами в
полёте, `idle-conns` — кто закрывает простаивающие соединения LB →
реплика и `hang-key` — повтор ключа после зависшей реплики. Только
реплика, `hang-key` — повтор ключа после зависшей реплики,
`cache-check` и `auth-storage` — доказательства исключений сверки
покрытия (кэш, хранение паролей и токенов). `stop-at-start` — остановка
контейнеров образа во время старта, без стенда. Только
стандартная библиотека Python 3.9+: `make instances` запускает драйвер
системным `python3` (на macOS — 3.9), поэтому без `datetime.UTC`,
`match` и прочего синтаксиса 3.10+.
@@ -94,6 +97,9 @@ python3 $D stop
| `kill-inflight [--threads 8] [--seconds 4] [--after 1.5]` | только стенд с LB (`--port 8080`): потоки входят по Basic, через `--after` с `scripts/stop-one.sh` в режиме kill убивает реплику пробного запроса. Печатает статусы по репликам и ответы LB: оборванные входы — 502 в формате контракта без повтора, начатые после kill — 201 от другой реплики. Код 1, если оборванных нет. Реплика остаётся остановленной — `make replicas` |
| `idle-conns [--threads 20] [--requests 50] [--keep-alive 60] [--lb C]` | только стенд с LB: всплеск `GET /health/live` через LB с keep-alive соединениями, клиенты остаются подключены и молчат; раз в секунду — установленные соединения на порт API внутри каждой реплики (`/proc/net/tcp`) и пул LB (`idle_conn_cur` + `safe_conn_cur`). Код 0, если реплики остались без соединений раньше `--keep-alive` (`[app] keep_alive_seconds`): закрыл LB по своему `timeout http-keep-alive`, а не реплика; иначе код 1 и «closed by the replica». `--lb C` — контейнер LB, если `--port` ведёт на временный LB с другим вариантом конфигурации перед теми же репликами (`evidence/failover/keep-alive.md`) |
| `hang-key` | только стенд с LB: временный триггер `hang_probe_<метка>` задерживает вставку пробного сообщения на 2 с, реплика с этой транзакцией замораживается `docker pause`, повторы того же `Idempotency-Key` через LB до 201 (сначала 504 от LB или 503 по ожиданию блокировки), разморозка; печатает `idle_in_transaction_session_timeout` соединения приложения и строку журнала PostgreSQL о прерывании. Код 0 — повтор получил 201, в чате одно сообщение, обе реплики снова `UP`. Триггер удаляется и реплика размораживается при любом исходе, в том числе по Ctrl+C, SIGTERM и SIGHUP; если удалить не удалось — печатается SQL удаления и код 1 (от SIGKILL уборки нет) |
| `cache-check` | только стенд с LB (`--port 8080`): сценарии `chat-cache` «Чтение из кэша», «Срок записи», «Временная база». Два синтетических пользователя и чат; ключ `messenger:v1:<база>:chat:<id>` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_<db>`) базы. Код 0 — чтений `chats` ≤ 1, hits ≥ +49, промахов ≤ 1, ответы равны ответу на создание, TTL не продлевается, ≥ 2 `X-Instance-Id`. Для «Временной базы» перед ней — `make test_isolated`. На стенде в это время ничего другого не должно идти. Вывод — `evidence/cache/hits.md` |
| `auth-storage` | только стенд с LB: сценарии `users` «Хэш в БД» и `sessions` «Токена нет в хранилище». Пароль P (с `:` и кириллицей) и токен T — только в памяти; через psql — префикс `$argon2id$…` до соли и длина у двух пользователей с одним P, неравенство хэшей, строка `sessions` с `token_hash` = SHA-256(T) (32 байта); `pg_dump --data-only` в память — нет ли T (текстом и в hex) и P. Код 0 — всё так. Вывод — `evidence/auth/passwords-and-tokens.md` |
| `stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]` | спек `graceful-shutdown` «Остановка во время старта»: контейнеры образа (по умолчанию `mtusi-messenger:lab3`) с лимитами реплики (1 CPU / 512 МиБ без swap), без сети и `config.toml`; `docker stop --timeout 10` через паузу после `docker run` и сразу по строке «Started server process». По потоку `docker events` и журналу: «сигнал через», время `docker stop`, «выход после сигнала», код выхода, этап (`import` / `server-start` / `running`), кто остановил (`early` / `uvicorn`). Код 0 — каждая попытка с кодом 0 и `docker stop` ≤ 1 с, есть `import`, остановленный ранним обработчиком, и `running`. Проекты compose не трогает, свои контейнеры удаляет по метке `mtusi.stop-at-start`. Вывод — `evidence/failover/stop-at-start.md` |
| `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает |
| `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` |
@@ -132,6 +138,9 @@ TARGET_INSTANCE_ID=<x-instance-id> scripts/stop-one.sh # остановить
python3 $D --port 8080 kill-inflight # kill реплики во время входов: 502 от LB без повтора
python3 $D --port 8080 idle-conns # простаивающие соединения с репликами закрывает LB (~10 с), а не реплика (60 с)
python3 $D --port 8080 hang-key # зависшая реплика держит ключ: повтор получает 201 после прерывания транзакции
make test_isolated && python3 $D --port 8080 cache-check # кэш карточки: одно чтение chats на 50, TTL, ключи двух баз
python3 $D --port 8080 auth-storage # Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump
python3 $D stop-at-start # docker stop стартующей реплики: ~0,06 с и код 0 (раньше 10 с и 137)
make bench_failover_quick # отказ каждой реплики под нагрузкой на своём стенде mtusi-bench, ~2 мин
make rolling_update # новый код на реплики без простоя: сборка, миграции один раз, по одной: новая UP → старая drain → stop → rm
make rolling_update COMMIT=<commit> MIGRATE=0 # откат на образ прежнего commit (git archive), схема остаётся новой
+34 -14
View File
@@ -24,10 +24,19 @@ PostgreSQL «too many clients», `scaling-improvement` — пул PostgreSQL
«до/после» с A/A, засчитано с оговоркой), `profile-resources` — CPU и
память каждого компонента по окнам профилей `failover` и `rollout`
(сэмплер `scan`, `bench/resources.py`, метки `resources`; добавлен после
закрытия лабы, код приложения не трогает). Лаба 3 закрыта: все семь
changes лабы 3, как и changes перехода на lab2, — в
`openspec/changes/archive/`, активных changes нет, `REPORT.md` заполнен,
чистый clone проверен (`evidence/tests/clean-clone-final.md`). Дальше —
закрытия лабы, код приложения не трогает), `fix-known-issues` —
исправление пяти записей `KNOWN_ISSUES.md` перед переносом: ранний
обработчик SIGTERM до импорта приложения (`src/infra/early_stop.py`,
`docker stop` стартующей реплики — 0,06 с вместо 10 с и SIGKILL),
поток событий Docker в профиле `failover`, `init: true` у PostgreSQL
стенда отказов и проверка его журнала, `swapouts_delta` при нуле,
доказательства исключений сверки покрытия на стенде лабы 3 (команды
драйвера `cache-check`, `auth-storage`; сверка падает на ссылке на
отсутствующий файл). Лаба 3 закрыта: семь changes лабы 3, как и changes
перехода на lab2, — в `openspec/changes/archive/`, `fix-known-issues` —
восьмой, активный до archive; `KNOWN_ISSUES.md` без открытых записей,
`REPORT.md` заполнен, чистый clone проверен
(`evidence/tests/clean-clone-final.md`). Дальше —
перенос в лабу 4 (раздел «Переход в следующую лабу»). Рабочий план лабы
(`PLAN.md`) удалён, его решения — в `REPORT.md` и design архивных
changes; последняя версия — `git show 063eedb:PLAN.md`. Стек:
@@ -282,7 +291,7 @@ Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
| `make wipe_data` | `down -v` — удалить данные стенда (и кэш); только после ввода `yes` |
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе (`student-tests.md`) |
| `make student_test [BASE_URL=...] [EXPECT_REPLICAS=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); `EXPECT_REPLICAS` (по умолчанию `API_REPLICAS`) — сколько реплик за `BASE_URL`, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом |
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~60 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~60 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; после тестов — журнал PostgreSQL стенда: сводка (`crash markers`, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
| `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (HAProxy и одна реплика API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда; k6 ходит через LB); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) |
| `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт |
| `make bench_restore [RESTORE_LABEL=...]` | трек 2, восстановление (~20 мин, метка `restore` по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — `pg_dump` во время записи через HTTP, активность после backup, `pg_restore -j` в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после `FLUSHALL`; время dump / restore / RTO и потерянные сообщения — в `summary.md` |
@@ -310,7 +319,7 @@ Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
```
src/
__main__.py # python -m src → main.main()
__main__.py # python -m src: early_stop.install() до импорта приложения → main.main()
main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run
config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [idempotency] ttl_seconds
api/
@@ -327,6 +336,7 @@ src/
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ и сообщение одной транзакцией
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py
infra/
early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped API before startup» и выход 0; disarm() — первая строка lifespan
logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи
password.py # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username
db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping
@@ -348,16 +358,16 @@ student-tests/ # black-box тесты по HTTP (уровень 4)
contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, X-Instance-Id, assert_error, assert_replicas
test_idempotency.py # спек idempotency: ключ, повтор, 409, область, порядок кодов, повтор через другую реплику (гонка — test_race.py, отказы — test_failures.py)
test_load_balancing.py # спек load-balancing (вне сверки покрытия): одна сессия на разных репликах, запись видна через другую реплику
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия; missing_evidence — файл evidence по ссылке исключения должен быть в репозитории
test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4
test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
test_failures.py # проверки отказов (маркер fault): только make failure_checks
run_isolated.py # make test_isolated: образ на временной базе test_<db> (stdlib)
run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, уборка (stdlib)
run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), уборка (stdlib)
fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггеры сбоя участников и сообщений, заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions (stdlib)
failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, LB), healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения)
failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, LB), healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster)
bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling
run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover, профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json
run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json
scaling.py # серии трека 1 без docker: лестница и автомат поиска R*, разбор итога k6 и строк сэмплера, агрегаты окна, вердикт SLO и брака генератора, признаки узкого места (THRESHOLDS), предельный CPU на запрос, сводка серии; --selftest
plots.py # make bench_plots: SVG на stdlib (R* от числа реплик, p95 от интенсивности, CPU по компонентам) и сводка с точкой насыщения; render_series — графики в каталоге метки
sampler.sh # сэмплер (только в контейнере mtusi-bench-sampler на образе PostgreSQL, --cgroupns host): режим list (серии) — cpu.stat, память и PSI заданных контейнеров, /proc/stat и PSI ВМ, статистика HAProxy, psql \watch по pg_stat_activity / database / wal / io; режим scan (failover, rollout) — обход cgroup всех контейнеров и /proc/stat, без сети, psql и LB
@@ -382,12 +392,12 @@ docker-compose.yml # проект mtusi-lab3: postgres, valkey, migrat
config_example.toml, .env.example
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции
evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига
evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт
evidence/tests/ # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md; profile-resources-checks.md — проверки сэмплера, быстрые профили, сторож, хост и сравнение меток resources с baseline
evidence/auth/ # passwords-and-tokens.md — driver.py auth-storage на стенде лабы 3: Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump (исключения сверки покрытия)
evidence/cache/ # hits.md — make test_isolated + driver.py cache-check на стенде лабы 3: одно чтение chats на 50 через LB, TTL, ключи двух баз (исключения сверки покрытия)
evidence/tests/ # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md; profile-resources-checks.md — проверки сэмплера, быстрые профили, сторож, хост и сравнение меток resources с baseline; fix-known-issues-checks.md — сверка событий поток/буфер, красный и зелёный failure_checks, консоль, сверка ссылок исключений, регрессия
evidence/idempotency/ # повтор, 409, гонка, таблица ключей, X-Instance-Id
evidence/replicas/ # стенд с LB: порты, лимиты и их цена для Argon2id, окружение, распределение, ответы LB (нет реплик, зависшая, без PostgreSQL), test-persistence, чистый clone на нестандартных портах
evidence/failover/ # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh; замер обнаружения, keep-alive, зависшая реплика и ключ
evidence/failover/ # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh; замер обнаружения, keep-alive, зависшая реплика и ключ; stop-at-start.md — docker stop стартующей реплики «до/после» раннего обработчика и ветка сбоя rolling-update.sh
evidence/failover/<метка>/ # результаты make bench_failover: паспорт, phases.csv, посекундная timeline.csv, summary.md, итоги k6 и журнал LB по фазам; с change profile-resources (метка resources и новые) — resources.csv (фаза × окно × компонент) и samples.csv (посекундно от действия)
evidence/rollout/ # совместимость старого образа с новой схемой, make rolling_update и жизненный цикл стенда после замены, отказы скрипта (Ctrl+C, слоты, lock_timeout миграции)
evidence/rollout/<метка>/ # результаты make bench_rollout: паспорт с контейнерами, образами и ревизией до и после, rollout.csv, replicas.csv, timeline.csv, summary.md, строки скрипта, журнал LB; с change profile-resources (метка resources и новые) — resources.csv (окно × компонент) и samples.csv (посекундно от начала замены)
@@ -484,6 +494,16 @@ KNOWN_ISSUES.md # найденные попутно дефекты,
`COURSE.md`, `tests/`, `contracts/`, `lab.json`, `REPORT.md`,
`evidence/` (доказательства остаются в репозитории своей лабы),
`graphify-out/` (граф собирается заново).
- Доказательства исключений сверки покрытия снять заново на стенде новой
лабы, иначе `make student_test` красный (`test_exclusion_evidence_exists`
называет сценарий и путь): `make test_isolated`, затем `driver.py
--port <LB> cache-check` → `evidence/cache/hits.md`; `driver.py --port
<LB> auth-storage` → `evidence/auth/passwords-and-tokens.md`; `make
test-persistence ACTION_SCRIPT=scripts/restart.sh` →
`evidence/replicas/test-persistence.md` (или путь, который назовёт
исключение); повтор отправки с ключом после `docker compose up -d
--force-recreate api` → `evidence/idempotency/replay-after-restart.md`
(`student-tests.md`).
- Сначала прочитать переходы API в `COURSE.md` и `contracts/README.md`
нового skeleton, потом править код. Обновить этот файл: номер лабы,
таблицу важных файлов, новые правила.
+1 -103
View File
@@ -3,106 +3,4 @@
Найдены попутно, не исправлены без отдельной просьбы (AGENTS.md).
Исправленные удаляются отсюда, история — в git.
## Исключения сверки покрытия ссылаются на evidence лабы 2
- **Где:** `student-tests/spec_coverage.py`, `EXCLUDED`: сценарии
`chat-cache` «Чтение из кэша», «Срок записи», «Временная база»
(`evidence/cache/hits.md`), `sessions` «Токена нет в хранилище» и
`users` «Хэш в БД» (`evidence/auth/passwords-and-tokens.md`).
- **Что не так:** `evidence/` перенесён в лабу 3 без содержимого лабы 2
(AGENTS.md, карта кода), этих файлов в репозитории нет. Исключение
называет способ проверки, но доказательства по ссылке нет.
- **Найдено:** change `replicas-lb` (2026-10-10). Ссылки двух
сценариев рестарта (`evidence/storage/test-persistence.md`) этот
change перевёл на свой `evidence/replicas/test-persistence.md`.
- **Предложение:** снять те же проверки на стенде лабы 3 (`valkey-cli`
для ключей и TTL кэша, `psql` для хэшей паролей и токенов) в
`evidence/cache/` и `evidence/auth/`, либо сослаться на файлы
репозитория лабы 2 с commit. Тест `test_coverage.py` существование
файлов не проверяет.
## SIGTERM во время старта реплики теряется
- **Где:** `Dockerfile` (`CMD ["python", "-m", "src"]`, процесс — PID 1),
`src/main.py` (`uvicorn.run`).
- **Что не так:** у PID 1 ядро не доставляет сигнал без обработчика, а
обработчики SIGTERM uvicorn ставит только на старте сервера, после
импорта приложения и до lifespan. `docker stop` реплики, которая ещё
стартует (первые ~1–2 с), теряет SIGTERM: Docker ждёт `stop_grace_period`
10 с и шлёт SIGKILL. Тем временем реплика успевает стать готовой и
получать запросы через LB, а SIGKILL обрывает их. Найдено в apply
change `rolling-update` (2026-10-11): неготовую новую реплику скрипт
останавливал 10 с, и она 9 с была `UP` в LB.
- **Обход в `scripts/rolling-update.sh`:** неготовая новая реплика
убирается `docker rm -f` после `maint` её слота (design change
`rolling-update`, Risks). Штатные остановки (`stop-one.sh`, замена
старой реплики) касаются уже запущенного процесса и не затронуты.
- **Предложение:** ранний обработчик SIGTERM в `src/__main__.py` до
импорта приложения (выставить флаг, который uvicorn проверит после
старта), либо `init: true` в compose (tini как PID 1 пересылает
сигнал, а у Python без обработчика SIGTERM завершает процесс). Второе
расходится с `docker.md` («сервер — PID 1»), поэтому решать
отдельным change.
## Профиль `failover` берёт события Docker из буфера демона
- **Где:** `bench/run.py`, `Bench.run_phase` — `stand.events(target_id,
started - 5, ended + 1)` (`docker events --since … --until …` после
фазы).
- **Что не так:** демон Docker хранит только последние 256 событий всех
контейнеров. Каждый `docker exec` даёт три события (`exec_create`,
`exec_start`, `exec_die`). Профиль `rollout`, который много раз
обращается к LB через `docker exec`, в первой самопроверке потерял
события миграции и старых реплик (change `rolling-update`, design,
решение 8). Проверки здоровья — тоже `docker exec` с теми же тремя
событиями: на стенде `bench/` PostgreSQL, Valkey и HAProxy проверяются
раз в 5 с (у реплик проверка отключена), это ~1,8 события в секунду,
~110 за окно фазы `failover` (~60 с от `started - 5` до запроса). Все
прогоны до сих пор находили события, но запас — около двух раз
(буфер покрывает ~140 с). Подсчёт `docker events` за 60 с на рабочем
стенде, где проверяются и обе реплики: 144 события, все от проверок
здоровья (2026-10-13). Любой новый опрос через `docker exec` или
проверка реплик в профиле съест этот запас: тогда фаза падает с
«docker events … not found».
- **Предложение:** как в профиле `rollout` — поток `docker events` с
фильтром контейнера или проекта, запущенный до фазы
(`Stand.project_events`).
## `fill-connections` роняет PostgreSQL стенда отказов в crash recovery
- **Где:** `student-tests/fault_hook.py`, `FILL_SH` и `CLEAR_FILL_SH`
(действия `fill-connections` / `clear-connections` теста
`test_connection_limit_reached`).
- **Что не так:** `FILL_SH` запускается `docker compose exec -d` и
отвязывает `psql … &`. После `kill` цикла и обрыва сессий эти процессы
становятся сиротами, их наследует PID 1 контейнера — postmaster. Он
считает их своими «untracked child process», и выход с ненулевым кодом
(`psql` получил FATAL) для него — авария: «all server processes
terminated; reinitializing», recovery и сброс статистики
`pg_stat_database`. Журнал PostgreSQL стенда отказов, 2026-10-11:
`untracked child process (PID 79) exited with exit code 2` сразу после
`clear-connections`. Тесты проходят: к следующему тесту база уже
поднята, а пулы API переподключаются. Но каждый прогон `make
failure_checks` перезапускает PostgreSQL посреди набора, и следующий
тест видит пустую статистику и только что поднятую базу.
- **Найдено:** change `scaling-improvement` (2026-10-11), разбор шума
теста `test_pool_keeps_connections` (журнал с `log_connections`).
- **Предложение:** запускать заполнение под отдельным init — `init:
true` у `postgres` в `student-tests/failures.compose.yml` (tini
реапит сирот сам), либо держать `psql` детьми долгоживущего `sh`
(`wait` в конце `FILL_SH`, `CLEAR_FILL_SH` убивает группу процессов).
## Паспорт метки без `swapouts_delta`, когда счётчик выгрузок равен 0
- **Где:** `bench/run.py`, конец `main()` — условие `if
state.get("swapouts") is not None and end_state.get("swapouts"):`.
- **Что не так:** при `Swapouts` 0 в конце прогона (хост после
перезагрузки) второе условие ложно, и `host_state.swapouts_delta` в
`meta.json` не пишется, хотя `start` и `end` (0 и 0) записаны. Так у
меток `scaling-db-aa2`, `scaling-db-before2`, `scaling-db-nooverflow2`.
Предупреждение о выгрузке (`swap_warning`) и проверка в
`bench/compare.py` работают верно: страдает только поле паспорта.
- **Найдено:** verify change `scaling-improvement` (2026-10-11, S5).
- **Предложение:** `end_state.get("swapouts") is not None`. Правка
меняет код стенда `bench/`: делать её между сериями, а не посреди
«до/после».
Открытых записей нет: записи лабы 3 исправлены change `fix-known-issues`.
+60 -24
View File
@@ -31,7 +31,15 @@
графики, точка насыщения и ответ 503 на «too many clients» —
`scaling-bench` (уровень «5»);
- одно улучшение по найденному узкому месту — пул без переполнения —
`scaling-improvement` (уровень «5»).
`scaling-improvement` (уровень «5»);
- исправление пяти найденных попутно дефектов перед переносом в лабу 4
— `fix-known-issues`: SIGTERM на старте реплики больше не теряется
(ранний обработчик до импорта приложения), профиль `failover` читает
события Docker потоком, PostgreSQL стенда отказов работает под init и
`make failure_checks` проверяет его журнал, паспорт меток пишет
`swapouts_delta` и при нуле, доказательства исключений сверки
покрытия сняты на стенде лабы 3 (`KNOWN_ISSUES.md` — без открытых
записей).
## Запуск из чистого clone
@@ -669,6 +677,9 @@ SHA-256 тела; `created_at` с индексом; `CHECK` формата и д
| «5», трек 1: уровень шума для улучшения | `make bench_scaling SERIES=ab SCALING_LABEL=scaling-aa`; `make bench_compare BEFORE=scaling-b AFTER=scaling-aa`, `BEFORE=scaling-b AFTER=scaling-a` | шум между сессиями (B → A/A, тот же код `712d245`): 1 × 1 666 (666–704) → 704 (666–704), +5,7 % — одна ступень деления; 6 × 1 2 034 (1 923–2 034) → 2 034 (2 034–2 034), Δ в пределах одной ступени (< 5,7 %); разбросы пересекаются. Согласованность серий: 4 × 1 серии `a` и k = 4 серии `b` — 1 819 и 1 819. Для `scaling-improvement` `scaling-aa` как `AA` не годится: код после правки 53300 другой, A/A снимается заново | `evidence/compare/scaling-b__scaling-aa.md`, `evidence/compare/scaling-b__scaling-a.md` |
| «5», трек 1: одно подтверждённое улучшение — пул без переполнения (change `scaling-improvement`) | H4 закоммичена до замеров (`0b0421a`, набор ячеек — `1bb8ea6`, попытка 2 — `a676a52`); изменение `9c3959d` (дефолт `max_overflow` 5 → 0) откачено; в одной сессии хоста: A/A `make bench_scaling SERIES=db4 SCALING_LABEL=scaling-db-aa2`, затем `make bench_ab BEFORE=scaling-db-before2 AFTER=scaling-db-nooverflow2 REAPPLY=5c07923 SERIES=db4`; `make bench_compare … AA=scaling-db-aa2 CHANGE=scaling-improvement`. Попытка 1 — те же команды с метками без `2`, откат `62fa575` | **попытка 2 (окончательная, тихий хост):** основная `4x1-pg0.5` R* 931 (931–984) → 1 101 (1 101–1 101), +18,3 %, «эффект», шум A/A 5,4 %; механизм: новых сессий на первой нарушившей 102 → 4, соединений 60 → 40, CPU PostgreSQL на запрос там 416 → 336 мкс; контроль `4x1-pg2` +5,7 % (в пределах шума). **Подтверждено с оговоркой**: по букве критерия проверка дрейфа (CPU на запрос при 500/с ±5 %) у основной ячейки −5,4 % из-за двух ячеек «до» (переполнения при 500/с нет ни в одной метке); против A/A2 той же сессии (`make bench_compare BEFORE=scaling-db-aa2 AFTER=scaling-db-nooverflow2 AA=scaling-db-before2 CHANGE=scaling-improvement`) дрейфа нет — 1 940 → 1 936 мкс, R* 984 → 1 101, +11,9 % (две ступени), «эффект»; засчитано решением автора после результатов. Попытка 1: +32 %, но шум A/A 20 % из-за помех macOS (iCloud, Zoom) — не прошла дрейф | `evidence/compare/scaling-db-before2__scaling-db-nooverflow2.md`, `evidence/compare/scaling-db-aa2__scaling-db-nooverflow2.md`, `evidence/compare/scaling-db-aa2__scaling-db-before2.md`, `evidence/bench/scaling-db-{aa2,before2,nooverflow2}/`, попытка 1 — `evidence/compare/scaling-db-before__scaling-db-nooverflow.md` и метки без `2`, `evidence/tests/scaling-improvement-checks.md` |
| Пул без переполнения: соединения не переоткрываются | `make failure_checks`: тест `test_pool_keeps_connections` (48 потоков × 5 запросов, пачки больше пула 10, счётчик `pg_stat_database.sessions` через hook `db-sessions`); рабочий `config.toml` с `max_overflow` 5 и 0 | 10 + 5 — красный: 18–21 новая сессия PostgreSQL за 720 запросов; 10 + 0 — 0, 17 проверок отказов прошли (4 прогона); регрессия на коде `80e64cd`: `make test`, `make student_test` (131 passed), `make test_isolated`, `make test-persistence`, `make test-failover` для обеих реплик — `PASS`; соединений приложения на рабочем стенде 17 ≤ 2 × 10 | `evidence/tests/scaling-improvement-checks.md` |
| «4»: остановка реплики во время старта (`docker stop` до готовности) | `driver.py stop-at-start --image <образ>`: контейнеры образа с лимитами реплики, `docker stop --timeout 10` через 0,2–0,4 с после старта (импорт), по строке «Started server process» и в работающий сервер; «до» — образ кода `628bbfa`, «после» — `edad1fd`; ветка сбоя `rolling-update.sh` (`ROLLOUT_READY_TIMEOUT=1` и `2`) | «до»: во время импорта SIGTERM потерян — `docker stop` 10,1 с, код 137, сервер после сигнала дошёл до «Uvicorn running on»; «после»: 0,06 с, код 0, запись `info` «Stopped API before startup» с `signal` `SIGTERM`; сигнал на старте сервера и работающей реплике — uvicorn, ≤ 0,5 с, код 0 в обоих; неготовая новая реплика со слотом LB — `maint` и штатная остановка с кодом 0; окно запуска интерпретатора (десятки мс) — ограничение | `evidence/failover/stop-at-start.md` |
| Исключения сверки покрытия на стенде лабы 3 (кэш, пароли и токены) | `make test_isolated`, затем `driver.py --port 8080 cache-check`; `driver.py --port 8080 auth-storage` (код драйвера `5372d20`, приложение `edad1fd`); сверка ссылок исключений `test_exclusion_evidence_exists` | 50 чтений карточки через обе реплики — таблица `chats` прочитана 1 раз, `keyspace_hits` +49, промахов +1; TTL 3600 с = настроенному, чтения его не продлевают; ключи рабочей и тестовой базы — 78 и 74 под разными префиксами. `password_hash` — `$argon2id$v=19$m=65536,t=3,p=4$…`, у одного пароля хэши разные; `token_hash` — 32 байта SHA-256, ни токена, ни пароля в `pg_dump`. Без этих файлов сверка падает и называет 5 сценариев и 2 пути | `evidence/cache/hits.md`, `evidence/auth/passwords-and-tokens.md` |
| Регрессия `fix-known-issues` (итоговый код `949bea4`) | сверка событий `failover` поток против буфера демона (временный commit и `git revert`), без помех и под шумом `docker exec`; `make failure_checks` до и после `init: true`; консоль (SIGTERM / SIGINT на старте, reload); `make test`, `make student_test`, `make test-persistence`, `make test-failover` (`stop` для обеих, `kill`), `make test_isolated`, `make failure_checks`, `make bench_failover_quick`, `make bench_rollout_quick` | без помех моменты совпали до наносекунды (4 фазы), под шумом ~24 `docker exec`/с буфер потерял события всех 4 фаз, поток — ни одного; красный `failure_checks` — «untracked child process … exit code 2», «reinitializing», код ненулевой; зелёный — `crash markers 0` дважды; консоль — код 0 без traceback; всё остальное — код 0: 133 passed через LB, 129 + 4 пропуска в изоляции, 17 проверок отказов | `evidence/tests/fix-known-issues-checks.md` |
| Цена нового соединения PostgreSQL и пинга | микропроба в реплике рабочего стенда (`cd88b48`): проверка сессии и страница истории через repo, из пула с пингом, без пинга и с новым соединением на итерацию | новое соединение — 11,7–11,8 мс CPU реплики (SCRAM-SHA-256 asyncpg в event loop) и 2,7 мс CPU PostgreSQL против 0,6 и 0,15 мс из пула; пинг при выдаче — +0,13 мс реплики и +0,05 мс PostgreSQL на запрос | `evidence/storage/connection-cost.md` |
**Сверка с рубрикой README.** Каждому пункту — строка с командой,
@@ -681,7 +692,7 @@ SHA-256 тела; `created_at` с индексом; `CHECK` формата и д
| 3 | отказ любой одной реплики: ≤10 с до новых чтений и записей, подтверждённые сообщения доступны, ошибки измерены | «3»: отказ любой одной реплики…; «3»: отказ процесса без graceful; «4»: последовательная остановка каждой реплики |
| 3 | повтор с тем же `Idempotency-Key` без дублей: конкурентный, при переключении реплики, неподтверждённая запись | «3»: повтор `POST`…; другое тело с тем же ключом; повтор через другой процесс; при переключении реплики; ключ переживает рестарт; неподтверждённую запись можно повторить; «4»: идемпотентность под параллельными запросами |
| 3 | `make test`, persistence и failover проходят, ≥2 наблюдаемых реплики; hook подтверждён составом перезапущенных процессов | публичный smoke; «3»: `make test-persistence` с LB (`StartedAt` всех контейнеров до и после); «3»: отказ любой одной реплики (`STOP_ONE_LOG`, `docker compose ps -a`); failover hook не трогает чужое |
| 4 | health/readiness, таймауты, SIGTERM согласованы; LB исключает недоступный backend; период проверок и максимальное время обнаружения | «4» (часть): LB исключает недоступный backend; «4»: health/readiness, таймауты и прекращение приёма при SIGTERM |
| 4 | health/readiness, таймауты, SIGTERM согласованы; LB исключает недоступный backend; период проверок и максимальное время обнаружения | «4» (часть): LB исключает недоступный backend; «4»: health/readiness, таймауты и прекращение приёма при SIGTERM; «4»: остановка реплики во время старта (SIGTERM не теряется и до старта сервера) |
| 4 | каждая реплика по очереди с восстановлением: RPS, ошибки, время восстановления; идемпотентность параллельными запросами | «4»: последовательная остановка каждой реплики…; «4»: CPU и память профилей отказа и замены; «4»: идемпотентность под параллельными запросами |
| 4 | лимиты CPU/RAM, порты API не наружу, секреты только где нужно, нет `container_name` | «4»: лимиты CPU/RAM…; порты из `.env` со стендом за LB |
| 4 | rolling update под нагрузкой; миграции однократно и совместимы | «4»: rolling update…; «4»: CPU и память профилей отказа и замены; «4»: миграции однократно и совместимы; замена при сбое и неготовом стенде |
@@ -716,7 +727,8 @@ Desktop 29.8.2, ВМ 12 vCPU / 7,7 GiB; перед каждым замером
и выгрузок в swap (паспорта `meta.json`; у профиля `failover` счётчик
выгрузок — в `evidence/failover/detection.md`, у `rollout` — только
занятый swap, у меток попытки 2 улучшения — `Swapouts` 0 в начале и в
конце без поля `swapouts_delta`, `KNOWN_ISSUES.md`; у меток `resources`
конце, поле `swapouts_delta` не записано, дефект паспорта исправлен
change `fix-known-issues`, метки не правились; у меток `resources`
обоих профилей — `Swapouts` в начале и в конце равны: 129 588 у
`failover`, 157 300 у `rollout`, `host_warnings` пусты; прогон `rollout`
с выгрузкой 7 236 страниц отброшен и переснят,
@@ -751,6 +763,7 @@ Desktop 29.8.2, ВМ 12 vCPU / 7,7 GiB; перед каждым замером
| остановка всех реплик | LB отвечает 503 в формате контракта, healthcheck LB — `unhealthy` | так и есть; после `make replicas` — 200 через ~3 с | данные в Postgres не затронуты (`evidence/replicas/lb-errors.md`) |
| `scripts/restart.sh`: LB, обе реплики, Postgres, Valkey | данные и токен переживают рестарт | `PASS`; до прохождения проверок LB отвечал 503, реплики начинают в `DOWN` | 6,4 с на тест целиком; кэш пуст, данные целы (`evidence/replicas/test-persistence.md`) |
| `make rolling_update` под `tests/load.py` (4 клиента): вперёд, откат на `c50b721`, снова вперёд | новая реплика в LB до вывода старой, старая выводится из LB до SIGTERM — ошибок нет | 0 неуспешных из 21 043, 16 687 и 18 480 запросов (`84161c0`); замена 10–12 с; новая миграция при прежних репликах — `make test` и `make student_test` проходят | простоя нет; по `messages.instance_id` видно, какая версия что записала (`evidence/rollout/compatibility.md`) |
| `docker stop` стартующей реплики (`driver.py stop-at-start`: сигнал через 0,25–0,45 с после старта контейнера, во время импорта приложения) | процесс с PID 1 получает SIGTERM и выходит сразу: запросов ещё нет | «до» (`628bbfa`): сигнал потерян, сервер после него дошёл до «Uvicorn running on», `docker stop` 10,1 с, SIGKILL, код 137; «после» (`edad1fd`): 0,06 с, код 0, запись «Stopped API before startup»; сигнал на старте сервера и в работе — как раньше, uvicorn, ≤ 0,5 с, код 0 | без потерь: запросов у стартующей реплики нет; окно запуска интерпретатора (десятки мс) осталось (`evidence/failover/stop-at-start.md`) |
| миграция ждёт блокировку `messages` за чужой 20-секундной транзакцией, через LB идут запись и чтение | миграция сдаётся по `lock_timeout`, запросы в очереди за ней выполняются | `lock_timeout` 5 с (apply): все 6 запросов из очереди — 503 через 5,03 с (`statement_timeout` приложения 5 с истёк вместе с ним); 2 с (`84161c0`): 0 ошибок, те же 6 запросов — 2,01–2,02 с | схема и реплики не тронуты, повтор после конца транзакции прошёл (`evidence/rollout/script-failures.md`, случай 7) |
### Отказ каждой реплики под нагрузкой (change `graceful-failover`)
@@ -1780,7 +1793,8 @@ swap 0, брака генератора нет (`evidence/tests/scaling-bench-ch
Zoom не запущен, средняя нагрузка за 5 мин < 8 (≤ 7,88), Spotlight
< 15 % CPU (≤ 12,6 %), выгрузок 0 (проверка хоста; в паспортах —
`Swapouts` 0 в начале и в конце, поле `swapouts_delta` не записано,
`KNOWN_ISSUES.md`).
дефект паспорта исправлен change `fix-known-issues`, метки не
правились).
- Эффект — вывод `make bench_compare … AA=scaling-db-aa` (попытка 1) /
`AA=scaling-db-aa2` (попытка 2): разбросы не
пересекаются и Δ больше шума A/A; плюс сдвиг не меньше двух ступеней
@@ -2040,23 +2054,33 @@ CHANGE=scaling-improvement`
хост (энергоэффективные ядра, частота, гипервизор — замер не
разделяет); выигрыш пинга только после простоя соединения; эффект
пула 10 + 0 на дефолтных лимитах PostgreSQL.
- **Известные дефекты** (`KNOWN_ISSUES.md`, не исправлены): SIGTERM во
время старта реплики теряется (обход — в `rolling-update.sh`);
`fill-connections` в `make failure_checks` перезапускает PostgreSQL
стенда отказов посреди набора (тесты проходят, но следующий тест
видит свежую базу); 5 исключений сверки покрытия ссылаются на
evidence лабы 2, которого в этом репозитории нет; профиль `failover`
берёт события Docker из буфера демона (256 событий); паспорта меток
попытки 2 без `swapouts_delta`.
- **Известные дефекты:** открытых нет (`KNOWN_ISSUES.md`). Пять записей,
найденных попутно, исправлены change `fix-known-issues`: SIGTERM на
старте реплики терялся (теперь ранний обработчик до импорта
приложения, `evidence/failover/stop-at-start.md`);
`fill-connections` перезапускал PostgreSQL стенда отказов посреди
набора (теперь `init: true` и проверка журнала в `make
failure_checks`); исключения сверки покрытия ссылались на evidence,
которого в репозитории не было (теперь доказательства сняты на стенде
лабы 3, а сверка падает на ссылке на отсутствующий файл); профиль
`failover` брал события Docker из буфера демона (теперь поток);
паспорт метки не писал `swapouts_delta` при нуле (метки
`scaling-db-*2` не правились). Сводка проверок —
`evidence/tests/fix-known-issues-checks.md`.
- **Окно запуска интерпретатора.** В первые десятки миллисекунд жизни
процесса, до первых строк `src/__main__.py`, SIGTERM реплике с PID 1
по-прежнему не доставляется: `docker stop` в этот миг ждёт 10 с и
SIGKILL. Закрыть это окно может только init-процесс, а сервер должен
оставаться PID 1. Запросов у такой реплики нет; `rolling-update.sh`
убирает реплику без слота LB `docker rm -f`.
**Следующие шаги:** ранний обработчик SIGTERM или `init` для реплики
(`KNOWN_ISSUES.md`); пинг соединения только после простоя (design
**Следующие шаги:** пинг соединения только после простоя (design
`scaling-improvement`, решение 6); причинная проба хоста («грелка» на
6 vCPU); фоновая уборка ключей в worker лабы 5; повтор замеров уровня
«4» с несколькими прогонами на фазу (и ресурсов — с распределением, а
не одним значением); пункты `KNOWN_ISSUES.md`
(evidence лабы 2 в исключениях сверки покрытия, буфер событий Docker в
профиле `failover`).
не одним значением); в лабе 4 — снять заново доказательства исключений
сверки покрытия на её стенде (`AGENTS.md`, «Переход в следующую
лабу»).
Идемпотентность:
@@ -2238,10 +2262,15 @@ CHANGE=scaling-improvement`
очереди до 2 с.
- **Сборка образа идёт на том же хосте, под нагрузкой.** Из кэша слоёв
— секунды CPU ВМ Docker.
- **SIGTERM во время старта реплики теряется** (процесс с PID 1 до
установки обработчиков uvicorn, `KNOWN_ISSUES.md`). Скрипт обходит это
для неготовой новой реплики: слот в `maint`, затем `docker rm -f`.
Штатные остановки касаются уже запущенных процессов.
- **Неготовая новая реплика при сбое замены** (change
`fix-known-issues`, решение 7). Слот LB уже есть — `maint`, затем
штатная остановка (стартующая реплика выходит сразу по раннему
обработчику SIGTERM, работающая дорабатывает запросы, отправленные на
слот до `maint`) и `docker rm -f`; слота нет — сразу `docker rm -f`:
запросов на ней не было, и это страховка на окно запуска
интерпретатора, где SIGTERM ещё некому принять. Проверено
`ROLLOUT_READY_TIMEOUT=1` и `2`: оба раза путь со слотом, код выхода
0 (`evidence/failover/stop-at-start.md`).
- **Замена только на одном хосте** и только для `api`. LB, PostgreSQL и
Valkey обновляются с простоем.
- **Профиль отказа — один прогон на фазу, один хост.** Замер показывает
@@ -2442,7 +2471,8 @@ structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn
Работа велась по changes OpenSpec (`openspec/changes/archive/`: семь
changes лабы 3, седьмой — `profile-resources`, CPU и память профилей
уровня «4», добавлен после закрытия лабы; все в архиве, спеки
синхронизированы). Каждый change проходил этапы propose → apply →
синхронизированы; восьмой — `fix-known-issues`, исправление записей
`KNOWN_ISSUES.md` перед переносом в лабу 4). Каждый change проходил этапы propose → apply →
verify → правки по verify и archive. Каждый этап выполнял отдельный субагент,
основная сессия координировала: передавала этапы, проверяла итоги,
присылала автору прогресс. Все commit после skeleton помечены
@@ -2478,7 +2508,11 @@ changes).
- засчитать улучшение с оговоркой по пункту дрейфа после результатов
попытки 2 (design `scaling-improvement`, п. 4);
- коммиты и замеры в автономном режиме — с условием: перед каждым
замером проверка хоста, при плохом состоянии — остановка и вопрос.
замером проверка хоста, при плохом состоянии — остановка и вопрос;
- исправить все пять записей `KNOWN_ISSUES.md` отдельным change
`fix-known-issues` до переноса кода в лабу 4 (2026-10-13), а его
быстрые профили-самопроверки разрешить от батареи и рядом с
посторонним контейнером (это не замеры для отчёта).
Как проверялось:
- verify каждого change отдельным субагентом: сверка с задачами, спеками
@@ -2496,7 +2530,9 @@ changes).
- ошибки ИИ, найденные по ходу, описаны в отчёте как есть: ошибочный
пункт `KNOWN_ISSUES.md` о `make run_docker` (диагноз по digest
конфигурации образа containerd), 500 вместо 503 на 53300, первая
попытка замера улучшения на зашумлённом хосте.
попытка замера улучшения на зашумлённом хосте; исключения сверки
покрытия ссылались на файлы доказательств, не перенесённые из
репозитория прошлой лабы (теперь сверка это ловит).
Утверждения отчёта о поведении стенда подтверждены командами, выводы
которых лежат в `evidence/`; решения, перечисленные выше, принимал
+157
View File
@@ -0,0 +1,157 @@
# Остановка реплики во время старта
| | |
|---|---|
| Спеки | `graceful-shutdown` «Остановка во время старта»: «docker stop во время импорта приложения», «Сигнал во время старта сервера», «Работающий процесс останавливается как раньше» (консоль — `evidence/tests/fix-known-issues-checks.md`) |
| Change | `fix-known-issues`, задачи 5.2, 5.7–5.9 |
| Дата | 2026-10-13, 13:52–14:44 UTC |
| Commit | «до» — образ из `42e6edf` (команда драйвера, код приложения как в `628bbfa`), команда — `f6052f6`; «после» — код приложения `edad1fd` (образ рабочего стенда после `make rolling_update` на `949bea4`, код приложения тот же) |
| Образы | «до» `mtusi-messenger:stop-before` `sha256:537d30351c41…`; «после» `mtusi-messenger:lab3` `sha256:7e13dab695ea…` — тот же `.Image`, что у реплик рабочего стенда |
| Контейнер | `docker run -d --network none --cpus 1 --memory 512m --memory-swap 512m` — лимиты реплики `api`, без сети и без `config.toml` (приложение стартует на дефолтах, соединения с хранилищами ленивые); `docker stop --timeout 10` — `stop_grace_period` compose |
| Хост | Docker Desktop 29.8.2, macOS arm64, ВМ 12 CPU / 7,7 GiB; от батареи (разрешено пользователем), посторонний контейнер `domains-postgres-1`; давление памяти — нормальное (уровень 1), `Swapouts` без роста за прогон |
| Команда | `python3 .claude/skills/run-mtusi-messenger/driver.py stop-at-start --image <образ>` |
Как устроена команда (design change `fix-known-issues`, решение 8).
Каждая попытка — свой контейнер. Паузы 0,2 / 0,3 / 0,4 с после `docker
run` попадают в импорт приложения: «Started server process» на этом
образе появляется через ~0,7 с. Паузы 1,5 и 5 с — в работающий сервер.
Ещё три попытки шлют `docker stop` сразу по строке «Started server
process» (`docker logs -f`): сигнал попадает между ней и «Uvicorn
running on». Время — часы ВМ Docker: поток `docker events` по метке
(`start`, `kill` с сигналом 15, `die` с кодом выхода) и `timestamp`
записей журнала. Класс попытки — по моменту `kill`: `import` — до
«Started server process», `server-start` — до «Uvicorn running on»,
`running` — после. Кто остановил: `early` — запись «Stopped API before
startup», `uvicorn` — «Shutting down», «Stopped API», «Finished server
process». Попытки `server-start` и `running` журнала «после» здесь
сокращены: их последовательность та же, что у «до».
## «До»: образ из `42e6edf` (код приложения без раннего обработчика)
```text
$ python3 .claude/skills/run-mtusi-messenger/driver.py stop-at-start --image mtusi-messenger:stop-before
image mtusi-messenger:stop-before (sha256:537d30351c41), label mtusi.stop-at-start=f7baa267
#1 pause 0.2 s: signal after 0.264 s, docker stop 10.120 s, exit after signal 10.070 s, exit code 137, import, stopped by none
log: Started server process → Waiting for application startup. → Database password is empty → Cache password is empty → Started API → Application startup complete. → Uvicorn running on
#2 pause 0.3 s: signal after 0.353 s, docker stop 10.088 s, exit after signal 10.044 s, exit code 137, import, stopped by none
log: Started server process → Waiting for application startup. → Database password is empty → Cache password is empty → Started API → Application startup complete. → Uvicorn running on
#3 pause 0.4 s: signal after 0.454 s, docker stop 10.110 s, exit after signal 10.068 s, exit code 137, import, stopped by none
log: Started server process → Waiting for application startup. → Database password is empty → Cache password is empty → Started API → Application startup complete. → Uvicorn running on
#4 pause 1.5 s: signal after 1.565 s, docker stop 0.363 s, exit after signal 0.306 s, exit code 0, running, stopped by uvicorn
log: Started server process → Waiting for application startup. → Database password is empty → Cache password is empty → Started API → Application startup complete. → Uvicorn running on → Shutting down → Waiting for application shutdown. → Stopped API → Application shutdown complete. → Finished server process
#5 pause 5 s: signal after 5.062 s, docker stop 0.450 s, exit after signal 0.395 s, exit code 0, running, stopped by uvicorn
log: (та же последовательность, что у #4)
#6 server-start: signal after 0.743 s, docker stop 0.371 s, exit after signal 0.323 s, exit code 0, server-start, stopped by uvicorn
log: (та же последовательность, что у #4)
#7 server-start: signal after 0.739 s, docker stop 0.279 s, exit after signal 0.235 s, exit code 0, server-start, stopped by uvicorn
log: (та же последовательность, что у #4)
#8 server-start: signal after 0.846 s, docker stop 0.498 s, exit after signal 0.455 s, exit code 0, server-start, stopped by uvicorn
log: (та же последовательность, что у #4)
attempts: import 3, server-start 3, running 2
FAIL: #1: exit code 137; #1: docker stop took 10.1 s; #1: import, nobody stopped the process; #2: exit code 137; #2: docker stop took 10.1 s; #2: import, nobody stopped the process; #3: exit code 137; #3: docker stop took 10.1 s; #3: import, nobody stopped the process; no import attempt stopped early
```
Код 1. Дефект воспроизведён: SIGTERM во время импорта процесс с PID 1
потерял. Сервер после сигнала дошёл до «Uvicorn running on» и работал,
пока Docker через 10 с не прислал SIGKILL (код 137). Сигнал после
установки обработчиков uvicorn (`server-start`, `running`) обработан
штатно.
Первый прогон «до» шёл без `--timeout`: `docker stop` у контейнера
`docker run` на Docker Desktop 29.8.2 ждал не 10 с, а ~3,1 с (тоже код
137). Срок команды приведён к `stop_grace_period` отдельным commit
`f6052f6`, прогон выше — на нём.
## «После»: код `edad1fd` (ранний обработчик)
```text
$ python3 .claude/skills/run-mtusi-messenger/driver.py stop-at-start --image mtusi-messenger:lab3
image mtusi-messenger:lab3 (sha256:7e13dab695ea), label mtusi.stop-at-start=e76e20e0
#1 pause 0.2 s: signal after 0.247 s, docker stop 0.063 s, exit after signal 0.031 s, exit code 0, import, stopped by early
log: Stopped API before startup
#2 pause 0.3 s: signal after 0.356 s, docker stop 0.063 s, exit after signal 0.015 s, exit code 0, import, stopped by early
log: Stopped API before startup
#3 pause 0.4 s: signal after 0.445 s, docker stop 0.061 s, exit after signal 0.022 s, exit code 0, import, stopped by early
log: Stopped API before startup
#4 pause 1.5 s: signal after 1.575 s, docker stop 0.374 s, exit after signal 0.309 s, exit code 0, running, stopped by uvicorn
#5 pause 5 s: signal after 5.058 s, docker stop 0.483 s, exit after signal 0.434 s, exit code 0, running, stopped by uvicorn
#6 server-start: signal after 0.688 s, docker stop 0.451 s, exit after signal 0.421 s, exit code 0, server-start, stopped by uvicorn
#7 server-start: signal after 0.697 s, docker stop 0.308 s, exit after signal 0.263 s, exit code 0, server-start, stopped by uvicorn
#8 server-start: signal after 0.684 s, docker stop 0.289 s, exit after signal 0.251 s, exit code 0, server-start, stopped by uvicorn
attempts: import 3, server-start 3, running 2
PASS: SIGTERM during start stops the replica at once, exit 0
```
Код 0. У #4–#8 журнал — полная последовательность старта и остановки,
как у #4 «до». Запись ранней остановки — одна строка JSON с полями
записей structlog (ручной `docker run` и `docker stop` через 0,3 с):
```json
{"event": "Stopped API before startup", "instance_id": "88ef53e0e6e8", "module": "startup", "signal": "SIGTERM", "level": "info", "timestamp": "2026-10-13T14:44:04.127058Z"}
```
`instance_id` — короткий ID контейнера, как `X-Instance-Id`; код выхода
0. Предыдущий прогон «после» (под давлением памяти уровня 2, на
пересобранном теге того же кода) тоже дал PASS: `import` — 0,054–0,086
с, `server-start` и `running` — 0,30–0,59 с.
| | `import` (сигнал через 0,25–0,45 с) | `server-start` | `running` |
|---|---|---|---|
| «до» | `docker stop` 10,09–10,12 с, код 137, остановки нет | 0,28–0,50 с, код 0, uvicorn | 0,36–0,45 с, код 0, uvicorn |
| «после» | **0,061–0,063 с, код 0, ранний обработчик** | 0,29–0,45 с, код 0, uvicorn | 0,37–0,48 с, код 0, uvicorn |
## `scripts/rolling-update.sh`: неготовая новая реплика
Ветка сбоя замены на рабочем стенде (`edad1fd`), срок готовности
искусственно короткий:
```text
$ ROLLOUT_READY_TIMEOUT=1 make rolling_update # скрипт — код 1
13:54:59 rolling-update: replica 1/2: started new 8f53ef0fdad3
13:55:00 rolling-update: error: replica 1/2: new replica 8f53ef0fdad3 not UP in LB within 1s (container starting, LB no slot)
13:55:00 rolling-update: replica 1/2: removing new replica 8f53ef0fdad3 that is not ready
13:55:00 rolling-update: replica 1/2: removed new 8f53ef0fdad3 (slot api-1: stop 0s, exit 0)
13:55:01 rolling-update: stopped: 2 api replicas running; rerun make rolling_update to finish
$ ROLLOUT_READY_TIMEOUT=2 make rolling_update # скрипт — код 1
13:55:13 rolling-update: replica 1/2: started new 983337770b32
13:55:15 rolling-update: error: replica 1/2: new replica 983337770b32 not UP in LB within 2s (container healthy, LB DOWN 1/2)
13:55:15 rolling-update: replica 1/2: removing new replica 983337770b32 that is not ready
13:55:15 rolling-update: replica 1/2: removed new 983337770b32 (slot api-1: stop 0s, exit 0)
13:55:16 rolling-update: stopped: 2 api replicas running; rerun make rolling_update to finish
```
Оба раза к моменту уборки DNS уже отдал новой реплике слот: путь со
слотом — `maint`, штатная остановка с кодом 0 меньше чем за секунду,
`docker rm -f`, слот `ready`. Раньше этот путь шёл через `docker rm -f`
сразу (обход потерянного SIGTERM). Путь «no slot: docker rm -f» в
прогонах не выпал. После каждого запуска — две реплики `UP`
(`make lb_stats`), `srv_admin_state` занятых слотов 0, пустых 32
(обслуживание по DNS), флагов ручного состояния 1 и 8 нет.
Замена старых реплик на новый код под `tests/load.py` (4 клиента, 45 с):
скрипт — код 0, `failed_requests` 0 из 30 000:
```text
13:54:06 rolling-update: replica 1/2: removed old eaf46242aa75 (stop 0s, exit 0)
13:54:12 rolling-update: replica 2/2: removed old cc40cf19ba6e (stop 0s, exit 0)
13:54:14 rolling-update: done: 2 replicas 6dfdb911e5f6 9cae7d3032c0 UP in 15s
```
Работающая реплика выходит, как раньше, с кодом 0: снятый ранний
обработчик пропускает повтор сигнала uvicorn после остановки.
## Вывод
- SIGTERM, пришедший во время импорта приложения, больше не теряется:
`docker stop` стартующей реплики — 0,06 с вместо 10 с, код 0 вместо
137, в журнале — запись «Stopped API before startup» с `signal`
`SIGTERM`, записей старта сервера нет.
- Сигнал между «Started server process» и «Uvicorn running on» и
остановка работающей реплики — без изменений: uvicorn, код 0, меньше
0,5 с.
- Осталось окно запуска интерпретатора — первые десятки миллисекунд до
первых строк `src/__main__.py`. В нём SIGTERM процессу с PID 1
по-прежнему отбрасывается; закрыть его может только init-процесс, а
он противоречит правилу «сервер — PID 1». `rolling-update.sh` убирает
реплику без слота LB `docker rm -f`: запросов на ней нет.
+220
View File
@@ -0,0 +1,220 @@
# Проверки change `fix-known-issues`
| | |
|---|---|
| Спеки | дельты change: `graceful-shutdown` «Остановка во время старта»; `student-tests` «Доказательства исключений сверки в репозитории», «PostgreSQL стенда отказов без аварийных перезапусков»; `load-benchmark` «События Docker профилей отказа и замены». Регрессия — все основные спеки через `make student_test` и сверку покрытия |
| Change | `fix-known-issues`, задачи 2.2, 3.4–3.7, 4.2–4.4, 5.6, 5.7, 5.10, 6.4–6.6, 7.x |
| Дата | 2026-10-13, 13:20–14:50 UTC |
| Commit | база `628bbfa`; 1 `1823858` `swapouts_delta`; 2 `fe75fcf` поток событий `failover`; 3 `a24832c` временная сверка с буфером; 4 `b37c45c` её откат; 5 `249b67e` проверка журнала PostgreSQL; 6 `f8c8187` `init: true`; 7 `42e6edf` `stop-at-start`; 7a `f6052f6` срок `docker stop` в команде; 8 `edad1fd` ранний обработчик и `rolling-update.sh`; 9 `5372d20` `cache-check`, `auth-storage`; 10 `f241126` сверка ссылок исключений; 11 `949bea4` evidence исключений |
| Стенды | рабочий `mtusi-lab3` (HAProxy на `127.0.0.1:8080`, `api` × 2); `mtusi-bench` (быстрые профили); `mtusi-lab3-failures`; `make test_isolated` |
| Хост | Docker Desktop 29.8.2, macOS arm64, ВМ 12 CPU / 7,7 GiB. Питание от батареи и работающий посторонний контейнер `domains-postgres-1` (проверка здоровья `pg_isready` раз в 1 с) — по разрешению пользователя; перед прогонами `bench/` — давление памяти уровня 1, `Swapouts` без роста минуту. Быстрые профили — самопроверки, а не замеры: метки `quick-*` в git не идут |
## `swapouts_delta` (задача 2.2)
```text
$ uv run python -c "…; assert d({'swapouts': 0}, {'swapouts': 0}) == 0; …; print('swapouts ok')"
swapouts ok
```
`swapouts_delta` — `None`, только если одного из счётчиков нет; иначе
разность, в том числе 0. `swap_warning` считает через неё, тексты
прежние. Поле записано в паспортах всех быстрых меток ниже и равно
`end − start`.
## События фазы `failover`: поток против буфера демона (задачи 3.4–3.7)
Временный commit 3 (`a24832c`) после событий из потока запрашивал те же
события из буфера демона прежним способом (`docker events --since …
--until …`) и сравнивал `TimeNano` действия и возврата.
**Прогон 1, без помех** (`make bench_failover_quick`, метка
`quick-failover-20261013T132353Z`, `a24832c`, `dirty: false`):
```text
phase 01-stop-r1: cross-check: stream = buffer (kill 1791897858.365170240, start 1791897868.898480654)
phase 02-stop-r2: cross-check: stream = buffer (kill 1791897886.349954128, start 1791897896.451654196)
phase 03-kill-r1: cross-check: stream = buffer (kill 1791897913.066960096, start 1791897923.143096209)
phase 04-kill-r2: cross-check: stream = buffer (kill 1791897939.874256849, start 1791897949.957222462)
complete: 4/4 runs
```
Моменты совпали до наносекунды: величины фаз, посчитанные от них, те
же, что дал бы прежний способ. Поэтому метки `failover/baseline` и
`failover/resources` не переснимаются. Фон событий на хосте без стенда
— 84 за 30 с, все от `domains-postgres-1` (2,8/с). Вместе с проверками
здоровья стенда (~1,8/с) буфер в 256 событий покрывал ~55 с, а окно
быстрой фазы от `started − 5` до запроса — ~35 с, и в этом прогоне
буфер ещё держал.
**Прогон 2, под шумом** — цикл `docker exec mtusi-bench-valkey true`
всё время прогона (метка `quick-failover-20261013T133631Z`, `a24832c`):
```text
noise-execs=3306 seconds=139 # ~24 exec/с ≈ 71 событие/с
phase 01-stop-r1: cross-check: buffer lost the events
phase 02-stop-r2: cross-check: buffer lost the events
phase 03-kill-r1: cross-check: buffer lost the events
phase 04-kill-r2: cross-check: buffer lost the events
complete: 4/4 runs
```
Буфер потерял события действия и возврата во всех четырёх фазах:
прежний способ упал бы на «docker events of … not found». Поток нашёл
их везде, фазы завершились, сверка записей сошлась.
**Откат** — commit 4 `b37c45c` (`git revert` commit 3), `git diff
fe75fcf b37c45c -- bench` пуст. **Итоговый прогон** на `b37c45c`
(`quick-failover-20261013T134052Z`, `dirty: false`): 4 фазы, строк
`cross-check` нет; `stop` — LB out 0,78–1,16 с, 0 ошибок; `kill` — по
одному 502; `messages = keys` в каждой фазе.
| Метка | `git.commit` | `Swapouts` начало → конец | `swapouts_delta` |
|---|---|---|---|
| `quick-failover-20261013T132353Z` | `a24832c` | 209 172 → 226 144 | 16 972 |
| `quick-failover-20261013T133631Z` | `a24832c` | 264 748 → 282 920 | 18 172 |
| `quick-failover-20261013T134052Z` | `b37c45c` | 282 920 → 289 964 | 7 044 |
Выгрузки во время прогонов есть: хост работал от батареи рядом с IDE и
браузером, `host_warnings` их называют. Для самопроверки сверки это не
помеха: сравнивались моменты одних и тех же событий.
## Стенд отказов (задачи 4.2–4.4)
**Красный** — commit 5 `249b67e`, проверка журнала без исправления:
```text
$ make failure_checks
================ 17 passed, 131 deselected in 62.64s (0:01:02) =================
[failure_checks] postgres log: 193 lines, crash markers 5; "too many clients" 22, "administrator command" 31
[failure_checks] crash markers in the postgres log:
2026-10-13 13:44:24.452 UTC [1] LOG: untracked child process (PID 85) exited with exit code 2
2026-10-13 13:44:24.452 UTC [1] LOG: terminating any other active server processes
2026-10-13 13:44:24.467 UTC [1] LOG: all server processes terminated; reinitializing
2026-10-13 13:44:24.477 UTC [1] LOG: untracked child process (PID 788) exited with exit code 0
2026-10-13 13:44:24.592 UTC [921] LOG: database system was not properly shut down; automatic recovery in progress
[failure_checks] results: {'fault': 0, 'postgres': 1}
make: *** [failure_checks] Error 1
```
Тесты прошли, но PostgreSQL стенда перезапустился аварийно сразу после
`clear-connections`; команда — код 2 (make), стенд отказов удалён.
**Зелёные** — commit 6 `f8c8187` (`init: true` у `postgres` в
`failures.compose.yml`), два прогона подряд:
```text
$ docker inspect -f '{{.HostConfig.Init}}' mtusi-lab3-failures-postgres-1 # во время pytest
true # PID 1: /sbin/docker-init -- docker-entrypoint.sh postgres
================ 17 passed, 131 deselected in 62.94s (0:01:02) =================
[failure_checks] postgres log: 378 lines, crash markers 0; "too many clients" 23, "administrator command" 129
[failure_checks] results: {'fault': 0, 'postgres': 0}
================ 17 passed, 131 deselected in 63.42s (0:01:03) =================
[failure_checks] postgres log: 378 lines, crash markers 0; "too many clients" 23, "administrator command" 129
[failure_checks] results: {'fault': 0, 'postgres': 0}
```
Заполнение и освобождение слотов были («too many clients» 23,
«administrator command» 129: без аварии каждую сессию заполнения
завершает `clear-connections`, а не перезапуск сервера). `StartedAt`
контейнеров рабочего стенда до и после обоих прогонов не изменился.
## Консоль (задачи 5.6, 5.10)
На commit 8 `edad1fd`, `APP__RUN_MODE=console APP__PORT=18089
.venv/bin/python -m src`:
```text
SIGTERM через 0,3 с после запуска → exit=0
{"event": "Stopped API before startup", "instance_id": "<host>", "module": "startup", "signal": "SIGTERM", "level": "info", "timestamp": "2026-10-13T13:53:21.359077Z"}
SIGINT через 0,3 с → exit=0
{"event": "Stopped API before startup", "instance_id": "<host>", "module": "startup", "signal": "SIGINT", "level": "info", "timestamp": "2026-10-13T13:53:21.670798Z"}
SIGTERM после /health/live → exit=0
Uvicorn running on … → Started reloader process → Started server process → … → Started API → Application startup complete. → Shutting down → Waiting for application shutdown. → Stopped API → Application shutdown complete. → Finished server process → Stopping reloader process
```
`<host>` — имя машины (hostname, `instance_id` по умолчанию в консоли).
Traceback `KeyboardInterrupt` на Ctrl+C во время старта больше нет.
Reload: `driver.py start`, `touch src/main.py` — через 3 с в журнале
«Reloading» и новый старт воркера, `status` — `ready: True`, записи
ранней остановки нет. `driver.py all` на 18080: код 0, `FAILED: none` у
`flow`, `PASS` у smoke, 127 passed и 4 теста реплик пропущены с причиной
«one API process».
## Замена на рабочем стенде (задача 5.7)
`tests/load.py --duration 45 --concurrency 4` параллельно `make
rolling_update` (код 8 → реплики): скрипт — код 0, `removed old
eaf46242aa75 (stop 0s, exit 0)`, `removed old cc40cf19ba6e (stop 0s,
exit 0)`; `successful_requests` 30 000, `failed_requests` 0; обе новые
реплики `UP` на одном `.Image`, старт в журнале обычный. Ветка сбоя
скрипта и «до/после» остановки стартующей реплики —
`evidence/failover/stop-at-start.md`.
## Сверка ссылок исключений (задачи 6.4–6.6)
**Красная** — commit 10 `f241126`, до файлов доказательств:
```text
$ uv run pytest student-tests/test_coverage.py
student-tests/test_coverage.py::test_exclusion_evidence_exists FAILED
E AssertionError: exclusion refers to missing evidence/cache/hits.md: chat-cache / Временная база
E exclusion refers to missing evidence/cache/hits.md: chat-cache / Срок записи
E exclusion refers to missing evidence/cache/hits.md: chat-cache / Чтение из кэша
E exclusion refers to missing evidence/auth/passwords-and-tokens.md: sessions / Токена нет в хранилище
E exclusion refers to missing evidence/auth/passwords-and-tokens.md: users / Хэш в БД
==================== 1 failed, 7 passed, 1 skipped in 0.07s ====================
```
**Зелёная** — с `evidence/cache/hits.md` и
`evidence/auth/passwords-and-tokens.md` (commit 11 `949bea4`): `8
passed, 1 skipped` (пропуск — полная сверка, она идёт в `make
student_test`); `make student_test` через LB — `133 passed, 17
deselected` (было 131: два новых теста сверки), `coverage: 137
scenarios in 11 specs, 125 tested (18 by make failure_checks), 12
excluded`.
## Регрессия на итоговом коде (`949bea4`, задачи 7.1–7.8)
```text
$ make lint → All checks passed!
$ make check → PASS: offline skeleton structure, local refs and Python syntax
$ make validate PYTHON=.venv/bin/python → PASS: full OpenAPI 3.1 and JSON Schema validation
$ uv run python bench/scaling.py --selftest → selftest ok
$ uv run python bench/resources.py --selftest → selftest ok
$ однострочник 2.2 → swapouts ok
$ sh -n scripts/rolling-update.sh → exit 0
$ make test → PASS: lab3 public API scenario
$ make instances → instances: 2 (по 6)
$ make student_test → 133 passed, 17 deselected; coverage 137 / 125 / 12
$ make test-persistence ACTION_SCRIPT=scripts/restart.sh → PASS; те же ID, новый StartedAt у LB, обеих реплик, PostgreSQL, Valkey
$ STOP_ONE_LOG=… make test-failover ACTION_SCRIPT=scripts/stop-one.sh → PASS, TARGET 9cae7d3032c0 = контейнер, Exited (0)
$ make replicas; curl …/health/live; STOP_ONE_LOG=… make test-failover … → PASS, TARGET 6dfdb911e5f6 = контейнер, Exited (0)
$ make replicas; STOP_MODE=kill STOP_ONE_LOG=… make test-failover … → PASS, TARGET 6dfdb911e5f6, Exited (137)
$ make replicas; make lb_stats → обе UP
$ make test_isolated → exit 0: 129 passed, 4 skipped (one API process), 17 deselected
$ make failure_checks → exit 0: 17 passed; postgres log: 378 lines, crash markers 0; "too many clients" 23, "administrator command" 129
```
Быстрые профили (`make stop`, дерево чистое, хост: давление памяти
уровня 1, `Swapouts` без роста минуту):
```text
$ make bench_failover_quick && make bench_rollout_quick → chain-exit=0
quick-failover-20261013T144411Z: 4/4 фазы; stop — LB out 0,48 / 0,82 с, 0 ошибок; kill — 2 и 1 × 502, повторены с тем же ключом; messages = keys (9 203)
quick-rollout-20261013T144613Z: замена 10,17 с, ошибок 0 / 0 / 0, old after drain 0, 7 301 = 7 301;
raw/rollout-script.log: removed old b8259b663c7c (stop 1s, exit 0), removed old d69d6d0e1ce7 (stop 1s, exit 0)
```
Обе метки — `git.commit` `949bea4`, `dirty: false`, `swapouts_delta`
есть (33 452 и 18 728, предупреждения о выгрузке — хост на батарее с
IDE; это самопроверки, не замеры).
Что менял change в коде приложения и образа:
```text
$ git diff --stat 628bbfa 949bea4 -- src Dockerfile docker-compose.yml infra pyproject.toml uv.lock
src/__main__.py | 10 +++++--
src/infra/early_stop.py | 72 +++++++++++++++++++++++++++++++++++++++++++++++++
src/main.py | 5 ++++
3 files changed, 85 insertions(+), 2 deletions(-)
```
@@ -756,6 +756,36 @@ tasks.
- **[Проверка из чистого clone удаляет данные рабочего стенда]** → как в
прошлый раз; бриф это разрешает, стенд поднимается заново.
## Найдено в apply
- **Срок `docker stop` в `stop-at-start`.** Без `--timeout` `docker
stop` контейнера `docker run` на Docker Desktop 29.8.2 ждёт ~3,1 с, а
не 10 с (проба: процесс-PID 1 без обработчика, `StopTimeout` не
задан). Первый прогон «до» дал 3,1 с и код 137. Команда шлёт `docker
stop --timeout 10` (`stop_grace_period` compose) — отдельный commit
`f6052f6` между 7 и 8 (решение 14); «до» переснят на нём: 10,1 с.
- **`ended` в `run_phase`.** После перехода на поток переменная не
нужна (ruff F841) и удалена в commit 2; временная сверка (commit 3)
берёт конец окна буфера как `time.time() + 1` в момент сверки — та же
точка после `wait_ready`.
- **Посторонний контейнер и батарея.** Пользователь разрешил прогоны
`bench/` и `stop-at-start` от батареи и рядом с `domains-postgres-1`.
Его проверка здоровья — раз в 1 с, 2,8 события в секунду в буфере
демона, больше проверок стенда `bench/` (~1,8/с). В прогоне 1 сверки
(без помех) буфер всё же держал все 4 фазы (покрытие ~55 с при окне
~35 с); под шумом `docker exec` потерял все 4.
- **Давление памяти уровня 2** держалось ~35 мин посреди apply
(`Swapouts` без роста). Первый «после» `stop-at-start` снят при нём —
PASS; переснят при уровне 1 после `make rolling_update`, который
заодно вернул общий образ тегу и репликам: неуспешные запуски 5.8
пересобирают тег (`docker compose build` даёт новый `.Image` и без
изменений кода), и `.Image` тега расходился с репликами.
- **Ветка сбоя `rolling-update.sh`.** При `ROLLOUT_READY_TIMEOUT=1` и
`2` оба раза сработал путь со слотом (`maint`, `stop 0s, exit 0`): к
моменту уборки DNS уже отдал слот. Путь «no slot» в прогонах не выпал.
- **driver.py на Python 3.9:** `zip(strict=)` (B905 ruff) недоступен —
цикл по одной последовательности.
## Migration Plan
- **Рабочий стенд.** Новый код — `make rolling_update`, без простоя;
+50 -50
View File
@@ -72,13 +72,13 @@
## 1. Подготовка
- [ ] 1.1 Исходное состояние:
- [x] 1.1 Исходное состояние:
- `git status --porcelain` пуст;
- `git log --oneline -1` — commit `docs: propose fix-known-issues
change`. Его хэш — `BASE` в журнале;
- `docker compose ps` — пять контейнеров `mtusi-lab3` `healthy`,
`make lb_stats` — обе реплики `UP`. Иначе — `make run_docker`.
- [ ] 1.2 Read правил из таблицы «Правила слоёв» и по одному файлу из
- [x] 1.2 Read правил из таблицы «Правила слоёв» и по одному файлу из
каждого затрагиваемого каталога: `bench/run.py`,
`student-tests/run_failures.py`, `src/main.py`, `src/infra/logger.py`,
`scripts/rolling-update.sh`,
@@ -87,7 +87,7 @@
## 2. Паспорт метки — `swapouts_delta` (запись 5, решение 13)
- [ ] 2.1 `bench/run.py`:
- [x] 2.1 `bench/run.py`:
- функция `swapouts_delta(start, end) -> int | None` рядом со
`swap_warning`, с докстрингом: `None`, если одного счётчика нет;
иначе разность, в том числе 0;
@@ -97,7 +97,7 @@
- код ячеек серий (`host_swapouts`) не трогать.
Проверка: `git diff --stat` — только `bench/run.py`.
- [ ] 2.2 Самопроверка, вывод — в журнал:
- [x] 2.2 Самопроверка, вывод — в журнал:
```sh
uv run python -c "import sys; sys.path.insert(0, 'bench'); import run; d, w = run.swapouts_delta, run.swap_warning; assert d({'swapouts': 0}, {'swapouts': 0}) == 0; assert d({'swapouts': None}, {'swapouts': 3}) is None; assert d({'swapouts': 5}, {'swapouts': None}) is None; assert d({'swapouts': 5}, {'swapouts': 9}) == 4; assert w({'swapouts': 0}, {'swapouts': 0}) is None; assert w({'swapouts': 5}, {'swapouts': 9}) == 'host swapped out 4 pages during the run: rerun'; print('swapouts ok')"
@@ -105,11 +105,11 @@
Ожидается `swapouts ok`. Затем `make lint` — код 0, других файлов он
не меняет.
- [ ] 2.3 Commit 1. Проверка: `git status --porcelain` пуст.
- [x] 2.3 Commit 1. Проверка: `git status --porcelain` пуст.
## 3. События фазы `failover` — поток (запись 3, решения 9, 10)
- [ ] 3.1 `bench/run.py` (решение 9):
- [x] 3.1 `bench/run.py` (решение 9):
- метод `Stand.container_events(container, path)` — поток `docker
events` по контейнеру в файл, тот же фильтр и формат, что у прежнего
`Stand.events`; докстринг — почему поток (буфер демона, 256
@@ -128,8 +128,8 @@
- `uv run python bench/scaling.py --selftest` и `uv run python
bench/resources.py --selftest` — `selftest ok`;
- `make lint` — код 0.
- [ ] 3.2 Commit 2. Проверка: дерево чистое, хэш — в журнал.
- [ ] 3.3 Временная сверка (решение 10):
- [x] 3.2 Commit 2. Проверка: дерево чистое, хэш — в журнал.
- [x] 3.3 Временная сверка (решение 10):
- в `bench/run.py` — метод запроса к буферу демона: копия прежнего
`Stand.events` под именем `events_from_buffer`;
- в `run_phase` после событий из потока — тот же разбор по буферу за
@@ -140,7 +140,7 @@
- различаются — `BenchError`.
`make lint`, commit 3. Хэш — в журнал.
- [ ] 3.4 Прогон 1 без помех: проверка хоста (с `make stop`), затем
- [x] 3.4 Прогон 1 без помех: проверка хоста (с `make stop`), затем
`nohup make bench_failover_quick > <scratchpad>/fix-known-issues/failover-cross.log
2>&1 &`, ожидание. Проверка:
- код 0, 4 фазы;
@@ -152,7 +152,7 @@
`null`.
Чтение — `python3 -c` с `json.load`. Сбой — разбор.
- [ ] 3.5 Прогон 2 под шумом `docker exec`. Проверка хоста, затем:
- [x] 3.5 Прогон 2 под шумом `docker exec`. Проверка хоста, затем:
```sh
S=<scratchpad>/fix-known-issues; rm -f $S/noise.stop
@@ -169,11 +169,11 @@
Ни одна фаза не потеряла — шума мало: повтор один раз с двумя такими
циклами. Снова нет — записать как результат и идти дальше.
- [ ] 3.6 Откат сверки: `git revert --no-commit <commit 3>`, затем `git
- [x] 3.6 Откат сверки: `git revert --no-commit <commit 3>`, затем `git
commit`, сообщение commit 4 с телом «This reverts commit <хэш>.» и
строкой `Co-Authored-By`. Проверка: `git diff <commit 2> HEAD --
bench` пуст.
- [ ] 3.7 Итоговый прогон на окончательном коде: проверка хоста, `make
- [x] 3.7 Итоговый прогон на окончательном коде: проверка хоста, `make
bench_failover_quick` (фоном, журнал `failover-final.log`). Проверка:
- код 0, 4 фазы, строк «cross-check» нет;
- `meta.json`: `git.commit` = commit 4, `git.dirty` `false`,
@@ -184,7 +184,7 @@
## 4. PostgreSQL стенда отказов (запись 4, решения 11, 12)
- [ ] 4.1 `student-tests/run_failures.py` (решение 12):
- [x] 4.1 `student-tests/run_failures.py` (решение 12):
- константа признаков аварии;
- функция чтения журнала: `dc(project, "logs", "--no-log-prefix",
"postgres", quiet=True)`;
@@ -196,7 +196,7 @@
- строка в докстринге модуля.
`make lint`, commit 5.
- [ ] 4.2 Красный прогон, то есть воспроизведение дефекта на
- [x] 4.2 Красный прогон, то есть воспроизведение дефекта на
закоммиченном коде (сценарий «PostgreSQL перезапустился аварийно»):
`nohup make failure_checks > <scratchpad>/fix-known-issues/failure-red.log
2>&1 &`, ожидание (~70 с). Ожидается:
@@ -210,7 +210,7 @@
Не воспроизвелось — повтор `make failure_checks FAULT_ARGS='-k
connection_limit'` до двух раз. Нет и тогда — остановиться, разобрать
и вернуть отчёт основной сессии; `init: true` вслепую не коммитить.
- [ ] 4.3 Исправление (решение 11):
- [x] 4.3 Исправление (решение 11):
- `student-tests/failures.compose.yml`: `init: true` у `postgres`;
в шапке — зачем (сироты `psql` из `fill-connections` подбирает
init, а не postmaster);
@@ -218,7 +218,7 @@
init стенда. Код hook не меняется.
`make lint`, commit 6.
- [ ] 4.4 Зелёные прогоны (сценарий «Заполнение и освобождение
- [x] 4.4 Зелёные прогоны (сценарий «Заполнение и освобождение
слотов»): `make failure_checks` два раза. До и после — `StartedAt`
контейнеров `mtusi-lab3` (`docker inspect`). В каждом прогоне:
- код 0, 17 passed;
@@ -232,7 +232,7 @@
## 5. Ранний обработчик сигналов (запись 2, решения 3–8)
- [ ] 5.1 Команда `stop-at-start` в `driver.py` (решение 8): аргументы,
- [x] 5.1 Команда `stop-at-start` в `driver.py` (решение 8): аргументы,
контейнеры по метке, поток событий, классы попыток, «кто остановил»,
PASS, уборка в `finally`. Плюс строка в докстринге драйвера.
Проверка:
@@ -243,7 +243,7 @@
- `make lint` — код 0.
Commit 7.
- [ ] 5.2 «До» (сценарии `graceful-shutdown` на прежнем коде). Образ:
- [x] 5.2 «До» (сценарии `graceful-shutdown` на прежнем коде). Образ:
`git archive --format=tar HEAD | docker build -t
mtusi-messenger:stop-before -` — HEAD это commit 7, код приложения как
в `BASE`. ID образа — в журнал. Проверка хоста, затем `python3
@@ -255,7 +255,7 @@
журнале нет, а «Uvicorn running on» появился уже после сигнала —
дефект воспроизведён;
- попытки `running` и `server-start`: код 0, остановил `uvicorn`.
- [ ] 5.3 Код (решения 3–5):
- [x] 5.3 Код (решения 3–5):
- новый `src/infra/early_stop.py`: только stdlib, `install()`,
`disarm()`, обработчик — запись по решению 5 и `os._exit(0)` в
`finally`; докстринг со ссылкой на design;
@@ -269,7 +269,7 @@
stdlib;
- `.venv/bin/python -c "import src.infra.early_stop"` — код 0;
- `make lint` — код 0.
- [ ] 5.4 `scripts/rolling-update.sh`, `remove_new` (решение 7):
- [x] 5.4 `scripts/rolling-update.sh`, `remove_new` (решение 7):
- слот есть → `maint` → `docker stop --timeout 10` с временем и кодом
выхода → `docker rm -f` → адрес ушёл → `ready`;
- слота нет → `docker rm -f`;
@@ -278,8 +278,8 @@
Проверка: `sh -n scripts/rolling-update.sh`; `git diff` — только
`remove_new` и комментарии.
- [ ] 5.5 `make lint`, `make check`, commit 8. Хэш — в журнал.
- [ ] 5.6 Консоль на commit 8 (решение 6, сценарий «Ctrl+C в консоли во
- [x] 5.5 `make lint`, `make check`, commit 8. Хэш — в журнал.
- [x] 5.6 Консоль на commit 8 (решение 6, сценарий «Ctrl+C в консоли во
время старта»), порт 18089 свободен (`lsof -nP -iTCP:18089
-sTCP:LISTEN` пусто):
- SIGTERM на импорте:
@@ -300,7 +300,7 @@
$D start` (порт 18080), `touch src/main.py`, через 3 с в
`/tmp/mtusi-api-18080.log` — «Reloading», `python3 $D status` —
`ready: True`, `python3 $D stop`. `git status --porcelain` пуст.
- [ ] 5.7 Новый код на рабочий стенд без простоя:
- [x] 5.7 Новый код на рабочий стенд без простоя:
- до замены — ID и `.Image` реплик (`docker compose ps -q api`,
`docker inspect -f '{{.Image}}'`);
- `python3 tests/load.py --duration 45 --concurrency 4 >
@@ -314,7 +314,7 @@
- `make lb_stats` — две реплики `UP`;
- реплики с новыми ID на одном новом `.Image`;
- в журнале новых реплик — обычный старт.
- [ ] 5.8 Ветка сбоя `rolling-update.sh` (решение 7):
- [x] 5.8 Ветка сбоя `rolling-update.sh` (решение 7):
- `ROLLOUT_READY_TIMEOUT=1 make rolling_update`: код 1, строки
`removing new replica … that is not ready` и `removed new … (no
slot: docker rm -f)` или `(slot api-N: stop Ns, exit 0)`;
@@ -325,7 +325,7 @@
compose exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/9999 &&
echo "show servers state api" >&3 && cat <&3'` — у слотов
`srv_admin_state` 0 или 32, без флагов 1 и 8.
- [ ] 5.9 «После». Проверка хоста, затем `python3
- [x] 5.9 «После». Проверка хоста, затем `python3
.claude/skills/run-mtusi-messenger/driver.py stop-at-start --image
mtusi-messenger:lab3 > <scratchpad>/fix-known-issues/stop-after.log`.
ID образа равен `.Image` реплик рабочего стенда. Ожидается:
@@ -334,16 +334,16 @@
- хотя бы одна `server-start`: остановил `uvicorn`, ≤ 1 с, код 0. Ни
одной — повтор с `--server-start 10`;
- `running`: остановил `uvicorn`, код 0.
- [ ] 5.10 Регрессия консоли: `lsof -nP -iTCP:18080 -sTCP:LISTEN` пусто,
- [x] 5.10 Регрессия консоли: `lsof -nP -iTCP:18080 -sTCP:LISTEN` пусто,
затем `python3 .claude/skills/run-mtusi-messenger/driver.py all`.
Ожидается: `FAILED: none` у `flow`, `PASS` у smoke, все тесты прошли,
тесты реплик пропущены с причиной, код 0.
- [ ] 5.11 Уборка: `docker image rm mtusi-messenger:stop-before`; `docker
- [x] 5.11 Уборка: `docker image rm mtusi-messenger:stop-before`; `docker
ps -a --filter label=mtusi.stop-at-start -q` пусто.
## 6. Доказательства исключений сверки (запись 1, решения 1, 2)
- [ ] 6.1 Команды `cache-check` и `auth-storage` в `driver.py` (решение
- [x] 6.1 Команды `cache-check` и `auth-storage` в `driver.py` (решение
1), строки в докстринге. Проверка:
- `/usr/bin/python3 -m py_compile .claude/skills/run-mtusi-messenger/driver.py`;
- `make lint` — код 0;
@@ -351,11 +351,11 @@
в выводе нет токена, пароля и хэшей.
Commit 9.
- [ ] 6.2 `make test_isolated > <scratchpad>/fix-known-issues/test-isolated.log
- [x] 6.2 `make test_isolated > <scratchpad>/fix-known-issues/test-isolated.log
2>&1` при работающем рабочем стенде. Ожидается код 0, 4 теста реплик
пропущены с причиной. Сразу после — 6.3: ключи тестового прогона
нужны в Valkey.
- [ ] 6.3 Снятие доказательств, ничего другого на стенде не идёт:
- [x] 6.3 Снятие доказательств, ничего другого на стенде не идёт:
- `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080
cache-check > <scratchpad>/fix-known-issues/cache-check.log`. Код
0. Ожидается (решение 1, шаги 5–8): чтений `chats` 1, hits +49,
@@ -368,7 +368,7 @@
Проверка секретов: `grep -nE '/Users/|Bearer |\$argon2id\$[^ ]*\$[A-Za-z0-9+/]{8,}'`
по обоим журналам — пусто.
- [ ] 6.4 Сверка ссылок (решение 2):
- [x] 6.4 Сверка ссылок (решение 2):
- `missing_evidence` в `student-tests/spec_coverage.py`;
- два теста в `student-tests/test_coverage.py`;
- тексты `check` пяти исключений называют команды.
@@ -378,7 +378,7 @@
pytest student-tests/test_coverage.py`. Тест на настоящих исключениях
падает и называет пять сценариев и два пути, остальные проходят.
Вывод — в журнал.
- [ ] 6.5 `evidence/cache/hits.md` и `evidence/auth/passwords-and-tokens.md`
- [x] 6.5 `evidence/cache/hits.md` и `evidence/auth/passwords-and-tokens.md`
по образцу файлов лабы 2:
- шапка: спеки и сценарии, change, дата, commit (код команд —
commit 9, приложения — commit 8), стенд (LB, две реплики, лимиты),
@@ -389,26 +389,26 @@
Проверка: `uv run pytest student-tests/test_coverage.py` — зелёный;
grep секретов из 6.3 по обоим файлам — пусто.
- [ ] 6.6 `make student_test` через LB — все прошли (на 2 больше, чем
- [x] 6.6 `make student_test` через LB — все прошли (на 2 больше, чем
до change: 131 → 133), строка сверки покрытия с прежними числами
(137 / 125 / 12). Commit 11: оба файла.
## 7. Регрессия на итоговом коде
- [ ] 7.1 Статика:
- [x] 7.1 Статика:
- `make lint`, `make check`, `make validate PYTHON=.venv/bin/python`;
- `uv run python bench/scaling.py --selftest`, `uv run python
bench/resources.py --selftest`, однострочник 2.2;
- `sh -n scripts/rolling-update.sh`.
Все — код 0.
- [ ] 7.2 `make test` — `PASS`; `make instances` — `instances: 2`.
- [ ] 7.3 `make student_test` через LB — все прошли, тесты реплик
- [x] 7.2 `make test` — `PASS`; `make instances` — `instances: 2`.
- [x] 7.3 `make student_test` через LB — все прошли, тесты реплик
выполнены, строка сверки покрытия.
- [ ] 7.4 `make test-persistence ACTION_SCRIPT=scripts/restart.sh` —
- [x] 7.4 `make test-persistence ACTION_SCRIPT=scripts/restart.sh` —
`PASS`; `StartedAt` LB, реплик, PostgreSQL и Valkey до и после —
новые, ID те же.
- [ ] 7.5 `make test-failover` по `evidence/tests/clean-clone-final.md`,
- [x] 7.5 `make test-failover` по `evidence/tests/clean-clone-final.md`,
с `STOP_ONE_LOG`:
- `stop` для одной реплики, `make replicas`, сдвиг очереди одним
запросом, `stop` для другой;
@@ -417,10 +417,10 @@
Все `PASS`. ID остановленного контейнера = `TARGET_INSTANCE_ID`. Код
выхода: `Exited (0)` у `stop`, `Exited (137)` у `kill`. В конце `make
replicas`.
- [ ] 7.6 `make test_isolated` — код 0.
- [ ] 7.7 `make failure_checks` — код 0, сводка журнала PostgreSQL
- [x] 7.6 `make test_isolated` — код 0.
- [x] 7.7 `make failure_checks` — код 0, сводка журнала PostgreSQL
`crash markers 0`.
- [ ] 7.8 Быстрые профили на итоговом коде. Проверка хоста (с `make
- [x] 7.8 Быстрые профили на итоговом коде. Проверка хоста (с `make
stop`), дерево чистое, затем цепочкой фоном:
```sh
@@ -439,7 +439,7 @@
## 8. Документы и evidence проверок
- [ ] 8.1 `evidence/failover/stop-at-start.md`:
- [x] 8.1 `evidence/failover/stop-at-start.md`:
- шапка: сценарии `graceful-shutdown`, change, дата, commit «до» (7)
и «после» (8), ID образов, лимиты (1 CPU / 512 МиБ, без сети),
хост;
@@ -448,7 +448,7 @@
- строки `rolling-update.sh` ветки сбоя (5.8) и коды выхода старых
реплик при замене (5.7);
- вывод: что исправлено и что осталось — окно 0.
- [ ] 8.2 `evidence/tests/fix-known-issues-checks.md`, в стиле
- [x] 8.2 `evidence/tests/fix-known-issues-checks.md`, в стиле
`rolling-update-checks.md`. Шапка — change, даты, хэши коммитов 1–11,
стенды, хост. Разделы:
- самопроверка `swapouts_delta` (2.2);
@@ -463,10 +463,10 @@
- `git diff --stat <BASE> HEAD -- src Dockerfile docker-compose.yml
infra pyproject.toml uv.lock` — только `src/__main__.py`,
`src/main.py`, `src/infra/early_stop.py`.
- [ ] 8.3 `KNOWN_ISSUES.md`: пять записей удалить, шапку оставить, плюс
- [x] 8.3 `KNOWN_ISSUES.md`: пять записей удалить, шапку оставить, плюс
строка «Открытых записей нет: записи лабы 3 исправлены change
`fix-known-issues`.» Проверка: `grep -c '^## ' KNOWN_ISSUES.md` → 0.
- [ ] 8.4 Правила — факты, которые меняет change:
- [x] 8.4 Правила — факты, которые меняет change:
- `docker.md`, пункт `CMD`: сервер — PID 1, ранний обработчик до
импорта приложения, почему без `init` у `api`;
- `run-modes.md`: «Точка входа» (`src/__main__.py` → `early_stop` →
@@ -485,11 +485,11 @@
Проверка: `grep -n "KNOWN_ISSUES" .claude/rules/*.md` — нет ссылок на
удалённые записи; каждое изменённое утверждение сверено с кодом.
- [ ] 8.5 `.claude/skills/run-mtusi-messenger/SKILL.md`: строки таблицы
- [x] 8.5 `.claude/skills/run-mtusi-messenger/SKILL.md`: строки таблицы
команд и примеры для `stop-at-start`, `cache-check`, `auth-storage`.
Проверка: `python3 .claude/skills/run-mtusi-messenger/driver.py
--help` перечисляет их, описания совпадают.
- [ ] 8.6 `AGENTS.md`:
- [x] 8.6 `AGENTS.md`:
- вступление: change `fix-known-issues` в перечне и что он
исправил; число changes в архиве — по факту;
- таблица команд: `make failure_checks` — проверка журнала
@@ -506,7 +506,7 @@
Проверка: `grep -n "early_stop\|fix-known-issues\|cache-check" AGENTS.md`
находит новые строки.
- [ ] 8.7 `REPORT.md`, свежий Read:
- [x] 8.7 `REPORT.md`, свежий Read:
- шапка: `fix-known-issues` в списке «Сделано по changes». Абзац о
проверке из чистого clone — в 9.3;
- таблица доказательств — новые строки с командой, наблюдением и
@@ -534,9 +534,9 @@
Проверка: `grep -n "не исправлены\|evidence лабы 2" REPORT.md` —
пусто; `grep -n "теряется" REPORT.md` — только про окно 0 (запуск
интерпретатора).
- [ ] 8.8 Файлы change: отметки задач из журнала в `tasks.md`; раздел
- [x] 8.8 Файлы change: отметки задач из журнала в `tasks.md`; раздел
«Найдено в apply» в `design.md`, если было что найти.
- [ ] 8.9 Финал документов:
- [x] 8.9 Финал документов:
- `make lint`, `make check`, `openspec validate fix-known-issues
--strict` — код 0;
- grep секретов из 6.3 по новым и изменённым файлам `evidence/` —