diff --git a/.claude/rules/balancer.md b/.claude/rules/balancer.md index 67476796..fa1bc716 100644 --- a/.claude/rules/balancer.md +++ b/.claude/rules/balancer.md @@ -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 (slot + api-N: stop Ns, exit N)`. Стартующая реплика выходит сразу по раннему + обработчику SIGTERM (`run-modes.md`), работающая — дорабатывает + запросы, которые LB успел отправить на слот до `maint`; +- слота нет → сразу `docker rm -f`, строка `removed new (no slot: + docker rm -f)`: запросов на ней не было, а это ещё и страховка на окно + запуска интерпретатора, где SIGTERM некому принять. + +Новая уже `UP` — вывод текущей старой доводится до конца. Прерывание внутри `up --scale`, когда ID новой ещё не известен: уборка находит её сама — контейнер, которого не было до команды. ID новой прежнего шага сбрасывается до перехода в это состояние: иначе уборка diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index 6699f04c..0135cfbc 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -171,6 +171,17 @@ paths: (`docker events`), исключение и возврат в LB — строки журнала HAProxy (`docker logs -t`), запросы — `Date.now()` k6 при отправке. Часы хоста с ними не сравниваются. +- События цели — **поток** `Stand.container_events` (`docker events + --filter container=` в `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`), в отчёте оно указывается по diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index d69e0354..5867e5b6 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -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 diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 27f9a0a7..3e6aa94c 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -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`). diff --git a/.claude/rules/logging.md b/.claude/rules/logging.md index c173513e..7dddd4be 100644 --- a/.claude/rules/logging.md +++ b/.claude/rules/logging.md @@ -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/.py` | подключение, закрытие, ошибки; запросы к внешним API (`debug`) | `module=""` | | `main.py` | старт (host, port, режим), начало и конец shutdown | `module="startup"` | +| `infra/early_stop.py` | только остановка до старта сервера, одна запись без structlog (раздел выше) | нет, поле `module` — `startup` | | чистые функции | не логируют, бросают доменные исключения | нет | Строки старта и shutdown нужны на защите: по ним видно, что SIGTERM diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index 08b45279..8ab07ae1 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -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` реплики ошибок от её недоступности не даёт — diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 8d6b7a41..86299209 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -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 cache-check` (после `make + test_isolated` — для «Временной базы») → `evidence/cache/hits.md`, + `driver.py --port 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` затенил бы diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 78f01b03..ef199728 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -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:` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_`) базы. Код 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= 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= MIGRATE=0 # откат на образ прежнего commit (git archive), схема остаётся новой diff --git a/AGENTS.md b/AGENTS.md index a7edbdb6..53292761 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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_` с 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/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ и сообщение одной транзакцией exceptions/.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_.py # сценарии основных спеков, маркер @pytest.mark.spec test_failures.py # проверки отказов (маркер fault): только make failure_checks run_isolated.py # make test_isolated: образ на временной базе test_ (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 cache-check` → `evidence/cache/hits.md`; `driver.py --port + 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, потом править код. Обновить этот файл: номер лабы, таблицу важных файлов, новые правила. diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index 6b523454..c54dcdd5 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -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`. diff --git a/REPORT.md b/REPORT.md index 7bdfd0bc..d3c50eff 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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/`; решения, перечисленные выше, принимал diff --git a/evidence/failover/stop-at-start.md b/evidence/failover/stop-at-start.md new file mode 100644 index 00000000..b3b18068 --- /dev/null +++ b/evidence/failover/stop-at-start.md @@ -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`: запросов на ней нет. diff --git a/evidence/tests/fix-known-issues-checks.md b/evidence/tests/fix-known-issues-checks.md new file mode 100644 index 00000000..e4d7ffd0 --- /dev/null +++ b/evidence/tests/fix-known-issues-checks.md @@ -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": "", "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": "", "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 +``` + +`` — имя машины (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(-) +``` diff --git a/openspec/changes/fix-known-issues/design.md b/openspec/changes/fix-known-issues/design.md index 6ed433c4..3f2760c2 100644 --- a/openspec/changes/fix-known-issues/design.md +++ b/openspec/changes/fix-known-issues/design.md @@ -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`, без простоя; diff --git a/openspec/changes/fix-known-issues/tasks.md b/openspec/changes/fix-known-issues/tasks.md index 0e6414ce..08b7ac94 100644 --- a/openspec/changes/fix-known-issues/tasks.md +++ b/openspec/changes/fix-known-issues/tasks.md @@ -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 > /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=/fix-known-issues; rm -f $S/noise.stop @@ -169,11 +169,11 @@ Ни одна фаза не потеряла — шума мало: повтор один раз с двумя такими циклами. Снова нет — записать как результат и идти дальше. -- [ ] 3.6 Откат сверки: `git revert --no-commit `, затем `git +- [x] 3.6 Откат сверки: `git revert --no-commit `, затем `git commit`, сообщение commit 4 с телом «This reverts commit <хэш>.» и строкой `Co-Authored-By`. Проверка: `git diff 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 > /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 > /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 > /fix-known-issues/test-isolated.log +- [x] 6.2 `make test_isolated > /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 > /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 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/` —