# 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` (активный): компенсация в загрузке (удаление объекта при известном исходе, 503 вместо 500), уборщик незавершённых загрузок — сервис `cleaner` (`python -m src.cleaner`, grace 900 с, свой пользователь S3 «чтение и удаление»), частичный индекс строк `pending`; дельты уже синхронизированы в основные спеки (новая capability `storage-consistency`). План работ, решения и трек «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` лабы 4 — в `openspec/changes/archive/`, активный — `upload-consistency`, спеки синхронизированы (новые capability: с `s3-storage` — `object-storage`, с `attachments` — `attachments`, с `upload-consistency` — `storage-consistency`); в `KNOWN_ISSUES.md` одна открытая запись (bootstrap после удаления bucket). Отчёт, 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). `/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`). - `.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//spec.md` — текущее поведение, `changes//` — предложения (`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 attachment-failover [--mode stop\|kill]` | вложение через LB, `stop-one.sh` принявшей реплики, скачивание через другую (тот же SHA-256), 404 постороннему, затем `make replicas`; доказательство исключения `attachments` «Принявшая реплика остановлена» | | `driver.py --port attachment-storage` | схема таблиц вложений, вид `object_key`, объект в bucket, анонимный GET — 403, `docker diff` реплик; доказательство исключения «Байты не в БД и не на диске API» | | `driver.py --port upload-consistency` | согласованность БД и S3 на рабочем стенде (~45 с): загрузка при `pause` S3 и со сбоем фиксации `ready` (триггер на `filename` прогона) — 503, строки `pending` не видны, компенсация удалила объект; `cleaner --once` с grace 30 с убирает обе, объектов без строки нет, готовое вложение цело; `evidence/attachments/consistency.md` | | `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_` с Valkey и S3 стенда (ключи кэша и объектов разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе — база и объекты под префиксом `test_/` (`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`, ~4 мин) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres, Valkey и S3 (с bootstrap), уборщик (grace 20 с, интервал 1 с), обычный и «тесный» API (срок 2 с, пул 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_plots LABELS="..." [PLOTS=scaling]` | графики SVG и сводка серий трека 1 из меток: R* от числа реплик, p95 от интенсивности, CPU по компонентам, эффективность и точка насыщения — `evidence/plots//` | | `make bench_ab BEFORE=... AFTER=... REAPPLY= [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, цикл с интервалом, SIGTERM — довести строку и выйти 0, --once — коды 0/1/2 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, [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100 api/ routers/health.py # /health/live, /health/ready: вне версии, без идентификации routers/v1/.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/.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), формат ошибки контракта; у 500 — X-Request-Id и X-Instance-Id middlewares/ # X-Request-Id, X-Instance-Id и access-лог core/ repos/.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 repos/attachment_object.py # оригинал в S3: ключ <база>/attachments//original, put, open, delete_original repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией services/attachment.py # AttachmentService(db_scope, cache, storage): загрузка (проверки → тело со счётчиком в BytesIO, bytes без копии → структура и SHA-256 в потоке → pending → PUT → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503), метаданные, отдача потоком services/attachment_cleanup.py # AttachmentCleanupService(db_scope, storage): проход уборщика — кандидаты keyset, каждая строка в три шага: блокировка и пометка (commit) → DELETE объекта → блокировка и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва, 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 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)) и 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 / head / open (чтение блоками) / delete, срок на вызов и блок, ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo, StoredObject s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan schemas/ dataclasses/.py # DTO между repo → service → api enums/.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType 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, сбор маркеров spec, стоп без hook api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message (с attachment_ids) — с Idempotency-Key; post_attachment/upload, attachment_meta, attachment_content contract.py # тела по схемам contracts/openapi.json, форматы id, attachment_ids и времени, X-Instance-Id, assert_error (с 413 и 415), assert_errors (статусы всех вариантов запроса разом), assert_content (байты, тип, nosniff, без Location и x-amz-*), assert_replicas images.py # изображения для тестов: PNG на stdlib (любые IHDR, Adam7, точный размер, бомба, огромные размеры, порча байта), JPEG через Pillow (dev), обрезка и хвост test_attachments.py # спек attachments: загрузка, лимиты, тип и целостность, filename, доступ, метаданные, оригинал, variant, повтор, другая реплика 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_.py # сценарии основных спеков, маркер @pytest.mark.spec test_failures.py # проверки отказов (маркер fault): только make failure_checks run_isolated.py # make test_isolated: образ на временной базе test_, уборка базы и префикса test_/ в 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_*), два API, 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 (stdlib) failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, S3, LB), уборщик с CLEANER__* 20 / 1 и 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 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; s3 и cleaner описаны (mtusi-bench-s3, mtusi-bench-cleaner, без порта), но профили их не запускают 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, досрочный выход); 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 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, пользователи 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 в формате контракта, мониторинг :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 → 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 без портов, 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, рестарт хранилищ) 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 с ключом уборщика, секреты по сервисам) evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга evidence/migrations/ # миграции с нуля и повторно, ошибка миграции; лаба 4: pending-index.md (ревизия 739b8f04d5fb с нуля, повтор, откат, EXPLAIN общего плана кандидатов уборщика на рабочей базе с откатом, rollout_quick) 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 и уборщиком, 29 проверок, красный прогон до upload-consistency), student-test-lb.md, test-isolated-s3-cleanup.md (уборка префикса test_/) — до 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/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/-`, затем перенести своё. - Переносить: `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 cache-check --require-test-keys` → `evidence/cache/hits.md`; `driver.py --port auth-storage` → `evidence/auth/passwords-and-tokens.md`; `make test-persistence ACTION_SCRIPT=scripts/restart.sh` → `evidence/replicas/test-persistence.md` (или путь, который назовёт исключение); повтор отправки с ключом после `docker compose up -d --force-recreate api` → `evidence/idempotency/replay-after-restart.md`; с лабы 4 ещё `driver.py --port attachment-failover` (оба режима) → `evidence/attachments/failover.md` и `driver.py --port attachment-storage` → `evidence/attachments/storage.md` (`student-tests.md`). Файлы `evidence/` этой лабы в новую лабу не копировать, даже эти: сверка проверяет только наличие файла и с копией останется зелёной без пересъёмки. - `Profile.rollout_from` в `bench/run.py` (профили `rollout`, `rollout_quick`) поменять на commit новой лабы до изменения, которое должна показать замена: commit этой лабы в истории новой нет, и команда откажет до стенда (`bench.md`, профиль `rollout`). - Сначала прочитать переходы 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`, включая использование ИИ.