Repeat the REPORT.md "Запуск из чистого clone" sequence from a real git clone of the final strict-id-validation code on the default ports: env setup, stand, no-cache build, check, validate, smoke, instances on two Python versions, persistence, failover of each replica and kill, own tests, fault checks and the isolated run. All steps exit 0. The clone ran as compose project mtusi-lab3-cleancheck while the working stand was only stopped, because removing its volume was refused by the agent's auto mode; the previous checks ran as mtusi-lab3. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
69 KiB
MTUSI Messenger
REST API мессенджера (пользователи, чаты, история сообщений). Этот код
переносится через все семь лабораторных курса и на каждой обрастает
инфраструктурой. Текущая работа — лаба 3 (lab.json): балансировщик,
≥2 взаимозаменяемые API-реплики, общие сессии, обязательный
Idempotency-Key на отправке сообщения и X-Instance-Id в ответах
(README.md, COURSE.md, переход 2 → 3). Код перенесён из лабы 2
(репозиторий mtusi2026lab2-safronov, ветка solution/bvt2301-safronov,
commit c6ad34d): PostgreSQL как источник истины, вход по Basic →
Bearer-сессия, Valkey — кэш карточек чатов, трек 2 лабы 2 (план запроса
и восстановление) в bench/. Change instance-id-idempotency добавил
X-Instance-Id и Idempotency-Key, replicas-lb — HAProxy перед
двумя репликами API, лимиты, scripts/stop-one.sh,
graceful-failover — обоснованная и замеренная цепочка таймаутов,
стенд bench/ на HAProxy + N реплик и профиль failover,
rolling-update — поочерёдная замена реплик с дренажём через runtime
API HAProxy (make rolling_update), expand-миграция и профиль
rollout, scaling-bench — серии трека 1 «Цена масштабирования»
(make bench_scaling: открытая модель, поиск R*, сэмплер, графики,
насыщение пула и PostgreSQL управляемыми опытами) и ответ 503 на отказ
PostgreSQL «too many clients», scaling-improvement — пул PostgreSQL
10 + 0 без переполнения (улучшение трека 1: профиль SERIES=db4,
«до/после» с A/A, засчитано с оговоркой), profile-resources — CPU и
память каждого компонента по окнам профилей failover и rollout
(сэмплер scan, bench/resources.py, метки resources; добавлен после
закрытия лабы, код приложения не трогает), 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; сверка падает на ссылке на
отсутствующий файл), strict-id-validation — по рецензии PR:
изменённый клиентом курсор — 400 вместо 500 (поля курсора проверяются
по отдельности, незнакомые игнорируются — формат открыт для совместимых
правок при поочерёдной замене), UUID на входе (chat_id, member_ids)
— только запись 8-4-4-4-12 (UuidIn). Лаба 3 закрыта: все девять
changes лабы 3 (девятый — strict-id-validation), как и changes
перехода на lab2, — в openspec/changes/archive/, спеки
синхронизированы, активных changes нет; KNOWN_ISSUES.md без открытых
записей, REPORT.md заполнен, чистый clone проверен на итоговом коде
ebf080a (evidence/tests/clean-clone-final.md). Дальше —
перенос в лабу 4 (раздел «Переход в следующую лабу»). Рабочий план лабы
(PLAN.md) удалён, его решения — в REPORT.md и design архивных
changes; последняя версия — git show 063eedb:PLAN.md. Стек:
Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
(JSON в stdout), redis-py (клиент Valkey).
Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные
проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные
тесты и REPORT.md пишем мы.
Обязательные правила
-
Контракт и skeleton не менять:
contracts/,tests/,scripts/(кроме своихscripts/restart.shиscripts/stop-one.shпо образцамrestart.example.shиstop-one.example.sh),lab.json,README.md,COURSE.md,CONTRIBUTING.md,MAINTAINERS.md,.github/,compose.example.yaml,infra/README.md, целиcheck/validate/test/load/test-persistence/test-failoverвMakefile. Если публичный тест упал, чиним приложение, а не тест. Если в контракте противоречие — сказать пользователю (это вопрос преподавателю), не выбирать трактовку самому. Ответ преподавателя записать в «Согласования с преподавателем». -
Git не трогать без явной просьбы: никаких commit, push, checkout, reset, stash. Смотреть можно (
git status,git diff,git log). Замер или evidence для отчёта снимается с закоммиченного кода, но коммит — только после подтверждения пользователя: показать изменения, предложить сообщение, ждать ок (.claude/rules/bench.md, «Измеренное состояние — commit»). -
Перед завершением задачи с кодом —
make lint. Правки API проверять на запущенном сервере (make run_devили контейнер, затемmake testиmake student_test), а не «на глаз». -
Тесты пишем, но только black-box по HTTP в
student-tests/(.claude/rules/student-tests.md). В bp_proxies тесты были запрещены, здесь они часть рубрики уровня 4. -
Упавший тест — сначала разбор, потом правка. Воспроизвести падение, прочитать вывод и назвать причину: дефект приложения, ошибка в самом тесте или стенд (чужой сервис на порту, старый образ, не тот
BASE_URL). Только после этого что-то менять, а в итоге задачи сказать, в чём была причина. -
Если тест упал, чинится код, а не тест. Упавший тест из
student-tests/правится только в крайнем случае:- поведение меняется намеренно: так записано в дельте спека OpenSpec change или в контракте новой лабы. Тест правится вместе со спеком;
- тест ошибочен сам: противоречит спеку или контракту либо зависит от случайного (порядок тестов, время, чужие данные на стенде). В итоге задачи назвать, чему именно он противоречит.
«Тест красный» — не причина его править. Нельзя ослаблять проверку, подгонять ожидание под фактический ответ, ставить
skip/xfailили удалять тест, чтобы прогон позеленел. Дефект приложения вне текущей задачи записывается вKNOWN_ISSUES.md(правило ниже), а тест остаётся как есть. Если причина неясна или правка теста спорная — остановиться и спросить. -
Лаба 2: источник истины — PostgreSQL, SQLite его не заменяет. Пользователи, чаты, участники, сообщения и ещё действующие сессии переживают рестарт API и хранилищ без удаления volumes. Basic — только на
POST /auth/sessions, остальное — Bearer;X-User-Idдоступа не даёт; пароли — только через password KDF (auth.md). Valkey — на «4», кэш карточки чата: источник истины — PostgreSQL, отказ Valkey — обход кэша, а не ошибка (infra.md). Всё это сохраняется в лабе 3. -
Лаба 3: ≥2 взаимозаменяемые реплики
apiза HAProxy — единственной публичной точкой входа; порты реплик наружу не публикуются, sticky session нет. В памяти процесса нет ничего, от чего зависит корректность: сессии, данные и ключи идемпотентности — в Postgres, Valkey — общий кэш неизменяемых карточек. В каждом ответе API —X-Instance-Id.POSTсообщения требуетIdempotency-Key; ключ и сообщение пишутся в одной транзакции (api-contract.md,service-layer.md). Миграции — однократно, отдельным сервисом, не репликами, и только расширяют схему: старые реплики работают на новой (migrations.md). Новый код доходит до реплик без простоя черезmake rolling_update. Стенд и отказы —balancer.md. В каждом процессе uvicorn по-прежнему один worker: масштабирование — числом реплик. -
.env,config.toml, секреты, токены и реальные данные не попадают ни в git, ни в образ. Вevidence/иREPORT.md— только обезличенные выводы команд. -
Найденный попутно дефект не чинить без просьбы: записать в
KNOWN_ISSUES.md(завести при первой находке) с путём и предложением правки. -
OpenSpec: если команде
/opsx:*подходит больше одного изменения (change) — несколько активных вopenspec/changes/, имя совпало частично, из контекста подходят несколько, — не выполнять её для всех подряд и не выбирать самому. Спросить, для какого изменения запустить: варианты — каждое по имени, последним — «все». То же при нескольких подходящих спеках (capability).
Согласования с преподавателем
Договорённости, которых нет в skeleton. Каждую упомянуть в REPORT.md
и перенести в следующую лабу вместе с этим файлом, если она ещё
действует.
| Дата | Договорённость | Где учтено |
|---|---|---|
| 2026-09-26 | Лабы можно делать на FastAPI, несмотря на расхождения с контрактом (лишний 422, другой порядок кодов ошибок). Публичный smoke при этом должен проходить | .claude/rules/api-contract.md, раздел «FastAPI» |
| 2026-09-29 | Конфиг через pydantic-settings: окружение → .env → config.toml → дефолты. config.toml не в git и не в образе, монтируется read-only при запуске. Это подходит под «конфигурация приходит из окружения» (README лабы 1, п. 3) и п. 6 Dockerfile.example. Требование «только env» — упрощение курса, config.toml можно использовать |
.claude/rules/settings.md, .claude/rules/docker.md |
Задание и контракт: важные файлы
| Файл | Что в нём |
|---|---|
README.md |
задание лабы: рубрика 3/4/5, сценарий и вопросы защиты, что приложить к PR |
COURSE.md |
карта семи лаб, три объявленных перехода API (1→2, 2→3, 4→5), правила честных измерений |
contracts/openapi.json |
нормативный OpenAPI 3.1: пути, схемы, коды ответов |
contracts/README.md |
нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв, с lab3 — Idempotency-Key и X-Instance-Id; разделы lab4+ — на будущее |
contracts/examples.json, infrastructure.json |
примеры тел (проверяет make validate); роли инфраструктуры лабы: api ×2+ без локального состояния, postgres, load_balancer; Redis/Valkey — необязательно; внутренние порты реплик в обход LB не публикуются |
lab.json |
номер лабы (3); по нему tests/client.py выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer; с лабы 3 — идемпотентность) |
tests/smoke.py, tests/client.py |
публичный сквозной сценарий make test; что он проверяет и чего нет — tests/README.md |
tests/resilience.py |
make test-persistence: данные и прежний токен после restart hook; make test-failover: ≥2 реплики, запись во время остановки одной, повтор с тем же ключом, без дублей |
tests/load.py |
closed-loop нагрузка POST сообщений (make load); для трека 5 одного его мало |
scripts/check_contract.py, scripts/validate_openapi.py |
make check / make validate |
scripts/restart.example.sh |
образец restart hook; свой — scripts/restart.sh: перезапуск API и всех хранилищ без удаления volumes |
scripts/stop-one.example.sh |
образец failover hook; свой — scripts/stop-one.sh: остановить одну API-реплику по TARGET_INSTANCE_ID и оставить её остановленной |
compose.example.yaml |
список ролей с пустым services, не стенд; свой стенд — свой compose-файл |
infra/README.md |
куда класть конфигурации сервисов и что сопоставить в REPORT.md |
REPORT.md |
отчёт: запуск из чистого clone, архитектура, доказательства по каждому критерию, эксперименты, ИИ и источники |
evidence/ |
сохранённые выводы проверок и измерений (что можно класть — evidence/README.md) |
CONTRIBUTING.md |
fork/PR, имя ветки, что переносить в следующую лабу |
.github/pull_request_template.md |
шаблон PR; CI workflows/contracts.yml проверяет только контракт, приложение не запускает |
Dockerfile.example |
опорные шаги Dockerfile, не рабочий файл |
.env.example |
шаблон .env; «логические» имена skeleton (lab2 и новые lab3 API_REPLICAS, IDEMPOTENCY_TTL_SECONDS) перечислены в шапке, их соответствие — в REPORT.md (settings.md) |
examples/requests.http |
ручные запросы для HTTP-клиента IDE |
Где лежат инструкции
Четыре уровня, не дублировать их друг в друге:
-
AGENTS.md(этот файл): инварианты, команды, карта кода.CLAUDE.mdимпортирует его. -
.claude/rules/*.md: правила по слоям. Подгружаются автоматически, когда открыт файл изpaths:во фронтматтере. Проект пишется с нуля, а при создании файла через Write правило само не подгрузится. Поэтому перед созданием первого файла слоя его правило нужно прочитать руками.Файл Действует на api-contract.mdsrc/api/**,src/core/**,src/schemas/**,student-tests/**: что требует контракт и где FastAPI по умолчанию его нарушаетapi-layer.mdsrc/api/**,src/main.py: роутеры, зависимости, middlewares, обработчики ошибокservice-layer.mdsrc/core/services/**repo-layer.mdsrc/core/repos/**dto.mdsrc/schemas/**infra.mdsrc/infra/**: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе) и другие клиентыauth.mdsrc/**/session.py, сервис пользователей,dependencies.py,errors.py, идентификация вstudent-tests/: пароль и KDF, разбор Basic, токен, срок и отзыв сессииlogging.mdсервисы, API, инфраструктура, src/main.py: где и как логировать, чего в логах быть не должноsettings.mdsrc/config/**,.env.example,config_example.toml: источники настроек, что куда кластьrun-modes.mdточки входа, Makefile, compose, шаблоны конфигов: console и docker, uvicorn, SIGTERMdocker.mdDockerfile,docker-compose.yml,.dockerignore,scripts/restart.sh,infra/**: мультистейдж, non-root, пины, healthcheck, стенд compose, volumes, restart hookbalancer.mddocker-compose.yml,infra/haproxy/**,scripts/stop-one.sh,scripts/rolling-update.sh: реплики за HAProxy, проверки и цепочка таймаутов, повторы LB, failover hook, поочерёдная замена, лимиты и пулы (с лабы 3)student-tests.mdstudent-tests/**: обязательные проверки уровня 4, black-box по HTTP, особый стендbench.mdbench/**: нагрузочный стенд на Postgres (проект composemtusi-bench), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состоянийmigrations.mdmigrations/**,alembic.ini,src/infra/db/models/**: схема до запросов, ограничения, индексы, повторный запуск миграций -
openspec/(схемаspec-driven, язык артефактов — русский, см.openspec/config.yaml): что система делает и зачем.specs/<capability>/spec.md— текущее поведение,changes/<change>/— предложения (proposal.md,design.md,tasks.md, дельты спеков),changes/archive/— внедрённые. Крупную работу ведут командами/opsx:propose→/opsx:apply→/opsx:verify→/opsx:archive(ещёexplore,update,sync). Команды в.claude/commands/opsx/ставитopenspec update, руками их не править. Спеки не пересказывают контракт и правила: вtasks.mdссылаться наcontracts/и.claude/rules/, а не копировать их. -
Граф кода (
graphify-out/, CLI graphify; локальный, не в git и не в образе, состав —.graphifyignore): для вопросов о структуре и связях — где используется, кто вызывает, что затронет правка. Команды:graphify query "<вопрос>",graphify path "A" "B",graphify explain "X",graphify affected "X". Граф — подсказка, а не источник правды: до обновления он отстаёт от кода.- Перед правкой — Read файла, как без графа: иначе правило слоя из
.claude/rules/не подгрузится. Граф этого не заменяет. - Граф строится без LLM: код — по AST, markdown — по структуре
(разделы становятся узлами). Раздел правила или спеки связан
(
references, INFERRED) с символами кода, упомянутыми в его тексте в обратных кавычках. Полной карты «правило → код» в графе нет — она в таблице выше и вpaths:правил. queryищет узлы по подстроке метки. В запрос — имена символов кода ("ChatService ChatNotFound chat"), а не пересказ вопроса: тогда в ответе и код, и разделы правил и спек.- В граф не попадают
.json/.yaml/.yml(contracts/openapi.json,docker-compose.yml),Dockerfile,Makefileи шаблоны конфигов: их CLI не разбирает. По ним —grep. - Только CLI
graphify update .. Не запускать скилл/graphifyиgraphify extract: семантический разбор документов через LLM стоит сотни тысяч токенов, а следующийgraphify update .всё равно заменяет его структурным. Не запускатьgraphify install,graphify claude install,graphify hook installиgraphify watch: первые два пишут секцию вCLAUDE.mdи PreToolUse-хук на Read, остальные пересобирают граф без спроса.
- Перед правкой — Read файла, как без графа: иначе правило слоя из
Окружение и команды
- Python 3.12 (
.python-version), зависимости через uv (uv sync,uv run ...), lock вuv.lock. ruff глобальный (/opt/homebrew/bin/ruff, им же пользуется PyCharm), в проекте он в extradev. - Конфиг:
.env(то, что читают compose и контейнеры зависимостей) +config.toml(то, что читает только приложение). Читает ихsrc/config/settings.py(pydantic-settings), все поля — в секциях. Приоритет: окружение >.env>config.toml> дефолты. Параметры приложения в.envпишутся в формате настроек (APP__PORT), без секции — только то, что приложение не читает (APP_OUT_PORT).config.tomlв образ не копируется, а монтируется на старте. РежимAPP__RUN_MODE(console/docker) в.envне хранится. Подробно —settings.md,docker.mdиrun-modes.md. - Точка входа:
python -m src(src/__main__.py→src/main.py), порт 8080. make testходит наhttp://localhost:8080. Если там отвечает чужой сервис, smoke упадёт с 404 на/health/liveвместо ошибки соединения. Проверить, кто занял порт:lsof -nP -iTCP:8080 -sTCP:LISTEN,docker ps.- Стенд — проект compose
mtusi-lab3со своей базой. Послеmake rolling_updateреплики называютсяapi-Nс растущим номером (compose нумерует новые контейнеры сервиса по возрастанию): штатные цели с ними работают,make down+make run_dockerснова даютapi-1,api-2(balancer.md). make instancesи публичные проверки skeleton запускаются системнымpython3(3.9+ на macOS), без uv: драйвер скилла — только stdlib и синтаксис 3.9.- graphify (граф кода, «Где лежат инструкции») — вне проекта, в
uv tool, версия закреплена:- CLI:
uv tool install --python 3.12 'graphifyy==0.9.72'. Без--python 3.12uv берёт free-threaded 3.14t, и установка падает на сборкеtree-sitter-rust. - Сборка и обновление — одна команда
graphify update .в корне: без LLM и токенов, около секунды, работает и в чистом clone. Граф обновляется вручную, после заметной работы (новый слой, закрыт change). Попутноupdateкладёт копию прошлого графа вgraphify-out/<дата>/и называет кластеры по центральному узлу.
- CLI:
| Команда | Что делает |
|---|---|
make check |
офлайн-проверка структуры skeleton, JSON и синтаксиса Python-проверок |
make validate PYTHON=.venv/bin/python |
полная валидация OpenAPI и примеров (валидатор стоит в dev-группе uv) |
make test [BASE_URL=...] |
публичный smoke против запущенного сервера |
make load |
нагрузка из tests/load.py; параметры — tests/README.md |
make test-persistence ACTION_SCRIPT=scripts/restart.sh |
сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (tests/README.md) |
make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
отказ одной API-реплики через LB: 15 с записи параллельно hook, восстановление записи ≤10 с, без дублей (tests/README.md). STOP_MODE=kill — без graceful, STOP_ONE_LOG=<файл> — какой TARGET_INSTANCE_ID и контейнер остановлен. Между прогонами — make replicas |
make run_dev |
make upgrade (Postgres из compose и миграции) и make start_cache, затем APP__RUN_MODE=console uv run python -m src: 127.0.0.1:8080, reload |
make lint |
ruff format + ruff check --fix, дважды: так нужно из-за COM812; tests/ и scripts/ skeleton исключены в [tool.ruff] |
make env_setup |
.env.example → .env со случайными POSTGRES_PASSWORD и VALKEY_PASSWORD, config_example.toml → config.toml; существующие файлы не перезаписывает (новые строки шаблона переносятся руками) |
make run_docker |
make env_setup (только недостающие файлы) + docker compose build + up -d: postgres, valkey → migrate → api × API_REPLICAS (2) → haproxy на 127.0.0.1:APP_OUT_PORT; config.toml, infra/valkey/valkey.conf и infra/haproxy/haproxy.cfg монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — make rolling_update |
make stop / make down |
остановить / удалить контейнеры compose; volume с данными остаётся |
make logs |
журнал всех реплик API, каждая строка — JSON (--no-log-prefix), реплика — поле instance_id |
make replicas [API_REPLICAS=N] |
вернуть остановленные реплики (те же ID) и выставить их число, ждать healthy (balancer.md) |
make instances |
вход одним синтетическим пользователем, 12 × GET /users/me через LB: X-Instance-Id каждого ответа и итог по репликам |
make lb_stats |
слоты HAProxy: адрес, состояние проверки (DRAIN, MAINT при замене), запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB) |
make rolling_update [COMMIT=...] [MIGRATE=0] |
поочерёдная замена реплик без простоя (scripts/rolling-update.sh, balancer.md): сборка из рабочего дерева (или файлов COMMIT через git archive), миграции один раз, затем по одной — новая healthy и UP в LB, старая drain → запросов в полёте 0 → maint → stop → rm → слот ready. Нужен штатный стенд (make replicas) без слотов LB в ручном drain / maint (иначе код 2 и команда set server … state ready); сбой и Ctrl+C — API_REPLICAS готовых реплик, повтор доводит; MIGRATE=0 — откат на прежний образ (после него docker compose up без сборки не запускать: migrate прежнего образа упадёт на новой ревизии) |
make start_db / make stop_db |
Postgres стенда: up -d --wait postgres / stop postgres |
make start_cache / make stop_cache |
Valkey стенда: up -d --wait valkey / stop valkey; volume нет, кэш после рестарта пуст |
make upgrade |
start_db + uv run alembic upgrade head с хоста (127.0.0.1:POSTGRES_OUT_PORT) |
make revision |
upgrade + alembic revision --autogenerate, сообщение спрашивает read -p |
make wipe_data |
down -v — удалить данные стенда (и кэш); только после ввода yes |
make test_isolated [KEEP_TEST_DB=1] |
образ на временной базе test_<db> с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на TEST_APP_PORT, make test + make student_test EXPECT_REPLICAS=1 (тесты реплик пропускаются с причиной), уборка при любом исходе (student-tests.md) |
make student_test [BASE_URL=...] [EXPECT_REPLICAS=...] |
собственные тесты student-tests/ (pytest) против запущенного сервера, кроме проверок отказов (-m 'not fault'); EXPECT_REPLICAS (по умолчанию API_REPLICAS) — сколько реплик за BASE_URL, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом |
make failure_checks [FAULT_ARGS=...] |
проверки отказов (pytest -m fault, ~60 с) на отдельном стенде: проект <рабочий>-failures со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook student-tests/fault_hook.py; после тестов — журнал 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 |
make bench_restore_quick |
то же на 1k / 5k / 10k (~1,5 мин), метка quick-restore-<время>, в git не идёт; сценарий защиты трека 2 |
make bench_failover [FAILOVER_LABEL=...] |
уровень 4, отказ реплик под нагрузкой (~6 мин, метка baseline по умолчанию): стенд mtusi-bench с HAProxy и двумя репликами с лимитами рабочего стенда, k6 — 100 записей с ключом и 100 чтений в секунду; каждая реплика в режимах stop, kill, pause с возвратом. Посекундная шкала, время исключения из LB и восстановления, сверка записей после повтора с тем же ключом, CPU и память каждого компонента по окнам фазы (сэмплер scan, resources.csv, samples.csv; CPU на запрос — только до действия) — evidence/failover/<метка>/. Перед запуском — проверка хоста (bench.md): питание, давление памяти, Swapouts без роста; сумма лимитов на пике больше CPU ВМ — код 2 |
make bench_failover_quick |
то же короче, режимы stop и kill (~2 мин), с ресурсами, метка quick-failover-<время>, в git не идёт |
make bench_rollout [ROLLOUT_LABEL=...] |
уровень 4, поочерёдная замена под нагрузкой (~3 мин, метка baseline по умолчанию): стенд mtusi-bench как у bench_failover, реплики на образе прежнего commit (Profile.rollout_from, git archive), та же нагрузка; посреди неё scripts/rolling-update.sh меняет их на образ текущего checkout. Посекундная шкала с ответами старых и новых реплик, шаги по репликам, контейнеры, образы и ревизия до и после, сверка записей, CPU и память каждой старой и новой реплики, миграции и остальных компонентов по окнам до / подготовка / замена / после (CPU на запрос — до и после) — evidence/rollout/<метка>/. Перед запуском — проверка хоста (bench.md) |
make bench_rollout_quick |
то же с короткими окнами (~2 мин), с ресурсами, метка quick-rollout-<время>, в git не идёт |
make bench_scaling SERIES=a|b|pool|ab|db|db4 [SCALING_LABEL=...] [RESUME=1] |
уровень 5, трек 1: серия на стенде mtusi-bench (метка scaling-<серия> по умолчанию). a — бюджет 4 CPU: 1 × 4, 2 × 2, 4 × 1 (~50 мин); b — 1…6 реплик по 1 CPU (~100 мин); pool — 4 реплики при max_connections 100 и 50 (~35 мин); ab — 1 × 1 и 6 × 1 для «до/после» и A/A (~35 мин); db — 1, 2, 4 реплики при PostgreSQL 0,5 CPU и контроль 4 × 1 при 2 CPU (~50 мин); db4 — только 4 × 1 при 0,5 и 2 CPU (~25 мин, «до/после» scaling-improvement); db_quick — самопроверка серии db (~4 мин, метка quick-*). Ячейка — конфигурация × повтор (3), свежий стенд; открытая модель 70/20/10, фиксированные 250 и 500/с и поиск R* по SLO; сэмплер контейнеров, ВМ, LB и PostgreSQL. RESUME=1 — продолжить прерванную метку на том же commit. Перед запуском — проверка хоста, рабочий стенд — make stop; метку коммитить до следующей серии (bench.md) |
make bench_scaling_quick |
самопроверка серий: 1 × 1 и 2 × 1 при max_connections 50, короткие окна (~4 мин), метка quick-scaling-<время>, в git не идёт |
make bench_plots LABELS="..." [PLOTS=scaling] |
графики SVG и сводка серий трека 1 из меток: R* от числа реплик, p95 от интенсивности, CPU по компонентам, эффективность и точка насыщения — evidence/plots/<PLOTS>/ |
make bench_ab BEFORE=... AFTER=... REAPPLY=<commit> [SERIES=...] |
«до» и «после» одного изменения подряд (два прогона bench): bench для BEFORE, commit доказательств, git revert commit отката REAPPLY, bench для AFTER; с SERIES — серия трека 1 вместо матрицы (make bench_scaling). Нужно чистое рабочее дерево; сама делает два коммита |
make bench_compare BEFORE=... AFTER=... [AA=...] [CHANGE=...] |
дельта двух меток make bench по ячейкам матрицы, у серий трека 1 — по общим конфигурациям (R*, задержки на фиксированных уровнях, CPU на запрос) и таблица PostgreSQL на R* и первой нарушившей ступени (CPU на запрос, новые сессии, соединения); CHANGE — change в шапке сравнения серий (по умолчанию scaling-bench); метки с разной методикой не сравнивает (в том числе метку без LB с меткой стенда на LB и серию с матрицей); с AA (метка того же кода, что BEFORE) отделяет эффект от шума. Результат в evidence/compare/<до>__<после>.md |
Разовая подмена внешнего порта — аргументом make:
make run_docker APP_OUT_PORT=8090, затем
make test BASE_URL=http://localhost:8090. Префикс окружения
(APP_OUT_PORT=8090 make ...) не работает: Makefile подключает .env
(run-modes.md, Troubleshooting).
Карта кода
Файлы домена называются одинаково во всех слоях (user, chat,
message, session, idempotency и т.д.).
src/
__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/
routers/health.py # /health/live, /health/ready: вне версии, без идентификации
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py)
schemas/<domain>.py # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12
dependencies.py # сессия БД, фабрики сервисов (с кэшем), разбор Basic, текущая сессия по Bearer, пагинация
errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; у 500 — X-Request-Id и X-Instance-Id
middlewares/ # X-Request-Id, X-Instance-Id и access-лог
core/
repos/<domain>.py # атомарный доступ к хранилищу, модульные функции
repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата
repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ и сообщение одной транзакцией
exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py
infra/
early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped API before startup» и выход 0; disarm() — первая строка lifespan
logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи
password.py # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username
db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping
db/session.py # глобалы engine и session_factory процесса API
db/errors.py # is_db_unavailable: какие ошибки драйвера — 503
db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit
cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск
cache/instance.py # глобал cache процесса API
schemas/
dataclasses/<domain>.py # DTO между repo → service → api
enums/<domain>.py # StrEnum доменов, RunModeEnum
utils/
constants.py # лимиты контракта, размер страницы, префиксы путей
utc.py # utcnow() (aware UTC), формат RFC 3339 с Z
cursor.py # непрозрачный keyset-курсор: кодирование и разбор; поля проверяются по отдельности, незнакомые игнорируются, смена формата — новая CURSOR_VERSION
student-tests/ # black-box тесты по HTTP (уровень 4): make student_test
conftest.py # BASE_URL, EXPECT_REPLICAS и фикстура replicas (пропуск против одного процесса), проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook
api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message — с Idempotency-Key
contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, X-Instance-Id, assert_error, assert_errors (статусы всех вариантов запроса разом), assert_replicas
test_idempotency.py # спек idempotency: ключ, повтор, 409, область, порядок кодов, повтор через другую реплику (гонка — test_race.py, отказы — test_failures.py)
test_load_balancing.py # спек load-balancing (вне сверки покрытия): одна сессия на разных репликах, запись видна через другую реплику
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия; missing_evidence — файл evidence по ссылке исключения должен быть в репозитории
test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4
test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
test_failures.py # проверки отказов (маркер fault): только make failure_checks
run_isolated.py # make test_isolated: образ на временной базе test_<db> (stdlib)
run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, журнал 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 (не добавляет сессий в базу приложения), 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 (события цели — поток 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
resources.py # ресурсы профилей failover и rollout без docker: интервалы контейнеров (сброс при новой cgroup, заморозка, новые контейнеры с момента запуска), окна, CPU / троттлинг / память по компонентам и ВМ, CPU на запрос в установившихся окнах, resources.csv / samples.csv, разделы summary.md; --selftest
failover.py # профиль failover без docker: строки k6 о запросах, статистика и журнал HAProxy, события Docker, посекундная шкала, величины фазы, summary.md
rollout.py # профиль rollout без docker: строки скрипта замены, события контейнеров проекта, состояния слотов LB (UP, drain, maint, ready), шаги по репликам, шкала со старыми и новыми ответами, окна до / во время / после, summary.md
bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain
bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей)
k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы
compare.py # make bench_compare: дельта двух меток (ячейки матрицы или общие конфигурации серий), уровень шума, эффект или шум; отказ при разной методике, в том числе метке без LB и серии против матрицы
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд, с --series — серии трека 1
migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose
infra/ # конфигурации сервисов стенда; README.md — skeleton
valkey/valkey.conf # лимит памяти и LRU, persistence выключен
haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене)
scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey
scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG
scripts/rolling-update.sh # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/
Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck
docker-compose.yml # проект mtusi-lab3: postgres, valkey, migrate, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volume postgres_data, лимиты у всех, окружение по сервисам
.dockerignore
config_example.toml, .env.example
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции
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, консоль, сверка ссылок исключений, регрессия; strict-id-validation-checks.md — красный и зелёный прогоны курсора и UUID на входе, пересмотр проверки курсора, замена реплик, клон во временном проекте
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, зависшая реплика и ключ; 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 (посекундно от начала замены)
evidence/bench/<метка>/ # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6
evidence/bench/scaling-*/ # серии трека 1 (a, b, pool, A/A scaling-aa, db — насыщение PostgreSQL; db4 — «до/после» пула без переполнения: scaling-db-aa*, -before*, -nooverflow*, окончательные — с суффиксом 2): паспорт с планом, бюджетом и лимитами по конфигурациям, runs.csv (строка на ступень), searches.csv (строка на ячейку), samples.csv (посекундно в окнах), summary.md, p95-by-rate.svg, cpu-by-component.svg, итоги k6 ступеней и журналы 5xx
evidence/plots/scaling/ # make bench_plots по сериям a и b: графики SVG и summary.md (R*, эффективность, точка насыщения, цена запроса, память)
evidence/plots/scaling-db/ # make bench_plots по серии db: R* по лимитам PostgreSQL и раздел «Насыщение PostgreSQL»
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
evidence/ перенесён без содержимого лабы 2 (оно осталось в
репозитории mtusi2026lab2-safronov). Каталоги выше появляются заново
по мере changes.
Архитектура в двух словах
- Поток однонаправленный. Роутер (зависимости, модели API) → сервис
(логика, проверки доступа, id и время, логи) → repo (одна атомарная
операция над хранилищем, отдаёт DTO) → PostgreSQL через
AsyncSession(src/infra/db/). Подробности — в правилах слоёв. - Отличия от bp_proxies. Из
core/вынесены инфраструктура (src/infra/: логгер, хранилища, клиенты), утилиты (src/utils/), настройки (src/config/вместоsrc/data/) и HTTP-модели (src/api/schemas/вместоschemas/pydantic/). Вcore/остались доменные слои: repos, services, exceptions. Бота, loader и контроллера нет; фоновая работа появится в лабе 5 отдельным worker. - Ошибки: сервис бросает доменное исключение.
src/api/errors.pyодной таблицей переводит его в статус иcodeи отдаёт тело{"error": {...}}сrequest_id.HTTPExceptionв сервисах и ручках не используется. - Конкурентность: все ручки и зависимости —
async def, один event loop, один worker в процессе, процессов —API_REPLICASза HAProxy. Атомарность и защиту от гонок, в том числе между репликами, дают транзакции и ограничения Postgres (уникальность,ON CONFLICT), транзакцией управляет сервис. ПовторPOSTсообщения через другую реплику находит тот же ключ идемпотентности в Postgres. На лабе 1 ту же роль играло отсутствиеawaitвнутри repo-функции надMemoryStore. KDF пароля — в потоке, чтобы не останавливать event loop. - Request id генерирует middleware. Тот же id уходит в заголовок
X-Request-Id, вrequest_idтела ошибки и в каждую строку лога.
Соглашения по коду
- ruff: 79 символов, py312, набор правил в
pyproject.toml(isort, bugbear, comprehensions, unused-arguments, pyupgrade, simplify, quotes). Кавычки как в файле (quote-style preserve), trailing comma обязательна. - Типизация везде:
X | None,list[...],UUIDиdatetimeвместо строк. Методы сервисов keyword-only (*,); repo и сервисы вызываются только именованными аргументами. - Комментарии и докстринги короткие, на русском. Сообщения логов и
тексты ошибок API (
error.message) — на английском. - Константы (лимиты контракта, размер страницы, пути) — в
src/utils/constants.py, не литералами в коде. - Время только через
utcnow()изsrc/utils/utc.py: aware UTC. В bp_proxies был naive UTC, здесь контракт требует...Z, а с лабы 2 —timestamptz. - Коммиты (когда попросят): английский, conventional style
(
feat: ...,fix: ...,refactor: ...).
Дорожная карта лаб
Каждая лаба — отдельный skeleton-репозиторий; переходы API — COURSE.md
нового skeleton. Что меняется в коде:
| Лаба | Что появляется | Где в коде |
|---|---|---|
| 1 | in-memory API, Dockerfile | infra/memory.py, X-User-Id в get_current_user |
| 2 | PostgreSQL, Basic → Bearer-сессия; Valkey на «4» | infra/db/, migrations/, repo на AsyncSession; password при регистрации (KDF); get_current_user на Bearer; SESSION_TTL_SECONDS; кэш карточки чата — infra/cache/, repos/chat_cache.py |
| 3 | балансировщик, ≥2 реплики, идемпотентность | middleware X-Instance-Id; Idempotency-Key на POST сообщения; никакого состояния в памяти процесса |
| 4 | приватный S3, вложения | клиент в infra/, домен attachment |
| 5 | брокер, worker, превью | отдельная точка входа worker; загрузка отвечает 202 |
| 6 | OTel Collector, Grafana | телеметрия в infra/ |
| 7 | Argon2id, TLS/mTLS, OpenBao | HTTPS, секреты из OpenBao |
Переход в следующую лабу
По CONTRIBUTING.md: fork нового skeleton, ветка
solution/<group>-<surname>, затем перенести своё.
- Переносить:
src/,student-tests/,migrations/,alembic.ini,Dockerfile,docker-compose.yml,infra/valkey/,infra/haproxy/(безinfra/README.mdskeleton), своиscripts/restart.sh,scripts/stop-one.shиscripts/rolling-update.sh(без примеров и проверок skeleton вscripts/),pyproject.toml,uv.lock,.python-version,config_example.toml,AGENTS.md,CLAUDE.md,.claude/,openspec/,.graphifyignore,bench/,KNOWN_ISSUES.md. - Сливать, а не копировать поверх:
Makefile,.env.example,.gitignore,.dockerignore. Берём версию нового skeleton (в ней новые цели и проверки) и дописываем свои секции. - Не копировать:
.git,.env,config.toml, volumes,README.md,COURSE.md,tests/,contracts/,lab.json,REPORT.md,evidence/(доказательства остаются в репозитории своей лабы),graphify-out/(граф собирается заново). - Доказательства исключений сверки покрытия снять заново на стенде новой
лабы, иначе
make student_testкрасный (test_exclusion_evidence_existsназывает сценарий и путь):make test_isolated, затемdriver.py --port <LB> cache-check --require-test-keys→evidence/cache/hits.md;driver.py --port <LB> auth-storage→evidence/auth/passwords-and-tokens.md;make test-persistence ACTION_SCRIPT=scripts/restart.sh→evidence/replicas/test-persistence.md(или путь, который назовёт исключение); повтор отправки с ключом послеdocker compose up -d --force-recreate api→evidence/idempotency/replay-after-restart.md(student-tests.md). Файлыevidence/лабы 3 в новую лабу не копировать, даже эти четыре: сверка проверяет только наличие файла и с копией останется зелёной без пересъёмки. - Сначала прочитать переходы API в
COURSE.mdиcontracts/README.mdнового skeleton, потом править код. Обновить этот файл: номер лабы, таблицу важных файлов, новые правила.
Ветки и PR
Git — только по просьбе. Когда просят, порядок такой:
- Работа идёт в ветке
solution/bvt2301-safronovот ветки skeleton. - PR — в исходный репозиторий преподавателя. Заголовок
ЛР N — Группа — Фамилия — на 3/4/5, тело — по.github/pull_request_template.md. Перед PR выполнитьmake check,make testна собранном из чистого clone образе и заполнитьREPORT.md, включая использование ИИ.