Files
mtusi2026lab4/AGENTS.md
T
2026-10-23 20:28:49 +03:00

112 KiB
Raw Blame History

MTUSI Messenger

REST API мессенджера (пользователи, чаты, история сообщений). Этот код переносится через все семь лабораторных курса и на каждой обрастает инфраструктурой. Текущая работа — лаба 4 (lab.json): приватное S3-совместимое хранилище и вложения-изображения в сообщениях: метаданные — в PostgreSQL, байты — в приватном bucket, загрузка отвечает 201 со status=ready (README.md, COURSE.md, contracts/README.md, раздел «Вложения (с lab4)»). Код перенесён из лабы 3 (репозиторий mtusi2026lab3-safronov, ветка solution/bvt2301-safronov, commit ce89eba) по разделу «Переход в следующую лабу». S3 в стенде — change s3-storage (заархивирован 2026-10-20, openspec/changes/archive/2026-10-20-s3-storage/): SeaweedFS с приватным bucket, bootstrap и клиент src/infra/s3/. Вложения — change attachments (заархивирован 2026-10-21, openspec/changes/archive/2026-10-21-attachments/): ручки загрузки, метаданных и скачивания, структурная проверка PNG/JPEG, attachment_ids в сообщениях, таблицы attachments и message_attachments. Согласованность БД и S3 — change upload-consistency (заархивирован 2026-10-21, openspec/changes/archive/2026-10-21-upload-consistency/): компенсация в загрузке (удаление объекта при известном исходе, 503 вместо 500), уборщик незавершённых загрузок — сервис cleaner (python -m src.cleaner, grace 900 с, свой пользователь S3 «чтение и удаление»), частичный индекс строк pending, новая capability storage-consistency. Память и сроки загрузки — change upload-memory (заархивирован 2026-10-22, openspec/changes/archive/2026-10-22-upload-memory/): места загрузки на процесс API ([uploads]: 4 места, очередь 16, ожидание 5 с, затем 429 rate_limited с Retry-After), срок тела 30 с (400), одна копия тела при PUT, буферы сокетов реплики 512 KiB и LB 256 / 128 KiB, timeout server LB пути загрузки 30 с, дренаж замены 90 с, профиль uploads стенда bench/. Сверка bucket и БД (трек 2) — change track2-reconciler (заархивирован 2026-10-22, openspec/changes/archive/2026-10-22-track2-reconciler/): сверка в процессе уборщика (make reconcile [APPLY=1] и плановая), классы расхождений, пометка потерянного оригинала lost_at, список по префиксу у ключа уборщика. Изредка 503 на загрузке — change fix-upload-put-flake (заархивирован 2026-10-23, openspec/changes/archive/2026-10-23-fix-upload-put-flake/): у клиента S3 нет срока чтения aiohttp (он переживал ответ и портил соединение в пуле), срок — только asyncio.timeout вызова и блока; четвёртый API стенда отказов со сроком S3 1 с (test_upload_after_idle_s3), проба driver.py s3-idle. Стоимость сверки (трек 2) — change track2-reconcile-cost (заархивирован 2026-10-23, openspec/changes/archive/2026-10-23-track2-reconcile-cost/): стратегия «HEAD на строку» и глубокая сверка (класс «другой SHA-256», пометку снимает только тот же SHA-256) в разовом проходе, предел скорости [reconciler] max_objects_per_second (2000 объектов S3/с), отказ по пределу без лишних перепроверок, стоимость прохода в его итоге, профиль reconcile стенда bench/. План работ, решения и трек «5» — PLAN.md. Из лабы 2: PostgreSQL как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш карточек чатов. Из лабы 3: HAProxy перед ≥2 репликами API (replicas-lb), X-Instance-Id и обязательный Idempotency-Key (instance-id-idempotency), замеренная цепочка таймаутов (graceful-failover), поочерёдная замена реплик make rolling_update (rolling-update), ранний обработчик SIGTERM (fix-known-issues), строгие курсор и UUID на входе (strict-id-validation). Стенд bench/ — трек 2 лабы 2 (план запроса и восстановление), профили failover и rollout, серии трека 1 лабы 3 (scaling-bench, scaling-improvement, profile-resources). Changes лаб 2 и 3 и s3-storage, attachments, upload-consistency, upload-memory, track2-reconciler, fix-upload-put-flake, track2-reconcile-cost лабы 4 — в openspec/changes/archive/, активных changes нет, спеки синхронизированы (новые capability: с s3-storage — object-storage, с attachments — attachments, с upload-consistency — storage-consistency); в KNOWN_ISSUES.md четыре открытые записи (bootstrap после удаления bucket; уборщик удаляет объект зависшей загрузки по ключу вне своего префикса; 408 LB на медленные заголовки текстом HAProxy; поля float настроек принимают inf). Отчёт, evidence и рабочий план лабы 3 остались в её репозитории (REPORT.md, evidence/, git show 063eedb:PLAN.md). Стек: Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore (клиент S3).

Репозиторий — 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 и 4.

  • Лаба 3: ≥2 взаимозаменяемые реплики api за HAProxy — единственной публичной точкой входа; порты реплик наружу не публикуются, sticky session нет. В памяти процесса нет ничего, от чего зависит корректность: сессии, данные и ключи идемпотентности — в Postgres, Valkey — общий кэш неизменяемых карточек, S3 — байты вложений. В каждом ответе API — X-Instance-Id. POST сообщения требует Idempotency-Key; ключ и сообщение пишутся в одной транзакции (api-contract.md, service-layer.md). Миграции — однократно, отдельным сервисом, не репликами, и только расширяют схему: старые реплики работают на новой (migrations.md). Новый код доходит до реплик без простоя через make rolling_update. Стенд и отказы — balancer.md. В каждом процессе uvicorn по-прежнему один worker: масштабирование — числом реплик. Всё это сохраняется в лабе 4.

  • Лаба 4, S3 (change s3-storage): SeaweedFS в стенде, образ закреплён тегом и digest, volume s3_data. Bucket приватен с первой секунды: административная пара — только у сервера, служебные серверы — на loopback контейнера, gRPC шлюза закрыт ключом подписи. Bucket, политику и пользователя API создаёт одноразовый s3-bootstrap (идемпотентно, сам проверяет приватность), реплики ждут его, как миграций. У API — только ключи своего пользователя (чтение, запись, удаление объектов своего bucket). Срок вызова клиента S3 — только asyncio.timeout вызова и блока, read_timeout aiohttp выключен (change fix-upload-put-flake, infra.md). /health/ready S3 не проверяет. Приватность вне API — make s3_check (docker.md, infra.md, design change s3-storage).

  • Лаба 4, согласованность БД и S3 (change upload-consistency): строка pending с ключом — до PUT; после записанного объекта сбой до отправки COMMIT ready — объект удаляется до ответа 503, исход COMMIT неизвестен — объект не трогается (service-layer.md). Незавершённые загрузки убирает только уборщик — отдельный сервис cleaner на образе API, а не реплики: строки pending старше [cleaner] pending_grace_seconds (900 с; больше границы живой загрузки 17 с, иначе уборщик не стартует) под FOR UPDATE SKIP LOCKED, в два шага: пометка строки (updated_at) отдельной транзакцией, затем объект и строка одной транзакцией под блокировкой (объект раньше строки); помеченную строку mark_ready в ready не переводит, ready уборщик не трогает. У уборщика свой пользователь S3 — только чтение и удаление объектов своего bucket, ключи S3_CLEANER_* только у него и bootstrap (docker.md, settings.md).

  • Лаба 4, сверка bucket и БД (change track2-reconciler, трек 2): её делает процесс уборщика — разовая make reconcile [APPLY=1] (по умолчанию dry-run; коды 0 / 3 / 1 / 2) и плановая в сервисе cleaner при старте и раз в [reconciler] interval_seconds (3600 с) с исправлением. Удаляется только объект без строки старше grace и зависшая загрузка (шагом уборщика); строки ready, объект, на который ссылается строка, и чужой ключ — никогда; строку с ключом вне <база>/attachments/ сверка только называет (чужой объект): её объект не читает, строку не помечает и не убирает. Сигнал — перед каждым вызовом хранилища (остановка ждёт ≤ 5 с S3 или ≤ 6 с шага БД). Grace — тот же [cleaner] pending_grace_seconds, по LastModified объекта и времени строки; перед каждым действием — перепроверка в БД и HEAD, отсутствие объекта — только при живом bucket; больше [reconciler] max_changes (100) изменений — ни одного и код 3. Потерянный оригинал помечается (attachments.lost_at): скачивание — 404, метаданные — 200, ссылка — 201 (вопрос преподавателю, PLAN.md). Уборщику разрешён список только с префиксом <база>/attachments/ (S3_CLEANER_LIST_PREFIX у bootstrap). На время восстановления базы уборщик останавливают (docker.md). С change track2-reconcile-cost: проход затрагивает в среднем не больше [reconciler] max_objects_per_second (2000; 0 — без предела) объектов S3 в секунду, паузу прерывает сигнал; разовый проход — ещё --strategy head (выборка строки на объект, HEAD на строку, без множества ключей) и --deep (GET и SHA-256: «другой SHA-256» помечается потерянным), плановая — всегда batch, поверхностная; «оригинал вернулся» — только тот же SHA-256; с --apply, как только подтверждённых изменений больше предела, остальные кандидаты не перепроверяются (unchecked); итог называет стоимость — объекты и запросы S3, байты, сеансы, длительность шагов (service-layer.md).

  • Лаба 4, память загрузок (change upload-memory): память загрузок реплики ограничена числом мест, а не числом клиентов. Место берётся после проверок 401/400/404/415/413 и до чтения тела, держится до ответа и освобождается при любом исходе; без места — очередь процесса до [uploads] max_waiting не дольше wait_timeout_seconds, затем 429 с Retry-After без строки и объекта. Тело — не дольше body_timeout_seconds с момента места (иначе 400), в PUT уходит тот же BytesIO без второй копии (service-layer.md). Ожидание, тело и проверка — до строки pending: граница B уборщика прежняя (17 с). Буфер приёма сокетов api — 512 KiB (sysctls), буфер отправки LB к реплике — 256 KiB, буфер приёма LB от клиента — 128 KiB; timeout server пути загрузки 30 с, остальных — 10 с; ROLLOUT_DRAIN_TIMEOUT 90 с (balancer.md, docker.md).

  • .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
2026-10-20 Лаба 4: «пустой текст» сообщения — это и "", и текст только из пробельных символов. Допустимы: вложение + непустой текст, без вложения + непустой текст, вложение + пустой текст. Значит, " " с хотя бы одним вложением — 201, без вложений — 400 спек messages (change attachments, сценарий «Пробелы с вложением»), design attachments, решение 8; .claude/rules/api-contract.md

Задание и контракт: важные файлы

Файл Что в нём
README.md задание лабы: рубрика 3/4/5, сценарий и вопросы защиты, что приложить к PR
PLAN.md наш план лабы 4 на «5»: рубрика → change, ключевые решения (S3-сервер, порядок записи, память), трек 2, порядок changes, риски; удаляется, когда все changes закрыты
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 — вложения: сырые bytes PNG/JPEG ≤10 MiB и ≤40 млн пикселей, 201 Attachment (ready), attachment_ids в сообщении, download только участникам; пустой текст (в том числе из пробелов) — только с вложением (согласование 2026-10-20); разделы lab5+ — на будущее; как это сделано — api-contract.md, «Вложения (лаба 4)»
contracts/examples.json, infrastructure.json примеры тел (проверяет make validate); роли инфраструктуры лабы: api ×2+ без локального состояния, postgres, load_balancer, s3 (одно из MinIO, SeaweedFS, RustFS; приватный bucket, persistent volume); Redis/Valkey — необязательно; внутренние порты реплик в обход LB не публикуются
lab.json номер лабы (4); по нему tests/client.py выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer; с лабы 3 — идемпотентность; с лабы 4 — вложение, 201 вместо 202 с лабы 5)
tests/smoke.py, tests/client.py публичный сквозной сценарий make test; с лабы 4 — загрузка tests/fixtures/sample.png, сообщение с attachment_ids, SHA-256 скачанного оригинала, 404 постороннему; что он проверяет и чего нет — tests/README.md
tests/fixtures/, tests/image_probe.py синтетический PNG 320×200 и его SHA-256 (tests/fixtures/README.md); размеры JPEG без внешних библиотек (thumbnail — с лабы 5)
tests/resilience.py make test-persistence: данные, прежний токен и с лабы 4 — тот же оригинал вложения после 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 и новые lab4 S3_*, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS) перечислены в шапке, их соответствие — в REPORT.md (settings.md)
examples/requests.http ручные запросы для HTTP-клиента IDE

Где лежат инструкции

Четыре уровня, не дублировать их друг в друге:

  • AGENTS.md (этот файл): инварианты, команды, карта кода. CLAUDE.md импортирует его.

  • .claude/rules/*.md: правила по слоям. Подгружаются автоматически, когда открыт файл из paths: во фронтматтере. Проект пишется с нуля, а при создании файла через Write правило само не подгрузится. Поэтому перед созданием первого файла слоя его правило нужно прочитать руками.

    Файл Действует на
    api-contract.md src/api/**, src/core/**, src/schemas/**, student-tests/**: что требует контракт и где FastAPI по умолчанию его нарушает
    api-layer.md src/api/**, src/main.py: роутеры, зависимости, middlewares, обработчики ошибок
    service-layer.md src/core/services/**
    repo-layer.md src/core/repos/**
    dto.md src/schemas/**
    infra.md src/infra/**: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе), клиент S3 (без повторов, срок на вызов, перевод ошибок) и другие клиенты
    auth.md src/**/session.py, сервис пользователей, dependencies.py, errors.py, идентификация в student-tests/: пароль и KDF, разбор Basic, токен, срок и отзыв сессии
    logging.md сервисы, API, инфраструктура, src/main.py: где и как логировать, чего в логах быть не должно
    settings.md src/config/**, .env.example, config_example.toml: источники настроек, что куда класть
    run-modes.md точки входа, Makefile, compose, шаблоны конфигов: console и docker, uvicorn, SIGTERM
    docker.md Dockerfile, docker-compose.yml, .dockerignore, scripts/restart.sh, infra/**: мультистейдж, non-root, пины, healthcheck, стенд compose, S3 и bootstrap, секреты по сервисам, volumes, restart hook
    balancer.md docker-compose.yml, infra/haproxy/**, scripts/stop-one.sh, scripts/rolling-update.sh: реплики за HAProxy, проверки и цепочка таймаутов, повторы LB, failover hook, поочерёдная замена, лимиты и пулы (с лабы 3)
    student-tests.md student-tests/**: обязательные проверки уровня 4, black-box по HTTP, особый стенд
    bench.md bench/**: нагрузочный стенд на Postgres (проект compose mtusi-bench), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний
    migrations.md migrations/**, 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, остальные пересобирают граф без спроса.

Окружение и команды

  • Python 3.12 (.python-version), зависимости через uv (uv sync, uv run ...), lock в uv.lock. ruff глобальный (/opt/homebrew/bin/ruff, им же пользуется PyCharm), в проекте он в extra dev.
  • Конфиг: .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-lab4 со своей базой. После 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.12 uv берёт free-threaded 3.14t, и установка падает на сборке tree-sitter-rust.
    • Сборка и обновление — одна команда graphify update . в корне: без LLM и токенов, около секунды, работает и в чистом clone. Граф обновляется вручную, после заметной работы (новый слой, закрыт change). Попутно update кладёт копию прошлого графа в graphify-out/<дата>/ и называет кластеры по центральному узлу.
Команда Что делает
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 и make start_s3, затем 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 и шестью секретами S3, config_example.toml → config.toml; существующие файлы не перезаписывает, но в существующий .env дописывает переменные шаблона, которых в нём нет (секреты — случайными, прежние строки не меняются); печатает только имена
make run_docker make env_setup (недостающие файлы и переменные) + docker compose build + up -d: postgres, valkey, s3 → migrate, s3-bootstrap → api × API_REPLICAS (2) и cleaner → haproxy на 127.0.0.1:APP_OUT_PORT; config.toml, infra/valkey/valkey.conf, infra/haproxy/haproxy.cfg и infra/s3/bootstrap.sh монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — make rolling_update
make stop / make down остановить / удалить контейнеры compose; volumes с данными остаются; S3 останавливается плавно ~15 с
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 каждого ответа и итог по репликам
driver.py upload / download загрузка файла и скачивание оригинала с SHA-256 на любом сервере (.claude/skills/run-mtusi-messenger/SKILL.md)
driver.py --port <LB> attachment-failover [--mode stop|kill] вложение через LB, stop-one.sh принявшей реплики, скачивание через другую (тот же SHA-256), 404 постороннему, затем make replicas; доказательство исключения attachments «Принявшая реплика остановлена»
driver.py --port <LB> attachment-storage схема таблиц вложений, вид object_key, объект в bucket, анонимный GET — 403, docker diff реплик; доказательство исключения «Байты не в БД и не на диске API»
driver.py --port <LB> upload-consistency согласованность БД и S3 на рабочем стенде (~45 с): загрузка при pause S3 и со сбоем фиксации ready (триггер на filename прогона) — 503, строки pending не видны, компенсация удалила объект; cleaner --once с grace 30 с убирает обе, объектов без строки нет, готовое вложение цело; evidence/attachments/consistency.md
driver.py lb-upload-timeouts [--config F] сроки LB пути загрузки без стенда (~35 с): haproxy -c, временная сеть, HAProxy закреплённого образа с F (по умолчанию infra/haproxy/haproxy.cfg) и заглушка реплики api на образе API; молчание 12 с до и после тела загрузки — 201, 12 с на другом пути — 504 через ~10 с, 32 с на пути загрузки — 504 через ~30 с, клиент молчит посреди тела — 400 в формате контракта; уборка при любом исходе, код 1 при расхождении; evidence/uploads/lb-timeouts.md
driver.py --port <LB> s3-idle [--rounds 3] клиент S3 после простоя (~40 с, change fix-upload-put-flake): проба в реплике стенда (docker exec -i … python -, код и ключи образа), варианты «образ» и «эталон» с прежним read_timeout aiohttp; раунд — 10 одновременных медленных скачиваний 4 MiB, простой срока вызова + 0,5 с, 12 PUT; взведённые и испорченные соединения пула, PUT прошло и упало (цепочка ошибки, мс), чтение обратно; объекты под <база>/.s3-idle-probe/ удаляются в finally; код 0 — у образа ни порчи, ни упавших PUT, 1 — иначе, 2 — нет стенда; evidence/s3/idle-connection.md
make reconcile [APPLY=1] [MAX_CHANGES=N] [STRATEGY=head] [DEEP=1] [RATE=R] разовая сверка bucket и БД в контейнере уборщика (docker compose run --rm --no-deps cleaner reconcile [--apply] [--max-changes N] [--strategy batch|head] [--deep] [--max-objects-per-second R]): по умолчанию dry-run — записи «Found storage discrepancy» по классам и итог со стоимостью прохода; APPLY=1 — исправить; STRATEGY=head — HEAD на строку, DEEP=1 — SHA-256 содержимого, RATE — предел скорости (0 — без него); 0 — расхождений нет, 3 — остались (чужие объекты, отказ по пределу), 1 — прервана, 2 — конфигурация
driver.py --port <LB> reconcile-cycle сверка на рабочем стенде (~2 мин): исходный dry-run без расхождений (иначе код 2), расхождения с обеих сторон, dry-run без изменений, 500 → --apply → 404 и 200, повтор, удаление чужого объекта, свежий объект после grace, возврат оригинала; evidence/reconcile/cycle.md
driver.py --port <LB> reconcile-stress [--seconds S] [--clients N] --apply раз в ~3 с под загрузками и отправками N клиентов S секунд (4 × 40 с): внесённое исправлено, каждое 201 скачивается с тем же SHA-256, повтор — 0; evidence/reconcile/stress.md
driver.py reconcile-signal [--pace [--apply]] только не рабочий проект compose (COMPOSE_PROJECT_NAME и др., mtusi-lab4 — код 2): pause s3, разовый reconcile --apply отдельным контейнером, docker stop через секунду после «Started cleaner» — код 1, interrupted_by: stop, «Stopped cleaner» с exit_code 1, быстрее 10 с; unpause в finally. --pace (change track2-reconcile-cost) — вместо pause s3 объекты пробы мимо API и reconcile --max-objects-per-second 1, docker stop через 2 с во время паузы предела скорости — остановка ≤ 1 с, listed_objects — ключи страницы; --pace --apply (verify W1) — объекты пробы без строки, grace 18 с, reconcile --apply, docker stop посреди удалений: записей «Fixed» и fixed столько же, сколько удалено; объекты удаляются в finally; evidence/reconcile/service.md
make bench_reconcile [RECONCILE_LABEL=...] трек 2, стоимость сверки (~50 мин, метка baseline; change track2-reconcile-cost): стенд mtusi-bench с LB, двумя репликами, PostgreSQL, Valkey и S3 с лимитами рабочего стенда, порт метрик шлюза S3 на loopback; наполнение мимо API (\copy метаданных, PUT объектов загрузчиком bench/fill_objects.py), 1 000 × 1 MiB и 10k → 30k → 100k × 4 KiB с 0,25 % расхождений каждого класса; разовые проходы уборщика (0,25 CPU / 256 МБ, управляемый опыт — 1 CPU): batch, head, глубокая, фоновая нагрузка с пределом скорости и без, отказ по пределу на образе Profile.reconcile_before (7f4e626) и checkout; 3 повтора, найденное сверяется с моделью (иначе отказ), счёт сверки — с метриками шлюза; evidence/reconcile/<метка>/ (passes.csv, windows.csv, summary.md с H1–H4 и S4, SVG). Перед запуском — проверка хоста (bench.md), рабочий стенд — make stop
make bench_reconcile_quick то же на 2 000 × 4 KiB, по одному проходу каждого вида, окна 5 с, S4 с 300 кандидатами (~4 мин: 3,7 мин на шумном хосте), метка quick-reconcile-<время>, в git не идёт
docker compose run --rm --no-deps cleaner --once разовый проход уборщика незавершённых загрузок (grace — [cleaner] или -e CLEANER__PENDING_GRACE_SECONDS=…, не меньше 18 с): 0 — проход дошёл до конца, 1 — прерван отказом, 2 — неверная конфигурация; журнал сервиса — docker compose logs --no-log-prefix cleaner
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 start_s3 / make stop_s3 S3 стенда: up -d --wait s3, затем up --no-deps --exit-code-from s3-bootstrap s3-bootstrap (код bootstrap — код цели: --wait одноразовый сервис не ждёт) / stop s3
make s3_check приватность bucket вне API на запущенном стенде (driver.py s3-check): bootstrap в режиме check (права ключей API и уборщика, чужой временный bucket, административные запросы), анонимные запросы с хоста и из сети стенда, порты контейнера S3 из сети, затем cleanup; таблица «где → проверка → ожидаемо → получено», код 1 при нарушении
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 — удалить данные стенда (volumes Postgres и S3 называются в запросе) и кэш; только после ввода yes
make test_isolated [KEEP_TEST_DB=1] образ на временной базе test_<db> с Valkey и S3 стенда (ключи кэша и объектов разделены именем базы): сборка, миграции, отдельный контейнер API на TEST_APP_PORT, make test + make student_test EXPECT_REPLICAS=1 (тесты реплик пропускаются с причиной), уборка при любом исходе — база и объекты под префиксом test_<db>/ (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, 56 проверок, ~15 мин) на отдельном стенде: проект <рабочий>-failures со своими Postgres, Valkey и S3 (с bootstrap), уборщик (grace 20 с, интервал 1 с), четыре API — обычный, «тесный» (срок 2 с, пул 1), «узкий по загрузкам» и «с коротким сроком S3» (1 с), hook student-tests/fault_hook.py; после тестов — журнал PostgreSQL стенда: сводка (crash markers, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volumes удаляются при любом исходе, рабочий не трогается (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; сейчас e1161f7 — последний до change attachments, правило выбора — bench.md; commit вне истории — код 2 до стенда, отладка --from), та же нагрузка; посреди неё 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_uploads [UPLOADS_LABEL=...] уровень 4, память при одновременных загрузках (~50 мин, метка baseline по умолчанию; change upload-memory): стенд mtusi-bench с LB, одной репликой 1 CPU / 512 МБ без swap, PostgreSQL, Valkey и S3 рабочего стенда; варианты «до» (Profile.uploads_before — f894040, git archive; commit вне истории — код 2), «без лимита» (1000 мест, без очереди) и «с лимитом» (по умолчанию) × тела PNG ~1 и ~10 MiB × 1 / 10 / 20 / 40 клиентов × 3 повтора, на прогон — новые реплика и volume S3; пик memory.peak окна со сбросом (сэмплер peak), anon, sock, OOM, ответы по кодам, загрузок/с, p50/p95/p99, пики S3 и LB, H1–H4 в сводке — evidence/uploads/<метка>/. Перед запуском — проверка хоста (bench.md), рабочий стенд — make stop, гипотезы закоммичены раньше
make bench_uploads_quick то же короче (~4,5 мин): «без лимита» и «с лимитом», 10 MiB, 1 / 10 / 40 клиентов, один повтор, метка quick-uploads-<время>, в 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
  cleaner/__main__.py        # python -m src.cleaner [--once]: early_stop.install("cleaner") до импорта → main(); неверные настройки — запись без значений и код 2
  cleaner/main.py            # уборщик незавершённых загрузок: проверка grace > 2 × request_timeout + s3 timeout (иначе код 2), свой engine и клиент S3, цикл с интервалом и плановой сверкой (при старте и раз в [reconciler] interval_seconds), SIGTERM — довести текущий шаг и выйти 0, --once — коды 0/1/2; reconcile [--apply] [--max-changes N] [--strategy batch|head] [--deep] [--max-objects-per-second R] — разовая сверка, коды 0/3/1/2; плановая — batch, поверхностная, предел скорости из настроек
  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, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds, [uploads] max_concurrent 4, max_waiting 16, wait_timeout_seconds 5, body_timeout_seconds 30 (места загрузок процесса API), [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100, [reconciler] interval_seconds 3600, page_size 1000, max_changes 100, max_objects_per_second 2000 (предел скорости сверки; 0 — без него)
  api/
    routers/health.py        # /health/live, /health/ready: вне версии, без идентификации
    routers/v1/<domain>.py   # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra, строгий UTF-8 filename по scope["query_string"]), метаданные, байты StreamingResponse
    schemas/<domain>.py      # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12; attachment.py — DisplayFilename (отказ на / \ Cc и пробелы) и Attachment; message.py — CreateMessage с attachment_ids и валидатором пустого текста
    dependencies.py          # db_session_scope (сессия на шаг — session_scope с фабрикой API) и get_db_session поверх него, фабрики сервисов (с кэшем; вложения — без сессии запроса), разбор Basic, текущая сессия по Bearer, CurrentUserBrief (вход с короткой сессией), пагинация
    errors.py                # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; RETRY_AFTER — Retry-After у 429 занятых мест загрузки; у 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
    repos/attachment.py      # строки вложений: вставка pending (created_at = updated_at), mark_ready (pending и непомеченная → ready RETURNING), чтение одной и до 10; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment; сверке — get_attachments_for_objects (id = ANY OR object_key = ANY), get_ready_page (keyset ready по id), find_attachment_reference, mark_lost / clear_lost (условный UPDATE lost_at)
    repos/attachment_object.py  # оригинал в S3: ключ <база>/attachments/<id>/original, put_original (поток BytesIO и size, без копии тела), open, delete_original; сверке — originals_prefix, is_own_key (ключ под префиксом вложений своей базы), parse_original_key, list_originals, probe_originals (bucket на месте), head_original
    repos/message.py         # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой
    services/<domain>.py     # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией
    services/attachment.py   # AttachmentService(db_scope, cache, storage, slots): загрузка (проверки → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT тем же BytesIO → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503; место — до ответа), метаданные, отдача потоком
    services/attachment_cleanup.py  # AttachmentCleanupService(db_scope, storage): проход уборщика — кандидаты keyset, каждая строка в два шага (remove_stale_pending): блокировка и пометка (commit) → блокировка, DELETE объекта и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO
    services/attachment_reconcile.py  # AttachmentReconcileService(db_scope, storage): сверка bucket и БД — S3 → БД (страницы списка, выборка на страницу, множество ключей), БД → S3 (keyset ready; ключ строки вне префикса вложений — чужой объект без HEAD; строка с ключом <id>/original другого вложения — HEAD её объекта, verify W2), зависшие, перепроверка в БД и HEAD (bucket — probe), сигнал — перед каждым вызовом хранилища, предел изменений, действия с apply (зависшие шагом уборщика → объекты без строки → пометки → снятия); журнал Found / Fixed / Finished; ReconcilePassDTO. С change track2-reconcile-cost: strategy head (выборка строки на объект, HEAD на строку, без множества), deep (GET и SHA-256 потоком, checksum_mismatch; «оригинал вернулся» — тот же SHA-256), предел скорости после каждого вызова S3 (_pace, куски 0,2 с; сигнал прекращает паузу, останавливает следующий check_stop — verify W1), ранний отказ по пределу (unchecked), счёт сеансов обёрткой db_scope, стоимость в итоге (storage_objects, s3_requests, read_bytes, db_sessions, phase_ms)
    exceptions/<domain>.py   # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва и срока тела (UploadTimedOut), 429 занятых мест (UploadsBusy), 500 пропавшего объекта
  infra/
    early_stop.py            # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog
    logger.py                # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи
    password.py              # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username
    upload_slots.py          # UploadSlots (asyncio.Semaphore по порядку прихода, счётчик ожидающих, срок ожидания; slot() — UploadsBusy или ожидание в мс, место в finally) и глобал upload_slots из [uploads]; импортирует только dependencies.py
    db/engine.py             # фабрики engine и сессий, BoundedCloseConnection, ping
    db/session.py            # глобалы engine и session_factory процесса API
    db/scope.py              # session_scope(factory, timeout_seconds): сессия на шаг, срок, отказ БД → invalidate, warning, ServiceUnavailable; общая для API и уборщика
    db/errors.py             # is_db_unavailable: какие ошибки драйвера — 503
    db/models/               # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit; attachment.py — Attachment (частичный индекс pending по (created_at, id), lost_at — пометка потерянного оригинала) и MessageAttachment (порядок position, FK без каскада)
    cache/client.py          # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск
    cache/instance.py        # глобал cache процесса API
    s3/client.py             # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete / list_page (ListObjectsV2 по префиксу, нет bucket — ошибка), срок на вызов и блок — единственный срок клиента (read_timeout aiohttp выключен: переживал ответ и портил соединение в пуле, change fix-upload-put-flake), ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo (с last_modified, у open — тоже), StoredObject, StoredObjectPage; счётчики попыток по операциям, ключей списка и прочитанных байт — stats() → StorageStats (change track2-reconcile-cost)
    s3/instance.py           # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan
  schemas/
    dataclasses/<domain>.py  # DTO между repo → service → api
    enums/<domain>.py        # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType, ReconcileFinding, ReconcileAction, ReconcileStrategy (batch, head)
  utils/
    constants.py             # лимиты контракта (с лабы 4 — 10 MiB, 40 млн пикселей, filename, 10 вложений), размер страницы, префиксы путей, имя bucket S3, разделитель и части ключа объекта, keep-alive клиента S3
    image.py                 # inspect_image: структурная проверка PNG/JPEG без декодирования пикселей (stdlib), тип, размеры, UnsupportedImage / DamagedImage / TooManyPixels
    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/uploads_api/s3_api, сбор маркеров spec, стоп без hook
  api_client.py              # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message (с attachment_ids) — с Idempotency-Key; post_attachment/upload, attachment_meta, attachment_content, attachment_content_slowly (потоком с паузой после блока)
  contract.py                # тела по схемам contracts/openapi.json, форматы id, attachment_ids и времени, X-Instance-Id, assert_error (с 413, 415 и 429 — Retry-After положительное целое), assert_errors (статусы всех вариантов запроса разом), assert_content (байты, тип, nosniff, без Location и x-amz-*), assert_replicas
  images.py                  # изображения для тестов: PNG на stdlib (любые IHDR, Adam7, точный размер, бомба, огромные размеры, порча байта, шум RGB ~1 MiB от зерна — png_noise), JPEG через Pillow (dev), обрезка и хвост
  test_attachments.py        # спек attachments: загрузка, лимиты, тип и целостность, filename, доступ, метаданные, оригинал, variant, повтор, 10 одновременных загрузок, другая реплика
  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>, уборка базы и префикса test_<db>/ в S3 (weed shell fs.rm, затем проверка fs.ls: код 0 weed shell успеха не значит; префикс только из проверенного имени) (stdlib)
  run_failures.py            # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap, уборщик с grace 20 с и интервалом 1 с без плановой сверки → FAULT_CLEANER_*, FAULT_RECONCILER_INTERVAL_S; уборщик с плановой сверкой <проект>-cleaner-scheduled убирается вместе с API), четыре API (обычный, «тесный», «узкий по загрузкам» с UPLOADS_ENV → FAULT_UPLOADS_BASE_URL / FAULT_UPLOADS_ENV, «с коротким сроком S3» с S3_ENV → FAULT_S3_BASE_URL / FAULT_S3_ENV), pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), журналы API и уборщика при падении, уборка (stdlib)
  fault_hook.py              # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников, сообщений и вложений (fail-attachments insert|ready|stall|commit|outlive|undeletable: сбой вставки, перевода в ready до и на COMMIT, задержка, строка «старше grace» с ожиданием уборщика, неудаляемая строка), заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, attachment-ids, last-pending, object-ids (файлы original по fs.tree), kill-api / start-api; расхождения и сверка (change track2-reconciler): put-object (тело — stdin, botocore в контейнере API его ключами) / delete-object (weed fs.rm) только под <база>/attachments/, delete-row, set-size, age-row, set-key (object_key строки под <база>/), lost-ids, fail-attachments mark, reconcile dry-run|apply [предел] [--strategy batch|head] [--deep] [--max-objects-per-second R] (аргументы по списку, записи и exit_code=), stop|start cleaner, run-cleaner <с> (stdlib)
  failures.compose.yml       # override стенда отказов: без публикации портов (Postgres, Valkey, S3, LB), уборщик с CLEANER__* 20 / 1, RECONCILER__INTERVAL_SECONDS 0 и restart "no", stop_grace_period 2 с у S3, 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 / bench_uploads (с S3)
  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; профиль uploads (S3 и bootstrap на стенде, на прогон — новый volume S3 и реплика с окружением варианта через .work/variant.compose.yml, образ «до» — тег bench-from, сэмплер peak), в паспорте всех профилей stand.api_tcp_rmem и docker.kernel; профиль reconcile (S3 с портом метрик через .work/s3-metrics.compose.yml, наполнение \copy и загрузчиком, разовые проходы mtusi-bench-reconcile-<n> с лимитом CPU варианта, «до» — .work/cleaner-before.compose.yml, метрики шлюза и pg_stat_database до и после, блок H4 с k6 background.js, отказ по пределу S4)
  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; режим peak (uploads) — сброс memory.peak реплики, S3 и LB через свой дескриптор (perl), чтение пика в конце окна, выборка current / anon / sock / oom_kill раз в 0,2 с (--user 0, cgroupfs rw, без сети)
  uploads.py                 # профиль uploads без docker: тела PNG из шума от зерна, план кругами, разбор строк k6 и сэмплера peak, строка runs.csv, пометки oom / host_swap / peak_sampled / s3_down, summary.md (медиана и min–max по ячейкам, сценарии спеков, H1–H4); --selftest
  reconcile.py               # профиль reconcile без docker (change track2-reconcile-cost): модель набора (id, содержимое и класс по номеру и зерну, строки CSV для \copy, ожидаемое по классам), план кругами, разбор записей уборщика, метрик шлюза S3, строк bg k6 и сэмплера, окна и r / a H4, passes.csv и windows.csv, вердикты H1–H4 и S4, summary.md и SVG (plots.Svg); --selftest
  fill_objects.py            # загрузчик объектов профиля reconcile: только в контейнере mtusi-bench-fill на образе стенда (botocore образа, bench/ на чтение, ключи API из окружения), процессы × потоки PUT по модели reconcile.py
  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; s3 (лимиты BENCH_S3_*, swap = память) запускают профили uploads и reconcile, cleaner (mtusi-bench-cleaner, без порта, лимиты BENCH_CLEANER_* без swap) — только разовыми проходами профиля reconcile; буфер приёма реплики — sysctls основного compose
  bench.env                  # подстановки compose стенда вместо .env рабочего стенда (без паролей и секретов S3: их генерирует run.py)
  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, досрочный выход), uploads (constant-vus загрузок тела из /work, пауза Retry-After на 429 и 1 с на прочие ошибки, строка на запрос, WARMUP — одна загрузка), background (профиль reconcile: constant-arrival-rate скачиваний, записи и чтения истории, строка bg на запрос, остановка SIGINT); 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; 739b8f04d5fb — частичный индекс pending CONCURRENTLY в autocommit_block; 5c3e1f0a9b7d — attachments.lost_at (NULL, SET LOCAL lock_timeout)
infra/                       # конфигурации сервисов стенда; README.md — skeleton
  valkey/valkey.conf         # лимит памяти и LRU, persistence выключен
  s3/bootstrap.sh            # bootstrap S3 (сервис s3-bootstrap, network_mode: service:s3): apply — bucket, анонимный доступ none, политики api-objects и cleaner-objects (у уборщика — ещё список только с префиксом S3_CLEANER_LIST_PREFIX = <база>/attachments/), пользователи api и cleaner с ключами из .env, проверки приватности обоих ключей; check (и строки ключа уборщика) и cleanup — для make s3_check; секреты — stdin weed shell и файл curl на tmpfs
  haproxy/haproxy.cfg        # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта (400, 502, 503, 504), timeout server 30 с пути загрузки (set-timeout, остальные 10 с), tune.sndbuf.server 256 KiB и tune.rcvbuf.client 128 KiB, мониторинг :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, s3 (~25 с); start api повторяет migrate и s3-bootstrap (no-op); уборщика не трогает — рестарт хранилищ он переживает сам
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 (до 90 с: дольше загрузки) → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/
Dockerfile                   # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck, MALLOC_MMAP_THRESHOLD_ (буфер загрузки растёт без копии)
docker-compose.yml           # проект mtusi-lab4: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), migrate, s3-bootstrap, api × API_REPLICAS без портов (sysctls: буфер приёма сокетов до 512 KiB), cleaner (уборщик: точка входа python -m src.cleaner, пул 1, ключи S3_CLEANER_*, без healthcheck), haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env, x-s3-api-keys-env)
.dockerignore
config_example.toml, .env.example
evidence/attachments/        # change attachments: smoke.md, failover.md (driver.py attachment-failover stop и kill), storage.md (driver.py attachment-storage), slow-transfer.md (10 MiB через LB дольше 6 с); change upload-consistency: consistency.md (driver.py upload-consistency и журналы API и уборщика), cleaner-process.md (старт, отказ конфигурации, остановка, окно 0, рестарт хранилищ, отказ S3 во время прохода)
evidence/s3/                 # change s3-storage: bootstrap.md (первый запуск, повтор, смена секрета, ошибка шага, до bootstrap), privacy.md (make s3_check, нарушение и исправление, порты, секреты по сервисам), grpc-admin.md (gRPC шлюза без токена), restart.md (restart.sh и SIGKILL S3), client.md (операции, pause/stop, неверный секрет, журнал), memory.md (20 × 10 MiB PUT); change upload-consistency: cleaner-key.md (пользователь уборщика в bootstrap, смена секрета, make s3_check с ключом уборщика, секреты по сервисам); change track2-reconciler: cleaner-list.md (bootstrap с политикой списка по префиксу, неверный префикс, make s3_check со строками списка уборщика, окружение s3-bootstrap)
evidence/reconcile/          # change track2-reconciler: cycle.md (driver.py reconcile-cycle), stress.md (driver.py reconcile-stress), service.md (Started cleaner с параметрами сверки, плановая сверка при старте, docker stop во время сверки при pause s3, код 1 разового прохода по сигналу — driver.py reconcile-signal, отказ старта на RECONCILER__*, коды 3 и 0; с change track2-reconcile-cost — остановка во время паузы предела скорости, driver.py reconcile-signal --pace)
evidence/reconcile/<метка>/  # результаты make bench_reconcile (change track2-reconcile-cost): meta.json (раздел reconcile: план, этапы и модели, commit и образы «до», аргументы S3), passes.csv, windows.csv, summary.md (H1–H4 и S4), cost-by-n.svg, requests-by-n.svg, background-p95.svg, raw/ (записи уборщика по проходам, итог k6 блока H4)
evidence/storage/            # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга
evidence/migrations/         # миграции с нуля и повторно, ошибка миграции; лаба 4: pending-index.md (ревизия 739b8f04d5fb с нуля, повтор, откат, EXPLAIN общего плана кандидатов уборщика на рабочей базе с откатом, rollout_quick), lost-at.md (ревизия 5c3e1f0a9b7d колонки lost_at: с нуля, повтор, откат, --sql с lock_timeout, make rolling_update с ревизией до и после)
evidence/auth/               # passwords-and-tokens.md — driver.py auth-storage на стенде текущей лабы: Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump (исключения сверки покрытия)
evidence/cache/              # hits.md — make test_isolated + driver.py cache-check на стенде текущей лабы: одно чтение chats на 50 через LB, TTL, ключи двух баз (исключения сверки покрытия)
evidence/tests/              # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md; лаба 4: failure-checks.md (стенд отказов со своим S3 и уборщиком, 56 проверок с `ca0c4b2`, красные прогоны новых тестов каждого change лабы 4 и правок по verify), student-test-lb.md, test-isolated-s3-cleanup.md (уборка префикса test_<db>/) — до attachments с ожидаемо красными тестами схемы Message; лаба 3 (в этом репозитории пока нет): 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/uploads/            # change upload-memory: <метка>/ — make bench_uploads (meta.json, runs.csv, summary.md, raw/), lb-timeouts.md — driver.py lb-upload-timeouts, rollout-upload.md — медленная загрузка во время make rolling_update
evidence/compare/            # таблицы make bench_compare: <до>__<после>.md
KNOWN_ISSUES.md              # найденные попутно дефекты, не исправленные без просьбы

evidence/ перенесён без содержимого лабы 3 (оно осталось в репозитории mtusi2026lab3-safronov). Каталоги выше появляются заново по мере changes; четыре файла исключений сверки покрытия снимаются заново на стенде лабы 4 (раздел «Переход в следующую лабу»).

Архитектура в двух словах

  • Поток однонаправленный. Роутер (зависимости, модели 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/s3/ (без infra/README.md skeleton), свои 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; с лабы 4 ещё driver.py --port <LB> attachment-failover (оба режима) → evidence/attachments/failover.md и driver.py --port <LB> attachment-storage → evidence/attachments/storage.md (student-tests.md). Файлы evidence/ этой лабы в новую лабу не копировать, даже эти: сверка проверяет только наличие файла и с копией останется зелёной без пересъёмки.
  • Profile.rollout_from в bench/run.py (профили rollout, rollout_quick) поменять на commit новой лабы до изменения, которое должна показать замена: commit этой лабы в истории новой нет, и команда откажет до стенда (bench.md, профиль rollout). Так же Profile.uploads_before (профиль uploads, вариант «до»): commit новой лабы до изменения, которое показывает профиль.
  • Сначала прочитать переходы 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, включая использование ИИ.