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

10 KiB
Raw Blame History

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 мин.