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

151 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Proposal
## Why
Лаба 3 закрыта, но в `KNOWN_ISSUES.md` остались пять записей. Две из
них — дефекты поведения. Реплика, остановленная в первую секунду
старта, теряет SIGTERM и через 10 с получает SIGKILL;
`scripts/rolling-update.sh` обходит это `docker rm -f`. `make
failure_checks` посреди набора роняет PostgreSQL своего стенда в crash
recovery. Третья запись — дыра в доказательствах: пять исключений
сверки покрытия ссылаются на evidence лабы 2, которого в этом
репозитории нет. Ещё две — хрупкость стенда `bench/`: профиль `failover`
берёт события Docker из буфера демона (256 событий, запас около двух
раз), а поле паспорта `swapouts_delta` пропадает при нулевом счётчике
выгрузок. Пользователь попросил исправить всё, что можно, до переноса
кода в лабу 4: дефекты переехали бы вместе с кодом.
## What Changes
- **Исключения сверки покрытия — доказательства лабы 3.**
- Сценарии `chat-cache` «Чтение из кэша», «Срок записи», «Временная
база», `sessions` «Токена нет в хранилище» и `users` «Хэш в БД»
проверяются заново на стенде лабы 3 (HAProxy и две реплики).
- Проверки делают две новые команды драйвера скилла
`run-mtusi-messenger`: `cache-check` и `auth-storage`. Результаты —
в `evidence/cache/hits.md` и `evidence/auth/passwords-and-tokens.md`,
только факты, счётчики и префиксы, без токенов, паролей и полных
хэшей.
- Исключения называют эти команды.
- Сверка покрытия падает, если исключение ссылается на файл
`evidence/`, которого нет в репозитории.
- **SIGTERM на старте реплики больше не теряется.**
- Точка входа `python -m src` до импорта приложения ставит свой
обработчик SIGTERM и SIGINT. Пока сервер не стартовал, запросов
нет, и процесс завершается сразу: код 0, одна запись журнала
`info`.
- Сигнал во время старта сервера и остановка работающей реплики
обрабатываются как раньше. Сервер по-прежнему PID 1, без `init`.
- `rolling-update.sh` убирает неготовую новую реплику со слотом LB
штатной остановкой после `maint`. `docker rm -f` остаётся для
реплики без слота.
- Воспроизведение «до/после» — новая команда драйвера `stop-at-start`.
- **События фазы `failover` — поток.** События реплики фазы читаются
потоком `docker events`, запущенным до нагрузки фазы, как у профиля
`rollout`, а не из буфера демона после фазы.
- **PostgreSQL стенда отказов без аварий.**
- У `postgres` в `student-tests/failures.compose.yml` — `init: true`:
сирот `psql` из `fill-connections` подбирает init, а не postmaster.
- `make failure_checks` перед уборкой проверяет журнал PostgreSQL
стенда и падает на признаках аварийного перезапуска.
- **`swapouts_delta` при нулевом счётчике.** Паспорт метки пишет прирост
выгрузок и тогда, когда счётчик в конце равен 0.
- **Регрессия на новом коде** — смоук, собственные тесты, проверки
отказов, failover, persistence, `make rolling_update` под нагрузкой,
быстрые профили. Плюс повтор проверки из чистого clone: код
приложения меняется после итоговой проверки (`dbb9150`).
- **Документы:**
- `KNOWN_ISSUES.md` без исправленных записей;
- `REPORT.md`, `AGENTS.md`;
- правила `.claude/rules/`;
- `SKILL.md` драйвера.
## Non-goals
- **Окно запуска интерпретатора.** В первые десятки миллисекунд, до
первых строк точки входа, SIGTERM процессу с PID 1 по-прежнему не
доставляется: `docker stop` в этот миг ждёт 10 с и SIGKILL. Закрыть
это окно может только init-процесс, а он противоречит
`.claude/rules/docker.md` и спеку `container-image` («Сервер —
основной процесс контейнера»). В `rolling-update.sh` это окно
обходится: реплику без слота LB скрипт убирает `docker rm -f`,
запросов на ней нет.
- **Метки `failover/baseline` и `failover/resources` не переснимаются.**
События в них найдены, а величины фазы зависят только от отметок тех
же событий демона. Способ чтения их не меняет: это проверяется
сверкой обоих способов на одном прогоне (design).
- **Паспорта меток `scaling-db-aa2`, `scaling-db-before2`,
`scaling-db-nooverflow2` не правятся.** Это измеренное состояние;
`Swapouts` 0 в начале и в конце в них записаны. Отсутствие поля
оговаривается в `REPORT.md`.
- **Профиль `rollout` не меняется:** он уже читает события потоком.
- **Evidence лабы 2 не копируется, и ссылок на репозиторий лабы 2 нет.**
У лабы 3 другой стенд (LB, две реплики, общий Valkey), и каждая лаба
держит свои доказательства.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `graceful-shutdown`: новое требование «Остановка во время старта» —
сигнал до старта сервера и во время старта не теряется, сроки, код
выхода, запись журнала.
- `student-tests`: новые требования:
- «Доказательства исключений сверки в репозитории» — файл, на который
ссылается исключение, есть в репозитории лабы, снят на её стенде и
без секретов; иначе сверка падает;
- «PostgreSQL стенда отказов без аварийных перезапусков» — проверки
не роняют PostgreSQL стенда, `make failure_checks` проверяет его
журнал.
- `load-benchmark`: новое требование «События Docker профилей отказа и
замены» — поток, запущенный до нагрузки, без зависимости от истории
демона.
Не меняются:
- `chat-cache`, `sessions`, `users`: сценарии те же, меняется только
доказательство исключений;
- `load-balancing`: «Сбой поочерёдной замены» выполняется по-прежнему,
неготовая новая реплика удаляется;
- `service-logging`: запись ранней остановки — JSON с `timestamp`,
`level`, `event` и `instance_id`;
- `container-image`: сервер — по-прежнему PID 1.
## Impact
- **Приложение:** `src/__main__.py`, новый модуль в `src/infra/`
(только stdlib), lifespan в `src/main.py`. Контракт, API, `Dockerfile`
и compose рабочего стенда не меняются.
- **Скрипты:** `scripts/rolling-update.sh`, функция `remove_new`.
- **Тесты и стенд отказов:**
- `student-tests/spec_coverage.py`, `test_coverage.py`;
- `run_failures.py`, `failures.compose.yml`;
- `fault_hook.py` — только комментарии.
- **Стенд `bench/`:** `run.py` — профиль `failover` и паспорт. Методика
меток не меняется.
- **Драйвер скилла:** команды `stop-at-start`, `cache-check`,
`auth-storage`, `SKILL.md`.
- **Evidence:**
- новые: `evidence/cache/hits.md`, `evidence/auth/passwords-and-tokens.md`,
`evidence/failover/stop-at-start.md`,
`evidence/tests/fix-known-issues-checks.md`;
- переписывается: `evidence/tests/clean-clone-final.md`.
- **Документы:** `REPORT.md`, `AGENTS.md`, `KNOWN_ISSUES.md`, правила
`docker.md`, `run-modes.md`, `logging.md`, `infra.md`, `balancer.md`,
`student-tests.md`, `bench.md`.
- **Рабочий стенд:**
- новый код — через `make rolling_update`, без простоя;
- итоговая проверка из чистого clone удаляет его данные (`down -v`),
как в прошлый раз, и поднимает заново.
- **Следующая лаба:** сверка покрытия упадёт, пока доказательства
исключений не сняты на её стенде. Это намеренно, а переснять их — по
команде на файл (`AGENTS.md`, «Переход в следующую лабу»).
- **Время:**
- четыре быстрых профиля `failover` и один `rollout` — ~12 мин;
- `make failure_checks` четыре раза — ~5 мин;
- `make test_isolated` дважды — ~2 мин;
- проверка из чистого clone — ~25 мин.