Files
mtusi2026lab6/AGENTS.md
T
2026-11-15 06:17:06 +03:00

937 lines
177 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MTUSI Messenger
REST API мессенджера (пользователи, чаты, история сообщений). Этот код
переносится через все семь лабораторных курса и на каждой обрастает
инфраструктурой. Текущая работа — **лаба 6** (`lab.json`): наблюдаемость —
SDK OpenTelemetry в API и worker, отдельный OTel Collector, хранилища
метрик, логов и трасс, Grafana с provisioning из git; бизнес-API не
меняется (`README.md`, `contracts/observability.md`,
`contracts/infrastructure.json`, `infra/otel/README.md`). Цель — оценка 5,
трек 1 «Цена наблюдаемости»; хранилища — Prometheus (метрики), Loki
(логи), Tempo (трассы), интерфейс — Grafana (решения пользователя
2026-11-11). План изменений лабы и развилки — `PLAN.md`. Решения, принятые
без пользователя, и открытые вопросы —
`QUESTIONS.md`. Первое изменение лабы, наблюдаемость (уровень 3) — change
`otel-telemetry` (заархивирован 2026-11-11,
`openspec/changes/archive/2026-11-11-otel-telemetry/`, новая capability
`observability`): SDK в
API и worker (секция `[telemetry]`, `src/infra/telemetry/`), Collector
contrib, Prometheus, Loki, Tempo и Grafana в compose (`infra/otel/`, сеть
`telemetry`, наружу — только Grafana на `127.0.0.1:GRAFANA_OUT_PORT`), сигналы
уровня 3, healthcheck брокера от его пользователя (стенд с нуля одной
командой), команды драйвера `telemetry-check`, `telemetry-outage`,
`stand-from-scratch` (правило `telemetry.md`). Второе изменение лабы, первая
часть уровня 4 — change `job-trace-propagation` (заархивирован 2026-11-11,
`openspec/changes/archive/2026-11-11-job-trace-propagation/`, capability
`observability`, изменены ещё `graceful-shutdown`, `service-configuration`,
`service-logging`):
контекст W3C загрузки в `attachment_jobs.traceparent` / `tracestate`
(ревизия `e4b8c2d17f90`), SDK в relay (`messenger-relay`), span producer
relay и consumer span worker (parent и link) — одна трасса на загрузку, с
повторами и replay; заголовки AMQP — carrier, тело сообщения прежнее;
`ParentBased(ALWAYS_ON)`; ленивый импорт SDK; метрики уровня 4 — время до
`ready`, очередь и возраст (снимок relay), пул `db.client.connection.*`
(`CountingQueuePool`), насыщение worker, CPU и память контейнеров из cgroup
(без `docker.sock`); панели уровня 4 в том же dashboard; команда драйвера
`trace-chain`. Код — commit `72cfa9a`, evidence снято на нём:
`evidence/telemetry/check.md`, `queue-snapshot.md`, раздел change в
`budget.md`, `evidence/migrations/job-trace-context.md`; правки verify —
commit `72e2598`, на нём пересняты `evidence/telemetry/trace-chain.md` и
`collector-outage.md` (`check.md`, `trace-chain.md` и `collector-outage.md` ещё раз
пересняты на `15ea156`, change `slo-alerts`). Третье изменение лабы, вторая часть уровня 4 —
change `slo-alerts` (заархивирован 2026-11-14,
`openspec/changes/archive/2026-11-14-slo-alerts/`, изменяет `observability` и `load-balancing`):
SLI и SLO (доступность на LB 99,5 %, задержка «лёгких» ручек ≤ 0,25 с 99 %,
время до `ready` ≤ 30 с 99 %, окно 7 суток), метрики HAProxy (`/metrics` на
порту статистики, забирает только Collector), правила записи и семь
оповещений Prometheus в `infra/otel/prometheus/rules.yml` с тестами
`rules.test.yml` (`make alerts_test`, шаг CI) и runbooks
`infra/otel/runbooks/`, без Alertmanager; очереди экспорта Collector по байтам
и повторы 30 с, срок рядов экспортёра 1 мин, время начала рядов по protobuf
(`created-timestamp-zero-ingestion`); внутренние метрики SDK и учёт потерь
(`telemetry:lost_items:total`); панели SLO, LB и конвейера; команды драйвера
`alerts-check` и `backend-outage`. ВМ Docker Desktop с 2026-11-11 — 12 CPU /
11 902 МиБ. Код — commit `15ea156`, evidence снято на нём (2026-11-13):
`evidence/alerts/rules-test.md`, `evidence/alerts/check.md`,
`evidence/telemetry/backend-outage.md`, пересняты `evidence/telemetry/check.md`,
`trace-chain.md`, `collector-outage.md`, раздел change в `budget.md`. Правки verify
(ноль ряда потерь процесса SDK, описания оповещений с текущим значением, панель потерь
в проверках, pending на каждом шаге, сверка SLI одним окном) — commit `ef60b47`, на нём
пересняты (2026-11-14) `rules-test.md`, `alerts/check.md` и `backend-outage.md`;
`evidence/telemetry/check.md` — на `4a2f9c9` (тот же код и правила, драйвер ждёт в Loki все записи
прохода relay). Четвёртое изменение лабы, уровень 5, трек 1 «Цена наблюдаемости» — change
`track1-telemetry-cost` (заархивирован 2026-11-15,
`openspec/changes/archive/2026-11-15-track1-telemetry-cost/`, изменяет
`observability`, `service-configuration`, `load-benchmark`): выбор трасс в голове и наборы границ
histogram — поля `[telemetry] trace_sample_ratio`, `metric_buckets` (по умолчанию прежнее
поведение), счёт начатых span `otel.sdk.span.started`, запись о старте с долей, набором и
интервалом; телеметрия на стенде `bench/` — профиль `make bench_telemetry` (варианты `off`,
`full`, `full-aa`, `head`, `tail`, `metrics`, `balanced`, редкие события с известным счётом,
`evidence/telemetry-cost/<метка>/`) и выключатель `TELEMETRY=on` у `bench_uploads` и
`bench_queue`; сбалансированная конфигурация — `bench/otel/` (рабочий стенд остаётся со всеми
трассами); гипотезы H1–H8 и критерии B1–B5 — `REPORT.md`, «Цена наблюдаемости (трек 1)».
Гипотезы — commit `509afca`, метка `evidence/telemetry-cost/baseline2/` снята на коде `68e14b6`
(каталог — commit `0f5dbfc`), правки verify — commit `56132c7`.
Код перенесён из лабы 5 (репозиторий
`mtusi2026lab5-safronov`, ветка `solution/bvt2301-safronov`, commit
`046ec9e`) по разделу «Переход в следующую лабу»; отчёт и evidence лабы 5
остались в её репозитории. Дальше — что досталось от лабы 5: брокер
RabbitMQ 4, отдельный worker, состояния вложения `queued` / `processing` /
`ready` / `failed` и преобразование изображений; загрузка отвечает `202`
(`COURSE.md`, переход 4 → 5, `contracts/README.md`, «Фоновая обработка (с
lab5)», `contracts/attachment-states.md`, `contracts/jobs.schema.json`).
Предупреждения о хосте, которые явно не влияют на результат замера, прогон
не останавливают (указание пользователя 2026-10-31). Фоновая обработка
(уровень 3) — change `async-attachments` (заархивирован 2026-10-31,
`openspec/changes/archive/2026-10-31-async-attachments/`): загрузка — 202
после staging, задания в PostgreSQL и подтверждения брокера, worker на
образе API, thumbnail, очередь RabbitMQ 4, новые capability
`attachment-processing` и `message-broker`. Надёжность конвейера
(уровень 4) — change `pipeline-reliability` (заархивирован 2026-10-31,
`openspec/changes/archive/2026-10-31-pipeline-reliability/`, новая capability `job-outbox`): outbox и
relay вместо публикации в запросе, варианты `crop` и `optimized`, лимиты в процессе
обработки на задание, backoff с jitter, реестр `failed` и replay, аренда и fencing,
prefetch, очистка staging. Единица работы — change `unit-of-work` (заархивирован 2026-11-01,
`openspec/changes/archive/2026-11-01-unit-of-work/`, полный UoW по Cosmic Python, решение
пользователя, новая capability `unit-of-work`): сервисы на абстракциях
`src/core/ports/`, соединение на шаг, быстрые тесты `service-tests/`. Очередь под
перегрузкой (уровень 5) — change `track1-queue-overload` (заархивирован 2026-11-02,
`openspec/changes/archive/2026-11-02-track1-queue-overload/`, новая capability
`queue-overload`): предел незавершённых заданий на входе API, профиль `make bench_queue`,
гипотезы H1–H9 в `REPORT.md` лабы 5; основная метка `baseline4` — в репозитории лабы 5. В
лабу 5 код пришёл из лабы 4 (репозиторий `mtusi2026lab4-safronov`, ветка
`solution/bvt2301-safronov`, commit `2546deb`); отчёт и evidence лабы 4
остались в её репозитории. Дальше — что досталось от лабы 4. 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/`. Рабочий план лабы 4 (`PLAN.md`) удалён после закрытия
всех changes: итоги — в `REPORT.md` репозитория лабы 4, открытые вопросы
преподавателю — в его разделе «Открытые вопросы преподавателю», последняя
версия плана — там же, `git show fd03b84: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, `async-attachments`,
`pipeline-reliability`, `unit-of-work` и `track1-queue-overload` лабы 5 и
`otel-telemetry`, `job-trace-propagation`, `slo-alerts` и `track1-telemetry-cost` лабы 6 — в
`openspec/changes/archive/`, активных нет (новые
capability: с `s3-storage` —
`object-storage`, с `attachments` — `attachments`, с
`upload-consistency` — `storage-consistency`, с `async-attachments` —
`attachment-processing`, `message-broker`, с `pipeline-reliability` — `job-outbox`,
с `unit-of-work` — `unit-of-work`, с `track1-queue-overload` — `queue-overload`, с
`otel-telemetry` — `observability`);
в `KNOWN_ISSUES.md` одиннадцать открытых записей (запись о первом старте RabbitMQ на
пустом volume закрыта change `otel-telemetry`; с него же — 400 текстом uvicorn на
нестандартный метод HTTP; смесь версий при замене реплик на первый
релиз с обработкой; bootstrap после удаления
bucket; уборщик
удаляет объект зависшей загрузки по ключу вне своего префикса; 408 LB на медленные заголовки текстом HAProxy; поля `float` настроек принимают `inf`; 504 LB на метаданных и скачивании вложения при зависшем PostgreSQL; ложный FAIL `driver.py reconcile-cycle` на наполненном стенде; память S3 на долго живущем стенде; граница живой загрузки уборщика без закрытия соединения; остановка API при замороженном PostgreSQL дольше срока контейнера). Отчёт, 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/` (кроме своего CI job по `CONTRIBUTING.md`,
«CI»: `.github/workflows/application.yml` и `.github/ci/`),
`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; быстрые тесты сервисов на фейках и настоящая
единица работы — только в `service-tests/` вне образа
(`.claude/rules/service-tests.md`).
- Единица работы (change `unit-of-work`, `service-layer.md`): работа сервиса с
PostgreSQL — `async with self.uow:`, один блок — одна транзакция, явный
`await self.uow.commit()`, выход без него — откат. Вложенный блок и repo вне
блока или после фиксации — ошибка. В сервисах нет `AsyncSession`, SQLAlchemy,
реализаций repo и глобалов хранилищ: они зависят от `src/core/ports/`, реализации
выбирают точки входа. Экземпляр — на задачу: запрос, доставка worker, сервис в
последовательных процессах. Соединение занято на шаг, вход и операция — разные
блоки; `[database] request_timeout_seconds` — срок блока с откатом, а на
JSON-роутерах ещё и общий срок запроса (`request_deadline`). Новый метод repo —
порт, SQL, фейк и строка `service-tests/repo_contract.py`.
- Упавший тест — сначала разбор, потом правка. Воспроизвести падение,
прочитать вывод и назвать причину: дефект приложения, ошибка в самом
тесте или стенд (чужой сервис на порту, старый образ, не тот
`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–6.
- Лаба 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–6.
- Лаба 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 с по
формуле, с закрытием соединения до 21 с, иначе уборщик не стартует) под `FOR UPDATE SKIP LOCKED`, в два шага:
пометка строки (`updated_at`) отдельной транзакцией, затем объект и
строка одной транзакцией под блокировкой (объект раньше строки);
помеченную строку `mark_queued` в `queued` не переводит,
`queued`, `processing`, `ready` и `failed` уборщик не трогает, удаляет
`staging_key`, а у строки прежней версии `object_key`. У уборщика свой пользователь 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 (вопрос преподавателю, `REPORT.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 с по
формуле, с закрытием соединения до 21 с: `KNOWN_ISSUES.md`).
Буфер приёма сокетов `api` — 512 KiB (`sysctls`), буфер отправки LB к
реплике — 256 KiB, буфер приёма LB от клиента — 128 KiB; `timeout server` пути загрузки 30 с, остальных — 10
с; `ROLLOUT_DRAIN_TIMEOUT` 90 с (`balancer.md`, `docker.md`).
- Лаба 5, фоновая обработка (change `async-attachments`, `worker.md`): ответ 202
— только после оригинала в staging (`<база>/staging/<id>/original`) и `queued` с
заданием одной транзакцией. Ack — после устойчивого эффекта, повтор — те же
ключи, ключ эффекта `(attachment_id, pipeline_version, variant)`. Брокер, relay и
worker не входят в `/health/ready`, без них работают загрузка (202), текст,
история, метаданные и готовые байты. Очередь — `<база>.attachment.process.v1`,
durable, сообщения persistent, в них только id и служебные поля
(`contracts/jobs.schema.json`).
- Лаба 5, надёжность конвейера (change `pipeline-reliability`, `worker.md`):
брокера в пути запроса нет, у реплик API ни клиента, ни пароля; намерения
(`attachment_jobs`, `state = 'queued' AND published_at IS NULL`) публикует
relay (`python -m src.relay`, отдельный сервис) с подтверждением, отметка — только
подтверждённым; доставка at least once, дубль — no-op. Сообщение — подсказка, истина
в строке: дубль при живой аренде и сообщение раньше срока подтверждаются без
эффекта, номер попытки — fencing. Аренда `job_timeout + lease_margin` без пульса,
истёкшую возвращает relay. Следующую попытку публикует relay по `next_attempt_at`
(backoff с jitter), пауза места конкуренции не занимает. Декодирует и делает три
варианта только отдельный процесс на задание (`src/worker/render.py`, лимиты CPU и
адресного пространства, без секретов в окружении): Pillow нет ни в репликах, ни в
процессе worker. Постоянная ошибка — `failed` сразу, реестр — строки `failed`, возврат
— `make replay` с записью аудита и новым бюджетом (`attempt_base`). Staging убирает
только уборщик: у `ready` — следующим проходом, у `failed` — по `[cleaner]
staging_retention_seconds` вместе с частично записанными объектами, блокировка `FOR
NO KEY UPDATE`; сверка находит `orphan_staging`. Лимиты 0,25 CPU / 256 МБ у relay, пул
1. Цепочка LB — 26 с и 73 с (`balancer.md`).
- Лаба 5, предел принятой работы (change `track1-queue-overload`, спек `queue-overload`,
`service-layer.md`): загрузка при `[uploads] max_unfinished_jobs` (250, 0 — без предела)
и больше незавершённых заданий стенда (`queued`, `processing`) получает 429
`rate_limited` с `Retry-After: 5`, без тела и места, ни строки, ни объекта. Порядок: 404
→ 415 → 413 → 429 предела → 429 мест. Считает все реплики по PostgreSQL одним запросом
в первом блоке (три частичных индекса с `LIMIT` на группу, `count_unfinished`), шаг
с БД не прибавляется, цепочка LB прежняя. Предел мягкий: превышение — только загрузки в
полёте. Текст, история, метаданные, готовые байты и `/health/ready` от него не
зависят. Профиль `uploads` и четыре прежних API стенда отказов — с пределом 0.
- `.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 |
| `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 млн пикселей, на лабе 4 `201 Attachment` (`ready`), с лабы 5 — `202` (`queued`), `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 не публикуются; с лабы 6 — `otel_collector` (metrics, logs, traces), `telemetry_storage` (три сигнала, например Prometheus, Loki, Tempo; persistent volume) и `grafana` (provisioning в git) |
| `contracts/observability.md` | с лабы 6: логические сигналы по уровням (HTTP requests и duration, jobs и их duration, логи с `trace_id` / `span_id`, трассы API и worker; на 4 — queue depth и возраст старейшей job, пул БД и saturation worker, сквозная связь upload → publish → consume, время до `ready`), resource attributes, запрещённые labels и данные в telemetry, определение error ratio, что лежит в git (Collector, backends, provisioning, dashboard JSON, alert rules), три контролируемых инцидента уровня 4 |
| `lab.json` | номер лабы (6); по нему `tests/client.py` выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer; с лабы 3 — идемпотентность; с лабы 4 — вложение, 201 вместо 202 с лабы 5; у лабы 6 — как у лабы 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` |
| `infra/otel/README.md` | с лабы 6: что положить — `collector.yaml` (receivers, processors, exporters, bind endpoints, memory limits / batch, поведение при backpressure), конфиги хранилищ, provisioning datasources и dashboards Grafana, dashboard JSON; на 4 — alert rules и runbooks; OTLP, metrics и административные порты наружу не публиковать; сделано — `infra/otel/` (change `otel-telemetry`, карта кода; alert rules, тесты и runbooks — change `slo-alerts`: `infra/otel/prometheus/rules.yml`, `rules.test.yml`, `infra/otel/runbooks/`), правило `telemetry.md` |
| `REPORT.md` | отчёт: запуск из чистого clone, архитектура, доказательства по каждому критерию, эксперименты, ИИ и источники |
| `evidence/` | сохранённые выводы проверок и измерений (что можно класть — `evidence/README.md`) |
| `CONTRIBUTING.md` | fork/PR, имя ветки, что переносить в следующую лабу |
| `.github/pull_request_template.md` | шаблон PR; CI `workflows/contracts.yml` проверяет только контракт, приложение не запускает; сборку, стенд и `make test` — свой job `workflows/application.yml` (карта кода) |
| `Dockerfile.example` | опорные шаги Dockerfile, не рабочий файл |
| `.env.example` | шаблон `.env`; «логические» имена skeleton (lab2, lab3 `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS` и новые lab4 `S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, lab5 `BROKER_URL_FILE` и др.) перечислены в шапке, их соответствие — в `REPORT.md` (`settings.md`); имена lab6 `OTEL_*` настройками не являются — их соответствие `[telemetry]` и константам кода в шапке шаблона и в `REPORT.md`; `GRAFANA_ADMIN_PASSWORD` (случайный от `make env_setup`) и `GRAFANA_OUT_PORT` |
| `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/**`, `src/core/ports/**`: порты и repo-классы |
| `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/**`, `.github/ci/**`, `.github/workflows/application.yml`: мультистейдж, 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, особый стенд |
| `service-tests.md` | `service-tests/**`: быстрые тесты на фейках, контракт repo на фейке и на SQL, временная база |
| `worker.md` | `src/worker/**`, `src/relay/**`, `src/infra/render/**`, `src/core/services/attachment_processing.py`, `attachment_relay.py`, `attachment_replay.py`, `src/utils/image_variants.py`: worker, relay, процесс обработки, claim и fencing, аренда, бюджет, лимиты, варианты, replay |
| `bench.md` | `bench/**`: нагрузочный стенд на Postgres (проект compose `mtusi-bench`), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний |
| `migrations.md` | `migrations/**`, `alembic.ini`, `src/infra/db/models/**`: схема до запросов, ограничения, индексы, повторный запуск миграций |
| `telemetry.md` | `src/infra/telemetry/**`, `infra/otel/**` (с лабы 6): SDK только из `[telemetry]` и без `OTEL_*`, правило корня, запреты атрибутов, журнал через хуки, закрытие со сроком, конфигурации Collector, хранилищ и Grafana файлами для CI, сети и healthcheck |
- **`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-lab6` со своей базой. После `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`; рядом, без зависимостей приложения от них, — otel-collector, prometheus, loki, tempo и grafana на `127.0.0.1:GRAFANA_OUT_PORT` (пароль `admin` — `GRAFANA_ADMIN_PASSWORD` из `.env`); на пустых volumes — с первой попытки; `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-lab6` — код 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` (`9cc6c0c`, commit переноса лабы 5 в лабу 6: ранний отказ уже есть, `bench.md`) и 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 run_worker` | worker в консоли (`python -m src.worker`, тот же `.env`, ключи `S3_WORKER_*` в окружении процесса, рецепт без эха); рядом с `make run_dev` |
| `make run_relay` | relay в консоли (`python -m src.relay`, те же мосты `.env`); рядом с `make run_dev`: без него задания ждут в PostgreSQL |
| `make replay [ATTACHMENT=…] [ERROR_CODE=…] [REASON=…] [LIMIT=…] [APPLY=1] [OPERATOR=…]` | реестр `failed` и возврат работы (`docker compose run --rm --no-deps relay replay …`): без `APPLY=1` только показ; с ним выбор обязателен, иначе код 2; 0 — выполнено или показано, 3 — есть отказы, 1 — отказ PostgreSQL |
| `make start_broker` / `make stop_broker` | брокер стенда: `up -d --wait rabbitmq` / `stop rabbitmq` |
| `driver.py --port <LB> defense-scenario` | сценарий защиты на рабочем стенде: worker остановлен → 202 → сообщение 201 → 409 → текст 201 → `scripts/restart.sh` → worker → `ready`, оригинал и thumbnail; `id` и `StartedAt`, worker запускается при любом исходе; `evidence/attachments/defense.md` |
| `driver.py --port <LB> broker-check [--require-test-queue]` | образ и digest, volume, порт, предел памяти, очередь, остановка брокера; `evidence/broker/stand.md`, `evidence/broker/isolated.md` |
| `driver.py --port <LB> worker-process` | PID 1, лимиты, остановка, неверные `WORKER__*`, рестарт хранилищ, остановка на двух дорогих JPEG (быстрее 9,5 с, в том числе при замороженных PostgreSQL и брокере), ~5 мин; `evidence/worker/process.md` |
| `driver.py --port <LB> relay-process` | то же у relay: PID 1, нет healthcheck, лимиты, запись о старте, неверные `RELAY__*`, остановка простаивающего, на старте и при замороженном брокере, рестарт хранилищ; `evidence/relay/process.md` |
| `driver.py --port <LB> defense-faults` | шаг 4 защиты на рабочем стенде (~4 мин: аренда 70 с): crash после записи объектов и после фиксации до ack, relay убит до публикации и после подтверждения до отметки, replay неудачного и отказ replay готового; триггеры на `filename` прогона снимаются, worker и relay запускаются при любом исходе; `evidence/attachments/defense-faults.md` |
| `driver.py --port <LB> pipeline-state` | только чтение, JSON: задания по состояниям, due, ждущие срока, опубликованные и не взятые, истёкшие аренды, возраст старейшего, очередь |
| `driver.py --port <LB> worker-memory` | память контейнера worker (~35 с): на девять случаев в пределах контракта два одинаковых файла разом, новая cgroup на случай; `memory.peak`, `VmHWM`, `render_peak`, OOM, сумма пиков меньше 1 ГБ; worker и relay запускаются при любом исходе; `evidence/worker/memory.md` |
| `driver.py freeze-sessions [--rounds 6] [--settle 15]` | сессии PostgreSQL и журнал пула после заморозки (~2,5 мин), работает и на рабочем стенде: приложение в процессе одноразового контейнера `api`, PostgreSQL только через TCP-прокси пробы, заморожен прокси, а не сервер; режимы — между блоками и до запросов при пуле 2 и 4; `evidence/storage/freeze-sessions.md` |
| `driver.py --port <LB> telemetry-check` | телеметрия рабочего стенда через HTTP API Grafana с паролем из `.env` (~2 мин, change `otel-telemetry`): вход, порт, источники, dashboard provisioned и неизменяем, цели Prometheus, метрики LB, панель потерь на тихом стенде — 0 (ожидание до 330 с); свой запрос → stdout → Loki → Tempo, traceparent, нестандартный метод, 401, 404; загрузка → трасса worker, недекодируемый JPEG → `failed`; рост счётчиков по репликам и исходам; S3 заморожен → span S3 с ошибкой (`unpause` в `finally`); сети хранилищ из api и worker, разовый контейнер с `OTEL_*`, проба приватности, рестарт Collector и хранилищ; `evidence/telemetry/check.md` |
| `driver.py --port <LB> telemetry-outage` | Collector `stop` и `pause` (~3,5 мин): `make test`, загрузка до `ready`, записи SDK в stdout; возврат Collector — запись, трасса, span producer и ряды API, worker и relay при прежних `StartedAt` и `RestartCount` их контейнеров; второе окно того же вида — `make test`, `docker stop` реплики, worker и relay быстрее 10 с с кодом 0; все сервисы телеметрии остановлены — рестарт api, worker и relay, `make test`; сигналы (и span producer relay) снова приходят; стенд возвращается в `finally`; `evidence/telemetry/collector-outage.md` |
| `make alerts_test` | правила Prometheus без стенда и сети (change `slo-alerts`): `tar` файлов `infra/otel/prometheus/` в одноразовый контейнер образа Prometheus из compose (`--network none`) — `promtool check config`, `check rules`, `test rules rules.test.yml`; затем у каждого оповещения `runbook_url` на существующий файл; шаг CI; `evidence/alerts/rules-test.md` |
| `driver.py --port <LB> alerts-check` | учения оповещений на рабочем стенде (~25 мин, change `slo-alerts`), через HTTP API Grafana: правила загружены, доставки нет, тихий стенд (иначе код 2); фоновая нагрузка драйвера; worker остановлен — `MessengerQueueLagHigh` и счёт времени до готовности по точкам; relay остановлен — `MessengerQueueMetricsMissing`; блокировка таблицы сообщений — `MessengerSlowRequests`, доля span PostgreSQL, пул, CPU; входы по Basic — без оповещения; PostgreSQL остановлен — `MessengerNoReadyReplicas` и `MessengerHighErrorRate`, 5xx LB против API; на каждом шаге моменты pending, firing и снятия; SLI двумя путями (у доступности и задержки — и одним окном часа), новые панели и история состояний; в `finally` — нагрузка, сессия блокировки, PostgreSQL, worker, relay, LB; `evidence/alerts/check.md` |
| `driver.py --port <LB> backend-outage` | отказ хранилищ телеметрии под нагрузкой (~18 мин, change `slo-alerts`): Loki и Tempo 10 с и 120 с, Prometheus 60 с, Collector 120 с — `make test`, 5xx у клиента, очереди и память Collector, память реплик, учёт потерь и панель потерь (Collector и SDK реплик), `TelemetryTargetDown` и `TelemetryDataLoss`, пики памяти по cgroup; сервисы телеметрии запускаются в `finally`; `evidence/telemetry/backend-outage.md` |
| `driver.py --port <LB> trace-chain` | сквозная трасса и сигналы уровня 4 на рабочем стенде (~5 мин, change `job-trace-propagation`), через HTTP API Grafana: предусловие — глубина очереди 0 за 120 с (иначе код 2 «stand is not quiet»); очередь и её возраст при остановленном worker и спад до 0; загрузка с повтором при замороженном S3 — одна трасса: server span API, два span producer relay, два consumer span worker (parent и link, span S3 с ошибкой, запись оригинала и вариантов); replay в той же трассе; задание без контекста (`UPDATE` колонок своей строки) — корень worker; время до `ready`, пулы, ёмкость worker, пределы контейнеров = `docker inspect` и рост CPU каждого за прогон, нет сокета Docker, панели уровня 4 с данными; `unpause s3`, worker и relay — в `finally`; `evidence/telemetry/trace-chain.md` |
| `driver.py stand-from-scratch [--runs 2]` | `make run_docker` на пустых volumes своим проектом `mtusi-lab6-scratch` (рабочий — код 2) на свободных портах (~1 мин на прогон): код 0, состояния, `RestartCount` брокера и телеметрии 0, нет `eacces`, provisioning, `make test`; проект удаляется с volumes при любом исходе, ID контейнеров рабочего стенда прежние; `evidence/stand/from-scratch.md` |
| `driver.py freeze-lb [--rounds 3]` | только не рабочий проект compose (`COMPOSE_PROJECT_NAME`, по умолчанию `mtusi-lab6-freeze`; `mtusi-lab6` — код 2): сама поднимает стенд с данными в tmpfs (volumes нет) на образе `mtusi-messenger:lab6` и убирает его при любом исходе; `docker pause` PostgreSQL, шесть запросов через LB — 503 за ~8 с, 504 нет, `unpause` в `finally`, сессий не больше пулов (~1,5 мин); раздел `evidence/storage/freeze-sessions.md` |
| `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 service_test` | быстрые тесты сервисов на фейках (`service-tests/unit`): ветки всех сервисов, архитектура (импорты, сигнатуры порт — реализация — фейк), контракт repo на фейке; без PostgreSQL, Valkey, S3, брокера, docker и сети, секунды (`service-tests.md`) |
| `make service_test_db` | `start_db` и `service-tests/db` на временной базе `test_uow_<db>`: настоящая единица работы, тот же контракт repo на SQL, соединение на шаг и общий срок JSON-запроса в процессе (S3 и кэш — фейки), замороженный сервер — TCP-прокси; база удаляется при любом исходе, имя не по шаблону — код 2 |
| `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`, 147 проверок, ~39 мин) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres, Valkey и S3 (с bootstrap), уборщик (grace 20 с, интервал 1 с), пять API — обычный, «тесный» (срок 2 с, пул 1), «узкий по загрузкам», «с коротким сроком S3» (1 с) и «узкий по заданиям» (предел 3; у прочих предел выключен), 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`; сейчас `9cc6c0c` — commit переноса лабы 5 в лабу 6, правило выбора — `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` — `9cc6c0c`, commit переноса лабы 5 в лабу 6: места загрузки уже есть, успех 202, `bench.md`; `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_queue [QUEUE_LABEL=...] [RESUME=1]` | уровень 5, трек 1, очередь под перегрузкой (~2 ч 10 мин, метка `baseline` по умолчанию; заняты `baseline`…`baseline4`, основная — `baseline4`, новый прогон — со своей `QUEUE_LABEL`; change `track1-queue-overload`): стенд `mtusi-bench` с S3, брокером, relay, worker и уборщиком, настройки (1, 1), (2, 2), (4, 4), (2, 256) × классы `s`, `m`, `lj`, `lp` × 3 повтора и блоки предела, приёма, второго worker, KILL worker, рестарта брокера; на ячейку — свежий стенд, открытая модель, контрольный поток, разбор очереди, обход метаданных; `evidence/queue/<метка>/` (`meta.json`, `cells.csv`, `timeline.csv`, `summary.md` с H1–H9 и рекомендацией, SVG). Рабочий стенд — `make stop`, гипотезы закоммичены раньше метки |
| `make bench_queue_quick` | то же короче (~11 мин): `s` (2, 2), `lp` (4, 4), предел 40 и без него, `kill-worker`, `w2-p256`, один повтор, метка `quick-queue-<время>`, в git не идёт; шаг защиты «для 5» лабы 5 |
| `TELEMETRY=on` у `make bench_uploads`, `bench_uploads_quick`, `bench_queue`, `bench_queue_quick` | выключатель телеметрии стенда (change `track1-telemetry-cost`, по умолчанию `off` — методика прежняя): Collector, Prometheus, Loki и Tempo рабочего стенда (`bench/telemetry.compose.yml`, без Grafana) и SDK реплик, worker и relay с настройками рабочего стенда; режим — в паспорте и сводке, `RESUME=1` — только в том же режиме; у очереди — столбцы `tel_*` в конце `cells.csv` и предупреждение о сумме лимитов CPU (12,25 при 12 у ВМ) вместо кода 2; у других профилей `--telemetry on` — код 2 до стенда |
| `make bench_telemetry [TELEMETRY_LABEL=...] [RESUME=1] [VARIANTS=...]` | уровень 5, трек 1 «Цена наблюдаемости» (~1 ч 25 мин, метка по умолчанию `baseline`: её первая попытка не снята, каталог удалён; основная — `baseline2`, код `68e14b6`, метка в `0f5dbfc`; change `track1-telemetry-cost`): проверка конфигураций до стенда (лимиты телеметрии против `docker-compose.yml`, слои Collector `validate` и `print-config`, `prometheus-lean.yml` построчно и `promtool`) — иначе код 2; стенд `mtusi-bench` профиля очереди и, в вариантах с телеметрией, сервисы телеметрии рабочего стенда; варианты `off`, `full`, `full-aa`, `head` (доля 0,1), `tail` (типовой tail sampling), `metrics` (30 с, `coarse`, отбор рядов), `balanced` × 3 повтора кругами, свежий стенд на прогон; открытая нагрузка `k6/telemetry.js` (окна 30 + 90 + 30 с) и редкие события: 500 вложения без объекта, недекодируемый JPEG, регистрация, медленные записи под блокировкой; выборка из Tempo, Loki и Prometheus (`telemetry_lookup.py`), сэмплер `cost`, размер volume; вариант не применён (записи о старте, слои) — отказ; `evidence/telemetry-cost/<метка>/` (`meta.json`, `runs.csv`, `components.csv`, `classes.csv`, `summary.md` с H1–H8 и B1–B5, SVG, `raw/`); `VARIANTS` — отладка. Рабочий стенд — `make stop`, гипотезы закоммичены раньше метки |
| `make bench_telemetry_quick [VARIANTS=...]` | то же короче (~20 мин): шесть вариантов без `full-aa`, один повтор, окна 10 + 30 + 15 с, метка `quick-telemetry-<время>`, в git не идёт; калибровка до гипотез; шаг защиты «для 5» — `VARIANTS=off,full,tail` (~10 мин) |
| `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
worker/__main__.py # python -m src.worker: early_stop.install("worker") до импорта → main(); неверные настройки — запись без значений и код 2; os._exit в конце
worker/main.py # worker обработки вложений: свои engine, S3 и потребитель; цикл соединений с паузой, задачи доставок (prefetch) под семафором concurrency, сервис и SqlAlchemyUnitOfWork на доставку, ack / requeue / drop по итогу, SIGTERM — начатые ждут в срок, закрытие клиентов одним gather; с лабы 6 — телеметрия messenger-worker, consumer span и histogram по исходу доставки (JobDeliveryOutcome, error — на исключении) после места конкуренции, закрытие SDK в окне gather; с change job-trace-propagation — consumer span дочерний к delivery.trace_context с link, итог handle — JobDeliveryResultDTO (атрибуты попытки и причины, messenger.job.time_to_ready), счётчики WorkerLoad «ждут места» и «заняты» вокруг семафора и observe_worker
worker/render.py # процесс обработки: python -m src.worker.render, лимиты первыми строками (RLIMIT_AS, RLIMIT_CPU, RLIMIT_CORE), затем Pillow; stdin — байты, stdout — строка JSON и варианты, коды 0/3/4/5
relay/__main__.py # python -m src.relay: early_stop.install("relay") до импорта → main(); неверные настройки — запись без значений и код 2; os._exit в конце
relay/main.py # relay: свои engine, SqlAlchemyUnitOfWork и издатель, цикл проходов с паузами, отказ брокера и PostgreSQL не роняет, SIGTERM — текущий шаг и выход 0; replay — разовая команда реестра, коды 0/3/1/2 (без SDK); с change job-trace-propagation — телеметрия messenger-relay после disarm, instrument_engine, QueueSnapshots и observe_queue (снимок после успешного прохода не чаще 5 с, отказ PostgreSQL — пропуск), закрытие SDK в окне gather 0,5 с
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, SqlAlchemyUnitOfWork на сервис и клиент 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), max_unfinished_jobs 250 (предел незавершённых заданий стенда; 0 — без него), [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 — без него); [telemetry] enabled, otlp_endpoint, environment, trace_sample_ratio 1 (доля корней в голове, change track1-telemetry-cost), metric_buckets default|coarse, metric_export_interval_seconds 15 (≤ 30), очереди и сроки SDK
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 # get_uow (SqlAlchemyUnitOfWork на запрос), request_deadline (общий срок JSON-запроса), фабрики сервисов на UowDep (с кэшем; вложения — ещё S3 и места), разбор Basic, текущая сессия по Bearer, пагинация; TraceContextDep — контекст W3C server span для задания загрузки (change job-trace-propagation)
errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; RETRY_AFTER — Retry-After у 429 занятых мест загрузки и предела заданий (UploadBacklogFull, 5 с); у 500 — X-Request-Id и X-Instance-Id
middlewares/ # X-Request-Id, X-Instance-Id и access-лог; с лабы 6 — server span и histogram http.server.request.duration (не для health), итоговая запись внутри span
core/
ports/uow.py # AbstractUnitOfWork: блок, commit, rollback, blocks_opened, правила вложенного входа и repo вне блока, UnitOfWorkError; реальные шаги — _open, _close, _commit, _rollback реализации; Repositories
ports/<domain>.py # Abstract<Domain>Repository: абстрактные методы, докстринг — контракт (None, False, условие перехода); импорты — только DTO, enum, src.utils
repos/<domain>.py # SqlAlchemy<Domain>Repository: одна атомарная операция на метод; chat_cache и attachment_object — модульные функции над клиентом
repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата
repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
repos/attachment_job.py # задание вложения: вставка, lock_job FOR UPDATE, start_attempt, return_to_queued своей попытки, finish_job; count_unfinished (предел принятой работы: сумма трёх count с LIMIT по частичным индексам); relay — lock_due_jobs (SKIP LOCKED, порядок срока), count_published, mark_published пакета, recover_expired_leases, has_published_before, reset_published_before; replay_job, list_failed; с change job-trace-propagation — колонки traceparent и tracestate во вставке и выборках, queue_snapshot (стадии scheduled / outbox / published / processing и LEAST трёх min(created_at) одним выражением по частичным индексам)
repos/attachment_job_replay.py # журнал replay: вставка записи аудита, чтение по заданию
repos/attachment_variant.py # варианты: вставка ON CONFLICT DO NOTHING по ключу эффекта, варианты вложения, один по имени
repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_queued (pending и непомеченная → queued RETURNING), mark_processing, return_to_queued, return_group_to_queued, replay_failed, lock_attachment (FOR NO KEY UPDATE), commit_ready, commit_failed, чтение одной и до 10; очистке staging — get_staging_candidates, lock_staging_candidate, clear_staging_key; уборщику — 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: staging_key <база>/staging/<id>/original, variant_key и parse_variant_key <база>/attachments/<id>/v<N>-<имя>, оригинал <база>/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, staging_prefix, is_own_staging_key, parse_staging_key, list_staging; variant_keys — ключи вариантов всех имён
repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой
services/<domain>.py # <Domain>Service(uow, …): логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем, require_member внутри чужого блока; отправка — ключ, сообщение и связи с вложениями одним блоком
services/attachment.py # AttachmentService(uow, cache, storage, slots): загрузка (проверки в первом блоке и там же предел заданий count_unfinished, 429 UploadBacklogFull → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT в staging тем же BytesIO → queued и задание, ответ 202; сбой до COMMIT или пропавшая строка — удаление объекта и 503; брокера в пути нет; место — до ответа), метаданные с вариантами, отдача потоком
services/attachment_processing.py # AttachmentProcessingService(uow, storage, renderer, stop): разбор сообщения, claim с арендой и бюджетом, GET staging и сверка, PUT оригинала, варианты через ImageRenderer, PUT вариантов, фиксация ready с fencing одной транзакцией; временные ошибки — queued со сроком (retry_delay, jitter) и ACK, постоянные — failed; JobOutcome; итог handle — JobDeliveryResultDTO (исход, попытка, причина, код, время до ready без replay)
services/attachment_relay.py # AttachmentRelayService(uow, publisher): проход — истёкшие аренды, потерянные сообщения, публикация с подтверждением и отметка пакета внутри транзакции SKIP LOCKED, предел опубликованных; RelayPassDTO; элементы JobPublicationDTO (publication: попытка, replay, причина, контекст задания), queue_snapshot — один блок
services/attachment_replay.py # AttachmentReplayService(uow): реестр failed, replay одной транзакцией с аудитом и новым бюджетом, отказы not_found / already_ready / not_failed / source_gone; ReplayPassDTO
services/attachment_cleanup.py # AttachmentCleanupService(uow, storage): проход уборщика — кандидаты keyset, каждая строка в два шага (remove_stale_pending): блокировка и пометка (commit) → блокировка, DELETE объекта и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO; clean_staging — очистка staging ready и failed по сроку под FOR NO KEY UPDATE SKIP LOCKED, StagingCleanupPassDTO
services/attachment_reconcile.py # AttachmentReconcileService(uow, storage): сверка bucket и БД — S3 → БД (страницы списка, выборка на страницу, множество ключей), БД → S3 (keyset ready; ключ строки вне префикса вложений — чужой объект без HEAD; строка с ключом <id>/original другого вложения — HEAD её объекта, verify W2), зависшие, перепроверка в БД и HEAD (bucket — probe), сигнал — перед каждым вызовом хранилища, предел изменений, действия с apply (зависшие шагом уборщика → объекты без строки → объекты staging без строки → пометки → снятия); журнал Found / Fixed / Finished; ReconcilePassDTO. С change pipeline-reliability: шаг _list_staging, orphan_staging, listed_staging. С change track2-reconcile-cost: strategy head (выборка строки на объект, HEAD на строку, без множества), deep (GET и SHA-256 потоком, checksum_mismatch; «оригинал вернулся» — тот же SHA-256), предел скорости после каждого вызова S3 (_pace, куски 0,2 с; сигнал прекращает паузу, останавливает следующий check_stop — verify W1), ранний отказ по пределу (unchecked), счёт сеансов — uow.blocks_opened, стоимость в итоге (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), 429 предела заданий (UploadBacklogFull), 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 в каждой записи; с лабы 6 — хуки телеметрии (export_to_telemetry, add_trace_fields: trace_id и span_id активного span) в обеих цепочках и RateLimitFilter записей opentelemetry.* (одна в минуту на логгер); SDK не импортирует
telemetry/ # change otel-telemetry и job-trace-propagation (telemetry.md): core.py — только opentelemetry-api: start (SDK загружает модуль sdk.py, ресурс из четырёх атрибутов), remove_otel_environment, begin_shutdown / wait_closed / shutdown (daemon-потоки и срок), child_span (правило корня, ошибка — класс без текста), server_span / finish_request (span SERVER и histogram http.server.request.duration), PROPAGATOR (W3C без baggage), current_trace_context, remote_context, Exporters (in-memory для тестов); sdk.py — единственный импорт SDK, экспортёра и requests: провайдеры только из [telemetry], ParentBased(ALWAYS_ON), cumulative, View границ трёх histogram, без exemplars и atexit, otlp_metric_reader / otlp_span_exporter / otlp_log_exporter; с change slo-alerts — сначала MeterProvider, затем процессоры и экспортёры span и журнала с ним внутри _internal_metrics (внутренние метрики SDK otel.sdk.*, переменная SDK только на время сборки), гистограммы SDK — DropAggregation; messaging.py — producer_span (PRODUCER publish <очередь> под сохранённым контекстом, заголовки), consumer_span (CONSUMER дочерний к контексту сообщения с link, без него — корень) и JobObservation (итог доставки: атрибуты, messenger.job.duration и time_to_ready); metrics.py — observe_pool (db.client.connection.* по текущему пулу engine), WorkerLoad / observe_worker, observe_queue (gauge по последнему снимку, старше 30 с — ничего); container.py — cgroup v2 (cpu.stat, memory.current, cpu.max, memory.max); db.py — instrument_engine (слушатели before/after_cursor_execute, handle_error, метрики пула), commit_span; logs.py — экспорт записи structlog в логгер SDK и trace_ids, install_log_hooks; setup.py — start_process_telemetry(<service.name>, cgroup_root=…): OTEL_* с warning, провайдеры, метрики контейнера (нет cgroup — одна запись), хуки; с change track1-telemetry-cost — sdk.sampler (доля 1 — ParentBased(ALWAYS_ON), иначе ParentBased(TraceIdRatioBased)), границы по набору metric_buckets, TracerProvider с meter_provider и Tracer в окне внутренних метрик (otel.sdk.span.started; otel.sdk.span.live — DropAggregation), setup.startup_fields — поля телеметрии записи о старте API, worker и relay
password.py # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username
broker/client.py # aio-pika: JobPublisher relay (соединение лениво, publish_many с confirm и общим сроком, ready_messages, сброс после любой ошибки), JobConsumer worker (своё соединение, prefetch), JobDelivery, queue_name <база>.attachment.process.v1; с change job-trace-propagation — span producer и заголовки traceparent / tracestate в _publish_one, JobDelivery.trace_context из заголовков (trace_context_from_headers)
render/client.py # ImageRenderer: процесс обработки на задание, окружение без секретов, срок и kill в finally, разбор вывода, коды в ImageRejected / RenderInterrupted; span render attachment variants (размер входа, исход, код выхода, пик)
upload_slots.py # UploadSlots (asyncio.Semaphore по порядку прихода, счётчик ожидающих, срок ожидания; slot() — UploadsBusy или ожидание в мс, место в finally) и глобал upload_slots из [uploads]; импортирует только dependencies.py
db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping; _ping_once — проверка соединения при выдаче одним обменом; CountingQueuePool (poolclass engine, change job-trace-propagation): connect() со счётом ожидающих и отказов по сроку, pending(), timeouts()
db/session.py # глобалы engine и session_factory процесса API
db/scope.py # session_scope(factory, timeout_seconds): сессия на блок, срок вместе с откатом, отмена и отказ БД → invalidate, warning, ServiceUnavailable; deadline_scope — общий срок JSON-запроса без сессии, внутри него таймер блока той же задачи не взводится
db/uow.py # SqlAlchemyUnitOfWork(factory, timeout_seconds) поверх session_scope, repo на блок; импортируют только точки входа; span COMMIT в _commit
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: срок на команду, отказ — промах и пропуск; span GET / SET без ключа с messenger.cache.result
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); span S3.<Операция> в _call без ключа (нет объекта у HEAD и DELETE — исход missing, не ошибка)
s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan
schemas/
jobs/attachment.py # AttachmentJobMessage (pydantic по contracts/jobs.schema.json) и build_job_body
dataclasses/<domain>.py # DTO между repo → service → api
enums/<domain>.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType, ReconcileFinding, ReconcileAction, ReconcileStrategy (batch, head), JobDeliveryOutcome (исход доставки worker → JobOutcome)
utils/
image_variants.py # render_variants: thumbnail, crop, optimized из одного декодирования, fit_size вниз своим расчётом, EXIF orientation, alpha на белый у JPEG, InvalidImage; импортирует Pillow, поэтому только src/worker/render.py
constants.py # лимиты контракта (с лабы 4 — 10 MiB, 40 млн пикселей, filename, 10 вложений), размер страницы, префиксы путей, имя bucket S3, разделитель и части ключа объекта, keep-alive клиента S3
image.py # inspect_image: структурная проверка PNG/JPEG без декодирования пикселей (stdlib), тип, размеры, UnsupportedImage / DamagedImage / TooManyPixels; у JPEG ещё таблицы DQT/DHT, компоненты и полоса скана, определённые к скану таблицы (0 и 1 Хаффмана непрогрессивного кадра — необязательны), данные скана Хаффмана — условия отказа djpeg
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/backlog_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): разновидности, подмена размеров, без таблиц, изменённый заголовок скана и пустой скан (jpeg_undecodable); обрезка и хвост
test_attachment_processing.py # спек attachment-processing по HTTP: готовность, thumbnail, варианты, failed от недекодируемого JPEG
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, «узкий по заданиям» с BACKLOG_ENV → FAULT_BACKLOG_BASE_URL / FAULT_BACKLOG_ENV; у первых четырёх предел заданий выключен, NO_BACKLOG_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 стенда отказов: relay (опрос 0,2 с, restart "no"), worker и уборщик с короткими сроками change pipeline-reliability, без публикации портов (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)
service-tests/ # быстрые тесты сервисов (вне образа и вне student-tests), service-tests.md
pytest.ini # настройки pytest этого каталога: pyproject.toml здесь не применяется
builders.py # DTO для тестов: явное время, PASSWORD_HASH по виду CHECK
repo_contract.py # один набор условий repo: на фейке и на настоящем SQL
fakes/ # FakeDatabase (таблицы, снимок, events, held, fail_on), FakeUnitOfWork на базовом классе порта, фейки девяти repo, FakeCache, FakeObjectStorage, FakeJobPublisher, FakeImageRenderer
unit/ # make service_test: test_unit_of_work, test_architecture, test_repo_contract, test_<service> на каждый сервис, test_worker_deliveries (одновременные доставки), test_telemetry (in-memory экспортёры SDK: выключено, OTEL_*, ресурс, middleware, журнал, правило корня, Valkey и S3, закрытие со сроком, исход доставки; с change job-trace-propagation — контекст загрузки, span producer и consumer, невыбранный контекст, время до готовности, пул, насыщение, очередь, cgroup, ресурс relay, заголовки доставки, модули SDK без телеметрии в отдельном интерпретаторе); conftest подставляет поля settings
db/ # make service_test_db: conftest (временная база, TcpProxy, «тесный» API окружением до импорта src), test_uow, test_repo_contract_sql, test_request_flow, test_telemetry_db (span запросов и COMMIT под родителем, без родителя — ни одного), test_pool_counts (CountingQueuePool: ожидающий и отказ по сроку, класс после dispose)
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, без сети); режим queue — scan с mp, mq и psql \watch заданий; режим cost (telemetry) — scan и строки mp, без сети
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
overload.py # профиль queue без docker (change track1-queue-overload): план кругами, разбор строк q/qs/qv, jobs, mq, mp и журналов, жизни контейнера, строка cells.csv и timeline.csv, пометки, вердикты H1–H9, правило рекомендации, summary.md и SVG; --selftest
make_images.py # файлы классов s, m, lj, lp профиля queue и bad профиля telemetry (s с 12 битами точности в SOF: 202, затем failed): только в контейнере mtusi-bench-images на образе стенда (Pillow образа, --network none), зерно из аргумента, JSON с размерами и SHA-256, больше лимита контракта — код 1
telemetry_cost.py # профиль telemetry без docker (change track1-telemetry-cost): таблица вариантов и override прогона, план кругами, ожидание отправок, проверки слоя Collector (print-config) и копии Prometheus (построчно вне bench-lean), записи о старте и слои, разбор строк k6 t и сэмплера cost, компоненты, строки runs.csv / components.csv / classes.csv, потери по звеньям, пометки, правило шума, биномиальный интервал, вердикты H1–H8 и B1–B5, summary.md и четыре SVG; --selftest
telemetry_lookup.py # выборка профиля telemetry: только в контейнере mtusi-bench-lookup на образе стенда (stdlib urllib, сеть mtusi-bench-telemetry); wait-ready и collect — трассы по request_id и цепочки загрузок (TraceQL), записи журнала и переход к трассе, счётчики Prometheus, status/tsdb и config, квантили buckets против журнала; результат, равный пределу, — отказ
telemetry.compose.yml # второй -f при включённой телеметрии стенда: TELEMETRY__ENABLED true и адрес Collector у api, worker, relay
otel/ # слои вариантов профиля telemetry (не infra/otel/): tail-typical.yaml и tail-balanced.yaml — второй --config Collector (только tail_sampling и процессоры pipeline трасс), prometheus-lean.yml — копия prometheus.yml с блоками # bench-lean (отбор собственных рядов хранилищ)
queue.compose.yml # третий -f только профиля queue: плагин метрик брокера и статистика в секунду (bench/rabbitmq/), restart: unless-stopped у worker
rabbitmq/ # enabled_plugins и 91-bench.conf профиля queue
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; с change track1-telemetry-cost — otel-collector, prometheus, loki, tempo (mtusi-bench-<сервис>, лимиты BENCH_COLLECTOR_* / _PROMETHEUS_* / _LOKI_* / _TEMPO_* без swap, сеть mtusi-bench-telemetry; запускают профиль telemetry и TELEMETRY=on), grafana без порта и не запускается
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 и queue: constant-arrival-rate скачиваний, записи и чтения истории, строка bg на запрос, остановка SIGINT), queue (окна constant-arrival-rate загрузок, VU заранее, ответ не повторяется, строка q на загрузку; WARM — разогрев) и queue_sweep (метаданные каждого принятого вложения, SHA-256 выборки, строки qs и qv), telemetry (профиль цены телеметрии: девять классов constant-arrival-rate — чтение, запись, /users/me, карточка, скачивание, загрузка s и bad, вложение без объекта, регистрация; строка t с X-Request-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; 5c3e1f0a9b7d — attachments.lost_at (NULL, SET LOCAL lock_timeout); c7e2f1a04b56 — attempt_base и attachment_job_replays; d3f9a6b2c1e7 — индексы outbox, аренды и очистки staging CONCURRENTLY; e4b8c2d17f90 — attachment_jobs.traceparent и tracestate (NULL, CHECK NOT VALID, SET LOCAL lock_timeout)
infra/ # конфигурации сервисов стенда; README.md — skeleton
valkey/valkey.conf # лимит памяти и LRU, persistence выключен
rabbitmq/rabbitmq.conf # предел памяти брокера 400 МиБ: лимит контейнера он не видит
otel/collector.yaml # Collector contrib (change otel-telemetry): OTLP HTTP :4318, memory_limiter и batch, экспортёры prometheus :8889, otlp_http/loki, otlp_http/tempo, свои метрики :8888; с change slo-alerts — приёмник prometheus/haproxy (haproxy:8404/metrics, frontend и backend, отбор имён), batch/logs 256, очереди экспорта по байтам 16 / 8 МиБ и повторы 30 с, metric_expiration 1m
otel/prometheus/prometheus.yml # scrape Collector (honor_labels), Collector, Loki, Tempo и себя раз в 15 с; срок и объём — флаги compose; с change slo-alerts — rule_files, protobuf первым у otel-collector-exporter (время начала рядов), глобально прежний текстовый список
otel/loki/loki.yaml # монолит filesystem, schema v13, compactor, срок 168h, без отчётов
otel/tempo/tempo.yaml # монолит 3.1, OTLP HTTP :4318, local, block_retention 168h у scheduler и worker, без отчётов
otel/grafana/ # datasources.yaml (uid prometheus, loki, tempo; лог ↔ трасса; с change slo-alerts — manageAlerts у Prometheus), dashboards.yaml (папка Messenger, без правок из UI), dashboards/messenger-overview.json (панели уровня 3; с change job-trace-propagation — p99 и строки «Pipeline» и «Saturation» уровня 4; с change slo-alerts — строки «SLO and alerts» сверху, «Load balancer» и «Telemetry pipeline», id с 25)
otel/prometheus/rules.yml # change slo-alerts: группы messenger-sli (окна 2 мин, telemetry:lost_items:total), messenger-slo (приращения SLI за 5 мин), messenger-alerts и telemetry-alerts — семь оповещений с for, severity, summary, description, runbook_url
otel/prometheus/rules.test.yml # promtool test rules: срабатывание, порог, без трафика, снятие, правила записи (make alerts_test, в контейнер не монтируется)
otel/runbooks/ # change slo-alerts: <оповещение>.md — значение, панели, диагностика по сохранённым наблюдениям (PromQL, LogQL, TraceQL), действия, восстановление, связанные
rollback/broker.compose.yml # override отката реплик на образ до pipeline-reliability (прежний код публикует сам): адрес и пароль брокера только на время отката
s3/bootstrap.sh # bootstrap S3 (ещё пользователь worker: чтение и запись объектов; сервис 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 (с change slo-alerts — ещё /metrics экспортёра Prometheus для Collector), 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 с); ожидание хранилищ — up --wait --no-recreate (Compose 5.4 иначе пересоздаёт контейнеры, чьи образы скачивались при первом up, и s3-bootstrap не стартует); 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-lab6: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), rabbitmq, migrate, s3-bootstrap, relay и worker (пароль брокера только у них и rabbitmq), api × API_REPLICAS без портов (sysctls: буфер приёма сокетов до 512 KiB), cleaner (уборщик: точка входа python -m src.cleaner, пул 1, ключи S3_CLEANER_*, без healthcheck), haproxy — единственный порт API; с лабы 6 — otel-collector (сети default и telemetry), prometheus, loki, tempo, grafana (сеть telemetry, наружу — только Grafana на 127.0.0.1:GRAFANA_OUT_PORT), x-telemetry-env у api и worker, healthcheck брокера через gosu rabbitmq; адреса и порты из .env, volumes postgres_data, s3_data, rabbitmq_data, prometheus_data, loki_data, tempo_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env, x-s3-api-keys-env)
.dockerignore
config_example.toml, .env.example
evidence/broker/ # change async-attachments: stand.md (driver.py broker-check), isolated.md (очередь временной базы)
evidence/worker/ # change async-attachments: process.md (driver.py worker-process), logs.md (журнал задания); memory.md (driver.py worker-memory)
evidence/attachments/ # change async-attachments: defense.md (driver.py defense-scenario); 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 во время прохода); по замечанию ревьюера: jpeg-structure.md (варианты JPEG — прежняя и новая проверка, Pillow, djpeg; регрессия на 301 JPEG; время; красный и зелёный прогоны test_undecodable_jpeg)
evidence/s3/ # privacy.md — make s3_check на текущем коде; 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/telemetry/ # change otel-telemetry: budget.md (пики и лимиты сервисов телеметрии, реплик и worker с телеметрией и без); на commit 15ea156 change slo-alerts переснято: collector-outage.md (driver.py telemetry-outage), trace-chain.md (driver.py trace-chain), раздел change slo-alerts в budget.md; на ef60b47 (правки verify slo-alerts): backend-outage.md (driver.py backend-outage, с панелью потерь); на 4a2f9c9 (тот же код, гонка relay_pass_records в драйвере): check.md (driver.py telemetry-check, с метриками LB, новыми панелями и панелью потерь на тихом стенде); на 72cfa9a (change job-trace-propagation): queue-snapshot.md (EXPLAIN снимка очереди), раздел change в budget.md (relay с SDK, уборщик после ленивого импорта)
evidence/migrations/ # change job-trace-propagation: job-trace-context.md — ревизия e4b8c2d17f90 (временная база: с нуля, повтор, откат, CHECK, lock_timeout; --sql; рабочий стенд: откат реплик на ff0073e с MIGRATE=0, ревизия до и после make rolling_update)
evidence/stand/ # change otel-telemetry: from-scratch.md (driver.py stand-from-scratch --runs 2)
evidence/alerts/ # change slo-alerts (commit ef60b47, правки verify; первая съёмка — 15ea156): rules-test.md (make alerts_test и контроли), check.md (driver.py alerts-check); там же — evidence/telemetry/backend-outage.md (driver.py backend-outage) и раздел change в budget.md (15ea156)
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга; freeze-sessions.md — change unit-of-work: сессии и журнал пула после заморозки PostgreSQL (driver.py freeze-sessions и freeze-lb)
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/ # change unit-of-work: service-tests.md (make service_test и service_test_db, таблица регрессий); выводы make test_isolated (test-isolated.md), make student_test через LB (student-test-lb.md) и make failure_checks (failure-checks.md) для REPORT.md, secrets.md; файлы этих проверок лаб 3 и 4 — в их репозиториях
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/queue/<метка>/ # результаты make bench_queue (change track1-queue-overload): meta.json (классы, план, окна, app_env по конфигурациям), cells.csv, timeline.csv, summary.md (H1–H9, рекомендация), SVG, raw/ — итоги k6
evidence/telemetry-cost/<метка>/ # результаты make bench_telemetry (change track1-telemetry-cost): meta.json (варианты с SHA-256 слоёв, план, интенсивности, окна, блокировки, app_env по вариантам, stand и stand_telemetry, limits_by_mode), runs.csv, components.csv, classes.csv, summary.md (H1–H8, B1–B5), cpu-by-group.svg, latency-light.svg, ingest.svg, traces-by-class.svg, raw/ — итоги k6 и выборки
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/bench/unit-of-work-*/ # change unit-of-work, профиль quick с именной меткой (идёт в git): before и aa на b2fb88f, after на 6ba74b1
evidence/rollout/unit-of-work*/ # change unit-of-work: unit-of-work (замена с Profile.rollout_from), unit-of-work-previous (--from b2fb88f: CPU на запрос старых и новых реплик)
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md; unit-of-work-before__unit-of-work-after.md и unit-of-work-aa__unit-of-work-after.md — цена шага от двух меток одного кода
.github/workflows/application.yml # свой CI job (CONTRIBUTING.md, «CI»; contracts.yml — skeleton): checkout commit прогона (адрес Gitea литералом: github.server_url — внутренний http://gitea:3000, из job не резолвится; по той же причине contracts.yml на этом раннере падает на actions/checkout), сборка и стенд под проектом mtusi-lab6-safronov-ci-<run_id>, job подключается к сети стенда, готовность — обе реплики через LB, make check / test, аноним в S3 — 403, make validate, make student_test, test-persistence, test-failover stop и kill, уборка при любом исходе; без s3_check, test_isolated и failure_checks (порты хоста). Раннер Gitea (act_runner) запускает job в контейнере на том же Docker, что стенд
.github/ci/compose.yml # override стенда в CI: конфиги — configs из переменных окружения вместо bind mount (файлов job нет на хосте раннера), без портов на хосте, образ API с тегом прогона; у Prometheus, Loki и Tempo — только именованный volume, у Collector и Grafana — ни одного (tmpfs Grafana остаётся)
.github/ci/stand-env.sh # «.» в шагах job: содержимое конфигов в CI_* для configs (с переводом строки в конце: без него HAProxy конфиг не принимает), wait_replicas — /health/ready 200 от API_REPLICAS разных реплик через LB за 60 с
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
```
`evidence/` в лабу 6 не переносился: здесь только снятое на её стенде, а
файлы и метки лаб 3–5 остались в репозиториях `mtusi2026lab3-safronov`,
`mtusi2026lab4-safronov` и `mtusi2026lab5-safronov`. Записи карты о changes
лаб 3–5 говорят, что
такой каталог содержит, когда он снят: каталоги появляются заново по мере
changes, а файлы исключений сверки покрытия снимаются заново на стенде
текущей лабы (раздел «Переход в следующую лабу»).
## Архитектура в двух словах
- Поток однонаправленный. Роутер (зависимости, модели API) → сервис
(логика, проверки доступа, id и время, логи) → единица работы и repo за портами
`src/core/ports/` (одна атомарная операция над хранилищем, отдаёт DTO) →
PostgreSQL через `SqlAlchemyUnitOfWork` (`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/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/`, `service-tests/`, `migrations/`, `alembic.ini`,
`Dockerfile`, `docker-compose.yml`, `infra/valkey/`,
`infra/haproxy/`, `infra/s3/`, `infra/rabbitmq/`, `infra/rollback/` и
конфигурации наблюдаемости лабы 6 в `infra/` (без `infra/README.md` и
`infra/otel/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`, свой CI
job `.github/workflows/application.yml` и `.github/ci/` (остальное в
`.github/` — из нового skeleton). В job поменять номер лабы в префиксе
проекта `mtusi-lab6-safronov-ci-` (и в шаге уборки хвостов), в
override — новые сервисы и конфиги нового стенда; Actions в новом fork
включить в его настройках.
- Сливать, а не копировать поверх: `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`; с лабы 5 —
`driver.py --port <LB> broker-check` (`--require-test-queue` после
`make test_isolated`) → `evidence/broker/stand.md` и
`evidence/broker/isolated.md`, `make bench_uploads` →
`evidence/uploads/baseline/summary.md` (~50 мин), `make bench_queue` →
`evidence/queue/<метка>/summary.md` (~2 ч 10 мин; метку называет
исключение `queue-overload`) — всего 10 файлов при переносе 5 → 6
(`QUESTIONS.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`, включая использование ИИ.