937 lines
177 KiB
Markdown
937 lines
177 KiB
Markdown
# 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`, включая использование ИИ.
|