feat: add replicated messenger and reproducible lab3 stand

This commit is contained in:
2026-10-15 13:43:39 +03:00
parent 0ab3a341aa
commit 84dd7fec0a
106 changed files with 17235 additions and 24 deletions
+147
View File
@@ -0,0 +1,147 @@
# Правила команд Codex для проекта (execpolicy, Starlark).
#
# Действуют на команды, которые Codex запускает вне sandbox (docker, сеть):
# allow — без вопроса;
# prompt — спросить пользователя перед каждым запуском;
# forbidden — не запускать никогда.
# Несколько совпавших правил — побеждает самое строгое (forbidden →
# prompt → allow). pattern — точный префикс аргументов команды; список в
# позиции — варианты. match / not_match — примеры, которые Codex
# проверяет при загрузке правил.
#
# Файл загружается, только если проект доверенный (слой .codex/ проекта
# trusted). После правки — перезапустить Codex. Проверка правила:
# codex execpolicy check --pretty --rules .codex/rules/messenger.rules -- git push
#
# Источник запретов — корневой AGENTS.md, раздел 2 «Нельзя»; правила их
# дублируют на уровне команд, но не заменяют.
# --- git: только смотреть; изменения — по просьбе пользователя -------------
prefix_rule(
pattern = ["git", ["status", "diff", "log", "show", "rev-parse", "ls-files"]],
decision = "allow",
justification = "Read-only git commands are always fine.",
match = ["git status", "git diff --stat", "git log --oneline -5"],
not_match = ["git commit -m x"],
)
prefix_rule(
pattern = ["git", ["commit", "checkout", "switch", "reset", "stash", "rebase", "merge", "restore", "tag", "branch"]],
decision = "prompt",
justification = "AGENTS.md: git changes only when the user asked for them (commit message in English, conventional style).",
match = ["git commit -m 'feat: x'", "git reset --hard", "git checkout main"],
not_match = ["git status"],
)
prefix_rule(
pattern = ["git", ["push", "clean"]],
decision = "forbidden",
justification = "Never push or clean the working tree: the user does it; git clean would delete evidence and local files.",
match = ["git push", "git push origin main", "git clean -fdx"],
)
# --- данные стендов: удаление только с согласия -----------------------------
prefix_rule(
pattern = ["make", "wipe"],
decision = "prompt",
justification = "make wipe deletes the working stand volume (all data). Ask the user first (AGENTS.md, section 2, item 8).",
match = ["make wipe"],
)
prefix_rule(
pattern = ["docker", "compose", "down", "-v"],
decision = "prompt",
justification = "down -v deletes volumes. The bench and test stands remove their own projects themselves; for the working stand ask the user.",
match = ["docker compose down -v", "docker compose down -v --remove-orphans"],
not_match = ["docker compose down"],
)
prefix_rule(
pattern = ["docker", "volume", ["rm", "prune"]],
decision = "prompt",
justification = "Deleting volumes deletes data: only bench leftovers (vlad-bench*) and only with the user's consent.",
match = ["docker volume rm vlad-bench_pgdata", "docker volume prune -f"],
)
prefix_rule(
pattern = ["docker", ["rm", "kill", "stop", "pause"]],
decision = "prompt",
justification = "Only own containers (vladimirceva-lab3*, vlad-bench*); never containers of other projects.",
match = ["docker rm -f vlad-bench-gen", "docker stop some-container"],
)
prefix_rule(
pattern = ["docker", ["system", "builder", "image", "container", "network"], "prune"],
decision = "forbidden",
justification = "Prune touches every project on this machine. Remove own leftovers by name instead (bench/AGENTS.md).",
match = ["docker system prune -af", "docker image prune -a"],
)
# --- процессы: не убивать по порту вслепую ------------------------------------
prefix_rule(
pattern = [["kill", "pkill", "killall"]],
decision = "prompt",
justification = "Kill only a PID whose command is `python -m src` (AGENTS.md, section 10). A published port on macOS belongs to com.docker.backend: killing it stops Docker Desktop.",
match = ["kill 12345", "pkill -f uvicorn"],
)
prefix_rule(
pattern = ["rm", ["-rf", "-fr", "-r"]],
decision = "prompt",
justification = "Recursive delete: label folders in evidence/ are removed only with the user's consent (bench/AGENTS.md).",
match = ["rm -rf evidence/scaling/quick-x"],
)
# --- проект: проверки, стенд, замеры — без вопроса ----------------------------
prefix_rule(
pattern = [
"make",
[
"install", "lint", "fmt", "check", "validate", "test", "load",
"test-persistence", "test-failover", "student-test", "test-isolated",
"failure-checks", "requirements", "requirements-check", "env",
"docker-build", "up", "stop", "down", "logs", "db-up", "run",
"migrate-local", "replicas", "instances", "lb-stats",
"failover-each", "rolling-update",
"bench-failover", "bench-failover-quick", "bench-rollout",
"bench-rollout-quick", "bench-scaling", "bench-scaling-quick",
"bench-compare", "bench-plots",
],
],
decision = "allow",
justification = "Project targets: checks, the working stand without deleting data, bench profiles (bench/RUNBOOK.md).",
match = ["make lint", "make test-isolated", "make bench-scaling SERIES=a", "make failover-each STOP_MODE=kill"],
not_match = ["make wipe"],
)
prefix_rule(
pattern = ["docker", ["ps", "info", "version", "inspect", "logs", "images", "events", "exec", "cp", "build", "tag", "run", "start", "unpause"]],
decision = "allow",
justification = "Inspecting and running own stand containers; deletion is covered by stricter rules above.",
match = ["docker ps -a", "docker info", "docker logs -t vlad-bench-lb"],
)
prefix_rule(
pattern = ["docker", "compose"],
decision = "allow",
justification = "Compose of this project; down -v is prompted by the stricter rule above.",
match = ["docker compose ps", "docker compose logs api"],
)
prefix_rule(
pattern = ["uv", ["run", "sync", "lock", "export"]],
decision = "allow",
justification = "Project environment from uv.lock; new dependencies still need the user's consent (AGENTS.md, section 2, item 11).",
match = ["uv run pytest", "uv sync", "uv run python bench/analysis.py --selftest"],
)
prefix_rule(
pattern = [["python3", "python"], ["scripts/lab3.py", "student-tests/stand.py", "tests/smoke.py", "tests/resilience.py", "scripts/check_contract.py"]],
decision = "allow",
justification = "Project scripts on the host Python (stdlib only).",
match = ["python3 scripts/lab3.py instances", "python3 student-tests/stand.py isolated"],
)
+14
View File
@@ -18,3 +18,17 @@ __pycache__
node_modules
evidence
.DS_Store
.codex
.agents
tests
student-tests
bench
contracts
infra
scripts
**/AGENTS.md
**/__pycache__
**/*.pyc
**/.DS_Store
*.md
**/*.md
+13 -1
View File
@@ -1,6 +1,7 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
APP_HOST=0.0.0.0
# Host process (make run); the container binds 0.0.0.0 in Dockerfile.
APP_HOST=127.0.0.1
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
@@ -11,3 +12,14 @@ SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
# Compose and make run. make env fills the empty passwords locally.
HOST_PORT=8080
POSTGRES_USER=messenger
POSTGRES_DB=messenger
POSTGRES_PASSWORD=
POSTGRES_HOST_PORT=5433
VALKEY_PASSWORD=
VALKEY_HOST_PORT=6380
LOG_LEVEL=INFO
SHUTDOWN_TIMEOUT=5
+5
View File
@@ -28,5 +28,10 @@ coverage/
.DS_Store
.idea/
.vscode/
# Temporary benchmark state and self-check results are not submission evidence.
bench/.bench.lock
evidence/failover/quick-*/
evidence/rollout/quick-*/
evidence/scaling/quick-*/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
+354
View File
@@ -0,0 +1,354 @@
# AGENTS.md — мессенджер MTUSI, лабораторная 3
REST API мессенджера (пользователи, чаты, история сообщений): реплики
API за HAProxy, PostgreSQL — источник истины (данные, сессии, ключи
идемпотентности), Valkey — общий кэш карточек чатов. Код перенесён из
лабы 2 и переведён на лабу 3: `X-Instance-Id` в каждом ответе,
обязательный `Idempotency-Key` при отправке сообщения, ≥ 2
взаимозаменяемые реплики, отказ реплики, поочерёдная замена. Цель —
оценка **«5»**: уровни 3 и 4 из `README.md` и трек 1 уровня 5 «Цена
масштабирования».
**Состояние (14 октября 2026).** Уровень 3 и всё, что в уровне 4 не
требует нагрузки, реализовано и проверено; доказательства — `evidence/`,
отчёт — `REPORT.md`. Нагрузочный стенд (`bench/`) готов и проверен
самопроверками (`*-quick`), но замеры под нагрузкой ещё не сняты:
отказ каждой реплики и замена под нагрузкой (уровень 4), серии трека 1
и улучшение. **Следующая работа — `bench/RUNBOOK.md`** (на устройстве,
где идут замеры); в `REPORT.md` их места помечены `TODO (Codex)`.
Гипотезы трека 1 записаны в `REPORT.md` до замеров.
Стек: Python 3.13, FastAPI + Starlette 1.x, uvicorn, pydantic v2,
SQLAlchemy Core 2.1 + asyncpg, alembic, argon2-cffi, redis-py;
PostgreSQL 18.6, Valkey 9.1.2, HAProxy 3.4; uv (локально), pip +
`requirements.txt` с хешами (в образе), pytest + httpx.
## 1. Где инструкции и как их читать
Codex сам загружает `AGENTS.md` от корня репозитория до рабочего
каталога (вместе — не больше 32 КиБ). Правила слоёв лежат глубже,
поэтому **перед правкой файла прочитай каждый `AGENTS.md` на пути к
нему** (`cat`), даже если задача «на одну строку».
| Файл | Когда читать |
|---|---|
| `AGENTS.md` (этот) | всегда: запреты, команды, карта, Definition of Done |
| `src/AGENTS.md` | любая правка в `src/`: слои, импорты, ошибки, конфиг, точка входа, логи, время |
| `src/api/AGENTS.md` | роуты, схемы, middleware, вход и Bearer, `X-Instance-Id`, `Idempotency-Key` |
| `src/services/AGENTS.md` | бизнес-правила, пароли и сессии, отправка с ключом |
| `src/storage/AGENTS.md` | PostgreSQL: транзакции, гонки, ключ идемпотентности; кэш Valkey |
| `migrations/AGENTS.md` | схема БД, новые ревизии, совместимость с работающей версией |
| `infra/AGENTS.md` | `Dockerfile`, `compose.yaml`, HAProxy и цепочка таймаутов, `scripts/*.sh`, `scripts/lab3.py` |
| `student-tests/AGENTS.md` | собственные тесты, отдельные стенды, проверки отказов |
| `evidence/AGENTS.md` | доказательства для `REPORT.md` |
| `bench/AGENTS.md` | нагрузочный стенд: методика, честность результатов |
| `bench/RUNBOOK.md` | замеры уровня 4 и трека 1 по шагам; читать перед любым `make bench-*` |
Кроме `AGENTS.md`, Codex читает из проекта:
- **правила команд** `.codex/rules/messenger.rules` (Starlark,
`prefix_rule`): что запускается вне sandbox без вопроса (`make …`
проекта, `docker ps/logs/compose`, `uv run`), что требует
подтверждения (git-изменения, `make wipe`, `down -v`, удаление
контейнеров и volume, `kill`, `rm -r`) и что запрещено (`git push`,
`git clean`, `docker … prune`). Загружаются, только если проект
**доверенный** (trusted); после правки — перезапустить Codex;
проверка — `codex execpolicy check --pretty --rules
.codex/rules/messenger.rules -- <команда>`. Правила дублируют раздел 2,
но не заменяют его;
- **навыки** `.agents/skills/*/SKILL.md`: `lab3-bench` — замеры по
`bench/RUNBOOK.md`, `messenger-stand` — работа со стендом. Codex
выбирает их по описанию или по `$имя`.
Конфликт: более глубокий файл уточняет корневой, но не отменяет
раздел 2. Прямая просьба пользователя в чате важнее этих файлов, кроме
пунктов раздела 2, помеченных «спросить»: там сначала переспроси.
## 2. Нельзя
1. **Менять skeleton преподавателя** (спросить): `contracts/`, `tests/`,
`scripts/` (кроме своих `restart.sh`, `stop-one.sh`,
`rolling-update.sh`, `lab3.py`), `lab.json`, `README.md`, `COURSE.md`,
`CONTRIBUTING.md`, `MAINTAINERS.md`, `Dockerfile.example`,
`compose.example.yaml`, `infra/README.md`, `requirements-dev.txt`,
`evidence/README.md`, `.github/`, верх `Makefile` до строки `=====`
(цели `help`/`check`/`validate`/`test`/`load`/`test-persistence`/
`test-failover`). Публичный тест упал — чиним приложение.
2. **Подгонять тесты под код**: ослаблять `assert`, менять ожидаемый
статус, ставить `skip`/`xfail`, удалять тест, чтобы прогон позеленел.
3. **Состояние в памяти процесса, от которого зависит корректность**:
сессии, данные и ключи идемпотентности — только PostgreSQL; Valkey —
только кэш неизменяемой карточки чата. `--workers`, gunicorn,
`reload` в образе: масштабирование — числом реплик. Sticky session
(cookie, stick-table) в HAProxy.
4. **Порты реплик наружу и `container_name` у `api`**: API — только
через HAProxy (рубрика «4»).
5. **Файлы конфигурации приложения** (`config.toml`, pydantic-settings с
файлами): настройки — только переменные окружения (`src/config.py`).
6. **JSON-логи, structlog, `print`** вместо логгера (`src/log.py`).
7. **Писать в лог** текст сообщений, `display_name`, `title`, username,
пароль, токен, их хэши, `Authorization`, `Idempotency-Key`, тела,
параметры SQL. Можно id и длины.
8. **Git без просьбы**: `commit`, `push`, `checkout`, `reset`, `stash`,
`rebase`, `clean`. Смотреть можно: `status`, `diff`, `log`.
9. **Удалять данные стенда без просьбы** (спросить): `make wipe`,
`docker compose down -v`, `docker volume rm`, `FLUSHALL` рабочего
Valkey, `TRUNCATE`/`DROP` в рабочей базе; каталоги меток в `evidence/`.
10. **Секреты и `.env`** в git, образ, `evidence/`, вывод и отчёт; `COPY .
.` в Dockerfile. Пароли и токены в командной строке не печатать.
11. **Незакреплённые версии**: `latest`, тег без digest, пакет без lock.
12. **Новая зависимость** (спросить): объяснить, зачем она и почему не
хватает stdlib и текущих пакетов; проверить точное имя пакета.
13. **Миграция, которая ломает работающую версию** (удаление,
переименование, `NOT NULL` без значения): только расширение схемы,
contract — отдельной ревизией позже (`migrations/AGENTS.md`). Править
применённую ревизию нельзя.
14. **`HTTPException`** в сервисах и хранилище, **403** для чужого чата,
**422** наружу: ошибки только через `src/errors.py`. Прозрачные
повторы `POST` (кроме отказа соединения в LB).
15. **Обходить sandbox Codex** (раздел 10): нет сети или docker — просить
одобрение или пользователя.
16. **Выдумывать результаты**: в отчёт, `REPORT.md` и `evidence/` — только
реальный вывод команд, которые ты запустил. Гипотезы трека 1 после
замеров не переписывать.
17. **Чинить попутно найденное** без просьбы: записать в
`KNOWN_ISSUES.md` (путь, симптом, предложение) и сказать в отчёте.
## 3. Порядок работы
1. Найди, откуда требование: `README.md` (рубрика), `contracts/README.md`
(семантика), `contracts/openapi.json` (схемы, коды), `COURSE.md`
(переходы API). Неясно или противоречит контракту — остановись и
спроси. Ответ преподавателя — в раздел 12.
2. Прочитай нужные `AGENTS.md` (раздел 1) и затрагиваемые файлы целиком.
3. Задача больше пары файлов — сначала короткий план в чате.
4. Минимальный дифф: не переименовывать и не «улучшать» лишнее.
5. Проверки из раздела 8 — до того, как сказать «готово».
6. Отчёт пользователю — раздел 11.
## 4. Команды
| Команда | Что делает |
|---|---|
| `make install` | `uv sync` (нужна сеть) |
| `make env` | `.env` из `.env.example` со случайными паролями, если его нет |
| `make up` | стенд: postgres, valkey → migrate → api × `API_REPLICAS` (2) → haproxy на `127.0.0.1:HOST_PORT` (8080); ждёт healthy |
| `make stop` / `make down` / `make logs` | остановить / удалить контейнеры (volume остаётся) / журнал реплик |
| `make wipe` | удалить контейнеры и volume: только после ввода `yes` (раздел 2, п. 9) |
| `make replicas [API_REPLICAS=N]` | вернуть остановленные реплики (те же ID) и выставить их число |
| `make instances` | одна сессия, серия запросов через LB: `X-Instance-Id` каждого ответа |
| `make lb-stats` | слоты HAProxy: адрес, состояние, запросы, повторы |
| `make failover-each [STOP_MODE=kill]` | `make test-failover` для каждой реплики по очереди, `STOP_ONE_LOG`, `docker compose ps` |
| `make rolling-update` | поочерёдная замена реплик на образ рабочего дерева без простоя |
| `make db-up` / `make run [RUN_PORT=8081]` / `make migrate-local` | хранилища стенда / один процесс на хосте без LB / миграции с хоста |
| `make lint` / `make fmt` | ruff: проверка / исправление и формат |
| `make test [BASE_URL=...]` | публичный smoke |
| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и прежний токен после рестарта LB, реплик, PostgreSQL и Valkey |
| `make test-failover ACTION_SCRIPT=scripts/stop-one.sh [STOP_MODE=kill]` | отказ одной реплики через LB: запись восстанавливается ≤ 10 с, без дублей |
| `make student-test [BASE_URL=...] [EXPECT_REPLICAS=...]` | свои тесты против запущенного стенда (без проверок отказов) |
| `make test-isolated` | отдельный стенд с LB и 2 репликами: smoke, свои тесты, test-failover, test-persistence, уборка (~50 с) |
| `make failure-checks [FAULT_ARGS=-rP]` | проверки отказов на отдельном стенде (~55 с) |
| `make check` / `make validate PYTHON=.venv/bin/python` | офлайн-проверка skeleton / полная валидация OpenAPI |
| `make requirements` / `make requirements-check` | `requirements.txt` из `uv.lock` / сверка |
| `make bench-failover` / `make bench-rollout` | уровень 4 под нагрузкой: `evidence/failover/<метка>/`, `evidence/rollout/<метка>/` |
| `make bench-scaling SERIES=a\|b\|db\|ab [CONFIGS=…] [RESUME=1]` | трек 1: серии, `evidence/scaling/<метка>/` |
| `make bench-*-quick`, `make bench-scaling-quick` | самопроверки стенда, метки `quick-*` в отчёт не идут |
| `make bench-compare BEFORE= AFTER= [AA=]` / `make bench-plots LABELS="…"` | «до/после» с шумом A/A / графики SVG |
`make test`, `make student-test`, `make instances`, `make failover-each`
ходят на `http://localhost:8080` (HAProxy). Внешние порты — `HOST_PORT`,
`POSTGRES_HOST_PORT` (5433), `VALKEY_HOST_PORT` (6380) в `.env`; разовая
подмена — аргументом make (`make test BASE_URL=http://localhost:8090`).
Внутри сети стенда порты фиксированы: 8080, 5432, 6379, 8404 (мониторинг
LB). Тесты против рабочего стенда оставляют в нём данные; чистый
прогон — `make test-isolated`.
## 5. Карта кода
```
src/ пакет приложения: python -m src (__main__ → early_stop.install() → main.run())
main.py create_app(): Db, кэш, хранилище, пароли, middleware (X-Request-Id, X-Instance-Id), роутеры
config.py Settings.from_env(): только окружение (Database, Cache, instance_id, сроки)
early_stop.py SIGTERM/SIGINT до старта сервера: строка журнала и выход 0 (stdlib)
constants.py, log.py, errors.py, clock.py, domain.py, pagination.py, healthcheck.py
db.py Db: пул и сроки, transaction(), отказ → Unavailable, ping()
cache.py клиент Valkey: срок на команду, обход при отказе
passwords.py Argon2id в потоке с лимитом, фиктивный хэш
api/ routes/ (health, users, sessions, chats, messages + Idempotency-Key), schemas, deps,
identity (BearerBackend), request_id, handlers
services/ UserService, SessionService, ChatService, MessageService (хэш тела); access.py
storage/ base.py (Protocol), postgres.py (ключ + сообщение одной транзакцией), cached.py, tables.py
migrations/ alembic: 0001 схема лабы 2, 0002 idempotency_keys (expand)
student-tests/ тесты по HTTP; stand.py — отдельные стенды; fault_hook.py
bench/ run.py, common.py, analysis.py, loadgen.py, sampler.py, compare.py, plots.py, RUNBOOK.md
infra/haproxy/ haproxy.cfg: DNS Docker, проверки /health/ready, цепочка таймаутов, runtime API
infra/valkey/ valkey.conf: лимит памяти, LRU, без persistence
scripts/ restart.sh, stop-one.sh, rolling-update.sh, lab3.py (свои); остальное — skeleton
.codex/rules/ правила команд Codex; .agents/skills/ — навыки Codex
evidence/ доказательства для REPORT.md; failover/, rollout/, scaling/ — метки стенда
Dockerfile, compose.yaml, alembic.ini, pyproject.toml, uv.lock, requirements.txt, .env.example
```
Поток запроса: клиент → HAProxy (round-robin, только готовые реплики) →
uvicorn реплики → `RequestIdMiddleware` → `AuthenticationMiddleware`
(`BearerBackend`: сессия из PostgreSQL, 401 или 503 до роутинга) → роут
(схема тела и ключа, 400) → сервис (членство, 404) → `CachedStorage` →
`PostgresStorage` (ключ и сообщение одной транзакцией, 409) / Valkey.
## 6. Контракт: самое важное
Полностью — `src/api/AGENTS.md` и `contracts/`. Переход 2 → 3
(`COURSE.md`): `Idempotency-Key` обязателен для отправки сообщения,
ответы API содержат `X-Instance-Id`.
- Любой ответ API несёт непустые `X-Request-Id` и `X-Instance-Id` (одно
значение на процесс; ответы самого HAProxy — без него). Ошибка —
`{"error": {"code", "message", "request_id"}}`.
- 400 (тело, JSON, UUID, `limit`, курсор, нет или неверный
`Idempotency-Key`), 401 (`WWW-Authenticate`: Basic на входе, Bearer
остальное), 404 (нет или чужое), 409 (username занят; ключ с другим
телом), 503 (PostgreSQL недоступен), 500. 422 и 403 не отдаются.
- Сначала аутентификация: 401 раньше 400. Порядок отправки: 401 → 400 →
404 → 409.
- Повтор того же тела с тем же ключом (24 ч, `IDEMPOTENCY_TTL_SECONDS`) —
тот же 201 и тот же `Message`; область ключа — автор + чат + ключ;
конкурентные повторы через разные реплики — одно сообщение; 5xx не
фиксируется результатом.
- Токен — 256 бит, в БД SHA-256; срок фиксируется при входе. Время —
RFC 3339 UTC с `Z`; порядок `(created_at, id)`; `limit` 1–100.
## 7. Конфигурация, логи, Docker, зависимости
**Переменные окружения** читает только `src/config.py`; неверное
значение — выход с кодом 2. Группы: `APP_HOST`, `APP_PORT`,
`APP_INSTANCE_ID` (по умолчанию hostname), `LOG_LEVEL`,
`SHUTDOWN_TIMEOUT`, `KEEP_ALIVE_TIMEOUT`; `SESSION_TTL_SECONDS`,
`IDEMPOTENCY_TTL_SECONDS`, `KDF_CONCURRENCY`; `DB_*`, `CACHE_*`. Таблица
— `src/AGENTS.md`. Логические имена `.env.example` skeleton и их
соответствие — `REPORT.md`, «Конфигурация».
**Логи**: строка на событие, `время уровень логгер [rid=...] сообщение
key=value`; строка старта содержит `instance=` (значение
`X-Instance-Id`), реплику в `docker compose logs` видно по префиксу.
**Docker, compose, HAProxy**: правила и цепочка таймаутов —
`infra/AGENTS.md`. Числа менять только вместе (обнаружение отказа ≤ 10 с,
`timeout connect` × 3 < 2 с, `timeout server` > срок операции,
keep-alive LB < keep-alive реплики, `SHUTDOWN_TIMEOUT` <
`stop_grace_period`).
**Зависимости**: `pyproject.toml` → `uv lock` → `make requirements` →
`make requirements-check` → пересборка образа.
## 8. Definition of Done
- [ ] `make fmt`, затем `make lint` — без ошибок;
- [ ] `make test-isolated` — в `results` все 0;
- [ ] правка хранилища, сессий, ключей, кэша, `db.py`, `cache.py`,
таймаутов — ещё `make failure-checks`;
- [ ] правка `compose.yaml`, `haproxy.cfg`, `scripts/*.sh` — `make up`,
`make test`, `make instances`, `make test-persistence
ACTION_SCRIPT=scripts/restart.sh`, `make failover-each`; скрипт
замены — `make rolling-update`;
- [ ] правка схемы — новая expand-ревизия, `alembic check` без
расхождений (`migrations/AGENTS.md`);
- [ ] правка `Dockerfile`, зависимостей — `make up`, все `(healthy)`,
`make test`, `make requirements-check`;
- [ ] правка `bench/` — `uv run python bench/analysis.py --selftest` и
самопроверки `make bench-*-quick` (`bench/AGENTS.md`);
- [ ] новое поведение из рубрики — тест в `student-tests/`;
- [ ] изменилось описанное в `REPORT.md`, `evidence/`, `AGENTS.md` —
обновлено там же;
- [ ] остановлены серверы и удалены контейнеры, которые ты запустил
(кроме рабочего стенда, если он работал до тебя).
Не смог выполнить пункт (нет сети, docker, порт занят) — так и напиши,
с причиной. «Должно работать» не считается проверкой.
## 9. Если тест или проверка упали
1. Воспроизведи и прочитай вывод целиком.
2. Назови причину: **дефект приложения** → чинить код; **ошибка в самом
тесте** (противоречит контракту или зависит от случайного) → править
тест можно, но назови, чему он противоречил; **стенд** (порт занят
чужим сервисом — smoke получает 404 на `/health/live`, старый образ,
не тот `BASE_URL`, остатки прерванного прогона, реплика ещё не `UP` в
LB) → чинить стенд.
3. Причина неясна или правка теста спорная — остановись и спроси.
Тест `tests/` не правится никогда. Дефект вне задачи — в
`KNOWN_ISSUES.md`. Проверки отказов меряют время с запасом 0,3–1 с: на
загруженном хосте возможно ложное падение — перезапусти один раз и
скажи об этом.
## 10. Особенности Codex
- В sandbox нет сети: `uv sync`/`uv lock`/`docker build` упадут. Docker
из sandbox часто недоступен (сокет): почти всё здесь требует docker.
Запроси запуск вне sandbox (правила `.codex/rules/` разрешают команды
проекта без вопроса, если проект доверенный) или попроси пользователя;
приложи команду дословно.
- Долгие команды (`make bench-*` — до часа) — в фоне с журналом:
`nohup make … > /tmp/bench-x.log 2>&1 &`, затем `tail` журнала.
- Сервис на хосте (`make run`) — в фоне с журналом; до запуска проверь
порт (`lsof -nP -iTCP:8081 -sTCP:LISTEN`), в конце убей только PID,
чей `ps -p <PID> -o command=` — `python -m src`.
- Никогда не убивать процесс по порту вслепую: порт опубликованного
контейнера на macOS держит `com.docker.backend`. Чужие процессы и
контейнеры не трогать — взять другой порт.
- Держи этот файл ≤ ~28 КБ (`wc -c`, кириллица — два байта на символ):
Codex читает `AGENTS.md` до 32 КиБ вместе. Новое правило слоя — во
вложенный `AGENTS.md`.
## 11. Отчёт пользователю в конце задачи
По-русски, коротко: что сделано (файлы и суть); какие проверки и с каким
итогом (`84 passed`, `PASS: lab3 ...`, `results: {...}`); что не
проверено и почему; что записано в `KNOWN_ISSUES.md`, вопросы к
преподавателю.
## 12. Согласования с преподавателем
Договорённости, которых нет в skeleton. Каждую упомянуть в `REPORT.md`.
| Дата | Договорённость | Где учтено |
|---|---|---|
| — | пока нет | — |
## 13. Стиль кода
- ruff (`pyproject.toml`): строка 88, py313, isort, bugbear, pyupgrade,
simplify, pytest-style, async. Формат — `make fmt`.
- Аннотации типов везде; дженерики PEP 695. Исключение — скрипты на
`python3` хоста (`student-tests/stand.py`, `fault_hook.py`,
`scripts/lab3.py`): Python 3.9+, stdlib, `from __future__ import
annotations`.
- Методы сервисов и изменяющие методы хранилища — keyword-only.
- Комментарии и докстринги — короткие, по-русски, объясняют «почему».
Сообщения логов и `error.message` — по-английски.
- Константы контракта — `src/constants.py`; время — `src/clock.py`.
- Коммиты (только по просьбе): английский, conventional.
## 14. Документы решения
- `REPORT.md` — отчёт: запуск из чистого clone, архитектура, таблица
доказательств, эксперименты, гипотезы трека 1, ограничения.
- `evidence/` — реальные выводы проверок (`evidence/AGENTS.md`).
- `KNOWN_ISSUES.md` — найденные, но не исправленные дефекты.
- `bench/RUNBOOK.md` — замеры по шагам. Стенд и метки лабы 2 (EXPLAIN,
восстановление) остались в репозитории лабы 2.
## 15. Дальше: лаба 4
Новый skeleton — отдельный репозиторий; переходы API — в его
`COURSE.md`, читать до правки кода (лаба 4: приватный S3, вложения,
`attachment_ids` в теле сообщения — добавить в `request_hash` со
значением по умолчанию `[]`). Переносить: `src/`, `student-tests/`,
`migrations/`, `alembic.ini`, `bench/`, `infra/haproxy/`, `infra/valkey/`,
свои `scripts/*`, `Dockerfile`, `compose.yaml`, `pyproject.toml`,
`uv.lock`, `requirements.txt`, `.python-version`, все `AGENTS.md`,
`.codex/`, `.agents/`, `KNOWN_ISSUES.md`. Сливать со skeleton:
`Makefile`, `.env.example`, `.gitignore`, `.dockerignore`. Не
копировать: `.git`, `.env`, volumes, `README.md`, `COURSE.md`, `tests/`,
`contracts/`, `lab.json`, `REPORT.md`, `evidence/`. Имя проекта compose
(`name:`) — на `vladimirceva-lab4`.
+57
View File
@@ -0,0 +1,57 @@
# Образ API мессенджера, лаба 3: сервер (реплики за HAProxy) и миграции.
# Правила — infra/AGENTS.md.
#
# Базовый образ закреплён тегом с патч-версией и digest индекса
# (linux/amd64 + linux/arm64), в обоих stage один и тот же: venv ссылается
# на интерпретатор базового образа. Обновление — новый тег и строка
# Digest из `docker buildx imagetools inspect python:<тег>`.
# deps: зависимости строго по requirements.txt (экспорт uv.lock с хешами).
# У asyncpg, greenlet и argon2-cffi-bindings есть готовые колёса для
# linux amd64/arm64: компилятор в образе не нужен
FROM python:3.13.15-slim-trixie@sha256:7c61056e61ac89e852de05f3dc6fa51a6dd2181797bceed46aa725dd7cb2cd3b AS deps
ENV PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
RUN python -m venv /opt/venv
COPY requirements.txt /tmp/requirements.txt
# --require-hashes: пакет с другим хешем или без пина — сборка падает;
# --no-deps: ставится ровно список из файла, без догрузки зависимостей;
# --only-binary: сборка из исходников (sdist) запрещена
RUN /opt/venv/bin/pip install --require-hashes --no-deps --only-binary=:all: \
-r /tmp/requirements.txt
# runtime: интерпретатор базового образа, venv и код; без pip-кэша и тестов
FROM python:3.13.15-slim-trixie@sha256:7c61056e61ac89e852de05f3dc6fa51a6dd2181797bceed46aa725dd7cb2cd3b AS runtime
RUN groupadd --system --gid 10001 messenger \
&& useradd --system --uid 10001 --gid messenger --no-create-home \
--home-dir /nonexistent --shell /usr/sbin/nologin messenger
ENV PATH=/opt/venv/bin:$PATH \
PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
APP_HOST=0.0.0.0 \
APP_PORT=8080
WORKDIR /app
# код и venv принадлежат root: пользователю messenger — только чтение.
# Миграции едут в том же образе: сервис migrate запускает его с командой
# `python -m alembic upgrade head`
COPY --from=deps /opt/venv /opt/venv
COPY src ./src
COPY alembic.ini ./
COPY migrations ./migrations
USER messenger:messenger
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --start-interval=1s \
--retries=3 CMD ["python", "-m", "src.healthcheck"]
# exec-форма: сервер — PID 1 и сам получает SIGTERM от docker stop
CMD ["python", "-m", "src"]
+13
View File
@@ -0,0 +1,13 @@
# Известные проблемы
Найдены попутно и не исправлены без отдельной просьбы (AGENTS.md,
раздел 2, п. 17). Формат: что, где, симптом, предложение. Исправленное
удаляется отсюда.
Открытых дефектов нет.
Закрыто при переносе в лабу 3: косметическая находка лабы 2 в
`bench/run.py:render_explain` (подпись раздела «Страница middle без
индекса» у чата без средней страницы). Стенд лабы 2 с планами запроса в
лабу 3 не переносился — стенд переписан под реплики за HAProxy, функции
больше нет; метки и отчёт лабы 2 остались в её репозитории.
+261
View File
@@ -28,3 +28,264 @@ test-persistence:
test-failover:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2)
$(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
# ===========================================================================
# Собственные цели решения. Цели skeleton выше (help, check, validate, test,
# load, test-persistence, test-failover) не менять: в следующей лабе
# Makefile придёт новый, свои цели переносятся в него слиянием.
# ===========================================================================
# .env: подстановки compose и окружение приложения на хосте. Без него —
# значения по умолчанию ниже (пароли пустые: сначала `make env`)
-include .env
IMAGE ?= mtusi-messenger-vladimirceva:lab3
# порт HAProxy на 127.0.0.1 — единственный порт API стенда на хосте
HOST_PORT ?= 8080
# порт сервиса на хосте (make run): другой, чем у стенда, — оба могут
# работать одновременно
RUN_PORT ?= 8081
POSTGRES_USER ?= messenger
POSTGRES_DB ?= messenger
POSTGRES_HOST_PORT ?= 5433
VALKEY_HOST_PORT ?= 6380
SESSION_TTL_SECONDS ?= 3600
# реплик API за HAProxy; разово — `make replicas API_REPLICAS=3`
API_REPLICAS ?= 2
DC = docker compose
UV_EXPORT = uv export --frozen --no-dev --no-emit-project --no-header --format requirements.txt
# долгие замеры на macOS — под caffeinate: ноутбук не уснёт по простою
CAFFEINATE := $(shell command -v caffeinate >/dev/null 2>&1 && echo caffeinate -isu)
# --- приложение на хосте ----------------------------------------------------
.PHONY: install
install:
uv sync
# окружение сервиса и миграций на хосте: хранилища стенда на 127.0.0.1,
# пароли из .env. .env читается в рецепте, а не при разборе Makefile: так
# первый запуск видит и файл, только что созданный `make env`. Рецепт без
# эха — пароли не печатаются
LOCAL_ENV = set -a; . ./.env; set +a; \
export DB_HOST=127.0.0.1 DB_PORT="$$POSTGRES_HOST_PORT" DB_NAME="$$POSTGRES_DB" \
DB_USER="$$POSTGRES_USER" DB_PASSWORD="$$POSTGRES_PASSWORD" CACHE_HOST=127.0.0.1 \
CACHE_PORT="$$VALKEY_HOST_PORT" CACHE_PASSWORD="$$VALKEY_PASSWORD"
# PostgreSQL и Valkey из compose, миграции с хоста, затем один процесс
# сервиса на 127.0.0.1:RUN_PORT без LB, текстовые логи в stdout; стоп —
# Ctrl+C. Срок сессии — `make run SESSION_TTL_SECONDS=2`
.PHONY: run
run: migrate-local
@echo "uv run python -m src # 127.0.0.1:$(RUN_PORT), SESSION_TTL_SECONDS=$(SESSION_TTL_SECONDS)"
@$(LOCAL_ENV); APP_PORT=$(RUN_PORT) SESSION_TTL_SECONDS=$(SESSION_TTL_SECONDS) \
uv run python -m src
# миграции с хоста в PostgreSQL стенда (127.0.0.1:POSTGRES_HOST_PORT)
.PHONY: migrate-local
migrate-local: db-up
@echo "uv run alembic upgrade head # 127.0.0.1:$(POSTGRES_HOST_PORT)"
@$(LOCAL_ENV); uv run alembic upgrade head
.PHONY: lint
lint:
uv run ruff format --check .
uv run ruff check .
.PHONY: fmt
fmt:
uv run ruff format .
uv run ruff check --fix .
# собственные тесты против запущенного стенда (BASE_URL, по умолчанию
# HAProxy рабочего стенда); EXPECT_REPLICAS — сколько реплик за BASE_URL
# (против `make run` — 1: тесты реплик пропускаются с причиной).
# Проверки отказов (маркер fault) — make failure-checks
EXPECT_REPLICAS ?= $(API_REPLICAS)
.PHONY: student-test
student-test:
BASE_URL=$(BASE_URL) EXPECT_REPLICAS=$(EXPECT_REPLICAS) uv run pytest
# отдельный стенд из того же compose.yaml (свои PostgreSQL, Valkey, volume,
# HAProxy и две реплики, свои пароли, без .env): сборка, миграции, make
# test и make student-test через его LB, затем уборка при любом исходе.
# Рабочий стенд не трогается. $(PYTHON), а не uv run: uv повторно шлёт
# SIGINT, и Ctrl+C обрывал бы уборку
.PHONY: test-isolated
test-isolated:
$(PYTHON) student-tests/stand.py isolated
# проверки отказов (pytest -m fault, ~1,5 мин) на таком же отдельном
# стенде: обычный и «тесный» API (сроки сессии и ключа 2 с, пул 1), hook
# student-tests/fault_hook.py. FAULT_ARGS — аргументы pytest
.PHONY: failure-checks
failure-checks:
$(PYTHON) student-tests/stand.py failures $(FAULT_ARGS)
# requirements.txt для образа — только из uv.lock, с хешами
.PHONY: requirements
requirements:
$(UV_EXPORT) --output-file requirements.txt
.PHONY: requirements-check
requirements-check:
$(UV_EXPORT) | diff -u requirements.txt - && echo "requirements.txt matches uv.lock"
# --- Docker и compose ---------------------------------------------------------
# .env из шаблона, если его ещё нет, со случайными паролями PostgreSQL и
# Valkey: в шаблоне они пустые, общего пароля стенда в git нет.
# Существующий .env не трогается
.PHONY: env
env:
@test -f .env || sed \
-e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \
-e "s/^VALKEY_PASSWORD=$$/VALKEY_PASSWORD=$$(openssl rand -hex 16)/" \
.env.example > .env
@echo ".env ready"
.PHONY: docker-build
docker-build:
docker build -t $(IMAGE) .
# весь стенд: postgres, valkey -> migrate -> api × API_REPLICAS -> haproxy;
# --wait ждёт healthy реплик и LB (миграции к этому моменту завершились с
# кодом 0). Реплики с изменённым образом пересоздаются все разом, с
# простоем; без простоя — make rolling-update
.PHONY: up
up: env
$(DC) up -d --build --wait api haproxy
# остановить контейнеры (SIGTERM); данные и контейнеры остаются. LB
# останавливается раньше реплик (depends_on)
.PHONY: stop
stop:
$(DC) stop
# удалить контейнеры; volume pgdata с данными остаётся (удаление — wipe)
.PHONY: down
down:
$(DC) down
# журнал всех реплик; префикс строки — имя контейнера реплики
.PHONY: logs
logs:
$(DC) logs -f api
# только хранилища стенда, с ожиданием healthcheck: для make run
.PHONY: db-up
db-up: env
$(DC) up -d --wait postgres valkey
# удалить контейнеры и volume с данными стенда: только после ввода yes
.PHONY: wipe
wipe:
@read -p "Удалить все данные стенда (volume PostgreSQL)? Введите yes: " answer; \
if [ "$$answer" = "yes" ]; then \
$(DC) down -v --remove-orphans; \
else \
echo "cancelled, nothing removed"; exit 1; \
fi
# --- Реплики за HAProxy (лаба 3) --------------------------------------------
# вернуть остановленные реплики (те же контейнеры и X-Instance-Id) и
# выставить их число API_REPLICAS; ждёт healthy
.PHONY: replicas
replicas:
$(DC) up -d --no-deps --no-recreate --wait --scale api=$(API_REPLICAS) api
# вход одним синтетическим пользователем и серия GET /users/me с одним
# токеном через LB: X-Instance-Id каждого ответа и итог по репликам
.PHONY: instances
instances:
$(PYTHON) scripts/lab3.py instances --base-url "$(BASE_URL)"
# слоты HAProxy: адрес, состояние проверки (DRAIN/MAINT при замене),
# запросы, ошибки соединения, повторы, перенаправления
.PHONY: lb-stats
lb-stats:
$(PYTHON) scripts/lab3.py lb-stats
# make test-failover для каждой реплики по очереди с возвратом
# предыдущей (make replicas): какой контейнер остановлен, строка
# STOP_ONE_LOG и итог теста. STOP_MODE=kill — без graceful
STOP_MODE ?= stop
.PHONY: failover-each
failover-each:
$(PYTHON) scripts/lab3.py failover-each --base-url "$(BASE_URL)" \
--replicas $(API_REPLICAS) --mode $(STOP_MODE)
# поочерёдная замена реплик на образ рабочего дерева без простоя:
# сборка, миграции один раз, по одной реплике через drain в LB
.PHONY: rolling-update
rolling-update:
API_REPLICAS=$(API_REPLICAS) scripts/rolling-update.sh
# --- Нагрузочный стенд (уровень «4» — отказ и замена под нагрузкой,
# уровень «5» — трек 1 «Цена масштабирования») ---------------------------
# Порядок работы — bench/RUNBOOK.md, правила — bench/AGENTS.md. Свой проект
# compose vlad-bench, рабочий стенд перед замером — make stop.
FAILOVER_LABEL ?= baseline
ROLLOUT_LABEL ?= baseline
# серия трека 1: a — бюджет 4 CPU на 1/2/4 реплики; b — 1…N реплик по
# 1 CPU; db — PostgreSQL 0,5 CPU при 1/2/4 репликах; ab — ячейки «до/после»
SERIES ?=
SCALING_LABEL ?=
LABELS ?=
PLOTS ?= scaling
BENCH = $(CAFFEINATE) uv run python bench/run.py
# уровень 4: две реплики под постоянной нагрузкой, каждая в режимах stop,
# kill, pause с возвратом; пишет evidence/failover/<метка>/
.PHONY: bench-failover
bench-failover:
$(BENCH) failover --label "$(FAILOVER_LABEL)"
# проверка стенда отказа (~2 мин); метка quick-failover-<UTC> в отчёт не идёт
.PHONY: bench-failover-quick
bench-failover-quick:
$(BENCH) failover-quick
# уровень 4: поочерёдная замена (scripts/rolling-update.sh) под той же
# нагрузкой, с новой expand-ревизией; пишет evidence/rollout/<метка>/
.PHONY: bench-rollout
bench-rollout:
$(BENCH) rollout --label "$(ROLLOUT_LABEL)"
.PHONY: bench-rollout-quick
bench-rollout-quick:
$(BENCH) rollout-quick
# уровень 5, трек 1: серия конфигураций, на каждую ячейку свежий стенд,
# открытая модель, поиск R*; пишет evidence/scaling/<метка>/.
# CONFIGS="4x1-pg0.5 4x1" — ячейки вместо профильных (серия ab — всегда);
# RESUME=1 — продолжить прерванную метку
CONFIGS ?=
.PHONY: bench-scaling
bench-scaling:
@test -n "$(SERIES)" || (echo "usage: make bench-scaling SERIES=a|b|db|ab [SCALING_LABEL=...] [CONFIGS=...] [RESUME=1]"; exit 2)
$(BENCH) scaling --series "$(SERIES)" $(if $(SCALING_LABEL),--label "$(SCALING_LABEL)",) \
$(if $(CONFIGS),--configs "$(CONFIGS)",) $(if $(RESUME),--resume,)
# самопроверка серий (~5 мин): 1 × 1 и 2 × 1, короткие окна
.PHONY: bench-scaling-quick
bench-scaling-quick:
$(BENCH) scaling --series quick
# сравнение двух меток (серии — по общим конфигурациям); AA — метка того
# же кода, что BEFORE: уровень шума
.PHONY: bench-compare
bench-compare:
@test -n "$(BEFORE)" -a -n "$(AFTER)" || \
(echo "usage: make bench-compare BEFORE=<label> AFTER=<label> [AA=<label>]"; exit 2)
uv run python bench/compare.py --before "$(BEFORE)" --after "$(AFTER)" \
$(if $(AA),--aa "$(AA)",)
# графики SVG и сводка серий трека 1: evidence/plots/<PLOTS>/
.PHONY: bench-plots
bench-plots:
@test -n "$(LABELS)" || (echo "usage: make bench-plots LABELS=\"scaling-a scaling-b\" [PLOTS=scaling]"; exit 2)
uv run python bench/plots.py --out "$(PLOTS)" $(LABELS)
+472 -23
View File
@@ -1,37 +1,486 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Владимирцева, БВТ2301
- Целевая оценка 5; выбранный трек 5: 1 «Цена масштабирования»
- Commit/PR: TODO после публикации (ветка `solution/bvt2301-vladimirceva`)
- Использованные источники, библиотеки и помощь ИИ: раздел 8 в конце
отчёта
## Запуск из чистого clone
Состояние отчёта: уровень 3 и проверки уровня 4 без нагрузки сняты
(раздел 3, файлы `evidence/`). Замеры под нагрузкой — отказ каждой
реплики, поочерёдная замена и серии трека 1 — выполняются по
[bench/RUNBOOK.md](bench/RUNBOOK.md); их места помечены `TODO (Codex)`.
Гипотезы и прогнозы раздела 4 записаны **до** этих замеров.
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
## 1. Запуск и демонстрация
## Архитектура и решения
Нужны Docker Compose (Docker Desktop), make и uv. API — Python 3.13.15;
PostgreSQL 18.6, Valkey 9.1.2, HAProxy 3.4.6. Образы закреплены тегом с
патч-версией и digest индекса в [Dockerfile](Dockerfile) и
[compose.yaml](compose.yaml), зависимости — [uv.lock](uv.lock) и
`requirements.txt` с хешами.
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```sh
make install # uv sync
make env # .env со случайными паролями (в git нет)
make up # postgres, valkey → migrate → api × 2 → haproxy
make test # публичный smoke через LB
make instances # одна сессия на разных репликах (X-Instance-Id)
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make replicas # вернуть остановленную реплику
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-isolated # всё выше на отдельном чистом стенде (~50 с)
make failure-checks # проверки отказов (~55 с)
make rolling-update # поочерёдная замена без простоя
```
## Доказательства критериев
`make up` ждёт готовности хранилищ, успешного завершения миграций
(сервис `migrate`), готовности реплик и HAProxy. Единственная точка
входа API — HAProxy на `127.0.0.1:${HOST_PORT}` (8080). Число реплик —
`API_REPLICAS` (2), разово — `make replicas API_REPLICAS=3`.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
**Сценарий защиты** (`README.md`):
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
1. `make up`, `make instances` — ≥ 2 разных `X-Instance-Id` у запросов
одной сессии ([пример](evidence/replicas/instances.txt)).
2. `make test-failover ACTION_SCRIPT=scripts/stop-one.sh
STOP_ONE_LOG=/tmp/stop-one.log` — запись во время отказа, повтор с
исходным ключом, без дублей.
3. `docker compose ps` и строка `/tmp/stop-one.log`: остановлен именно
контейнер с ID из `TARGET_INSTANCE_ID`. `make replicas`, затем то же
для второй реплики. Обе реплики по очереди, `stop` и `kill` —
`make failover-each [STOP_MODE=kill]`
([вывод](evidence/failover/failover-each.txt)).
4. `make test-persistence ACTION_SCRIPT=scripts/restart.sh`: рестарт LB,
реплик, PostgreSQL и Valkey с сохранением volume, тот же токен.
Для уровней 4 и 5 — метки стенда `bench/` (раздел 4).
## Эксперименты и отказы
Остановка: `make stop` (контейнеры остаются), `make down` (контейнеры
удаляются, volume `pgdata` остаётся). Удаление учебных данных — `make
wipe`, только после ввода `yes`.
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
## 2. Архитектура и решения
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
```text
клиент → 127.0.0.1:HOST_PORT → HAProxy ─┬→ api-1 ─┬→ PostgreSQL (данные, сессии, ключи идемпотентности)
└→ api-2 ─┴→ Valkey (кэш карточек чатов)
migrate (один раз на up и на замену, до реплик) → PostgreSQL
```
## Ограничения и следующие шаги
**Перенесено из лабы 2** без изменений поведения: REST API, слои HTTP →
сервисы → хранилище (SQLAlchemy Core + asyncpg), PostgreSQL как источник
истины, Basic → Bearer-сессии (Argon2id, SHA-256 токена, TTL), кэш
карточек в Valkey с обходом при отказе, 503 при недоступной БД,
ограниченные пул и сроки, собственные тесты и проверки отказов.
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
**Изменено в лабе 3:**
| Что | Как |
|---|---|
| Реплики | сервис `api` × `API_REPLICAS` без портов и `container_name`; в памяти процесса нет ничего, от чего зависит корректность |
| Точка входа | HAProxy 3.4: round-robin без sticky session, реплики через DNS Docker, активная проверка `/health/ready`, повтор только при отказе соединения |
| `X-Instance-Id` | в каждом ответе API (в том числе ошибки, health, 404, 405, 500); hostname контейнера — начало его ID |
| `Idempotency-Key` | обязателен при отправке сообщения; ключ и сообщение — одна транзакция PostgreSQL (ниже) |
| Миграции | однократно сервисом `migrate`, только расширение схемы: ревизия `0002` — таблица ключей |
| Остановка | ранний обработчик SIGTERM до импорта приложения, согласованная цепочка таймаутов (ниже) |
| Поочерёдная замена | `scripts/rolling-update.sh`: миграции один раз, затем по одной реплике через drain в LB |
| Лимиты | CPU/RAM у всех контейнеров; секреты — только сервисам, которым нужны |
**Почему HAProxy, а не Nginx, Traefik или Swarm.** Нужны активные
проверки готовности, видимость новых и пропавших реплик без
перезагрузки и управляемый вывод реплики из балансировки при замене.
HAProxy даёт всё это штатно: `server-template` + `resolvers` (DNS
Docker), `option httpchk`, runtime API (`drain`/`maint`/`ready`) и
статистику слотов. Бесплатный Nginx активных проверок не имеет, Traefik
решает это через метки Docker и сокет демона (лишний доступ), Swarm
меняет весь способ запуска стенда (`stack.yaml`, registry для образа).
Compose + HAProxy — один `make up` и один хост.
### Идемпотентность отправки
Таблица `idempotency_keys`: первичный ключ (автор, чат, ключ) — область
из контракта (пользователь + метод + путь чата + ключ; ключ принимает
одна ручка); SHA-256 канонического JSON тела; `message_id`; время
захвата; внешний ключ `(chat_id, автор) → chat_members`; ссылка на
сообщение `DEFERRABLE INITIALLY DEFERRED`. Отправка — одна транзакция:
1. захват ключа одним `INSERT … ON CONFLICT DO UPDATE … WHERE created_at <
now − TTL RETURNING`: новый или просроченный ключ — захвачен, иначе —
занят, строка заблокирована до конца транзакции;
2. захвачен — вставка сообщения с этим `message_id`, commit (ссылка
проверяется при commit) → 201;
3. занят — чтение сохранённого: тот же хэш → тот же `Message` (201),
другой → 409 `conflict`.
Одновременные запросы с одним ключом через разные реплики ждут друг
друга на уникальном индексе: второй после commit первого видит его
строку и отдаёт повтор. Сбой до commit (отказ БД, ошибка вставки
сообщения) откатывает и ключ, и сообщение: транзиентная ошибка
результатом не фиксируется, повтор с тем же ключом безопасен. Повтор
заново проходит проверку сессии и членства. Порядок кодов: 401 → 400
(ключ и тело) → 404 → 409. Хэш строится из разобранных полей: пробелы и
`\u`-экранирование не делают тело «другим». TTL ключа —
`IDEMPOTENCY_TTL_SECONDS` (86400 = 24 ч, контракт). Ключ в журнал и
текст ошибки не попадает.
### Реплики, проверки и цепочка таймаутов
| Звено | Значение | Почему |
|---|---|---|
| Проверка LB | `GET /health/ready` раз в 1 с, после неудачи — 0,5 с; `fall 2`, `rise 2`; `timeout check` 2,5 с | `/health/live` не годится: живой процесс без PostgreSQL запросы не обслуживает |
| Худшее обнаружение отказа | зависшая реплика 6,5 с; пропавший адрес (`kill`) 2,5 с; закрытый сокет (`stop`) 1,5 с | ≤ 10 с из рубрики; формула — `inter + timeout check + (fall − 1) × (fastinter + timeout check)` |
| Возврат реплики в LB | ≤ 1,5 с после готовности; новый слот начинает `DOWN` (`init-state down`) | запросы не идут на процесс, который ещё не слушает порт |
| `timeout connect`, `retries`, `redispatch` | 0,5 с, 2, на другую реплику; повтор только `conn-failure` | 0,5 × 3 = 1,5 с < 2 с таймаута клиента `tests/resilience.py`; запрос, дошедший до реплики, не повторяется (POST не идемпотентны) |
| `timeout server` | 10 с | > срок операции хранилища 6 с + закрытие соединения 2 с |
| Готовность внутри реплики | `SELECT 1` за 2 с | < `timeout check` 2,5 с: медленная БД — 503 реплики, а не таймаут проверки |
| Keep-alive | LB 10 с (`http-reuse never`) < реплика 60 с | простаивающее соединение закрывает LB, а не реплика: нет 502 на гонке закрытия |
| Остановка | `SHUTDOWN_TIMEOUT` 5 с < `stop_grace_period` 10 с; `stop-one.sh` — `docker stop --timeout 9` | graceful успевает до SIGKILL, hook возвращается раньше 10 с |
| Старт | ранний обработчик SIGTERM до импорта приложения | `docker stop` стартующей реплики — 0,10 с, код 0 ([evidence](evidence/stand/early-stop.txt)) |
### Лимиты, пулы и порты
| Сервис | CPU | Память | Порт на хосте | Секреты |
|---|---|---|---|---|
| api × 2 | 1 | 512 МиБ | нет | пароли PostgreSQL и Valkey |
| haproxy | 1 | 256 МиБ | `127.0.0.1:HOST_PORT` | нет |
| postgres | 2 | 1 ГиБ | `127.0.0.1:POSTGRES_HOST_PORT` (для `make run`) | свой |
| valkey | 0,5 | 128 МиБ | `127.0.0.1:VALKEY_HOST_PORT` (для `make run`) | свой |
| migrate | 0,5 | 256 МиБ | нет | пароль PostgreSQL |
Соединения PostgreSQL: 2 × (пул 10 + переполнение 5) + migrate = 31 ≤
`max_connections` 100; при замене на пике три реплики — 46. Реплики,
`migrate` и LB: read-only файловая система, `cap_drop: ALL`,
`no-new-privileges`. Проверено: [стенд и лимиты](evidence/replicas/stand.txt).
### Миграции и совместимость
Миграции выполняет одноразовый сервис `migrate` до старта реплик;
реплики их не запускают. Повторный запуск — no-op. При поочерёдной
замене миграции — один раз, на новом образе, до первой новой реплики;
пересоздаётся контейнер самого сервиса `migrate` (иначе `restart.sh`
позже запускал бы старый образ на новой схеме). Ревизии только
расширяют схему (`0002` — новая таблица), поэтому реплики прежней версии
работают на новой схеме, пока их не заменят; удаление и переименование
— отдельной ревизией после замены (expand → contract). Ревизия,
блокирующая рабочую таблицу, начинает с `SET LOCAL lock_timeout = '2s'`.
Отката кода автоматически нет: прежний код на расширенной схеме
работает, откат — прежний код и снова `make rolling-update`.
### Конфигурация: логические имена `.env.example`
| Имя skeleton | Реализация |
|---|---|
| `APP_HOST`, `APP_PORT` | `APP_HOST`/`APP_PORT` приложения; в образе `0.0.0.0:8080`; на хосте — `HOST_PORT` у HAProxy |
| `APP_ENV` | не используется: режим один (контейнер или `make run`) |
| `SESSION_TTL_SECONDS` | то же имя, по умолчанию 3600 |
| `DATABASE_URL_FILE` | не используется: `DB_HOST`/`DB_PORT`/`DB_NAME`/`DB_USER`/`DB_PASSWORD`, пароль из `.env` (`POSTGRES_PASSWORD`) через `environment` compose |
| `SESSION_STORE` | `postgres` — сессии в PostgreSQL |
| `CACHE_URL_FILE` | не используется: `CACHE_HOST`/`CACHE_PORT`/`CACHE_PASSWORD` (`VALKEY_PASSWORD`) |
| `API_REPLICAS` | то же имя: `deploy.replicas` сервиса `api` |
| `IDEMPOTENCY_TTL_SECONDS` | то же имя, по умолчанию 86400 |
Новые настройки приложения: `APP_INSTANCE_ID` (по умолчанию hostname),
`KEEP_ALIVE_TIMEOUT` (60 с). Полная таблица — [src/AGENTS.md](src/AGENTS.md).
### Пагинация и часы
Порядок истории — `(created_at, id)`, keyset по индексу `(chat_id,
created_at, id)`. `created_at` назначает приложение: строго монотонно
внутри процесса; у реплик одного хоста общие часы ВМ, при равенстве
порядок задаёт `id`. Транзакции фиксируются не в порядке времени, и
сообщение с меньшим `created_at` может стать видимым позже соседнего:
обход неизменной истории без повторов гарантирован, снимок между
запросами — нет (контракт этого не требует).
## 3. Доказательства критериев
| Критерий | Результат | Доказательство |
|---|---|---|
| Публичный smoke через LB | `PASS: lab3 public API scenario` | [test-isolated](evidence/tests/test-isolated.txt), [после замены](evidence/rollout/rolling-update.txt) |
| Стенд одной командой; ≥ 2 реплики, одна точка входа, одна БД и общие сессии | `make up`; порт API — только HAProxy; реплики без портов | [стенд](evidence/replicas/stand.txt) |
| Одна сессия на разных репликах | 12 запросов одного токена — 2 реплики по 6; тест: 20 запросов — 10/10 | [instances](evidence/replicas/instances.txt), [тесты через LB](evidence/tests/student-test-lb.txt) |
| Остановка любой одной реплики: запись восстанавливается ≤ 10 с, подтверждённые сообщения целы | `test-failover` PASS для каждой реплики, `stop` и `kill`: неудачных попыток 0, первая запись после hook — 0,24–1,73 с | [failover-each](evidence/failover/failover-each.txt), [test-isolated](evidence/tests/test-isolated.txt) |
| Какой контейнер действительно остановлен | ID из `TARGET_INSTANCE_ID` = ID в `exited` (`STOP_ONE_LOG`, `docker compose ps`) | [failover-each](evidence/failover/failover-each.txt) |
| Повтор POST с тем же ключом без дубля, в том числе конкурентный и через другую реплику | 10 одновременных отправок — 10 × 201, один id, пара пересекающихся запросов на разных репликах; повтор через другую реплику — тот же `Message`, 409 от обеих | [тесты через LB](evidence/tests/student-test-lb.txt) |
| Неподтверждённую запись можно повторить с тем же ключом | 503 не фиксируется результатом; сбой вставки сообщения откатывает ключ; срок ключа | [проверки отказов](evidence/tests/failure-checks.txt) |
| `make test-persistence` | PASS; StartedAt всех контейнеров новые, volume тот же | [persistence](evidence/stand/persistence.txt) |
| Health/readiness, timeouts, SIGTERM согласованы; LB исключает недоступную реплику; период проверок и худшее обнаружение | раздел 2, таблица цепочки; SIGTERM на старте 0,10 с, после старта 0,41 с, код 0 | [early-stop](evidence/stand/early-stop.txt), [haproxy.cfg](infra/haproxy/haproxy.cfg) |
| Каждая реплика по очереди под нагрузкой: RPS, ошибки, время восстановления | TODO (Codex): таблица фаз `stop`/`kill`/`pause` | TODO (Codex): `evidence/failover/baseline/` |
| Общая идемпотентность параллельными запросами | 10 потоков, один ключ, разные реплики — одно сообщение | [тесты через LB](evidence/tests/student-test-lb.txt) |
| CPU/RAM-лимиты, API без портов в обход LB, секреты только где нужно, нет `container_name` у `api` | лимиты у всех; переменные окружения по сервисам | [стенд](evidence/replicas/stand.txt) |
| Rolling update проверен | `make rolling-update`: по одной реплике, drain → maint → stop (exit 0) → rm, smoke PASS | [rolling-update](evidence/rollout/rolling-update.txt) |
| Rolling update под нагрузкой; миграции однократно и совместимы | TODO (Codex): окна до / во время / после, ревизия `0002 → 9001` | TODO (Codex): `evidence/rollout/baseline/` |
| Миграции однократно, повтор — no-op, схема = описание | `alembic check`: No new upgrade operations | [migrations](evidence/stand/migrations.txt) |
| Собственные тесты уровня 4 | 84 passed; проверки отказов 15 passed | [test-isolated](evidence/tests/test-isolated.txt), [failure-checks](evidence/tests/failure-checks.txt) |
| Трек 1: фиксированный бюджет 1/2/4 реплики | TODO (Codex) | TODO (Codex): `evidence/scaling/scaling-a/` |
| Трек 1: рост ресурсов, точка насыщения | TODO (Codex) | TODO (Codex): `evidence/scaling/scaling-b/`, `scaling-db/`, `evidence/plots/scaling/` |
| Трек 1: одно подтверждённое улучшение | TODO (Codex) | TODO (Codex): `evidence/compare/scaling-ab-before__scaling-ab-after.md` |
| Запуск из копии без локальных файлов | TODO (Codex, шаг 6 RUNBOOK) | [fresh-copy](evidence/stand/fresh-copy.txt) |
## 4. Эксперименты и отказы
### 4.1. Отказы без нагрузки (сняты)
| Воздействие | Что ожидали | Что наблюдали | Восстановление / потеря данных |
|---|---|---|---|
| `docker stop` реплики во время записи (`test-failover`, обе реплики) | LB перенаправляет отказ соединения на живую реплику, ошибок нет | 0 неудачных попыток; первая запись после hook 1,22–1,73 с (hook ждёт graceful stop) | потерь и дублей нет |
| `docker kill` реплики во время записи | возможны оборванные запросы; повтор с ключом | 0 неудачных попыток; первая запись после hook 0,24–0,75 с | потерь и дублей нет |
| Рестарт LB, реплик, PostgreSQL и Valkey | данные и прежний токен целы | PASS | volume тот же, сессия та же |
| PostgreSQL остановлен | 503 быстро, без деталей | `POST` сообщения — 503 за 0,007 с; ready — 503 за 0,013 с | запись во время отказа не появилась; тот же ключ после возврата — 201 один раз |
| PostgreSQL заморожен, пул из 1 | 503 за срок операции + закрытие | 503 за 4,02 с; второй запрос — 1,02 с (ожидание пула) | — |
| Valkey остановлен / заморожен | ответы из PostgreSQL, ≤ 0,2 с лишних | 200 за 0,013 с; заморозка — +0,22 с у одного запроса | кэш возвращается без рестарта API |
| Сбой вставки сообщения после ключа | откат ключа и сообщения | 500; ключей 0; повтор с ключом — 201 | — |
| SIGTERM стартующей реплике | быстрый выход 0, а не 10 с и SIGKILL | 0,10 с, код 0, строка `stopped before startup` | — |
Источники — [failover-each](evidence/failover/failover-each.txt),
[persistence](evidence/stand/persistence.txt),
[failure-checks](evidence/tests/failure-checks.txt),
[early-stop](evidence/stand/early-stop.txt).
### 4.2. Отказ каждой реплики под нагрузкой (уровень 4)
**Методика** (`make bench-failover`, профиль `failover`): свой проект
compose `vlad-bench` с лимитами рабочего стенда (2 реплики по 1 CPU /
512 МиБ, PostgreSQL 2 / 1 ГиБ, Valkey 0,5 / 128 МиБ, HAProxy 1 / 256 МиБ,
без swap); открытая модель через HAProxy — 100 записей с новым
`Idempotency-Key` и 100 чтений страницы истории в секунду; каждая
реплика по очереди в режимах `stop` (`docker stop --timeout 9`), `kill`,
`pause`; фаза — 10 с до действия, 15 с отказа, возврат той же реплики,
10 с после. Отметки — часы ВМ Docker: события Docker, журнал HAProxy,
моменты запросов по расписанию. После фазы неуспешные записи
повторяются с тем же ключом, затем сверка: строк в чате = ключей, без
дублей. CPU и память компонентов — сэмплер cgroup.
**Прогноз** (записан до замера):
| Режим | Обнаружение (граница) | Ошибки клиента | Восстановление |
|---|---|---|---|
| `stop` | ≤ 1,5 с (сокет закрыт) | 0: отказ соединения LB повторяет на живую; рост задержки отдельных запросов до `timeout connect` 0,5 с | 0 с |
| `kill` | ≤ 2,5 с | единицы: запросы, уже ушедшие на реплику (≈ интенсивность × задержка), — 502/обрыв; LB их не повторяет | ≤ 1 с; после повтора с ключом — потерь и дублей нет |
| `pause` | ≤ 6,5 с | до половины запросов окна обнаружения (≈ 100/с × 6,5 с) — 504 через `timeout server` 10 с | ≈ время обнаружения; после повтора — без потерь и дублей |
**Результат:** TODO (Codex): таблица фаз из
`evidence/failover/baseline/summary.md` как есть, CPU по окнам, итог
сравнения с прогнозом.
### 4.3. Поочерёдная замена под нагрузкой (уровень 4)
**Методика** (`make bench-rollout`, профиль `rollout`): тот же стенд и
нагрузка; посреди неё `scripts/rolling-update.sh` (тот же, что `make
rolling-update`) меняет обе реплики на образ с expand-ревизией
`9001_rollout_probe` (`ALTER TABLE messages ADD COLUMN rollout_probe text
NULL`; ревизия существует только в образе стенда): миграция один раз,
затем по одной реплике. Окна: до скрипта, во время, после; ответы
старых и новых реплик по `X-Instance-Id`; проверки: две новые реплики,
ни одной старой, один новый образ, ревизия `0002 → 9001`, сверка
записей.
**Прогноз:** ошибок клиента 0 (новая реплика получает запросы только
после `UP`, старая выводится `drain` до SIGTERM); p95 во время замены — не
больше двух p95 до неё: `ADD COLUMN` берёт `ACCESS EXCLUSIVE` на
`messages` на миллисекунды и ждёт идущие вставки; после замены — только
новые реплики.
**Результат:** TODO (Codex): таблица окон, события контейнеров,
проверки из `evidence/rollout/baseline/summary.md`; итог по прогнозу.
### 4.4. Цена масштабирования (трек 1)
**Методика** (`make bench-scaling SERIES=…`, профили `SERIES` в
[bench/run.py](bench/run.py), правила — [bench/AGENTS.md](bench/AGENTS.md)):
- конфигурация — реплик × CPU реплики (память 512 МиБ на CPU),
PostgreSQL 2 CPU / 1 ГиБ (серия `db` — 0,5 CPU), HAProxy 1 / 256 МиБ,
Valkey 0,5 / 128 МиБ, генератор 2 / 1 ГиБ, сэмплер 0,25 / 256 МиБ, без
swap; сумма лимитов ≤ CPU ВМ Docker (иначе отказ до стенда);
- ячейка — конфигурация × повтор (3), каждая на свежем стенде: 20
пользователей, читаемый чат из 10 000 сообщений, 10 чатов записи,
`VACUUM (ANALYZE)`, `CHECKPOINT`; порядок ячеек — круги с
перемешиванием;
- нагрузка — открытая модель через HAProxy (генератор на stdlib,
несколько процессов): 70 % страниц истории (`limit=50`, курсор из пула),
20 % отправок с новым ключом, 10 % `GET /users/me`; задержка — от
момента по расписанию (без coordinated omission);
- ступень — прогрев 10 с с нуля или 5 с подъёма, окно 15 с; сначала 250 и
500 запросов/с, затем поиск R*: лестница `100 × 1,25^i` от 300 ×
реплик, подъём до первой нарушившей, два деления по среднему
геометрическому (разрешение ≈ 5,7 %);
- SLO ступени: p95 успешных ≤ 200 мс и (ошибки + неполные страницы +
недосланные) ≤ 1 %; R* — наибольший прошедший уровень поиска;
- сэмплер раз в секунду: CPU, троттлинг и память каждого контейнера
(cgroup), занятость ВМ, статистика HAProxy, соединения и счётчики
PostgreSQL; признаки узкого места с порогами, заданными до замеров
(`THRESHOLDS` в [bench/analysis.py](bench/analysis.py)): `app`,
`db_cpu`, `db_lock`, `pool`, `churn`, `lb`, `host`, `generator`.
Серии: `a` — бюджет 4 CPU / 2 ГиБ: 1 × 4, 2 × 2, 4 × 1; `b` — 1, 2, 3, 4
реплики по 1 CPU; `db` — те же реплики 1, 2, 4 при PostgreSQL 0,5 CPU
(управляемое насыщение общей зависимости); `ab` — «до/после» улучшения
и A/A.
Калибровка до записи гипотез (самопроверка `make bench-scaling-quick` на
машине разработки Apple M3 Pro, 1 000 сообщений и окна по 6 с; метки
самопроверок в git не идут и результатом не являются): R*(1 × 1) ≈ 530/с,
R*(2 × 1) ≈ 830/с; на первой нарушившей ступени — `app` и `pool`, у 2 × 1
ещё `churn`; CPU PostgreSQL ≈ 0,4 мс на запрос на 200/с.
**Гипотезы** (записаны до замеров; итог — отдельным абзацем под каждой,
формулировки не меняются):
- **H1. Фиксированный бюджет (серия `a`).** Один процесс uvicorn с одним
event loop занимает не больше одного ядра (GIL; Argon2id в потоках —
только при входе, вне ступеней). Поэтому R*(1 × 4) ≈ R*(1 × 1) (из
серии `b`), а 2 × 2 и 4 × 1 растут почти пропорционально числу
процессов, пока не упрутся в общий ресурс.
- Подтвердит: R*(1 × 4) / R*(1 × 1) ∈ [0,85; 1,25]; CPU реплики 1 × 4
на ступени R* (`api_cpu_max`) ≤ 1,3 ядра; R*(2 × 2) ≥ 1,6 × R*(1 × 1);
R*(4 × 1) ≥ 2,8 × R*(1 × 1) **или** на первой нарушившей у 4 × 1 есть
признак общего ресурса (`db_cpu`, `pool`, `churn`, `lb`, `host`).
- Опровергнет: R*(1 × 4) ≥ 1,25 × R*(1 × 1) или `api_cpu_max` 1 × 4
≥ 1,5 ядра; R*(2 × 2) < 1,6 × R*(1 × 1) без признака общего ресурса.
- Итог: TODO (Codex).
- **H2. Рост ресурсов (серия `b`, PostgreSQL 2 CPU).** R* растёт с
числом реплик, ограничение каждой ступени — CPU своей реплики (`app`);
до 4 реплик общий ресурс не насыщается: по калибровке PostgreSQL
тратит ≈ 0,4 мс CPU на запрос, и 2 ядра хватает до ≈ 4 000–5 000/с.
- Подтвердит: эффективность R*(4) / (4 × R*(1)) ≥ 0,7; на первой
нарушившей ступени при k ≤ 4 есть `app` и нет `db_cpu` в ≥ 2 из 3
повторов; CPU PostgreSQL на R*(4) < 1,7 ядра.
- Опровергнет: R*(4) < 1,25 × R*(3) (насыщение уже в серии `b`) или
`db_cpu` / `lb` / `host` на первой нарушившей при k ≤ 4 — тогда
точка насыщения найдена в серии `b`, и её признак называет узкое
место.
- Итог: TODO (Codex).
- **H3. Насыщение PostgreSQL (серия `db`, 0,5 CPU).** С общим
PostgreSQL на 0,5 CPU рост реплик перестаёт помогать после двух:
запросы ждут базу, а не CPU реплик. Под очередью к базе пул реплики
выходит за 10 соединений, и соединения переполнения переоткрываются
(`churn`), отнимая у насыщенной базы ещё CPU на новые сессии.
- Подтвердит: R*(4 × 1) < 1,2 × R*(2 × 1); на первой нарушившей при
k ≥ 2 — `db_cpu` (CPU PostgreSQL ≥ 0,425 ядра) в ≥ 2 из 3 повторов;
CPU реплик на этой ступени < 0,85 ядра (`api_cpu_max`); у 4 × 1 —
`churn` (≥ 20 новых сессий PostgreSQL за окно) в ≥ 2 из 3.
- Опровергнет: R*(4 × 1) ≥ 1,2 × R*(2 × 1) или `db_cpu` нет — база не
узкое место даже на 0,5 CPU.
- Итог: TODO (Codex).
- **H4. Улучшение: пул без переполнения** (снимается, только если у
`4x1-pg0.5` есть `churn` в ≥ 2 из 3 ячеек; иначе выбор улучшения —
решение пользователя, `bench/RUNBOOK.md`, шаг 4). Изменение — одно
значение по умолчанию: `DB_POOL_OVERFLOW` 5 → 0 (`src/config.py`).
Механизм: `QueuePool` SQLAlchemy закрывает возвращённое соединение,
если в пуле уже `pool_size` свободных, поэтому соединения сверх 10
живут, только пока заняты, и под нагрузкой открываются снова и снова;
каждое новое — процесс PostgreSQL, аутентификация SCRAM-SHA-256 на
стороне базы и PBKDF2 на стороне asyncpg. Без переполнения запрос ждёт
свободное соединение (`DB_POOL_TIMEOUT` 5 с), но база не тратит CPU на
новые сессии.
- Предсказание для `4x1-pg0.5`: R* после / до ≥ 1,118 (две ступени
сетки), вывод `compare.py` с A/A — «эффект»; новых сессий за окно на
первой нарушившей «после» ≤ 5 («до» ≥ 20); CPU PostgreSQL на запрос на
R* «после» меньше, чем «до».
- Контроль `4x1` (PostgreSQL 2 CPU, узкое место — реплики): |Δ R*| меньше
двух ступеней.
- Подтвердит: всё для `4x1-pg0.5` и контроль в пределах; шум A/A
меньше двух ступеней. Опровергнет: разбросы пересекаются, Δ не больше
шума A/A или меньше двух ступеней; переоткрытие не исчезло.
- Цена: под перегрузкой запросы ждут пул, а не открывают соединения;
после 5 с ожидания — 503. Соединений на реплику — не больше 10.
- Итог: TODO (Codex).
**Результаты:** TODO (Codex): R* по конфигурациям (медиана, min–max) из
`summary.md` серий, графики `evidence/plots/scaling/rstar-by-config.svg`,
`rstar-by-replicas.svg`, `p95-by-rate.svg` и `cpu-by-component.svg`
серий; точка насыщения и признак, который её называет; таблица
`evidence/compare/scaling-ab-before__scaling-ab-after.md` и вывод по H4.
## 5. Ограничения
- Один Docker-хост, один HAProxy, одна PostgreSQL, один Valkey.
Выдерживается отказ процесса API (любой одной реплики при ≥ 2 живых);
не выдерживается отказ хоста, LB и PostgreSQL. Отказ Valkey —
деградация до PostgreSQL, не отказ.
- Отказ при `kill` и `pause`: запрос, который уже ушёл на реплику, LB не
повторяет (POST не идемпотентны). Клиент получает 502/504 и обязан
повторить отправку с тем же ключом — так делает `tests/resilience.py` и
генератор стенда.
- Остановка без вывода из LB (`stop-one.sh`, `docker stop`) имитирует
отказ: на гонке закрытия keep-alive возможен одиночный 502. Плановая
замена (`rolling-update.sh`) сначала выводит реплику (`drain`).
- Окно запуска интерпретатора до раннего обработчика SIGTERM — десятки
миллисекунд: сигнал в нём теряется (PID 1). Скрипт замены убирает
такую реплику `docker rm -f`.
- Просроченные ключи идемпотентности не удаляются сами: занятый заново
ключ заменяется, остальные копятся. Уборка — `DELETE FROM
idempotency_keys WHERE created_at < now() - interval '24 hours'` по
индексу `created_at` (учебному стенду не нужна).
- Порядок истории между репликами — по часам ВМ одного хоста; на разных
хостах понадобился бы источник порядка в базе.
- Замеры — на одном ноутбуке, все компоненты делят его CPU; лимиты
cgroup не привязаны к производительным ядрам. Числа разных машин рядом
не ставятся.
- TODO (Codex): ограничения, обнаруженные при замерах (хост,
`generator_bound`, конфигурации, не поместившиеся в ВМ).
## 6. Ответы на вопросы защиты
**Чем отказ процесса отличается от отказа узла?** Отказ процесса
(реплика остановлена или убита) оставляет хост, сеть, LB и хранилища
живыми: HAProxy перестаёт получать ответы проверок от одной реплики и за
1,5–6,5 с выводит её, остальные обслуживают запросы. Отказ узла уносит
всё, что на нём: здесь на одном хосте и LB, и PostgreSQL, и все реплики —
стенд его не переживает (раздел 5).
**Почему `depends_on`/healthcheck сами по себе не являются
балансировщиком?** `depends_on` упорядочивает только старт контейнеров,
healthcheck меняет лишь статус контейнера в Docker: запросы клиента они
не распределяют и не перенаправляют. Распределение, исключение
неготовой реплики и повтор при отказе соединения делает HAProxy со
своими проверками `/health/ready`.
**Какие POST можно повторять после timeout и что защищает
`Idempotency-Key`?** Только отправку сообщения — с тем же ключом и тем же
телом: сервер вернёт то же сообщение, если первая попытка
зафиксировалась, или создаст его один раз, если нет (ключ и сообщение в
одной транзакции). `POST /users` и `POST /chats` ключ не защищает: повтор
может создать второй объект, поэтому ни LB, ни API их прозрачно не
повторяют. Ключ защищает от дублей при неопределённом результате
(таймаут, обрыв, 5xx, переключение реплики), но не от другого тела с тем
же ключом — это 409.
**Что сломается при увеличении числа API, если сессии находятся в
локальной памяти?** Токен, выданный одной репликой, другие не знают:
round-robin отправит следующий запрос на другую реплику — 401, хотя вход
был; logout отзовёт сессию только в одной реплике; рестарт реплики
выкинет её пользователей. Лечить это sticky session — значит
привязать пользователя к процессу и потерять его сессию при отказе этого
процесса. Поэтому сессии — в PostgreSQL.
## 7. Что ещё проверить на защите
- `make lb-stats` — слоты HAProxy, состояния `UP`/`DOWN`, повторы.
- `docker compose logs haproxy` — строки `Server api/api-N is DOWN` и
`is UP` во время `make test-failover`.
- Таблица ключей: `docker compose exec postgres psql -U … -c "\d
idempotency_keys"` ([вывод](evidence/stand/migrations.txt)).
## 8. Источники и помощь ИИ
- Документация: [HAProxy 3.4 Configuration Manual](https://docs.haproxy.org/3.4/configuration.html)
(server-template, resolvers, http-check, retry-on, http-reuse, runtime
API), [Compose file reference](https://docs.docker.com/reference/compose-file/),
[PostgreSQL INSERT … ON CONFLICT](https://www.postgresql.org/docs/18/sql-insert.html),
[SQLAlchemy pooling](https://docs.sqlalchemy.org/en/21/core/pooling.html),
[uvicorn settings](https://www.uvicorn.org/settings/),
[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110) (семантика повторов),
draft IETF «The Idempotency-Key HTTP Header Field».
- Библиотеки: FastAPI, Starlette, uvicorn, pydantic, SQLAlchemy,
asyncpg, alembic, argon2-cffi, redis-py; тесты — pytest, httpx;
генератор нагрузки, сэмплер, оркестратор стенда и графики — только
стандартная библиотека Python.
- Помощь ИИ: Claude (Anthropic) — перенос кода из лабы 2, реализация
`X-Instance-Id`, идемпотентности, раннего обработчика SIGTERM, стенда
compose с HAProxy, скриптов отказа и замены, тестов, нагрузочного
стенда и черновиков документации; Codex (OpenAI) — замеры по
`bench/RUNBOOK.md` и их разбор. Все числа в отчёте — из файлов
`evidence/`, снятых командами, указанными в их шапках; решения
проверены тестами и вручную.
+13
View File
@@ -0,0 +1,13 @@
# Миграции alembic; правила — migrations/AGENTS.md.
# URL подключения migrations/env.py собирает из тех же переменных DB_*,
# что и приложение (src/config.py), поэтому sqlalchemy.url здесь нет.
# Секций logging тоже нет: журнал идёт текстовым форматом src/log.py.
[alembic]
script_location = %(here)s/migrations
# имя ревизии: <номер>_<slug>.py, номер задаётся при создании (--rev-id)
file_template = %%(rev)s_%%(slug)s
truncate_slug_length = 40
# импорт src из корня репозитория и из /app в образе
prepend_sys_path = .
path_separator = os
+190
View File
@@ -0,0 +1,190 @@
# bench/ — нагрузочный стенд лабы 3
Нужен для трёх вещей из `README.md`:
- уровень «4»: поочерёдный отказ каждой реплики под нагрузкой — RPS,
ошибки, время восстановления (профиль `failover`);
- уровень «4»: поочерёдная замена (rolling update) под нагрузкой,
миграция однократно и совместима с работающей версией (профиль
`rollout`);
- уровень «5», трек 1 «Цена масштабирования»: серии конфигураций реплик
и лимитов, точка насыщения, одно подтверждённое улучшение (`scaling`).
Порядок работы по шагам — `bench/RUNBOOK.md`. Здесь — правила, которые
действуют на каждом шаге. Стенд лабы 2 (матрица 10k/100k/500k, EXPLAIN,
восстановление из backup) и его метки остались в репозитории лабы 2:
другая задача и другая методика, их числа сюда не переносятся.
## Что есть
| Файл | Команда | Что делает |
|---|---|---|
| `run.py` | `make bench-failover`, `bench-rollout`, `bench-scaling SERIES=…`, `*-quick` | оркестратор: стенд, профили, файлы метки |
| `common.py` | — | docker, стенд compose `vlad-bench`, паспорт, хост, бюджет, контекст «нового» образа для `rollout` |
| `analysis.py` | `uv run python bench/analysis.py --selftest` | разбор без docker: журналы запросов, события Docker, журнал HAProxy, агрегаты сэмплера, признаки узкого места (`THRESHOLDS`), автомат поиска R* (`Search`) |
| `loadgen.py` | — (его вызывает `run.py` через `docker exec`) | генератор на stdlib: открытая модель, несколько процессов; `setup`, `step` (ступень смеси), `constant` (постоянная интенсивность с журналом каждого запроса), `retry` (повтор неуспешных записей с тем же ключом) |
| `sampler.py` | — (контейнер `vlad-bench-sampler`) | раз в секунду: cgroup каждого контейнера (CPU, троттлинг, память), CPU ВМ; в режиме `list` ещё статистика HAProxy и `pg_stat_activity` / `pg_stat_database` |
| `compare.py` | `make bench-compare BEFORE= AFTER= [AA=]` | «до/после» серий по общим конфигурациям, шум A/A, вывод «эффект / шум / в пределах разрешения» |
| `plots.py` | `make bench-plots LABELS="…" [PLOTS=…]` | SVG: R* по конфигурациям, R* от числа реплик с линией линейного роста, сводка и точка насыщения |
| `bench.compose.yml`, `bench.env` | — | override стенда: имена, лимиты `BENCH_*`, реплики, без портов, без swap |
Профили и серии (поля — `PROFILES` и `SERIES` в `run.py`, целиком в `meta.json`):
| Профиль / серия | Что | Время |
|---|---|---|
| `failover` | 2 реплики с лимитами рабочего стенда, 100 записей с ключом + 100 чтений/с; каждая реплика в режимах `stop`, `kill`, `pause` с возвратом (6 фаз) | ~6 мин |
| `rollout` | та же нагрузка; `scripts/rolling-update.sh` меняет обе реплики на образ с expand-ревизией `9001_rollout_probe` | ~3 мин |
| `scaling` `a` | бюджет 4 CPU / 2 ГиБ: 1 × 4, 2 × 2, 4 × 1 | ~45 мин |
| `scaling` `b` | реплики по 1 CPU: 1, 2, 3, 4 | ~60 мин |
| `scaling` `db` | PostgreSQL 0,5 CPU при 1, 2, 4 репликах — управляемое насыщение общей зависимости | ~45 мин |
| `scaling` `ab` | ячейки «до/после» улучшения и A/A (`CONFIGS`) | ~30 мин на метку |
| `*-quick`, `scaling` `quick` | самопроверка стенда; метки `quick-*` в отчёт не идут (`.gitignore`) | 1,5–4 мин |
Стенд — свой проект compose `vlad-bench`: тот же `compose.yaml` с
override `bench.compose.yml` и подстановками `bench.env`, а не `.env`
рабочего стенда. Контейнеры: `vlad-bench-postgres`, `vlad-bench-valkey`,
`vlad-bench-lb` (HAProxy с рабочим `infra/haproxy/haproxy.cfg`), реплики
`vlad-bench-api-N`, генератор `vlad-bench-gen` (базовый образ
`Dockerfile`), сэмплер `vlad-bench-sampler` (образ приложения,
`--cgroupns host`), сеть `vlad-bench-net`. Генератор ходит только через
LB (`http://haproxy:8080`), при одной реплике тоже: серии сравнивают
конфигурации на одном пути запроса. Каждая ячейка серии и каждый
профиль — свежий стенд: `down -v`, хранилища, миграции, реплики, LB.
Файлы меток:
- `evidence/failover/<метка>/`: `summary.md`, `phases.csv` (строка на фазу:
обнаружение, возврат в LB, ошибки по окнам, восстановление, RPS, p95,
повтор и сверка), `timeline.csv` (посекундно от действия),
`resources.csv` (CPU и память по окнам фазы), `meta.json`, `raw/`
(события Docker, журнал HAProxy, журнал запросов `.csv.gz`);
- `evidence/rollout/<метка>/`: `summary.md`, `windows.csv` (до / во время /
после), `timeline.csv` (ответы старых и новых реплик по секундам),
`resources.csv`, `meta.json` (раздел `rollout`: реплики, образы,
ревизия схемы до и после, события контейнеров, проверки), `raw/`
(строки скрипта, журнал LB, события, запросы);
- `evidence/scaling/<метка>/`: `summary.md`, `runs.csv` (строка на
ступень), `searches.csv` (строка на ячейку), `samples.csv` (посекундно
по контейнерам в окнах ступеней), `stand.json` (паспорт хранилищ),
`p95-by-rate.svg`, `cpu-by-component.svg`, `meta.json` (план ячеек,
бюджет, пороги, код, пул приложения), `raw/` (итог генератора каждой
ступени);
- `evidence/compare/<до>__<после>.md` — `compare.py`;
`evidence/plots/<имя>/` — `plots.py`.
Хеш кода `src_sha256` (по `src/` и `migrations/` **внутри образа**) и пул
приложения по умолчанию (`app_defaults`) — в паспорте метки. Образ метки
`mtusi-messenger-vladimirceva:bench-<метка>` остаётся в docker; образы
`quick-*` стенд удаляет.
## Методика не меняется между метками
Метки сравнимы, только если между ними различается код приложения
(одно изменение) и больше ничего. Не меняются:
- **машина и сессия**: «до», A/A и «после» — на одной машине, подряд, без
перезагрузки и без другой нагрузки; рабочий стенд остановлен (`make
stop`), посторонних контейнеров нет. Числа с другой машины рядом не
ставятся;
- **профиль** (`run.py`): лимиты (PostgreSQL 2 CPU / 1 ГиБ, HAProxy 1 /
256 МиБ, Valkey 0,5 / 128 МиБ, генератор 2 / 1 ГиБ, сэмплер 0,25 /
256 МиБ, реплика — 512 МиБ на CPU, без swap), данные (пользователи,
читаемый чат, чаты записи), смесь 70/20/10, ступени и окна, SLO,
лестница и деления поиска, порог досрочного выхода, зерно порядка
ячеек. Новый параметр методики — поле профиля, а не константа в коде;
- **хранилища и LB**: те же пины образов, что у рабочего стенда, тот же
`haproxy.cfg` и `valkey.conf`; PostgreSQL — настройки образа плюс
`max_connections` из конфигурации (по умолчанию 100);
- **приложение**: значения по умолчанию `src/config.py`, окружение
стенда — только срок сессии (`stand.json`, `app_env`). Изменение пула
или другой настройки для «до/после» — правка значения по умолчанию в
коде, а не окружение стенда: иначе `src_sha256` не отличит метки;
- **генератор и сэмплер**: `loadgen.py`, `sampler.py`, их лимиты.
Поменял что-то из списка — новая методика: метки переснимаются, в
`REPORT.md` — что и почему. Нельзя менять профиль, чтобы результат
выглядел лучше. `--configs` у серий `a`, `b`, `db` — только если
конфигурация не помещается в ВМ Docker; это пишется в паспорт и в отчёт.
## Честность результатов
- В `evidence/failover/<метка>/`, `evidence/rollout/<метка>/`,
`evidence/scaling/<метка>/` пишет только `run.py`, в
`evidence/compare/` — только `compare.py`, в `evidence/plots/` — только
`plots.py`. Руками эти файлы не править и не пересобирать из памяти.
- Каталог метки не перезаписывается. Неудачная метка (`aborted`,
предупреждения о хосте, пометки) не удаляется молча и не выдаётся за
результат: сними новую метку и скажи пользователю, почему старая не
годится. Удалять каталог метки — только с согласия пользователя.
- Числа в `REPORT.md` переносятся из `summary.md`, `*.csv` и
`compare/*.md` как есть: дельты не считать вручную, медианы не округлять
«в пользу» гипотезы.
- Гипотезы и прогнозы трека 1 записаны в `REPORT.md` **до** замеров и
после них не переписываются; итог (подтверждена, опровергнута,
частично) — отдельным абзацем ниже. Опровергнутая гипотеза — тоже
результат.
- Пороги признаков узкого места (`THRESHOLDS`) заданы до замеров. Их
изменение — смена методики (переснять серии), а не подгонка вывода.
- Проект не под git: измеренный код называет `src_sha256` в паспорте.
Если проект станет git-репозиторием, замер для отчёта — с закоммиченного
кода, коммит — только с согласия пользователя.
## Как устроен стенд (не ломать)
- Чёрный ящик: `run.py` не импортирует `src` и в приложение не ходит; все
запросы к API — генератор по HTTP через LB внутри сети стенда.
- Исключение — PostgreSQL стенда: `docker exec … psql` от пользователя
контейнера, SQL через stdin, только для обслуживания и сверки:
`VACUUM (ANALYZE)`, `CHECKPOINT`, число строк и разных текстов в чате
записи, ревизия `alembic_version`, наличие колонки пробной ревизии.
Данных, видимых приложению, оркестратор не меняет; схему меняет только
миграция приложения (профиль `rollout` — тем же
`scripts/rolling-update.sh`, что и рабочий стенд).
- Сэмплер читает cgroup всех контейнеров ВМ (`--cgroupns host`), но роли
назначает оркестратор по ID своих контейнеров; чужие в результаты не
идут. В режиме `list` у него одно соединение с PostgreSQL (слот
`max_connections`) и опрос статистики HAProxy внутри сети.
- Все вызовы compose — с `-p vlad-bench`, обоими `-f` и `--env-file
bench/bench.env`; скрипт замены получает то же через
`COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`. Без этого
`down -v` удалил бы чужой volume, а compose прочитал бы рабочий `.env`.
Пароли хранилищ — новые на прогон, никуда не пишутся.
- Пароли пользователей стенда живут только в памяти `loadgen.py setup`,
токены — в файле фикстуры внутри контейнера генератора; в stdout,
результаты и паспорт они не попадают.
- Все отметки времени — часы ВМ Docker: генератор, события Docker
(поток `docker events`, а не буфер демона), журнал HAProxy (`docker
logs -t`), сэмплер. Начало и конец скрипта замены оркестратор
переводит на часы ВМ по измеренному смещению (`clock_offset_s`).
- Только стандартная библиотека Python на хосте и в генераторе. Новых
зависимостей и образов (k6, wrk и т. п.) не добавлять.
- Один прогон за раз: блокировка `bench/.bench.lock`. Остатки
прерванного прогона `run.py` не удаляет сам: отказывается стартовать и
печатает команды уборки (только контейнеры, сеть и volume `vlad-bench*`).
- Чужие контейнеры не останавливать и не удалять; процессы по порту не
убивать.
- Столбцы `runs.csv`, `searches.csv`, `phases.csv`, `timeline.csv`,
`resources.csv` не переименовывать и не удалять: по ним сравниваются
метки и строятся графики. Новая метрика — новый столбец в конце.
## Пометки и что с ними делать
| Где | Пометка | Значит | Действие |
|---|---|---|---|
| `meta.json` | `aborted` | прогон прерван | результат частичный: серия — `RESUME=1` на том же коде; профиль — новая метка |
| `meta.json` | `host_warnings` | батарея, давление на память, посторонние контейнеры, выгрузка страниц или сон хоста во время прогона | устранить и переснять |
| `searches.csv` | `generator_bound` | на первой нарушившей ступени генератор у своего предела | R* — нижняя граница; сказать пользователю, не выдавать за предел системы |
| `searches.csv` | `stand_down:…` | хранилище или LB упали или перезапускались | ячейку не использовать, переснять серию |
| `searches.csv` | `cap` | поиск дошёл до потолка `rate_cap` | предел не найден: сказать пользователю |
| `phases.csv` | `over_bound` | обнаружение отказа дольше формулы `haproxy.cfg` | это результат, а не сбой: объяснить в отчёте |
| `phases.csv` | `verified=False` | ключей отправлено ≠ строк в базе | профиль падает сам; разбираться в дефекте, не переснимать вслепую |
## Проверка правок стенда
`make fmt && make lint`, `uv run python bench/analysis.py --selftest`,
затем самопроверки: `make bench-failover-quick` (~1,5 мин),
`make bench-rollout-quick` (~1,5 мин), `make bench-scaling-quick`
(~4 мин). Прогоны доходят до конца, `aborted` нет, в `failover` сверка
`ok`, в `rollout` все проверки `True`, в серии есть R* обеих ячеек.
Docker недоступен из sandbox — попросить пользователя запустить команду
и прислать вывод.
+326
View File
@@ -0,0 +1,326 @@
# Лаба 3: замеры уровня 4 и трек 1 — порядок работы
Документ для того, кто выполняет замеры на устройстве, где идут прогоны,
— человека или Codex. Правила стенда — `bench/AGENTS.md`, общие —
корневой `AGENTS.md`. Читать целиком до первого `make bench-*`.
**Цель — оценка «5»** (`README.md`): весь уровень 4 и законченный трек 1
«Цена масштабирования». Приложение, тесты, стенд и все проверки уровней
3 и 4, которые не требуют нагрузки, готовы и сняты (`evidence/`,
`REPORT.md`). По этому документу остаются замеры под нагрузкой, выводы и
отчёт. Код приложения меняется **только** на шаге 5 (одно улучшение,
заранее записанное в `REPORT.md`) и только по правилу этого шага.
**Что требует задание.**
- Уровень 4: «последовательно остановите каждую API-реплику (восстанавливая
предыдущую); соберите RPS, ошибки и время восстановления»; «rolling
update или эквивалентная поочерёдная замена проверена под нагрузкой.
Миграции запускаются однократно и совместимы с работающей версией».
- Трек 1: «при фиксированном суммарном CPU/RAM сравните 1/2/4 API-реплики
на одном профиле нагрузки; затем проведите серию с ростом ресурсов.
Найдите saturation point БД/LB/пула и покажите, почему рост реплик
перестаёт помогать. Дайте исходные данные, графики и одно подтверждённое
улучшение» — плюс гипотеза, повторяемая методика, результаты,
ограничения.
- `COURSE.md`: версии и образы, железо, лимиты CPU/RAM, команда запуска,
прогрев, длительность, интенсивность, успешные RPS, доля ошибок,
p50/p95/p99, CPU/RAM. Всё это стенд пишет в `meta.json` и `summary.md`.
## Словарь
- **Метка** — один прогон профиля или серии; каталог
`evidence/<failover|rollout|scaling>/<метка>/` не перезаписывается.
- **Ячейка** — конфигурация × повтор в серии: свежий стенд, данные,
ступени. **Ступень** — один запуск генератора на заданной интенсивности:
прогрев, затем окно измерения.
- **Конфигурация** — `<реплик>x<CPU реплики>[-pg<CPU PostgreSQL>]`:
`4x1-pg0.5` — 4 реплики по 1 CPU, PostgreSQL 0,5 CPU (иначе 2 CPU).
Память реплики — 512 МиБ на CPU.
- **R\*** — наибольшая интенсивность (запросов/с по расписанию), на
которой ступень держит SLO: p95 успешных ≤ 200 мс и (ошибки + неполные
страницы + недосланные) ≤ 1 %. Поиск — лестница 100 × 1,25^i, затем
два деления; разрешение ≈ 5,7 %.
- **A/A** — две метки одного кода. Их расхождение — уровень шума: сдвиг
меньше него эффектом не считается.
- **Признаки узкого места** — `app`, `db_cpu`, `db_lock`, `pool`, `churn`,
`lb`, `host`, `generator` (пороги — `THRESHOLDS` в `bench/analysis.py`,
смысл — `summary.md` серии).
## Сколько это занимает
| Шаг | Что | Время |
|---|---|---|
| 0 | подготовка, проверки, самопроверки стенда | 20–25 мин |
| 1 | уровень 4: отказ каждой реплики (`failover`) | ~6 мин + 20 мин отчёт |
| 2 | уровень 4: замена под нагрузкой (`rollout`) | ~3 мин + 15 мин отчёт |
| 3 | трек 1: серии `a`, `b`, `db` и графики | ~45 + 60 + 45 мин + 40 мин анализ |
| 4 | трек 1: выбор улучшения по записанному правилу | 15 мин |
| 5 | трек 1: «до», A/A, изменение, «после», сравнение | 3 × ~30 мин + 30 мин |
| 6 | отчёт и финальные проверки | 60 мин |
Шаги 1–5 — в одной сессии устройства, без перезагрузки. Во время
прогонов устройством не пользоваться, крышку ноутбука не закрывать
(цели `bench-*` идут под `caffeinate`, но от сна при закрытой крышке он
не спасает). Длинные команды — в фоне с журналом в файл (ниже), не в
чате.
**Точки остановки.** После шагов 0, 2, 3 и 5 — короткий отчёт
пользователю (что снято, пометки и предупреждения, главные числа) и
ожидание «продолжай». Что-то пошло не по плану (`aborted`,
`host_warnings`, упавшие проверки, `generator_bound`) — остановиться
сразу, не переснимать молча. Шаг 4 без явного «да» пользователя не
переходит в шаг 5, если правило выбора не дало однозначного ответа.
**Как запускать долгое** (Codex: команды с docker — вне sandbox, с
одобрения пользователя; корневой `AGENTS.md`, раздел 10):
```sh
nohup make bench-scaling SERIES=a > /tmp/bench-a.log 2>&1 &
tail -n 20 /tmp/bench-a.log # раз в несколько минут
```
Каждая ступень печатает строку `step … p95 … pass/FAIL [признаки]`,
каждая ячейка — `R* = …`. Прерванную серию продолжает `RESUME=1` с тем
же кодом (`make bench-scaling SERIES=a RESUME=1`).
---
## Шаг 0. Подготовка
- [ ] Docker доступен: `docker version`. Из sandbox Codex docker часто
недоступен — запроси запуск вне sandbox или попроси пользователя.
- [ ] Ресурсы ВМ Docker Desktop: `docker info --format '{{.NCPU}} CPU,
{{.MemTotal}} bytes'`. Нужно **не меньше 10 CPU и 7 ГиБ** (серии `a`
и `b`: 9,75 CPU лимитов, ~6,1 ГиБ с запасом; `failover` — 7,75 CPU,
`rollout` на пике — 8,75 CPU). Меньше — Settings → Resources в
Docker Desktop: CPU — максимум, память — 8 ГиБ, перезапуск Docker.
Если у хоста меньше 10 ядер — **сказать пользователю до замеров**:
серию `b` тогда снимают без `4x1` (`CONFIGS="1x1 2x1 3x1"`, сколько
помещается), и это ограничение пишется в отчёт.
- [ ] `make install`, `make lint`, `uv run python bench/analysis.py
--selftest` (`analysis selftest: ok`), `make test-isolated` (в
`results` все 0), `make failure-checks` (`15 passed`). Красное —
сначала разобраться (корневой `AGENTS.md`, раздел 9), замеры не
начинать.
- [ ] Рабочий стенд остановлен: `make stop`. `docker ps` — пусто. Чужие
контейнеры не останавливать: если они есть, спросить пользователя
(стенд пишет их в `host_warnings`).
- [ ] Питание от сети, свободной памяти достаточно (`memory_pressure`),
тяжёлые программы закрыты.
- [ ] Самопроверки стенда (метки `quick-*` в отчёт не идут):
```sh
make bench-failover-quick # ~1,5 мин: в таблице сверка «ok»
make bench-rollout-quick # ~1,5 мин: все проверки True, ошибок 0
make bench-scaling-quick # ~4 мин: R* у 1x1 и 2x1, без aborted
```
Смотри `summary.md` каждой метки: нет `aborted`, нет
`generator_bound`, в разделе «Предупреждения о хосте» пусто.
- [ ] Гипотезы трека 1 (H1–H4) и прогнозы уровня 4 уже записаны в
`REPORT.md`, раздел «Эксперименты», **до** замеров. Не переписывай
их; итог — отдельными абзацами «Итог: …» под каждой.
- [ ] Проект не под git: измеренный код называет `src_sha256` в паспорте.
Если пользователь сделал из проекта git-репозиторий — коммит перед
замером только с его согласия.
**Остановка:** отчёт пользователю — ресурсы ВМ, результаты проверок и
самопроверок.
## Шаг 1. Уровень 4: отказ каждой реплики под нагрузкой
```sh
nohup make bench-failover > /tmp/bench-failover.log 2>&1 &
```
Метка `baseline` (`evidence/failover/baseline/`, ~6 мин): две реплики с
лимитами рабочего стенда, 100 записей с ключом + 100 чтений в секунду,
каждая реплика в режимах `stop`, `kill`, `pause` с возвратом.
Проверь `summary.md`:
- [ ] в каждой фазе «Сверка» — `ok: N ключей = N строк`: после повтора
неуспешных записей с тем же ключом нет ни потерь, ни дублей;
- [ ] обнаружение не больше границы (2,5 с для `stop`/`kill`, 6,5 с для
`pause`); `⚠` (`over_bound`) — это результат: объясни в отчёте;
- [ ] `aborted` нет, предупреждений о хосте нет.
В `REPORT.md` (раздел «Отказ каждой реплики под нагрузкой»):
- таблица фаз из `summary.md` как есть (режим, реплика, обнаружение,
возврат в LB, ошибки по окнам и их виды, восстановление, RPS до /
во время / после, p95, max) и ссылка на метку;
- объяснение по режимам: `stop` — uvicorn закрывает сокет, LB повторяет
отказ соединения на живую реплику (ошибок нет; задержка — ожидание
`timeout connect`); `kill` — оборванные запросы, которые уже ушли на
реплику (LB их не повторяет: POST не идемпотентен), повтор клиента с
тем же ключом; `pause` — запросы на замёрзшую реплику ждут `timeout
server` (504), пока проверки не исключат её (≤ 6,5 с);
- сравнение с прогнозом (раздел гипотез) — подтвердился или нет;
- строка в таблице доказательств: критерий «поочерёдная остановка каждой
реплики: RPS, ошибки, время восстановления» → `evidence/failover/baseline/`.
## Шаг 2. Уровень 4: поочерёдная замена под нагрузкой
```sh
nohup make bench-rollout > /tmp/bench-rollout.log 2>&1 &
```
Метка `baseline` (`evidence/rollout/baseline/`, ~3 мин): та же нагрузка,
посреди неё `scripts/rolling-update.sh` меняет обе реплики на образ с
expand-ревизией `9001_rollout_probe` (колонка `messages.rollout_probe`
NULL; ревизия есть только в образе стенда).
Проверь `summary.md`:
- [ ] «Проверки» — все `True`: две новые реплики, ни одной старой, один
новый образ, ревизия `0002 → 9001`, колонка есть, сверка записей;
- [ ] код выхода скрипта 0; ответы старых реплик в окне «после» — 0;
- [ ] ошибки по окнам — сколько есть (ожидание — 0; любые ошибки
объяснить по `timeline.csv` и `raw/rollout-lb.log`).
В `REPORT.md` (раздел «Поочерёдная замена под нагрузкой»): таблица окон
и события контейнеров из `summary.md`, вывод про миграцию (один раз, до
первой новой реплики, старые реплики работали на расширенной схеме),
сравнение с прогнозом; строка в таблице доказательств.
**Остановка:** отчёт пользователю — главные числа шагов 1–2.
## Шаг 3. Трек 1: серии
Порядок — подряд, в одной сессии:
```sh
nohup make bench-scaling SERIES=a > /tmp/bench-a.log 2>&1 & # ~45 мин
nohup make bench-scaling SERIES=b > /tmp/bench-b.log 2>&1 & # ~60 мин
nohup make bench-scaling SERIES=db > /tmp/bench-db.log 2>&1 & # ~45 мин
make bench-plots LABELS="scaling-a scaling-b scaling-db" # evidence/plots/scaling/
```
Метки по умолчанию — `scaling-a`, `scaling-b`, `scaling-db`. Следующую
серию запускай только после конца предыдущей (одна блокировка стенда).
Проверь каждую `summary.md`:
- [ ] у каждой конфигурации 3 повтора и R*; нет `aborted`;
- [ ] нет `generator_bound` и `cap`; если есть — R* этой ячейки нижняя
граница: скажи пользователю, в отчёте — оговорка;
- [ ] разброс повторов (min–max) — в отчёт как есть.
Что извлечь (числа — из `summary.md` и `evidence/plots/scaling/summary.md`
как есть, без пересчёта):
- **серия `a`** (бюджет 4 CPU): R*(1 × 4), R*(2 × 2), R*(4 × 1); R*(1 × 1)
— из серии `b`. Отношение R*(1 × 4) / R*(1 × 1) и рост 2 × 2, 4 × 1.
CPU реплики 1 × 4 на ступени R* (`cpu-by-component.svg`, `runs.csv`
`api_cpu_max`) — занимает ли один процесс больше одного ядра;
- **серия `b`** (рост ресурсов): R*(k), эффективность R*(k) / (k × R*(1)),
точка насыщения по `plots.py` (следующая реплика даёт < +10 %),
признаки на первой нарушившей ступени у каждого k;
- **серия `db`** (PostgreSQL 0,5 CPU): перестаёт ли расти R* после 2
реплик; признаки `db_cpu` / `churn` / `pool`; CPU PostgreSQL на запрос
на R* и на первой нарушившей (`runs.csv`: `db_cpu_us_per_req`,
`pg_new_sessions`, `pg_conn_max`).
В `REPORT.md` (раздел «Цена масштабирования»): итог по H1, H2, H3
(подтверждена / опровергнута / частично — с числами и ссылками на
метки), графики `evidence/plots/scaling/*.svg` и `cpu-by-component.svg`
серий, объяснение «почему рост реплик перестаёт помогать» — по
признакам, а не по догадке.
**Остановка:** отчёт пользователю — R* по конфигурациям, точка
насыщения, признаки у `4x1-pg0.5`.
## Шаг 4. Трек 1: какое улучшение снимать
Правило записано в `REPORT.md` (гипотеза H4) до замеров. По `searches.csv`
метки `scaling-db`, конфигурация `4x1-pg0.5` (столбец `signals_at_fail`):
- **`churn` есть хотя бы в 2 из 3 ячеек** → улучшение H4 «пул без
переполнения»: шаг 5 как написан;
- **`churn` нет**, а есть `db_cpu` или `app` → правило не даёт
улучшения: **остановись и спроси пользователя**, приложи признаки и
числа. Кандидаты, требующие решения пользователя: другая настройка пула
(`DB_POOL_SIZE`), uvicorn с `httptools`/`uvloop` (новая зависимость —
только с согласия, корневой `AGENTS.md`, раздел 2, п. 11). Новая
гипотеза записывается в `REPORT.md` до её замеров.
## Шаг 5. Трек 1: «до», A/A, изменение, «после»
Ячейки: основная `4x1-pg0.5` (насыщенный PostgreSQL) и контрольная
`4x1` (PostgreSQL 2 CPU). Всё — подряд, в одной сессии, без перезагрузки.
1. «До» и A/A на текущем коде (пул 10 + 5):
```sh
make bench-scaling SERIES=ab SCALING_LABEL=scaling-ab-before > /tmp/bench-ab-before.log 2>&1
make bench-scaling SERIES=ab SCALING_LABEL=scaling-ab-aa > /tmp/bench-ab-aa.log 2>&1
```
У обеих меток один `src_sha256` в `meta.json` — проверь.
2. Изменение — одно значение по умолчанию в коде (окружение стенда для
этого не годится, `bench/AGENTS.md`): в `src/config.py`, класс
`Database`, `pool_overflow: int = 5` → `pool_overflow: int = 0`. Там же
обновить комментарий; в `src/AGENTS.md` — строку таблицы
`DB_POOL_OVERFLOW`; комментарий о расчёте соединений в `compose.yaml`
(2 × 10 + 1). Затем `make fmt`, `make lint`, `make test-isolated`,
`make failure-checks` — всё зелёное, иначе остановиться.
3. «После»:
```sh
make bench-scaling SERIES=ab SCALING_LABEL=scaling-ab-after > /tmp/bench-ab-after.log 2>&1
make bench-compare BEFORE=scaling-ab-before AFTER=scaling-ab-after AA=scaling-ab-aa
make bench-plots LABELS="scaling-ab-before scaling-ab-aa scaling-ab-after" PLOTS=scaling-ab
```
4. Вывод — из `evidence/compare/scaling-ab-before__scaling-ab-after.md`
как есть: «эффект», «шум» или «в пределах разрешения поиска»
(порог — две ступени сетки, R* после / до ≥ 1,118, и сдвиг больше
шума A/A). Механизм — столбцы «Новых сессий за окно на первой
нарушившей» и «PostgreSQL мкс/запрос на R*».
5. В `REPORT.md` под H4: итог по критериям, записанным до замеров
(подтверждена / опровергнута), таблица сравнения, графики. Если
эффекта нет — так и написать: опровергнутая гипотеза — тоже результат;
изменение тогда **вернуть** (`pool_overflow: int = 5`, документы,
проверки) и сказать пользователю. Если эффект есть — изменение
остаётся, `KNOWN_ISSUES.md` не трогать, в отчёте — что улучшено и
какой ценой (ожидание пула вместо новых соединений).
**Остановка:** отчёт пользователю — вывод сравнения и что с изменением.
## Шаг 6. Отчёт и проверка
- [ ] `REPORT.md`: все строки `TODO (Codex)` заменены реальными числами со
ссылками на метки; гипотезы не переписаны, итоги — отдельными
абзацами; ограничения дополнены тем, что обнаружено (хост,
`generator_bound`, конфигурации, которые не поместились).
- [ ] Таблица доказательств: у каждого критерия уровня 4 и трека 1 —
метка или файл `evidence/`.
- [ ] Корневой `AGENTS.md`: абзац «Состояние» — что снято, где результаты.
- [ ] `make lint`, `make check`, `make test-isolated` — после всех правок.
- [ ] Проверка копии без локальных файлов (как чистый clone) —
`evidence/stand/fresh-copy.txt`: обновить реальным выводом
(процедура — в шапке файла).
- [ ] Остановить всё, что запускал: `docker ps -a | grep vlad-bench` —
пусто; рабочий стенд — как был до тебя.
- [ ] Отчёт пользователю (корневой `AGENTS.md`, раздел 11).
## Чеклист готовности
- [ ] `evidence/failover/baseline/` — 6 фаз, сверка `ok` везде.
- [ ] `evidence/rollout/baseline/` — все проверки `True`.
- [ ] `evidence/scaling/scaling-a`, `-b`, `-db` — без `aborted`, по 3
повтора каждой конфигурации; `evidence/plots/scaling/`.
- [ ] `evidence/scaling/scaling-ab-before`, `-aa`, `-after` и
`evidence/compare/scaling-ab-before__scaling-ab-after.md` — или
записанное решение пользователя по шагу 4.
- [ ] `REPORT.md`: итоги H1–H4, прогнозы уровня 4, графики, ограничения.
## Если что-то пошло не так
| Симптом | Причина и что делать |
|---|---|
| `leftovers of an interrupted bench run` | прошлый прогон прерван: выполнить напечатанные команды уборки (только `vlad-bench*`), затем повторить |
| `another bench run holds bench/.bench.lock` | идёт другой прогон: дождаться (`ps aux \| grep bench/run.py`) |
| `limits need N CPU, docker VM has M` | ВМ Docker меньше лимитов: шаг 0, ресурсы; не уменьшать лимиты профиля |
| `aborted` в серии | `RESUME=1` с тем же кодом; повторилось — разбор `app-tail.log`, `raw/` |
| `generator_bound` | генератор у своего лимита: R* — нижняя граница; сказать пользователю |
| `host_warnings` | устранить причину (питание, память, посторонние контейнеры) и переснять метку новым именем |
| `verified=False` в `failover` (профиль падает) | потеря или дубль записи — дефект: остановиться, `KNOWN_ISSUES.md`, сказать пользователю |
| `rollout checks failed` | смотреть `raw/rollout-script.log` и `raw/rollout-lb.log`; повторить один раз; повторилось — остановиться |
| `make test-isolated` или `failure-checks` красные после шага 5 | изменение сломало поведение: вернуть, разобраться, без замеров «после» |
+546
View File
@@ -0,0 +1,546 @@
"""Разбор результатов стенда без docker: журналы, окна, признаки, поиск R*.
Чистые функции над строками журналов генератора, событиями Docker,
журналом HAProxy и тиками сэмплера. Их зовёт `run.py`; самопроверка —
`uv run python bench/analysis.py --selftest`. Только stdlib.
Все отметки времени — часы ВМ Docker в миллисекундах эпохи: генератор
(`time.time()` в контейнере), события Docker (`timeNano`), журнал HAProxy
(`docker logs -t`), сэмплер. Часы хоста с ними не сравниваются.
"""
import dataclasses
import datetime
import json
import math
import re
import sys
# --- журнал запросов генератора (профили failover и rollout) ----------------
@dataclasses.dataclass(frozen=True)
class Request:
scheduled: float
sent: float | None
done: float | None
kind: str
status: int
instance: str
key: str
error: str
@property
def ok(self) -> bool:
return self.status == (201 if self.kind == "write" else 200)
@property
def latency(self) -> float | None:
"""Задержка от момента по расписанию до ответа, мс."""
return None if self.done is None else self.done - self.scheduled
def parse_requests(text: str) -> list[Request]:
out = []
for line in text.splitlines():
parts = line.split(",")
if len(parts) != 9 or parts[0] != "fo":
continue
out.append(
Request(
scheduled=float(parts[1]),
sent=float(parts[2]) if parts[2] else None,
done=float(parts[3]) if parts[3] else None,
kind=parts[4],
status=int(parts[5]),
instance=parts[6],
key=parts[7],
error=parts[8],
),
)
out.sort(key=lambda r: r.scheduled)
return out
def percentile(values: list[float], fraction: float) -> float | None:
if not values:
return None
ordered = sorted(values)
return ordered[max(1, math.ceil(fraction * len(ordered))) - 1]
def error_label(request: Request) -> str:
return request.error or str(request.status)
def window_stats(requests: list[Request], start: float, end: float) -> dict:
"""Запросы окна [start, end) по моменту расписания."""
inside = [r for r in requests if start <= r.scheduled < end]
seconds = max((end - start) / 1000, 1e-9)
ok = [r for r in inside if r.ok]
errors: dict[str, int] = {}
for request in inside:
if not request.ok:
errors[error_label(request)] = errors.get(error_label(request), 0) + 1
latencies = [r.latency for r in ok if r.latency is not None]
return {
"seconds": round(seconds, 2),
"requests": len(inside),
"ok": len(ok),
"ok_rps": round(len(ok) / seconds, 1),
"ok_write_rps": round(sum(r.kind == "write" for r in ok) / seconds, 1),
"ok_read_rps": round(sum(r.kind == "read" for r in ok) / seconds, 1),
"errors": sum(errors.values()),
"error_kinds": errors,
"p50_ms": _r(percentile(latencies, 0.5)),
"p95_ms": _r(percentile(latencies, 0.95)),
"p99_ms": _r(percentile(latencies, 0.99)),
"max_ms": _r(max(latencies) if latencies else None),
}
def _r(value: float | None, digits: int = 1) -> float | None:
return None if value is None else round(value, digits)
def timeline(
requests: list[Request],
origin: float,
start: float,
end: float,
groups: dict[str, set[str]] | None = None,
) -> list[dict]:
"""Посекундная шкала от `origin`: успешные по видам, ошибки, реплики.
`groups` — именованные наборы X-Instance-Id (цель и остальные, старые
и новые): у каждого — число успешных ответов в секунду.
"""
first = math.floor((start - origin) / 1000)
last = math.ceil((end - origin) / 1000)
rows = []
for second in range(first, last):
lo, hi = origin + second * 1000, origin + (second + 1) * 1000
inside = [r for r in requests if lo <= r.scheduled < hi]
ok = [r for r in inside if r.ok]
errors: dict[str, int] = {}
for request in inside:
if not request.ok:
errors[error_label(request)] = errors.get(error_label(request), 0) + 1
latencies = [r.latency for r in ok if r.latency is not None]
row = {
"second": second,
"sent": len(inside),
"ok_write": sum(r.kind == "write" for r in ok),
"ok_read": sum(r.kind == "read" for r in ok),
"errors": sum(errors.values()),
"error_kinds": ";".join(f"{k}:{v}" for k, v in sorted(errors.items())),
"p95_ms": _r(percentile(latencies, 0.95)),
"max_ms": _r(max(latencies) if latencies else None),
}
for name, ids in (groups or {}).items():
row[f"ok_{name}"] = sum(r.instance in ids for r in ok)
rows.append(row)
return rows
def recovery_seconds(
requests: list[Request],
action: float,
end: float,
offered_per_s: float,
) -> float | None:
"""Время восстановления, с: от действия до начала первой секунды, после
которой до `end` нет ни одной ошибки и успешных не меньше 90 % от
поданной нагрузки в каждой секунде. None — не восстановилось."""
rows = timeline(requests, action, action, end)
good = [
row["errors"] == 0 and row["ok_write"] + row["ok_read"] >= 0.9 * offered_per_s
for row in rows
]
for index in range(len(good)):
if all(good[index:]):
return float(rows[index]["second"])
return None
# --- события Docker и журнал HAProxy ------------------------------------------------
def parse_events(text: str) -> list[tuple[float, str, str]]:
"""`docker events --format '{{json .}}'`: (мс, действие, id контейнера)."""
events = []
for line in text.splitlines():
line = line.strip()
if not line:
continue
data = json.loads(line)
action = data.get("Action") or data.get("status") or ""
actor = (data.get("Actor") or {}).get("ID") or data.get("id") or ""
events.append((int(data["timeNano"]) / 1e6, action.split(":")[0], actor))
events.sort()
return events
_LB_STATE = re.compile(
r"Server api/(?P<slot>api-\d+)\b.*?(?P<state>is DOWN|is UP|is going DOWN"
r"|enters drain|enters maintenance|is leaving forced drain|is leaving maintenance"
r"|administratively READY)",
)
def parse_docker_time(stamp: str) -> float:
"""RFC 3339 с наносекундами из `docker logs -t` → мс эпохи."""
stamp = stamp.rstrip("Z")
main, _, fraction = stamp.partition(".")
base = datetime.datetime.fromisoformat(main).replace(tzinfo=datetime.UTC)
return base.timestamp() * 1000 + float(f"0.{fraction or 0}") * 1000
def parse_lb_log(text: str) -> list[tuple[float, str, str]]:
"""Смены состояния слотов: (мс, слот, состояние). Дубли строк HAProxy
(мастер и воркер пишут одну и ту же) схлопываются."""
seen = set()
out = []
for line in text.splitlines():
stamp, _, message = line.partition(" ")
match = _LB_STATE.search(message)
if not match:
continue
when = parse_docker_time(stamp)
item = (round(when / 50), match.group("slot"), match.group("state"))
if item in seen:
continue
seen.add(item)
out.append((when, match.group("slot"), match.group("state")))
out.sort()
return out
def lb_http_errors(text: str) -> dict[str, int]:
"""Ответы с ошибкой в журнале HAProxy (option dontlog-normal пишет
только их): статус → число."""
counts: dict[str, int] = {}
for line in text.splitlines():
match = re.search(r'\s(\d{3}) \d+ - - (\S{4}) .*"(GET|POST) ', line)
if match and match.group(1)[0] in "45":
counts[match.group(1)] = counts.get(match.group(1), 0) + 1
return counts
# --- сэмплер ---------------------------------------------------------------------------
def window_ticks(ticks: list[dict], start: float, end: float) -> list[dict]:
"""Тики окна [start, end] (секунды эпохи) плюс по одному снаружи:
приращения считаются по краям окна."""
inside = [t for t in ticks if start <= t["ts"] <= end]
before = [t for t in ticks if t["ts"] < start]
after = [t for t in ticks if t["ts"] > end]
return ([before[-1]] if before else []) + inside + ([after[0]] if after else [])
def cgroup_usage(ticks: list[dict], container: str) -> dict | None:
"""CPU (ядер), доля троттлинга и память контейнера по тикам окна.
Каждый соседний интервал считается отдельно: новая cgroup (контейнер
перезапущен) даёт отрицательное приращение — такой интервал
пропускается, а не обнуляет окно.
"""
points = [(t["ts"], t["cg"].get(container[:12])) for t in ticks]
points = [(ts, line) for ts, line in points if line]
if len(points) < 2:
return None
cpu_us = seconds = periods = throttled = 0.0
memory = 0
for (t0, a), (t1, b) in zip(points, points[1:], strict=False):
if b[0] < a[0]:
continue
cpu_us += b[0] - a[0]
seconds += t1 - t0
periods += b[1] - a[1]
throttled += b[2] - a[2]
memory = max(memory, a[4], b[4])
if seconds <= 0:
return None
return {
"cpu_cores": round(cpu_us / seconds / 1e6, 3),
"throttled_share": round(throttled / periods, 4) if periods else 0.0,
"memory_mib": round(memory / 2**20, 1),
}
def vm_busy(ticks: list[dict]) -> float | None:
if len(ticks) < 2:
return None
busy = ticks[-1]["vm"][0] - ticks[0]["vm"][0]
total = ticks[-1]["vm"][1] - ticks[0]["vm"][1]
return round(busy / total, 4) if total else None
def lb_delta(ticks: list[dict], field: str) -> int | None:
"""Приращение счётчика HAProxy по всем слотам за окно."""
with_lb = [t for t in ticks if t.get("lb")]
if len(with_lb) < 2:
return None
def total(tick: dict) -> int:
return sum(
row.get(field, 0) for name, row in tick["lb"].items() if name != "FRONTEND"
)
return total(with_lb[-1]) - total(with_lb[0])
def pg_stats(ticks: list[dict], replica_addrs: set[str]) -> dict:
"""Соединения приложения и счётчики базы за окно."""
with_pg = [t for t in ticks if t.get("pg")]
if not with_pg:
return {}
per_tick_total, per_replica_max, active, lock_waits = [], 0, [], []
for tick in with_pg:
by_addr: dict[str, int] = {}
busy = waiting = 0
for addr, state, wait, count in tick["pg"]["conn"]:
by_addr[addr] = by_addr.get(addr, 0) + count
if state == "active":
busy += count
if wait == "Lock":
waiting += count
per_tick_total.append(sum(by_addr.values()))
known = [
n for a, n in by_addr.items() if not replica_addrs or a in replica_addrs
]
per_replica_max = max([per_replica_max, *known])
active.append(busy)
lock_waits.append(waiting)
first, last = with_pg[0]["pg"]["db"], with_pg[-1]["pg"]["db"]
seconds = max(with_pg[-1]["ts"] - with_pg[0]["ts"], 1e-9)
return {
"pg_conn_max": max(per_tick_total),
"pg_conn_replica_max": per_replica_max,
"pg_active_mean": round(sum(active) / len(active), 2),
"pg_lock_wait_mean": round(sum(lock_waits) / len(lock_waits), 2),
"pg_new_sessions": last["sessions"] - first["sessions"],
"pg_commits_per_s": round(
(last["xact_commit"] - first["xact_commit"]) / seconds, 1
),
}
# --- признаки узкого места (серии трека 1) ------------------------------------------
# Пороги заданы до прогонов (REPORT.md, гипотезы трека 1). Сработавший
# признак на первой нарушившей ступени называет, во что упёрлась система
THRESHOLDS = {
# реплика: доля своего лимита CPU или заметный троттлинг CFS
"app_cpu_share": 0.85,
"app_throttled_share": 0.20,
# PostgreSQL: доля лимита CPU, средние ожидания блокировок
"db_cpu_share": 0.85,
"db_lock_wait_mean": 1.0,
# пул: соединений одной реплики не меньше доли её предела (размер + переполнение)
"pool_share": 0.90,
# переоткрытие соединений: новых сессий PostgreSQL за окно ступени
"churn_sessions": 20,
# LB: доля его лимита CPU
"lb_cpu_share": 0.85,
# ВМ Docker занята почти целиком: реплики ждут CPU хоста
"host_busy_share": 0.90,
# генератор: доля лимита CPU или отставание от расписания
"gen_cpu_share": 0.90,
"gen_lag_p99_ms": 50.0,
}
def signals(row: dict, limits: dict, pool_cap: int) -> list[str]:
"""Признаки узкого места ступени по агрегатам `row` (см. run.py)."""
found = []
if (row.get("api_cpu_max") or 0) >= THRESHOLDS["app_cpu_share"] * limits[
"api_cpus"
] or (row.get("api_throttled_max") or 0) >= THRESHOLDS["app_throttled_share"]:
found.append("app")
if (row.get("db_cpu_cores") or 0) >= THRESHOLDS["db_cpu_share"] * limits["db_cpus"]:
found.append("db_cpu")
if (row.get("pg_lock_wait_mean") or 0) >= THRESHOLDS["db_lock_wait_mean"]:
found.append("db_lock")
if (
pool_cap
and (row.get("pg_conn_replica_max") or 0) >= THRESHOLDS["pool_share"] * pool_cap
):
found.append("pool")
if (row.get("pg_new_sessions") or 0) >= THRESHOLDS["churn_sessions"]:
found.append("churn")
if (row.get("lb_cpu_cores") or 0) >= THRESHOLDS["lb_cpu_share"] * limits["lb_cpus"]:
found.append("lb")
if (row.get("vm_busy_share") or 0) >= THRESHOLDS["host_busy_share"]:
found.append("host")
if (
(row.get("gen_cpu_cores") or 0)
>= THRESHOLDS["gen_cpu_share"] * limits["gen_cpus"]
or (row.get("lag_p99_ms") or 0) >= THRESHOLDS["gen_lag_p99_ms"]
or (row.get("dropped") or 0) > 0
):
found.append("generator")
return found
# --- поиск R* ---------------------------------------------------------------------------
@dataclasses.dataclass
class Search:
"""Автомат поиска R*: наибольшей интенсивности, на которой ступень
выдерживает SLO.
Сначала фиксированные уровни (сравнение конфигураций на одной
нагрузке), затем лестница `base × factor^i`: начало — первая ступенька
не ниже `start`, подъём до первой нарушившей (если нарушена первая —
спуск до первой прошедшей), затем `bisections` делений интервала
«прошла — нарушила» по среднему геометрическому, с округлением до
целого. R* — наибольшая прошедшая ступень поиска.
"""
fixed: tuple[float, ...]
base: float
factor: float
start: float
bisections: int
cap: float
floor: float = 25.0
results: list[tuple[float, bool, str]] = dataclasses.field(default_factory=list)
def ladder(self, rate: float) -> float:
steps = math.ceil(math.log(rate / self.base, self.factor) - 1e-9)
return round(self.base * self.factor ** max(steps, 0))
def record(self, rate: float, passed: bool, phase: str) -> None:
self.results.append((rate, passed, phase))
def next_rate(self) -> tuple[float, str] | None:
done_fixed = [r for r in self.results if r[2] == "fixed"]
if len(done_fixed) < len(self.fixed):
return self.fixed[len(done_fixed)], "fixed"
search = [r for r in self.results if r[2] != "fixed"]
passed = [rate for rate, ok, _ in search if ok]
failed = [rate for rate, ok, _ in search if not ok]
if not search:
fixed_pass = [rate for rate, ok, _ in done_fixed if ok]
start = max([self.start, *fixed_pass])
return min(self.ladder(start), self.cap), "ladder"
phase = search[-1][2]
if phase == "ladder":
last_rate, last_ok, _ = search[-1]
if last_ok and not failed:
if last_rate >= self.cap:
return None
return min(round(last_rate * self.factor), self.cap), "ladder"
if not last_ok and not passed:
lower = round(last_rate / self.factor)
return (lower, "ladder") if lower >= self.floor else None
# интервал найден: деления
if not passed or not failed:
return None
bisections = sum(1 for r in search if r[2] == "bisect")
if bisections >= self.bisections:
return None
lo = max(passed)
hi = (
min(rate for rate in failed if rate > lo)
if any(r > lo for r in failed)
else None
)
if hi is None:
return None
middle = round(math.sqrt(lo * hi))
if middle <= lo or middle >= hi:
return None
return middle, "bisect"
def r_star(self) -> float | None:
passed = [rate for rate, ok, phase in self.results if ok and phase != "fixed"]
return max(passed) if passed else None
def first_fail(self) -> float | None:
r_star = self.r_star() or 0
failed = [
rate for rate, ok, phase in self.results if not ok and phase != "fixed"
]
above = [rate for rate in failed if rate > r_star]
return min(above) if above else None
# --- самопроверка ---------------------------------------------------------------------
def _selftest() -> None:
# поиск: подъём, нарушение, два деления
search = Search(
fixed=(250, 500), base=100, factor=1.25, start=600, bisections=2, cap=8000
)
capacity = 1000
plan = []
while (step := search.next_rate()) is not None:
rate, phase = step
plan.append((rate, phase))
search.record(rate, rate <= capacity, phase)
assert plan[:2] == [(250, "fixed"), (500, "fixed")], plan
# лестница 100 × 1,25^i: первая ступенька не ниже 600 — 745
assert plan[2] == (745, "ladder"), plan
assert search.r_star() is not None, plan
assert search.r_star() <= capacity, plan
assert search.first_fail() > capacity, plan
assert sum(phase == "bisect" for _, phase in plan) == 2, plan
# первая ступень поиска нарушена — спуск
search = Search(fixed=(), base=100, factor=1.25, start=300, bisections=1, cap=8000)
plan = []
while (step := search.next_rate()) is not None:
plan.append(step)
search.record(step[0], step[0] <= 200, step[1])
assert plan[0] == (305, "ladder"), plan
assert plan[1] == (244, "ladder"), plan
assert search.r_star() <= 200, plan
# окно и время восстановления
reqs = [
Request(
1000 + i * 10, 1000 + i * 10, 1005 + i * 10, "write", 201, "a", f"k{i}", ""
)
for i in range(500)
]
reqs[200] = dataclasses.replace(reqs[200], status=502)
stats = window_stats(reqs, 1000, 6000)
assert stats["errors"] == 1, stats
assert stats["ok"] == 499, stats
assert recovery_seconds(reqs, 1000, 6000, 100) == 3.0
rows = timeline(reqs, 1000, 1000, 6000, {"a": {"a"}})
assert rows[2]["errors"] == 1, rows[:3]
assert rows[0]["ok_a"] == 100, rows[:3]
# сэмплер: приращения, перезапуск контейнера
ticks = [
{"ts": 0.0, "cg": {"abc": [0, 0, 0, 0, 100]}, "vm": [0, 100]},
{"ts": 1.0, "cg": {"abc": [500_000, 10, 1, 0, 200]}, "vm": [50, 200]},
{"ts": 2.0, "cg": {"abc": [100_000, 2, 0, 0, 50]}, "vm": [60, 300]},
{"ts": 3.0, "cg": {"abc": [600_000, 12, 0, 0, 80]}, "vm": [160, 400]},
]
usage = cgroup_usage(ticks, "abc")
assert usage["cpu_cores"] == 0.5, usage
assert vm_busy(ticks) == 0.5333, vm_busy(ticks)
# журнал LB: дубли схлопываются
log = (
"2026-10-14T10:00:00.100000000Z Server api/api-1 is DOWN, reason: x\n"
"2026-10-14T10:00:00.101000000Z [WARNING] (8) : Server api/api-1 is DOWN, reason: x\n"
"2026-10-14T10:00:03.000000000Z Server api/api-1 is UP, reason: y\n"
)
parsed = parse_lb_log(log)
assert [p[2] for p in parsed] == ["is DOWN", "is UP"], parsed
print("analysis selftest: ok")
if __name__ == "__main__":
if sys.argv[1:] == ["--selftest"]:
_selftest()
else:
print("usage: python bench/analysis.py --selftest", file=sys.stderr)
sys.exit(2)
+73
View File
@@ -0,0 +1,73 @@
# Override нагрузочного стенда (bench/run.py): тот же compose.yaml под
# проектом vlad-bench, со своими volume, сетью, именами и лимитами. Пины
# хранилищ и LB, healthcheck хранилищ, valkey.conf, haproxy.cfg и
# миграции — из основного файла. Подстановки — bench/bench.env, а не .env
# рабочего стенда; пароли, образ и BENCH_* передаёт run.py (поля профиля),
# без них стенд не поднимается. Что не меняется между метками —
# bench/AGENTS.md.
#
# Лимиты — в той же форме deploy.resources.limits, что у основного файла:
# cpus / mem_limit рядом с ними compose не принимает. Swap выключен
# (memswap_limit = memory). Портов на хост нет: генератор и сэмплер ходят
# внутри сети vlad-bench-net.
services:
postgres:
container_name: vlad-bench-postgres
# упавший контейнер не поднимается сам: прогон помечается stand_down
restart: "no"
command: ["postgres", "-c", "max_connections=${BENCH_DB_MAX_CONNECTIONS:?run make bench-*}"]
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_DB_CPUS:?run make bench-*}
memory: ${BENCH_DB_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_DB_MEMORY:?run make bench-*}
valkey:
container_name: vlad-bench-valkey
restart: "no"
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_CACHE_CPUS:?run make bench-*}
memory: ${BENCH_CACHE_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_CACHE_MEMORY:?run make bench-*}
migrate:
image: ${BENCH_IMAGE:?run make bench-*}
# реплики без container_name: их число — BENCH_API_REPLICAS (--scale)
api:
image: ${BENCH_IMAGE:?run make bench-*}
restart: "no"
# проверка образа — второй процесс Python раз в несколько секунд в квоте
# CPU реплики; готовность и так проверяет LB раз в секунду
healthcheck:
disable: true
environment:
SESSION_TTL_SECONDS: ${BENCH_SESSION_TTL:?run make bench-*}
deploy:
replicas: ${BENCH_API_REPLICAS:?run make bench-*}
resources:
limits:
cpus: ${BENCH_API_CPUS:?run make bench-*}
memory: ${BENCH_API_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_API_MEMORY:?run make bench-*}
haproxy:
container_name: vlad-bench-lb
restart: "no"
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_LB_CPUS:?run make bench-*}
memory: ${BENCH_LB_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_LB_MEMORY:?run make bench-*}
networks:
default:
# генератор и сэмплер подключаются к сети стенда по имени
name: vlad-bench-net
+7
View File
@@ -0,0 +1,7 @@
# Подстановки compose для нагрузочного стенда вместо .env рабочего стенда
# (docker compose --env-file bench/bench.env). Только несекретные имена:
# пароли генерирует bench/run.py на каждый прогон, лимиты, образ, число
# реплик и срок сессии приходят из профиля (BENCH_*).
POSTGRES_USER=bench
POSTGRES_DB=bench
LOG_LEVEL=INFO
+867
View File
@@ -0,0 +1,867 @@
"""Общее для профилей стенда: docker, стенд compose, паспорт, хост.
Импортируют `run.py`, `compare.py` и `plots.py`; сам по себе не
запускается. Только стандартная библиотека.
Все вызовы compose — с `-p vlad-bench`, обоими `-f` и `--env-file
bench/bench.env`: рабочий стенд и его `.env` не затрагиваются. Пароли
хранилищ генерируются на прогон и никуда не пишутся. Свои контейнеры —
`vlad-bench-*`; чужие стенд не останавливает и не удаляет.
"""
import dataclasses
import datetime
import fcntl
import json
import os
import platform
import re
import secrets
import shutil
import subprocess
import sys
import tempfile
import time
from contextlib import contextmanager
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
BENCH = ROOT / "bench"
EVIDENCE = ROOT / "evidence"
IMAGE_REPO = "mtusi-messenger-vladimirceva"
# тег, на который смотрит сервис api стенда (BENCH_IMAGE); профиль rollout
# переставляет его со старого образа на новый
SERVICE_TAG = f"{IMAGE_REPO}:bench"
PROJECT = "vlad-bench"
NET = "vlad-bench-net"
DB = "vlad-bench-postgres"
CACHE = "vlad-bench-valkey"
LB = "vlad-bench-lb"
GEN = "vlad-bench-gen"
SAMPLER = "vlad-bench-sampler"
NAMED = (DB, CACHE, LB, GEN, SAMPLER)
COMPOSE_FILES = (ROOT / "compose.yaml", BENCH / "bench.compose.yml")
ENV_FILE = BENCH / "bench.env"
LOCK = BENCH / ".bench.lock"
# что из окружения хоста нужно самому docker compose; остальное (в том
# числе POSTGRES_* из shell) в стенд не попадает
HOST_ENV = ("PATH", "HOME", "USER", "TMPDIR", "LANG", "DOCKER_HOST", "DOCKER_CONFIG")
LB_URL = "http://haproxy:8080"
LABEL_RE = re.compile(r"[A-Za-z0-9._-]{1,48}")
# фикстура генератора: токены пользователей стенда живут только в его контейнере
FIXTURE = "/tmp/bench-fixture.json"
# psql в контейнере PostgreSQL от пользователя образа, без пароля; SQL — stdin
PSQL = 'exec psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq -v ON_ERROR_STOP=1'
# статистика HAProxy изнутри его контейнера (curl в образе нет, bash есть)
LB_STATS_CMD = (
"exec 3<>/dev/tcp/127.0.0.1/8404 && "
"printf 'GET /stats;csv HTTP/1.0\\r\\n\\r\\n' >&3 && cat <&3"
)
PG_SETTINGS = (
"shared_buffers",
"max_connections",
"synchronous_commit",
"fsync",
"wal_level",
"checkpoint_timeout",
"max_wal_size",
"jit",
"password_encryption",
)
class StandError(Exception):
pass
def say(text: str) -> None:
stamp = datetime.datetime.now().strftime("%H:%M:%S")
print(f"[{stamp}] {text}", flush=True)
def utc_now() -> str:
return datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
def sh(
cmd: list[str],
*,
check: bool = True,
timeout: float | None = None,
env: dict[str, str] | None = None,
stdin: str | None = None,
):
done = subprocess.run(
cmd,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=timeout,
check=False,
cwd=ROOT,
env=env,
input=stdin,
)
if check and done.returncode != 0:
tail = (done.stderr or done.stdout).strip().splitlines()[-15:]
raise StandError(
f"{' '.join(cmd[:4])}... exit {done.returncode}\n" + "\n".join(tail)
)
return done
def docker(*args: str, check: bool = True, timeout: float | None = None):
return sh(["docker", *args], check=check, timeout=timeout)
@contextmanager
def bench_lock():
"""Один прогон стенда за раз: второй — код 2 (общие имена контейнеров)."""
LOCK.parent.mkdir(parents=True, exist_ok=True)
with LOCK.open("w") as handle:
try:
fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError:
raise SystemExit(
"another bench run holds bench/.bench.lock: wait for it to finish"
) from None
yield
# --- хост и паспорт ------------------------------------------------------------------
def cpu_model() -> str:
try:
if sys.platform == "darwin":
return sh(["sysctl", "-n", "machdep.cpu.brand_string"]).stdout.strip()
if sys.platform.startswith("linux"):
for line in Path("/proc/cpuinfo").read_text().splitlines():
if line.lower().startswith(("model name", "hardware")):
return line.split(":", 1)[1].strip()
except (OSError, StandError):
pass
return platform.processor() or "unknown"
def ram_gb() -> float | None:
try:
if sys.platform == "darwin":
return round(int(sh(["sysctl", "-n", "hw.memsize"]).stdout) / 2**30, 1)
if sys.platform.startswith("linux"):
for line in Path("/proc/meminfo").read_text().splitlines():
if line.startswith("MemTotal:"):
return round(int(line.split()[1]) / 2**20, 1)
except (OSError, StandError, ValueError):
pass
return None
def swapouts() -> int | None:
"""Счётчик выгрузок страниц macOS (`vm_stat`): прирост за прогон — помеха."""
if sys.platform != "darwin":
return None
out = sh(["vm_stat"], check=False).stdout
match = re.search(r"Swapouts:\s+(\d+)", out)
return int(match.group(1)) if match else None
def host_state() -> dict:
"""Питание, swap и давление на память (macOS)."""
state: dict = {"swap_used_mib": None, "power": None, "memory_pressure": None}
if sys.platform != "darwin":
return state
swap = sh(["sysctl", "-n", "vm.swapusage"], check=False).stdout
match = re.search(r"used = ([\d.,]+)M", swap)
if match:
state["swap_used_mib"] = float(match.group(1).replace(",", "."))
batt = sh(["pmset", "-g", "batt"], check=False).stdout
match = re.search(r"drawing from '([^']+)'", batt)
if match:
state["power"] = match.group(1)
pressure = sh(["memory_pressure", "-Q"], check=False).stdout
match = re.search(r"free percentage: (\d+)%", pressure)
if match:
state["memory_free_percent"] = int(match.group(1))
state["swapouts"] = swapouts()
return state
def host_info() -> dict:
info = {
"platform": platform.platform(),
"machine": platform.machine(),
"cpu_model": cpu_model(),
"cpu_count": os.cpu_count(),
"ram_gb": ram_gb(),
**host_state(),
}
if hasattr(os, "getloadavg"):
info["loadavg_1m"] = round(os.getloadavg()[0], 2)
return info
def docker_info() -> dict:
raw = json.loads(docker("info", "--format", "{{json .}}").stdout)
keys = (
"ServerVersion",
"OperatingSystem",
"KernelVersion",
"Architecture",
"NCPU",
"MemTotal",
"CgroupVersion",
"CgroupDriver",
)
info = {key: raw.get(key) for key in keys}
compose = docker("compose", "version", "--short", check=False).stdout.strip()
info["compose_version"] = compose or None
names = docker("ps", "--format", "{{.Names}}").stdout.split()
info["other_running_containers"] = sorted(
name
for name in names
if not name.startswith(f"{PROJECT}-") and name not in NAMED
)
return info
def host_warnings(host: dict, dock: dict) -> list[str]:
"""Хост не в форме: метку переснять (bench/AGENTS.md)."""
warnings = []
if host.get("power") == "Battery Power":
warnings.append("host on battery power: CPU may be throttled")
free = host.get("memory_free_percent")
if free is not None and free < 20:
warnings.append(f"memory pressure: only {free}% free")
if dock["other_running_containers"]:
warnings.append(
f"{len(dock['other_running_containers'])} other container(s) running: "
"they share CPU with the stand (make stop on the working stand)",
)
return warnings
def budget_check(cpus: float, memory_gib: float, dock: dict) -> dict:
"""Сумма лимитов стенда и ВМ Docker: не помещается — отказ до стенда."""
vm_cpus = dock["NCPU"]
vm_gib = dock["MemTotal"] / 2**30
budget = {
"limits_cpus": round(cpus, 2),
"limits_memory_gib": round(memory_gib, 2),
"vm_cpus": vm_cpus,
"vm_memory_gib": round(vm_gib, 2),
}
if cpus > vm_cpus:
raise SystemExit(
f"limits need {cpus:.2f} CPU, docker VM has {vm_cpus}: raise CPUs in "
"Docker Desktop (Settings → Resources) or use a smaller series",
)
if memory_gib + 1.5 > vm_gib:
raise SystemExit(
f"limits need {memory_gib:.1f} GiB + 1.5 GiB reserve, docker VM has "
f"{vm_gib:.1f} GiB: raise memory in Docker Desktop",
)
return budget
def base_image() -> str:
"""Базовый образ из Dockerfile: генератор работает на нём же."""
for line in (ROOT / "Dockerfile").read_text(encoding="utf-8").splitlines():
if line.startswith("FROM "):
return line.split()[1]
raise StandError("no FROM line in Dockerfile")
# Выполняется внутри образа: версии, хеш кода и пул приложения — того кода,
# который реально измеряется
IMAGE_PROBE = """
import hashlib, importlib.metadata as m, json, pathlib, platform
from src.config import Database, Settings
root = pathlib.Path.cwd()
digest = hashlib.sha256()
for path in sorted([*(root / "src").rglob("*.py"), *(root / "migrations").rglob("*.py")]):
digest.update(path.relative_to(root).as_posix().encode())
digest.update(b"\\0")
digest.update(path.read_bytes())
digest.update(b"\\0")
packages = ("fastapi", "starlette", "uvicorn", "pydantic", "sqlalchemy", "asyncpg",
"alembic", "redis", "argon2-cffi")
db = Database()
app = Settings()
print(json.dumps({
"src_sha256": digest.hexdigest(),
"versions": {"python": platform.python_version(), **{p: m.version(p) for p in packages}},
"app_defaults": {
"pool_size": db.pool_size, "pool_overflow": db.pool_overflow,
"pool_timeout": db.pool_timeout, "operation_timeout": db.operation_timeout,
"statement_timeout_ms": db.statement_timeout_ms,
"kdf_concurrency": app.kdf_concurrency, "keep_alive": app.keep_alive,
"shutdown_timeout": app.shutdown_timeout,
},
}))
"""
def build_image(tag: str, context: Path | None = None) -> None:
sh(["docker", "build", "-q", "-t", tag, str(context or ROOT)], timeout=1800)
def image_info(image: str) -> dict:
raw = json.loads(docker("image", "inspect", image).stdout)[0]
probe = docker("run", "--rm", "--entrypoint", "python", image, "-c", IMAGE_PROBE)
data = json.loads(probe.stdout.strip().splitlines()[-1])
return {"tag": image, "id": raw["Id"], "created": raw["Created"], **data}
def code_state(image: dict) -> dict:
"""Что измеряется: хеш кода из образа и, если есть git, commit."""
state = {"src_sha256": image["src_sha256"], "git_commit": None, "git_dirty": None}
if (ROOT / ".git").exists():
head = sh(["git", "rev-parse", "HEAD"], check=False)
if head.returncode == 0:
state["git_commit"] = head.stdout.strip()
status = sh(["git", "status", "--porcelain"], check=False).stdout
state["git_dirty"] = bool(status.strip())
return state
def probe_migration_context(workdir: Path) -> tuple[Path, str]:
"""Контекст сборки «нового» образа профиля rollout: файлы рабочего
дерева, которые копирует Dockerfile, плюс expand-ревизия
`9001_rollout_probe` — новая колонка `messages.rollout_probe` (NULL).
Ревизия существует только в этом образе и в базе стенда: так замена
под нагрузкой проходит с настоящей миграцией схемы, а рабочее дерево
и миграции репозитория не меняются. Возвращает каталог и ревизию head.
"""
context = workdir / "rollout-context"
for name in ("Dockerfile", "requirements.txt", "alembic.ini"):
target = context / name
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(ROOT / name, target)
for folder in ("src", "migrations"):
shutil.copytree(
ROOT / folder,
context / folder,
ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "AGENTS.md"),
)
revisions, parents = set(), set()
for path in (ROOT / "migrations" / "versions").glob("*.py"):
text = path.read_text(encoding="utf-8")
rev = re.search(r'^revision: str = "([^"]+)"', text, re.MULTILINE)
down = re.search(r'^down_revision: [^=]+= "([^"]+)"', text, re.MULTILINE)
if rev:
revisions.add(rev.group(1))
if down:
parents.add(down.group(1))
heads = revisions - parents
if len(heads) != 1:
raise StandError(f"cannot find a single migration head: {sorted(heads)}")
head = heads.pop()
(context / "migrations" / "versions" / "9001_rollout_probe.py").write_text(
PROBE_MIGRATION.replace("@HEAD@", head), encoding="utf-8"
)
return context, head
PROBE_MIGRATION = '''"""rollout probe: nullable column for the bench rollout profile
Revision ID: 9001
Revises: @HEAD@
Только в образе профиля rollout стенда bench/ (bench/common.py):
expand-миграция под нагрузкой. Колонка NULL, старый код её не замечает.
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "9001"
down_revision: str | Sequence[str] | None = "@HEAD@"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
# ADD COLUMN берёт ACCESS EXCLUSIVE: очередь за ним ограничена
op.execute("SET LOCAL lock_timeout = '2s'")
op.add_column("messages", sa.Column("rollout_probe", sa.Text(), nullable=True))
def downgrade() -> None:
op.drop_column("messages", "rollout_probe")
'''
# --- стенд ------------------------------------------------------------------------
@dataclasses.dataclass(frozen=True)
class Limits:
"""Лимиты контейнеров стенда и число реплик. Часть методики."""
api_replicas: int
api_cpus: float
api_memory: str
db_cpus: float = 2.0
db_memory: str = "1g"
db_max_connections: int = 100
cache_cpus: float = 0.5
cache_memory: str = "128m"
lb_cpus: float = 1.0
lb_memory: str = "256m"
gen_cpus: float = 2.0
gen_memory: str = "1g"
sampler_cpus: float = 0.25
sampler_memory: str = "256m"
def total_cpus(self, replicas: int | None = None) -> float:
replicas = self.api_replicas if replicas is None else replicas
return (
replicas * self.api_cpus
+ self.db_cpus
+ self.cache_cpus
+ self.lb_cpus
+ self.gen_cpus
+ self.sampler_cpus
)
def total_memory_gib(self, replicas: int | None = None) -> float:
replicas = self.api_replicas if replicas is None else replicas
return (
replicas * gib(self.api_memory)
+ gib(self.db_memory)
+ gib(self.cache_memory)
+ gib(self.lb_memory)
+ gib(self.gen_memory)
+ gib(self.sampler_memory)
)
def gib(value: str) -> float:
number, unit = float(value[:-1]), value[-1].lower()
return number / 1024 if unit == "m" else number
def leftovers() -> list[str]:
"""Команды уборки остатков другого (прерванного) прогона."""
label = f"label=com.docker.compose.project={PROJECT}"
names = set(docker("ps", "-a", "--format", "{{.Names}}").stdout.split())
project = docker("ps", "-aq", "--filter", label).stdout.split()
volumes = docker("volume", "ls", "-q", "--filter", label).stdout.split()
networks = docker("network", "ls", "--format", "{{.Name}}").stdout.split()
fixes = []
containers = sorted(set(project) | (names & set(NAMED)))
if containers:
fixes.append(f"docker rm -f {' '.join(containers)}")
if volumes:
fixes.append(f"docker volume rm {' '.join(volumes)}")
if NET in networks:
fixes.append(f"docker network rm {NET}")
return fixes
def lb_slots_from_csv(text: str) -> list[dict]:
"""Слоты backend api со статистикой HAProxy (адрес — без порта)."""
lines = [line for line in text.splitlines() if line.startswith(("# ", "api,"))]
if not lines or not lines[0].startswith("# "):
return []
header = lines[0][2:].split(",")
slots = []
for line in lines[1:]:
row = dict(zip(header, line.split(","), strict=False))
if row.get("svname") in ("BACKEND", "FRONTEND"):
continue
addr = row.get("addr", "").rsplit(":", 1)[0]
slots.append(
{"slot": row["svname"], "addr": addr, "status": row.get("status", "")}
)
return slots
class Stand:
"""Проект compose `vlad-bench`: хранилища, миграции, реплики, LB,
контейнеры генератора и сэмплера."""
def __init__(self, limits: Limits, *, session_ttl: int, workdir: Path) -> None:
self.limits = limits
self.workdir = workdir
host_env = {key: os.environ[key] for key in HOST_ENV if key in os.environ}
self.env = {
**host_env,
"POSTGRES_PASSWORD": secrets.token_hex(16),
"VALKEY_PASSWORD": secrets.token_hex(16),
"BENCH_IMAGE": SERVICE_TAG,
"BENCH_API_REPLICAS": str(limits.api_replicas),
"BENCH_API_CPUS": str(limits.api_cpus),
"BENCH_API_MEMORY": limits.api_memory,
"BENCH_DB_CPUS": str(limits.db_cpus),
"BENCH_DB_MEMORY": limits.db_memory,
"BENCH_DB_MAX_CONNECTIONS": str(limits.db_max_connections),
"BENCH_CACHE_CPUS": str(limits.cache_cpus),
"BENCH_CACHE_MEMORY": limits.cache_memory,
"BENCH_LB_CPUS": str(limits.lb_cpus),
"BENCH_LB_MEMORY": limits.lb_memory,
"BENCH_SESSION_TTL": str(session_ttl),
}
# --- compose и контейнеры ---
def compose_args(self) -> list[str]:
files = [arg for path in COMPOSE_FILES for arg in ("-f", str(path))]
return ["docker", "compose", "-p", PROJECT, "--env-file", str(ENV_FILE), *files]
def compose(self, *args: str, check: bool = True, timeout: float | None = 600):
"""docker compose стенда; без `-p vlad-bench` не вызывается."""
return sh(
[*self.compose_args(), *args], check=check, timeout=timeout, env=self.env
)
def script_env(self) -> dict[str, str]:
"""Окружение скриптов репозитория (rolling-update.sh): тот же
проект compose переменными, без `-p` в самом скрипте."""
return {
**self.env,
"COMPOSE_PROJECT_NAME": PROJECT,
"COMPOSE_FILE": os.pathsep.join(str(path) for path in COMPOSE_FILES),
"COMPOSE_ENV_FILES": str(ENV_FILE),
}
def start(self) -> None:
"""Свежий стенд: пустая база на новом volume, миграции, реплики, LB,
генератор. Готов, когда LB видит `UP` все реплики."""
self.compose("up", "-d", "--wait", "postgres", "valkey")
self.compose("run", "--rm", "migrate")
self.compose("up", "-d", "--no-deps", "--no-build", "api")
self.compose("up", "-d", "--no-deps", "--no-build", "haproxy")
self.wait_lb_up(self.limits.api_replicas)
docker(
"run",
"-d",
"--name",
GEN,
"--network",
NET,
"--cpus",
str(self.limits.gen_cpus),
"--memory",
self.limits.gen_memory,
"--memory-swap",
self.limits.gen_memory,
"--entrypoint",
"python",
base_image(),
"-c",
"import time; time.sleep(86400)",
)
# docker cp, а не bind-mount: не зависит от общих каталогов Docker Desktop
docker("cp", str(BENCH / "loadgen.py"), f"{GEN}:/tmp/loadgen.py")
ready = self.gen("ready", "--timeout", "60")
if not ready["ready"]:
raise StandError("API is not ready through the LB:\n" + self.app_tail())
def stop(self) -> None:
"""Генератор и сэмплер первыми: подключённые к сети чужие для compose
контейнеры не дали бы удалить сеть. Затем стенд с volume."""
docker("rm", "-f", GEN, SAMPLER, check=False)
self.compose("down", "-v", "--remove-orphans", check=False)
def api_ids(self, *, all_states: bool = False) -> list[str]:
args = (
["ps", "-a", "-q", "--no-trunc", "api"]
if all_states
else [
"ps",
"-q",
"--no-trunc",
"api",
]
)
return self.compose(*args).stdout.split()
def address(self, container: str) -> str:
return docker(
"inspect",
"-f",
"{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}",
container,
).stdout.strip()
def lb_slots(self) -> list[dict]:
out = docker("exec", LB, "bash", "-c", LB_STATS_CMD, check=False)
return lb_slots_from_csv(out.stdout) if out.returncode == 0 else []
def wait_lb_up(self, replicas: int, timeout: float = 90) -> None:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
up = [slot for slot in self.lb_slots() if slot["status"] == "UP"]
if len(up) >= replicas:
return
time.sleep(0.5)
raise StandError(
f"LB does not see {replicas} replicas UP in {timeout:.0f}s:\n"
+ self.app_tail()
)
def wait_slot(self, address: str, status: str, timeout: float = 30) -> float | None:
"""Ждать состояния слота с адресом; секунды или None."""
started = time.monotonic()
while time.monotonic() - started < timeout:
for slot in self.lb_slots():
if slot["addr"] == address and slot["status"].startswith(status):
return time.monotonic() - started
time.sleep(0.25)
return None
def app_tail(self, lines: int = 30) -> str:
done = self.compose("logs", "--tail", str(lines), "api", "haproxy", check=False)
return done.stdout + done.stderr
def gen(self, *args: str, timeout: float = 3600) -> dict:
done = docker(
"exec",
GEN,
"python",
"/tmp/loadgen.py",
"--base-url",
LB_URL,
*args,
timeout=timeout,
)
return json.loads(done.stdout.strip().splitlines()[-1])
def gen_popen(self, *args: str) -> subprocess.Popen:
"""Генератор в фоне: оркестратор действует на стенд, пока идёт нагрузка."""
return subprocess.Popen(
[
"docker",
"exec",
GEN,
"python",
"/tmp/loadgen.py",
"--base-url",
LB_URL,
*args,
],
cwd=ROOT,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
)
def gen_file(self, path: str) -> str:
return docker("exec", GEN, "cat", path).stdout
def psql(self, sql: str) -> str:
"""SQL в базе стенда через stdin: пользователь контейнера, без пароля."""
done = sh(
["docker", "exec", "-i", DB, "sh", "-c", PSQL], stdin=sql, check=False
)
if done.returncode != 0:
raise StandError(f"psql: exit {done.returncode}\n{done.stderr}")
return done.stdout.strip()
def maintain(self) -> float:
"""VACUUM (ANALYZE) и CHECKPOINT после наполнения; секунды."""
started = time.monotonic()
self.psql("VACUUM (ANALYZE);\nCHECKPOINT;\n")
return time.monotonic() - started
# --- сэмплер ---
def start_sampler(self, mode: str, containers: list[str] | None = None) -> None:
"""Сэмплер на образе приложения с `--cgroupns host` (bench/sampler.py)."""
args = [
"run",
"-d",
"--name",
SAMPLER,
"--cgroupns",
"host",
"--cpus",
str(self.limits.sampler_cpus),
"--memory",
self.limits.sampler_memory,
"--memory-swap",
self.limits.sampler_memory,
]
if mode == "list":
# пароль — только в окружении контейнера сэмплера
args += [
"--network",
NET,
"-e",
"PGUSER=bench",
"-e",
"PGDATABASE=bench",
"-e",
f"PGPASSWORD={self.env['POSTGRES_PASSWORD']}",
]
else:
args += ["--network", "none"]
docker(
*args,
"--entrypoint",
"python",
SERVICE_TAG,
"-c",
"import time; time.sleep(86400)",
)
docker("cp", str(BENCH / "sampler.py"), f"{SAMPLER}:/tmp/sampler.py")
command = [
"exec",
"-d",
SAMPLER,
"python",
"/tmp/sampler.py",
"--mode",
mode,
"--out",
"/tmp/samples.jsonl",
]
for container in containers or []:
command += ["--container", container]
docker(*command)
def sampler_lines(self) -> list[dict]:
done = docker("exec", SAMPLER, "cat", "/tmp/samples.jsonl", check=False)
return [json.loads(line) for line in done.stdout.splitlines() if line.strip()]
def stop_sampler(self) -> None:
docker("rm", "-f", SAMPLER, check=False)
# --- паспорт ---
def passport(self) -> dict:
"""Хранилища, лимиты и окружение API для паспорта; паролей здесь нет."""
settings = self.psql(
"SELECT name, current_setting(name) FROM pg_settings "
f"WHERE name = ANY(string_to_array('{','.join(PG_SETTINGS)}', ',')) "
"ORDER BY name;\n",
)
info = docker("exec", CACHE, "valkey-cli", "INFO", "server", check=False).stdout
valkey_version = re.search(r"^valkey_version:(\S+)", info, re.MULTILINE)
api = self.api_ids()
env = json.loads(docker("inspect", "-f", "{{json .Config.Env}}", api[0]).stdout)
app_env = dict(
sorted(
item.split("=", 1)
for item in env
if re.match(
r"(DB|CACHE|SESSION|LOG|SHUTDOWN|KDF|IDEMPOTENCY|APP)_[A-Z_]*=",
item,
)
and "PASSWORD" not in item.split("=", 1)[0]
),
)
limits = {}
for role, name in (
("api", api[0]),
("postgres", DB),
("valkey", CACHE),
("haproxy", LB),
):
host = json.loads(
docker("inspect", "-f", "{{json .HostConfig}}", name).stdout
)
limits[role] = {
"nano_cpus": host.get("NanoCpus"),
"memory": host.get("Memory"),
"memory_swap": host.get("MemorySwap"),
"published_ports": host.get("PortBindings") or {},
}
def image(name: str) -> str:
return docker("inspect", "-f", "{{.Config.Image}}", name).stdout.strip()
return {
"postgres": {
"image": image(DB),
"version": self.psql("SHOW server_version;\n"),
"settings": dict(line.split("|", 1) for line in settings.splitlines()),
},
"valkey": {
"image": image(CACHE),
"version": valkey_version.group(1) if valkey_version else None,
},
"haproxy": {"image": image(LB)},
"limits": limits,
"api_replicas": len(api),
"app_env": app_env,
}
def new_label_dir(kind: str, label: str) -> Path:
if not LABEL_RE.fullmatch(label):
raise SystemExit(f"label must match {LABEL_RE.pattern}")
folder = EVIDENCE / kind / label
if folder.exists():
raise SystemExit(
f"{folder.relative_to(ROOT)} exists: labels are not overwritten"
)
folder.mkdir(parents=True)
return folder
def quick_label(kind: str) -> str:
stamp = datetime.datetime.now(datetime.UTC).strftime("%Y%m%dT%H%M%SZ")
return f"quick-{kind}-{stamp}" if kind else f"quick-{stamp}"
def write_json(path: Path, data: dict) -> None:
path.write_text(
json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
)
def preflight(limits_cpus: float, limits_memory_gib: float) -> dict:
"""Хост, Docker, бюджет лимитов, остатки прошлых прогонов."""
fixes = leftovers()
if fixes:
raise SystemExit(
"leftovers of an interrupted bench run; remove them first:\n "
+ "\n ".join(fixes)
)
host = host_info()
dock = docker_info()
budget = budget_check(limits_cpus, limits_memory_gib, dock)
return {
"host": host,
"docker": dock,
"budget": budget,
"warnings": host_warnings(host, dock),
}
def finish_host_state(
meta: dict, started_monotonic: float, started_wall: float
) -> None:
"""Сон ноутбука и выгрузка страниц за прогон — в паспорт и предупреждения."""
elapsed_wall = time.time() - started_wall
elapsed_mono = time.monotonic() - started_monotonic
end = host_state()
state = {
"slept_seconds": round(max(0.0, elapsed_wall - elapsed_mono), 1),
"swapouts_start": meta["host"].get("swapouts"),
"swapouts_end": end.get("swapouts"),
"power_end": end.get("power"),
}
if state["swapouts_start"] is not None and state["swapouts_end"] is not None:
state["swapouts_delta"] = state["swapouts_end"] - state["swapouts_start"]
if state["swapouts_delta"] > 0:
meta["host_warnings"].append(
f"host swapped out {state['swapouts_delta']} pages during the run"
)
if state["slept_seconds"] > 5:
meta["host_warnings"].append(
f"host slept {state['slept_seconds']}s during the run: rerun"
)
meta["host_state_end"] = state
def temp_workdir() -> Path:
return Path(tempfile.mkdtemp(prefix="vlad-bench-"))
+248
View File
@@ -0,0 +1,248 @@
"""Сравнение двух меток серий трека 1: «до» и «после» одного изменения.
uv run python bench/compare.py --before scaling-ab-before \\
--after scaling-ab-after [--aa scaling-ab-aa]
→ evidence/compare/<до>__<после>.md
По общим конфигурациям: R* (медиана, min–max, Δ), задержки на
фиксированных уровнях, CPU на запрос реплик и PostgreSQL, новые сессии
PostgreSQL и соединения на ступени R* и на первой нарушившей. С `--aa`
(метка того же кода, что «до») — уровень шума: наибольшее |Δ медианы R*|
между «до» и A/A по общим конфигурациям.
Изменение R* — эффект, только если: разбросы повторов не пересекаются,
|Δ медианы| больше шума A/A и не меньше двух ступеней сетки поиска
(R* после / R* до ≥ √factor ≈ 1,118 при factor 1,25: шаг сетки после двух
делений — factor^¼, одна ступень — в пределах разрешения поиска). Иначе
— «шум» или «в пределах разрешения».
Методика меток должна совпадать: профиль (кроме списка ячеек серии ab),
лимиты, образы хранилищ, хост. Различаться может только код приложения
(`src_sha256`). Иначе — отказ.
"""
import argparse
import csv
import json
import math
import statistics
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
SCALING = ROOT / "evidence" / "scaling"
OUT = ROOT / "evidence" / "compare"
def read_csv(path: Path) -> list[dict]:
with path.open(encoding="utf-8") as handle:
return list(csv.DictReader(handle))
def num(value) -> float | None:
try:
return float(value)
except (TypeError, ValueError):
return None
def load(label: str) -> dict:
folder = SCALING / label
if not (folder / "meta.json").exists():
raise SystemExit(f"no label {label} in evidence/scaling")
return {
"label": label,
"meta": json.loads((folder / "meta.json").read_text(encoding="utf-8")),
"searches": read_csv(folder / "searches.csv"),
"runs": read_csv(folder / "runs.csv"),
}
def methodology(meta: dict) -> dict:
"""Что должно совпасть у сравниваемых меток."""
profile = dict(meta["profile"])
profile.pop("configs", None)
stand = meta.get("stand") or {}
return {
"profile": profile,
"series_name": profile.get("name"),
"configs": meta.get("configs"),
"cpu_model": meta["host"].get("cpu_model"),
"vm_cpus": meta["docker"].get("NCPU"),
"postgres_image": (stand.get("postgres") or {}).get("image"),
}
def check_methodology(before: dict, after: dict) -> list[str]:
a, b = methodology(before["meta"]), methodology(after["meta"])
problems = []
if a["profile"] != b["profile"]:
problems.append("profile differs")
if a["cpu_model"] != b["cpu_model"] or a["vm_cpus"] != b["vm_cpus"]:
problems.append("host or docker VM differs")
common = set(a["configs"] or {}) & set(b["configs"] or {})
for config in sorted(common):
if a["configs"][config] != b["configs"][config]:
problems.append(f"limits of {config} differ")
return problems
def stats_by_config(data: dict) -> dict:
out = {}
for row in data["searches"]:
entry = out.setdefault(row["config"], {"r": [], "cells": []})
if num(row["r_star"]) is not None:
entry["r"].append(num(row["r_star"]))
entry["cells"].append(row)
for entry in out.values():
values = entry["r"] or [0.0]
entry["median"] = statistics.median(values)
entry["min"], entry["max"] = min(values), max(values)
return out
def step_metric(data: dict, config: str, which: str, key: str) -> float | None:
"""Медиана поля на ступени R* (`star`) или первой нарушившей (`fail`)."""
values = []
for search in data["searches"]:
if search["config"] != config:
continue
rate = num(search["r_star"] if which == "star" else search["first_fail"])
row = next(
(
r
for r in data["runs"]
if r["cell"] == search["cell"]
and r["phase"] != "fixed"
and num(r["rate"]) == rate
),
None,
)
if row is not None and num(row.get(key)) is not None:
values.append(num(row[key]))
return statistics.median(values) if values else None
def fixed_metric(data: dict, config: str, rate: float, key: str) -> float | None:
values = [
num(r[key])
for r in data["runs"]
if r["config"] == config
and r["phase"] == "fixed"
and num(r["rate"]) == rate
and num(r.get(key)) is not None
]
return statistics.median(values) if values else None
def fmt(value: float | None, digits: int = 1) -> str:
if value is None:
return "—"
return f"{round(value, digits):g}"
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--before", required=True)
parser.add_argument("--after", required=True)
parser.add_argument("--aa")
args = parser.parse_args()
before, after = load(args.before), load(args.after)
aa = load(args.aa) if args.aa else None
problems = check_methodology(before, after)
if aa:
problems += [f"A/A: {p}" for p in check_methodology(before, aa)]
if aa["meta"]["code"]["src_sha256"] != before["meta"]["code"]["src_sha256"]:
problems.append("A/A label has different code than BEFORE (src_sha256)")
if problems:
raise SystemExit("labels are not comparable: " + "; ".join(problems))
factor = before["meta"]["profile"]["ladder_factor"]
two_steps = math.sqrt(factor)
sb, sa = stats_by_config(before), stats_by_config(after)
common = [c for c in before["meta"]["profile"]["configs"] if c in sb and c in sa]
noise = None
if aa:
saa = stats_by_config(aa)
deltas = [
abs(saa[c]["median"] - sb[c]["median"]) / sb[c]["median"]
for c in common
if c in saa and sb[c]["median"]
]
noise = max(deltas) if deltas else None
same_code = (
before["meta"]["code"]["src_sha256"] == after["meta"]["code"]["src_sha256"]
)
lines = [
f"# Сравнение: {args.before} → {args.after}",
"",
f"- Код «до»: src_sha256 `{before['meta']['code']['src_sha256'][:16]}`; «после»: "
f"`{after['meta']['code']['src_sha256'][:16]}`"
+ (" — **код одинаковый: это A/A, а не изменение**" if same_code else "")
+ ".",
f"- Пул приложения «до»: {before['meta']['image'].get('app_defaults')}; «после»: "
f"{after['meta']['image'].get('app_defaults')}.",
f"- Шум A/A ({args.aa}): "
+ (
f"наибольшее |Δ медианы R*| = {noise * 100:.1f} %"
if noise is not None
else "не задан"
)
+ ".",
f"- Порог эффекта: разбросы не пересекаются, |Δ| > шума и R* после / до ≥ "
f"{two_steps:.3f} (две ступени сетки поиска; одна ступень — {factor**0.25:.3f}).",
"",
"| Конфигурация | R* до, медиана (min–max) | R* после | Δ | Вывод | p95 до / после на фиксированных, мс | API мкс/запрос до / после | PostgreSQL мкс/запрос на R* до / после | Новых сессий за окно на первой нарушившей до / после | Соединений на R* до / после |",
"|---|---|---|---|---|---|---|---|---|---|",
]
rates = before["meta"]["profile"]["fixed_rates"]
for config in common:
b, a = sb[config], sa[config]
delta = (a["median"] - b["median"]) / b["median"] if b["median"] else None
overlap = not (a["min"] > b["max"] or a["max"] < b["min"])
ratio = a["median"] / b["median"] if b["median"] else None
if delta is None:
verdict = "нет данных"
elif overlap:
verdict = "шум (разбросы пересекаются)"
elif noise is not None and abs(delta) <= noise:
verdict = "шум (в пределах A/A)"
elif ratio is not None and (ratio >= two_steps or ratio <= 1 / two_steps):
verdict = "эффект"
else:
verdict = "в пределах разрешения поиска"
p95 = " ; ".join(
f"{r:g}: {fmt(fixed_metric(before, config, r, 'p95_ms'))} / {fmt(fixed_metric(after, config, r, 'p95_ms'))}"
for r in rates
)
api_us = (
f"{fmt(fixed_metric(before, config, rates[-1], 'api_cpu_us_per_req'))} / "
f"{fmt(fixed_metric(after, config, rates[-1], 'api_cpu_us_per_req'))}"
)
db_us = (
f"{fmt(step_metric(before, config, 'star', 'db_cpu_us_per_req'))} / "
f"{fmt(step_metric(after, config, 'star', 'db_cpu_us_per_req'))}"
)
sessions = (
f"{fmt(step_metric(before, config, 'fail', 'pg_new_sessions'), 0)} / "
f"{fmt(step_metric(after, config, 'fail', 'pg_new_sessions'), 0)}"
)
conns = (
f"{fmt(step_metric(before, config, 'star', 'pg_conn_max'), 0)} / "
f"{fmt(step_metric(after, config, 'star', 'pg_conn_max'), 0)}"
)
lines.append(
f"| {config} | {b['median']:g} ({b['min']:g}–{b['max']:g}) | "
f"{a['median']:g} ({a['min']:g}–{a['max']:g}) | "
f"{fmt(delta * 100 if delta is not None else None)} % | {verdict} | {p95} | "
f"{api_us} | {db_us} | {sessions} | {conns} |"
)
OUT.mkdir(parents=True, exist_ok=True)
path = OUT / f"{args.before}__{args.after}.md"
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
print("\n".join(lines))
print(f"\nwritten: {path.relative_to(ROOT)}")
if __name__ == "__main__":
main()
+1003
View File
File diff suppressed because it is too large Load Diff
+412
View File
@@ -0,0 +1,412 @@
"""Графики серий трека 1: SVG на стандартной библиотеке.
uv run python bench/plots.py --out scaling scaling-a scaling-b scaling-db
→ evidence/plots/<out>/: rstar-by-config.svg, rstar-by-replicas.svg,
summary.md (R*, эффективность, точка насыщения)
`run.py` после серии зовёт `render_label()`: в каталоге метки —
`p95-by-rate.svg` (p95 от поданной интенсивности по ячейкам) и
`cpu-by-component.svg` (CPU компонентов на ступени R*). Числа берутся из
`searches.csv` и `runs.csv` меток как есть.
"""
import argparse
import csv
import html
import math
import re
import statistics
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
SCALING = ROOT / "evidence" / "scaling"
PLOTS = ROOT / "evidence" / "plots"
COLORS = (
"#2f6fbf",
"#d0752a",
"#3c9a5f",
"#b8404a",
"#7a5cb5",
"#8c6d3f",
"#c25f9c",
"#5f8f9c",
)
COMPONENTS = (
("api_cpu_cores", "API (сумма реплик)", "#2f6fbf"),
("db_cpu_cores", "PostgreSQL", "#b8404a"),
("lb_cpu_cores", "HAProxy", "#3c9a5f"),
("cache_cpu_cores", "Valkey", "#7a5cb5"),
("gen_cpu_cores", "генератор", "#8c6d3f"),
)
CONFIG_RE = re.compile(r"(\d+)x([\d.]+)(?:-pg([\d.]+))?")
def read_csv(path: Path) -> list[dict]:
if not path.exists():
return []
with path.open(encoding="utf-8") as handle:
return list(csv.DictReader(handle))
def num(value) -> float | None:
try:
return float(value)
except (TypeError, ValueError):
return None
def nice_step(raw: float) -> float:
"""Круглый шаг сетки не меньше raw: 1, 2, 2,5, 5 или 10 × 10^k."""
magnitude = 10 ** math.floor(math.log10(raw))
return next(m * magnitude for m in (1, 2, 2.5, 5, 10) if m * magnitude >= raw)
def nice_ticks(top: float, count: int = 6) -> list[float]:
step = nice_step(top / count) if top > 0 else 1.0
return [round(step * i, 6) for i in range(int(top / step) + 1)]
class Svg:
"""Поле графика с осями: x и y в единицах данных."""
def __init__(self, width: int, height: int, title: str) -> None:
self.width, self.height = width, height
# справа — место под легенду: имена меток длинные
self.left, self.right, self.top, self.bottom = 70, 300, 40, 50
self.parts = [
f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" '
f'viewBox="0 0 {width} {height}" font-family="sans-serif" font-size="12">',
f'<rect width="{width}" height="{height}" fill="white"/>',
f'<text x="{width / 2}" y="22" text-anchor="middle" font-size="14">'
f"{html.escape(title)}</text>",
]
self.x0 = self.x1 = self.y0 = self.y1 = 0.0
self.ystep = 1.0
self.legend_row = 0
def scale(self, x0: float, x1: float, y0: float, y1: float) -> None:
"""Ось y — от y0 до круглого значения не меньше y1 (шаг сетки
1, 2, 2,5 или 5 × 10^k, пять–шесть делений)."""
self.ystep = nice_step(max(y1 - y0, 1e-9) / 5)
top = y0 + self.ystep * math.ceil(max(y1 - y0, 1e-9) / self.ystep)
self.x0, self.x1, self.y0, self.y1 = (
x0,
x1 if x1 > x0 else x0 + 1,
y0,
top,
)
def px(self, x: float) -> float:
span = self.width - self.left - self.right
return self.left + (x - self.x0) / (self.x1 - self.x0) * span
def py(self, y: float) -> float:
span = self.height - self.top - self.bottom
return self.height - self.bottom - (y - self.y0) / (self.y1 - self.y0) * span
def axes(self, xlabel: str, ylabel: str, xticks: list[tuple[float, str]]) -> None:
bottom, left = self.height - self.bottom, self.left
right = self.width - self.right
self.parts.append(
f'<line x1="{left}" y1="{bottom}" x2="{right}" y2="{bottom}" stroke="#333"/>'
)
self.parts.append(
f'<line x1="{left}" y1="{self.top}" x2="{left}" y2="{bottom}" stroke="#333"/>'
)
for x, text in xticks:
self.parts.append(
f'<text x="{self.px(x):.1f}" y="{bottom + 16}" text-anchor="middle">{html.escape(text)}</text>'
)
for index in range(round((self.y1 - self.y0) / self.ystep) + 1):
value = round(self.y0 + self.ystep * index, 6)
y = self.py(value)
self.parts.append(
f'<line x1="{left}" y1="{y:.1f}" x2="{right}" y2="{y:.1f}" stroke="#eee"/>'
)
self.parts.append(
f'<text x="{left - 6}" y="{y + 4:.1f}" text-anchor="end">{value:g}</text>'
)
self.parts.append(
f'<text x="{(left + right) / 2}" y="{self.height - 12}" text-anchor="middle">{html.escape(xlabel)}</text>'
)
self.parts.append(
f'<text x="16" y="{(self.top + bottom) / 2}" text-anchor="middle" '
f'transform="rotate(-90 16 {(self.top + bottom) / 2})">{html.escape(ylabel)}</text>'
)
def line(
self, points: list[tuple[float, float]], color: str, dash: str = ""
) -> None:
if not points:
return
path = " ".join(f"{self.px(x):.1f},{self.py(y):.1f}" for x, y in points)
extra = f' stroke-dasharray="{dash}"' if dash else ""
self.parts.append(
f'<polyline points="{path}" fill="none" stroke="{color}" stroke-width="2"{extra}/>'
)
def dot(self, x: float, y: float, color: str, hollow: bool = False) -> None:
fill = "white" if hollow else color
self.parts.append(
f'<circle cx="{self.px(x):.1f}" cy="{self.py(y):.1f}" r="3.5" fill="{fill}" stroke="{color}"/>'
)
def whisker(self, x: float, lo: float, hi: float, color: str) -> None:
self.parts.append(
f'<line x1="{self.px(x):.1f}" y1="{self.py(lo):.1f}" x2="{self.px(x):.1f}" '
f'y2="{self.py(hi):.1f}" stroke="{color}" stroke-width="1.5"/>'
)
def bar(self, x: float, width: float, y0: float, y1: float, color: str) -> None:
left = self.px(x - width / 2)
right = self.px(x + width / 2)
self.parts.append(
f'<rect x="{left:.1f}" y="{self.py(y1):.1f}" width="{right - left:.1f}" '
f'height="{self.py(y0) - self.py(y1):.1f}" fill="{color}" opacity="0.85"/>'
)
def legend(self, text: str, color: str, dash: str = "") -> None:
x = self.width - self.right + 14
y = self.top + 14 + 18 * self.legend_row
extra = f' stroke-dasharray="{dash}"' if dash else ""
self.parts.append(
f'<line x1="{x}" y1="{y - 4}" x2="{x + 18}" y2="{y - 4}" stroke="{color}" stroke-width="3"{extra}/>'
)
self.parts.append(f'<text x="{x + 24}" y="{y}">{html.escape(text)}</text>')
self.legend_row += 1
def save(self, path: Path) -> None:
path.write_text("\n".join([*self.parts, "</svg>"]) + "\n", encoding="utf-8")
def render_label(folder: Path) -> None:
"""Графики одной метки серии: p95 от интенсивности, CPU на ступени R*."""
runs = read_csv(folder / "runs.csv")
searches = read_csv(folder / "searches.csv")
if not runs:
return
configs = list(dict.fromkeys(row["config"] for row in runs))
rates = [num(r["rate"]) or 0 for r in runs]
p95s = [min(num(r["p95_ms"]) or 0, 1000) for r in runs]
svg = Svg(1000, 440, f"p95 успешных от поданной интенсивности: {folder.name}")
svg.scale(0, max(rates) * 1.05, 0, max(max(p95s) * 1.1, 250))
ticks = [(x, f"{x:g}") for x in nice_ticks(max(rates))]
svg.axes("запросов в секунду (по расписанию)", "p95, мс (≤ 1000)", ticks)
svg.line([(0, 200), (max(rates) * 1.05, 200)], "#999", "4 4")
for index, config in enumerate(configs):
color = COLORS[index % len(COLORS)]
cells = sorted(
{(r["cell"], r["repeat"]) for r in runs if r["config"] == config}
)
for cell, _ in cells:
points = sorted(
(num(r["rate"]) or 0, min(num(r["p95_ms"]) or 1000, 1000))
for r in runs
if r["cell"] == cell
)
svg.line(points, color)
for r in runs:
if r["cell"] == cell:
svg.dot(
num(r["rate"]) or 0,
min(num(r["p95_ms"]) or 1000, 1000),
color,
hollow=r["slo_pass"] != "True",
)
svg.legend(config, color)
svg.legend("SLO 200 мс", "#999", "4 4")
svg.save(folder / "p95-by-rate.svg")
# CPU компонентов на ступени R* каждой ячейки (медиана по повторам)
stacks = []
for config in configs:
values = {key: [] for key, _, _ in COMPONENTS}
for search in [s for s in searches if s["config"] == config]:
star = num(search["r_star"])
row = next(
(
r
for r in runs
if r["cell"] == search["cell"]
and r["phase"] != "fixed"
and num(r["rate"]) == star
),
None,
)
if row is None:
continue
for key, _, _ in COMPONENTS:
if num(row.get(key)) is not None:
values[key].append(num(row[key]))
stacks.append(
(config, {k: statistics.median(v) if v else 0 for k, v in values.items()})
)
if not stacks:
return
top = max(sum(s.values()) for _, s in stacks) or 1
svg = Svg(
1000, 440, f"CPU компонентов на ступени R* (медиана), ядер: {folder.name}"
)
svg.scale(0, len(stacks) + 1, 0, top * 1.15)
svg.axes("конфигурация", "ядер", [(i + 1, c) for i, (c, _) in enumerate(stacks)])
for index, (_, stack) in enumerate(stacks):
base = 0.0
for key, _, color in COMPONENTS:
svg.bar(index + 1, 0.5, base, base + stack[key], color)
base += stack[key]
for _, name, color in COMPONENTS:
svg.legend(name, color)
svg.save(folder / "cpu-by-component.svg")
def label_rows(label: str) -> list[dict]:
rows = read_csv(SCALING / label / "searches.csv")
for row in rows:
row["label"] = label
return rows
def summarize(rows: list[dict]) -> dict[tuple[str, str], dict]:
"""(метка, конфигурация) → медиана, min, max R*, реплик, CPU."""
out: dict[tuple[str, str], dict] = {}
for row in rows:
key = (row["label"], row["config"])
entry = out.setdefault(
key,
{
"values": [],
"replicas": int(row["replicas"]),
"api_cpus": num(row["api_cpus"]),
"db_cpus": num(row["db_cpus"]),
"signals": {},
},
)
if num(row["r_star"]) is not None:
entry["values"].append(num(row["r_star"]))
for signal in (row["signals_at_fail"] or "").split(";"):
if signal:
entry["signals"][signal] = entry["signals"].get(signal, 0) + 1
for entry in out.values():
values = entry["values"] or [0]
entry["median"] = statistics.median(values)
entry["min"], entry["max"] = min(values), max(values)
return out
def saturation(points: list[tuple[int, float]]) -> int | None:
"""Наименьшее k, после которого следующая реплика даёт < +10 % R*."""
points = sorted(points)
for (k, r), (_, r_next) in zip(points, points[1:], strict=False):
if r_next < 1.10 * r:
return k
return None
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--out", required=True)
parser.add_argument("labels", nargs="+")
args = parser.parse_args()
if not re.fullmatch(r"[A-Za-z0-9._-]{1,48}", args.out):
raise SystemExit("--out must be a simple name")
rows = [row for label in args.labels for row in label_rows(label)]
if not rows:
raise SystemExit("no searches.csv in the given labels")
stats = summarize(rows)
folder = PLOTS / args.out
folder.mkdir(parents=True, exist_ok=True)
# R* по конфигурациям всех меток: медиана и min–max
items = list(stats.items())
top = max(entry["max"] for _, entry in items) or 1
svg = Svg(
max(1000, 90 * len(items) + 380), 460, "R* по конфигурациям: медиана и min–max"
)
svg.scale(0, len(items) + 1, 0, top * 1.15)
svg.axes(
"метка / конфигурация",
"R*, запросов/с",
[(i + 1, cfg) for i, ((_, cfg), _) in enumerate(items)],
)
labels = list(dict.fromkeys(label for (label, _), _ in items))
for index, ((label, _), entry) in enumerate(items):
color = COLORS[labels.index(label) % len(COLORS)]
svg.bar(index + 1, 0.55, 0, entry["median"], color)
svg.whisker(index + 1, entry["min"], entry["max"], "#222")
for label in labels:
svg.legend(label, COLORS[labels.index(label) % len(COLORS)])
svg.save(folder / "rstar-by-config.svg")
# R* от числа реплик по 1 CPU — по меткам, где такие конфигурации есть
svg = Svg(
860, 440, "R* от числа реплик (по 1 CPU): медиана, min–max, линейный рост"
)
curves = {}
for (label, config), entry in items:
match = CONFIG_RE.fullmatch(config)
if match and float(match.group(2)) == 1.0:
curves.setdefault((label, match.group(3) or "2"), []).append(
(entry["replicas"], entry)
)
if curves:
max_k = max(k for points in curves.values() for k, _ in points)
# линия линейного роста от 1 × 1 тоже должна поместиться
ideal = [
e["median"] * max_k
for points in curves.values()
for k, e in points
if k == 1
]
svg.scale(0, max_k + 0.5, 0, max([top, *ideal]) * 1.05)
svg.axes("реплик", "R*, запросов/с", [(k, str(k)) for k in range(1, max_k + 1)])
for index, ((label, pg), points) in enumerate(sorted(curves.items())):
color = COLORS[index % len(COLORS)]
points.sort(key=lambda p: p[0])
svg.line([(k, e["median"]) for k, e in points], color)
for k, entry in points:
svg.dot(k, entry["median"], color)
svg.whisker(k, entry["min"], entry["max"], color)
one = next((e["median"] for k, e in points if k == 1), None)
if one:
svg.line([(1, one), (max_k, one * max_k)], color, "3 4")
svg.legend(f"{label}, PostgreSQL {pg} CPU", color)
svg.save(folder / "rstar-by-replicas.svg")
lines = [
f"# Графики трека 1: {args.out}",
"",
f"Метки: {', '.join(args.labels)}. Числа — `searches.csv` меток.",
"",
"| Метка | Конфигурация | Реплик | CPU реплики | PostgreSQL CPU | R* медиана | min–max | Эффективность к 1 × 1 метки | Признаки на первой нарушившей |",
"|---|---|---|---|---|---|---|---|---|",
]
for (label, config), entry in items:
one = stats.get((label, "1x1"))
eff = (
f"{entry['median'] / (entry['replicas'] * one['median']):.2f}"
if one and one["median"] and config != "1x1"
else "—"
)
signals = (
", ".join(f"{k} ×{v}" for k, v in sorted(entry["signals"].items())) or "—"
)
lines.append(
f"| {label} | {config} | {entry['replicas']} | {entry['api_cpus']:g} | "
f"{entry['db_cpus']:g} | {entry['median']:g} | {entry['min']:g}–{entry['max']:g} | "
f"{eff} | {signals} |"
)
lines += ["", "## Точка насыщения", ""]
for (label, pg), points in sorted(curves.items()):
k = saturation([(k, e["median"]) for k, e in points])
verdict = (
f"после {k} реплик(и) следующая даёт меньше +10 % R*"
if k
else "в пределах снятых конфигураций рост не останавливается (≥ +10 % на реплику)"
)
lines.append(f"- {label}, PostgreSQL {pg} CPU: {verdict}.")
(folder / "summary.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
print(f"written: {folder.relative_to(ROOT)}")
if __name__ == "__main__":
main()
+1854
View File
File diff suppressed because it is too large Load Diff
+182
View File
@@ -0,0 +1,182 @@
"""Сэмплер стенда: раз в секунду — ресурсы контейнеров, LB и PostgreSQL.
Работает только внутри контейнера `vlad-bench-sampler` (образ
приложения: в нём есть Python и asyncpg) с `--cgroupns host`: тогда в
`/sys/fs/cgroup/docker/<id>/` видны cgroup всех контейнеров ВМ Docker.
Его запускает `bench/run.py` (`Stand.start_sampler`), на хосте он не
работает. Пишет строки JSON в файл `--out`; время — часы ВМ (`time.time()`),
те же, что у генератора.
Строка тика:
{"ts": ..., "cg": {"<id12>": [usage_usec, nr_periods, nr_throttled,
throttled_usec, memory_current]},
"vm": [занято_jiffies, всего_jiffies],
"lb": {"<слот>": {...}, "FRONTEND": {...}}, # режим list
"pg": {"conn": [[адрес, состояние, ожидание, n], ...],
"db": {xact_commit, xact_rollback, sessions, numbackends}}}
Режимы:
list — заданные контейнеры (`--container id` …), опрос статистики
HAProxy (`/stats;csv` на :8404 внутри сети) и одно постоянное
соединение с PostgreSQL стенда (`pg_stat_activity`,
`pg_stat_database`); его слот занимает одно из
`max_connections`. Серии трека 1;
scan — все каталоги контейнеров в cgroup на каждом тике (новые
реплики видны с первого тика), без сети, LB и PostgreSQL:
наблюдатель не обращается к стенду. Профили failover и rollout.
Пароль PostgreSQL — только из окружения контейнера (`PGPASSWORD`), в
вывод не попадает.
"""
import argparse
import asyncio
import contextlib
import json
import os
import re
import sys
import time
import urllib.request
from pathlib import Path
CGROUP = Path("/sys/fs/cgroup/docker")
HEX64 = re.compile(r"[0-9a-f]{64}")
LB_STATS = "http://haproxy:8404/stats;csv"
LB_FIELDS = ("scur", "stot", "econ", "eresp", "wretr", "wredis", "qcur", "rate")
# соединения приложения: application_name из src/constants.py (копия:
# сэмплер код приложения не импортирует)
APP_NAME = "mtusi-messenger"
PG_CONN_SQL = """
SELECT coalesce(host(client_addr), '-'), coalesce(state, '-'),
coalesce(wait_event_type, 'CPU'), count(*)
FROM pg_stat_activity
WHERE backend_type = 'client backend' AND application_name = $1
GROUP BY 1, 2, 3
"""
PG_DB_SQL = """
SELECT xact_commit, xact_rollback, sessions, numbackends
FROM pg_stat_database WHERE datname = current_database()
"""
def cgroup_line(container: str) -> list[int] | None:
"""usage_usec, nr_periods, nr_throttled, throttled_usec, memory.current."""
folder = CGROUP / container
try:
stat = (folder / "cpu.stat").read_text()
memory = int((folder / "memory.current").read_text())
except (OSError, ValueError):
return None
values = dict(line.split() for line in stat.splitlines() if line)
return [
int(values.get("usage_usec", 0)),
int(values.get("nr_periods", 0)),
int(values.get("nr_throttled", 0)),
int(values.get("throttled_usec", 0)),
memory,
]
def vm_line() -> list[int]:
fields = Path("/proc/stat").read_text().splitlines()[0].split()[1:9]
user, nice, system, idle, iowait, irq, softirq, steal = (int(f) for f in fields)
total = user + nice + system + idle + iowait + irq + softirq + steal
return [total - idle - iowait, total]
def lb_stats() -> dict | None:
try:
with urllib.request.urlopen(LB_STATS, timeout=0.5) as response: # noqa: S310
text = response.read().decode()
except OSError:
return None
lines = text.splitlines()
header = lines[0].lstrip("# ").split(",")
out = {}
for line in lines[1:]:
row = dict(zip(header, line.split(","), strict=False))
if row.get("pxname") != "api" and row.get("pxname") != "entry":
continue
name = "FRONTEND" if row["pxname"] == "entry" else row["svname"]
if name == "FRONTEND" and row["svname"] != "FRONTEND":
continue
out[name] = {
"status": row.get("status", ""),
"addr": row.get("addr", ""),
**{field: int(row[field]) for field in LB_FIELDS if row.get(field)},
}
return out
async def main() -> None:
args = parser().parse_args()
interval = args.interval
connection = None
if args.mode == "list":
import asyncpg # noqa: PLC0415 - нужен только режиму list
for _ in range(20):
try:
connection = await asyncpg.connect(
host="postgres",
user=os.environ["PGUSER"],
database=os.environ["PGDATABASE"],
password=os.environ["PGPASSWORD"],
server_settings={"application_name": "bench-sampler"},
timeout=3,
)
break
except (OSError, asyncpg.PostgresError):
await asyncio.sleep(0.5)
out = open(args.out, "a", encoding="ascii") # noqa: ASYNC230, SIM115
next_tick = time.monotonic()
while True:
ts = time.time()
if args.mode == "scan":
# файлы cgroup — псевдофайловая система ядра: чтение без ожидания
try:
ids = [
p.name
for p in CGROUP.iterdir() # noqa: ASYNC240
if HEX64.fullmatch(p.name)
]
except OSError:
ids = []
else:
ids = args.container
tick: dict = {"ts": round(ts, 3), "cg": {}, "vm": vm_line()}
for container in ids:
line = cgroup_line(container)
if line is not None:
tick["cg"][container[:12]] = line
if args.mode == "list":
tick["lb"] = await asyncio.to_thread(lb_stats)
if connection is not None:
with contextlib.suppress(Exception):
rows = await connection.fetch(PG_CONN_SQL, APP_NAME)
db = await connection.fetchrow(PG_DB_SQL)
# соединения приложения: адрес реплики, состояние, ожидание
tick["pg"] = {
"conn": [list(row) for row in rows],
"db": dict(db),
}
out.write(json.dumps(tick, separators=(",", ":")) + "\n")
out.flush()
next_tick += interval
await asyncio.sleep(max(0.0, next_tick - time.monotonic()))
def parser() -> argparse.ArgumentParser:
root = argparse.ArgumentParser(description=__doc__.splitlines()[0])
root.add_argument("--mode", choices=("list", "scan"), required=True)
root.add_argument("--interval", type=float, default=1.0)
root.add_argument("--out", required=True)
root.add_argument("--container", action="append", default=[])
return root
if __name__ == "__main__":
with contextlib.suppress(KeyboardInterrupt):
asyncio.run(main())
sys.exit(0)
+210
View File
@@ -0,0 +1,210 @@
# Стенд лабы 3: HAProxy — единственная точка входа API, за ним
# API_REPLICAS реплик; PostgreSQL (источник истины: данные, сессии, ключи
# идемпотентности), Valkey (общий кэш карточек чатов), одноразовые
# миграции. Значения ${...} compose берёт из .env (шаблон .env.example,
# `make env`). Порты публикуются только на 127.0.0.1; внутри сети стенда
# порты фиксированы: 5432, 6379, 8080, мониторинг LB — 8404.
# Правила — infra/AGENTS.md; запуск — `make up`.
#
# Имя проекта меняется в каждой лабе: от него зависят имена volume, и
# стенд лабы 3 не подключается к данным лабы 2.
name: vladimirceva-lab3
# окружение по сервисам: секреты получают только те, кому они нужны.
# PostgreSQL — api и migrate
x-db-env: &db-env
LOG_LEVEL: ${LOG_LEVEL:-INFO}
DB_HOST: postgres
DB_PORT: "5432"
DB_NAME: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env}
DB_USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env}
DB_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env}
# Valkey — только api
x-cache-env: &cache-env
CACHE_HOST: valkey
CACHE_PORT: "6379"
CACHE_PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, run make env}
# ужесточение контейнеров приложения: файловая система только для
# чтения, без capabilities и повышения привилегий
x-hardened: &hardened
read_only: true
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
services:
postgres:
image: postgres:18.6-trixie@sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722
restart: unless-stopped
environment:
POSTGRES_USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env}
POSTGRES_DB: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env}
ports:
# только localhost: к нему подключается `make run` и миграции с
# хоста. API наружу так не публикуется — только через LB
- "127.0.0.1:${POSTGRES_HOST_PORT:-5433}:5432"
volumes:
# Postgres 18 хранит данные в /var/lib/postgresql/18/docker; volume
# образа — весь /var/lib/postgresql (Config.Volumes)
- pgdata:/var/lib/postgresql
healthcheck:
# по TCP, а не через сокет: при инициализации образ поднимает
# временный сервер только на сокете, и проверка через сокет
# сказала бы «готов» раньше времени. $$ — переменная контейнера
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
interval: 5s
timeout: 3s
retries: 10
start_period: 30s
start_interval: 1s
deploy:
resources:
limits:
# соединения: API_REPLICAS × (DB_POOL_SIZE + DB_POOL_OVERFLOW) +
# migrate ≤ max_connections (100): 2 × 15 + 1 = 31, при
# поочерёдной замене 3 × 15 + 1 = 46 (REPORT.md, «Лимиты и пулы»)
cpus: "2.0"
memory: 1G
# кэш карточек чатов: volume нет, persistence выключен в valkey.conf —
# после рестарта кэш пуст, данные остаются в PostgreSQL
valkey:
image: valkey/valkey:9.1.2-trixie@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd
restart: unless-stopped
# $$ — переменная контейнера: пароля нет в command литералом. Через
# docker-entrypoint.sh образа: он запускает сервер не от root
command:
- sh
- -c
- exec docker-entrypoint.sh valkey-server /usr/local/etc/valkey/valkey.conf --requirepass "$$VALKEY_PASSWORD"
environment:
VALKEY_PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, run make env}
# пароль для valkey-cli в контейнере (healthcheck), без -a в команде
VALKEYCLI_AUTH: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, run make env}
ports:
# только localhost: к нему подключается `make run`
- "127.0.0.1:${VALKEY_HOST_PORT:-6380}:6379"
volumes:
- type: bind
source: ./infra/valkey/valkey.conf
target: /usr/local/etc/valkey/valkey.conf
read_only: true
bind:
create_host_path: false
healthcheck:
# PONG только после AUTH: проверяет и запуск, и пароль
test: ["CMD-SHELL", 'test "$$(valkey-cli ping)" = PONG']
interval: 5s
timeout: 3s
retries: 10
start_period: 10s
start_interval: 1s
deploy:
resources:
limits:
# maxmemory 64mb в valkey.conf плюс накладные
cpus: "0.5"
memory: 128M
# миграции до старта реплик: тот же образ, другая команда. Один раз на
# `up`, реплики ждут его завершения; сами реплики миграции не запускают
# (их несколько — они гонялись бы за одну схему). Повторный запуск —
# no-op: alembic применяет только недостающие ревизии
migrate:
image: mtusi-messenger-vladimirceva:lab3
# образ собирает сервис api (make up, make docker-build)
pull_policy: never
command: ["python", "-m", "alembic", "upgrade", "head"]
restart: "no"
# только PostgreSQL: пароль Valkey миграциям не нужен
environment: *db-env
<<: *hardened
depends_on:
postgres:
condition: service_healthy
deploy:
resources:
limits:
cpus: "0.5"
memory: 256M
# реплики API: портов наружу нет, фиксированного имени контейнера нет
# (оба мешали бы масштабированию одного сервиса) — запросы идут только
# через haproxy. X-Instance-Id — hostname, то есть короткий ID
# контейнера. Разовая подмена числа — `make replicas API_REPLICAS=N`
api:
build: .
# тот же тег, что у make docker-build
image: mtusi-messenger-vladimirceva:lab3
restart: unless-stopped
environment:
<<: [*db-env, *cache-env]
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400}
SHUTDOWN_TIMEOUT: ${SHUTDOWN_TIMEOUT:-5}
<<: *hardened
# приложение ничего не пишет на диск, кроме временных файлов Python
tmpfs:
- /tmp
depends_on:
postgres:
condition: service_healthy
# без кэша API работает, но в штатном стенде он есть с первого запроса
valkey:
condition: service_healthy
migrate:
condition: service_completed_successfully
# healthcheck — из образа; SIGKILL не раньше, чем через 10 с после
# SIGTERM (uvicorn завершается сам за SHUTDOWN_TIMEOUT ≤ 9 с)
stop_grace_period: 10s
deploy:
replicas: ${API_REPLICAS:-2}
resources:
limits:
# один процесс, один event loop: больше одного CPU он не займёт,
# кроме Argon2id входа в потоках (под лимитом вход медленнее).
# Память: Argon2id 4 × 64 MiB + интерпретатор
cpus: "1.0"
memory: 512M
# единственная точка входа: реплики находит через DNS Docker, проверяет
# /health/ready; конфиг — infra/haproxy/haproxy.cfg. Секретов не получает
haproxy:
image: haproxy:3.4.6-trixie@sha256:e273915691a8eab3f105bf3e39fd4c29a4ecf334e33421903b5589d25e14db26
restart: unless-stopped
ports:
# только localhost: стенд учебный; API с хоста доступно только так
- "127.0.0.1:${HOST_PORT:-8080}:8080"
volumes:
- type: bind
source: ./infra/haproxy/haproxy.cfg
target: /usr/local/etc/haproxy/haproxy.cfg
read_only: true
bind:
create_host_path: false
<<: *hardened
# make stop гасит LB раньше реплик, make up поднимает после них
depends_on:
- api
healthcheck:
# healthy — через LB можно обслужить запрос: /lb/ready отвечает 200,
# пока есть хотя бы одна готовая реплика. curl в образе нет, bash есть
test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8404 && printf 'GET /lb/ready HTTP/1.0\\r\\n\\r\\n' >&3 && head -n 1 <&3 | grep -q ' 200 '"]
interval: 5s
timeout: 3s
retries: 3
start_period: 10s
start_interval: 1s
deploy:
resources:
limits:
# nbthread 1 в haproxy.cfg
cpus: "1.0"
memory: 256M
volumes:
pgdata:
+62
View File
@@ -0,0 +1,62 @@
# evidence/ — доказательства для REPORT.md
Требования преподавателя — `evidence/README.md` (skeleton, не менять).
Каждый файл здесь — подтверждение строки таблицы «Доказательства
критериев» в `REPORT.md`. Доказательства лабы 2 остались в её
репозитории: сюда они не копируются даже по одному файлу — всё снято
заново на стенде лабы 3.
## Правила
- **Только реальный вывод** команд, которые ты сам запустил в этой
задаче. Не дописывать «ожидаемый» результат, не править числа, не
склеивать выводы разных прогонов без пометки. Нечем проверить (нет
docker, сети) — не создавать файл, а сказать пользователю.
- Шапка файла — комментарии `#`: что доказывает (критерий рубрики), дата
UTC, окружение (ОС, CPU, версии Docker, Compose, Python), стенд
(рабочий `make up` и его порт, отдельный стенд тестов), код
(`src_sha256` — хеш `src/` и `migrations/`, как в паспорте `bench/`;
commit, если проект под git). Как повторить — команды.
- Команда — строкой `$ ...`, под ней вывод. Длинный вывод можно
сокращать с пометкой `...`, но не менять строки, на которые ссылается
отчёт.
- Итог — комментарием `#` после вывода: что именно видно и почему это
закрывает критерий.
- Без секретов, токенов, `.env`, реальных данных и текстов сообщений;
абсолютные пути домашнего каталога — `<репозиторий>`. Значения
переменных окружения контейнеров не печатать — только имена.
- Файл пишется инструментом правки (`apply_patch`), а не перенаправлением
`>` из shell: так правку видно в диффе.
## Состав
| Файл | Критерий |
|---|---|
| `replicas/stand.txt` | стенд: HAProxy — единственный порт API, ≥ 2 реплики без портов и `container_name`, лимиты CPU/RAM у всех, секреты только где нужны |
| `replicas/instances.txt` | одна сессия на разных репликах (`X-Instance-Id`), шаг 1 защиты |
| `failover/failover-each.txt` | `make test-failover` для каждой реплики, `stop` и `kill`; какой контейнер остановлен (`STOP_ONE_LOG`, `docker compose ps`) |
| `stand/persistence.txt` | `make test-persistence`: данные и прежний токен после рестарта LB, реплик и хранилищ; `StartedAt` до и после |
| `stand/migrations.txt` | миграции однократно сервисом `migrate`, повтор — no-op, `alembic check`, схема ключей идемпотентности |
| `stand/early-stop.txt` | SIGTERM во время старта и после: быстрый выход с кодом 0 |
| `stand/fresh-copy.txt` | копия без игнорируемых файлов (как чистый clone): `make check`, `lint`, `validate`, `requirements-check`, `test-isolated` |
| `rollout/rolling-update.txt` | `make rolling-update`: миграции один раз, по одной реплике через drain, smoke после |
| `tests/test-isolated.txt` | smoke, свои тесты через LB с тестами реплик, `test-failover`, `test-persistence` на отдельном стенде |
| `tests/student-test-lb.txt` | свои тесты через LB рабочего стенда; вывод тестов реплик и идемпотентности через разные реплики |
| `tests/failure-checks.txt` | проверки отказов уровня 4 с замеренным временем (в том числе ключ идемпотентности) |
| `failover/<метка>/` | уровень 4: отказ каждой реплики под нагрузкой (`make bench-failover`) |
| `rollout/<метка>/` | уровень 4: поочерёдная замена под нагрузкой с expand-миграцией (`make bench-rollout`) |
| `scaling/<метка>/` | трек 1: серии конфигураций, R*, признаки узкого места (`make bench-scaling`) |
| `compare/<до>__<после>.md` | трек 1: «до/после» улучшения с шумом A/A (`make bench-compare`) |
| `plots/<имя>/` | трек 1: графики и точка насыщения (`make bench-plots`) |
Поменялось поведение, которое показано в файле, — перезапусти проверку
и обнови файл целиком, вместе с датой в шапке.
## Каталоги меток — исключение из правил выше
`failover/<метка>/`, `rollout/<метка>/`, `scaling/<метка>/`, `compare/`,
`plots/` пишут стенд и его скрипты (`make bench-*`): руками их не
править и не создавать, шапку и паспорт стенд ставит сам. Каталог метки
не перезаписывается и не удаляется без согласия пользователя. Метки
`quick-*` — самопроверки, в git и отчёт не идут. Правила —
`bench/AGENTS.md`, порядок — `bench/RUNBOOK.md`.
+127
View File
@@ -0,0 +1,127 @@
# Что доказывает (уровень 3, шаги 2–3 сценария защиты; уровень 4 — «каждую
# реплику по очереди»): make test-failover проходит для КАЖДОЙ реплики в
# режимах stop (SIGTERM, graceful) и kill (SIGKILL, без graceful):
# до отказа видны ≥ 2 реплики, запись восстанавливается ≤ 10 с, остановленная
# реплика не отвечает, подтверждённые сообщения целы, неопределённый POST
# повторяется с тем же ключом без дублей. Какой контейнер действительно
# остановлен — docker compose ps до и после и строка STOP_ONE_LOG (ID
# совпадает с TARGET_INSTANCE_ID, который выбрал тест). Перед прогоном для
# следующей реплики предыдущая возвращена (make replicas — те же
# контейнеры и ID).
# Дата (UTC): 2026-10-13T22:09:40Z — 2026-10-13T22:12:20Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1;
# python3 хоста 3.11.9
# Стенд: рабочий проект vladimirceva-lab3, 2 реплики за HAProxy на
# 127.0.0.1:8090 (на этой машине), код src_sha256 0349e9a270178467.
# Как повторить: make failover-each [STOP_MODE=kill]
# (scripts/lab3.py failover-each: make replicas, ожидание UP всех слотов
# в LB, при необходимости сдвиг очереди round-robin, make test-failover
# ACTION_SCRIPT=scripts/stop-one.sh с STOP_ONE_LOG, docker compose ps).
# Вывод hook тест скрывает; строку о контейнере hook пишет в STOP_ONE_LOG.
# Число запросов в секунду и время восстановления под постоянной нагрузкой
# — не этот тест, а профиль failover стенда bench/ (make bench-failover,
# evidence/failover/<метка>/).
## STOP_MODE=stop
$ make failover-each BASE_URL=http://localhost:8090
python3 scripts/lab3.py failover-each --base-url "http://localhost:8090" \
--replicas 2 --mode stop
=== attempt 1: docker compose ps before
NAME CONTAINER ID STATE STATUS
vladimirceva-lab3-api-3 d69ba3cda2cf running Up 31 seconds (healthy)
vladimirceva-lab3-api-4 4c13b772d928 running Up 39 minutes (healthy)
vladimirceva-lab3-haproxy-1 dbbd5323b65f running Up 39 minutes (healthy)
vladimirceva-lab3-migrate-1 4d22bee7c479 exited Exited (0) 39 minutes ago
vladimirceva-lab3-postgres-1 853f7b94f164 running Up 39 minutes (healthy)
vladimirceva-lab3-valkey-1 2b35e0afc56e running Up 39 minutes (healthy)
$ make test-failover ACTION_SCRIPT=scripts/stop-one.sh (STOP_MODE=stop)
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 116, "failed_attempts": 0, "first_recovery_seconds": 1.599}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
STOP_ONE_LOG: 2026-10-13T22:09:57Z TARGET_INSTANCE_ID=d69ba3cda2cf container=d69ba3cda2cfa0a2cee26985622395bac8ff7058c0b0eff41c702fd2738e8243 mode=stop
docker compose ps after
NAME CONTAINER ID STATE STATUS
vladimirceva-lab3-api-3 d69ba3cda2cf exited Exited (0) 14 seconds ago
vladimirceva-lab3-api-4 4c13b772d928 running Up 39 minutes (healthy)
vladimirceva-lab3-haproxy-1 dbbd5323b65f running Up 39 minutes (healthy)
vladimirceva-lab3-migrate-1 4d22bee7c479 exited Exited (0) 39 minutes ago
vladimirceva-lab3-postgres-1 853f7b94f164 running Up 40 minutes (healthy)
vladimirceva-lab3-valkey-1 2b35e0afc56e running Up 40 minutes (healthy)
=== attempt 2: docker compose ps before
NAME CONTAINER ID STATE STATUS
vladimirceva-lab3-api-3 d69ba3cda2cf running Up 1 second (healthy)
vladimirceva-lab3-api-4 4c13b772d928 running Up 39 minutes (healthy)
...
$ make test-failover ACTION_SCRIPT=scripts/stop-one.sh (STOP_MODE=stop)
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 115, "failed_attempts": 0, "first_recovery_seconds": 1.22}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
STOP_ONE_LOG: 2026-10-13T22:10:15Z TARGET_INSTANCE_ID=4c13b772d928 container=4c13b772d92828b4a54cd40e8c6214c95ea69a2c0231aeffd36acd81c57870d3 mode=stop
...
replicas stopped one by one: ['4c13b772d928', 'd69ba3cda2cf']; all restored:
...
## STOP_MODE=kill
$ make failover-each BASE_URL=http://localhost:8090 STOP_MODE=kill
python3 scripts/lab3.py failover-each --base-url "http://localhost:8090" \
--replicas 2 --mode kill
=== attempt 1: docker compose ps before
NAME CONTAINER ID STATE STATUS
vladimirceva-lab3-api-3 d69ba3cda2cf running Up About a minute (healthy)
vladimirceva-lab3-api-4 4c13b772d928 running Up About a minute (healthy)
vladimirceva-lab3-haproxy-1 dbbd5323b65f running Up 41 minutes (healthy)
vladimirceva-lab3-migrate-1 4d22bee7c479 exited Exited (0) 41 minutes ago
vladimirceva-lab3-postgres-1 853f7b94f164 running Up 41 minutes (healthy)
vladimirceva-lab3-valkey-1 2b35e0afc56e running Up 41 minutes (healthy)
$ make test-failover ACTION_SCRIPT=scripts/stop-one.sh (STOP_MODE=kill)
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 120, "failed_attempts": 0, "first_recovery_seconds": 0.745}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
STOP_ONE_LOG: 2026-10-13T22:11:48Z TARGET_INSTANCE_ID=4c13b772d928 container=4c13b772d92828b4a54cd40e8c6214c95ea69a2c0231aeffd36acd81c57870d3 mode=kill
docker compose ps after
NAME CONTAINER ID STATE STATUS
vladimirceva-lab3-api-3 d69ba3cda2cf running Up About a minute (healthy)
vladimirceva-lab3-api-4 4c13b772d928 exited Exited (137) 15 seconds ago
vladimirceva-lab3-haproxy-1 dbbd5323b65f running Up 41 minutes (healthy)
vladimirceva-lab3-migrate-1 4d22bee7c479 exited Exited (0) 41 minutes ago
vladimirceva-lab3-postgres-1 853f7b94f164 running Up 41 minutes (healthy)
vladimirceva-lab3-valkey-1 2b35e0afc56e running Up 41 minutes (healthy)
=== attempt 2: docker compose ps before
NAME CONTAINER ID STATE STATUS
vladimirceva-lab3-api-3 d69ba3cda2cf running Up About a minute (healthy)
vladimirceva-lab3-api-4 4c13b772d928 running Up 2 seconds (healthy)
...
$ make test-failover ACTION_SCRIPT=scripts/stop-one.sh (STOP_MODE=kill)
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 122, "failed_attempts": 0, "first_recovery_seconds": 0.237}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
STOP_ONE_LOG: 2026-10-13T22:12:07Z TARGET_INSTANCE_ID=d69ba3cda2cf container=d69ba3cda2cfa0a2cee26985622395bac8ff7058c0b0eff41c702fd2738e8243 mode=kill
docker compose ps after
NAME CONTAINER ID STATE STATUS
vladimirceva-lab3-api-3 d69ba3cda2cf exited Exited (137) 15 seconds ago
vladimirceva-lab3-api-4 4c13b772d928 running Up 18 seconds (healthy)
...
replicas stopped one by one: ['4c13b772d928', 'd69ba3cda2cf']; all restored:
NAME CONTAINER ID STATE STATUS
vladimirceva-lab3-api-3 d69ba3cda2cf running Up 1 second (healthy)
vladimirceva-lab3-api-4 4c13b772d928 running Up 19 seconds (healthy)
vladimirceva-lab3-haproxy-1 dbbd5323b65f running Up 42 minutes (healthy)
vladimirceva-lab3-migrate-1 4d22bee7c479 exited Exited (0) 41 minutes ago
vladimirceva-lab3-postgres-1 853f7b94f164 running Up 42 minutes (healthy)
vladimirceva-lab3-valkey-1 2b35e0afc56e running Up 42 minutes (healthy)
# Итог: 4 прогона × PASS; остановлена ровно та реплика, которую назвал
# тест (ID в STOP_ONE_LOG = ID контейнера в exited), вторая работает,
# хранилища и LB не трогались, volume на месте. Код выхода остановленной:
# 0 при stop (graceful, uvicorn завершился сам), 137 при kill (SIGKILL).
# Неудачных попыток записи — 0 во всех прогонах: отказ соединения с
# остановленной репликой HAProxy повторяет на живую (retry-on
# conn-failure, redispatch); первая запись после hook — через 0,24–1,6 с
# (hook ждёт docker stop/kill, тест шлёт параллельно). «...» — повтор той
# же таблицы docker compose ps, опущен.
+35
View File
@@ -0,0 +1,35 @@
# Что доказывает (уровень 3, шаг 1 сценария защиты): разные запросы одного
# пользователя с одной сессией обслуживают разные реплики без повторного
# входа — это видно по X-Instance-Id; LB — round-robin без sticky session.
# Дата (UTC): 2026-10-13T22:11Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1;
# python3 хоста 3.11.9
# Стенд: рабочий проект vladimirceva-lab3, 2 реплики за HAProxy на
# 127.0.0.1:8090 (на этой машине; по умолчанию 8080), код src_sha256
# 0349e9a270178467.
# Как повторить: make instances (BASE_URL по умолчанию http://localhost:8080)
# Скрипт регистрирует синтетического пользователя, входит по Basic один
# раз и шлёт GET /api/v1/users/me с тем же токеном; пароль и токен не
# печатаются.
$ make instances BASE_URL=http://localhost:8090
python3 scripts/lab3.py instances --base-url "http://localhost:8090"
one session, 12 x GET /api/v1/users/me via http://localhost:8090
1: 200 X-Instance-Id=d69ba3cda2cf
2: 200 X-Instance-Id=4c13b772d928
3: 200 X-Instance-Id=d69ba3cda2cf
4: 200 X-Instance-Id=4c13b772d928
5: 200 X-Instance-Id=d69ba3cda2cf
6: 200 X-Instance-Id=4c13b772d928
7: 200 X-Instance-Id=d69ba3cda2cf
8: 200 X-Instance-Id=4c13b772d928
9: 200 X-Instance-Id=d69ba3cda2cf
10: 200 X-Instance-Id=4c13b772d928
11: 200 X-Instance-Id=d69ba3cda2cf
12: 200 X-Instance-Id=4c13b772d928
replicas seen: 2 {'d69ba3cda2cf': 6, '4c13b772d928': 6}
# X-Instance-Id — hostname контейнера (начало его ID): по нему видно, какие
# процессы ответили (docker compose ps — evidence/replicas/stand.txt).
# Одного заголовка для доказательства «разных процессов» мало: остановка
# именно этого контейнера и запись на другом — evidence/failover/.
+60
View File
@@ -0,0 +1,60 @@
# Что доказывает (уровни 3 и 4): стенд compose лабы 3 — HAProxy единственная
# точка входа API (единственный опубликованный порт API, только
# 127.0.0.1), за ним две реплики сервиса api без портов и без
# container_name (масштабирование одного сервиса), одна PostgreSQL, один
# Valkey, одноразовый migrate. Лимиты CPU/RAM у всех контейнеров;
# секреты — только тем, кому нужны: пароль PostgreSQL — api и migrate,
# пароль Valkey — api (и сам Valkey), у HAProxy окружения нет.
# Дата (UTC): 2026-10-13T22:10:57Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1;
# uv 0.12.17; python3 хоста 3.11.9
# Стенд: рабочий проект compose vladimirceva-lab3 (make up); код
# src_sha256 0349e9a270178467. На машине разработки 8080/5433/6380
# заняты другим стендом, поэтому в локальном .env HOST_PORT=8090,
# POSTGRES_HOST_PORT=5443, VALKEY_HOST_PORT=6390; по умолчанию — 8080,
# 5433, 6380 (.env.example).
# Имена контейнеров api-3/api-4: до снимка реплики уже заменялись
# поочерёдно (make rolling-update), compose нумерует новые по возрастанию.
# Как повторить: make up; docker compose ps; docker inspect каждого
# контейнера проекта (значения переменных окружения не печатаются —
# только имена).
$ docker compose ps -a --format "table {{.Name}}\t{{.Image}}\t{{.State}}\t{{.Ports}}"
NAME IMAGE STATE PORTS
vladimirceva-lab3-api-3 mtusi-messenger-vladimirceva:lab3 running 8080/tcp
vladimirceva-lab3-api-4 mtusi-messenger-vladimirceva:lab3 running 8080/tcp
vladimirceva-lab3-haproxy-1 haproxy:3.4.6-trixie@sha256:e273915691a8eab3f105bf3e39fd4c29a4ecf334e33421903b5589d25e14db26 running 127.0.0.1:8090->8080/tcp
vladimirceva-lab3-migrate-1 mtusi-messenger-vladimirceva:lab3 exited
vladimirceva-lab3-postgres-1 postgres:18.6-trixie@sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722 running 127.0.0.1:5443->5432/tcp
vladimirceva-lab3-valkey-1 valkey/valkey:9.1.2-trixie@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd running 127.0.0.1:6390->6379/tcp
$ docker inspect: лимиты, опубликованные порты, read-only, capabilities, имена переменных окружения
vladimirceva-lab3-api-3 service=api cpus=1 memory=512MiB swap=1024MiB published=- read_only=True cap_drop=['ALL'] restart=unless-stopped
env: APP_HOST, APP_PORT, CACHE_HOST, CACHE_PASSWORD, CACHE_PORT, DB_HOST, DB_NAME, DB_PASSWORD, DB_PORT, DB_USER, IDEMPOTENCY_TTL_SECONDS, LOG_LEVEL, SESSION_TTL_SECONDS, SHUTDOWN_TIMEOUT
vladimirceva-lab3-api-4 service=api cpus=1 memory=512MiB swap=1024MiB published=- read_only=True cap_drop=['ALL'] restart=unless-stopped
env: APP_HOST, APP_PORT, CACHE_HOST, CACHE_PASSWORD, CACHE_PORT, DB_HOST, DB_NAME, DB_PASSWORD, DB_PORT, DB_USER, IDEMPOTENCY_TTL_SECONDS, LOG_LEVEL, SESSION_TTL_SECONDS, SHUTDOWN_TIMEOUT
vladimirceva-lab3-haproxy-1 service=haproxy cpus=1 memory=256MiB swap=512MiB published=['127.0.0.1:8090->8080/tcp'] read_only=True cap_drop=['ALL'] restart=unless-stopped
env: -
vladimirceva-lab3-migrate-1 service=migrate cpus=0.5 memory=256MiB swap=512MiB published=- read_only=True cap_drop=['ALL'] restart=no
env: APP_HOST, APP_PORT, DB_HOST, DB_NAME, DB_PASSWORD, DB_PORT, DB_USER, LOG_LEVEL
vladimirceva-lab3-postgres-1 service=postgres cpus=2 memory=1024MiB swap=2048MiB published=['127.0.0.1:5443->5432/tcp'] read_only=False cap_drop=- restart=unless-stopped
env: POSTGRES_DB, POSTGRES_PASSWORD, POSTGRES_USER
vladimirceva-lab3-valkey-1 service=valkey cpus=0.5 memory=128MiB swap=256MiB published=['127.0.0.1:6390->6379/tcp'] read_only=False cap_drop=- restart=unless-stopped
env: VALKEYCLI_AUTH, VALKEY_PASSWORD
$ docker compose config --format json → services.api
{'container_name': None, 'ports': None, 'deploy.replicas': 2, 'limits': {'cpus': 1, 'memory': '536870912'}}
$ lsof -nP -iTCP:8090 -sTCP:LISTEN
com.docke 4350 roman 138u IPv4 0x8440e97e735d7c33 0t0 TCP 127.0.0.1:8090 (LISTEN)
# Итог. Наружу (127.0.0.1) опубликованы только HAProxy (API), PostgreSQL и
# Valkey (для make run и миграций с хоста); у реплик портов нет, запросы к
# API идут только через LB. container_name у api нет, число реплик —
# deploy.replicas (API_REPLICAS). Сумма лимитов: CPU 2 × 1 + 2 + 0,5 + 1 =
# 5,5 (+0,5 у migrate на время миграций), память 2 × 512 + 1024 + 128 +
# 256 = 2432 МиБ (+256 у migrate). Swap контейнеров рабочего стенда — по
# умолчанию Docker (= лимиту памяти); на нагрузочном стенде bench/ swap
# выключен (memswap_limit = memory). Пул PostgreSQL: 2 реплики × (10 + 5)
# + migrate 1 = 31 ≤ max_connections 100; при поочерёдной замене на пике
# три реплики — 46.
+66
View File
@@ -0,0 +1,66 @@
# Что доказывает (уровень 4, функционально): make rolling-update заменяет
# реплики по одной без простоя: сборка, миграции один раз в контейнере
# сервиса migrate (до первой новой реплики), затем для каждой старой —
# новая реплика healthy и UP в LB → старая drain (запросов в полёте 0) →
# maint → docker stop (exit 0 — graceful) → docker rm → слот ready. После
# замены — две новые реплики, публичный smoke PASS, оба слота UP.
# Поведение под постоянной нагрузкой (ошибки, RPS по секундам, ответы
# старых и новых реплик, настоящая expand-миграция схемы) — профиль
# rollout стенда bench/ (make bench-rollout, evidence/rollout/<метка>/).
# Дата (UTC): 2026-10-13T22:12:50Z — 2026-10-13T22:13:05Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1
# Стенд: рабочий проект vladimirceva-lab3, HAProxy на 127.0.0.1:8090 (на
# этой машине), код src_sha256 0349e9a270178467. Код не менялся: образ
# пересобран из того же дерева (кэш слоёв), ревизия схемы та же — шаг
# миграции здесь no-op.
# Как повторить: make rolling-update [API_REPLICAS=2]
$ docker compose ps --format "table {{.Name}}\t{{.ID}}\t{{.Status}}" api (до)
NAME CONTAINER ID STATUS
vladimirceva-lab3-api-3 d69ba3cda2cf Up 8 seconds (healthy)
vladimirceva-lab3-api-4 4c13b772d928 Up 8 seconds (healthy)
$ make rolling-update
22:12:50 rolling-update: start: 2 replicas d69ba3cda2cf 4c13b772d928, image mtusi-messenger-vladimirceva:lab3
22:12:52 rolling-update: build done in 2s
migrate-1 | 2026-10-13T22:12:54.563Z INFO src.migrations [rid=-] migrations started db=postgres:5432/messenger
migrate-1 | 2026-10-13T22:12:54.649Z INFO alembic.runtime.migration [rid=-] Context impl PostgresqlImpl.
migrate-1 | 2026-10-13T22:12:54.650Z INFO alembic.runtime.migration [rid=-] Will assume transactional DDL.
migrate-1 | 2026-10-13T22:12:54.655Z INFO src.migrations [rid=-] migrations finished db=messenger
migrate-1 exited with code 0
22:12:55 rolling-update: migrate done in 3s
22:12:55 rolling-update: replica 1/2: started new 4d3d6014596b
22:12:57 rolling-update: replica 1/2: new 4d3d6014596b addr 172.31.0.7 slot api-3 UP in 2s
22:12:58 rolling-update: replica 1/2: drain old d69ba3cda2cf addr 172.31.0.5 slot api-1
22:12:58 rolling-update: replica 1/2: old d69ba3cda2cf idle after 0s
22:12:58 rolling-update: replica 1/2: maint slot api-1, stopping old d69ba3cda2cf
22:12:58 rolling-update: replica 1/2: removed old d69ba3cda2cf (stop 0s, exit 0)
22:12:59 rolling-update: replica 1/2: slot api-1 ready
22:12:59 rolling-update: replica 2/2: started new 68dfb44b44c1
22:13:02 rolling-update: replica 2/2: new 68dfb44b44c1 addr 172.31.0.5 slot api-1 UP in 3s
22:13:02 rolling-update: replica 2/2: drain old 4c13b772d928 addr 172.31.0.4 slot api-2
22:13:02 rolling-update: replica 2/2: old 4c13b772d928 idle after 0s
22:13:02 rolling-update: replica 2/2: maint slot api-2, stopping old 4c13b772d928
22:13:03 rolling-update: replica 2/2: removed old 4c13b772d928 (stop 0s, exit 0)
22:13:03 rolling-update: replica 2/2: slot api-2 ready
22:13:03 rolling-update: done: 2 replicas 4d3d6014596b 68dfb44b44c1 UP in 13s
$ docker compose ps ... api (после)
NAME CONTAINER ID STATUS
vladimirceva-lab3-api-5 4d3d6014596b Up 8 seconds (healthy)
vladimirceva-lab3-api-6 68dfb44b44c1 Up 3 seconds (healthy)
$ make test BASE_URL=http://localhost:8090
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
$ make lb-stats
slot addr status scur stot econ eresp wretr wredis
api-1 172.31.0.5:8080 UP 0 19 0 0 0 0
api-3 172.31.0.7:8080 UP 0 16 0 0 0 0
# Вывод сборки образа отфильтрован (оставлены строки скрипта и
# контейнера migrate). Compose нумерует новые контейнеры сервиса по
# возрастанию: после замены реплики — api-5 и api-6; штатные цели
# (make replicas, stop-one.sh, restart.sh) работают с сервисом api, а не с
# именами. Слот LB — свойство адреса из DNS, а не контейнера: новая
# реплика получила адрес и слот только что удалённой.
+41
View File
@@ -0,0 +1,41 @@
# Что доказывает (уровень 4: «прекращение приёма при SIGTERM настроено»):
# SIGTERM реплике завершает её быстро и с кодом 0 в обоих окнах:
# - во время старта (импорт приложения, обработчика uvicorn ещё нет) —
# ранний обработчик src/early_stop.py: одна строка журнала и выход 0;
# без него PID 1 терял бы сигнал, и docker stop ждал бы 10 с и SIGKILL;
# - после старта — штатная остановка uvicorn: «Shutting down» →
# lifespan закрывает пул PostgreSQL и клиент Valkey → «Finished server
# process», код 0, задолго до stop_grace_period 10 с.
# Дата (UTC): 2026-10-13T22:13:13Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2
# Стенд: отдельный контейнер на образе mtusi-messenger-vladimirceva:lab3
# (код src_sha256 0349e9a270178467) с --cpus 1, без хранилищ: процессу
# для старта и остановки они не нужны (соединения открываются лениво).
# Строки warning о пустых паролях (у пробного контейнера нет окружения
# стенда) из вывода убраны.
# Как повторить: команды ниже; <probe> — имя пробного контейнера.
$ docker run -d --cpus 1 --name <probe> mtusi-messenger-vladimirceva:lab3; sleep 0.15; time docker stop <probe>
docker stop took 0.10s
exit code 0, OOMKilled false
$ docker logs <probe>
2026-10-13T22:13:13.173Z INFO src.early_stop [rid=-] stopped before startup signal=SIGTERM instance=dc17a792469e
$ docker run -d --cpus 1 --name <probe> mtusi-messenger-vladimirceva:lab3; sleep 4; time docker stop <probe>
docker stop took 0.41s
exit code 0, OOMKilled false
$ docker logs <probe>
2026-10-13T22:13:14.138Z INFO uvicorn.error [rid=-] Started server process [1]
2026-10-13T22:13:14.138Z INFO uvicorn.error [rid=-] Waiting for application startup.
2026-10-13T22:13:14.199Z INFO src.main [rid=-] messenger started instance=18a3fead18ab host=0.0.0.0 port=8080 pid=1 db=127.0.0.1:5432/messenger cache=127.0.0.1:6379 pool=10+5 session_ttl=3600s idempotency_ttl=86400s shutdown_timeout=5s keep_alive=60s
2026-10-13T22:13:14.200Z INFO uvicorn.error [rid=-] Application startup complete.
2026-10-13T22:13:14.200Z INFO uvicorn.error [rid=-] Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
2026-10-13T22:13:17.627Z INFO uvicorn.error [rid=-] Shutting down
2026-10-13T22:13:17.729Z INFO uvicorn.error [rid=-] Waiting for application shutdown.
2026-10-13T22:13:17.731Z INFO src.main [rid=-] messenger stopped instance=18a3fead18ab
2026-10-13T22:13:17.731Z INFO uvicorn.error [rid=-] Application shutdown complete.
2026-10-13T22:13:17.731Z INFO uvicorn.error [rid=-] Finished server process [1]
# Время docker stop измерено на хосте (вызов CLI целиком). Остановка под
# нагрузкой с запросами в полёте и время исключения реплики из LB —
# профиль failover стенда bench/ (make bench-failover).
+92
View File
@@ -0,0 +1,92 @@
# Что доказывает: решение собирается и проходит проверки из копии только
# тех файлов, что попадут в git (как чистый clone): без .env, .venv,
# кэшей и пробных меток стенда. На чистом отдельном стенде из этой копии
# — smoke, свои тесты через LB с двумя репликами, test-failover и
# test-persistence.
# Дата (UTC): 2026-10-13T22:32:16Z — 2026-10-13T22:33:08Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1;
# uv 0.12.17; python3 хоста 3.11.9
# Как сделана копия: проект — не git-репозиторий, поэтому список файлов
# взят у git с временным GIT_DIR вне проекта по правилам .gitignore:
# git --git-dir=<tmp>/g init -q
# git --git-dir=<tmp>/g --work-tree=. ls-files -co --exclude-standard -z \
# | tar --null -T - -cf - | tar -xf - -C <tmp>/fresh
# Код src_sha256 0349e9a270178467. Временные пути заменены на <tmp>;
# строки docker compose о контейнерах, сети и сборке, список пакетов
# uv sync опущены («...»).
$ cd <tmp>/fresh; find . -type f | wc -l; test -e .env || echo "no .env"; test -e .venv || echo "no .venv"; ls evidence
135
no .env
no .venv
AGENTS.md
README.md
failover
replicas
rollout
stand
tests
$ make check
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ uv sync --frozen
...
$ make lint
uv run ruff format --check .
84 files already formatted
uv run ruff check .
All checks passed!
$ make requirements-check
requirements.txt matches uv.lock
$ make validate PYTHON=.venv/bin/python
.venv/bin/python scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
$ uv run python bench/analysis.py --selftest
analysis selftest: ok
$ make test-isolated
python3 student-tests/stand.py isolated
[isolated] project=vladimirceva-lab3-isolated
[isolated] build image
...
[isolated] start postgres and valkey
...
[isolated] migrations
...
2026-10-13T22:32:22.969Z INFO alembic.runtime.migration [rid=-] Running upgrade -> 0001, messenger schema: users, sessions, chats, chat members, messages
2026-10-13T22:32:22.978Z INFO alembic.runtime.migration [rid=-] Running upgrade 0001 -> 0002, idempotency keys for sending messages
2026-10-13T22:32:22.983Z INFO src.migrations [rid=-] migrations finished db=messenger
...
[isolated] ready: lb=http://127.0.0.1:63899 replicas=2
[isolated] make test
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
[isolated] pytest
...
collected 99 items / 15 deselected / 84 selected
...
====================== 84 passed, 15 deselected in 14.00s ======================
[isolated] make test-failover (scripts/stop-one.sh)
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 121, "failed_attempts": 0, "first_recovery_seconds": 1.2}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
[isolated] restore replicas
...
[isolated] make test-persistence (scripts/restart.sh)
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
[isolated] cleanup
[isolated] results: {'test': 0, 'student-test': 0, 'test-failover': 0, 'test-persistence': 0}
# Из копии без локальных файлов: контракт и OpenAPI валидны, линтер чист,
# requirements.txt совпадает с uv.lock, самопроверка разбора стенда
# проходит, образ собирается, на пустой базе — миграции 0001 и 0002,
# smoke PASS, 84 passed, test-failover и test-persistence PASS.
# Отдельному стенду .env не нужен: пароли он генерирует сам. Настоящий
# git clone — после публикации (REPORT.md); после замеров Codex
# переснимает этот файл (bench/RUNBOOK.md, шаг 6).
+61
View File
@@ -0,0 +1,61 @@
# Что доказывает (уровни 3 и 4): миграции выполняются однократно и
# отдельно от реплик — сервисом migrate (на пустом volume: 0001 → 0002,
# см. evidence/tests/test-isolated.txt), повторный upgrade head — no-op;
# схема в базе совпадает с описанием src/storage/tables.py (alembic check);
# ревизия 0002 — только расширение: новая таблица idempotency_keys с
# ограничениями, существующие таблицы не меняются, поэтому реплики прежней
# версии работают на новой схеме во время поочерёдной замены.
# Дата (UTC): 2026-10-13T22:13:28Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1;
# uv 0.12.17
# Стенд: рабочий проект vladimirceva-lab3, PostgreSQL на 127.0.0.1:5443 (на
# этой машине; по умолчанию 5433), код src_sha256 0349e9a270178467.
# Как повторить: make migrate-local; alembic check — команда в
# migrations/AGENTS.md («Проверка ревизии»); пароли из .env в вывод не
# попадают.
$ make migrate-local # повторный upgrade head на рабочей базе
.env ready
docker compose up -d --wait postgres valkey
uv run alembic upgrade head # 127.0.0.1:5443
2026-10-13T22:13:28.112Z INFO src.migrations [rid=-] migrations started db=127.0.0.1:5443/messenger
2026-10-13T22:13:28.137Z INFO alembic.runtime.migration [rid=-] Context impl PostgresqlImpl.
2026-10-13T22:13:28.137Z INFO alembic.runtime.migration [rid=-] Will assume transactional DDL.
2026-10-13T22:13:28.145Z INFO src.migrations [rid=-] migrations finished db=messenger
$ alembic check (окружение из .env, как make migrate-local)
2026-10-13T22:13:28.976Z INFO src.migrations [rid=-] migrations started db=127.0.0.1:5443/messenger
...
2026-10-13T22:13:29.055Z INFO src.migrations [rid=-] migrations finished db=messenger
No new upgrade operations detected.
$ alembic current
0002 (head)
$ docker compose exec -T postgres psql ... -c "\d idempotency_keys"
Table "public.idempotency_keys"
Column | Type | Collation | Nullable | Default
--------------+--------------------------+-----------+----------+---------
user_id | uuid | | not null |
chat_id | uuid | | not null |
key | text | | not null |
request_hash | bytea | | not null |
message_id | uuid | | not null |
created_at | timestamp with time zone | | not null |
Indexes:
"pk_idempotency_keys" PRIMARY KEY, btree (user_id, chat_id, key)
"ix_idempotency_keys_created_at" btree (created_at)
Check constraints:
"ck_idempotency_keys_key_format" CHECK (key ~ '^[A-Za-z0-9._:-]{1,128}$'::text)
"ck_idempotency_keys_request_hash_length" CHECK (octet_length(request_hash) = 32)
Foreign-key constraints:
"fk_idempotency_keys_chat_id_user_id_chat_members" FOREIGN KEY (chat_id, user_id) REFERENCES chat_members(chat_id, user_id)
"fk_idempotency_keys_message_id_messages" FOREIGN KEY (message_id) REFERENCES messages(id) DEFERRABLE INITIALLY DEFERRED
# Повторный upgrade head — без строк «Running upgrade»: ревизии уже
# применены. В выводе alembic check опущены строки настройки плагинов
# autogenerate («...»). Ключ идемпотентности — первичный ключ (автор, чат,
# ключ); внешний ключ на сообщение отложен до commit: ключ вставляется
# раньше сообщения в той же транзакции. Миграция под нагрузкой с
# настоящим изменением схемы (ADD COLUMN, lock_timeout 2 с) — профиль
# rollout стенда bench/.
+43
View File
@@ -0,0 +1,43 @@
# Что доказывает (уровень 3): make test-persistence с hook
# scripts/restart.sh — после перезапуска LB, ВСЕХ реплик API, PostgreSQL и
# Valkey с сохранённым volume те же данные читаются прежним токеном без
# повторного входа. Что перезапускалось действительно всё — StartedAt
# каждого контейнера до и после; volume pgdata тот же.
# Дата (UTC): 2026-10-13T22:12:30Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1;
# python3 хоста 3.11.9
# Стенд: рабочий проект vladimirceva-lab3, HAProxy на 127.0.0.1:8090 (на
# этой машине), код src_sha256 0349e9a270178467.
# Как повторить: make test-persistence ACTION_SCRIPT=scripts/restart.sh
$ docker inspect -f '{{.Name}} {{.State.Status}} StartedAt={{.State.StartedAt}}' (до)
vladimirceva-lab3-api-3 running StartedAt=2026-10-13T22:12:22.311014221Z
vladimirceva-lab3-api-4 running StartedAt=2026-10-13T22:12:03.968075546Z
vladimirceva-lab3-haproxy-1 running StartedAt=2026-10-13T21:30:16.255496844Z
vladimirceva-lab3-migrate-1 exited StartedAt=2026-10-13T21:30:24.11084075Z
vladimirceva-lab3-postgres-1 running StartedAt=2026-10-13T21:30:12.188687467Z
vladimirceva-lab3-valkey-1 running StartedAt=2026-10-13T21:30:12.162555508Z
$ make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8090
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8090"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
$ docker inspect ... (после)
vladimirceva-lab3-api-3 running StartedAt=2026-10-13T22:12:40.720163299Z
vladimirceva-lab3-api-4 running StartedAt=2026-10-13T22:12:40.645063924Z
vladimirceva-lab3-haproxy-1 running StartedAt=2026-10-13T22:12:40.799122132Z
vladimirceva-lab3-migrate-1 exited StartedAt=2026-10-13T22:12:38.560835215Z
vladimirceva-lab3-postgres-1 running StartedAt=2026-10-13T22:12:36.727145172Z
vladimirceva-lab3-valkey-1 running StartedAt=2026-10-13T22:12:36.689232422Z
$ docker volume ls --filter label=com.docker.compose.project=vladimirceva-lab3
DRIVER VOLUME NAME
local vladimirceva-lab3_pgdata
# Порядок hook: stop haproxy api → restart postgres valkey → up --wait
# postgres valkey (те же контейнеры) → start api haproxy. start api поднял
# и зависимость migrate: повторный upgrade head ничего не изменил. Число
# реплик то же (start, а не --scale). Кэш Valkey после рестарта пуст —
# persistence у него выключен, данные в PostgreSQL. Срок сессии не
# продлевается (expires_at фиксирован при входе).
+83
View File
@@ -0,0 +1,83 @@
# Что доказывает (уровень 4: автоматические проверки отказов): одной
# командой на отдельном стенде проверяются
# - истечение сессии при SESSION_TTL_SECONDS=2 и то, что запросы её не
# продлевают;
# - запрос с токеном при остановленной БД — 503 без вызова
# аутентификации, после возврата тот же токен работает;
# - откат составной операции: сбой вставки участников — нет ни чата, ни
# участников;
# - ключ идемпотентности (лаба 3): сбой вставки сообщения уже после
# вставки ключа откатывает и ключ (повтор с тем же ключом создаёт
# сообщение); 503 при остановленной БД не фиксируется результатом —
# тот же ключ после возврата даёт 201 один раз; срок ключа 2 с на
# «тесном» API — в срок повтор и 409, после срока ключ занимается заново;
# - остановленная БД: 503 быстро, без деталей; запись во время отказа не
# появилась;
# - замёрзшая БД и исчерпанный пул: 503 за срок операции + закрытие
# соединения, второй запрос — за срок ожидания пула;
# - readiness без БД — 503 за 2 с, live 200; без Valkey — ready 200;
# - Valkey остановлен, заморожен, очищен и вернулся: те же ответы, не
# дольше срока команды 0,2 с, кэш снова в работе без рестарта API.
# Дата (UTC): 2026-10-13T22:16:52Z — 2026-10-13T22:17:44Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1;
# python3 хоста 3.11.9 (stand.py, fault_hook.py), pytest на Python 3.13.15
# Стенд: student-tests/stand.py failures — проект vladimirceva-lab3-failures:
# обычный API (настройки по умолчанию) и «тесный» (SESSION_TTL_SECONDS=2,
# IDEMPOTENCY_TTL_SECONDS=2, DB_POOL_SIZE=1, DB_POOL_OVERFLOW=0,
# DB_POOL_TIMEOUT=1, DB_OPERATION_TIMEOUT=2) — по одному процессу без LB;
# хранилища — только через hook student-tests/fault_hook.py; стенд удалён
# после прогона. Код src_sha256 0349e9a270178467. Абсолютный путь заменён
# на <репозиторий>; строки docker compose опущены («...»).
# Как повторить: make failure-checks FAULT_ARGS=-rP
$ time make failure-checks FAULT_ARGS=-rP
python3 student-tests/stand.py failures -rP
[failures] project=vladimirceva-lab3-failures
[failures] build image
...
[failures] start postgres and valkey
...
[failures] migrations
...
2026-10-13T22:16:56.998Z INFO alembic.runtime.migration [rid=-] Running upgrade -> 0001, messenger schema: users, sessions, chats, chat members, messages
2026-10-13T22:16:57.006Z INFO alembic.runtime.migration [rid=-] Running upgrade 0001 -> 0002, idempotency keys for sending messages
2026-10-13T22:16:57.011Z INFO src.migrations [rid=-] migrations finished db=messenger
[failures] ready: api=http://127.0.0.1:63305 tight=http://127.0.0.1:63311
[failures] pytest -m fault
============================= test session starts ==============================
platform darwin -- Python 3.13.15, pytest-9.1.1, pluggy-1.6.0
rootdir: <репозиторий>
configfile: pyproject.toml
testpaths: student-tests
plugins: anyio-4.15.1
collected 99 items / 84 deselected / 15 selected
student-tests/test_failures.py ............... [100%]
==================================== PASSES ====================================
________________________ test_database_stopped_and_back ________________________
----------------------------- Captured stdout call -----------------------------
postgres stopped: POST message -> 503 in 0.007s
___________________ test_frozen_database_and_exhausted_pool ____________________
----------------------------- Captured stdout call -----------------------------
postgres paused: first request -> 503 in 4.02s, second (pool of 1 busy) -> 503 in 1.02s
_______________________ test_readiness_without_database ________________________
----------------------------- Captured stdout call -----------------------------
postgres stopped: /health/ready -> 503 in 0.013s
_______________________ test_valkey_stopped_is_bypassed ________________________
----------------------------- Captured stdout call -----------------------------
valkey stopped: GET chat -> 200 in 0.013s, POST message -> 201 in 0.009s
_____________________ test_valkey_paused_costs_one_timeout _____________________
----------------------------- Captured stdout call -----------------------------
valkey paused: baseline 0.002s, first read 0.219s, second read 0.006s
====================== 15 passed, 84 deselected in 43.01s ======================
[failures] cleanup
[failures] results: {'fault': 0}
make failure-checks FAULT_ARGS=-rP 4.34s user 2.15s system 12% cpu 51.845 total
# 15 passed, весь прогон со сборкой и уборкой — 52 с. Замёрзшая БД на
# «тесном» API: 503 через 4,02 с = срок операции 2 с + закрытие 2 с; пока
# единственное соединение пула занято, второй запрос — 503 через 1,02 с
# (срок ожидания пула). Замёрзший Valkey добавил к одному запросу 0,22 с
# (срок команды 0,2 с), следующий — без ожидания (окно пропуска 5 с).
# Тексты остальных проверок — student-tests/test_failures.py.
+71
View File
@@ -0,0 +1,71 @@
# Что доказывает (уровни 3 и 4): собственный набор целиком через HAProxy
# рабочего стенда с двумя репликами (EXPECT_REPLICAS=2: тесты реплик
# выполняются, а не пропускаются). Отдельно — вывод тестов реплик и
# идемпотентности через разные реплики:
# - одна сессия, 20 запросов — ответили обе реплики, без повторного входа;
# - сообщение, записанное через одну реплику, видно в каждом чтении,
# в том числе через другую;
# - X-Instance-Id стабилен на время жизни процесса;
# - 10 одновременных отправок одного тела с одним Idempotency-Key — десять
# 201 с одним id и одно сообщение в истории, причём пара пересекающихся
# по времени запросов обслужена разными репликами;
# - повтор с тем же ключом через другую реплику — тот же Message; другое
# тело — 409 от обеих реплик.
# Дата (UTC): 2026-10-13T22:11Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1;
# pytest на Python 3.13.15 (uv)
# Стенд: рабочий проект vladimirceva-lab3, HAProxy на 127.0.0.1:8090 (на
# этой машине), код src_sha256 0349e9a270178467. Тесты оставляют в
# рабочей базе синтетических пользователей и чаты; чистый прогон —
# make test-isolated (evidence/tests/test-isolated.txt).
# Как повторить: make student-test [BASE_URL=...] (EXPECT_REPLICAS берётся
# из API_REPLICAS); вывод тестов реплик — pytest -rP по тем же тестам.
$ make student-test BASE_URL=http://localhost:8090 EXPECT_REPLICAS=2
BASE_URL=http://localhost:8090 EXPECT_REPLICAS=2 uv run pytest
============================= test session starts ==============================
platform darwin -- Python 3.13.15, pytest-9.1.1, pluggy-1.6.0
rootdir: <репозиторий>
configfile: pyproject.toml
testpaths: student-tests
plugins: anyio-4.15.1
collected 99 items / 15 deselected / 84 selected
student-tests/test_auth.py ...................... [ 26%]
student-tests/test_balancing.py ... [ 29%]
student-tests/test_cache.py .... [ 34%]
student-tests/test_idempotency.py ................... [ 57%]
student-tests/test_race.py .... [ 61%]
student-tests/test_request_id.py ............. [ 77%]
student-tests/test_rubric.py ................... [100%]
====================== 84 passed, 15 deselected in 13.15s ======================
$ BASE_URL=http://localhost:8090 EXPECT_REPLICAS=2 uv run pytest -rP -q \
student-tests/test_balancing.py \
student-tests/test_race.py::test_same_key_through_replicas \
student-tests/test_idempotency.py::test_replay_through_other_replica
..... [100%]
==================================== PASSES ====================================
_____________________ test_one_session_on_several_replicas _____________________
----------------------------- Captured stdout call -----------------------------
one session, 20 requests: {'4c13b772d928': 10, 'd69ba3cda2cf': 10}
___________________ test_write_visible_through_other_replica ___________________
----------------------------- Captured stdout call -----------------------------
written via d69ba3cda2cf, read via {'4c13b772d928': 3, 'd69ba3cda2cf': 3}
____________________ test_instance_id_is_stable_per_process ____________________
----------------------------- Captured stdout call -----------------------------
series: [{'4c13b772d928': 6, 'd69ba3cda2cf': 6}, {'4c13b772d928': 6, 'd69ba3cda2cf': 6}]
________________________ test_same_key_through_replicas ________________________
----------------------------- Captured stdout call -----------------------------
statuses={201: 10} peak_in_flight=10 ids=1 history=1
attempt 1: served={'d69ba3cda2cf': 5, '4c13b772d928': 5} overlapping pairs={('4c13b772d928', 'd69ba3cda2cf')}
______________________ test_replay_through_other_replica _______________________
----------------------------- Captured stdout call -----------------------------
sent via d69ba3cda2cf, replayed via ['4c13b772d928', 'd69ba3cda2cf']
409 via ['4c13b772d928', 'd69ba3cda2cf']
5 passed in 1.32s
# 15 deselected — проверки отказов (маркер fault): их выполняет только
# make failure-checks (evidence/tests/failure-checks.txt). Абсолютный путь
# заменён на <репозиторий>.
+71
View File
@@ -0,0 +1,71 @@
# Что доказывает (уровни 3 и 4): на отдельном чистом стенде лабы 3 (свои
# PostgreSQL, Valkey и volume, HAProxy и две реплики, свои случайные
# пароли, без .env) одной командой проходят: публичный smoke (make test),
# весь собственный набор через LB с тестами реплик (EXPECT_REPLICAS=2),
# make test-failover (hook scripts/stop-one.sh в проекте стенда), возврат
# реплик и make test-persistence (hook scripts/restart.sh). Миграции на
# пустом volume — сервисом migrate, обе ревизии по порядку. Рабочий стенд
# не затрагивается, отдельный удаляется вместе с volume.
# Дата (UTC): 2026-10-13T22:16:04Z — 2026-10-13T22:16:52Z
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.8.2, Compose 5.5.1;
# python3 хоста 3.11.9 (stand.py, проверки skeleton), pytest на Python
# 3.13.15 (uv)
# Стенд: student-tests/stand.py isolated — проект vladimirceva-lab3-isolated,
# HAProxy на свободном порту 127.0.0.1; код src_sha256 0349e9a270178467.
# Абсолютный путь заменён на <репозиторий>; строки docker compose о
# контейнерах, сети и сборке опущены («...»).
# Как повторить: make test-isolated
$ time make test-isolated
python3 student-tests/stand.py isolated
[isolated] project=vladimirceva-lab3-isolated
[isolated] build image
...
[isolated] start postgres and valkey
...
[isolated] migrations
...
2026-10-13T22:16:09.550Z INFO src.migrations [rid=-] migrations started db=postgres:5432/messenger
2026-10-13T22:16:09.570Z INFO alembic.runtime.migration [rid=-] Context impl PostgresqlImpl.
2026-10-13T22:16:09.570Z INFO alembic.runtime.migration [rid=-] Will assume transactional DDL.
2026-10-13T22:16:09.576Z INFO alembic.runtime.migration [rid=-] Running upgrade -> 0001, messenger schema: users, sessions, chats, chat members, messages
2026-10-13T22:16:09.618Z INFO alembic.runtime.migration [rid=-] Running upgrade 0001 -> 0002, idempotency keys for sending messages
2026-10-13T22:16:09.625Z INFO src.migrations [rid=-] migrations finished db=messenger
...
[isolated] ready: lb=http://127.0.0.1:62916 replicas=2
[isolated] make test
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
[isolated] pytest
============================= test session starts ==============================
platform darwin -- Python 3.13.15, pytest-9.1.1, pluggy-1.6.0
rootdir: <репозиторий>
configfile: pyproject.toml
testpaths: student-tests
plugins: anyio-4.15.1
collected 99 items / 15 deselected / 84 selected
student-tests/test_auth.py ...................... [ 26%]
student-tests/test_balancing.py ... [ 29%]
student-tests/test_cache.py .... [ 34%]
student-tests/test_idempotency.py ................... [ 57%]
student-tests/test_race.py .... [ 61%]
student-tests/test_request_id.py ............. [ 77%]
student-tests/test_rubric.py ................... [100%]
====================== 84 passed, 15 deselected in 12.47s ======================
[isolated] make test-failover (scripts/stop-one.sh)
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 116, "failed_attempts": 0, "first_recovery_seconds": 1.729}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
[isolated] restore replicas
...
[isolated] make test-persistence (scripts/restart.sh)
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
[isolated] cleanup
[isolated] results: {'test': 0, 'student-test': 0, 'test-failover': 0, 'test-persistence': 0}
make test-isolated 3.28s user 0.94s system 8% cpu 47.602 total
# Весь прогон со сборкой (из кэша слоёв), стендом, тестами и уборкой —
# 48 с. 15 deselected — проверки отказов (маркер fault): их выполняет
# make failure-checks (evidence/tests/failure-checks.txt).
+216
View File
@@ -0,0 +1,216 @@
# Docker, compose, HAProxy и скрипты стенда
Правила для `Dockerfile`, `.dockerignore`, `compose.yaml`,
`infra/haproxy/haproxy.cfg`, `infra/valkey/valkey.conf` и своих скриптов
`scripts/restart.sh`, `scripts/stop-one.sh`, `scripts/rolling-update.sh`,
`scripts/lab3.py`. `infra/README.md` и остальное в `scripts/` —
skeleton, не менять. Требования рубрики (`README.md`) и
`Dockerfile.example` важнее этого файла.
```
клиент → 127.0.0.1:HOST_PORT → haproxy → api × API_REPLICAS → postgres (данные, сессии, ключи)
→ valkey (кэш карточек)
migrate (один раз на up, до реплик) → postgres
```
## Dockerfile
- Два stage (`deps` → `runtime`) на **одном** базовом образе
`python:<патч>-slim-trixie@sha256:<digest индекса>`: venv ссылается на
интерпретатор базового образа. Новый digest — строка `Digest:` из
`docker buildx imagetools inspect <тег>`. Не `latest` и не `3.13-slim`.
- Зависимости — `pip install --require-hashes --no-deps
--only-binary=:all: -r requirements.txt`. `requirements.txt` — только
`make requirements` из `uv.lock`.
- Runtime: UID/GID 10001, `USER messenger`; код и venv принадлежат root.
- Копируются только `requirements.txt`, `src/`, `alembic.ini`,
`migrations/`. `COPY . .` запрещён.
- `CMD ["python", "-m", "src"]` в exec-форме: сервер — PID 1. Ранний
обработчик SIGTERM ставит `src/__main__.py` до импорта приложения
(`src/early_stop.py`): без него PID 1 терял бы сигнал во время старта, и
`docker stop` стартующей реплики ждал бы 10 с и SIGKILL. `init: true`
у `api` не ставить: сервер перестал бы быть PID 1.
- `HEALTHCHECK` — `python -m src.healthcheck` с `--start-interval=1s`.
## `.dockerignore`
Файл skeleton дополняется. Паттерн без `**/` действует только в корне
контекста: вложенные `AGENTS.md`, `__pycache__`, `*.pyc`, `.DS_Store` —
через `**/`. В образ не попадают `.env`, секреты, `tests/`,
`student-tests/`, `bench/`, `contracts/`, `evidence/`, `infra/`,
`scripts/`, `.codex/`, `.agents/`, `.venv/`, документация.
## `compose.yaml`
- Проект `name: vladimirceva-lab3` — имя меняется в каждой лабе: от него
зависят имена volume, и стенд не подключается к данным прошлой лабы.
- Сервисы: `postgres`, `valkey` (пины, свой healthcheck), `migrate` (образ
API, `alembic upgrade head`), `api` × `API_REPLICAS` (по умолчанию 2),
`haproxy`. `api` ждёт хранилища (`service_healthy`) и `migrate`
(`service_completed_successfully`); `haproxy` — `api`
(`service_started`): `make stop` гасит LB раньше реплик.
- **`api` без `ports` и без `container_name`** (оба мешают
масштабированию одного сервиса): запросы — только через `haproxy`.
`deploy.replicas: ${API_REPLICAS:-2}`; разово — `make replicas
API_REPLICAS=N`. X-Instance-Id реплики — hostname, то есть короткий ID
контейнера.
- Наружу (`127.0.0.1`) — только `haproxy` (API, `HOST_PORT`), `postgres` и
`valkey` (`make run` и миграции с хоста). Мониторинг LB (`:8404`) и
runtime API (`127.0.0.1:9999` в контейнере LB) наружу не публикуются.
- Секреты — только тем, кому нужны: якоря `x-db-env` (PostgreSQL — `api`
и `migrate`) и `x-cache-env` (Valkey — только `api`); у `haproxy`
окружения нет. Новая переменная контейнера — строка в якоре или
`environment` сервиса и в `.env.example`.
- Лимиты CPU/RAM у **всех** сервисов (`deploy.resources.limits`): API 1 /
512 МиБ на реплику, PostgreSQL 2 / 1 ГиБ, Valkey 0,5 / 128 МиБ, HAProxy
1 / 256 МиБ, migrate 0,5 / 256 МиБ. Override стендов (`bench/`) задаёт
лимиты в той же форме: `cpus`/`mem_limit` рядом compose не принимает.
- Соединения PostgreSQL: `API_REPLICAS × (DB_POOL_SIZE + DB_POOL_OVERFLOW)
+ migrate ≤ max_connections` (100): 2 × 15 + 1 = 31, на пике замены
3 × 15 + 1 = 46. Больше реплик или больше пул — пересчитать.
- Ужесточение (`x-hardened`) у `api`, `migrate`, `haproxy`: `read_only`,
`cap_drop: ALL`, `no-new-privileges`; у `api` ещё `tmpfs: /tmp`.
`stop_grace_period: 10s` у `api` (uvicorn завершается за
`SHUTDOWN_TIMEOUT` ≤ 9 с), `restart: unless-stopped` — не поднимает
контейнер ни после `docker stop`, ни после `docker kill`.
- PostgreSQL: healthcheck `pg_isready -h 127.0.0.1` по TCP; volume
`pgdata` на `/var/lib/postgresql` (PostgreSQL 18). Valkey: volume нет,
persistence выключен в `valkey.conf`, пароль — в `command` через
переменную контейнера, healthcheck `valkey-cli ping` с `VALKEYCLI_AUTH`.
- Отдельные стенды — свои проекты с override
(`student-tests/stand.compose.yml`, `bench/bench.compose.yml`). Меняешь
сервис здесь — проверь `make test-isolated`, `make failure-checks`,
`make bench-failover-quick`.
## HAProxy (`infra/haproxy/haproxy.cfg`)
- Прокси `frontend entry` (`:8080`), `backend api`, `frontend monitor`
(`:8404`: `/lb/ready` — healthcheck контейнера LB, `/stats;csv`). Имена
разные: с HAProxy 3.3 одинаковые имена frontend и backend — ошибка.
Проверка конфига: `docker compose exec haproxy haproxy -c -f
/usr/local/etc/haproxy/haproxy.cfg`.
- Реплики — через DNS Docker: `resolvers docker` (127.0.0.11, `hold` 1 с)
и `server-template api- 8 api:8080 … init-addr none init-state down`:
новая и пропавшая реплика видны без перезагрузки LB; слот, получивший
адрес, начинает `DOWN` и получает запросы только после `rise` проверок.
8 слотов — максимум реплик серий трека 1 и замены (N + 1).
- Проверка — активная, `GET /health/ready` (не `/health/live`: живой
процесс без PostgreSQL запросы не обслуживает), `inter 1s fastinter
500ms fall 2 rise 2`, `timeout check 2500ms`.
- `balance roundrobin` без `cookie` и `stick-table`: sticky session
запрещён (README, п. 3), разные X-Instance-Id одной сессии — проверка
уровня 3.
- Повтор в LB — только `retry-on conn-failure`, `retries 2`, `option
redispatch 1` (каждый повтор — на другую реплику): запрос до реплики не
дошёл, повтор безопасен для любого метода. Ответ, который реплика уже
начала, не повторяется: `POST /users` и `POST /chats` не идемпотентны,
`POST` сообщения повторяет клиент с тем же ключом.
- Ответы самого LB (502/503/504) — в формате ошибки контракта
(`http-error … lf-string`, `code` `unavailable`, `request_id` —
`unique-id`); X-Instance-Id у них нет — контракт допускает.
- `log stdout`, `option httplog` + `dontlog-normal`: в журнале только
ошибки, повторы и смены состояния слотов. `nbthread 1` = лимит CPU LB.
### Цепочка таймаутов (менять только вместе)
- Худшее обнаружение отказа ≤ 10 с (рубрика «3»): зависшая реплика —
`inter + timeout check + (fall − 1) × (fastinter + timeout check)` =
6,5 с; пропавший адрес (`kill`, `stop` после выхода) — 2,5 с; закрытый
сокет (окно graceful) — 1,5 с. Возврат — ≤ 1,5 с после готовности.
- `timeout connect` × (`retries` + 1) = 1,5 с < 2 с таймаута клиента
`tests/resilience.py`: перенаправление успевает раньше.
- `timeout server` 10 с > срок операции хранилища (`DB_OPERATION_TIMEOUT`
6 с + закрытие соединения 2 с) и KDF входа.
- Срок проверки внутри `/health/ready` (2 с, `READINESS_TIMEOUT`) <
`timeout check` 2,5 с: медленный PostgreSQL даёт 503 реплики, а не
таймаут проверки. Уменьшать срок готовности ради быстрого обнаружения
нельзя: проверка берёт соединение из общего пула.
- Простаивающее соединение LB → реплика закрывает LB: `http-reuse never`,
`timeout http-keep-alive` 10 с < `KEEP_ALIVE_TIMEOUT` реплики 60 с.
Иначе LB мог бы отправить запрос в соединение, которое реплика в этот
момент закрывает (502, `empty-response` LB не повторяет).
- `SHUTDOWN_TIMEOUT` (5 с, не больше 9) < `stop_grace_period` 10 с.
## `scripts/restart.sh`
Hook `make test-persistence ACTION_SCRIPT=scripts/restart.sh`: `stop
haproxy api` → `restart postgres valkey` → `up -d --wait postgres valkey`
→ `start api haproxy`. Перезапускает LB, **все** реплики и **все**
хранилища, сохраняя volume: без `down -v`, `FLUSHALL`, повторного
наполнения. `start api` поднимает и `migrate` (no-op). Число реплик не
меняется. `#!/bin/sh`, `set -eu`, исполняемый бит, ≤ 90 с, секреты не
печатает. Доказательство перезапуска — `StartedAt` до и после.
## `scripts/stop-one.sh`
Hook `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`:
`TARGET_INSTANCE_ID` (X-Instance-Id = начало ID контейнера, только hex,
12–64 символа) ищется префиксом среди **работающих** реплик сервиса `api`
этого проекта (`docker compose ps -q --no-trunc api`); иначе — код 2/3,
ничего не трогается. `STOP_MODE=stop` (`docker stop --timeout 9`,
graceful) или `kill`; реплика остаётся остановленной; возврат — `make
replicas` (те же контейнеры и ID). `STOP_ONE_LOG=<файл>` — строка «время,
TARGET_INSTANCE_ID, полный ID, режим»: тест скрывает вывод hook, а
evidence должно показать, какой контейнер остановлен. PostgreSQL,
Valkey, LB, чужие контейнеры и volume — никогда.
## `scripts/rolling-update.sh` (`make rolling-update`)
Compose сам поочерёдно не заменяет (это `update_config` Swarm); плагинов
нет. Порядок:
0. Предусловия (код 2, ничего не менялось): работает ровно
`API_REPLICAS`, остановленных нет, runtime API LB отвечает, есть слот
для N + 1, нет слотов в ручном `drain`/`maint` (остаток прерванной
замены: флаги 1 и 8 в `srv_admin_state`), все реплики `UP`.
1. Сборка образа сервиса из рабочего дерева (`ROLLOUT_BUILD=0` — без
сборки: так делает стенд `bench/`, переставив тег сам).
2. Миграции один раз: пересоздаётся контейнер **сервиса** `migrate` на
новом образе (`up --no-deps --force-recreate --exit-code-from
migrate`), а не `run --rm`: иначе `restart.sh` позже запускал бы
`migrate` прежнего образа на новой схеме («Can't locate revision»).
Ошибка — код 1 до замены реплик.
3. `up --no-recreate --no-build --scale api=N+1`: одна новая реплика.
4. Новая `healthy` (на стенде `bench/` без healthcheck — `running`) **и**
`UP` в LB по её адресу (≤ `ROLLOUT_READY_TIMEOUT` 60 с).
5. Старая: `drain` через runtime API → запросов в полёте 0 (≤ 12 с) →
`maint` → `docker stop --timeout 10` (в строке — код выхода) → `docker
rm` → адрес ушёл из слота → слот `ready`. Дренаж убирает гонку
keep-alive: SIGTERM приходит реплике, которой LB уже не шлёт запросы.
Сбой (`trap`): новая не стала `UP` — удаляется (со слотом — `maint` и
штатный stop; без слота — `docker rm -f`); новая уже `UP` — вывод старой
доводится до конца. В любом исходе — `API_REPLICAS` готовых реплик и
слоты без ручного состояния; повтор доводит замену. Автоматического
отката нет: откат — вернуть прежний код и снова `make rolling-update`
(схема только расширялась). Runtime API — `stats socket
ipv4@127.0.0.1:9999 level admin`, доступ — `docker compose exec -T
haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/9999 …'`.
После замен реплики называются `api-N` с растущим номером: штатные цели
работают с сервисом `api`, а не с именами; `make down` + `make up` снова
дают `api-1`, `api-2`.
## `scripts/lab3.py`
Свои операторские команды (stdlib, Python 3.9+): `instances` (`make
instances`), `lb-stats` (`make lb-stats`), `failover-each` (`make
failover-each`: `make test-failover` для каждой реплики по очереди с
`STOP_ONE_LOG` и `docker compose ps` до и после). Пароль и токен
синтетического пользователя — только в памяти.
## Что стенд не переживает
Один Docker-host, один HAProxy, одна PostgreSQL, один Valkey.
Выдерживается отказ процесса API (любой одной реплики при ≥ 2 живых).
Не выдерживается отказ хоста, LB и PostgreSQL; отказ Valkey —
деградация до PostgreSQL. Это пишется в `REPORT.md` прямо.
## Проверка правок
`docker compose config --quiet`, `make up`, `docker compose ps` (все
`healthy`), `make test`, `make instances`, `make test-persistence
ACTION_SCRIPT=scripts/restart.sh`, `make failover-each`, `make
test-isolated`. Правка `haproxy.cfg` — ещё `haproxy -c` (выше), правка
скриптов — `make rolling-update` на рабочем стенде и `make
bench-rollout-quick`.
+129
View File
@@ -0,0 +1,129 @@
# Балансировщик лабы 3: единственная точка входа перед репликами сервиса
# api. Правила и цепочка таймаутов — infra/AGENTS.md; тот же файл берёт
# нагрузочный стенд bench/. Порты внутри сети стенда фиксированы: 8080 —
# API (и у реплик, и у LB), 8404 — мониторинг. Секретов LB не получает.
global
# журнал — в stdout контейнера (docker compose logs haproxy)
log stdout format raw local0 info
maxconn 4096
# один поток на лимит 1 CPU: иначе HAProxy создал бы поток на каждый
# CPU ВМ и делил между ними одну квоту
nbthread 1
# runtime API для поочерёдной замены (scripts/rolling-update.sh): слот
# уходящей реплики — drain, maint, затем снова ready. Только loopback
# внутри контейнера LB: из сети compose и с хоста не достать, доступ —
# docker compose exec haproxy (bash /dev/tcp)
stats socket ipv4@127.0.0.1:9999 level admin
# DNS Docker: имя сервиса api отвечает адресами всех работающих реплик.
# Пропавший адрес уходит из слота, новый появляется за 1–2 с без
# перезагрузки LB
resolvers docker
nameserver dns 127.0.0.11:53
accepted_payload_size 8192
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 1s
hold obsolete 1s
hold nx 1s
hold other 1s
hold refused 1s
hold timeout 1s
defaults
mode http
log global
option httplog
# обычные успешные запросы не пишутся; ошибки, таймауты, повторы,
# перенаправления и смена состояния реплик — пишутся
option dontlog-normal
# timeout connect × (retries + 1) = 0,5 × 3 = 1,5 с < 2 с таймаута
# клиента tests/resilience.py: перенаправление успевает раньше
timeout connect 500ms
retries 2
# каждый повтор — на другую реплику, а не на ту же
option redispatch 1
# повтор только если соединение не установлено: запрос до реплики не
# дошёл, повтор безопасен для любого метода. Ответ, который реплика уже
# начала, не повторяется: POST /users и POST /chats не идемпотентны,
# отправку сообщения повторяет клиент с тем же Idempotency-Key
retry-on conn-failure
# больше срока операции хранилища (DB_OPERATION_TIMEOUT 6 с + закрытие
# соединения 2 с) и KDF входа: LB не рвёт ответ, который API ещё отдаст
timeout server 10s
timeout client 30s
timeout http-request 10s
# простаивающий сеанс клиента, а с ним и соединение с репликой
# (http-reuse never): меньше KEEP_ALIVE_TIMEOUT реплики (60 с)
timeout http-keep-alive 10s
# больше срока проверки внутри /health/ready (2 с) на 0,5 с: медленный
# PostgreSQL даёт 503 от реплики, а не таймаут проверки
timeout check 2500ms
# request_id ответов, которые создаёт сам LB
unique-id-format lb-%{+X}o%ci%cp%Ts%rt%pid
# ответы самого LB — в формате ошибки контракта; отдельных кодов для 502
# и 504 в контракте нет, ближайший — unavailable. X-Instance-Id у них
# нет: контракт это допускает
http-error status 502 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica closed the connection","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
http-error status 503 content-type application/json lf-string '{"error":{"code":"unavailable","message":"No API replica is available","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
http-error status 504 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica did not respond in time","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
# точка входа клиентов: на хосте — 127.0.0.1:HOST_PORT (compose)
frontend entry
bind :8080
default_backend api
backend api
# по очереди, без cookie и stick-table: sticky session запрещён
# (README, п. 3), разные X-Instance-Id у одной сессии — проверка «3»
balance roundrobin
# соединение с репликой не уходит в общий пул и не отдаётся другому
# клиенту: живёт, пока жив сеанс клиента, а простаивающий сеанс LB
# закрывает по timeout http-keep-alive (10 с). uvicorn держит
# простаивающее соединение 60 с — значит, закрывает LB, и запрос не
# уходит в соединение, которое реплика в этот момент закрывает (ответа
# не было бы, а empty-response LB не повторяет). Гонку при SIGTERM
# (uvicorn сразу закрывает простаивающие соединения) это не убирает:
# остановка без вывода из LB может дать одиночный 502. Плановая
# остановка (scripts/rolling-update.sh) сначала выводит реплику (drain)
http-reuse never
# активная проверка готовности: /health/live для LB не годится, живой
# процесс без PostgreSQL запросы не обслуживает
option httpchk
http-check send meth GET uri /health/ready
http-check expect status 200
# реплика исключается после 2 неудачных проверок подряд и возвращается
# после 2 успешных; проверка раз в секунду (inter), после первой
# неудачи и до возврата — через fastinter. Следующая проверка
# начинается через интервал после конца предыдущей, поэтому худшее
# обнаружение:
# зависшая (соединение есть, ответа нет): inter + timeout check +
# (fall − 1) × (fastinter + timeout check) = 1 + 2,5 + 0,5 + 2,5
# = 6,5 с ≤ 10 с;
# адрес пропал (kill, stop после выхода): таймаут соединения
# проверки min(timeout connect, inter) = 0,5 с: 1 + 0,5 + 0,5 + 0,5
# = 2,5 с; DNS уводит слот в обслуживание за 1–2 с;
# сокет закрыт, адрес жив (окно graceful): 1 + 0,5 = 1,5 с.
# Возврат: ≤ inter + fastinter = 1,5 с после готовности.
# init-state down: слот, получивший адрес из DNS (старт LB, новая или
# вернувшаяся реплика), начинает DOWN и получает запросы только после
# rise проверок — иначе запросы шли бы на процесс, который ещё не
# слушает порт
default-server check inter 1s fastinter 500ms fall 2 rise 2 resolvers docker init-addr none init-state down resolve-prefer ipv4
# 8 слотов — максимум реплик стенда (серии трека 1 и замена N + 1);
# лишние слоты в MAINT, девятую реплику LB не увидит
server-template api- 8 api:8080
# мониторинг внутри сети compose, наружу не публикуется:
# /lb/ready — healthcheck контейнера LB (200, пока есть готовая реплика),
# /stats и /stats;csv — состояние и счётчики каждого слота (make lb-stats)
frontend monitor
bind :8404
monitor-uri /lb/ready
monitor fail if { nbsrv(api) lt 1 }
stats enable
stats uri /stats
# адрес реплики в статистике (поле addr): только внутри сети
stats show-legends
+15
View File
@@ -0,0 +1,15 @@
# Valkey стенда — кэш карточек чатов (src/storage/cached.py).
# Монтируется в контейнер только на чтение. Пароль задаёт command в
# compose.yaml из переменной контейнера, здесь его нет.
# лимит памяти; при нехватке вытесняются давно не читанные ключи
maxmemory 64mb
maxmemory-policy allkeys-lru
# persistence выключен: источник истины — PostgreSQL, кэш после рестарта
# пуст и заполняется заново при чтении
save ""
appendonly no
# без пароля сервер не примет соединения извне контейнера
protected-mode yes
+86
View File
@@ -0,0 +1,86 @@
# migrations/ — схема PostgreSQL (alembic)
Схема создаётся миграциями до первого запроса: одноразовый сервис
compose `migrate` (тот же образ, `python -m alembic upgrade head`)
завершается с кодом 0, и только потом стартуют реплики `api`. Реплики
сами миграции не запускают: их несколько, и они гонялись бы за одну
схему. При поочерёдной замене миграции — один раз, на новом образе, до
первой новой реплики (`scripts/rolling-update.sh`). С хоста —
`make migrate-local` (его же вызывает `make run`). Адрес базы
`env.py` собирает из тех же переменных `DB_*`, что и приложение.
Ревизии: `0001` — схема лабы 2 (пользователи, сессии, чаты, участники,
сообщения); `0002` — `idempotency_keys` (лаба 3): первичный ключ (автор,
чат, ключ), внешний ключ `(chat_id, user_id) → chat_members`, ссылка на
сообщение `DEFERRABLE INITIALLY DEFERRED` (ключ вставляется раньше
сообщения в той же транзакции), `CHECK` формата ключа и длины хэша,
индекс по `created_at` для уборки просроченных.
## Совместимость с работающей версией (с лабы 3)
Во время поочерёдной замены старые реплики работают на новой схеме,
пока их не заменят. Поэтому ревизия **только расширяет** схему (expand):
- новые таблицы; новые колонки `NULL` или с `server_default`; индексы
(на большой таблице — `CREATE INDEX CONCURRENTLY` вне транзакции);
- удаление и переименование колонок и таблиц, `NOT NULL` без значения по
умолчанию — отдельной ревизией **после** того, как старого кода не
осталось (expand → contract); нельзя так — ограничение в `REPORT.md`;
- первой строкой ревизии, которая берёт блокировку на рабочую таблицу
(`ADD COLUMN`, внешний ключ на неё, `ALTER`), — `op.execute("SET LOCAL
lock_timeout = '2s'")`: за ожидающей блокировкой встают все новые
запросы к таблице, и чужая долгая транзакция остановила бы запись всех
реплик. По сроку миграция падает без изменений, замена не начинается,
повтор проходит. 2 с меньше `DB_STATEMENT_TIMEOUT_MS` (5 с): запросы в
очереди за миграцией дожидаются её отказа, а не падают вместе с ней;
- в ревизиях — литералы, а не константы `src`: применённая ревизия не
меняется вместе с кодом.
Под нагрузкой это проверяет профиль `rollout` стенда `bench/`: он
добавляет в образ пробную expand-ревизию `9001_rollout_probe` (только в
образе и базе стенда, `bench/common.py`) и меняет реплики, пока идут
запись и чтение.
## Правила
- Ревизии: `versions/<номер>_<slug>.py`, номер по порядку (`0001`,
`0002`, ...), задаётся при создании: `uv run alembic revision
--rev-id 0002 -m "<что изменилось, англ.>"`. Цепочка линейная.
- **Применённую ревизию не править**: она уже стоит на volume рабочего
стенда и у проверяющего. Любое изменение — новая ревизия с
`upgrade()` и `downgrade()`.
- Описание схемы для запросов — `src/storage/tables.py`. Ревизия и
`tables.py` меняются вместе; расхождение ловит `alembic check` (ниже).
Имена ограничений и индексов — явные, в стиле `pk_<таблица>`,
`uq_<таблица>_<колонки>`, `fk_<таблица>_<колонки>_<таблица>`,
`ck_<таблица>_<смысл>`, `ix_<таблица>_<колонки>`: по имени их снимает
`downgrade()`, по нему же индекс виден в планах запроса.
- Повторный запуск миграций — no-op (alembic хранит версию в
`alembic_version`), данные не дублируются: так `scripts/restart.sh`
может запускать `migrate` на каждом старте реплик.
- Миграция с данными (не только схема) — без чтения в Python всей
таблицы: SQL одним оператором, в журнал — число затронутых строк. Если
миграция удаляет данные — сказать пользователю до запуска.
- Индекс на большой таблице рабочего стенда — `CREATE INDEX
CONCURRENTLY` в ревизии с `autocommit_block()`; на учебном стенде
допустим и обычный, но в `REPORT.md` — время и блокировка.
- `CHECK` дублируют контракт (первым отвечает API 400); новый лимит
контракта — в `src/constants.py` и в `CHECK` одной ревизией.
## Проверка ревизии
1. `make db-up`, затем `make migrate-local`.
2. `alembic check` с хоста — «No new upgrade operations detected»:
```sh
set -a; . ./.env; set +a
DB_HOST=127.0.0.1 DB_PORT=$POSTGRES_HOST_PORT DB_NAME=$POSTGRES_DB \
DB_USER=$POSTGRES_USER DB_PASSWORD=$POSTGRES_PASSWORD uv run alembic check
```
(переменные из `.env` в выводе не печатаются).
3. С нуля и повторно: `make test-isolated` поднимает пустую базу и
применяет все ревизии; `docker compose run --rm migrate` на рабочем
стенде — no-op.
4. `downgrade -1` и снова `upgrade head` на отдельном стенде, не на
рабочем (раздел 2 корневого `AGENTS.md`, п. 8).
+82
View File
@@ -0,0 +1,82 @@
"""Окружение alembic: адрес базы и формат журнала — как у приложения.
URL собирается из тех же переменных `DB_*` (`src/config.py`) и не
проходит через ConfigParser alembic, поэтому `%` в пароле ничего не
ломает. Журнал — текстовый формат `src/log.py`: у процесса миграций нет
uvicorn, который применил бы его сам, поэтому конфиг применяется здесь.
Асинхронное только подключение; ревизии — синхронный код `op.*`.
Неверная переменная окружения — та же строка `configuration error` и
код 2, что у сервиса.
"""
import asyncio
import logging.config
import sys
from alembic import context
from sqlalchemy import pool
from sqlalchemy.engine import Connection
from sqlalchemy.ext.asyncio import create_async_engine
from src.config import ConfigError, Settings
from src.db import database_url
from src.log import get_logger, logging_config
from src.storage.tables import metadata
try:
settings = Settings.from_env()
except ConfigError as exc:
print(f"configuration error: {exc}", file=sys.stderr)
raise SystemExit(2) from None
logging.config.dictConfig(logging_config(settings.log_level))
log = get_logger("src.migrations")
target_metadata = metadata
def run_migrations_offline() -> None:
"""SQL без подключения: `alembic upgrade head --sql`."""
context.configure(
url=database_url(settings.database),
target_metadata=target_metadata,
literal_binds=True,
dialect_opts={"paramstyle": "named"},
)
with context.begin_transaction():
context.run_migrations()
def do_run_migrations(connection: Connection) -> None:
context.configure(connection=connection, target_metadata=target_metadata)
with context.begin_transaction():
context.run_migrations()
async def run_async_migrations() -> None:
database = settings.database
# по журналу видно, какую базу мигрировали; пароля в строке нет
log.info(
"migrations started db=%s:%d/%s",
database.host,
database.port,
database.name,
)
engine = create_async_engine(
database_url(database),
poolclass=pool.NullPool,
connect_args={"timeout": database.connect_timeout},
)
try:
async with engine.connect() as connection:
await connection.run_sync(do_run_migrations)
finally:
await engine.dispose()
log.info("migrations finished db=%s", database.name)
if context.is_offline_mode():
run_migrations_offline()
else:
asyncio.run(run_async_migrations())
+25
View File
@@ -0,0 +1,25 @@
"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
${imports if imports else ""}
revision: str = ${repr(up_revision)}
down_revision: str | Sequence[str] | None = ${repr(down_revision)}
branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
depends_on: str | Sequence[str] | None = ${repr(depends_on)}
def upgrade() -> None:
${upgrades if upgrades else "pass"}
def downgrade() -> None:
${downgrades if downgrades else "pass"}
@@ -0,0 +1,147 @@
"""messenger schema: users, sessions, chats, chat members, messages
Revision ID: 0001
Revises:
Create Date: 2026-10-02
Схема лабы 2 целиком: в лабе 1 хранилище было в памяти процесса, данных
для переноса нет. Таблицы и ограничения — как в `src/storage/tables.py`
(`alembic check` сверяет), обоснование — REPORT.md, «Схема».
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "0001"
down_revision: str | Sequence[str] | None = None
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
op.create_table(
"users",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("username", sa.Text(), nullable=False),
sa.Column("display_name", sa.Text(), nullable=False),
sa.Column("password_hash", sa.Text(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("id", name="pk_users"),
sa.UniqueConstraint("username", name="uq_users_username"),
sa.CheckConstraint(
"username ~ '^[a-z0-9_]{3,32}$'",
name="ck_users_username_format",
),
sa.CheckConstraint(
"char_length(display_name) BETWEEN 1 AND 100",
name="ck_users_display_name_length",
),
sa.CheckConstraint(
"password_hash LIKE '$argon2id$%'",
name="ck_users_password_hash_argon2id",
),
)
op.create_table(
"sessions",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.Column("token_hash", sa.LargeBinary(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("id", name="pk_sessions"),
sa.ForeignKeyConstraint(
["user_id"],
["users.id"],
name="fk_sessions_user_id_users",
),
sa.UniqueConstraint("token_hash", name="uq_sessions_token_hash"),
sa.CheckConstraint(
"octet_length(token_hash) = 32",
name="ck_sessions_token_hash_length",
),
sa.CheckConstraint(
"expires_at > created_at",
name="ck_sessions_expires_after_created",
),
)
op.create_table(
"chats",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("title", sa.Text(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("id", name="pk_chats"),
sa.CheckConstraint(
"char_length(title) BETWEEN 1 AND 100",
name="ck_chats_title_length",
),
)
op.create_table(
"chat_members",
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.Column("position", sa.SmallInteger(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("chat_id", "user_id", name="pk_chat_members"),
sa.ForeignKeyConstraint(
["chat_id"],
["chats.id"],
name="fk_chat_members_chat_id_chats",
),
sa.ForeignKeyConstraint(
["user_id"],
["users.id"],
name="fk_chat_members_user_id_users",
),
sa.UniqueConstraint(
"chat_id",
"position",
name="uq_chat_members_chat_id_position",
),
sa.CheckConstraint(
"position >= 0",
name="ck_chat_members_position_non_negative",
),
)
op.create_index(
"ix_chat_members_user_id_created_at_chat_id",
"chat_members",
["user_id", "created_at", "chat_id"],
)
op.create_table(
"messages",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("sender_id", sa.Uuid(), nullable=False),
sa.Column("text", sa.Text(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("id", name="pk_messages"),
sa.ForeignKeyConstraint(
["chat_id", "sender_id"],
["chat_members.chat_id", "chat_members.user_id"],
name="fk_messages_chat_id_sender_id_chat_members",
),
sa.CheckConstraint(
"char_length(text) BETWEEN 1 AND 4000",
name="ck_messages_text_length",
),
)
op.create_index(
"ix_messages_chat_id_created_at_id",
"messages",
["chat_id", "created_at", "id"],
)
def downgrade() -> None:
op.drop_index("ix_messages_chat_id_created_at_id", table_name="messages")
op.drop_table("messages")
op.drop_index(
"ix_chat_members_user_id_created_at_chat_id",
table_name="chat_members",
)
op.drop_table("chat_members")
op.drop_table("chats")
op.drop_table("sessions")
op.drop_table("users")
@@ -0,0 +1,81 @@
"""idempotency keys for sending messages
Revision ID: 0002
Revises: 0001
Create Date: 2026-10-14
Лаба 3: `Idempotency-Key` обязателен при отправке сообщения, ключ и
сообщение пишутся одной транзакцией (`src/storage/postgres.py`).
Только расширение схемы (expand): новая таблица, существующие не
меняются. Реплики прежней версии на этой схеме работают как раньше —
таблицу ключей они не замечают, поэтому поочерёдная замена может
применить ревизию до первой новой реплики (`scripts/rolling-update.sh`).
Новая таблица пуста, `CREATE TABLE` не блокирует таблицы, которые читают
работающие реплики, кроме короткой ссылки на `messages` и
`chat_members` (`SHARE ROW EXCLUSIVE` на время создания внешних ключей).
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "0002"
down_revision: str | Sequence[str] | None = "0001"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
# ожидание блокировки ограничено: долгая чужая транзакция на messages
# не выстроит за миграцией очередь из запросов всех реплик — миграция
# упадёт без изменений, и её можно повторить
op.execute("SET LOCAL lock_timeout = '2s'")
op.create_table(
"idempotency_keys",
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("key", sa.Text(), nullable=False),
sa.Column("request_hash", sa.LargeBinary(), nullable=False),
sa.Column("message_id", sa.Uuid(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint(
"user_id",
"chat_id",
"key",
name="pk_idempotency_keys",
),
sa.ForeignKeyConstraint(
["chat_id", "user_id"],
["chat_members.chat_id", "chat_members.user_id"],
name="fk_idempotency_keys_chat_id_user_id_chat_members",
),
# ключ вставляется раньше сообщения в той же транзакции: ссылка
# проверяется при commit
sa.ForeignKeyConstraint(
["message_id"],
["messages.id"],
name="fk_idempotency_keys_message_id_messages",
deferrable=True,
initially="DEFERRED",
),
sa.CheckConstraint(
"key ~ '^[A-Za-z0-9._:-]{1,128}$'",
name="ck_idempotency_keys_key_format",
),
sa.CheckConstraint(
"octet_length(request_hash) = 32",
name="ck_idempotency_keys_request_hash_length",
),
)
op.create_index(
"ix_idempotency_keys_created_at",
"idempotency_keys",
["created_at"],
)
def downgrade() -> None:
op.drop_index("ix_idempotency_keys_created_at", table_name="idempotency_keys")
op.drop_table("idempotency_keys")
+60
View File
@@ -0,0 +1,60 @@
[project]
name = "mtusi-messenger"
version = "0.3.0"
description = "Lab 3: messenger REST API replicas behind HAProxy on PostgreSQL and Valkey"
requires-python = ">=3.13,<3.14"
dependencies = [
"fastapi>=0.120,<1",
"uvicorn>=0.38,<1",
# PostgreSQL: SQLAlchemy Core поверх asyncpg — пул, таймауты и
# параметризованные запросы; extra asyncio ставит greenlet
"sqlalchemy[asyncio]>=2.1.1,<2.2",
"asyncpg>=0.31,<0.32",
# миграции; в основной группе: сервис migrate работает на образе API
"alembic>=1.20,<2",
# Argon2id для паролей: bcrypt режет пароль на 72 байтах
"argon2-cffi>=25.1,<26",
# клиент Valkey: протокол Redis, асинхронный клиент redis.asyncio
"redis>=8.1,<9",
]
[dependency-groups]
dev = [
# student-tests: httpx.Client против запущенного стенда
"pytest>=8.4,<10",
"httpx>=0.28,<1",
"ruff>=0.16,<0.17",
# make validate (полная проверка OpenAPI skeleton)
"openapi-spec-validator==0.7.2",
]
[tool.uv]
# приложение не собирается пакетом: запуск `python -m src` из корня
package = false
[tool.ruff]
line-length = 88
target-version = "py313"
# first-party для isort: пакет src и хелперы набора student-tests
src = [".", "student-tests"]
# публичные проверки skeleton не форматируем и не правим; свои скрипты в
# scripts/ (lab3.py) линтер проверяет
extend-exclude = ["tests", "scripts/check_contract.py", "scripts/validate_openapi.py"]
[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP", "SIM", "C4", "RET", "PT", "ASYNC"]
[tool.ruff.lint.per-file-ignores]
# стенд собирает строки markdown-таблиц и SVG: они длиннее 88 символов
"bench/*.py" = ["E501"]
[tool.pytest.ini_options]
testpaths = ["student-tests"]
# хелперы набора импортируются из его каталога
pythonpath = ["student-tests"]
# проверки отказов (маркер fault) — только make failure-checks: там
# pytest -m fault перекрывает этот -m
addopts = "-ra --strict-markers -m 'not fault'"
markers = [
"fault: проверка отказа хранилища; нужен стенд make failure-checks и его hook",
]
+196
View File
@@ -0,0 +1,196 @@
alembic==1.20.0 \
--hash=sha256:77eb101048d95f982c0353e9233404889dcd7a6fc244c107836c0e2fc9cf7d9d \
--hash=sha256:db505480647bc60386c5369402f4a57a506b7539c9e9ef5e270d45cbbe4939bf
# via mtusi-messenger
annotated-doc==0.0.5 \
--hash=sha256:117bac03a25ede5df5440e855b32d556049ca169ead221505badf432fed4b101 \
--hash=sha256:c7e58ce09192557605d8bbd92836d7e1d520ac9580096042c0bfd197efacf1bb
# via fastapi
annotated-types==0.8.0 \
--hash=sha256:13b2beaad985e05e2d6407ee4c4f35590b11f8d693a258a561055cac8f64cab7 \
--hash=sha256:f072f4d804ea359e4eaf198b1af7a8b0943881a87f31bb764f8bf219bb9419e0
# via pydantic
anyio==4.15.1 \
--hash=sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101 \
--hash=sha256:9f28306018cbd6d329e64a36d58256edff76dd996fe423bc957326e578b82a94
# via starlette
argon2-cffi==25.1.0 \
--hash=sha256:694ae5cc8a42f4c4e2bf2ca0e64e51e23a040c6a517a85074683d3959e1346c1 \
--hash=sha256:fdc8b074db390fccb6eb4a3604ae7231f219aa669a2652e0f20e16ba513d5741
# via mtusi-messenger
argon2-cffi-bindings==26.1.0 \
--hash=sha256:21ca0396fe5ec995dd54431c32698189666f9224810acfa752e50d2bd94d9df2 \
--hash=sha256:224865cbbcb7a2bd1356741dff12b0134df726b6d44bb7b500df8e303cbd9e81 \
--hash=sha256:27f1821903e2ceadcb88ec2b45ef190897b7682449c772f4d9b53e42c520cf29 \
--hash=sha256:2c36ff87b5dfaa477d0bd51e9d7f6abdae7c8955d2983c97419085d842154b3e \
--hash=sha256:34b7d9c24a4165a2c61cc8ae11d44d48c9ce2830fb536cb7914e11fdd9962728 \
--hash=sha256:63505c71542a44b68b1e38060450fb006404170da375feb31af153e7f9c6205d \
--hash=sha256:78de2d65e0b9ea7ce9d1b1c3e87297b2d7305a02c266ee2a2d6910daddd7ee69 \
--hash=sha256:a86c069c91a747a2c4e5c51473590aeb48172fff9b2130d23729a42d98665ecb \
--hash=sha256:af11ac37a7c53dc16cb7950a6190851b0870fe218b6c60c0bb7ac355234e3083 \
--hash=sha256:d88e5f7e60f28ae0b0cc6b2f16c43e87cd642a196a86f85e0d8bb6fe016fc16d \
--hash=sha256:f9c4420a7a864fe1b86ce35befc95b8e39fb852493b81cf798671ddc265de638 \
--hash=sha256:ffff613aaa9ce6236766e2fc6dc560bb5abde7a2e2416e3db1f9ae395a2b4dd4
# via argon2-cffi
asyncpg==0.31.0 \
--hash=sha256:0bfbcc5b7ffcd9b75ab1558f00db2ae07db9c80637ad1b2469c43df79d7a5ae2 \
--hash=sha256:22bc525ebbdc24d1261ecbf6f504998244d4e3be1721784b5f64664d61fbe602 \
--hash=sha256:54a64f91839ba59008eccf7aad2e93d6e3de688d796f35803235ea1c4898ae1e \
--hash=sha256:bef056aa502ee34204c161c72ca1f3c274917596877f825968368b2c33f585f4 \
--hash=sha256:c0e0822b1038dc7253b337b0f3f676cadc4ac31b126c5d42691c39691962e403 \
--hash=sha256:c204fab1b91e08b0f47e90a75d1b3c62174dab21f670ad6c5d0f243a228f015b \
--hash=sha256:c989386c83940bfbd787180f2b1519415e2d3d6277a70d9d0f0145ac73500735 \
--hash=sha256:dc5f2fa9916f292e5c5c8b2ac2813763bcd7f58e130055b4ad8a0531314201ab \
--hash=sha256:f890de5e1e4f7e14023619399a471ce4b71f5418cd67a51853b9910fdfa73696
# via mtusi-messenger
cffi==2.1.1 \
--hash=sha256:19ee6127ee34de7d83ce3d371ebc5ed91addbdcc39f9ab15ce4eb35a4e534971 \
--hash=sha256:1aa5645c30469b09530c4ebca77ebf8f17618293c58f8549cb1a543a50236e7d \
--hash=sha256:31348097ff5bbe827ccc41795d4dd099d9f0625e7def00ee653c137a490c2a6c \
--hash=sha256:334644fbac4eff73d985a17a91226df55d0f394160c4cfb880e084c8f7161cac \
--hash=sha256:63bbfd5ded17c4840ac07cd8f1c21ba9d9708141f840b324f422f41b207e3973 \
--hash=sha256:6a8dddef476fab96d066d578fc88526767b836ab5ab21754e1d5bf3879c31c7c \
--hash=sha256:9d2055050ea716bd38b7f7f1579c275386646b4894c155a3e2f3cd62ed41b7c6 \
--hash=sha256:a2d7755bef5a12ed488f4ef1f1b69ee9191d7396083b755a5d2295f6edb4768b \
--hash=sha256:a931079504ecc49efed7744c476a5c343a92fabf66dec2db95edb1b2fdc770e2 \
--hash=sha256:aa9511c62d14da7aacc9b4bf51f3f697a621e83b2d6919008243c3aad168eea3 \
--hash=sha256:b5bdfd1c873d4e093aabc0ca84c4ca6dbc4f752afb5c86f146d9742580c9da2e \
--hash=sha256:dd31f52ea1086513bb9df30f8fcee9b8918323ae067a3d5b78bc826a000712be \
--hash=sha256:e0bcb7e0f677f543555d2adff3bf19c05f66cdb4796e5ff602442ab2fe3c4ef7 \
--hash=sha256:f16c709686a78c727bbbf059f92b0bf41c6fc60deec706d2dc19f529175a6125 \
--hash=sha256:fcd22650c908d7b7da162bbfaab594a1227a15d1643a98c68b122ac642fa2264
# via argon2-cffi-bindings
click==8.5.0 \
--hash=sha256:255bc9599cf7748b4b1a446ccc735421bd08a2ae529a8b88597d3de5664ee360 \
--hash=sha256:ba0d2089de75ea0310e2dde03160e6ca10009947fb95a182f9b54021bb272e34
# via uvicorn
fastapi==0.142.1 \
--hash=sha256:761663e3e6939da45f997a6f68362abc0fa9d8606e76d504f15f806d2281581d \
--hash=sha256:7eea2b5b1632ed43de2c090b3a43b7d92267189dfbbd55a967307ed763b6c57a
# via mtusi-messenger
greenlet==3.5.6 \
--hash=sha256:06c0e933290fba8ffe53ead4ae1b8044b0e9754b75cebf381aa2bc3e50d82fac \
--hash=sha256:5b602b4201b965a8354d74e232364a66ff243dd142e350d035f46169bb36e13d \
--hash=sha256:7f731ebac68ea06d628658295cb2d217b10186329fcf9a3b6a149045059bf92e \
--hash=sha256:876077e7ebb8c84ed068e2b23d4c62ebb010d60df84b9591af1be2f39010ffb2 \
--hash=sha256:8e67c43bdfc88d5fee6db0d3e40175b362fc95fb85f0412d233b9b203c53a575 \
--hash=sha256:a93ee7c6e8fd0f8a83525a51bd777be57ee17787e91d805bd8d6faf9dcada18e \
--hash=sha256:c75116c9de79949de23006e2d9b35ee82874c594fcf5c0311b439acaa14b8441 \
--hash=sha256:cad5782f93f7f738b62c6527b6f32a60694d924029f299a8b524758cfa53d815 \
--hash=sha256:df19e2d0b1620039af5102563fbd96e8938c7f5c3f5828528d641d9fc585525e \
--hash=sha256:f96f0e30b5a95c7631b12bfe214cbc90ec8fe8cfa36920596c10514a65743519 \
--hash=sha256:f98e8215e172f567ce80eeaed9107fb4d32b6c44f26983d9b8334658136a205a
# via sqlalchemy
h11==0.16.0 \
--hash=sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1 \
--hash=sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86
# via uvicorn
idna==3.20 \
--hash=sha256:a7db850025b95ded1eae8a46181a1a6c56c92c96f0e2b005d9ff8dc0210cab44 \
--hash=sha256:ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c
# via anyio
mako==1.4.3 \
--hash=sha256:723296007c870bfd6b3f0c3230dba7198096e5269297ebf5e4eff9e7ffa39d4f \
--hash=sha256:cd6537fe88d5fec315c55c2f8529bc4ce7a9a352ad7db3eeaa6a66e2dd4ec37a
# via alembic
markupsafe==3.0.3 \
--hash=sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219 \
--hash=sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb \
--hash=sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6 \
--hash=sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218 \
--hash=sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73 \
--hash=sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37 \
--hash=sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19 \
--hash=sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9 \
--hash=sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354 \
--hash=sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698 \
--hash=sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc \
--hash=sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485 \
--hash=sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12 \
--hash=sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025 \
--hash=sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009 \
--hash=sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5 \
--hash=sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f \
--hash=sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1 \
--hash=sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287 \
--hash=sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6 \
--hash=sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed \
--hash=sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676 \
--hash=sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795
# via mako
opentelemetry-api==1.45.0 \
--hash=sha256:711ede81773c8025c2c03dac0450bc89f3d30aea6eabcc815c570d4e35a963f7 \
--hash=sha256:80e068aba7cd56c8b58512d6a36f8d25cb1dfaa0c0a4cc1c938ccf9f362d9cb3
# via fastapi
pycparser==3.0 ; implementation_name != 'PyPy' \
--hash=sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29 \
--hash=sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992
# via cffi
pydantic==2.13.5 \
--hash=sha256:346a034f080da3755d8e9cb5e00e8b07de1d39e4f6e2c87d8ab7cafa0b269a73 \
--hash=sha256:51a9c5f7b2f8e636f04c6cada605d9b6a3bf1348fdf945a3d8869b19bba0ee08
# via fastapi
pydantic-core==2.46.5 \
--hash=sha256:10416c15b8839ecc4ef4d0885da76da6fd0f67333a0eb8aff6d93c4b8f2910fc \
--hash=sha256:15f4a94963c95accac15b7b657bb177d3ad82bb90b0d0526d9a9b85079925db5 \
--hash=sha256:193375f3548919d3f0b60936ca113ada3e38f264f91b9b8e0508efaad57be931 \
--hash=sha256:24922243639cbdac66c75fcb6fd6495a9cb52b213d62f9a0d16f0310b1ff8038 \
--hash=sha256:5ee239d575f80b08eca11f6e20f90c4c695de7825c67eefe6091fbf20dda648e \
--hash=sha256:6f7b393a8b3da82f5c1fc0751e6d01ac6c55b93c18226a60bdfba4a724efafd1 \
--hash=sha256:79bdfa52f843137045b2d081cc05c120ba6665d29b7559c2c47690906f39279f \
--hash=sha256:7ac031912d54f3d83ef3b3eb98dfabc1608802e2202263d25957eeed40b94761 \
--hash=sha256:837b396ca3d7b74091ca623f6cbd8351bd42d670a79c2683e79fb089f06a2de5 \
--hash=sha256:97bf8de4d541598c94a59344eeb988a94c08ff76b5723c41f6567ec18c7892ea \
--hash=sha256:9c4b71f10dd532fb7a5cbc8f58707779e64f03a258c2bf8bfbaecfcd9970b519 \
--hash=sha256:b7ca9034437b6022f941f4857459562ee00a560b97e7cce8a0ec5a74fc6766e0 \
--hash=sha256:c76fe65e607be28c7fd4d56fc3c42b1583aa058ce3408b7ad0fd540171d31f9f \
--hash=sha256:d22a945598fb91236b4dd793a6e42e4f3dd7740bb5aace5ebd7d4c08d13bb575 \
--hash=sha256:e80675d75ae2cd14372cb65cad5400d9347a3d3f6c13000183f22dfd027283ed \
--hash=sha256:f332f0e72a5a0400141f830744e141bf9f97917878dbe968669e8a7fefea78ff
# via pydantic
redis==8.1.0 \
--hash=sha256:6e1a19beef9225c83efd689c7e6b7da2d5215b1f42cd13b7fc3714d0a09c7b25 \
--hash=sha256:a4fe1aac3d3b3cc791d4b3d5931c5a956045dc951ee74d1c913ee3ac4d2ee9fb
# via mtusi-messenger
sqlalchemy==2.1.1 \
--hash=sha256:28b882509319789d52966d70164ccfc5bc1aaffc1c7f98a79bbccec13346ebd7 \
--hash=sha256:389e7098e9ae15094f222496de98b0fd211c06b896c73c6e46aa9ca5b6fcd590 \
--hash=sha256:4357c1a222e141662251a59d3702f9b124294941171dfa6bd570513e9f4905ee \
--hash=sha256:7c60fb6793cf60b2733012352f0e1861c38b24727d0e37a1da1f3974eb79f0ed \
--hash=sha256:7ed18c0747eec4a0d8d9abe4c89d96ec0eda97721ab7d3a31d0c1ebcbf38cd2e \
--hash=sha256:a74c46cd93e34b912adafab98aa71c862518451a019d97f9c2f37392fc8eea3f \
--hash=sha256:abd893deac6b0765f51d87129c5631cc5bc8f784f8bf22a9d3903695c764bccc \
--hash=sha256:b04365ffe57cdeaf4d0f75630332d857dde3f91336bc4bdec76c810473c9c35e \
--hash=sha256:cf88881d593f527860fa7c63a50095496a5fa15632b1fee58e3114353f7fbc22 \
--hash=sha256:dee7886f4725c304641929a38d1ebe163f9fb45a5c9363f34bbb85bfdcb084c5 \
--hash=sha256:eef01acb10295adfac8a960f716687052fe16f14a3f5955b56c24eefa9df7851 \
--hash=sha256:fcf3cbb33bb23bad75d2150157c21804618745731e9931ab27e61879a9f6123b
# via
# alembic
# mtusi-messenger
starlette==1.7.0 \
--hash=sha256:67f8e99895493dd2911a03f11314af6ceebeae4e704bb9f43dfc6a9db151c93e \
--hash=sha256:c79f74ea63cff761804fbbfb182f1e0b440c2d07b164d24700c5a1bab5d6ff5d
# via fastapi
typing-extensions==4.16.0 \
--hash=sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8 \
--hash=sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5
# via
# alembic
# anyio
# fastapi
# opentelemetry-api
# pydantic
# pydantic-core
# sqlalchemy
# typing-inspection
typing-inspection==0.4.4 \
--hash=sha256:547274fa6b0a561ccf549cc9524b999a578e737d015d8709d021f9d0d13bea47 \
--hash=sha256:65b8397ba37ccbce054456aaccddfc91e6e3083c92824df348d96ca832f3f147
# via
# fastapi
# pydantic
uvicorn==0.54.0 \
--hash=sha256:505bdb0f318731d45f1f712071fc781a8981f6847a31c902c9f5e652d4f67faf \
--hash=sha256:a2e33cbfaa0306f8e6b0c13e0cb89d7d7a2da3e62b90c66e18c33d9807b28620
# via mtusi-messenger
+251
View File
@@ -0,0 +1,251 @@
#!/usr/bin/env python3
"""Операторские команды стенда лабы 3 (свои, не skeleton). Python 3.9+, stdlib.
python3 scripts/lab3.py instances [--base-url URL] [--requests 12]
вход одним синтетическим пользователем и серия GET /users/me с одним
токеном через LB: X-Instance-Id каждого ответа и итог по репликам
(шаг 1 сценария защиты);
python3 scripts/lab3.py lb-stats
слоты HAProxy рабочего стенда: адрес, состояние проверки, запросы в
полёте, всего, ошибки соединения, повторы, перенаправления;
python3 scripts/lab3.py failover-each [--base-url URL] [--replicas 2]
[--mode stop|kill]
make test-failover для каждой реплики по очереди: перед прогоном все
реплики возвращены (make replicas), тест останавливает реплику,
ответившую на его первую запись; если это реплика, которую уже
проверили, очередь LB сдвигается одним запросом и прогон
повторяется. Печатает docker compose ps до и после, строку
STOP_ONE_LOG и итог теста — это evidence «какой контейнер
действительно остановлен».
Пароль синтетического пользователя и токен живут только в памяти и не
печатаются. Работает с проектом compose репозитория (compose.yaml и .env).
"""
from __future__ import annotations
import argparse
import base64
import json
import os
import secrets
import subprocess
import sys
import tempfile
import time
import urllib.error
import urllib.request
from collections import Counter
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
LB_STATS = (
"exec 3<>/dev/tcp/127.0.0.1/8404 && "
"printf 'GET /stats;csv HTTP/1.0\\r\\n\\r\\n' >&3 && cat <&3"
)
STAT_FIELDS = ("addr", "status", "scur", "stot", "econ", "eresp", "wretr", "wredis")
def call(base: str, method: str, path: str, headers=None, body=None):
data = json.dumps(body).encode() if body is not None else None
request = urllib.request.Request(base + path, data=data, method=method)
for key, value in (headers or {}).items():
request.add_header(key, value)
if data is not None:
request.add_header("Content-Type", "application/json")
try:
with urllib.request.urlopen(request, timeout=10) as response:
return response.status, dict(response.headers), response.read()
except urllib.error.HTTPError as error:
return error.code, dict(error.headers), error.read()
def login(base: str) -> str:
username = "ops_" + secrets.token_hex(6)
password = secrets.token_urlsafe(18)
status, _, _ = call(
base,
"POST",
"/api/v1/users",
body={"username": username, "display_name": "Оператор", "password": password},
)
if status != 201:
raise SystemExit(f"register -> {status}")
basic = base64.b64encode(f"{username}:{password}".encode()).decode()
status, _, data = call(
base,
"POST",
"/api/v1/auth/sessions",
headers={"Authorization": "Basic " + basic},
)
if status != 201:
raise SystemExit(f"login -> {status}")
return json.loads(data)["token"]
def instances(args: argparse.Namespace) -> int:
token = login(args.base_url)
seen: Counter = Counter()
print(f"one session, {args.requests} x GET /api/v1/users/me via {args.base_url}")
for number in range(1, args.requests + 1):
status, headers, _ = call(
args.base_url,
"GET",
"/api/v1/users/me",
headers={"Authorization": "Bearer " + token},
)
instance = headers.get("X-Instance-Id") or headers.get("x-instance-id") or "-"
seen[instance] += 1
print(f" {number:2d}: {status} X-Instance-Id={instance}")
print(f"replicas seen: {len(seen)} {dict(seen)}")
return 0 if len(seen) >= 2 else 1
def compose(*args: str, check: bool = True) -> subprocess.CompletedProcess:
return subprocess.run(
["docker", "compose", *args],
cwd=ROOT,
capture_output=True,
text=True,
check=check,
)
def lb_rows() -> list[dict]:
done = compose("exec", "-T", "haproxy", "bash", "-c", LB_STATS)
lines = [
line for line in done.stdout.splitlines() if line.startswith(("# ", "api,"))
]
header = lines[0][2:].split(",")
rows = []
for line in lines[1:]:
# zip(strict=) — только с Python 3.10, скрипт работает и на 3.9
row = dict(zip(header, line.split(","))) # noqa: B905
if row["svname"] in ("BACKEND", "FRONTEND") or not row.get("addr"):
continue
rows.append(row)
return rows
def lb_stats(_args: argparse.Namespace) -> int:
print("slot " + " ".join(f"{field:>12}" for field in STAT_FIELDS))
for row in lb_rows():
print(
f"{row['svname']:<9} "
+ " ".join(f"{row.get(f, ''):>12}" for f in STAT_FIELDS)
)
return 0
def wait_lb_up(replicas: int, timeout: float = 30) -> bool:
"""Все реплики UP в LB: `--wait` compose ждёт только healthcheck
контейнера, а слот вернувшейся реплики включается после проверок LB."""
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
up = [row for row in lb_rows() if row.get("status") == "UP"]
if len(up) >= replicas:
return True
time.sleep(0.5)
return False
def ps() -> str:
return compose(
"ps", "-a", "--format", "table {{.Name}}\t{{.ID}}\t{{.State}}\t{{.Status}}"
).stdout
def failover_each(args: argparse.Namespace) -> int:
done: set[str] = set()
log = Path(tempfile.mkdtemp(prefix="stop-one-")) / "stop-one.log"
env = {**os.environ, "STOP_ONE_LOG": str(log), "STOP_MODE": args.mode}
attempt = 0
while len(done) < args.replicas and attempt < args.replicas * 4:
attempt += 1
replicas = compose(
"up",
"-d",
"--no-deps",
"--no-recreate",
"--wait",
"--scale",
f"api={args.replicas}",
"api",
check=False,
)
if replicas.returncode != 0 or not wait_lb_up(args.replicas):
print(replicas.stderr or "replicas are not UP in the LB")
return 2
# сдвиг очереди round-robin: тест останавливает реплику, ответившую
# на его первую запись; с каждой попыткой сдвиг на запрос больше
for _ in range(attempt - 1):
call(args.base_url, "GET", "/health/live")
print(f"=== attempt {attempt}: docker compose ps before\n{ps()}", flush=True)
before = log.read_text().splitlines() if log.exists() else []
test = subprocess.run(
[
sys.executable,
"tests/resilience.py",
"--mode",
"failover",
"--action-script",
"scripts/stop-one.sh",
"--base-url",
args.base_url,
],
cwd=ROOT,
env=env,
capture_output=True,
text=True,
check=False,
)
print(
"$ make test-failover ACTION_SCRIPT=scripts/stop-one.sh "
f"(STOP_MODE={args.mode})"
)
print(test.stdout.strip())
lines = log.read_text().splitlines() if log.exists() else []
new = lines[len(before) :]
print("STOP_ONE_LOG: " + (new[-1] if new else "(no line)"))
print(f"docker compose ps after\n{ps()}", flush=True)
if test.returncode != 0:
return test.returncode
stopped = new[-1].split("container=")[1].split()[0][:12] if new else ""
if stopped:
done.add(stopped)
compose(
"up",
"-d",
"--no-deps",
"--no-recreate",
"--wait",
"--scale",
f"api={args.replicas}",
"api",
)
print(f"replicas stopped one by one: {sorted(done)}; all restored:\n{ps()}")
return 0 if len(done) >= args.replicas else 1
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
commands = parser.add_subparsers(dest="command", required=True)
one = commands.add_parser("instances")
one.add_argument("--base-url", default="http://localhost:8080")
one.add_argument("--requests", type=int, default=12)
commands.add_parser("lb-stats")
each = commands.add_parser("failover-each")
each.add_argument("--base-url", default="http://localhost:8080")
each.add_argument("--replicas", type=int, default=2)
each.add_argument("--mode", choices=("stop", "kill"), default="stop")
args = parser.parse_args()
handler = {
"instances": instances,
"lb-stats": lb_stats,
"failover-each": failover_each,
}
return handler[args.command](args)
if __name__ == "__main__":
sys.exit(main())
+20
View File
@@ -0,0 +1,20 @@
#!/bin/sh
set -eu
# Restart hook для make test-persistence (tests/README.md) по образцу
# scripts/restart.example.sh. Перезапускает балансировщик, все реплики API
# и все хранилища стенда — PostgreSQL и Valkey — с сохранением volume,
# схемы и данных: без down -v, FLUSHALL и повторного наполнения. Кэш
# Valkey после рестарта пуст: persistence у него выключен, данные — в
# PostgreSQL.
# LB гасится первым и поднимается последним. start поднимает те же
# контейнеры всех реплик: число реплик не меняется (реплика, которую
# оставил остановленной stop-one.sh, тоже запускается). start api
# запускает и его зависимость migrate: повторный прогон миграций ничего не
# меняет. Готовность через LB ждёт сам тест. Секреты не печатает.
cd "$(dirname "$0")/.."
docker compose stop haproxy api
docker compose restart postgres valkey
# те же контейнеры: --wait только дожидается их healthcheck
docker compose up -d --wait postgres valkey
docker compose start api haproxy
+422
View File
@@ -0,0 +1,422 @@
#!/bin/sh
set -eu
# Поочерёдная замена реплик api на новый образ без простоя (рубрика «4»
# лабы 3): make rolling-update. Правила — infra/AGENTS.md, «Поочерёдная
# замена». Compose сам так не умеет (это update_config Swarm), сторонние
# плагины не используются: ещё одна незакреплённая зависимость.
# 0. предусловия: работает ровно API_REPLICAS реплик, остановленных нет,
# слотов LB с ручным состоянием (drain, maint) нет, все реплики UP в
# LB, для ещё одной есть слот; иначе код 2, ничего не менялось;
# 1. сборка образа из рабочего дерева (ROLLOUT_BUILD=0 — без сборки:
# тег сервиса уже указывает на новый образ, так делает bench/);
# 2. миграции один раз: контейнер сервиса migrate пересоздаётся на новом
# образе и выполняется до новых реплик — в новом образе новые
# ревизии, они только расширяют схему (migrations/AGENTS.md);
# 3–5. для каждой старой реплики: рядом одна новая (--scale N+1
# --no-recreate) → новая healthy и UP в LB → слот старой drain,
# запросов в полёте 0 → maint → docker stop → docker rm → адрес ушёл
# из слота → слот ready.
# Сбой: новая реплика не готова — она удаляется; новая уже UP — вывод
# старой доводится до конца. В любом исходе работает API_REPLICAS реплик,
# слоты LB без ручного состояния; повторный запуск доводит замену.
# Отката нет: откат — вернуть прежний код и снова make rolling-update
# (схема только расширялась, прежний код на ней работает).
# Окружение:
# API_REPLICAS (2) — число реплик до и после;
# ROLLOUT_BUILD (1) — собрать образ сервиса api из рабочего дерева;
# ROLLOUT_MIGRATE (1) — 0: без миграций;
# ROLLOUT_READY_TIMEOUT (60) — срок готовности новой реплики, с;
# ROLLOUT_DRAIN_TIMEOUT (12) — срок дренажа старой, с: больше timeout
# server LB (10 с), дольше запрос через LB не живёт.
# Проект compose — как у самого docker compose: COMPOSE_PROJECT_NAME,
# COMPOSE_FILE, COMPOSE_ENV_FILES или compose.yaml и .env репозитория;
# стенд bench/ (профиль rollout) вызывает этот же скрипт со своими.
# Секретов не печатает. Коды: 0 — замена завершена; 2 — неверный ввод или
# стенд не готов, ничего не менялось; 1 — сбой; 130 / 143 — прерван
# (Ctrl+C / SIGTERM).
cd "$(dirname "$0")/.."
# runtime API HAProxy: только loopback внутри контейнера LB (haproxy.cfg)
LB_API_PORT=9999
replicas="${API_REPLICAS:-2}"
ready_timeout="${ROLLOUT_READY_TIMEOUT:-60}"
drain_timeout="${ROLLOUT_DRAIN_TIMEOUT:-12}"
build="${ROLLOUT_BUILD:-1}"
migrate="${ROLLOUT_MIGRATE:-1}"
# состояние текущей замены для trap: "" — реплики не тронуты, starting —
# новая запущена и ещё не UP, replacing — новая UP, старая выводится из LB
# и удаляется
state=""
before=""
new_id=""
old_id=""
old_addr=""
old_slot=""
step=""
log() {
printf '%s rolling-update: %s\n' "$(date -u +%H:%M:%S)" "$*"
}
fail() {
code=$1
shift
printf '%s rolling-update: error: %s\n' "$(date -u +%H:%M:%S)" "$*" >&2
exit "$code"
}
short() {
printf '%.12s' "$1"
}
count() {
printf '%s\n' "$1" | grep -c . || true
}
# команда runtime API LB изнутри его контейнера (curl и socat в образе
# нет, bash есть); ответ — в stdout
lb() {
docker compose exec -T haproxy bash -c \
'exec 3<>"/dev/tcp/127.0.0.1/$2" && printf "%s\n" "$1" >&3 && cat <&3' \
lb "$1" "$LB_API_PORT"
}
# та же команда LB для оператора — в подсказках ручной уборки
lb_hint() {
printf "docker compose exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/%s && echo \"%s\" >&3 && cat <&3'" \
"$LB_API_PORT" "$1"
}
# смена состояния слота: успешная команда отвечает пустой строкой, ошибка
# — текстом («No such server.»)
lb_set() {
answer=$(lb "set server api/$1 state $2" | tr -d '\r\n')
if [ -n "$answer" ]; then
printf '%s rolling-update: error: LB set server api/%s state %s: %s\n' \
"$(date -u +%H:%M:%S)" "$1" "$2" "$answer" >&2
return 1
fi
}
# занятые слоты backend api: «слот адрес запросов_в_полёте состояние»;
# состояние последним — в нём бывают пробелы («DOWN 1/2»)
slots() {
lb "show stat" | awk -F, '
/^# / { sub(/^# /, ""); for (i = 1; i <= NF; i++) col[$i] = i; next }
$1 == "api" && $2 != "BACKEND" && $(col["addr"]) != "" {
addr = $(col["addr"]); sub(/:[0-9]+$/, "", addr)
print $2, addr, $(col["scur"]), $(col["status"])
}'
}
slot_total() {
lb "show stat" | awk -F, '$1 == "api" && $2 != "BACKEND" && $2 != "" { n++ } END { print n + 0 }'
}
# слоты с ручным состоянием, которое оставила прерванная замена: флаги
# FMAINT (1) и FDRAIN (8) в srv_admin_state; обслуживание по DNS (32) —
# штатное. show stat их не различает: у слота без адреса и то и другое —
# «MAINT (resolution)», а следующей реплике в этом слоте LB запросов не даст
manual_slots() {
lb "show servers state api" | awk '
/^# / { for (i = 2; i <= NF; i++) col[$i] = i - 1; next }
NF > 5 && col["srv_admin_state"] {
s = $(col["srv_admin_state"])
if (s % 2 == 1 || int(s / 8) % 2 == 1) print $(col["srv_name"])
}'
}
# поле слота с адресом $1: 1 — слот, 3 — запросов в полёте, 4 — состояние
slot_field() {
slots | awk -v addr="$1" -v field="$2" '
$2 == addr { if (field == 4) { $1 = $2 = $3 = ""; sub(/^ +/, "") ; print } else print $field; exit }'
}
address() {
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$1"
}
health() {
docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$1" 2>/dev/null || echo gone
}
now() {
date +%s
}
# новая реплика — ID, которого не было до up --scale (список before)
find_new() {
for id in $(docker compose ps -a -q --no-trunc api); do
case " $before " in
*" $id "*) ;;
*) printf '%s\n' "$id" ;;
esac
done
}
# дождаться, пока адрес удалённой реплики уйдёт из слота (DNS, hold 1 с),
# не дольше 10 с
wait_address_gone() {
deadline=$(($(now) + 10))
while [ -n "$(slot_field "$1" 1)" ]; do
if [ "$(now)" -ge "$deadline" ]; then
log "$step: address $1 still in slot after 10s"
return 0
fi
sleep 0.25
done
}
# довести вывод старой реплики до удаления (шаги 3–5). Ошибки проверяются
# явно (|| return 1): в trap функция вызывается под if, где set -e не
# действует. Повторный вызов после частичного — тоже корректен: удалённый
# контейнер пропускается
remove_old() {
lb_set "$old_slot" maint || return 1
if docker inspect "$old_id" >/dev/null 2>&1; then
log "$step: maint slot $old_slot, stopping old $(short "$old_id")"
stopping=$(now)
# stop_grace_period сервиса: uvicorn завершается сам за SHUTDOWN_TIMEOUT
docker stop --timeout 10 "$old_id" >/dev/null || return 1
stopped=$(($(now) - stopping))
# код выхода: 0 — graceful по SIGTERM, 137 — SIGKILL по сроку
exited=$(docker inspect -f '{{.State.ExitCode}}' "$old_id" 2>/dev/null || echo '?')
docker rm "$old_id" >/dev/null || return 1
log "$step: removed old $(short "$old_id") (stop ${stopped}s, exit $exited)"
fi
wait_address_gone "$old_addr"
lb_set "$old_slot" ready || return 1
log "$step: slot $old_slot ready"
}
# убрать новую реплику, которая не стала готовой. Есть слот (DNS уже отдал
# его) — maint, затем штатная остановка: стартующий процесс выходит сразу
# по раннему обработчику SIGTERM (src/early_stop.py), работающий —
# дорабатывает запросы, которые LB успел отправить на слот до maint. Слота
# нет — запросов на ней не было, и docker rm -f безопасен: это и страховка
# на первые десятки миллисекунд старта интерпретатора, где SIGTERM ещё
# некому принять. Прерывание между up --scale и поиском новой: ID ещё не
# известен, ищется здесь
remove_new() {
if [ -z "$new_id" ]; then
new_id=$(find_new | tail -n 1)
fi
if [ -z "$new_id" ]; then
log "$step: no new replica was created"
return 0
fi
log "$step: removing new replica $(short "$new_id") that is not ready"
new_addr=$(address "$new_id" 2>/dev/null || true)
new_slot=""
if [ -n "$new_addr" ]; then
new_slot=$(slot_field "$new_addr" 1)
fi
if [ -z "$new_slot" ]; then
docker rm -f "$new_id" >/dev/null || return 1
log "$step: removed new $(short "$new_id") (no slot: docker rm -f)"
return 0
fi
lb_set "$new_slot" maint || return 1
stopping=$(now)
docker stop --timeout 10 "$new_id" >/dev/null || return 1
stopped=$(($(now) - stopping))
exited=$(docker inspect -f '{{.State.ExitCode}}' "$new_id" 2>/dev/null || echo '?')
docker rm -f "$new_id" >/dev/null || return 1
log "$step: removed new $(short "$new_id") (slot $new_slot: stop ${stopped}s, exit $exited)"
wait_address_gone "$new_addr"
lb_set "$new_slot" ready || return 1
}
cleanup() {
code=$?
set +e
trap '' INT TERM
case "$state" in
starting)
if ! remove_new; then
log "manual cleanup: docker rm -f ${new_id:-<new api container>}; slots in manual state: $(lb_hint 'show servers state api') (srv_admin_state 1 or 8); set each ready: $(lb_hint 'set server api/<slot> state ready')"
fi
;;
replacing)
log "$step: new replica is UP, finishing removal of old $(short "$old_id")"
if ! remove_old; then
log "manual cleanup: docker rm -f $old_id; then $(lb_hint "set server api/$old_slot state ready")"
fi
;;
esac
if [ "$code" -ne 0 ] && [ -n "$state" ]; then
log "stopped: $(count "$(docker compose ps -q api)") api replicas running; rerun make rolling-update to finish"
fi
exit "$code"
}
for value in "$replicas" "$ready_timeout" "$drain_timeout"; do
case "$value" in
'' | *[!0-9]* | 0) fail 2 "API_REPLICAS and ROLLOUT_*_TIMEOUT must be positive integers" ;;
esac
done
for value in "$build" "$migrate"; do
case "$value" in
0 | 1) ;;
*) fail 2 "ROLLOUT_BUILD and ROLLOUT_MIGRATE must be 0 or 1" ;;
esac
done
# 0. предусловия — ничего не меняют
if ! lb "show info" >/dev/null 2>&1; then
fail 2 "HAProxy runtime API is unreachable: start the LB with the current infra/haproxy/haproxy.cfg (docker compose up -d --force-recreate --no-deps haproxy)"
fi
old=$(docker compose ps -q --no-trunc api)
all=$(docker compose ps -a -q --no-trunc api)
if [ "$(count "$all")" -ne "$(count "$old")" ]; then
fail 2 "stopped api replicas exist: run make replicas first"
fi
if [ "$(count "$old")" -ne "$replicas" ]; then
fail 2 "$(count "$old") api replicas running, API_REPLICAS=$replicas: run make replicas first"
fi
slots_total=$(slot_total)
if [ $((replicas + 1)) -gt "$slots_total" ]; then
fail 2 "API_REPLICAS + 1 = $((replicas + 1)) replicas do not fit $slots_total LB slots"
fi
# раньше проверки UP: слот работающей реплики в ручном drain — не повод для
# make replicas, а остаток прерванной замены
stuck=$(manual_slots | tr '\n' ' ')
if [ -n "$stuck" ]; then
fail 2 "LB slots left in manual drain/maint by an interrupted rollout: ${stuck% }; set each ready: $(lb_hint 'set server api/<slot> state ready')"
fi
for id in $old; do
status=$(slot_field "$(address "$id")" 4)
if [ "$status" != UP ]; then
fail 2 "replica $(short "$id") is not UP in LB (${status:-no slot}): run make replicas and wait"
fi
done
image=$(docker inspect -f '{{.Config.Image}}' "$(printf '%s\n' "$old" | head -n 1)")
ids=""
for id in $old; do
ids="$ids $(short "$id")"
done
log "start: $replicas replicas${ids}, image $image"
began=$(now)
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
# 1. сборка: тот же тег сервиса, работающие реплики остаются на прежнем
# образе (контейнер держит образ по ID, а не по тегу)
if [ "$build" = 1 ]; then
started=$(now)
docker compose build api
log "build done in $(($(now) - started))s"
else
log "build skipped (ROLLOUT_BUILD=0): tag $image already points to the new image"
fi
# 2. миграции один раз, до первой новой реплики. Контейнер сервиса migrate
# пересоздаётся на новом образе, а не одноразовый run --rm: иначе в стенде
# остался бы migrate прежнего образа, и restart.sh (start api запускает
# зависимость migrate) гонял бы старые миграции на новой схеме — «Can't
# locate revision», и реплики не стартуют
if [ "$migrate" = 1 ]; then
started=$(now)
if ! docker compose up --no-deps --no-build --force-recreate \
--abort-on-container-exit --exit-code-from migrate migrate; then
fail 1 "migrations failed: no replica was replaced"
fi
log "migrate done in $(($(now) - started))s"
else
log "migrate skipped (ROLLOUT_MIGRATE=0)"
fi
number=0
for old_id in $old; do
number=$((number + 1))
step="replica $number/$replicas"
# 3. одна новая реплика рядом со старыми. new_id прежнего шага — уже
# рабочая реплика: сбросить до state, иначе уборка удалила бы её
new_id=""
before=$(docker compose ps -a -q --no-trunc api | tr '\n' ' ')
state=starting
started=$(now)
docker compose up -d --no-deps --no-recreate --no-build --scale "api=$((replicas + 1))" api
new_id=$(find_new | tail -n 1)
if [ -z "$new_id" ]; then
state=""
fail 1 "$step: compose did not start a new replica"
fi
log "$step: started new $(short "$new_id")"
# 4. новая готова: healthy (или running без healthcheck) и UP в LB по её
# адресу — слот начинает DOWN и включается после rise проверок
deadline=$(($(now) + ready_timeout))
while :; do
current=$(health "$new_id")
status=""
case "$current" in
healthy | running)
new_addr=$(address "$new_id")
if [ -n "$new_addr" ]; then
status=$(slot_field "$new_addr" 4)
fi
if [ "$status" = UP ]; then
break
fi
;;
exited | dead | gone)
fail 1 "$step: new replica $(short "$new_id") $current"
;;
esac
if [ "$(now)" -ge "$deadline" ]; then
fail 1 "$step: new replica $(short "$new_id") not UP in LB within ${ready_timeout}s (container ${current}, LB ${status:-no slot})"
fi
sleep 0.25
done
log "$step: new $(short "$new_id") addr $new_addr slot $(slot_field "$new_addr" 1) UP in $(($(now) - started))s"
# 5. старая: drain → запросов в полёте 0 → maint → stop → rm → ready
old_addr=$(address "$old_id")
old_slot=$(slot_field "$old_addr" 1)
if [ -z "$old_slot" ]; then
fail 1 "$step: old replica $(short "$old_id") has no LB slot"
fi
state=replacing
lb_set "$old_slot" drain
log "$step: drain old $(short "$old_id") addr $old_addr slot $old_slot"
started=$(now)
deadline=$((started + drain_timeout))
while :; do
inflight=$(slot_field "$old_addr" 3)
if [ "${inflight:-0}" = 0 ]; then
log "$step: old $(short "$old_id") idle after $(($(now) - started))s"
break
fi
if [ "$(now)" -ge "$deadline" ]; then
log "$step: drain timeout ${drain_timeout}s, $inflight requests in flight: graceful stop finishes them"
break
fi
sleep 0.25
done
remove_old
state=""
old_slot=""
done
# итог: API_REPLICAS реплик, ни одной прежней, все UP
current=$(docker compose ps -q --no-trunc api)
if [ "$(count "$current")" -ne "$replicas" ]; then
fail 1 "$(count "$current") api replicas running after rollout, expected $replicas"
fi
ids=""
for id in $current; do
case " $(printf '%s\n' "$old" | tr '\n' ' ') " in
*" $id "*) fail 1 "old replica $(short "$id") still running" ;;
esac
status=$(slot_field "$(address "$id")" 4)
if [ "$status" != UP ]; then
fail 1 "replica $(short "$id") is not UP in LB after rollout (${status:-no slot})"
fi
ids="$ids $(short "$id")"
done
log "done: $replicas replicas${ids} UP in $(($(now) - began))s"
+82
View File
@@ -0,0 +1,82 @@
#!/bin/sh
set -eu
# Failover hook для make test-failover (tests/README.md) по образцу
# scripts/stop-one.example.sh; правила — infra/AGENTS.md.
# TARGET_INSTANCE_ID — X-Instance-Id реплики, то есть начало ID её
# контейнера (hostname в compose). Скрипт останавливает ровно одну
# работающую реплику сервиса api этого проекта и оставляет её
# остановленной: restart: unless-stopped не поднимает контейнер ни после
# docker stop, ни после docker kill. PostgreSQL, Valkey, LB, чужие
# контейнеры и volumes не трогает. Восстановление — make replicas.
# STOP_MODE=stop (по умолчанию) — docker stop: SIGTERM и graceful;
# STOP_MODE=kill — docker kill: SIGKILL, отказ процесса без graceful;
# STOP_ONE_LOG=<файл> — дописать строку «время, TARGET_INSTANCE_ID,
# полный ID контейнера, режим»: тест скрывает вывод hook, а evidence
# должно показать, какой контейнер остановлен.
# Секретов и окружения не печатает. Неверный ввод — код 2 до вызова
# docker, нет такой реплики — код 3.
# Проект compose — как у самого docker compose: COMPOSE_PROJECT_NAME,
# COMPOSE_FILE и т. п. или compose.yaml и .env репозитория.
# пустое значение — код 2 в любой оболочке (${VAR:?} даёт 1 в bash и 2 в
# dash)
if [ -z "${TARGET_INSTANCE_ID:-}" ]; then
echo "stop-one: TARGET_INSTANCE_ID is empty; test provides target API instance alias" >&2
exit 2
fi
mode="${STOP_MODE:-stop}"
case "$mode" in
stop | kill) ;;
*)
echo "stop-one: STOP_MODE must be stop or kill" >&2
exit 2
;;
esac
# hostname контейнера — его ID в hex, от 12 символов
case "$TARGET_INSTANCE_ID" in
*[!0-9a-f]*)
echo "stop-one: TARGET_INSTANCE_ID is not a container id" >&2
exit 2
;;
esac
if [ "${#TARGET_INSTANCE_ID}" -lt 12 ] || [ "${#TARGET_INSTANCE_ID}" -gt 64 ]; then
echo "stop-one: TARGET_INSTANCE_ID is not a container id" >&2
exit 2
fi
cd "$(dirname "$0")/.."
# только работающие реплики сервиса api этого проекта, полные ID
match=""
for id in $(docker compose ps -q --no-trunc api); do
case "$id" in
"$TARGET_INSTANCE_ID"*)
if [ -n "$match" ]; then
echo "stop-one: TARGET_INSTANCE_ID matches several replicas" >&2
exit 3
fi
match="$id"
;;
esac
done
if [ -z "$match" ]; then
echo "stop-one: no running api replica of this project matches TARGET_INSTANCE_ID" >&2
exit 3
fi
if [ "$mode" = stop ]; then
# uvicorn завершается сам не позже SHUTDOWN_TIMEOUT (5 с, не больше 9);
# срок 9 с гарантирует возврат hook раньше 10 с и для зависшего процесса
docker stop --timeout 9 "$match" >/dev/null
else
docker kill "$match" >/dev/null
fi
if [ -n "${STOP_ONE_LOG:-}" ]; then
printf '%s TARGET_INSTANCE_ID=%s container=%s mode=%s\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$TARGET_INSTANCE_ID" "$match" "$mode" \
>>"$STOP_ONE_LOG"
fi
echo "stop-one: stopped api container $(printf '%.12s' "$match") (mode $mode)" >&2
+210
View File
@@ -0,0 +1,210 @@
# src/ — устройство приложения
Дополняет корневой `AGENTS.md`. Правила конкретных слоёв — в
`api/AGENTS.md`, `services/AGENTS.md`, `storage/AGENTS.md`.
## Слои и направление зависимостей
```
api/ (routes, deps, identity, request_id, handlers, schemas)
↓
services/ (UserService, SessionService, ChatService, MessageService, access.py)
↓
storage/ (Storage Protocol → CachedStorage → PostgresStorage)
```
Общие модули нижнего уровня: `domain.py`, `errors.py`, `pagination.py`,
`clock.py`, `constants.py`, `log.py`, `config.py`. Инфраструктура —
тоже общие модули: `db.py` (PostgreSQL), `cache.py` (Valkey),
`passwords.py` (Argon2id). В них нет бизнес-правил.
| Модуль | Может импортировать | Не может импортировать |
|---|---|---|
| `api/*` | services, storage (только тип `Storage`), общие модули, fastapi/starlette | `storage.postgres`, `storage.cached`, `db`, `cache` (их собирает `main.py`) |
| `services/*` | `storage.Storage`, `passwords`, общие модули | `api/*`, `db`, `cache`, fastapi, starlette, pydantic, sqlalchemy |
| `storage/*` | `domain`, `errors`, `pagination`, `clock`, `constants`, `db`, `cache`, sqlalchemy | `api/*`, `services/*`, fastapi, `log` |
| `db`, `cache`, `passwords` | `config`, `constants`, `errors`, `log`, свой драйвер | `api/*`, `services/*`, `storage/*` |
| `domain`, `clock`, `constants` | только стандартную библиотеку | всё остальное из `src` |
| `errors` | `constants` | остальное |
| `pagination` | `domain`, `errors` | остальное |
| `main.py` | всё: он собирает приложение | — |
| `healthcheck.py` | только стандартную библиотеку | `src.*` (проверка должна быть дешёвой) |
| `early_stop.py` | только стандартную библиотеку | `src.*`: работает до импорта приложения и настройки журнала |
Цикл импортов или импорт «вверх» — признак, что код лежит не в том слое.
`migrations/env.py` импортирует `config`, `db.database_url`, `log` и
`storage.tables` — и ничего, что создаёт engine при импорте.
## Кто за что отвечает
- **Роут**: принять запрос (pydantic-модель, параметры пути и query),
взять сессию и сервис из зависимостей, вызвать сервис именованными
аргументами, превратить доменный объект в модель ответа. Бизнес-правил
нет.
- **Сервис**: правила контракта, которые не выражаются схемой (дубликаты
участников, вызывающий в чате, членство, курсор), пароль и сессия,
вызов хранилища, логи бизнес-событий.
- **Хранилище**: атомарная операция над данными — одна транзакция
PostgreSQL; назначение `id` и `created_at`; уникальность и внешние
ключи; перевод сработавшего ограничения в доменную ошибку. Кэш —
обёртка `CachedStorage` над тем же интерфейсом.
- **Инфраструктура**: пул, сроки, обход отказов, журнал отказов. Отказ
PostgreSQL → `Unavailable` (503) в `db.py`; отказ Valkey → промах в
`cache.py`.
## Ошибки (`errors.py`)
- У каждого класса свои `status_code`, `code`, `default_message` и, у
401, `challenge` (значение `WWW-Authenticate`). Перевод в ответ — один
обработчик `api/handlers.py` (`app_error_response`), его же зовёт
`AuthenticationMiddleware` через `identity.on_auth_error`.
- Новая ошибка: наследник подходящего класса (`InvalidRequest` → 400,
`NotFound` → 404, ...), `code` — только из enum `Error.code` в
`contracts/openapi.json`. Текст — английский, без id, путей, имён
классов, SQL и признаков существования чужого объекта.
- Нет чата и чат чужой — **одно и то же** `NotFound`.
- Тот же `Idempotency-Key` с другим телом — `IdempotencyConflict` (409
`conflict`); нет ключа или он не по шаблону — 400 из валидации
заголовка ручки. Ключ в текст ошибки не попадает.
- Вход: `InvalidCredentials` (вызов Basic) — одна ошибка на неверный
пароль, неизвестный username и битый Basic. Остальное: `Unauthorized`
(вызов Bearer). Недоступность хранилища — `Unavailable` (503), никогда
не 401.
## Время (`clock.py`)
- `created_at` назначает `MonotonicClock` внутри хранилища, перед
вставкой: строго возрастающее aware-время UTC с шагом ≥ 1 мкс внутри
**процесса**. С лабы 3 процессов несколько (реплики): между репликами
монотонности нет, порядок задают часы ВМ Docker (у реплик одного хоста
общие) и `id` при равенстве. Транзакции фиксируются не в порядке
времени: запись с меньшим `created_at` может стать видимой позже
соседней (REPORT.md, «Пагинация»).
- Срок сессии сравнивается с `utc_now()` — без монотонной поправки.
- Наружу — только `to_rfc3339()`: `2026-09-01T12:00:00.000000Z`; обратно
(значение из кэша) — `from_rfc3339()`. `datetime.now()` без UTC и
`isoformat()` в ответах не использовать: smoke требует суффикс `Z`.
## Пагинация (`pagination.py`)
- Порядок `(created_at, id)` по возрастанию; `sort_key()` — единственное
место, где он задан в Python; в SQL — `ORDER BY created_at, id` и
сравнение кортежей.
- Сервис просит у хранилища `limit + 1` строк и отдаёт их в
`make_page()`: лишняя строка значит, что есть следующая страница.
Страница ровно из `limit` при пустом остатке даёт `next_cursor=None`.
- Курсор — ключ последнего элемента страницы плюс область
(`history_scope(chat_id)`, `chat_list_scope(user_id)`). Курсор чужой
области, битый base64, не та структура → `InvalidCursor` (400).
Формат курсора внутренний: клиенты и тесты его не разбирают.
## Логи (`log.py`)
- Логгер модуля: `log = get_logger(__name__)` сразу после импортов.
`logging.getLogger` напрямую, `print` и `traceback.print_exc` не
использовать (исключение — строка `configuration error` в stderr при
неверном окружении, до настройки логов).
- Формат задаёт `logging_config()`, его применяет uvicorn
(`uvicorn.run(log_config=...)`); у процесса миграций — `migrations/env.py`.
Второй `dictConfig`/`basicConfig` в коде приложения не добавлять.
- Сообщение — английский, нижний регистр, данные — `key=value` через
`%`-подстановку: `log.info("chat created chat_id=%s members=%d", ...)`.
Не f-string: форматирование ленивое.
- `rid` добавляет фильтр из contextvar `request_id_var`; ставит его
только `RequestIdMiddleware`.
- Уровни: `info` — бизнес-событие (создан пользователь, сессия, чат,
сообщение; отказ по бизнес-правилу), старт и остановка, возврат кэша;
`warning` — обработано, но требует внимания (неудачный вход, отказ БД
или Valkey); `error` — операция не выполнена. 4xx — не ошибки сервера.
- **Нельзя в лог**: `text` сообщения, `display_name`, `title`, username,
пароль, токен, их хэши, `Authorization`, `Idempotency-Key` (его
выбирает клиент, в нём может быть что угодно; повтор виден по
`replayed=true`), тела, query-строку, параметры SQL. Engine создан с
`hide_parameters=True`: текст ошибки драйвера содержит SQL, но не
параметры. Вместо текста — `length=len(text)`.
## Конфигурация (`config.py`)
- `Settings.from_env()` читает только `os.environ`, без `.env` и файлов.
Экземпляр создаётся в `run()` и кладётся в `app.state.settings`;
модульного глобала `settings` нет.
- Подключения — вложенные `Database` и `Cache` (переменные `DB_*`,
`CACHE_*`). Пароли — поля с `repr=False`: в `repr()` настроек их нет.
- У dataclass со `slots=True` атрибут класса — дескриптор, а не значение:
умолчания в `from_env` берутся у экземпляра (`default = cls()`).
- Неверное значение — `ConfigError` с именем переменной; `run()`
печатает её в stderr и выходит с кодом 2.
- Новая настройка — поле `Settings` (или `Database`/`Cache`) с безопасным
дефолтом и границами, `environment` в `compose.yaml` (если её задают
контейнеру), строка в `.env.example` (если она приходит из `.env`),
строка в таблице ниже.
| Переменная | По умолчанию | Смысл |
|---|---|---|
| `APP_HOST` / `APP_PORT` | `127.0.0.1` (в образе `0.0.0.0`) / `8080` | адрес и порт прослушивания |
| `APP_INSTANCE_ID` | hostname (в контейнере — начало его ID) | значение `X-Instance-Id`; `[A-Za-z0-9._-]{1,64}`; по нему `scripts/stop-one.sh` находит реплику |
| `LOG_LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR` |
| `SHUTDOWN_TIMEOUT` | `5` | секунды дожидания запросов после SIGTERM, 1..9 (< `stop_grace_period` 10 с) |
| `KEEP_ALIVE_TIMEOUT` | `60` | секунды простаивающего keep-alive соединения uvicorn; больше `timeout http-keep-alive` HAProxy (10 с) — закрывает LB, а не реплика (`infra/AGENTS.md`) |
| `SESSION_TTL_SECONDS` | `3600` | срок сессии (контракт); в тесте истечения — 2 |
| `IDEMPOTENCY_TTL_SECONDS` | `86400` | сколько повтор с тем же `Idempotency-Key` отдаёт прежний результат (контракт: ≥ 24 ч); в тесте срока — 2 |
| `KDF_CONCURRENCY` | `4` | одновременных хэшей Argon2id (64 MiB на каждый) |
| `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASSWORD` | `127.0.0.1` / `5432` / `messenger` / `messenger` / пусто | подключение к PostgreSQL |
| `DB_POOL_SIZE` / `DB_POOL_OVERFLOW` / `DB_POOL_TIMEOUT` | `10` / `5` / `5` с | пул на процесс и ожидание соединения |
| `DB_CONNECT_TIMEOUT` / `DB_STATEMENT_TIMEOUT_MS` / `DB_OPERATION_TIMEOUT` | `3` с / `5000` / `6` с | подключение, серверный срок запроса, срок операции хранилища целиком |
| `CACHE_HOST` / `CACHE_PORT` / `CACHE_PASSWORD` | `127.0.0.1` / `6379` / пусто | подключение к Valkey |
| `CACHE_TIMEOUT` / `CACHE_RETRY_AFTER` / `CACHE_CHAT_TTL` / `CACHE_MAX_CONNECTIONS` | `0.2` с / `5` с / `3600` с / `10` | срок команды, окно пропуска после отказа, срок карточки, пул |
## Приложение (`main.py`)
- `create_app()` собирает `Db`, кэш (`create_cache`, пространство ключей
— имя базы), `CachedStorage(PostgresStorage(db), cache)` и
`Passwords`; кладёт их в `app.state`. Соединения открываются лениво:
без PostgreSQL процесс стартует, `/health/ready` отвечает 503.
- Порядок middleware (снаружи внутрь): `ServerErrorMiddleware` →
`RequestIdMiddleware` → `AuthenticationMiddleware` → роутер.
`add_middleware` добавляет **снаружи**, поэтому `RequestIdMiddleware`
регистрируется последним. Порядок не менять: иначе ответы 401/503 от
аутентификации не попадут в access-лог и получат случайный id вместо
входящего `X-Request-Id` (ловит `student-tests/test_request_id.py`).
- `lifespan`: первой строкой `early_stop.disarm()` (дальше сигналы —
забота uvicorn), фиктивный хэш пароля, `ready=True`; в начале остановки
`ready=False`, затем `engine.dispose()` и закрытие клиента Valkey.
Строки «messenger started instance=…» (там же пул, сроки, keep-alive) и
«messenger stopped instance=…»: по ним реплика в журнале
сопоставляется с `X-Instance-Id`. Долгих операций в остановке нет:
SIGTERM укладывается в `SHUTDOWN_TIMEOUT`.
- `RequestIdMiddleware(instance_id=...)` ставит `X-Request-Id` и
`X-Instance-Id` каждому ответу; ответам 500 их ставит
`handlers.error_response` (они формируются снаружи middleware).
- `uvicorn.run(app, ...)` — экземпляр, без `workers` и `reload`, с
`timeout_keep_alive`: один процесс, пул соединений считан на него.
Масштабирование — числом реплик за HAProxy, а не `--workers`.
- В памяти процесса нет ничего, от чего зависит корректность: сессии,
данные и ключи идемпотентности — в PostgreSQL, Valkey — общий кэш
неизменяемых карточек (лаба 3, реплики взаимозаменяемы).
## Точка входа (`__main__.py`, `early_stop.py`)
`python -m src` → `early_stop.install()` **до** импорта приложения →
`main.run()`. В контейнере сервер — PID 1, а ядро не доставляет PID 1
сигнал без обработчика: пока идёт импорт (почти весь старт), SIGTERM
терялся бы, и `docker stop` стартующей реплики ждал бы 10 с и SIGKILL.
Ранний обработчик пишет одну строку «stopped before startup» (формат
`log.py`, без rid) и завершает процесс с кодом 0. `early_stop.py` — только
stdlib. Проверка — `evidence/stand/early-stop.txt`.
## Рецепт: новая ручка
1. Найти путь, схемы и коды в `contracts/openapi.json`; если ручки там
нет — она не нужна для «4», спросить пользователя.
2. Модели запроса/ответа — в `api/schemas.py` с именами из контракта.
3. Операция данных — метод в `storage/base.py` (Protocol, докстринг: что
атомарно и какие ошибки), реализация в `storage/postgres.py`
(одна транзакция), делегирование в `storage/cached.py`. Нужна новая
колонка или индекс — сначала ревизия (`migrations/AGENTS.md`).
4. Правила — метод сервиса (keyword-only, async), лог события.
5. Роут — в `api/routes/<домен>.py`; новый файл роутов — зарегистрировать
в `api/routes/__init__.py`. Публичная ручка под `/api/v1` — добавить в
`PUBLIC_ENDPOINTS` (`api/identity.py`).
6. Тест в `student-tests/`, затем Definition of Done (корневой файл, раздел 8).
+7
View File
@@ -0,0 +1,7 @@
"""REST API мессенджера MTUSI, лабораторная 3: реплики за HAProxy.
PostgreSQL — источник истины (данные, сессии, ключи идемпотентности),
Valkey — общий кэш карточек чатов. Пакет намеренно пустой при импорте:
`import src.<модуль>` не поднимает приложение, не читает окружение и не
подключается к базе.
"""
+10
View File
@@ -0,0 +1,10 @@
if __name__ == "__main__":
# обработчик SIGTERM — до импорта приложения (src/early_stop.py):
# импорт и есть почти весь старт, а PID 1 без обработчика сигнал теряет
from src import early_stop
early_stop.install()
from src.main import run
run()
+146
View File
@@ -0,0 +1,146 @@
# src/api/ — HTTP-слой и контракт
Источник правды — `contracts/openapi.json` и `contracts/README.md`.
Сгенерированная FastAPI схема (`/openapi.json`) — только справка, но
схемы безопасности в ней совпадают с контрактом (это проверяет
`student-tests/test_auth.py`).
## Устройство
| Файл | Что делает |
|---|---|
| `routes/health.py` | `/health/live` (всегда 200), `/health/ready` (200, если старт завершён и PostgreSQL отвечает `SELECT 1` за 2 с, иначе 503; Valkey не проверяется). Вне `/api/v1`, без идентификации, в access-лог не пишутся. `/health/ready` раз в секунду опрашивает HAProxy: по нему реплика исключается из LB и возвращается |
| `routes/users.py`, `sessions.py`, `chats.py`, `messages.py` | ручки v1; префикс `/api/v1` добавляет `api_router` в `routes/__init__.py`; `messages.py` объявляет обязательный заголовок `Idempotency-Key` |
| `schemas.py` | все pydantic-модели; имена = схемы контракта (`CreateUser`, `User`, `Session`, `ChatPage`, ...) |
| `deps.py` | `get_storage`, `get_passwords`, фабрики сервисов, `current_identity` / `current_user`, разбор Basic (`basic_credentials`), `PageParams` |
| `identity.py` | `BearerBackend` для `AuthenticationMiddleware`, `PUBLIC_ENDPOINTS`, `on_auth_error` |
| `request_id.py` | чистое ASGI-middleware (`__call__`): id запроса, заголовки `X-Request-Id` и `X-Instance-Id`, access-лог |
| `handlers.py` | `error_response()`, `app_error_response()` (с `WWW-Authenticate`) и обработчики всех исключений |
## Правила ручек
- Ручки и зависимости — только `async def`: драйвер БД асинхронный, а
синхронная `def` ушла бы в threadpool.
- Ручка: зависимости → вызов сервиса именованными аргументами →
`Schema.model_validate(domain_obj)`. Логики, обращений к хранилищу и
`try/except` здесь нет.
- POST создания — `status_code=201` в декораторе; `response_model` —
модель контракта. `DELETE /auth/sessions/current` — 204 без тела
(`response_class=Response`).
- Текущий пользователь — `CurrentUser`, текущая сессия (для logout) —
`CurrentIdentity` из `deps.py`. Заголовки `Authorization` и `X-User-Id`
в ручках не читать и не объявлять `Header()`.
- Ошибки — исключения из `src/errors.py`. `HTTPException` не бросать,
`JSONResponse` с ошибкой руками не собирать — только `handlers.py`.
- Модели API в сервис не передавать: разбирать на именованные аргументы.
## Идентификация (лаба 2)
- Bearer проверяет `BearerBackend` в `AuthenticationMiddleware` **до
роутинга и разбора тела**: битый JSON без токена получает 401, а не
400 («сначала аутентификация», `contracts/README.md`). Не переносить
проверку в зависимость ручки — порядок сломается.
- Защищено всё под `/api/v1/`, кроме `PUBLIC_ENDPOINTS`:
`POST /api/v1/users` и `POST /api/v1/auth/sessions`. Health и `/docs`
— вне `/api/v1`.
- Токен — из `Authorization: Bearer <token>` (схема без учёта
регистра). Нет заголовка, другая схема (в том числе Basic на
бизнес-ручке), пустой, неизвестный, истёкший, отозванный токен —
одинаковый 401 `Unauthorized` с `WWW-Authenticate: Bearer
realm="messenger"`.
- PostgreSQL недоступен во время проверки токена — 503 `unavailable` без
`WWW-Authenticate`: бэкенд заворачивает любую `AppError` в
`AuthFailure`, и `on_auth_error` отвечает её статусом. Запрос никогда
не идёт дальше как анонимный.
- `X-User-Id` не читается нигде: не даёт доступа и не меняет владельца
сессии.
- `current_identity` объявляет `Security(HTTPBearer(scheme_name=
"bearerAuth", bearerFormat="opaque session token", auto_error=False))`
только ради схемы в `/openapi.json` и кнопки Authorize в `/docs`; сам
заголовок там не читается — сессию уже положил бэкенд в `request.user`.
## Вход по Basic (`POST /auth/sessions`)
- Путь публичный для middleware; Basic разбирает зависимость
`basic_credentials`. Схема объявлена через `HTTPBase(scheme="basic",
scheme_name="basicAuth", auto_error=False)` (импорт из
`fastapi.security.http`). **Не `HTTPBasic`**: он декодирует ASCII и на
пароле не из ASCII сам отвечает 401 мимо формата контракта.
- Разбор: схема `Basic` → base64 строго (`validate=True`) → UTF-8 →
`partition(":")` по **первому** двоеточию (в пароле двоеточие
допустимо). Username не по шаблону и пароль вне 12–128 code points
отсекаются здесь, до БД и KDF. Любой сбой — тот же 401
`InvalidCredentials` с `WWW-Authenticate: Basic realm="messenger",
charset="UTF-8"`, что и неверный пароль. Ответа 400 у входа нет.
- JSON-тело входа не читается.
## Ловушки FastAPI и что ждёт контракт
| Ситуация | FastAPI по умолчанию | Нужно |
|---|---|---|
| ошибка валидации тела/пути/query | 422 `{"detail": ...}` | 400 `invalid_request` в формате контракта (`on_validation_error`) |
| битый JSON, массив вместо объекта | 422 `json_invalid` | 400 (с токеном) или 401 (без токена: middleware раньше) |
| неизвестный путь / метод | 404 / 405 `{"detail"}` | формат контракта (`on_http_error`) |
| необработанное исключение | 500 text/plain без `X-Request-Id` | 500 `internal_error` + заголовок (`on_unexpected_error` ставит его сам) |
| `Authorization` как `Header()` | пропуск → 400 из валидации | только схемы безопасности с `auto_error=False` |
| `HTTPBasic` | ASCII, свой 401 | `HTTPBase` + свой разбор |
| `strict=True` на всю модель | UUID-строка из JSON не проходит | строгость на полях: `StrictStr`, `NonBlankStr` |
## Валидация (всё — 400)
- Модели запросов наследуют `_Request` (`extra="forbid"`): лишнее поле,
например `sender_id` в сообщении, — 400.
- Строки — `StrictStr`: число вместо строки — 400. Обязательные строки
(`display_name`, `title`, `text`, `password`) — `NonBlankStr`: одни
пробелы — 400, значение не обрезается и не нормализуется.
- Длины — в Unicode code points (`len(str)`): `display_name`, `title`
1–100, `text` 1–4000, `password` 12–128. `username` —
`^[a-z0-9_]{3,32}$` целиком.
- `member_ids`: 1–100 UUID; дубликаты, неизвестные и отсутствие
вызывающего — 400 из сервиса/хранилища (`InvalidMembers`).
- `chat_id` не UUID, `limit` вне 1–100 или не число, пустой или битый
`cursor` — 400.
- Лимиты — только из `src/constants.py`.
## Ответы
- Модели ответа наследуют `_Response` (`from_attributes=True`), время —
тип `Timestamp` (RFC 3339 с `Z`). Лишних полей нет: smoke сверяет
`additionalProperties: false`. В `User` нет пароля, хэша и сессии.
- `Session`: `token`, `token_type="Bearer"`, `expires_at`, `user`.
- Список — `{"items": [...], "next_cursor": null | "..."}`.
- `X-Request-Id` ставит `RequestIdMiddleware` каждому ответу; входящий
заголовок принимается, только если он `[A-Za-z0-9._-]{1,64}`.
- `X-Instance-Id` (лаба 3) — **в каждом ответе API**: успех, ошибки,
health, 401/503 от аутентификации, 404 неизвестного пути, 405, 500.
Одно значение на процесс (`Settings.instance_id`: `APP_INSTANCE_ID` или
hostname — в контейнере начало ID). Ответы самого HAProxy (502/503/504)
его не имеют — контракт допускает. Тест — `test_request_id.py`.
- Access-лог: одна строка `METHOD path -> status (ms)`, без query, тела
и заголовков. Второй access-лог (uvicorn) выключен.
## Отправка сообщения: `Idempotency-Key` (лаба 3)
- Заголовок обязателен только у `POST /api/v1/chats/{chat_id}/messages`:
параметр ручки `Header(alias="Idempotency-Key", pattern=...)` с
шаблоном `IDEMPOTENCY_KEY_PATTERN` (`^[A-Za-z0-9._:-]{1,128}$`). Нет
ключа, пустой, длиннее 128, недопустимый символ, не-ASCII — 400
`invalid_request` той же валидацией, что тело; значение ключа в текст
ошибки не попадает. Другие POST ключ не читают.
- Порядок кодов: 401 (сессия — middleware) → 400 (ключ и тело — схема
ручки) → 404 (не участник — сервис) → 409 (ключ занят другим телом —
хранилище). Без токена — 401 даже с битым JSON и без ключа:
аутентификация в middleware раньше разбора тела и заголовков ручки.
Закреплено `test_idempotency.py::test_codes_order_401_400_404_409`.
- Повтор того же тела — **тот же 201 и то же `Message`** (тот же `id`,
`created_at` до микросекунды): ручка не различает новое и повторное.
«То же тело» — семантически: пробелы и `\u`-экранирование не важны
(хэш канонического JSON в сервисе).
- Прозрачных повторов других POST нет ни в API, ни в LB.
## Проверка правок этого слоя
`make fmt && make lint && make test-isolated`. Для точечной проверки —
рабочий стенд (`make up`) и `curl -s -i` с выводом статуса,
`x-request-id`, `x-instance-id`, `www-authenticate` и тела. Токен в
вывод и отчёт не копировать.
View File
+170
View File
@@ -0,0 +1,170 @@
"""Зависимости ручек: хранилище, сервисы, текущая сессия, вход, страница."""
import base64
import binascii
import re
from dataclasses import dataclass, field
from typing import Annotated
from fastapi import Depends, Query, Request, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from fastapi.security.http import HTTPBase
from src.constants import (
PAGE_LIMIT_DEFAULT,
PAGE_LIMIT_MAX,
PAGE_LIMIT_MIN,
PASSWORD_MAX_LENGTH,
PASSWORD_MIN_LENGTH,
USERNAME_PATTERN,
)
from src.domain import Identity, User
from src.errors import InvalidCredentials, Unauthorized
from src.passwords import Passwords
from src.services import ChatService, MessageService, SessionService, UserService
from src.storage import Storage
async def get_storage(request: Request) -> Storage:
return request.app.state.storage
async def get_passwords(request: Request) -> Passwords:
return request.app.state.passwords
StorageDep = Annotated[Storage, Depends(get_storage)]
PasswordsDep = Annotated[Passwords, Depends(get_passwords)]
async def get_user_service(storage: StorageDep, passwords: PasswordsDep) -> UserService:
return UserService(storage, passwords)
async def get_session_service(
request: Request,
storage: StorageDep,
passwords: PasswordsDep,
) -> SessionService:
return SessionService(
storage, passwords, ttl=request.app.state.settings.session_ttl
)
async def get_chat_service(storage: StorageDep) -> ChatService:
return ChatService(storage)
async def get_message_service(request: Request, storage: StorageDep) -> MessageService:
return MessageService(
storage,
key_ttl=request.app.state.settings.idempotency_ttl,
)
UserServiceDep = Annotated[UserService, Depends(get_user_service)]
SessionServiceDep = Annotated[SessionService, Depends(get_session_service)]
ChatServiceDep = Annotated[ChatService, Depends(get_chat_service)]
MessageServiceDep = Annotated[MessageService, Depends(get_message_service)]
# схемы bearerAuth и basicAuth из contracts/openapi.json: они есть в
# /openapi.json и дают кнопку Authorize в /docs. auto_error=False —
# FastAPI не отвечает сам своим 403/401 мимо формата контракта.
# Bearer проверяет BearerBackend (identity.py) ещё до роутинга.
bearer_scheme = HTTPBearer(
scheme_name="bearerAuth",
bearerFormat="opaque session token",
auto_error=False,
)
# HTTPBase, а не HTTPBasic: HTTPBasic декодирует credentials как ASCII и
# на пароле не из ASCII сам отвечает 401, а контракт требует UTF-8
basic_scheme = HTTPBase(scheme="basic", scheme_name="basicAuth", auto_error=False)
async def current_identity(
request: Request,
_credentials: Annotated[
HTTPAuthorizationCredentials | None, Security(bearer_scheme)
],
) -> Identity:
"""Сессия, которую нашёл BearerBackend.
`_credentials` здесь не читается: параметр только объявляет схему
bearerAuth в OpenAPI. Если ручку вдруг повесили на публичный путь,
сессии нет — 401, а не падение.
"""
identity = request.user
if not isinstance(identity, Identity):
raise Unauthorized
return identity
CurrentIdentity = Annotated[Identity, Depends(current_identity)]
async def current_user(identity: CurrentIdentity) -> User:
return identity.user
CurrentUser = Annotated[User, Depends(current_user)]
@dataclass(frozen=True, slots=True)
class BasicCredentials:
username: str
password: str = field(repr=False)
def parse_basic(
credentials: HTTPAuthorizationCredentials | None,
) -> BasicCredentials | None:
"""username и пароль из `Authorization: Basic`; `None` — разбор не удался.
base64 строго, UTF-8, разделитель — первое двоеточие: в username его
не бывает, в пароле оно допустимо. Значения, которые не могут быть
верными (формат username и длина пароля публичны), отсекаются здесь:
до БД и KDF не доходит ни мусор, ни пароль в мегабайт.
"""
if credentials is None or credentials.scheme.lower() != "basic":
return None
try:
decoded = base64.b64decode(credentials.credentials, validate=True)
username, separator, password = decoded.decode().partition(":")
except (binascii.Error, UnicodeDecodeError):
return None
if not separator or not re.fullmatch(USERNAME_PATTERN, username):
return None
if not PASSWORD_MIN_LENGTH <= len(password) <= PASSWORD_MAX_LENGTH:
return None
return BasicCredentials(username=username, password=password)
async def basic_credentials(
credentials: Annotated[HTTPAuthorizationCredentials | None, Security(basic_scheme)],
) -> BasicCredentials:
"""Учётные данные входа; любой сбой разбора — тот же 401, что неверный пароль."""
parsed = parse_basic(credentials)
if parsed is None:
raise InvalidCredentials
return parsed
BasicCredentialsDep = Annotated[BasicCredentials, Depends(basic_credentials)]
@dataclass(frozen=True, slots=True)
class PageParams:
limit: int
cursor: str | None
async def page_params(
limit: Annotated[int, Query(ge=PAGE_LIMIT_MIN, le=PAGE_LIMIT_MAX)] = (
PAGE_LIMIT_DEFAULT
),
cursor: Annotated[str | None, Query(min_length=1)] = None,
) -> PageParams:
return PageParams(limit=limit, cursor=cursor)
PageDep = Annotated[PageParams, Depends(page_params)]
+121
View File
@@ -0,0 +1,121 @@
"""Любая ошибка → `{"error": {"code", "message", "request_id"}}`.
- `AppError`: статус, `code` и `WWW-Authenticate` (у 401) берутся из
класса исключения.
- Ошибки валидации FastAPI → 400 `invalid_request` (422 не отдаётся).
- 404 неизвестного пути и 405 → формат контракта.
- Непредвиденное исключение → 500 без деталей. Traceback пишет uvicorn:
Starlette после ответа бросает исключение дальше.
"""
from uuid import uuid4
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException
from starlette.requests import HTTPConnection
from src.api.schemas import ErrorBody, ErrorResponse
from src.constants import INSTANCE_ID_HEADER, REQUEST_ID_HEADER
from src.errors import AppError
_HTTP_ERRORS: dict[int, tuple[str, str]] = {
404: ("not_found", "Not found"),
405: ("invalid_request", "Method not allowed"),
}
def request_id_of(conn: HTTPConnection) -> str:
"""Id запроса от RequestIdMiddleware; запасной — если ошибка случилась раньше."""
return getattr(conn.state, "request_id", None) or uuid4().hex
def error_response(
conn: HTTPConnection,
*,
status_code: int,
code: str,
message: str,
headers: dict[str, str] | None = None,
) -> JSONResponse:
request_id = request_id_of(conn)
body = ErrorResponse(
error=ErrorBody(code=code, message=message, request_id=request_id),
)
return JSONResponse(
status_code=status_code,
content=body.model_dump(),
# заголовки ставит и middleware; здесь они нужны ответам 500,
# которые формируются снаружи всех middleware
headers={
**(headers or {}),
REQUEST_ID_HEADER: request_id,
INSTANCE_ID_HEADER: conn.app.state.settings.instance_id,
},
)
def app_error_response(conn: HTTPConnection, exc: AppError) -> JSONResponse:
"""Ответ на доменную ошибку; общий для ручек и AuthenticationMiddleware."""
return error_response(
conn,
status_code=exc.status_code,
code=exc.code,
message=str(exc),
headers={"WWW-Authenticate": exc.challenge} if exc.challenge else None,
)
async def on_app_error(request: Request, exc: AppError) -> JSONResponse:
return app_error_response(request, exc)
async def on_validation_error(
request: Request,
exc: RequestValidationError,
) -> JSONResponse:
# первая ошибка: где и что не так; входное значение в ответ не попадает
errors = exc.errors()
first = errors[0] if errors else {}
location = ".".join(str(part) for part in first.get("loc", ()))
reason = first.get("msg", "Invalid request")
return error_response(
request,
status_code=400,
code="invalid_request",
message=f"{location}: {reason}" if location else reason,
)
async def on_http_error(
request: Request,
exc: StarletteHTTPException,
) -> JSONResponse:
code, message = _HTTP_ERRORS.get(
exc.status_code,
("invalid_request", "Invalid request"),
)
return error_response(
request,
status_code=exc.status_code,
code=code,
message=message,
headers=exc.headers,
)
async def on_unexpected_error(request: Request, _exc: Exception) -> JSONResponse:
return error_response(
request,
status_code=500,
code="internal_error",
message="Internal server error",
)
def install(app: FastAPI) -> None:
app.add_exception_handler(AppError, on_app_error)
app.add_exception_handler(RequestValidationError, on_validation_error)
app.add_exception_handler(StarletteHTTPException, on_http_error)
app.add_exception_handler(Exception, on_unexpected_error)
+89
View File
@@ -0,0 +1,89 @@
"""Идентификация лабы 2: Bearer-сессия — до роутинга и разбора тела.
Работает через стандартный `AuthenticationMiddleware` Starlette.
`BearerBackend` вызывается на каждый запрос:
- публичный путь (health, docs, `POST /api/v1/users`,
`POST /api/v1/auth/sessions`) — `None`, запрос идёт дальше без
пользователя. Вход по Basic разбирает сама ручка входа (`deps.py`);
- защищённый путь — сессия по токену из `Authorization: Bearer <token>`
или отказ, и middleware сразу отвечает через `on_auth_error`.
Поэтому 401 приходит раньше любой проверки тела, пути и query: «сначала
аутентификация» из contracts/README.md выполняется даже для битого JSON.
Ручки берут готовую сессию из `request.user` (`deps.current_identity`).
`X-User-Id` больше не читается нигде: он не даёт доступа и не меняет
владельца сессии. Basic на бизнес-ручке — чужая схема, тот же 401 с
вызовом Bearer. Недоступность PostgreSQL — 503, а не 401 и не анонимный
доступ.
"""
from fastapi.responses import JSONResponse
from fastapi.security.utils import get_authorization_scheme_param
from starlette.authentication import (
AuthCredentials,
AuthenticationBackend,
AuthenticationError,
)
from starlette.requests import HTTPConnection
from src.api.handlers import app_error_response
from src.constants import API_PREFIX, AUTHORIZATION_HEADER, SESSIONS_PATH
from src.domain import Identity
from src.errors import AppError, Unauthorized
from src.services import SessionService
# публичные пути внутри API_PREFIX: регистрация и вход по Basic
PUBLIC_ENDPOINTS = frozenset(
{
("POST", f"{API_PREFIX}/users"),
("POST", SESSIONS_PATH),
},
)
def requires_identity(method: str, path: str) -> bool:
return path.startswith(f"{API_PREFIX}/") and (method, path) not in PUBLIC_ENDPOINTS
def bearer_token(header: str | None) -> str | None:
"""Токен из `Authorization: Bearer <token>`; другая схема — `None`."""
scheme, token = get_authorization_scheme_param(header)
if scheme.lower() != "bearer" or not token:
return None
return token
class AuthFailure(AuthenticationError):
"""Отказ бэкенда с доменной ошибкой: 401 или 503 (БД недоступна)."""
def __init__(self, error: AppError) -> None:
super().__init__(str(error))
self.error = error
class BearerBackend(AuthenticationBackend):
async def authenticate(
self,
conn: HTTPConnection,
) -> tuple[AuthCredentials, Identity] | None:
if not requires_identity(conn.scope.get("method", ""), conn.scope["path"]):
return None
state = conn.app.state
sessions = SessionService(
state.storage,
state.passwords,
ttl=state.settings.session_ttl,
)
token = bearer_token(conn.headers.get(AUTHORIZATION_HEADER))
try:
identity = await sessions.authenticate(token=token)
except AppError as exc:
raise AuthFailure(exc) from exc
return AuthCredentials(["authenticated"]), identity
def on_auth_error(conn: HTTPConnection, exc: AuthenticationError) -> JSONResponse:
error = exc.error if isinstance(exc, AuthFailure) else Unauthorized()
return app_error_response(conn, error)
+83
View File
@@ -0,0 +1,83 @@
"""X-Request-Id и X-Instance-Id на каждом ответе, одна строка access-лога.
Чистое ASGI-middleware: прямой вызов приложения и обёртка send.
Без дочерней задачи и потока сообщений на каждый запрос: это уменьшает
накладные расходы слоя, исследуемые в треке «5».
Id запроса: входящий `X-Request-Id`, если он короткий и безопасный
(`[A-Za-z0-9._-]{1,64}`), иначе новый uuid4. Так id проходит через
балансировщик, а мусор из заголовка не попадает в логи. Тот же id — в
заголовке ответа, в `request_id` тела ошибки и в каждой строке лога
этого запроса.
`X-Instance-Id` (лаба 3) — реплика, которая обслужила запрос: одно
значение на процесс (`Settings.instance_id`). Ответы, которые создаёт
сам HAProxy (502/503/504), его не имеют — контракт это допускает.
"""
import re
import time
from uuid import uuid4
from starlette.datastructures import Headers, MutableHeaders
from starlette.types import ASGIApp, Message, Receive, Scope, Send
from src.constants import HEALTH_PATHS, INSTANCE_ID_HEADER, REQUEST_ID_HEADER
from src.log import get_logger, request_id_var
log = get_logger("src.http")
_SAFE_REQUEST_ID = re.compile(r"[A-Za-z0-9._-]{1,64}")
def _request_id(scope: Scope) -> str:
incoming = Headers(scope=scope).get(REQUEST_ID_HEADER)
if incoming and _SAFE_REQUEST_ID.fullmatch(incoming):
return incoming
return uuid4().hex
class RequestIdMiddleware:
def __init__(self, app: ASGIApp, *, instance_id: str) -> None:
self.app = app
self.instance_id = instance_id
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
if scope["type"] != "http":
await self.app(scope, receive, send)
return
request_id = _request_id(scope)
# request.state.request_id — для обработчиков ошибок
scope.setdefault("state", {})["request_id"] = request_id
# не сбрасывается: у каждого запроса в uvicorn своя задача, а
# traceback непредвиденной ошибки uvicorn пишет уже после выхода
# отсюда, и в нём тоже нужен rid
request_id_var.set(request_id)
status_code = 500
started = time.perf_counter()
async def send_with_ids(message: Message) -> None:
nonlocal status_code
if message["type"] == "http.response.start":
status_code = message["status"]
headers = MutableHeaders(scope=message)
if REQUEST_ID_HEADER not in headers:
headers.append(REQUEST_ID_HEADER, request_id)
if INSTANCE_ID_HEADER not in headers:
headers.append(INSTANCE_ID_HEADER, self.instance_id)
await send(message)
try:
await self.app(scope, receive, send_with_ids)
finally:
# health дёргают healthcheck и балансировщик: в лог не пишем.
# Путь без query; тела и заголовки идентификации не логируются
if scope["path"] not in HEALTH_PATHS:
log.info(
"%s %s -> %d (%.1f ms)",
scope["method"],
scope["path"],
status_code,
(time.perf_counter() - started) * 1000,
)
+24
View File
@@ -0,0 +1,24 @@
"""Роутеры. `api_router` собирает ручки версии 1 под API_PREFIX.
Новый домен регистрируется только здесь.
"""
from fastapi import APIRouter
from src.api.routes.chats import router as chats_router
from src.api.routes.health import router as health_router
from src.api.routes.messages import router as messages_router
from src.api.routes.sessions import router as sessions_router
from src.api.routes.users import router as users_router
from src.constants import API_PREFIX
api_router = APIRouter(prefix=API_PREFIX)
api_router.include_router(users_router)
api_router.include_router(sessions_router)
api_router.include_router(chats_router)
api_router.include_router(messages_router)
__all__ = [
"api_router",
"health_router",
]
+46
View File
@@ -0,0 +1,46 @@
from uuid import UUID
from fastapi import APIRouter
from src.api import schemas
from src.api.deps import ChatServiceDep, CurrentUser, PageDep
router = APIRouter(prefix="/chats", tags=["chats"])
@router.post("", status_code=201, response_model=schemas.Chat)
async def create_chat(
user: CurrentUser,
body: schemas.CreateChat,
chats: ChatServiceDep,
) -> schemas.Chat:
chat = await chats.create(
creator_id=user.id,
title=body.title,
member_ids=body.member_ids,
)
return schemas.Chat.model_validate(chat)
@router.get("", response_model=schemas.ChatPage)
async def list_chats(
user: CurrentUser,
page: PageDep,
chats: ChatServiceDep,
) -> schemas.ChatPage:
result = await chats.list_for(
user_id=user.id,
limit=page.limit,
cursor=page.cursor,
)
return schemas.ChatPage.model_validate(result)
@router.get("/{chat_id}", response_model=schemas.Chat)
async def get_chat(
user: CurrentUser,
chat_id: UUID,
chats: ChatServiceDep,
) -> schemas.Chat:
chat = await chats.get(chat_id=chat_id, user_id=user.id)
return schemas.Chat.model_validate(chat)
+32
View File
@@ -0,0 +1,32 @@
from fastapi import APIRouter, Request
from src.api.schemas import ErrorResponse, Health
from src.constants import HEALTH_LIVE_PATH, HEALTH_READY_PATH
from src.errors import Unavailable
# вне версии API, без идентификации, в access-лог не пишутся
router = APIRouter(tags=["health"])
@router.get(HEALTH_LIVE_PATH, response_model=Health)
async def live() -> Health:
"""Процесс жив и отвечает по HTTP. Хранилища не проверяются."""
return Health()
@router.get(
HEALTH_READY_PATH,
response_model=Health,
responses={503: {"model": ErrorResponse}},
)
async def ready(request: Request) -> Health:
"""Можно обслуживать обязательный путь; иначе 503.
Критичная зависимость — PostgreSQL (`SELECT 1` за 2 с): в нём данные
и сессии. Valkey не проверяется: это кэш, без него запросы идут в
PostgreSQL. До конца старта и с начала остановки — тоже 503.
"""
if not request.app.state.ready:
raise Unavailable
await request.app.state.storage.ping()
return Health()
+51
View File
@@ -0,0 +1,51 @@
from typing import Annotated
from uuid import UUID
from fastapi import APIRouter, Header
from src.api import schemas
from src.api.deps import CurrentUser, MessageServiceDep, PageDep
from src.constants import IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_KEY_PATTERN
router = APIRouter(prefix="/chats/{chat_id}/messages", tags=["messages"])
# обязательный заголовок (лаба 3). Проверяет схема ручки вместе с телом:
# нет ключа или он не по шаблону — 400 после 401 (middleware) и до 404
# (членство в сервисе). Значение в текст ошибки не попадает
IdempotencyKey = Annotated[
str,
Header(alias=IDEMPOTENCY_KEY_HEADER, pattern=IDEMPOTENCY_KEY_PATTERN),
]
@router.post("", status_code=201, response_model=schemas.Message)
async def send_message(
user: CurrentUser,
chat_id: UUID,
body: schemas.CreateMessage,
idempotency_key: IdempotencyKey,
messages: MessageServiceDep,
) -> schemas.Message:
message = await messages.send(
chat_id=chat_id,
sender_id=user.id,
text=body.text,
idempotency_key=idempotency_key,
)
return schemas.Message.model_validate(message)
@router.get("", response_model=schemas.MessagePage)
async def list_messages(
user: CurrentUser,
chat_id: UUID,
page: PageDep,
messages: MessageServiceDep,
) -> schemas.MessagePage:
result = await messages.history(
chat_id=chat_id,
user_id=user.id,
limit=page.limit,
cursor=page.cursor,
)
return schemas.MessagePage.model_validate(result)
+29
View File
@@ -0,0 +1,29 @@
from fastapi import APIRouter, Response
from src.api import schemas
from src.api.deps import BasicCredentialsDep, CurrentIdentity, SessionServiceDep
router = APIRouter(prefix="/auth/sessions", tags=["sessions"])
@router.post("", status_code=201, response_model=schemas.Session)
async def create_session(
credentials: BasicCredentialsDep,
sessions: SessionServiceDep,
) -> schemas.Session:
"""Вход по `Authorization: Basic`; тело запроса не читается."""
issued = await sessions.login(
username=credentials.username,
password=credentials.password,
)
return schemas.Session.model_validate(issued)
@router.delete("/current", status_code=204, response_class=Response)
async def revoke_current_session(
identity: CurrentIdentity,
sessions: SessionServiceDep,
) -> Response:
"""Выход: отзывается только сессия этого токена."""
await sessions.revoke(session_id=identity.session_id)
return Response(status_code=204)
+24
View File
@@ -0,0 +1,24 @@
from fastapi import APIRouter
from src.api import schemas
from src.api.deps import CurrentUser, UserServiceDep
router = APIRouter(prefix="/users", tags=["users"])
@router.post("", status_code=201, response_model=schemas.User)
async def register_user(
body: schemas.CreateUser,
users: UserServiceDep,
) -> schemas.User:
user = await users.register(
username=body.username,
display_name=body.display_name,
password=body.password,
)
return schemas.User.model_validate(user)
@router.get("/me", response_model=schemas.User)
async def get_me(user: CurrentUser) -> schemas.User:
return schemas.User.model_validate(user)
+133
View File
@@ -0,0 +1,133 @@
"""HTTP-модели. Имена и поля совпадают со схемами contracts/openapi.json.
Модели запросов строгие: лишнее поле или неверный тип — 400. Строгость
задаётся на уровне полей (`StrictStr`), а не `strict=True` на всю
модель: иначе UUID, пришедший строкой в JSON, не прошёл бы проверку.
"""
from datetime import datetime
from typing import Annotated, Literal
from uuid import UUID
from pydantic import (
AfterValidator,
BaseModel,
ConfigDict,
Field,
PlainSerializer,
StrictStr,
)
from src.clock import to_rfc3339
from src.constants import (
CHAT_MEMBERS_MAX,
CHAT_TITLE_MAX_LENGTH,
DISPLAY_NAME_MAX_LENGTH,
MESSAGE_TEXT_MAX_LENGTH,
PASSWORD_MAX_LENGTH,
PASSWORD_MIN_LENGTH,
USERNAME_PATTERN,
)
def _not_blank(value: str) -> str:
"""Строка из одних пробельных символов невалидна; значение не обрезается."""
if not value.strip():
raise ValueError("must not be blank")
return value
# строгая непустая строка: число не превращается в строку, пробелы — 400
NonBlankStr = Annotated[StrictStr, AfterValidator(_not_blank)]
# время в ответе: RFC 3339 UTC с микросекундами и Z
Timestamp = Annotated[datetime, PlainSerializer(to_rfc3339, return_type=str)]
class _Request(BaseModel):
model_config = ConfigDict(extra="forbid")
class _Response(BaseModel):
model_config = ConfigDict(from_attributes=True)
class CreateUser(_Request):
username: StrictStr = Field(pattern=USERNAME_PATTERN)
display_name: NonBlankStr = Field(min_length=1, max_length=DISPLAY_NAME_MAX_LENGTH)
# длина в code points; значение не обрезается и не нормализуется
password: NonBlankStr = Field(
min_length=PASSWORD_MIN_LENGTH,
max_length=PASSWORD_MAX_LENGTH,
json_schema_extra={"writeOnly": True},
)
class User(_Response):
"""Пароля, его хэша и данных сессии здесь нет и быть не может."""
id: UUID
username: str
display_name: str
created_at: Timestamp
class Session(_Response):
"""Ответ на вход. Токен клиент видит только здесь, один раз."""
token: str
token_type: Literal["Bearer"] = "Bearer"
expires_at: Timestamp
user: User
class CreateChat(_Request):
title: NonBlankStr = Field(min_length=1, max_length=CHAT_TITLE_MAX_LENGTH)
# только форма списка; дубликаты, существование участников и
# вызывающего в списке проверяет ChatService.create
member_ids: list[UUID] = Field(min_length=1, max_length=CHAT_MEMBERS_MAX)
class Chat(_Response):
id: UUID
title: str
member_ids: list[UUID]
created_at: Timestamp
class ChatPage(_Response):
items: list[Chat]
next_cursor: str | None
class CreateMessage(_Request):
"""Отправитель берётся из идентификации: поле sender_id даёт 400."""
text: NonBlankStr = Field(min_length=1, max_length=MESSAGE_TEXT_MAX_LENGTH)
class Message(_Response):
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: Timestamp
class MessagePage(_Response):
items: list[Message]
next_cursor: str | None
class Health(BaseModel):
status: Literal["ok"] = "ok"
class ErrorBody(BaseModel):
code: str
message: str
request_id: str
class ErrorResponse(BaseModel):
error: ErrorBody
+128
View File
@@ -0,0 +1,128 @@
"""Valkey: кэш со сроком на команду и обходом при отказе.
Кэш — не источник истины, поэтому его отказ — промах, а не ошибка:
`get` отдаёт `None`, `set` — `False`, и запрос идёт в PostgreSQL с тем
же ответом. Вся команда — ожидание пула, соединение, повтор и ответ —
ограничена `CACHE_TIMEOUT`. После отказа кэш пропускается на
`CACHE_RETRY_AFTER` секунд: следующие запросы не ждут срок заново.
redis-py по умолчанию повторяет команду с паузами, и замороженный
Valkey держал бы запрос секунды. Здесь повтор один, без паузы и только
на обрыв соединения: так старое соединение пула после рестарта Valkey
открывается заново сразу, а таймаут не повторяется.
В журнал — одна строка `warning` на отказ и `info` при возврате. Пароль
есть только в настройках пула и в журнал не попадает.
"""
import asyncio
import time
from redis.asyncio import BlockingConnectionPool, Redis
from redis.asyncio.retry import Retry
from redis.backoff import NoBackoff
from redis.exceptions import ConnectionError as RedisConnectionError
from redis.exceptions import RedisError
from src.config import Cache as CacheSettings
from src.log import get_logger
log = get_logger(__name__)
class Cache:
"""Строковый кэш поверх клиента Valkey: отказ — промах.
`namespace` — имя базы PostgreSQL, из которой взяты значения: на одном
Valkey ключи разных баз (рабочей и тестовой) не пересекаются.
"""
def __init__(
self,
client: Redis,
*,
namespace: str,
timeout: float,
retry_after: float,
) -> None:
self.namespace = namespace
self._client = client
self._timeout = timeout
self._retry_after = retry_after
# monotonic-время конца пропуска; None — кэш работает
self._skip_until: float | None = None
async def get(self, key: str) -> str | None:
"""Значение ключа; `None` — промах, в том числе из-за отказа."""
if self._skipping():
return None
try:
async with asyncio.timeout(self._timeout):
value = await self._client.get(key)
except (RedisError, OSError) as exc:
self._failed(exc)
return None
self._succeeded()
return value
async def set(self, key: str, value: str, *, ttl: int) -> bool:
"""Записать со сроком в секундах; `False` — не записано из-за отказа."""
if self._skipping():
return False
try:
async with asyncio.timeout(self._timeout):
await self._client.set(key, value, ex=ttl)
except (RedisError, OSError) as exc:
self._failed(exc)
return False
self._succeeded()
return True
async def close(self) -> None:
await self._client.aclose()
def _skipping(self) -> bool:
return self._skip_until is not None and time.monotonic() < self._skip_until
def _failed(self, error: Exception) -> None:
# одна строка на отказ: неудачные пробы после окна пропуска молчат.
# TimeoutError от asyncio.timeout без текста — тогда repr
if self._skip_until is None:
log.warning(
"cache unavailable error_type=%s error=%s retry_after=%.1fs",
type(error).__name__,
str(error) or repr(error),
self._retry_after,
)
self._skip_until = time.monotonic() + self._retry_after
def _succeeded(self) -> None:
if self._skip_until is not None:
self._skip_until = None
log.info("cache available again")
def create_cache(settings: CacheSettings, *, namespace: str) -> Cache:
"""Кэш с пулом и сроками из настроек; соединения открываются лениво."""
# BlockingConnectionPool: при всплеске запросов команда ждёт свободное
# соединение, а обычный пул сразу бросал бы MaxConnectionsError, и
# здоровый Valkey пропускался бы как отказавший.
# Retry — из redis.asyncio: синхронный класс асинхронное соединение
# принимает молча, но повтор с ним не выполняется
pool = BlockingConnectionPool(
host=settings.host,
port=settings.port,
password=settings.password or None,
max_connections=settings.max_connections,
timeout=settings.timeout,
socket_timeout=settings.timeout,
socket_connect_timeout=settings.timeout,
retry=Retry(NoBackoff(), 1, supported_errors=(RedisConnectionError,)),
decode_responses=True,
)
return Cache(
Redis.from_pool(pool),
namespace=namespace,
timeout=settings.timeout,
retry_after=settings.retry_after,
)
+51
View File
@@ -0,0 +1,51 @@
"""Время сервера: монотонные часы и формат RFC 3339.
`created_at` задаёт порядок истории `(created_at, id)`. Системные часы
могут шагнуть назад (NTP) или выдать одно значение двум записям подряд.
`MonotonicClock` отдаёт строго возрастающее время с шагом не меньше 1 мкс.
Хранилище берёт время у него перед вставкой. Процесс один, event loop
один, а `now()` не содержит `await`: два вызова не перемешаются.
Строгий рост — внутри одного процесса. Транзакции фиксируются не в том
порядке, в каком получили время, поэтому запись с меньшим `created_at`
может стать видимой чуть позже соседней (REPORT.md, «Пагинация»).
"""
from datetime import UTC, datetime, timedelta
# RFC 3339 в UTC: всегда шесть знаков микросекунд и суффикс Z
RFC3339_FORMAT = "%Y-%m-%dT%H:%M:%S.%fZ"
_TICK = timedelta(microseconds=1)
class MonotonicClock:
"""Строго возрастающее aware-время UTC.
Не потокобезопасен: вызывается только из event loop процесса.
"""
def __init__(self) -> None:
self._last: datetime | None = None
def now(self) -> datetime:
current = datetime.now(UTC)
if self._last is not None and current <= self._last:
current = self._last + _TICK
self._last = current
return current
def utc_now() -> datetime:
"""Текущее время UTC без монотонной поправки: для сравнения со сроком."""
return datetime.now(UTC)
def to_rfc3339(value: datetime) -> str:
"""Время для ответа API: `2026-09-01T12:00:00.000000Z`."""
return value.astimezone(UTC).strftime(RFC3339_FORMAT)
def from_rfc3339(value: str) -> datetime:
"""Обратно из `to_rfc3339()`: aware-время UTC с микросекундами."""
return datetime.strptime(value, RFC3339_FORMAT).replace(tzinfo=UTC)
+287
View File
@@ -0,0 +1,287 @@
"""Настройки процесса — только из переменных окружения.
Файлов конфигурации нет. В compose переменные задаёт `environment`
(значения подставляются из `.env`), `make run` передаёт их приложению на
хосте сам; без них действуют значения по умолчанию. Полный список
переменных — AGENTS.md, раздел «Конфигурация».
Пароли PostgreSQL и Valkey тоже приходят переменными: в `repr()`
настроек их нет, в лог они не пишутся.
"""
import os
import re
import socket
from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import Self
LOG_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR")
DEFAULT_HOST = "127.0.0.1"
DEFAULT_PORT = 8080
DEFAULT_LOG_LEVEL = "INFO"
DEFAULT_SHUTDOWN_TIMEOUT = 5
# секунды, которые uvicorn держит простаивающее keep-alive соединение.
# Больше timeout http-keep-alive HAProxy (10 с): простаивающее соединение
# LB → реплика закрывает LB, а не реплика (infra/AGENTS.md, «Цепочка
# таймаутов»)
DEFAULT_KEEP_ALIVE = 60
# контракт: SESSION_TTL_SECONDS, по умолчанию 3600
DEFAULT_SESSION_TTL = 3600
# контракт: результат отправки по ключу хранится не меньше 24 ч
DEFAULT_IDEMPOTENCY_TTL = 24 * 3600
# одновременных хэшей Argon2id: каждый берёт 64 MiB памяти
DEFAULT_KDF_CONCURRENCY = 4
# срок сессии и ключа не больше 30 суток: длиннее учебному стенду не нужно
MAX_SESSION_TTL = 30 * 24 * 3600
# X-Instance-Id: в compose это hostname контейнера (начало его ID)
_INSTANCE_ID = re.compile(r"[A-Za-z0-9._-]{1,64}")
class ConfigError(ValueError):
"""Переменная окружения задана, но её значение неверно."""
def _text(env: Mapping[str, str], name: str, default: str) -> str:
value = env.get(name, "").strip()
return value or default
def _int(env: Mapping[str, str], name: str, default: int, low: int, high: int) -> int:
raw = env.get(name, "").strip()
if not raw:
return default
try:
value = int(raw)
except ValueError:
raise ConfigError(f"{name} must be an integer, got {raw!r}") from None
if not low <= value <= high:
raise ConfigError(f"{name} must be within {low}..{high}, got {value}")
return value
def _instance_id(env: Mapping[str, str]) -> str:
"""`APP_INSTANCE_ID` или hostname: стабилен, пока жив процесс.
В контейнере hostname — короткий ID контейнера: по нему
`scripts/stop-one.sh` находит реплику, ответившую тесту.
"""
raw = env.get("APP_INSTANCE_ID", "").strip()
if not raw:
return socket.gethostname() or "local"
if not _INSTANCE_ID.fullmatch(raw):
raise ConfigError(
f"APP_INSTANCE_ID must match {_INSTANCE_ID.pattern}, got {raw!r}",
)
return raw
def _float(
env: Mapping[str, str],
name: str,
default: float,
low: float,
high: float,
) -> float:
raw = env.get(name, "").strip()
if not raw:
return default
try:
value = float(raw)
except ValueError:
raise ConfigError(f"{name} must be a number, got {raw!r}") from None
if not low <= value <= high:
raise ConfigError(f"{name} must be within {low}..{high}, got {value}")
return value
@dataclass(frozen=True, slots=True)
class Database:
"""Подключение к PostgreSQL, пул и сроки (переменные `DB_*`)."""
host: str = "127.0.0.1"
port: int = 5432
name: str = "messenger"
user: str = "messenger"
password: str = field(default="", repr=False)
# соединений в пуле и сверх него: пул считается на один процесс
pool_size: int = 10
pool_overflow: int = 5
# секунды ожидания свободного соединения пула
pool_timeout: float = 5.0
# секунды на установку соединения
connect_timeout: float = 3.0
# серверный statement_timeout, мс; 0 — без ограничения
statement_timeout_ms: int = 5000
# секунды на одну операцию хранилища целиком: зависший сервер или
# обрыв сети, где серверный таймаут не сработает
operation_timeout: float = 6.0
@classmethod
def from_env(cls, env: Mapping[str, str]) -> Self:
# у dataclass со slots атрибут класса — дескриптор, не значение:
# значения по умолчанию берутся у экземпляра
default = cls()
return cls(
host=_text(env, "DB_HOST", default.host),
port=_int(env, "DB_PORT", default.port, 1, 65535),
name=_text(env, "DB_NAME", default.name),
user=_text(env, "DB_USER", default.user),
password=env.get("DB_PASSWORD", ""),
pool_size=_int(env, "DB_POOL_SIZE", default.pool_size, 1, 100),
pool_overflow=_int(
env,
"DB_POOL_OVERFLOW",
default.pool_overflow,
0,
100,
),
pool_timeout=_float(
env,
"DB_POOL_TIMEOUT",
default.pool_timeout,
0.1,
60,
),
connect_timeout=_float(
env,
"DB_CONNECT_TIMEOUT",
default.connect_timeout,
0.1,
60,
),
statement_timeout_ms=_int(
env,
"DB_STATEMENT_TIMEOUT_MS",
default.statement_timeout_ms,
0,
600_000,
),
operation_timeout=_float(
env,
"DB_OPERATION_TIMEOUT",
default.operation_timeout,
0.1,
120,
),
)
@dataclass(frozen=True, slots=True)
class Cache:
"""Подключение к Valkey (кэш карточек чатов, переменные `CACHE_*`)."""
host: str = "127.0.0.1"
port: int = 6379
password: str = field(default="", repr=False)
# секунды на всю команду: ожидание пула, соединение, повтор, ответ;
# дольше — запрос идёт в PostgreSQL
timeout: float = 0.2
# секунды, на которые кэш пропускается после отказа Valkey
retry_after: float = 5.0
# секунды жизни карточки чата в кэше
chat_ttl: int = 3600
# соединений в пуле клиента
max_connections: int = 10
@classmethod
def from_env(cls, env: Mapping[str, str]) -> Self:
default = cls()
return cls(
host=_text(env, "CACHE_HOST", default.host),
port=_int(env, "CACHE_PORT", default.port, 1, 65535),
password=env.get("CACHE_PASSWORD", ""),
timeout=_float(env, "CACHE_TIMEOUT", default.timeout, 0.01, 10),
retry_after=_float(
env,
"CACHE_RETRY_AFTER",
default.retry_after,
0.1,
600,
),
chat_ttl=_int(env, "CACHE_CHAT_TTL", default.chat_ttl, 1, 86_400),
max_connections=_int(
env,
"CACHE_MAX_CONNECTIONS",
default.max_connections,
1,
1000,
),
)
@dataclass(frozen=True, slots=True)
class Settings:
# адрес прослушивания: локально только loopback, в образе ENV APP_HOST=0.0.0.0
host: str = DEFAULT_HOST
port: int = DEFAULT_PORT
log_level: str = DEFAULT_LOG_LEVEL
# секунды, которые uvicorn дорабатывает начатые запросы после SIGTERM;
# docker stop шлёт SIGKILL через 10 с, поэтому не больше 9
shutdown_timeout: int = DEFAULT_SHUTDOWN_TIMEOUT
keep_alive: int = DEFAULT_KEEP_ALIVE
# X-Instance-Id этого процесса; from_env берёт APP_INSTANCE_ID или
# hostname
instance_id: str = "local"
# секунды жизни сессии с момента входа; запросы и рестарт не продлевают
session_ttl: int = DEFAULT_SESSION_TTL
# секунды, в течение которых повтор с тем же Idempotency-Key отдаёт
# прежний результат; позже ключ можно занять заново
idempotency_ttl: int = DEFAULT_IDEMPOTENCY_TTL
kdf_concurrency: int = DEFAULT_KDF_CONCURRENCY
database: Database = Database()
cache: Cache = Cache()
@classmethod
def from_env(cls, env: Mapping[str, str] | None = None) -> Self:
"""Настройки из окружения; неверное значение — `ConfigError`."""
env = os.environ if env is None else env
log_level = _text(env, "LOG_LEVEL", DEFAULT_LOG_LEVEL).upper()
if log_level not in LOG_LEVELS:
raise ConfigError(
f"LOG_LEVEL must be one of {', '.join(LOG_LEVELS)}, got {log_level!r}",
)
return cls(
host=_text(env, "APP_HOST", DEFAULT_HOST),
port=_int(env, "APP_PORT", DEFAULT_PORT, 1, 65535),
log_level=log_level,
shutdown_timeout=_int(
env,
"SHUTDOWN_TIMEOUT",
DEFAULT_SHUTDOWN_TIMEOUT,
1,
9,
),
keep_alive=_int(
env,
"KEEP_ALIVE_TIMEOUT",
DEFAULT_KEEP_ALIVE,
1,
3600,
),
instance_id=_instance_id(env),
session_ttl=_int(
env,
"SESSION_TTL_SECONDS",
DEFAULT_SESSION_TTL,
1,
MAX_SESSION_TTL,
),
idempotency_ttl=_int(
env,
"IDEMPOTENCY_TTL_SECONDS",
DEFAULT_IDEMPOTENCY_TTL,
1,
MAX_SESSION_TTL,
),
kdf_concurrency=_int(
env,
"KDF_CONCURRENCY",
DEFAULT_KDF_CONCURRENCY,
1,
64,
),
database=Database.from_env(env),
cache=Cache.from_env(env),
)
+67
View File
@@ -0,0 +1,67 @@
"""Константы, одинаковые на всех установках.
Лимиты взяты из contracts/openapi.json и contracts/README.md. Это часть
контракта: значения не меняются и не выносятся в настройки.
"""
# пути
API_PREFIX = "/api/v1"
HEALTH_LIVE_PATH = "/health/live"
HEALTH_READY_PATH = "/health/ready"
HEALTH_PATHS = frozenset({HEALTH_LIVE_PATH, HEALTH_READY_PATH})
SESSIONS_PATH = f"{API_PREFIX}/auth/sessions"
# заголовки
REQUEST_ID_HEADER = "X-Request-Id"
AUTHORIZATION_HEADER = "Authorization"
# с лабы 3: какая реплика ответила (каждый ответ API) и ключ повтора
# отправки сообщения
INSTANCE_ID_HEADER = "X-Instance-Id"
IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
# пользователь
USERNAME_PATTERN = r"^[a-z0-9_]{3,32}$"
DISPLAY_NAME_MAX_LENGTH = 100
# пароль: 12–128 Unicode code points, хэшируется целиком как UTF-8
PASSWORD_MIN_LENGTH = 12
PASSWORD_MAX_LENGTH = 128
# начало строки Argon2id: CHECK в БД не даёт записать пароль иначе
PASSWORD_HASH_PREFIX = "$argon2id$"
# сессия
# байты случайности токена: 256 бит, 43 символа base64url
SESSION_TOKEN_BYTES = 32
# в БД хранится SHA-256 токена, а не токен
TOKEN_HASH_BYTES = 32
# realm в WWW-Authenticate у ответов 401
AUTH_REALM = "messenger"
# чат
CHAT_TITLE_MAX_LENGTH = 100
CHAT_MEMBERS_MAX = 100
# сообщение
MESSAGE_TEXT_MAX_LENGTH = 4000
# ключ идемпотентности отправки (лаба 3): ASCII, 1–128 символов целиком
IDEMPOTENCY_KEY_PATTERN = r"^[A-Za-z0-9._:-]{1,128}$"
# в БД хранится SHA-256 канонического тела запроса, а не тело
REQUEST_HASH_BYTES = 32
# пагинация
PAGE_LIMIT_MIN = 1
PAGE_LIMIT_MAX = 100
PAGE_LIMIT_DEFAULT = 50
# PostgreSQL
# имя соединений сервиса в pg_stat_activity
DB_APPLICATION_NAME = "mtusi-messenger"
# секунды на SELECT 1 в /health/ready
READINESS_TIMEOUT = 2.0
# секунды на мягкое закрытие соединения; дальше asyncpg обрывает его
DB_CLOSE_TIMEOUT = 2.0
# кэш (Valkey)
# начало ключей; v1 — формат значения: новый формат — v2, старые ключи
# тогда просто не читаются
CACHE_KEY_PREFIX = "messenger:v1"
+168
View File
@@ -0,0 +1,168 @@
"""PostgreSQL: engine с ограниченным пулом, срок операции, отказ → 503.
`Db` — то, через что хранилище ходит в базу. Одна операция хранилища —
одна транзакция `transaction()`: commit при выходе, откат при ошибке. Вся
операция — ожидание пула, подключение, запросы и commit — ограничена
`DB_OPERATION_TIMEOUT`: зависший сервер не держит запрос бесконечно.
Ошибки, которые значат «базы нет или она не отвечает», превращаются в
`Unavailable` (503) со строкой `warning` в журнале; остальные (нарушение
ограничения, синтаксис) идут дальше как есть: это дефект или доменная
ошибка, а не отказ хранилища.
Engine открывает соединения лениво: без PostgreSQL процесс стартует,
а `/health/ready` отвечает 503.
"""
import asyncio
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
import asyncpg
from sqlalchemy import URL, text
from sqlalchemy import exc as sa_exc
from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine, create_async_engine
from src.config import Database as DatabaseSettings
from src.constants import DB_APPLICATION_NAME, DB_CLOSE_TIMEOUT, READINESS_TIMEOUT
from src.errors import Unavailable
from src.log import get_logger
log = get_logger(__name__)
# SQLSTATE «база недоступна»: класс 08 — ошибки соединения, 57014 —
# сработал statement_timeout, 57P01–57P03 — сервер останавливается или
# ещё не принимает подключения
UNAVAILABLE_SQLSTATES = ("08", "57014", "57P01", "57P02", "57P03")
# длина текста ошибки в журнале: одна строка, без простыни SQLAlchemy
_ERROR_TEXT_LIMIT = 300
class BoundedCloseConnection(asyncpg.Connection):
"""Соединение asyncpg, мягкое закрытие которого ограничено сроком.
Прерванный по сроку запрос SQLAlchemy закрывает соединение мягко, а
asyncpg при этом ждёт ответа сервера без ограничения: замёрзший
PostgreSQL держал бы запрос до разморозки. Здесь закрытие ограничено
`DB_CLOSE_TIMEOUT`, дальше asyncpg обрывает соединение.
"""
# сигнатура — как у asyncpg.Connection.close: SQLAlchemy зовёт её так
async def close(self, *, timeout: float | None = None) -> None: # noqa: ASYNC109
await asyncio.wait_for(
super().close(timeout=timeout), timeout or DB_CLOSE_TIMEOUT
)
def database_url(settings: DatabaseSettings) -> URL:
"""URL драйвера asyncpg; пароль экранирует `URL.create`, строку не собираем."""
return URL.create(
"postgresql+asyncpg",
username=settings.user,
password=settings.password,
host=settings.host,
port=settings.port,
database=settings.name,
)
def create_engine(settings: DatabaseSettings) -> AsyncEngine:
"""Engine с ограниченным пулом и таймаутами из настроек."""
return create_async_engine(
database_url(settings),
pool_size=settings.pool_size,
max_overflow=settings.pool_overflow,
pool_timeout=settings.pool_timeout,
# после рестарта PostgreSQL соединения пула мертвы: проверка при
# выдаче не даёт первому запросу получить ошибку
pool_pre_ping=True,
# текст ошибки драйвера уходит в журнал: без этого в нём были бы
# параметры SQL — тексты сообщений, хэши паролей и токенов
hide_parameters=True,
connect_args={
"timeout": settings.connect_timeout,
# command_timeout asyncpg не задан: на зависшем сервере он
# отменяет запрос через новое соединение и ждёт без срока
"connection_class": BoundedCloseConnection,
"server_settings": {
"application_name": DB_APPLICATION_NAME,
"statement_timeout": str(settings.statement_timeout_ms),
},
},
)
def is_unavailable(error: BaseException) -> bool:
"""Ошибка значит «PostgreSQL недоступен» (→ 503), а не дефект (→ 500).
Остановленный сервер — `ConnectionRefusedError`, неразрешимое имя —
`socket.gaierror`, срок операции — `TimeoutError`: всё это `OSError`.
Пул исчерпан — `sqlalchemy.exc.TimeoutError`. Оборванное соединение и
statement_timeout — `DBAPIError` с признаком или SQLSTATE.
"""
if isinstance(error, OSError | sa_exc.TimeoutError):
return True
if isinstance(error, sa_exc.DBAPIError):
if error.connection_invalidated:
return True
sqlstate = getattr(error.orig, "sqlstate", None) or ""
return sqlstate.startswith(UNAVAILABLE_SQLSTATES)
return False
def _one_line(error: BaseException) -> str:
# TimeoutError от asyncio.timeout без текста — тогда repr
raw = " ".join(str(error).split()) or repr(error)
return raw[:_ERROR_TEXT_LIMIT]
class Db:
"""Engine процесса и границы транзакций хранилища."""
def __init__(self, settings: DatabaseSettings) -> None:
# имя базы: им же разделяются ключи кэша разных баз на одном Valkey
self.name = settings.name
self.engine = create_engine(settings)
self._operation_timeout = settings.operation_timeout
@asynccontextmanager
async def transaction(self) -> AsyncIterator[AsyncConnection]:
"""Одна транзакция со сроком; недоступность базы — `Unavailable`.
На сроке asyncio отменяет ожидание драйвера: SQLAlchemy считает
такое соединение испорченным и не возвращает его в пул, а его
закрытие ограничено `BoundedCloseConnection`. Поэтому замёрзший
сервер даёт 503 через `DB_OPERATION_TIMEOUT` + `DB_CLOSE_TIMEOUT`.
"""
try:
async with (
asyncio.timeout(self._operation_timeout),
self.engine.begin() as connection,
):
yield connection
except Exception as exc:
if not is_unavailable(exc):
raise
log.warning(
"database unavailable error_type=%s error=%s",
type(exc).__name__,
_one_line(exc),
)
raise Unavailable from exc
async def ping(self) -> None:
"""`SELECT 1` за `READINESS_TIMEOUT`; иначе `Unavailable`.
Не логирует: healthcheck спрашивает каждые несколько секунд.
Любая ошибка — 503: готовность не отвечает 500.
"""
try:
async with (
asyncio.timeout(READINESS_TIMEOUT),
self.engine.connect() as connection,
):
await connection.execute(text("SELECT 1"))
except Exception as exc:
raise Unavailable from exc
async def dispose(self) -> None:
await self.engine.dispose()
+90
View File
@@ -0,0 +1,90 @@
"""Доменные записи. Неизменяемые: хранилище отдаёт их наружу без копирования.
Пароль, его хэш и токен сессии в `User` не входят: хэш живёт только в
`Credentials` (вход), токен — только в `IssuedSession` (ответ на вход).
"""
from dataclasses import dataclass, field
from datetime import datetime
from uuid import UUID
@dataclass(frozen=True, slots=True)
class User:
id: UUID
username: str
display_name: str
created_at: datetime
@dataclass(frozen=True, slots=True)
class Credentials:
"""Пользователь и хэш его пароля: только для проверки при входе."""
user: User
password_hash: str = field(repr=False)
@dataclass(frozen=True, slots=True)
class Session:
"""Серверная сессия входа. Срок фиксируется при создании."""
id: UUID
user_id: UUID
expires_at: datetime
created_at: datetime
@dataclass(frozen=True, slots=True)
class IssuedSession:
"""Ответ на вход: токен отдаётся клиенту один раз и нигде не хранится."""
token: str = field(repr=False)
expires_at: datetime
user: User
@dataclass(frozen=True, slots=True)
class Identity:
"""Кто прислал запрос: действующая сессия и её владелец."""
session_id: UUID
user: User
@dataclass(frozen=True, slots=True)
class Chat:
id: UUID
title: str
# в порядке, переданном при создании
member_ids: tuple[UUID, ...]
created_at: datetime
@dataclass(frozen=True, slots=True)
class Message:
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: datetime
@dataclass(frozen=True, slots=True)
class SentMessage:
"""Итог отправки с ключом: новое сообщение или сохранённое прежнее.
`replayed` — ответ на повтор того же тела; клиенту оба случая
отдаются одинаково (201 и то же `Message`), флаг нужен журналу.
"""
message: Message
replayed: bool
@dataclass(frozen=True, slots=True)
class Page[T]:
"""Страница списка в порядке `(created_at, id)`."""
items: tuple[T, ...]
next_cursor: str | None
+63
View File
@@ -0,0 +1,63 @@
"""Остановка до старта сервера: SIGTERM и SIGINT во время импорта.
В контейнере `python -m src` — PID 1, а ядро не доставляет PID 1 сигнал,
для которого нет обработчика. Пока импортируется приложение (почти весь
старт, сотни миллисекунд при лимите в 1 CPU), обработчик uvicorn ещё не
стоит, и `docker stop` стартующей реплики ждал бы `stop_grace_period`
(10 с) и кончался SIGKILL. Это бьёт по поочерёдной замене: сбой на
середине убирает только что запущенную реплику (`scripts/rolling-update.sh`).
`install()` ставится первым делом в `src/__main__.py`, до импорта
приложения: сигнал до старта сервера пишет одну строку журнала и
завершает процесс с кодом 0 (запросов и соединений ещё нет).
`disarm()` — первая строка lifespan: дальше сигналы обрабатывает
uvicorn. После остановки сервера uvicorn возвращает этот обработчик и
повторяет пойманный сигнал — снятый обработчик его игнорирует, и
процесс выходит штатно, с кодом 0.
Только стандартная библиотека: модуль работает до настройки журнала и
до импорта `src.config`. Строка — в формате `src/log.py`, без rid.
"""
import contextlib
import os
import signal
import socket
import time
from types import FrameType
_armed = False
def _line(signum: int) -> bytes:
now = time.time()
stamp = time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(now))
millis = int(now % 1 * 1000)
instance = os.environ.get("APP_INSTANCE_ID", "").strip() or socket.gethostname()
return (
f"{stamp}.{millis:03d}Z INFO src.early_stop [rid=-] "
f"stopped before startup signal={signal.Signals(signum).name} "
f"instance={instance}\n"
).encode()
def _stop(signum: int, _frame: FrameType | None) -> None:
if not _armed:
return
# ошибка записи выходу не мешает
with contextlib.suppress(OSError):
os.write(1, _line(signum))
os._exit(0)
def install() -> None:
global _armed
_armed = True
signal.signal(signal.SIGTERM, _stop)
signal.signal(signal.SIGINT, _stop)
def disarm() -> None:
"""Сервер стартовал: дальше сигналы — забота uvicorn."""
global _armed
_armed = False
+96
View File
@@ -0,0 +1,96 @@
"""Ошибки приложения. Каждая сама знает свой HTTP-статус и `code` контракта.
Сервисы, хранилище и пагинация бросают только их (не `HTTPException`).
В ответ `{"error": {...}}` их переводит один обработчик в
src/api/handlers.py. Текст ошибки уходит клиенту в `error.message`:
по-английски, без деталей реализации и без признаков существования
чужого объекта. У ответов 401 есть ещё `WWW-Authenticate`: вызов той
схемы, которой клиенту повторить запрос (`challenge`).
"""
from src.constants import AUTH_REALM
class AppError(Exception):
status_code: int = 400
code: str = "invalid_request"
default_message: str = "Invalid request"
# значение WWW-Authenticate; только у 401
challenge: str | None = None
def __init__(self, message: str | None = None) -> None:
super().__init__(message or self.default_message)
class InvalidRequest(AppError):
"""Запрос синтаксически верен, но нарушает правила контракта."""
class InvalidMembers(InvalidRequest):
"""Дубликаты в member_ids, неизвестный участник или нет вызывающего."""
default_message = "Invalid chat members"
class InvalidCursor(InvalidRequest):
"""Курсор повреждён или выдан для другого списка."""
default_message = "Invalid cursor"
class InvalidCredentials(AppError):
"""Вход отклонён: неверный пароль, неизвестный username или битый Basic.
Все причины — один ответ: по нему не узнать, есть ли пользователь.
"""
status_code = 401
code = "unauthorized"
default_message = "Invalid username or password"
challenge = f'Basic realm="{AUTH_REALM}", charset="UTF-8"'
class Unauthorized(AppError):
"""Нет Bearer-токена, он неизвестен, истёк или отозван."""
status_code = 401
code = "unauthorized"
default_message = "Valid bearer token is required"
challenge = f'Bearer realm="{AUTH_REALM}"'
class NotFound(AppError):
"""Объекта нет или он чужой: оба случая неразличимы для клиента."""
status_code = 404
code = "not_found"
default_message = "Not found"
class UsernameTaken(AppError):
status_code = 409
code = "conflict"
default_message = "Username is already taken"
class IdempotencyConflict(AppError):
"""Тот же `Idempotency-Key` уже принят с другим телом сообщения.
Ключ в текст не попадает: его выбирает клиент.
"""
status_code = 409
code = "conflict"
default_message = "Idempotency key was already used with a different request"
class Unavailable(AppError):
"""PostgreSQL недоступен или не ответил вовремя; приложение не готово.
Ограниченная ошибка вместо 500 и никогда не пропуск запроса как
анонимного: недоступность хранилища сессий — не отказ в доступе.
"""
status_code = 503
code = "unavailable"
default_message = "Service is temporarily unavailable"
+25
View File
@@ -0,0 +1,25 @@
"""HEALTHCHECK образа: `python -m src.healthcheck`.
Код выхода 0 — `/health/ready` ответил 200, иначе 1. Только стандартная
библиотека и без импорта приложения: в slim-образе нет curl, а проверка
должна быть дешёвой.
"""
import os
import sys
import urllib.error
import urllib.request
def main() -> int:
port = os.environ.get("APP_PORT", "8080")
url = f"http://127.0.0.1:{port}/health/ready"
try:
with urllib.request.urlopen(url, timeout=2) as response:
return 0 if response.status == 200 else 1
except (urllib.error.URLError, OSError):
return 1
if __name__ == "__main__":
sys.exit(main())
+81
View File
@@ -0,0 +1,81 @@
"""Логи обычным текстом в stdout: одна строка на событие.
Формат строки (перенос — только здесь, в логе строка одна):
2026-09-30T12:00:00.123Z INFO src.http [rid=3f2a...]
POST /api/v1/users -> 201 (1.4 ms)
`rid` — id запроса из contextvar, тот же, что в заголовке `X-Request-Id`
и в теле ошибки; вне запроса (старт, остановка) там `-`. Время — UTC.
Логи uvicorn идут через тот же handler и формат: по строкам «Shutting
down» и «Finished server process» видно, сколько заняла остановка.
"""
import logging
import time
from contextvars import ContextVar
from typing import Any
# ставит только RequestIdMiddleware
request_id_var: ContextVar[str] = ContextVar("request_id", default="-")
LOG_FORMAT = "%(asctime)s %(levelname)-7s %(name)s [rid=%(request_id)s] %(message)s"
class UtcFormatter(logging.Formatter):
"""Время записи в UTC с миллисекундами и суффиксом Z."""
converter = time.gmtime
default_time_format = "%Y-%m-%dT%H:%M:%S"
default_msec_format = "%s.%03dZ"
class RequestIdFilter(logging.Filter):
"""Добавляет в каждую запись поле `request_id` из contextvar."""
def filter(self, record: logging.LogRecord) -> bool:
record.request_id = request_id_var.get()
return True
def get_logger(name: str) -> logging.Logger:
"""Логгер модуля приложения: `get_logger(__name__)`."""
return logging.getLogger(name)
def logging_config(level: str) -> dict[str, Any]:
"""Конфиг для `uvicorn.run(log_config=...)`.
uvicorn применяет его сам через `logging.config.dictConfig` до старта
приложения, поэтому второй настройки логирования в коде нет.
"""
return {
"version": 1,
"disable_existing_loggers": False,
"filters": {"request_id": {"()": RequestIdFilter}},
"formatters": {"text": {"()": UtcFormatter, "fmt": LOG_FORMAT}},
"handlers": {
"stdout": {
"class": "logging.StreamHandler",
"stream": "ext://sys.stdout",
"formatter": "text",
"filters": ["request_id"],
},
},
"loggers": {
"src": {
"level": level,
"handlers": ["stdout"],
"propagate": False,
},
# uvicorn.error наследует handler от uvicorn: свой дал бы дубли
"uvicorn": {"level": "INFO", "handlers": ["stdout"], "propagate": False},
# access-лог пишет RequestIdMiddleware, у uvicorn он выключен
"uvicorn.access": {"level": "WARNING", "handlers": [], "propagate": False},
# сервис migrate: строки «Running upgrade ...» тем же форматом
"alembic": {"level": "INFO", "handlers": ["stdout"], "propagate": False},
# SQL и его параметры в журнал не идут: только предупреждения
"sqlalchemy": {"level": "WARNING"},
},
"root": {"level": "WARNING", "handlers": ["stdout"]},
}
+143
View File
@@ -0,0 +1,143 @@
"""Сборка приложения и запуск uvicorn.
Порядок middleware (снаружи внутрь): ServerErrorMiddleware Starlette →
RequestIdMiddleware → AuthenticationMiddleware (Bearer) →
ExceptionMiddleware → роутер. Последний `add_middleware` оказывается
снаружи, поэтому RequestIdMiddleware добавляется последним: ответ 401
получает тот же id, что и остальные ответы, и попадает в access-лог.
Хранилище собирается здесь: `CachedStorage` (Valkey) поверх
`PostgresStorage`. Engine и клиент Valkey открывают соединения лениво:
без PostgreSQL процесс стартует, а `/health/ready` отвечает 503.
С лабы 3 процессов несколько — реплики за HAProxy. В памяти процесса нет
ничего, от чего зависит корректность: сессии, данные и ключи
идемпотентности — в PostgreSQL, Valkey — общий кэш неизменяемых карточек.
Каждый процесс по-прежнему один, с одним event loop: масштабирование —
числом реплик, а не `--workers`.
"""
import os
import sys
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
import uvicorn
from fastapi import FastAPI
from starlette.middleware.authentication import AuthenticationMiddleware
from src import early_stop
from src.api import handlers
from src.api.identity import BearerBackend, on_auth_error
from src.api.request_id import RequestIdMiddleware
from src.api.routes import api_router, health_router
from src.cache import create_cache
from src.config import ConfigError, Settings
from src.db import Db
from src.log import get_logger, logging_config
from src.passwords import Passwords
from src.storage import CachedStorage, PostgresStorage
log = get_logger(__name__)
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
# сервер стартовал: сигналы дальше обрабатывает uvicorn
early_stop.disarm()
settings: Settings = app.state.settings
if not settings.database.password:
log.warning("database password is empty")
if not settings.cache.password:
log.warning("cache password is empty")
# десятки миллисекунд CPU при старте: время ответа на вход с
# неизвестным username ровное с первого запроса
await app.state.passwords.prepare()
# instance — значение X-Instance-Id: по этой строке реплика в журнале
# сопоставляется с ответами, которые видел клиент
log.info(
"messenger started instance=%s host=%s port=%d pid=%d db=%s:%d/%s "
"cache=%s:%d pool=%d+%d session_ttl=%ds idempotency_ttl=%ds "
"shutdown_timeout=%ds keep_alive=%ds",
settings.instance_id,
settings.host,
settings.port,
os.getpid(),
settings.database.host,
settings.database.port,
settings.database.name,
settings.cache.host,
settings.cache.port,
settings.database.pool_size,
settings.database.pool_overflow,
settings.session_ttl,
settings.idempotency_ttl,
settings.shutdown_timeout,
settings.keep_alive,
)
app.state.ready = True
try:
yield
finally:
app.state.ready = False
# сюда uvicorn приходит после SIGTERM, когда начатые запросы
# закончились или вышел SHUTDOWN_TIMEOUT; данные уже в PostgreSQL
await app.state.db.dispose()
await app.state.cache.close()
log.info("messenger stopped instance=%s", settings.instance_id)
def create_app(settings: Settings | None = None) -> FastAPI:
"""Приложение с хранилищем на PostgreSQL и кэшем в Valkey."""
settings = settings or Settings.from_env()
app = FastAPI(
title="MTUSI Messenger — лабораторная 3",
version="1.3.0",
lifespan=lifespan,
)
db = Db(settings.database)
# ключи кэша — по имени базы: тестовая база не видит карточек рабочей
cache = create_cache(settings.cache, namespace=db.name)
app.state.settings = settings
app.state.db = db
app.state.cache = cache
app.state.storage = CachedStorage(
PostgresStorage(db),
cache,
chat_ttl=settings.cache.chat_ttl,
)
app.state.passwords = Passwords(settings.kdf_concurrency)
app.state.ready = False
handlers.install(app)
app.add_middleware(
AuthenticationMiddleware,
backend=BearerBackend(),
on_error=on_auth_error,
)
app.add_middleware(RequestIdMiddleware, instance_id=settings.instance_id)
app.include_router(health_router)
app.include_router(api_router)
return app
def run() -> None:
"""Точка входа `python -m src`: один процесс, один event loop."""
try:
settings = Settings.from_env()
except ConfigError as exc:
print(f"configuration error: {exc}", file=sys.stderr)
raise SystemExit(2) from None
# экземпляр, а не строка импорта: без reload и без --workers. Пул
# соединений считается на один процесс; процессов — число реплик
uvicorn.run(
create_app(settings),
host=settings.host,
port=settings.port,
log_config=logging_config(settings.log_level),
access_log=False,
server_header=False,
timeout_graceful_shutdown=settings.shutdown_timeout,
timeout_keep_alive=settings.keep_alive,
)
+88
View File
@@ -0,0 +1,88 @@
"""Keyset-пагинация по `(created_at, id)` и непрозрачный курсор.
Курсор — base64url без `=` от строки `<scope>|<микросекунды>|<id hex>`:
ключ последнего элемента страницы плюс область списка. Область —
`chat:<id>` для истории чата и `chats-of:<id>` для списка чатов
пользователя, поэтому курсор другого чата или пользователя не
принимается (400). Клиент курсор не разбирает, формат можно менять.
"""
import base64
import binascii
from collections.abc import Sequence
from datetime import UTC, datetime, timedelta
from typing import Protocol
from uuid import UUID
from src.domain import Page
from src.errors import InvalidCursor
type SortKey = tuple[datetime, UUID]
_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
_MICROSECOND = timedelta(microseconds=1)
_SEPARATOR = "|"
class Keyed(Protocol):
@property
def id(self) -> UUID: ...
@property
def created_at(self) -> datetime: ...
def sort_key(item: Keyed) -> SortKey:
"""Порядок контракта: `created_at`, при равенстве — `id` как UUID."""
return item.created_at, item.id
def history_scope(chat_id: UUID) -> str:
return f"chat:{chat_id}"
def chat_list_scope(user_id: UUID) -> str:
return f"chats-of:{user_id}"
def encode_cursor(scope: str, key: SortKey) -> str:
created_at, item_id = key
micros = (created_at - _EPOCH) // _MICROSECOND
raw = _SEPARATOR.join((scope, str(micros), item_id.hex))
return base64.urlsafe_b64encode(raw.encode()).rstrip(b"=").decode("ascii")
def decode_cursor(cursor: str | None, scope: str) -> SortKey | None:
"""Ключ, после которого начинается страница; нет курсора — `None`.
Битый курсор или курсор другой области — `InvalidCursor`.
"""
if cursor is None:
return None
try:
padded = cursor + "=" * (-len(cursor) % 4)
# Нестрогий декодер молча игнорировал посторонние символы курсора.
raw = base64.b64decode(
padded.encode("ascii"), altchars=b"-_", validate=True
).decode()
cursor_scope, micros, item_hex = raw.split(_SEPARATOR)
created_at = _EPOCH + int(micros) * _MICROSECOND
item_id = UUID(hex=item_hex)
except (ValueError, UnicodeError, binascii.Error, OverflowError):
raise InvalidCursor from None
if cursor_scope != scope:
raise InvalidCursor
return created_at, item_id
def make_page[T: Keyed](rows: Sequence[T], *, limit: int, scope: str) -> Page[T]:
"""Страница из выборки длиной до `limit + 1`.
Лишний элемент значит, что дальше есть ещё записи. Курсор строится по
последнему элементу страницы, а не по лишнему: тот придёт первым на
следующей странице.
"""
items = tuple(rows[:limit])
if len(rows) <= limit:
return Page(items=items, next_cursor=None)
return Page(items=items, next_cursor=encode_cursor(scope, sort_key(items[-1])))
+74
View File
@@ -0,0 +1,74 @@
"""Хэширование паролей: Argon2id в потоке с отдельным лимитом.
Профиль RFC 9106 low-memory (t=3, m=64 MiB, p=4) назван явно, а не взят
умолчанием argon2-cffi: обновление библиотеки не поменяет его молча. Один
хэш — десятки миллисекунд CPU и 64 MiB памяти, поэтому он считается в
потоке, а не в event loop (иначе один вход останавливал бы все запросы
процесса), и не больше `KDF_CONCURRENCY` хэшей одновременно: общий пул
потоков anyio на 40 потоков дал бы до 2,5 GiB памяти.
Пароль хэшируется целиком как UTF-8, без обрезки: bcrypt не подходит,
он режет пароль на 72 байтах, а 128 code points занимают до 512 байт.
"""
import secrets
import anyio
from anyio import to_thread
from argon2 import PasswordHasher, profiles
from argon2.exceptions import VerifyMismatchError
class Passwords:
def __init__(self, concurrency: int) -> None:
self._hasher = PasswordHasher.from_parameters(profiles.RFC_9106_LOW_MEMORY)
self._limiter = anyio.CapacityLimiter(concurrency)
# хэш для неизвестного username; считает lifespan при старте
self._dummy_hash: str | None = None
async def hash(self, password: str) -> str:
"""Строка Argon2id с параметрами и солью."""
return await to_thread.run_sync(
self._hasher.hash,
password,
limiter=self._limiter,
)
async def verify(self, *, password: str, password_hash: str | None) -> bool:
"""Подходит ли пароль к хэшу.
`password_hash=None` — пользователя нет. Пароль всё равно
проверяется, против фиктивного хэша: время ответа не выдаёт,
существует ли username.
"""
if password_hash is None:
await to_thread.run_sync(
self._matches,
await self.prepare(),
password,
limiter=self._limiter,
)
return False
return await to_thread.run_sync(
self._matches,
password_hash,
password,
limiter=self._limiter,
)
async def prepare(self) -> str:
"""Фиктивный хэш, один на процесс.
Lifespan вызывает его при старте: иначе первый вход с неизвестным
username считал бы хэш и проверку — вдвое дольше неверного пароля.
"""
if self._dummy_hash is None:
self._dummy_hash = await self.hash(secrets.token_urlsafe(16))
return self._dummy_hash
def _matches(self, password_hash: str, password: str) -> bool:
# повреждённый хэш (InvalidHashError) — дефект, а не неверный пароль
try:
return self._hasher.verify(password_hash, password)
except VerifyMismatchError:
return False
+93
View File
@@ -0,0 +1,93 @@
# src/services/ — бизнес-логика
## Правила
- Класс на домен: `UserService`, `SessionService`, `ChatService`,
`MessageService`. Конструктор принимает `Storage` (Protocol), не
реализацию; `UserService` и `SessionService` — ещё `Passwords`,
`SessionService` — срок сессии. Сервис создаётся на запрос фабрикой из
`api/deps.py` (`SessionService` — ещё и `BearerBackend` в
`api/identity.py`); состояния у него нет.
- Публичные методы — `async def` и keyword-only (`*,`).
- Сервис не знает про HTTP и про SQL: не импортирует fastapi, starlette,
pydantic, sqlalchemy, `src.db`, `src.cache`; не принимает модели API и
`Request`, не возвращает словари. Вход — примитивы и `UUID`, выход —
объекты `src/domain.py`.
- Ошибки — только классы из `src/errors.py`. `Unavailable` из хранилища
сервис не ловит: 503 должен дойти до клиента.
- Проверка доступа к чату — одна функция `access.chat_of_member()`.
Сервисы не вызывают друг друга: общий код — в функции модуля
`access.py` или новом модуле рядом.
- `id` и `created_at` сервис не назначает: это делает хранилище внутри
своей транзакции.
## Пароли и сессии
- Пароль хэшируется `Passwords.hash()` (Argon2id в потоке, лимит
`KDF_CONCURRENCY`) **до** обращения к БД: соединение пула не ждёт KDF.
- Вход (`SessionService.login`) — две операции хранилища: чтение хэша
(своя транзакция закрыта до KDF), проверка пароля вне БД, затем
создание сессии. Неизвестный username проверяется против фиктивного
хэша: время ответа не выдаёт, есть ли пользователь. Ошибка одна —
`InvalidCredentials`.
- Токен — `secrets.token_urlsafe(32)`; в хранилище уходит только
`hash_token(token)` (SHA-256). Токен возвращается клиенту один раз
(`IssuedSession`) и больше нигде не живёт.
- `authenticate` — один запрос хранилища по хэшу токена; нет токена или
сессии — `Unauthorized`. Срок не продлевается.
- `revoke` удаляет только текущую сессию; повторный выход тем же токеном
до сервиса не дойдёт (401 в middleware).
## Отправка с ключом идемпотентности (лаба 3)
- `MessageService(storage, key_ttl=IDEMPOTENCY_TTL_SECONDS)`;
`send(chat_id, sender_id, text, idempotency_key)`.
- Порядок: сессию уже проверил middleware, ключ и тело — схема ручки;
здесь членство (`chat_of_member` → `NotFound`, 404), затем один вызов
`storage.create_message(..., key, request_hash, key_ttl)`. Повтор
проходит членство и сессию заново: посторонний с чужим ключом — 404,
отозванный токен — 401.
- `request_hash(text=...)` — SHA-256 канонического JSON тела
(`sort_keys`, без пробелов, UTF-8), собранного из **разобранных** полей:
другая запись того же JSON — тот же хэш. Новое поле тела (с лабы 4 —
`attachment_ids`) добавляется сюда со значением по умолчанию, иначе
отсутствующее поле и явное значение по умолчанию дадут разные хэши.
- Решение «новое / повтор / 409», срок ключа и атомарность — в
хранилище, одной транзакцией (`storage/AGENTS.md`). Сервис не держит ни
ключей, ни результатов в памяти процесса: повтор может прийти на другую
реплику.
- Лог: `message created …` или `message replayed …` с `message_id`,
`chat_id`, `length`, `replayed`; ключ и текст — никогда.
## Что проверяет сервис, а что — другие
| Правило | Где |
|---|---|
| форма тела, длины, пустые строки, лишние поля, длина пароля | `api/schemas.py` |
| формат Basic, длина пароля при входе | `api/deps.py` (`parse_basic`) |
| дубликаты в `member_ids`, вызывающий в списке | `ChatService.create` |
| участники существуют | хранилище (`create_chat`, в той же транзакции) |
| username уникален | хранилище (`create_user`, уникальный индекс) |
| пользователь — участник чата (GET чата, история, отправка) | `access.chat_of_member` (карточка из кэша или БД) |
| отправитель — участник (страховка) | внешний ключ `messages → chat_members` |
| `Idempotency-Key` есть и по шаблону | схема ручки (`api/routes/messages.py`) |
| повтор того же тела / другое тело / срок ключа | хранилище (`create_message`, одна транзакция) |
| курсор разбирается и относится к этому списку | `pagination.decode_cursor` из сервиса |
| пароль верный, сессия действует | `SessionService` |
## Логи
- Логгер модуля: `log = get_logger(__name__)`.
- `info` на каждое изменение состояния (пользователь, сессия, чат,
сообщение созданы; сессия отозвана) и на отказ по бизнес-правилу
(username занят, неверные участники); `warning` — неудачный вход.
Чтения не логируются: access-строку и так пишет middleware.
- В строке — id и счётчики: `user_id=`, `session_id=`, `chat_id=`,
`message_id=`, `members=`, `length=`, `ttl=`. Никогда — `text`,
`display_name`, `title`, `username`, пароль, токен и их хэши.
## Тесты
Новое правило сервиса — тест в `student-tests/` через HTTP (статус и
форма ошибки). Юнит-тесты сервиса с подменой хранилища допустимы, но
не заменяют HTTP-тест.
+11
View File
@@ -0,0 +1,11 @@
from src.services.chats import ChatService
from src.services.messages import MessageService
from src.services.sessions import SessionService
from src.services.users import UserService
__all__ = [
"ChatService",
"MessageService",
"SessionService",
"UserService",
]
+21
View File
@@ -0,0 +1,21 @@
"""Проверка доступа к чату — общая для сервисов чатов и сообщений."""
from uuid import UUID
from src.domain import Chat
from src.errors import NotFound
from src.storage import Storage
async def chat_of_member(storage: Storage, *, chat_id: UUID, user_id: UUID) -> Chat:
"""Чат, если пользователь в нём состоит; иначе `NotFound`.
Несуществующий и чужой чат неразличимы: 404 не раскрывает, что чат
есть. Состав чата после создания не меняется, поэтому результат
проверки (в том числе по карточке из кэша) не устаревает до конца
запроса.
"""
chat = await storage.get_chat(chat_id)
if chat is None or user_id not in chat.member_ids:
raise NotFound
return chat
+56
View File
@@ -0,0 +1,56 @@
from collections.abc import Sequence
from uuid import UUID
from src.domain import Chat, Page
from src.errors import InvalidMembers
from src.log import get_logger
from src.pagination import chat_list_scope, decode_cursor, make_page
from src.services.access import chat_of_member
from src.storage import Storage
log = get_logger(__name__)
class ChatService:
def __init__(self, storage: Storage) -> None:
self._storage = storage
async def create(
self,
*,
creator_id: UUID,
title: str,
member_ids: Sequence[UUID],
) -> Chat:
if len(set(member_ids)) != len(member_ids):
log.info("chat rejected: duplicate members count=%d", len(member_ids))
raise InvalidMembers
if creator_id not in member_ids:
log.info("chat rejected: creator is not a member")
raise InvalidMembers
try:
chat = await self._storage.create_chat(title=title, member_ids=member_ids)
except InvalidMembers:
log.info("chat rejected: unknown members")
raise
log.info(
"chat created chat_id=%s members=%d",
chat.id,
len(chat.member_ids),
)
return chat
async def get(self, *, chat_id: UUID, user_id: UUID) -> Chat:
return await chat_of_member(self._storage, chat_id=chat_id, user_id=user_id)
async def list_for(
self,
*,
user_id: UUID,
limit: int,
cursor: str | None,
) -> Page[Chat]:
scope = chat_list_scope(user_id)
after = decode_cursor(cursor, scope)
rows = await self._storage.list_chats_of(user_id, after=after, limit=limit + 1)
return make_page(rows, limit=limit, scope=scope)
+87
View File
@@ -0,0 +1,87 @@
import hashlib
import json
from datetime import timedelta
from uuid import UUID
from src.domain import Message, Page
from src.log import get_logger
from src.pagination import decode_cursor, history_scope, make_page
from src.services.access import chat_of_member
from src.storage import Storage
log = get_logger(__name__)
def request_hash(*, text: str) -> bytes:
"""SHA-256 канонического JSON тела отправки.
Тело собирается из уже разобранных полей: пробелы, `\\u`-экранирование
и порядок ключей исходного JSON на хэш не влияют — это «тот же JSON»
из контракта. Новое поле тела (с лабы 4 — `attachment_ids`)
добавляется сюда со значением по умолчанию: отсутствующее поле должно
давать тот же хэш, что явное значение по умолчанию.
"""
canonical = json.dumps(
{"text": text},
ensure_ascii=False,
sort_keys=True,
separators=(",", ":"),
)
return hashlib.sha256(canonical.encode()).digest()
class MessageService:
def __init__(self, storage: Storage, *, key_ttl: int) -> None:
self._storage = storage
self._key_ttl = timedelta(seconds=key_ttl)
async def send(
self,
*,
chat_id: UUID,
sender_id: UUID,
text: str,
idempotency_key: str,
) -> Message:
"""Отправка с ключом идемпотентности.
Порядок проверок: сессию уже проверил middleware (401), ключ и
тело — схема ручки (400), здесь членство (404) и ключ (409).
Повтор проходит членство заново, как и проверку сессии.
"""
# членство — по карточке чата (из кэша, если она там есть); состав
# чата не меняется, а внешние ключи сообщения и ключа — страховка
await chat_of_member(self._storage, chat_id=chat_id, user_id=sender_id)
sent = await self._storage.create_message(
chat_id=chat_id,
sender_id=sender_id,
text=text,
key=idempotency_key,
request_hash=request_hash(text=text),
key_ttl=self._key_ttl,
)
# ни текст, ни ключ в лог не пишутся: ключ выбирает клиент, в нём
# может оказаться что угодно; повтор виден по replayed
log.info(
"message %s message_id=%s chat_id=%s length=%d replayed=%s",
"replayed" if sent.replayed else "created",
sent.message.id,
chat_id,
len(text),
str(sent.replayed).lower(),
)
return sent.message
async def history(
self,
*,
chat_id: UUID,
user_id: UUID,
limit: int,
cursor: str | None,
) -> Page[Message]:
await chat_of_member(self._storage, chat_id=chat_id, user_id=user_id)
scope = history_scope(chat_id)
after = decode_cursor(cursor, scope)
rows = await self._storage.list_messages(chat_id, after=after, limit=limit + 1)
return make_page(rows, limit=limit, scope=scope)
+93
View File
@@ -0,0 +1,93 @@
"""Вход по паролю, проверка Bearer-токена, выход.
Токен — `secrets.token_urlsafe(32)`: 256 бит случайности, ничего не
кодирует (не username, не UUID, не JWT). В БД хранится только SHA-256
токена: быстрого хэша достаточно, перебирать 256 бит нечего. Медленный
KDF нужен паролю, который выбирает человек.
Срок сессии фиксируется при входе (`SESSION_TTL_SECONDS`). Ни запросы,
ни рестарт его не продлевают. Каждый запрос — поиск сессии в PostgreSQL,
без кэша: отзыв действует мгновенно.
"""
import hashlib
import secrets
from datetime import timedelta
from uuid import UUID
from src.constants import SESSION_TOKEN_BYTES
from src.domain import Identity, IssuedSession
from src.errors import InvalidCredentials, Unauthorized
from src.log import get_logger
from src.passwords import Passwords
from src.storage import Storage
log = get_logger(__name__)
def hash_token(token: str) -> bytes:
"""SHA-256 токена: по нему ищется сессия, сам токен не хранится."""
return hashlib.sha256(token.encode()).digest()
class SessionService:
def __init__(self, storage: Storage, passwords: Passwords, *, ttl: int) -> None:
self._storage = storage
self._passwords = passwords
self._ttl = timedelta(seconds=ttl)
async def login(self, *, username: str, password: str) -> IssuedSession:
"""Проверка пароля и новая сессия.
Две операции хранилища: чтение хэша закрывает свою транзакцию до
KDF, поэтому соединение пула не ждёт хэш и очередь лимита.
Пароли и пользователи не меняются: между операциями проверять
нечего.
"""
credentials = await self._storage.get_credentials(username)
# неизвестный username проверяется против фиктивного хэша: время
# ответа то же, что у неверного пароля
valid = await self._passwords.verify(
password=password,
password_hash=credentials.password_hash if credentials else None,
)
if credentials is None or not valid:
# без username и пароля: по журналу не перебрать имена
log.warning("login failed")
raise InvalidCredentials
token = secrets.token_urlsafe(SESSION_TOKEN_BYTES)
session = await self._storage.create_session(
user_id=credentials.user.id,
token_hash=hash_token(token),
ttl=self._ttl,
)
log.info(
"session created user_id=%s session_id=%s ttl=%ds",
session.user_id,
session.id,
self._ttl.total_seconds(),
)
return IssuedSession(
token=token,
expires_at=session.expires_at,
user=credentials.user,
)
async def authenticate(self, *, token: str | None) -> Identity:
"""Действующая сессия по Bearer-токену; иначе `Unauthorized`.
Недоступность БД сюда не превращается: `Unavailable` идёт дальше
(503) — отказ хранилища не делает токен недействительным и не
пропускает запрос как анонимный.
"""
if not token:
raise Unauthorized
identity = await self._storage.get_identity(hash_token(token))
if identity is None:
raise Unauthorized
return identity
async def revoke(self, *, session_id: UUID) -> None:
deleted = await self._storage.delete_session(session_id)
# False — параллельный выход тем же токеном уже удалил сессию
log.info("session revoked session_id=%s already=%s", session_id, not deleted)
+30
View File
@@ -0,0 +1,30 @@
from src.domain import User
from src.errors import UsernameTaken
from src.log import get_logger
from src.passwords import Passwords
from src.storage import Storage
log = get_logger(__name__)
class UserService:
def __init__(self, storage: Storage, passwords: Passwords) -> None:
self._storage = storage
self._passwords = passwords
async def register(
self, *, username: str, display_name: str, password: str
) -> User:
# KDF до обращения к БД: соединение пула не ждёт хэш
password_hash = await self._passwords.hash(password)
try:
user = await self._storage.create_user(
username=username,
display_name=display_name,
password_hash=password_hash,
)
except UsernameTaken:
log.info("registration rejected: username taken")
raise
log.info("user registered user_id=%s", user.id)
return user
+108
View File
@@ -0,0 +1,108 @@
# src/storage/ — хранилище
`base.py` — `Storage` (Protocol): что сервисы могут просить у слоя
данных. `postgres.py` — `PostgresStorage`, источник истины.
`cached.py` — `CachedStorage`: тот же интерфейс, карточка чата через
Valkey, остальное — делегирование в PostgreSQL. `tables.py` — схема в
SQLAlchemy Core для запросов и `alembic check`. Собирает цепочку
`main.py`: `CachedStorage(PostgresStorage(db), cache)`.
## Инварианты `PostgresStorage` (атомарность и гонки — рубрика «4»)
1. **Один публичный метод — одна транзакция** `self._db.transaction()`:
проверка → назначение `id`/`created_at` → все вставки → commit до
возврата. 201 уходит клиенту только после commit. Исключение внутри —
откат целиком: чат не останется без участников (проверяет
`test_members_failure_rolls_back_chat`).
2. **Гонки закрывают ограничения PostgreSQL**, а не «сначала SELECT,
потом INSERT»: username — `INSERT ... ON CONFLICT (username) DO
NOTHING RETURNING` (пустой RETURNING → `UsernameTaken`); отправитель
— составной внешний ключ `(chat_id, sender_id) → chat_members`
(нарушение 23503 → `NotFound`). Явных блокировок нет: пользователи и
участники не меняются и не удаляются.
3. **`created_at` — `self._clock.now()`** перед вставкой; у участника —
копия времени чата (по ней keyset списка чатов). Время БД (`now()`)
не используется: порядок, который видит клиент, зависит от одних
часов.
4. **Запросы — SQLAlchemy Core с параметрами** (`select`, `insert`,
`pg_insert`, `tuple_`). SQL из f-строк и конкатенации запрещён;
`text()` — только без пользовательских значений.
5. **Keyset без OFFSET и count(\*)**: `WHERE chat_id = :id AND
(created_at, id) > (:t, :i) ORDER BY created_at, id LIMIT :n` по
индексу `ix_messages_chat_id_created_at_id`; список чатов — по
`ix_chat_members_user_id_created_at_chat_id`. Страница не читает
историю до курсора — это доказали планы `EXPLAIN (ANALYZE, BUFFERS)`
лабы 2 (её репозиторий, `evidence/bench/`).
6. **Хранилище бросает доменные ошибки** там, где сработало
ограничение: `UsernameTaken`, `InvalidMembers` (участника нет),
`NotFound` (внешний ключ сообщения или ключа идемпотентности),
`IdempotencyConflict` (ключ занят другим телом). Бизнес-правил
(членство, дубликаты в запросе) здесь нет — они в сервисах.
7. **Отказ базы — не здесь**: `Db.transaction()` (`src/db.py`) переводит
недоступность (остановлен, завис, пул исчерпан, `statement_timeout`,
обрыв) в `Unavailable` и пишет одну строку `warning`. Остальные
`DBAPIError` (нарушенный `CHECK`, синтаксис) — дефект, 500.
8. Хранилище не логирует и не импортирует `src.log`, fastapi, сервисы и
API. Наружу — только объекты `src/domain.py`, не `Row`.
## Отправка с ключом идемпотентности (`create_message`, лаба 3)
Одна транзакция, ключ — **раньше** сообщения:
1. Захват ключа одним выражением: `INSERT INTO idempotency_keys … ON
CONFLICT (user_id, chat_id, key) DO UPDATE SET request_hash,
message_id, created_at WHERE idempotency_keys.created_at < now − ttl
RETURNING message_id`. RETURNING не пуст — ключ новый или просроченный
(заменён тем же выражением, без DELETE и второй гонки); пуст — ключ
действует, а его строка заблокирована до конца транзакции.
2. Захватили — вставка сообщения с тем же `message_id`; внешний ключ
ключа на сообщение `DEFERRABLE INITIALLY DEFERRED` проверяется при
commit. Итог — `SentMessage(message, replayed=False)`.
3. Не захватили — чтение сохранённого (`request_hash` + сообщение через
JOIN). Хэш совпал — `SentMessage(сохранённое, replayed=True)`: тот же
`id` и `created_at`, ничего не пишется. Не совпал —
`IdempotencyConflict`, откат снимает блокировку.
Гонки: одновременные запросы с одним ключом (в том числе с разных
реплик) ждут друг друга на уникальном индексе; второй после commit
первого видит его строку и отдаёт повтор. Сбой до commit (отказ БД,
ошибка вставки сообщения) откатывает и ключ, и сообщение: транзиентная
ошибка результатом не фиксируется, повтор с тем же ключом безопасен.
Внешние ключи `(chat_id, автор) → chat_members` у ключа и сообщения —
страховка членства (нарушение → `NotFound`). Срок ключа считается по
часам приложения (`utc_now()`), как срок сессии. Просроченные ключи не
удаляются сами: занятый заново ключ заменяется, остальные копятся
(уборка — `DELETE … WHERE created_at < …` по индексу; ограничение в
`REPORT.md`). Ключи — только в PostgreSQL: в кэш их не класть.
## `CachedStorage` (кэш Valkey, уровень «4»)
- Кэшируется только неизменяемое — карточка чата (`id`, `title`,
`member_ids` в порядке создания, `created_at`), JSON под ключом
`messenger:v1:<имя базы>:chat:<id>`. Сессии, история и списки — нет:
logout должен действовать мгновенно, история меняется с каждой записью.
- Чтение: Valkey → при промахе PostgreSQL и запись в кэш. Отсутствующий
чат не кэшируется. Новый чат пишется в кэш **после** commit.
- Инвалидации нет: контракт не меняет и не удаляет чаты. Правка базы в
обход API (восстановление из backup) требует `FLUSHALL` после неё.
- Отказ Valkey — промах (`src/cache.py`): ответ тот же, из PostgreSQL.
- Новый метод `Storage` — делегирование здесь обязательно: класс
реализует протокол целиком, явными методами.
## Изменение интерфейса
Новый метод — сначала в `Storage` (`base.py`) с докстрингом: что
атомарно и какие ошибки, затем реализация в `postgres.py` (одна
транзакция), делегирование в `cached.py`. Сигнатура — только `domain`,
`UUID`, `SortKey`, `timedelta`, примитивы. Новая колонка, индекс,
ограничение — сначала в `tables.py` и новой ревизии
(`migrations/AGENTS.md`), `alembic check` без расхождений.
## Проверка
`make test-isolated` (в том числе `test_race.py`: 100 сообщений от 10
клиентов, гонка регистрации и гонка одного ключа через реплики) и `make
failure-checks` (откат чата и ключа, отказы БД и Valkey, пул, срок
ключа). Правка запроса истории, записи или индексов — ещё `make
bench-scaling-quick`: стоимость на запрос видна в `runs.csv`
(`db_cpu_us_per_req`).
+9
View File
@@ -0,0 +1,9 @@
from src.storage.base import Storage
from src.storage.cached import CachedStorage
from src.storage.postgres import PostgresStorage
__all__ = [
"CachedStorage",
"PostgresStorage",
"Storage",
]
+120
View File
@@ -0,0 +1,120 @@
"""Интерфейс хранилища: что сервисы могут просить у слоя данных.
Сервисы зависят от этого протокола, а не от реализации. Реализация —
`PostgresStorage` (`postgres.py`), поверх неё — `CachedStorage`
(`cached.py`) с кэшем карточек чатов в Valkey.
Каждый метод — одна атомарная операция: одна транзакция PostgreSQL. Id и
`created_at` назначает хранилище в той же операции, что и вставку, как
это делал бы `DEFAULT` в базе данных. Недоступность PostgreSQL —
`Unavailable` из любого метода.
"""
from collections.abc import Sequence
from datetime import timedelta
from typing import Protocol
from uuid import UUID
from src.domain import (
Chat,
Credentials,
Identity,
Message,
SentMessage,
Session,
User,
)
from src.pagination import SortKey
class Storage(Protocol):
async def ping(self) -> None:
"""Хранилище может обслуживать запросы; иначе `Unavailable`."""
...
async def create_user(
self,
*,
username: str,
display_name: str,
password_hash: str,
) -> User:
"""Новый пользователь; занятый username — `UsernameTaken`."""
...
async def get_credentials(self, username: str) -> Credentials | None:
"""Пользователь и хэш пароля для входа; нет такого — `None`."""
...
async def create_session(
self,
*,
user_id: UUID,
token_hash: bytes,
ttl: timedelta,
) -> Session:
"""Новая сессия; срок `created_at + ttl` фиксируется сейчас."""
...
async def get_identity(self, token_hash: bytes) -> Identity | None:
"""Действующая сессия по хэшу токена вместе с владельцем.
Неизвестный, истёкший и отозванный токен — одинаково `None`.
"""
...
async def delete_session(self, session_id: UUID) -> bool:
"""Отзыв; `False` — сессию уже удалил параллельный запрос."""
...
async def create_chat(self, *, title: str, member_ids: Sequence[UUID]) -> Chat:
"""Чат и все его участники — одной транзакцией.
Хотя бы один участник не существует — `InvalidMembers`, ничего не
создаётся. Сбой посреди операции откатывает и чат, и участников.
"""
...
async def get_chat(self, chat_id: UUID) -> Chat | None: ...
async def list_chats_of(
self,
user_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Chat]:
"""До `limit` чатов пользователя строго после ключа `after`."""
...
async def create_message(
self,
*,
chat_id: UUID,
sender_id: UUID,
text: str,
key: str,
request_hash: bytes,
key_ttl: timedelta,
) -> SentMessage:
"""Отправка с ключом идемпотентности — одной транзакцией.
Ключ `(sender_id, chat_id, key)` свободен или старше `key_ttl` —
ключ и новое сообщение фиксируются вместе. Ключ занят тем же
`request_hash` — прежнее сообщение (`replayed=True`), ничего не
пишется; другим — `IdempotencyConflict`. Конкурентные запросы с
одним ключом (с любых реплик) дают одно сообщение. Чата нет или
автор не участник — `NotFound`. Сбой до commit не оставляет ни
ключа, ни сообщения: повтор с тем же ключом безопасен.
"""
...
async def list_messages(
self,
chat_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Message]:
"""До `limit` сообщений чата строго после ключа `after`."""
...
+177
View File
@@ -0,0 +1,177 @@
"""Хранилище с кэшем карточек чатов в Valkey (уровень «4»).
`CachedStorage` реализует тот же `Storage` поверх `PostgresStorage`:
сервисы не знают, есть ли кэш. Кэшируется только карточка чата — `id`,
`title`, `member_ids` в порядке создания, `created_at`. Её читают три
самых частых запроса: `GET /chats/{id}`, `POST .../messages` и
`GET .../messages` (проверка членства).
- Источник истины — PostgreSQL. Чтение: Valkey → при промахе PostgreSQL
и запись в кэш (cache-aside). Чата нет — в кэш ничего не пишется.
- Новый чат пишется в кэш после commit: откат создания не оставит в кэше
чата, которого нет в базе.
- Инвалидации нет: по контракту чат и участники после создания не
меняются и не удаляются. Граница допущения — правка базы в обход API
(восстановление из backup): после неё кэш очищают `FLUSHALL`.
- Срок записи `CACHE_CHAT_TTL` ограничивает память, а не свежесть;
чтения его не продлевают.
- Сессии, история и списки чатов не кэшируются: сессию должен мгновенно
отзывать logout, история меняется с каждой записью.
- Отказ Valkey — промах (`src/cache.py`): ответ тот же, из PostgreSQL.
Ключ — `messenger:v1:<имя базы>:chat:<chat_id>`, значение — JSON.
"""
import json
from collections.abc import Sequence
from datetime import timedelta
from uuid import UUID
from src.cache import Cache
from src.clock import from_rfc3339, to_rfc3339
from src.constants import CACHE_KEY_PREFIX
from src.domain import (
Chat,
Credentials,
Identity,
Message,
SentMessage,
Session,
User,
)
from src.pagination import SortKey
from src.storage.base import Storage
def chat_key(namespace: str, chat_id: UUID) -> str:
return f"{CACHE_KEY_PREFIX}:{namespace}:chat:{chat_id}"
def dump_chat(chat: Chat) -> str:
return json.dumps(
{
"id": str(chat.id),
"title": chat.title,
"member_ids": [str(member_id) for member_id in chat.member_ids],
"created_at": to_rfc3339(chat.created_at),
},
ensure_ascii=False,
separators=(",", ":"),
)
def load_chat(value: str) -> Chat:
data = json.loads(value)
return Chat(
id=UUID(data["id"]),
title=data["title"],
member_ids=tuple(UUID(member_id) for member_id in data["member_ids"]),
created_at=from_rfc3339(data["created_at"]),
)
class CachedStorage:
def __init__(self, storage: Storage, cache: Cache, *, chat_ttl: int) -> None:
self._storage = storage
self._cache = cache
self._chat_ttl = chat_ttl
async def get_chat(self, chat_id: UUID) -> Chat | None:
key = chat_key(self._cache.namespace, chat_id)
cached = await self._cache.get(key)
if cached is not None:
return load_chat(cached)
chat = await self._storage.get_chat(chat_id)
if chat is not None:
await self._cache.set(key, dump_chat(chat), ttl=self._chat_ttl)
return chat
async def create_chat(self, *, title: str, member_ids: Sequence[UUID]) -> Chat:
chat = await self._storage.create_chat(title=title, member_ids=member_ids)
# чат уже зафиксирован: следующее чтение карточки попадёт в кэш
await self._cache.set(
chat_key(self._cache.namespace, chat.id),
dump_chat(chat),
ttl=self._chat_ttl,
)
return chat
# --- остальное — без кэша -----------------------------------------------
async def ping(self) -> None:
# кэш не критичен: без него обязательный путь идёт в PostgreSQL
await self._storage.ping()
async def create_user(
self,
*,
username: str,
display_name: str,
password_hash: str,
) -> User:
return await self._storage.create_user(
username=username,
display_name=display_name,
password_hash=password_hash,
)
async def get_credentials(self, username: str) -> Credentials | None:
return await self._storage.get_credentials(username)
async def create_session(
self,
*,
user_id: UUID,
token_hash: bytes,
ttl: timedelta,
) -> Session:
return await self._storage.create_session(
user_id=user_id,
token_hash=token_hash,
ttl=ttl,
)
async def get_identity(self, token_hash: bytes) -> Identity | None:
return await self._storage.get_identity(token_hash)
async def delete_session(self, session_id: UUID) -> bool:
return await self._storage.delete_session(session_id)
async def list_chats_of(
self,
user_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Chat]:
return await self._storage.list_chats_of(user_id, after=after, limit=limit)
async def create_message(
self,
*,
chat_id: UUID,
sender_id: UUID,
text: str,
key: str,
request_hash: bytes,
key_ttl: timedelta,
) -> SentMessage:
# ключи идемпотентности — только в PostgreSQL, в одной транзакции с
# сообщением: кэш отказывает и теряет данные, ему их не доверить
return await self._storage.create_message(
chat_id=chat_id,
sender_id=sender_id,
text=text,
key=key,
request_hash=request_hash,
key_ttl=key_ttl,
)
async def list_messages(
self,
chat_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Message]:
return await self._storage.list_messages(chat_id, after=after, limit=limit)
+386
View File
@@ -0,0 +1,386 @@
"""Хранилище лабы 2: PostgreSQL — источник истины.
Каждый публичный метод — одна транзакция `Db.transaction()`: проверка,
назначение id и времени, вставки — и commit до возврата. Ответ 201 уходит
клиенту только после commit. Ошибка внутри — откат целиком: создание
чата не оставит ни чата без участников, ни участников без чата.
Защиту от гонок дают ограничения PostgreSQL, а не проверки «сначала
SELECT, потом INSERT»: уникальность username — `ON CONFLICT DO NOTHING`
по уникальному индексу, участник и отправитель — внешние ключи. Запросы
— SQLAlchemy Core с параметрами, SQL из строк не собирается.
Хранилище бросает доменные ошибки там, где сработало ограничение:
`UsernameTaken` (уникальность), `InvalidMembers` (участника нет),
`NotFound` (внешний ключ сообщения или ключа идемпотентности),
`IdempotencyConflict` (ключ занят другим телом). Бизнес-правил
(членство, дубликаты в запросе) здесь нет — они в сервисах. Хранилище
не логирует: отказ базы пишет в журнал `Db.transaction()`.
"""
from collections.abc import Sequence
from datetime import timedelta
from uuid import UUID, uuid4
from sqlalchemy import Row, func, insert, select, tuple_
from sqlalchemy import delete as sa_delete
from sqlalchemy import exc as sa_exc
from sqlalchemy.dialects.postgresql import aggregate_order_by
from sqlalchemy.dialects.postgresql import insert as pg_insert
from src.clock import MonotonicClock, utc_now
from src.db import Db
from src.domain import (
Chat,
Credentials,
Identity,
Message,
SentMessage,
Session,
User,
)
from src.errors import IdempotencyConflict, InvalidMembers, NotFound, UsernameTaken
from src.pagination import SortKey
from src.storage.tables import (
chat_members,
chats,
idempotency_keys,
messages,
sessions,
users,
)
# SQLSTATE foreign_key_violation
_FK_VIOLATION = "23503"
_USER_COLUMNS = (users.c.id, users.c.username, users.c.display_name, users.c.created_at)
# участники в порядке member_ids при создании; отдельный алиас, чтобы не
# смешаться с chat_members внешнего запроса списка чатов
_member = chat_members.alias("member")
_MEMBER_IDS = (
select(func.array_agg(aggregate_order_by(_member.c.user_id, _member.c.position)))
.where(_member.c.chat_id == chats.c.id)
.scalar_subquery()
.label("member_ids")
)
_CHAT_COLUMNS = (chats.c.id, chats.c.title, _MEMBER_IDS, chats.c.created_at)
_MESSAGE_COLUMNS = (
messages.c.id,
messages.c.chat_id,
messages.c.sender_id,
messages.c.text,
messages.c.created_at,
)
def _user(row: Row) -> User:
return User(
id=row.id,
username=row.username,
display_name=row.display_name,
created_at=row.created_at,
)
def _chat(row: Row) -> Chat:
return Chat(
id=row.id,
title=row.title,
member_ids=tuple(row.member_ids),
created_at=row.created_at,
)
def _message(row: Row) -> Message:
return Message(
id=row.id,
chat_id=row.chat_id,
sender_id=row.sender_id,
text=row.text,
created_at=row.created_at,
)
class PostgresStorage:
def __init__(self, db: Db, clock: MonotonicClock | None = None) -> None:
self._db = db
self._clock = clock or MonotonicClock()
async def ping(self) -> None:
await self._db.ping()
# --- пользователи и сессии ---------------------------------------------
async def create_user(
self,
*,
username: str,
display_name: str,
password_hash: str,
) -> User:
user = User(
id=uuid4(),
username=username,
display_name=display_name,
created_at=self._clock.now(),
)
# уникальность держит индекс: из гонки регистраций одного username
# строку вставит ровно одна, остальные получат пустой RETURNING
statement = (
pg_insert(users)
.values(
id=user.id,
username=user.username,
display_name=user.display_name,
password_hash=password_hash,
created_at=user.created_at,
)
.on_conflict_do_nothing(index_elements=[users.c.username])
.returning(users.c.id)
)
async with self._db.transaction() as connection:
inserted = (await connection.execute(statement)).first()
if inserted is None:
raise UsernameTaken
return user
async def get_credentials(self, username: str) -> Credentials | None:
statement = select(*_USER_COLUMNS, users.c.password_hash).where(
users.c.username == username,
)
async with self._db.transaction() as connection:
row = (await connection.execute(statement)).first()
if row is None:
return None
return Credentials(user=_user(row), password_hash=row.password_hash)
async def create_session(
self,
*,
user_id: UUID,
token_hash: bytes,
ttl: timedelta,
) -> Session:
created_at = self._clock.now()
session = Session(
id=uuid4(),
user_id=user_id,
expires_at=created_at + ttl,
created_at=created_at,
)
statement = insert(sessions).values(
id=session.id,
user_id=session.user_id,
token_hash=token_hash,
created_at=session.created_at,
expires_at=session.expires_at,
)
async with self._db.transaction() as connection:
await connection.execute(statement)
return session
async def get_identity(self, token_hash: bytes) -> Identity | None:
# один запрос по уникальному индексу token_hash; срок сравнивается
# по часам приложения, которые его и поставили
statement = (
select(sessions.c.id.label("session_id"), *_USER_COLUMNS)
.join_from(sessions, users, sessions.c.user_id == users.c.id)
.where(
sessions.c.token_hash == token_hash, sessions.c.expires_at > utc_now()
)
)
async with self._db.transaction() as connection:
row = (await connection.execute(statement)).first()
if row is None:
return None
return Identity(session_id=row.session_id, user=_user(row))
async def delete_session(self, session_id: UUID) -> bool:
statement = (
sa_delete(sessions)
.where(sessions.c.id == session_id)
.returning(sessions.c.id)
)
async with self._db.transaction() as connection:
deleted = (await connection.execute(statement)).first()
return deleted is not None
# --- чаты ------------------------------------------------------------------
async def create_chat(self, *, title: str, member_ids: Sequence[UUID]) -> Chat:
chat = Chat(
id=uuid4(),
title=title,
member_ids=tuple(member_ids),
created_at=self._clock.now(),
)
# member_ids без дубликатов (проверил сервис), поэтому сравнение
# числа найденных пользователей с длиной списка точное
known = (
select(func.count()).select_from(users).where(users.c.id.in_(member_ids))
)
async with self._db.transaction() as connection:
# пользователей не удаляют: проверка до вставки не устареет,
# а внешний ключ участника — страховка на уровне БД
if await connection.scalar(known) != len(member_ids):
raise InvalidMembers
await connection.execute(
insert(chats).values(
id=chat.id, title=chat.title, created_at=chat.created_at
),
)
await connection.execute(
insert(chat_members).values(
[
{
"chat_id": chat.id,
"user_id": user_id,
"position": position,
"created_at": chat.created_at,
}
for position, user_id in enumerate(chat.member_ids)
],
),
)
return chat
async def get_chat(self, chat_id: UUID) -> Chat | None:
statement = select(*_CHAT_COLUMNS).where(chats.c.id == chat_id)
async with self._db.transaction() as connection:
row = (await connection.execute(statement)).first()
return None if row is None else _chat(row)
async def list_chats_of(
self,
user_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Chat]:
# keyset по индексу (user_id, created_at, chat_id) участников: их
# created_at равен времени чата, поэтому порядок — (created_at, id)
statement = (
select(*_CHAT_COLUMNS)
.join_from(chat_members, chats, chat_members.c.chat_id == chats.c.id)
.where(chat_members.c.user_id == user_id)
.order_by(chat_members.c.created_at, chat_members.c.chat_id)
.limit(limit)
)
if after is not None:
statement = statement.where(
tuple_(chat_members.c.created_at, chat_members.c.chat_id)
> tuple_(*after),
)
async with self._db.transaction() as connection:
rows = (await connection.execute(statement)).all()
return [_chat(row) for row in rows]
# --- сообщения -------------------------------------------------------------
async def create_message(
self,
*,
chat_id: UUID,
sender_id: UUID,
text: str,
key: str,
request_hash: bytes,
key_ttl: timedelta,
) -> SentMessage:
message = Message(
id=uuid4(),
chat_id=chat_id,
sender_id=sender_id,
text=text,
created_at=self._clock.now(),
)
# захват ключа под новое сообщение — одним выражением. Ключа нет или
# он просрочен — строка вставлена или заменена, RETURNING не пуст.
# Ключ действует — RETURNING пуст, а строка заблокирована до конца
# транзакции. Конкурентный захват того же ключа (с любой реплики)
# ждёт commit или отката первой транзакции на уникальном индексе
claim = pg_insert(idempotency_keys).values(
user_id=sender_id,
chat_id=chat_id,
key=key,
request_hash=request_hash,
message_id=message.id,
created_at=message.created_at,
)
claim = claim.on_conflict_do_update(
index_elements=[
idempotency_keys.c.user_id,
idempotency_keys.c.chat_id,
idempotency_keys.c.key,
],
set_={
"request_hash": claim.excluded.request_hash,
"message_id": claim.excluded.message_id,
"created_at": claim.excluded.created_at,
},
where=idempotency_keys.c.created_at < utc_now() - key_ttl,
).returning(idempotency_keys.c.message_id)
saved = (
select(idempotency_keys.c.request_hash, *_MESSAGE_COLUMNS)
.join_from(
idempotency_keys,
messages,
messages.c.id == idempotency_keys.c.message_id,
)
.where(
idempotency_keys.c.user_id == sender_id,
idempotency_keys.c.chat_id == chat_id,
idempotency_keys.c.key == key,
)
)
try:
async with self._db.transaction() as connection:
if (await connection.execute(claim)).first() is not None:
# ключ — первым: повтор не пишет и не откатывает
# сообщение, а ссылка ключа на него проверяется при commit
await connection.execute(
insert(messages).values(
id=message.id,
chat_id=message.chat_id,
sender_id=message.sender_id,
text=message.text,
created_at=message.created_at,
),
)
return SentMessage(message=message, replayed=False)
row = (await connection.execute(saved)).one()
# другое тело с тем же ключом: транзакция откатывается,
# блокировка строки ключа снимается
if row.request_hash != request_hash:
raise IdempotencyConflict
return SentMessage(message=_message(row), replayed=True)
except sa_exc.IntegrityError as exc:
# составные внешние ключи (chat_id, автор) → участники: чата нет
# или автор в нём не состоит
if getattr(exc.orig, "sqlstate", None) == _FK_VIOLATION:
raise NotFound from None
raise
async def list_messages(
self,
chat_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Message]:
# keyset по индексу (chat_id, created_at, id), без OFFSET: страница
# не просматривает историю до курсора
statement = (
select(*_MESSAGE_COLUMNS)
.where(messages.c.chat_id == chat_id)
.order_by(messages.c.created_at, messages.c.id)
.limit(limit)
)
if after is not None:
statement = statement.where(
tuple_(messages.c.created_at, messages.c.id) > tuple_(*after),
)
async with self._db.transaction() as connection:
rows = (await connection.execute(statement)).all()
return [_message(row) for row in rows]
+204
View File
@@ -0,0 +1,204 @@
"""Схема PostgreSQL в SQLAlchemy Core: по ней пишутся запросы хранилища.
Схему в базе создают миграции (`migrations/versions/`), этот файл её
описывает для запросов и для `alembic check`: расхождение с миграциями —
дефект. Имена ограничений и индексов заданы явно, их же видно в планах
запроса (`ix_messages_chat_id_created_at_id`) и в `\\d` psql.
`CHECK` дублируют контракт: первым отвечает API (400), сработавший
`CHECK` — дефект валидации. Время назначает приложение
(`MonotonicClock`), а не `DEFAULT now()`: порядок, который видит
клиент, зависит от одних часов.
"""
from sqlalchemy import (
CheckConstraint,
Column,
DateTime,
ForeignKeyConstraint,
Index,
LargeBinary,
MetaData,
PrimaryKeyConstraint,
SmallInteger,
Table,
Text,
UniqueConstraint,
Uuid,
)
from src.constants import (
CHAT_TITLE_MAX_LENGTH,
DISPLAY_NAME_MAX_LENGTH,
IDEMPOTENCY_KEY_PATTERN,
MESSAGE_TEXT_MAX_LENGTH,
PASSWORD_HASH_PREFIX,
REQUEST_HASH_BYTES,
TOKEN_HASH_BYTES,
USERNAME_PATTERN,
)
metadata = MetaData()
def _timestamp(name: str) -> Column:
return Column(name, DateTime(timezone=True), nullable=False)
users = Table(
"users",
metadata,
Column("id", Uuid, nullable=False),
Column("username", Text, nullable=False),
Column("display_name", Text, nullable=False),
# строка Argon2id с параметрами и солью; наружу уходит только при входе
Column("password_hash", Text, nullable=False),
_timestamp("created_at"),
PrimaryKeyConstraint("id", name="pk_users"),
UniqueConstraint("username", name="uq_users_username"),
CheckConstraint(
f"username ~ '{USERNAME_PATTERN}'", name="ck_users_username_format"
),
CheckConstraint(
f"char_length(display_name) BETWEEN 1 AND {DISPLAY_NAME_MAX_LENGTH}",
name="ck_users_display_name_length",
),
# защита в глубину: открытый пароль или быстрый хэш не запишется
CheckConstraint(
f"password_hash LIKE '{PASSWORD_HASH_PREFIX}%'",
name="ck_users_password_hash_argon2id",
),
)
sessions = Table(
"sessions",
metadata,
Column("id", Uuid, nullable=False),
Column("user_id", Uuid, nullable=False),
# SHA-256 токена: по таблице действующий токен не восстановить
Column("token_hash", LargeBinary, nullable=False),
_timestamp("created_at"),
_timestamp("expires_at"),
PrimaryKeyConstraint("id", name="pk_sessions"),
ForeignKeyConstraint(["user_id"], ["users.id"], name="fk_sessions_user_id_users"),
# проверка токена на каждом запросе — поиск по этому индексу
UniqueConstraint("token_hash", name="uq_sessions_token_hash"),
CheckConstraint(
f"octet_length(token_hash) = {TOKEN_HASH_BYTES}",
name="ck_sessions_token_hash_length",
),
CheckConstraint(
"expires_at > created_at", name="ck_sessions_expires_after_created"
),
)
chats = Table(
"chats",
metadata,
Column("id", Uuid, nullable=False),
Column("title", Text, nullable=False),
_timestamp("created_at"),
PrimaryKeyConstraint("id", name="pk_chats"),
CheckConstraint(
f"char_length(title) BETWEEN 1 AND {CHAT_TITLE_MAX_LENGTH}",
name="ck_chats_title_length",
),
)
# участник чата. `position` — место в member_ids запроса: контракт отдаёт
# участников в порядке создания. `created_at` — копия времени чата: по ней
# список чатов пользователя идёт keyset-ом по индексу, без сортировки
# всех его чатов
chat_members = Table(
"chat_members",
metadata,
Column("chat_id", Uuid, nullable=False),
Column("user_id", Uuid, nullable=False),
Column("position", SmallInteger, nullable=False),
_timestamp("created_at"),
PrimaryKeyConstraint("chat_id", "user_id", name="pk_chat_members"),
ForeignKeyConstraint(
["chat_id"],
["chats.id"],
name="fk_chat_members_chat_id_chats",
),
ForeignKeyConstraint(
["user_id"],
["users.id"],
name="fk_chat_members_user_id_users",
),
UniqueConstraint("chat_id", "position", name="uq_chat_members_chat_id_position"),
CheckConstraint("position >= 0", name="ck_chat_members_position_non_negative"),
# keyset списка чатов: WHERE user_id = ... AND (created_at, chat_id) > (...)
Index(
"ix_chat_members_user_id_created_at_chat_id",
"user_id",
"created_at",
"chat_id",
),
)
messages = Table(
"messages",
metadata,
Column("id", Uuid, nullable=False),
Column("chat_id", Uuid, nullable=False),
Column("sender_id", Uuid, nullable=False),
Column("text", Text, nullable=False),
_timestamp("created_at"),
PrimaryKeyConstraint("id", name="pk_messages"),
# отправитель — участник этого чата: проверяет сама БД
ForeignKeyConstraint(
["chat_id", "sender_id"],
["chat_members.chat_id", "chat_members.user_id"],
name="fk_messages_chat_id_sender_id_chat_members",
),
CheckConstraint(
f"char_length(text) BETWEEN 1 AND {MESSAGE_TEXT_MAX_LENGTH}",
name="ck_messages_text_length",
),
# keyset истории: WHERE chat_id = ... AND (created_at, id) > (...)
# ORDER BY created_at, id LIMIT n — страница без чтения всей истории
Index("ix_messages_chat_id_created_at_id", "chat_id", "created_at", "id"),
)
# ключ идемпотентности отправки (лаба 3, ревизия 0002). Область — автор,
# чат и ключ: метод и путь у ключа один (POST сообщения). Ключ пишется в
# той же транзакции, что и сообщение, и раньше него: ссылка на сообщение
# проверяется при commit (DEFERRABLE INITIALLY DEFERRED)
idempotency_keys = Table(
"idempotency_keys",
metadata,
Column("user_id", Uuid, nullable=False),
Column("chat_id", Uuid, nullable=False),
Column("key", Text, nullable=False),
# SHA-256 канонического тела: повтор сравнивается с ним, не с текстом
Column("request_hash", LargeBinary, nullable=False),
Column("message_id", Uuid, nullable=False),
# время захвата ключа; по нему истекает срок IDEMPOTENCY_TTL_SECONDS
_timestamp("created_at"),
PrimaryKeyConstraint("user_id", "chat_id", "key", name="pk_idempotency_keys"),
# ключ бывает только у участника чата: заодно ссылки на чат и автора
ForeignKeyConstraint(
["chat_id", "user_id"],
["chat_members.chat_id", "chat_members.user_id"],
name="fk_idempotency_keys_chat_id_user_id_chat_members",
),
ForeignKeyConstraint(
["message_id"],
["messages.id"],
name="fk_idempotency_keys_message_id_messages",
deferrable=True,
initially="DEFERRED",
),
CheckConstraint(
f"key ~ '{IDEMPOTENCY_KEY_PATTERN}'",
name="ck_idempotency_keys_key_format",
),
CheckConstraint(
f"octet_length(request_hash) = {REQUEST_HASH_BYTES}",
name="ck_idempotency_keys_request_hash_length",
),
# ручная уборка просроченных ключей: DELETE ... WHERE created_at < ...
Index("ix_idempotency_keys_created_at", "created_at"),
)
+113
View File
@@ -0,0 +1,113 @@
# student-tests/ — собственные тесты
Нужны для оценки «4» (`README.md`). Лаба 1 (сохраняется): неверный
JSON, чужой чат, пустое сообщение, дубликат username, обход нескольких
страниц, гонка «100 сообщений от 10 клиентов → ровно 100 уникальных».
Лаба 2 (сохраняется): истечение сессии при коротком
`SESSION_TTL_SECONDS`, logout, неверный пароль, недоступность
PostgreSQL и Valkey; гонка регистрации одного username; откат составной
операции. Лаба 3: `X-Instance-Id` на каждом ответе; идемпотентность
отправки (повтор, 409, область ключа, порядок кодов, повтор через другую
реплику); гонка одного ключа через разные реплики; одна сессия на
разных репликах; запись видна через другую реплику; сбой записи, отказ
БД и срок ключа (проверки отказов).
Объём намеренно минимальный: обязательные сценарии рубрики и то, на чём
держится архитектура. Новый тест — когда появилось новое поведение или
найден дефект.
## Как запускаются
Все тесты — по HTTP против запущенного стенда, `src` не импортируют.
| Команда | Против чего | Что идёт |
|---|---|---|
| `make test-isolated` | отдельный проект compose `<рабочий>-isolated`: свои PostgreSQL, Valkey, volume, **HAProxy и 2 реплики**, свои пароли, образ `:lab3-test`; удаляется после прогона | `make test`, все тесты, кроме `fault` (`EXPECT_REPLICAS=2` — тесты реплик идут), `make test-failover` и `make test-persistence` на этом стенде — **обычный прогон** |
| `make failure-checks [FAULT_ARGS=-rP]` | проект `<рабочий>-failures`: два процесса API без LB — обычный и «тесный» (сроки сессии и ключа 2 с, пул 1, ожидание пула 1 с, срок операции 2 с) | только `pytest -m fault` |
| `make student-test [BASE_URL=...] [EXPECT_REPLICAS=...]` | любой запущенный стенд (по умолчанию HAProxy рабочего на `http://localhost:8080`, `EXPECT_REPLICAS` = `API_REPLICAS`) | все, кроме `fault`; оставляет данные в его базе |
Оба отдельных стенда поднимает `stand.py` (stdlib, Python 3.9+): тот же
`compose.yaml` с override `stand.compose.yml` (порты хранилищ не
публикуются, HAProxy — на выбранном свободном порту, который переживает
stop/start из `restart.sh`) и подстановками `stand.env` вместо `.env`
рабочего стенда; уборка `down -v` в `finally` и по Ctrl+C. Проверки
skeleton (`tests/smoke.py`, `tests/resilience.py`) `stand.py` вызывает
напрямую, не через make: Makefile подключает `.env` рабочего стенда, и
его пароли перекрыли бы пароли стенда в окружении hooks. Hooks
`scripts/stop-one.sh` и `scripts/restart.sh` попадают в проект стенда
через `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`. Два
прогона одного вида одновременно не запускать.
Отсюда правила:
- тест не рассчитывает на пустой сервер: пользователи — с уникальным
`username` (`helpers.register` → `unique_username`), свои чаты;
- тест не лезет во внутреннее состояние: только HTTP. Исключение —
проверки отказов: на хранилища они действуют через фикстуру `stand`
(hook `fault_hook.py`), сами docker не трогают;
- клиент — фикстура `client`; ещё независимые клиенты (своё соединение)
— фабрика `new_client()`; «тесный» API — `tight_client`;
- сколько реплик за `BASE_URL`, набор узнаёт из `EXPECT_REPLICAS`, а не
угадывает по ответам: иначе сломанный LB давал бы пропуск вместо
падения. Фикстура `replicas` пропускает тест с причиной «one API
process», если `EXPECT_REPLICAS` < 2 (стенд отказов, `make run`); при
≥ 2 и одном увиденном `X-Instance-Id` тест падает (`assert_replicas`).
## Как писать
- Файлы: `test_rubric.py` — обязательные сценарии рубрики, `test_race.py`
— гонки (сообщения, регистрация, один ключ), `test_auth.py` — пароль,
Basic, Bearer, выход, схемы в OpenAPI, `test_cache.py` — что кэш не
меняет ответы, `test_request_id.py` — `X-Request-Id` и `X-Instance-Id`
на ответах всех видов, `test_idempotency.py` — `Idempotency-Key`,
`test_balancing.py` — реплики за LB, `test_failures.py` — проверки
отказов (маркер `fault` на весь модуль).
- Хелперы — `helpers.py`: `register`, `login`, `logout`, `create_chat`,
`send`, `read_history`, `chat_ids`, `public`, `assert_error`,
`assert_unauthorized`, `new_key`, `instance_id`, `assert_replicas`.
Идентификация — только `headers()` (Bearer); заголовки руками — только
в `test_auth.py`.
- **Отправка сообщения — только `send()`**: по умолчанию новый
`Idempotency-Key`, `key=None` — без заголовка, строка или байты — этот
ключ. Прямой POST без ключа получил бы 400 раньше проверки, которую
хочет увидеть тест (404 постороннему, 401 после выхода).
- Ошибку проверять через `assert_error(resp, status, code)` (статус,
`code`, форма, `request_id` = `X-Request-Id`, непустой
`X-Instance-Id`), 401 — через `assert_unauthorized(resp, …)`.
- Тест гонок — настоящая параллельность: потоки за `threading.Barrier`,
у каждого свой клиент, соединение открыто до барьера; ≥ 2 запросов в
полёте одновременно. Гонке «через разные реплики» ещё нужна пара
пересекающихся по времени ответов с разными `X-Instance-Id`.
- `sleep` — только там, где ждут срок (сессия, ключ, окно пропуска
кэша), с запасом 0,3–1 с.
- Проверка отказа, которая останавливает или замораживает хранилище, —
в `with outage(stand, ...)`: в `finally` хранилище возвращается.
Длительности печатаются (`print`), чтобы `FAULT_ARGS=-rP` дал числа.
- Hook `fault_hook.py` работает только с проектом из `FAULT_PROJECT`
(оканчивается на `-failures`). Действия: `stop`/`start`/`pause`/
`unpause` хранилищ, `flush-cache`, `cache-hits`, `cache-has-chat`,
`fail-members`/`clear-fail-members`, `count-chats`,
`fail-messages`/`clear-fail-messages` (вставка сообщения падает уже
после вставки ключа), `count-keys`. Формат ключа кэша в нём — копия
`CACHE_KEY_PREFIX`.
- Пароли и токены тестов синтетические, не печатаются и не попадают в
`evidence/`.
## Нельзя
- Править `tests/` (публичные проверки skeleton) или класть туда свои
тесты.
- Ослаблять проверки, ставить `skip`/`xfail`, удалять тест, чтобы
прогон стал зелёным (корневой `AGENTS.md`, разделы 2 и 9).
- Мокать хранилище или сервисы: тесты проверяют систему целиком.
- Запускать `pytest -m fault` против рабочего стенда: conftest
остановит прогон с кодом 2 без hook, а hook откажется работать с
рабочим проектом.
## После изменения тестов
1. `make fmt && make lint`.
2. `make test-isolated`; изменились проверки отказов — `make
failure-checks`.
3. Изменился состав или вывод — обновить `evidence/tests/` реальным
выводом и строку в `REPORT.md`.
+119
View File
@@ -0,0 +1,119 @@
"""Фикстуры собственных тестов. Все тесты — по HTTP против запущенного стенда.
`BASE_URL` (по умолчанию `http://localhost:8080`): compose-стенд
(`make up`), сервис на хосте (`make run`) или отдельный стенд
`make test-isolated`. Состояние общее и растёт от прогона к прогону:
тесты не рассчитывают на пустой сервер.
Проверки отказов (маркер `fault`) идут только на стенде
`make failure-checks`: он передаёт hook (`FAULT_HOOK`) и адрес «тесного»
API (`FAULT_TIGHT_BASE_URL`). Без них такие тесты не запускаются.
Сколько реплик за `BASE_URL`, набор узнаёт из `EXPECT_REPLICAS`, а не
угадывает по ответам: иначе сломанный LB давал бы пропуск вместо
падения. `make student-test` берёт его из `API_REPLICAS`, против одного
процесса (`make run`, стенд отказов) — 1: тестам реплик (фикстура
`replicas`) тогда нечего проверять, они пропускаются с причиной.
"""
import os
import subprocess
from collections.abc import Callable, Iterator
import httpx
import pytest
from helpers import ClientFactory
BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080").rstrip("/")
EXPECT_REPLICAS = int(os.environ.get("EXPECT_REPLICAS", "1"))
FAULT_HOOK = os.environ.get("FAULT_HOOK", "")
FAULT_TIGHT_BASE_URL = os.environ.get("FAULT_TIGHT_BASE_URL", "").rstrip("/")
FAULT_HOOK_TIMEOUT = 120
@pytest.hookimpl(trylast=True)
def pytest_collection_finish(session: pytest.Session) -> None:
"""Проверки отказов без стенда make failure-checks не запускаются.
Выход до первого теста: без hook ни одно хранилище не трогается.
"""
selected = [item for item in session.items if item.get_closest_marker("fault")]
if selected and not (FAULT_HOOK and FAULT_TIGHT_BASE_URL):
pytest.exit(
"fault checks need their stand and hook: run make failure-checks",
returncode=2,
)
@pytest.fixture(scope="session", autouse=True)
def _server_reachable() -> None:
"""Без сервера — одна понятная строка, а не десяток ошибок."""
try:
response = httpx.get(f"{BASE_URL}/health/live", timeout=2)
except httpx.HTTPError as exc:
pytest.exit(f"server is not reachable at {BASE_URL}: {exc!r}", returncode=2)
if response.status_code != 200:
pytest.exit(
f"{BASE_URL}/health/live answered {response.status_code}: "
"another service on this port?",
returncode=2,
)
@pytest.fixture
def new_client() -> Iterator[ClientFactory]:
"""Фабрика независимых клиентов: у каждого своё keep-alive соединение."""
clients: list[httpx.Client] = []
def factory() -> httpx.Client:
client = httpx.Client(base_url=BASE_URL, timeout=15)
clients.append(client)
return client
yield factory
for client in clients:
client.close()
@pytest.fixture
def client(new_client: ClientFactory) -> httpx.Client:
return new_client()
@pytest.fixture
def replicas() -> int:
"""Число реплик за BASE_URL; против одного процесса — пропуск теста."""
if EXPECT_REPLICAS < 2:
pytest.skip("one API process behind BASE_URL (EXPECT_REPLICAS=1)")
return EXPECT_REPLICAS
@pytest.fixture
def tight_client() -> Iterator[httpx.Client]:
"""API стенда отказов со сроком сессии 2 с и пулом из одного соединения."""
with httpx.Client(base_url=FAULT_TIGHT_BASE_URL, timeout=15) as client:
yield client
@pytest.fixture(scope="session")
def stand() -> Callable[..., str]:
"""Действие над стендом отказов через hook; возвращает его stdout.
`stand("stop", "postgres")` — «стенд, останови postgres». Hook —
исполняемый файл, вызов без shell, как `ACTION_SCRIPT` в
`tests/resilience.py`. Сам тест docker не трогает.
"""
def call(*args: str) -> str:
result = subprocess.run(
[FAULT_HOOK, *args],
capture_output=True,
text=True,
timeout=FAULT_HOOK_TIMEOUT,
check=False,
)
assert result.returncode == 0, f"fault hook {' '.join(args)}: {result.stderr}"
return result.stdout.strip()
return call
+251
View File
@@ -0,0 +1,251 @@
#!/usr/bin/env python3
"""Hook стенда отказов для проверок `fault` (`make failure-checks`).
Тесты вызывают его как `[FAULT_HOOK, действие, аргументы…]` без shell —
так же `tests/resilience.py` вызывает `ACTION_SCRIPT`. Сами тесты docker
не трогают. Hook работает только с проектом compose из `FAULT_PROJECT`
(его и пароли стенда передаёт `student-tests/stand.py` через окружение) и
отказывается работать с проектом рабочего стенда.
Действия:
stop|start|pause|unpause postgres|valkey
flush-cache FLUSHALL
cache-hits keyspace_hits из INFO stats
cache-has-chat <chat_id> EXISTS ключа карточки: 0 или 1
fail-members <title> вставка участников чата с этим названием
падает (триггер в базе стенда отказов)
clear-fail-members убрать триггер
count-chats <title> число чатов с этим названием
fail-messages <text> вставка сообщения с этим текстом падает —
уже после вставки ключа идемпотентности
clear-fail-messages убрать триггер
count-keys <chat_id> число ключей идемпотентности чата
Пароли не печатает: valkey-cli берёт пароль из VALKEYCLI_AUTH
контейнера, psql работает от POSTGRES_USER контейнера. Только stdlib,
Python 3.9+.
"""
from __future__ import annotations
import os
import subprocess
import sys
import time
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
COMPOSE_FILES = (ROOT / "compose.yaml", ROOT / "student-tests" / "stand.compose.yml")
ENV_FILE = ROOT / "student-tests" / "stand.env"
PROJECT_SUFFIX = "-failures"
SERVICES = ("postgres", "valkey")
# та же проверка, что healthcheck сервиса в compose.yaml
PROBES = {
"postgres": 'pg_isready -q -h 127.0.0.1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"',
"valkey": 'test "$(valkey-cli ping)" = PONG',
}
PROBE_TIMEOUT = 30
# начало ключа карточки — копия CACHE_KEY_PREFIX из src/constants.py: hook
# на stdlib и код приложения не импортирует. Меняется формат ключа —
# менять и здесь, иначе упадут test_flush_cache и test_valkey_back
CACHE_KEY_PREFIX = "messenger:v1"
FAIL_MEMBERS_SQL = """\
CREATE OR REPLACE FUNCTION fault_fail_members() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
IF (SELECT title FROM chats WHERE id = NEW.chat_id) = TG_ARGV[0] THEN
RAISE EXCEPTION 'fault injected: chat members insert';
END IF;
RETURN NEW;
END
$$;
DROP TRIGGER IF EXISTS fault_fail_members ON chat_members;
CREATE TRIGGER fault_fail_members BEFORE INSERT ON chat_members
FOR EACH ROW EXECUTE FUNCTION fault_fail_members(:'arg');
"""
CLEAR_FAIL_MEMBERS_SQL = """\
DROP TRIGGER IF EXISTS fault_fail_members ON chat_members;
DROP FUNCTION IF EXISTS fault_fail_members();
"""
COUNT_CHATS_SQL = "SELECT count(*) FROM chats WHERE title = :'arg';\n"
# сбой вставки сообщения: ключ идемпотентности к этому моменту уже вставлен
# той же транзакцией (src/storage/postgres.py) — откат должен убрать и его
FAIL_MESSAGES_SQL = """\
CREATE OR REPLACE FUNCTION fault_fail_messages() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
IF NEW.text = TG_ARGV[0] THEN
RAISE EXCEPTION 'fault injected: message insert';
END IF;
RETURN NEW;
END
$$;
DROP TRIGGER IF EXISTS fault_fail_messages ON messages;
CREATE TRIGGER fault_fail_messages BEFORE INSERT ON messages
FOR EACH ROW EXECUTE FUNCTION fault_fail_messages(:'arg');
"""
CLEAR_FAIL_MESSAGES_SQL = """\
DROP TRIGGER IF EXISTS fault_fail_messages ON messages;
DROP FUNCTION IF EXISTS fault_fail_messages();
"""
COUNT_KEYS_SQL = "SELECT count(*) FROM idempotency_keys WHERE chat_id = :'arg';\n"
class HookError(Exception):
"""Неверный вызов или проект: код 2 и сообщение в stderr."""
def fault_project() -> str:
project = os.environ.get("FAULT_PROJECT", "")
if not project.endswith(PROJECT_SUFFIX) or project == PROJECT_SUFFIX:
raise HookError(
f"FAULT_PROJECT must end with {PROJECT_SUFFIX!r}: run make failure-checks",
)
return project
def compose_run(project: str, *args: str, stdin: str | None = None):
files = [arg for path in COMPOSE_FILES for arg in ("-f", str(path))]
return subprocess.run(
[
"docker",
"compose",
"-p",
project,
"--env-file",
str(ENV_FILE),
*files,
*args,
],
cwd=ROOT,
input=stdin,
text=True,
capture_output=True,
check=False,
)
def compose(project: str, *args: str, stdin: str | None = None) -> str:
result = compose_run(project, *args, stdin=stdin)
if result.returncode != 0:
sys.stderr.write(result.stderr)
raise SystemExit(result.returncode)
return result.stdout.strip()
def service(name: str) -> str:
if name not in SERVICES:
raise HookError(f"service must be one of {SERVICES}")
return name
def wait_answers(project: str, name: str) -> str:
"""Ждать, пока сервис ответит проверкой из своего healthcheck.
После `unpause` Docker до следующего запуска healthcheck показывает
старое состояние, и `up --wait` выходит с ошибкой, хотя сервис уже
отвечает. Поэтому проверка — напрямую.
"""
deadline = time.monotonic() + PROBE_TIMEOUT
while time.monotonic() < deadline:
probe = compose_run(project, "exec", "-T", name, "sh", "-c", PROBES[name])
if probe.returncode == 0:
return ""
time.sleep(0.2)
raise HookError(f"{name} does not answer in {PROBE_TIMEOUT}s")
def valkey(project: str, *args: str) -> str:
# аргументы — позиционные параметры sh, без подстановки в строку
return compose(
project,
"exec",
"-T",
"valkey",
"sh",
"-c",
'exec valkey-cli "$@"',
"sh",
*args,
)
def psql(project: str, sql: str, *, arg: str = "") -> str:
# аргумент — переменная psql :'arg' (литерал в SQL экранирует сам psql)
return compose(
project,
"exec",
"-T",
"postgres",
"sh",
"-c",
'exec psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq '
'-v ON_ERROR_STOP=1 -v arg="$1"',
"sh",
arg,
stdin=sql,
)
def cache_hits(project: str) -> str:
for line in valkey(project, "INFO", "stats").splitlines():
if line.startswith("keyspace_hits:"):
return line.split(":", 1)[1].strip()
raise HookError("keyspace_hits not found in INFO stats")
def cache_has_chat(project: str, chat_id: str) -> str:
database = compose(project, "exec", "-T", "postgres", "printenv", "POSTGRES_DB")
key = f"{CACHE_KEY_PREFIX}:{database}:chat:{uuid.UUID(chat_id)}"
return valkey(project, "EXISTS", key)
def run(project: str, action: str, args: list[str]) -> str:
"""Выполнить действие; без match: hook запускается и на Python 3.9."""
if action in ("stop", "pause") and len(args) == 1:
return compose(project, action, service(args[0]))
if action == "start" and len(args) == 1:
# тот же контейнер, без пересоздания; --wait ждёт его healthcheck
return compose(project, "up", "-d", "--wait", "--no-recreate", service(args[0]))
if action == "unpause" and len(args) == 1:
compose(project, "unpause", service(args[0]))
return wait_answers(project, args[0])
if action == "flush-cache" and not args:
return valkey(project, "FLUSHALL")
if action == "cache-hits" and not args:
return cache_hits(project)
if action == "cache-has-chat" and len(args) == 1:
return cache_has_chat(project, args[0])
if action == "fail-members" and len(args) == 1:
return psql(project, FAIL_MEMBERS_SQL, arg=args[0])
if action == "clear-fail-members" and not args:
return psql(project, CLEAR_FAIL_MEMBERS_SQL)
if action == "count-chats" and len(args) == 1:
return psql(project, COUNT_CHATS_SQL, arg=args[0])
if action == "fail-messages" and len(args) == 1:
return psql(project, FAIL_MESSAGES_SQL, arg=args[0])
if action == "clear-fail-messages" and not args:
return psql(project, CLEAR_FAIL_MESSAGES_SQL)
if action == "count-keys" and len(args) == 1:
return psql(project, COUNT_KEYS_SQL, arg=str(uuid.UUID(args[0])))
raise HookError(f"unknown action or arguments: {action} {args}")
def main() -> int:
if len(sys.argv) < 2:
print(__doc__, file=sys.stderr)
return 2
try:
output = run(fault_project(), sys.argv[1], sys.argv[2:])
except (HookError, ValueError) as exc:
print(f"fault_hook: {exc}", file=sys.stderr)
return 2
if output:
print(output)
return 0
if __name__ == "__main__":
sys.exit(main())
+244
View File
@@ -0,0 +1,244 @@
"""Короткие обёртки над API. Проверка формы ответа — здесь, а не в каждом тесте.
Пользователь теста — «актёр»: словарь `User` из ответа API плюс его
синтетический пароль (`password`) и токен текущей сессии (`token`).
Для сравнения с ответами API — `public(actor)`. Пароли и токены
синтетические и никуда не печатаются.
С лабы 3 отправка сообщения — только через `send()`: по умолчанию новый
`Idempotency-Key` на каждый вызов, `key=None` — без заголовка, строка —
этот ключ. Прямой POST без ключа получил бы 400 раньше проверки, которую
хочет увидеть тест (404 постороннему, 401 после выхода).
"""
import base64
from collections.abc import Callable, Iterable
from typing import Any
from uuid import uuid4
import httpx
USERS = "/api/v1/users"
ME = f"{USERS}/me"
CHATS = "/api/v1/chats"
SESSIONS = "/api/v1/auth/sessions"
CURRENT_SESSION = f"{SESSIONS}/current"
# WWW-Authenticate у 401 (contracts/README.md): вход и остальные запросы
BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"'
BEARER_CHALLENGE = 'Bearer realm="messenger"'
USER_FIELDS = frozenset({"id", "username", "display_name", "created_at"})
IDEMPOTENCY_KEY = "Idempotency-Key"
INSTANCE_ID = "X-Instance-Id"
# «нет аргумента» у send(): None значит «без заголовка ключа»
NEW_KEY = object()
# фикстура new_client: каждый вызов — новый клиент со своим соединением
type ClientFactory = Callable[[], httpx.Client]
def headers(actor: dict[str, Any]) -> dict[str, str]:
"""Идентификация с лабы 2: Bearer-токен сессии. Собирается только здесь."""
return bearer_header(actor["token"])
def bearer_header(token: str) -> dict[str, str]:
return {"Authorization": f"Bearer {token}"}
def basic_header(username: str, password: str) -> dict[str, str]:
"""`Authorization: Basic` из username и пароля в UTF-8."""
return basic_raw(f"{username}:{password}".encode())
def basic_raw(raw: bytes) -> dict[str, str]:
"""`Authorization: Basic` из произвольных байтов, в том числе битых."""
return {"Authorization": "Basic " + base64.b64encode(raw).decode("ascii")}
def unique_username(label: str) -> str:
# состояние стенда общее: username не должен повторяться
return f"{label}_{uuid4().hex[:12]}"
def unique_password() -> str:
"""Синтетический пароль 12–128 символов, свой у каждого вызова."""
return f"pw-{uuid4().hex}"
def public(actor: dict[str, Any]) -> dict[str, Any]:
"""Поля `User` из контракта: без пароля и токена теста."""
return {key: actor[key] for key in USER_FIELDS}
def login_response(
client: httpx.Client, username: str, password: str
) -> httpx.Response:
return client.post(SESSIONS, headers=basic_header(username, password))
def login(client: httpx.Client, actor: dict[str, Any]) -> str:
"""Новая сессия пользователя; ответ проверяется по форме `Session`."""
response = login_response(client, actor["username"], actor["password"])
assert response.status_code == 201, response.text
session = response.json()
assert set(session) == {"token", "token_type", "expires_at", "user"}
assert session["token_type"] == "Bearer"
assert session["expires_at"].endswith("Z")
assert session["user"] == public(actor)
assert len(session["token"]) >= 32
return session["token"]
def logout(client: httpx.Client, actor: dict[str, Any]) -> httpx.Response:
return client.delete(CURRENT_SESSION, headers=headers(actor))
def register(
client: httpx.Client,
label: str = "user",
*,
password: str | None = None,
) -> dict[str, Any]:
"""Регистрация с паролем и сразу вход: у актёра есть токен."""
password = password or unique_password()
body = {
"username": unique_username(label),
"display_name": f"Тест {label}",
"password": password,
}
response = client.post(USERS, json=body)
assert response.status_code == 201, response.text
user = response.json()
# пароля и его хэша в ответе нет: только поля User
assert set(user) == USER_FIELDS
assert user["username"] == body["username"]
actor = {**user, "password": password}
actor["token"] = login(client, actor)
return actor
def create_chat(
client: httpx.Client,
owner: dict[str, Any],
*others: dict[str, Any],
title: str = "Тестовый чат",
) -> dict[str, Any]:
member_ids = [owner["id"], *(user["id"] for user in others)]
response = client.post(
CHATS,
json={"title": title, "member_ids": member_ids},
headers=headers(owner),
)
assert response.status_code == 201, response.text
return response.json()
def messages_path(chat: dict[str, Any]) -> str:
return f"{CHATS}/{chat['id']}/messages"
def new_key() -> str:
"""Свой Idempotency-Key у каждого вызова: ASCII из шаблона контракта."""
return f"key-{uuid4().hex}"
def send(
client: httpx.Client,
user: dict[str, Any],
chat: dict[str, Any],
text: str,
*,
key: Any = NEW_KEY,
) -> httpx.Response:
"""POST сообщения с ключом идемпотентности (лаба 3).
`key` не задан — новый ключ; `None` — без заголовка; строка или байты
— этот ключ (байты — для не-ASCII значений, httpx шлёт их как есть).
"""
request_headers = headers(user)
if key is NEW_KEY:
key = new_key()
if key is not None:
request_headers[IDEMPOTENCY_KEY] = key
return client.post(
messages_path(chat), json={"text": text}, headers=request_headers
)
def instance_id(response: httpx.Response) -> str:
"""X-Instance-Id ответа API: непустой у каждого ответа (с лабы 3)."""
value = response.headers.get(INSTANCE_ID, "")
assert value, f"missing {INSTANCE_ID} on {response.status_code}"
return value
def assert_replicas(seen: Iterable[str], expected: int) -> None:
"""Ответы пришли не меньше чем от двух реплик (если их ≥ 2 за BASE_URL)."""
distinct = set(seen)
assert len(distinct) >= min(expected, 2), (
f"{len(distinct)} replica(s) answered, expected at least "
f"{min(expected, 2)} of {expected}"
)
def read_history(
client: httpx.Client,
user: dict[str, Any],
chat: dict[str, Any],
*,
limit: int,
) -> tuple[list[dict[str, Any]], list[int]]:
"""Вся история обходом по курсору: сообщения и размеры страниц."""
items: list[dict[str, Any]] = []
sizes: list[int] = []
params: dict[str, Any] = {"limit": limit}
while True:
response = client.get(messages_path(chat), params=params, headers=headers(user))
assert response.status_code == 200, response.text
page = response.json()
assert set(page) == {"items", "next_cursor"}
items.extend(page["items"])
sizes.append(len(page["items"]))
if page["next_cursor"] is None:
return items, sizes
params = {"limit": limit, "cursor": page["next_cursor"]}
def chat_ids(client: httpx.Client, user: dict[str, Any]) -> list[str]:
"""Id всех чатов пользователя обходом списка по курсору."""
ids: list[str] = []
params: dict[str, Any] = {"limit": 100}
while True:
response = client.get(CHATS, params=params, headers=headers(user))
assert response.status_code == 200, response.text
page = response.json()
ids.extend(item["id"] for item in page["items"])
if page["next_cursor"] is None:
return ids
params = {"limit": 100, "cursor": page["next_cursor"]}
def assert_error(response: httpx.Response, status: int, code: str) -> dict[str, Any]:
"""Ошибка API в формате контракта; request_id совпадает с заголовком.
Ошибку создаёт API, поэтому у неё есть и X-Instance-Id (ответы самого
HAProxy — 502/503/504 — тесты здесь не проверяют).
"""
assert response.status_code == status, response.text
assert response.headers["content-type"].startswith("application/json")
body = response.json()
assert set(body) == {"error"}
error = body["error"]
assert set(error) == {"code", "message", "request_id"}
assert error["code"] == code
assert error["message"]
assert error["request_id"] == response.headers["X-Request-Id"]
instance_id(response)
return error
def assert_unauthorized(response: httpx.Response, challenge: str) -> dict[str, Any]:
"""401 в формате контракта с нужным вызовом в `WWW-Authenticate`."""
error = assert_error(response, 401, "unauthorized")
assert response.headers.get("WWW-Authenticate") == challenge
return error
+21
View File
@@ -0,0 +1,21 @@
# Override отдельных стендов тестов (student-tests/stand.py): тот же
# compose.yaml под проектом <рабочий>-isolated или <рабочий>-failures, со
# своим volume и сетью. Порты хранилищ не публикуются: к ним ходит только
# fault_hook.py через docker compose exec. HAProxy стенда isolated — на
# свободном порту 127.0.0.1, который выбрал stand.py (STAND_LB_PORT), а не
# на случайном от Docker: случайный менялся бы при каждом start, и
# make test-persistence потерял бы стенд после restart.sh. API стенда
# failures stand.py поднимает сам (docker compose run -p 127.0.0.1:...).
# У образа свой тег: рабочий образ стенда не пересобирается.
services:
postgres:
ports: !reset []
valkey:
ports: !reset []
migrate:
image: mtusi-messenger-vladimirceva:lab3-test
api:
image: mtusi-messenger-vladimirceva:lab3-test
haproxy:
ports: !override
- "127.0.0.1:${STAND_LB_PORT:-0}:8080"
+9
View File
@@ -0,0 +1,9 @@
# Подстановки compose для отдельных стендов тестов (student-tests/stand.py)
# вместо .env рабочего стенда: docker compose --env-file student-tests/stand.env.
# Только несекретные имена: пароли stand.py генерирует на каждый прогон.
POSTGRES_USER=messenger
POSTGRES_DB=messenger
LOG_LEVEL=INFO
SESSION_TTL_SECONDS=3600
IDEMPOTENCY_TTL_SECONDS=86400
API_REPLICAS=2
+394
View File
@@ -0,0 +1,394 @@
"""Отдельные стенды собственных тестов: `make test-isolated`, `make failure-checks`.
python3 student-tests/stand.py isolated
python3 student-tests/stand.py failures [аргументы pytest]
Оба поднимают тот же `compose.yaml` под своим проектом
(`<рабочий>-isolated`, `<рабочий>-failures`) с override
`student-tests/stand.compose.yml`: свои PostgreSQL и Valkey со своим
volume, порты хранилищ не публикуются, образ API — свой тег. Подстановки
— `student-tests/stand.env`, а не `.env` рабочего стенда; пароли
хранилищ генерируются на прогон и никуда не пишутся. Затем:
- isolated — стенд лабы 3 целиком: HAProxy на свободном порту 127.0.0.1
и две реплики за ним. Через LB: `make test`, `pytest` (без проверок
отказов, `EXPECT_REPLICAS=2` — тесты реплик выполняются), `make
test-failover` (hook `scripts/stop-one.sh` в проекте стенда), возврат
реплик и `make test-persistence` (hook `scripts/restart.sh`);
- failures — без LB: обычный API и «тесный» (сроки сессии и ключа
идемпотентности 2 с, пул из одного соединения, короткие сроки) —
контейнеры `docker compose run` на свободных портах, `pytest -m fault`
с hook `student-tests/fault_hook.py`;
- удалить стенд вместе с volume при любом исходе, в том числе по Ctrl+C.
Рабочий стенд, его база и кэш не затрагиваются: каждый вызов compose —
только с `-p <проект стенда>`; hooks skeleton получают тот же проект
через `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE` и `COMPOSE_ENV_FILES`. Два
прогона одного вида одновременно не запускать: уборка в начале второго
удалит стенд первого. Только stdlib и Python 3.9+: скрипт запускается
`python3`, как проверки skeleton.
"""
from __future__ import annotations
import json
import os
import secrets
import signal
import socket
import subprocess
import sys
import time
import urllib.error
import urllib.request
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
COMPOSE_FILES = (ROOT / "compose.yaml", ROOT / "student-tests" / "stand.compose.yml")
ENV_FILE = ROOT / "student-tests" / "stand.env"
FAULT_HOOK = ROOT / "student-tests" / "fault_hook.py"
# что из окружения хоста нужно самому docker compose и uv; остальное
# (в том числе POSTGRES_* из shell) в стенд не попадает
HOST_ENV = ("PATH", "HOME", "USER", "TMPDIR", "LANG", "DOCKER_HOST", "DOCKER_CONFIG")
READY_TIMEOUT = 60
LOG_TAIL_LINES = 50
REPLICAS = 2
# «тесный» API стенда отказов: сроки сессии и ключа 2 с, пул из одного
# соединения, короткие сроки ожидания пула и операции
TIGHT_ENV = {
"SESSION_TTL_SECONDS": "2",
"IDEMPOTENCY_TTL_SECONDS": "2",
"DB_POOL_SIZE": "1",
"DB_POOL_OVERFLOW": "0",
"DB_POOL_TIMEOUT": "1",
"DB_OPERATION_TIMEOUT": "2",
}
KINDS = ("isolated", "failures")
def say(kind: str, message: str) -> None:
print(f"[{kind}] {message}", flush=True)
def working_project() -> str:
"""Имя проекта рабочего стенда — из compose.yaml (`name:`)."""
config = subprocess.run(
[
"docker",
"compose",
"--env-file",
str(ENV_FILE),
"-f",
str(COMPOSE_FILES[0]),
"config",
"--format",
"json",
],
cwd=ROOT,
capture_output=True,
text=True,
check=True,
# подстановки не важны: нужно только имя проекта
env={**stand_env(), "POSTGRES_PASSWORD": "x", "VALKEY_PASSWORD": "x"},
)
return json.loads(config.stdout)["name"]
def stand_env() -> dict[str, str]:
"""Окружение docker compose стенда, собранное с нуля.
Пароли хранилищ новые на каждый прогон: живут только здесь, в
контейнерах стенда и у дочерних процессов (hooks вызывают compose с
ними же). В вывод и файлы не попадают.
"""
env = {key: os.environ[key] for key in HOST_ENV if key in os.environ}
return {
**env,
"POSTGRES_PASSWORD": secrets.token_hex(16),
"VALKEY_PASSWORD": secrets.token_hex(16),
# порт LB стенда isolated: постоянный на весь прогон, переживает
# stop/start из restart.sh
"STAND_LB_PORT": str(free_port()),
}
def free_port() -> int:
with socket.socket() as sock:
sock.bind(("127.0.0.1", 0))
return sock.getsockname()[1]
class Stand:
def __init__(self, kind: str) -> None:
self.kind = kind
self.env = stand_env()
working = working_project()
self.project = f"{working}-{kind}"
if self.project == working:
raise SystemExit(f"refusing to use the working project {working!r}")
self.containers: list[str] = []
def run(self, *args: str, check: bool = True, quiet: bool = False, env=None):
return subprocess.run(
args,
cwd=ROOT,
check=check,
text=True,
capture_output=quiet,
env=env or self.env,
)
def compose(self, *args: str, check: bool = True, quiet: bool = False):
"""docker compose стенда; без `-p <проект>` не вызывается никогда."""
files = [arg for path in COMPOSE_FILES for arg in ("-f", str(path))]
return self.run(
"docker",
"compose",
"-p",
self.project,
"--env-file",
str(ENV_FILE),
*files,
*args,
check=check,
quiet=quiet,
)
def hook_env(self, base_url: str) -> dict[str, str]:
"""Окружение make и hooks skeleton: docker compose без `-p` внутри
`scripts/*.sh` попадает в проект стенда, а не в рабочий."""
return {
**os.environ,
**self.env,
"BASE_URL": base_url,
"COMPOSE_PROJECT_NAME": self.project,
"COMPOSE_FILE": os.pathsep.join(str(path) for path in COMPOSE_FILES),
"COMPOSE_ENV_FILES": str(ENV_FILE),
}
def leftovers(self) -> list[str]:
"""Контейнеры и volume проекта стенда, которые ещё остались."""
label = f"label=com.docker.compose.project={self.project}"
found = []
for command in (("ps", "-aq"), ("volume", "ls", "-q")):
out = self.run(
"docker", *command, "--filter", label, check=False, quiet=True
)
found += out.stdout.split()
return found
def cleanup(self) -> bool:
for name in self.containers:
self.run("docker", "rm", "-f", name, check=False, quiet=True)
down = self.compose("down", "-v", "--remove-orphans", check=False, quiet=True)
return down.returncode == 0 and not self.leftovers()
def wait_ready(self, base_url: str, container: str | None) -> None:
deadline = time.monotonic() + READY_TIMEOUT
while time.monotonic() < deadline:
try:
with urllib.request.urlopen(
f"{base_url}/health/ready", timeout=2
) as resp:
if resp.status == 200:
return
except (urllib.error.URLError, OSError):
pass
if container:
state = self.run(
"docker",
"inspect",
"-f",
"{{.State.Running}}",
container,
check=False,
quiet=True,
)
if state.stdout.strip() != "true":
raise RuntimeError(f"container {container} is not running")
time.sleep(0.5)
raise RuntimeError(f"{base_url} not ready in {READY_TIMEOUT}s")
def start_api(self, suffix: str, extra_env: dict[str, str]) -> str:
"""Один процесс API без LB (стенд отказов) на свободном порту."""
name = f"{self.project}-{suffix}"
self.containers.append(name)
port = free_port()
env_args = [
arg for key, value in extra_env.items() for arg in ("-e", f"{key}={value}")
]
self.compose(
"run",
"-d",
"--no-deps",
"--name",
name,
*env_args,
"-p",
f"127.0.0.1:{port}:8080",
"api",
quiet=True,
)
base_url = f"http://127.0.0.1:{port}"
self.wait_ready(base_url, name)
return base_url
def start_lb(self) -> str:
"""HAProxy и REPLICAS реплик за ним; адрес LB на 127.0.0.1."""
self.compose("up", "-d", "--no-build", "--wait", "api", "haproxy")
base_url = f"http://127.0.0.1:{self.env['STAND_LB_PORT']}"
self.wait_ready(base_url, None)
return base_url
def prepare(self) -> None:
say(self.kind, "build image")
self.compose("build", "api")
say(self.kind, "start postgres and valkey")
self.compose("up", "-d", "--wait", "postgres", "valkey")
say(self.kind, "migrations")
self.compose("run", "--rm", "migrate")
def skeleton(self, script: str, base_url: str, *args: str) -> int:
"""Проверка skeleton (`tests/<script>`) — то же, что её цель make.
Не через make: Makefile подключает `.env` рабочего стенда, и его
пароли перекрыли бы пароли стенда в окружении hooks — `up` в
`restart.sh` пересоздал бы хранилища с чужими паролями.
"""
return self.run(
sys.executable,
f"tests/{script}",
"--base-url",
base_url,
*args,
check=False,
env=self.hook_env(base_url),
).returncode
def isolated(self, pytest_args: list[str]) -> dict[str, int]:
self.prepare()
base_url = self.start_lb()
say(self.kind, f"ready: lb={base_url} replicas={REPLICAS}")
results = {}
say(self.kind, "make test")
results["test"] = self.skeleton("smoke.py", base_url)
say(self.kind, "pytest")
results["student-test"] = self.run(
"uv",
"run",
"pytest",
*pytest_args,
check=False,
env={
**os.environ,
"BASE_URL": base_url,
"EXPECT_REPLICAS": str(REPLICAS),
},
).returncode
say(self.kind, "make test-failover (scripts/stop-one.sh)")
results["test-failover"] = self.skeleton(
"resilience.py",
base_url,
"--mode",
"failover",
"--action-script",
"scripts/stop-one.sh",
)
say(self.kind, "restore replicas")
self.compose(
"up",
"-d",
"--no-deps",
"--no-recreate",
"--no-build",
"--wait",
"--scale",
f"api={REPLICAS}",
"api",
)
say(self.kind, "make test-persistence (scripts/restart.sh)")
results["test-persistence"] = self.skeleton(
"resilience.py",
base_url,
"--mode",
"persistence",
"--action-script",
"scripts/restart.sh",
)
return results
def failures(self, pytest_args: list[str]) -> dict[str, int]:
self.prepare()
base_url = self.start_api("api", {})
tight_url = self.start_api("api-tight", TIGHT_ENV)
say(self.kind, f"ready: api={base_url} tight={tight_url}")
env = {
**os.environ,
**self.env,
"BASE_URL": base_url,
"FAULT_TIGHT_BASE_URL": tight_url,
"FAULT_HOOK": str(FAULT_HOOK),
"FAULT_PROJECT": self.project,
}
say(self.kind, "pytest -m fault")
code = self.run(
"uv",
"run",
"pytest",
"-m",
"fault",
*pytest_args,
check=False,
env=env,
).returncode
return {"fault": code}
def failed_logs(self) -> None:
for name in self.containers:
say(self.kind, f"last {LOG_TAIL_LINES} lines of {name}")
self.run("docker", "logs", "--tail", str(LOG_TAIL_LINES), name, check=False)
if self.kind == "isolated":
say(self.kind, f"last {LOG_TAIL_LINES} lines of api and haproxy")
self.compose(
"logs", "--tail", str(LOG_TAIL_LINES), "api", "haproxy", check=False
)
def main() -> int:
if len(sys.argv) < 2 or sys.argv[1] not in KINDS:
print(__doc__, file=sys.stderr)
return 2
kind, pytest_args = sys.argv[1], sys.argv[2:]
stand = Stand(kind)
say(kind, f"project={stand.project}")
if not stand.cleanup():
say(kind, "leftovers of a previous run could not be removed")
return 1
results: dict[str, int] = {}
failed = True
try:
results = getattr(stand, kind)(pytest_args)
failed = any(results.values())
except KeyboardInterrupt:
say(kind, "interrupted")
results["interrupted"] = 130
except (subprocess.CalledProcessError, RuntimeError) as exc:
say(kind, f"setup failed: {exc}")
results["setup"] = 1
finally:
# повторный Ctrl+C не должен оборвать уборку на полпути
signal.signal(signal.SIGINT, signal.SIG_IGN)
if failed:
stand.failed_logs()
say(kind, "cleanup")
if not stand.cleanup():
say(kind, "cleanup failed")
results["cleanup"] = 1
say(kind, f"results: {results}")
return next((code for code in results.values() if code), 0)
if __name__ == "__main__":
sys.exit(main())
+196
View File
@@ -0,0 +1,196 @@
"""Переход 1 → 2: пароль, вход по Basic, Bearer-сессия, выход.
Единственный модуль, который собирает `Authorization` и `X-User-Id` сам,
а не через `helpers.headers()`: здесь проверяются именно заголовки.
Неверный пароль и logout — в `test_rubric.py` (рубрика уровня «4»),
срок сессии и отказ БД — в `test_failures.py`.
"""
import secrets
from datetime import UTC, datetime
import httpx
import pytest
from helpers import (
BASIC_CHALLENGE,
BEARER_CHALLENGE,
CHATS,
ME,
SESSIONS,
USERS,
assert_error,
assert_unauthorized,
basic_header,
basic_raw,
bearer_header,
create_chat,
headers,
login,
logout,
messages_path,
public,
read_history,
register,
unique_password,
unique_username,
)
def test_login_returns_opaque_session(client: httpx.Client) -> None:
alice = register(client, "alice")
response = client.post(
SESSIONS, headers=basic_header(alice["username"], alice["password"])
)
assert response.status_code == 201, response.text
session = response.json()
assert session["user"] == public(alice)
expires_at = datetime.fromisoformat(session["expires_at"])
assert expires_at > datetime.now(UTC)
# токен ничего не кодирует: ни username, ни id
token = session["token"]
for value in (alice["username"], alice["id"], alice["id"].replace("-", "")):
assert value not in token
me = client.get(ME, headers=bearer_header(token))
assert me.json() == public(alice)
def test_login_ignores_json_body(client: httpx.Client) -> None:
alice, eve = register(client, "alice"), register(client, "eve")
response = client.post(
SESSIONS,
headers=basic_header(alice["username"], alice["password"]),
json={"username": eve["username"], "password": eve["password"]},
)
assert response.status_code == 201, response.text
assert response.json()["user"] == public(alice)
def test_password_with_colon_and_cyrillic(client: httpx.Client) -> None:
"""Пароль — UTF-8, разделитель Basic — первое двоеточие."""
actor = register(client, "utf", password="Пароль:с:двоеточиями-1")
assert client.get(ME, headers=headers(actor)).json() == public(actor)
@pytest.mark.parametrize(
"value",
["short", " " * 12, "x" * 129],
ids=["too-short", "blank", "too-long"],
)
def test_bad_password_on_registration_is_400(client: httpx.Client, value: str) -> None:
body = {
"username": unique_username("pw"),
"display_name": "Тест",
"password": value,
}
assert_error(client.post(USERS, json=body), 400, "invalid_request")
@pytest.mark.parametrize(
"header",
[
{"Authorization": "Basic !!!"},
basic_raw(b"no-colon-here"),
basic_raw(b"\xff\xfe:not-utf-8-password"),
{"Authorization": "Basic"},
bearer_header(secrets.token_urlsafe(32)),
{},
],
ids=["not-base64", "no-colon", "not-utf8", "empty", "bearer", "none"],
)
def test_broken_basic_is_401(client: httpx.Client, header: dict[str, str]) -> None:
assert_unauthorized(client.post(SESSIONS, headers=header), BASIC_CHALLENGE)
def test_basic_on_business_endpoint_is_401(client: httpx.Client) -> None:
alice = register(client, "alice")
response = client.get(
ME, headers=basic_header(alice["username"], alice["password"])
)
assert_unauthorized(response, BEARER_CHALLENGE)
@pytest.mark.parametrize(
"header",
[
{},
{"Authorization": "Bearer"},
bearer_header("x"),
bearer_header(secrets.token_urlsafe(32)),
],
ids=["none", "empty", "short", "unknown"],
)
def test_missing_or_unknown_token_is_401(
client: httpx.Client, header: dict[str, str]
) -> None:
assert_unauthorized(client.get(ME, headers=header), BEARER_CHALLENGE)
def test_x_user_id_gives_no_access(client: httpx.Client) -> None:
alice, eve = register(client, "alice"), register(client, "eve")
# только X-User-Id — 401; вместе с Bearer alice — по-прежнему alice
assert_unauthorized(
client.get(ME, headers={"X-User-Id": alice["id"]}), BEARER_CHALLENGE
)
response = client.get(ME, headers={**headers(alice), "X-User-Id": eve["id"]})
assert response.json() == public(alice)
def test_two_sessions_and_logout_of_one(client: httpx.Client) -> None:
alice = register(client, "alice")
second = {**alice, "token": login(client, alice)}
assert second["token"] != alice["token"]
assert logout(client, alice).status_code == 204
assert_unauthorized(client.get(ME, headers=headers(alice)), BEARER_CHALLENGE)
# другая сессия того же пользователя продолжает работать
assert client.get(ME, headers=headers(second)).json() == public(alice)
def test_revoked_token_is_rejected_everywhere(client: httpx.Client) -> None:
alice, bob = register(client, "alice"), register(client, "bob")
chat = create_chat(client, alice, bob)
assert logout(client, alice).status_code == 204
for method, path in (
("GET", ME),
("GET", CHATS),
("GET", f"{CHATS}/{chat['id']}"),
("GET", messages_path(chat)),
):
response = client.request(method, path, headers=headers(alice))
assert_unauthorized(response, BEARER_CHALLENGE)
response = client.post(
messages_path(chat),
json={"text": "после выхода"},
headers=headers(alice),
)
assert_unauthorized(response, BEARER_CHALLENGE)
items, _ = read_history(client, bob, chat, limit=50)
assert items == []
def test_user_never_contains_password(client: httpx.Client) -> None:
password = unique_password()
actor = register(client, "secret", password=password)
for response in (
client.get(ME, headers=headers(actor)),
client.post(SESSIONS, headers=basic_header(actor["username"], password)),
):
assert password not in response.text
assert "password" not in response.text
def test_security_schemes_in_openapi(client: httpx.Client) -> None:
"""Схемы bearerAuth и basicAuth как в контракте: кнопка Authorize в /docs."""
served = client.get("/openapi.json").json()
schemes = served["components"]["securitySchemes"]
assert schemes["bearerAuth"] == {
"type": "http",
"scheme": "bearer",
"bearerFormat": "opaque session token",
}
assert schemes["basicAuth"] == {"type": "http", "scheme": "basic"}
paths = served["paths"]
assert paths[ME]["get"]["security"] == [{"bearerAuth": []}]
assert paths[SESSIONS]["post"]["security"] == [{"basicAuth": []}]
assert not paths[USERS]["post"].get("security")
+77
View File
@@ -0,0 +1,77 @@
"""Реплики за балансировщиком (лаба 3, уровень «3»).
Одна сессия обслуживается разными репликами без повторного входа — это
видно по `X-Instance-Id`; подтверждённая запись видна следующему чтению
через любую реплику; у процесса одно значение заголовка. Нужны ≥ 2
реплики за `BASE_URL` (фикстура `replicas`): против одного процесса тесты
пропускаются с причиной. Опираются на round-robin LB без sticky session.
Отказ реплики (остановка, kill, зависание, поочерёдная замена) — не
pytest: ему нужно действие над контейнерами (`make test-failover`,
`make failover-each`, профили `failover` и `rollout` стенда `bench/`).
"""
from collections import Counter
import httpx
from helpers import (
ME,
assert_replicas,
create_chat,
headers,
instance_id,
messages_path,
public,
register,
send,
)
SESSION_REQUESTS = 20
def test_one_session_on_several_replicas(client: httpx.Client, replicas: int) -> None:
alice = register(client, "alice")
served: Counter[str] = Counter()
for _ in range(SESSION_REQUESTS):
response = client.get(ME, headers=headers(alice))
assert response.status_code == 200, response.text
assert response.json() == public(alice)
served[instance_id(response)] += 1
print(f"one session, {SESSION_REQUESTS} requests: {dict(served)}")
assert_replicas(served, replicas)
def test_write_visible_through_other_replica(
client: httpx.Client,
replicas: int,
) -> None:
alice, bob = register(client, "alice"), register(client, "bob")
chat = create_chat(client, alice, bob)
response = send(client, alice, chat, "через LB")
assert response.status_code == 201, response.text
message, writer = response.json(), instance_id(response)
readers: Counter[str] = Counter()
for _ in range(2 * replicas + 2):
page = client.get(messages_path(chat), headers=headers(bob))
assert page.status_code == 200, page.text
assert message in page.json()["items"]
readers[instance_id(page)] += 1
print(f"written via {writer}, read via {dict(readers)}")
assert_replicas(readers, replicas)
assert readers.keys() - {writer}, f"every read was served by the writer {writer}"
def test_instance_id_is_stable_per_process(client: httpx.Client, replicas: int) -> None:
"""Две одинаковые серии запросов: вторая не приносит новых значений, и
каждое значение повторяется — заголовок стабилен на время жизни
процесса, а не новый на каждый ответ."""
rounds = [
Counter(instance_id(client.get("/health/live")) for _ in range(6 * replicas))
for _ in range(2)
]
print(f"series: {[dict(counter) for counter in rounds]}")
assert set(rounds[1]) <= set(rounds[0])
assert all(count >= 2 for count in rounds[0].values())
assert_replicas(rounds[0], replicas)
+61
View File
@@ -0,0 +1,61 @@
"""Кэш карточек чатов в Valkey: что видно по HTTP.
Попадание в кэш по HTTP не отличить от чтения из PostgreSQL, поэтому
здесь проверяется только то, что кэш не меняет ответы: карточка с тем же
порядком участников, членство нового чата сразу, история и список чатов
без устаревших данных после записи (read-after-write из контракта).
Отказ Valkey, очистка и возврат кэша — `test_failures.py`.
"""
import httpx
from helpers import (
CHATS,
assert_error,
chat_ids,
create_chat,
headers,
read_history,
register,
send,
)
def test_repeated_reads_return_the_created_card(client: httpx.Client) -> None:
alice, bob, eve = (register(client, name) for name in ("alice", "bob", "eve"))
# порядок участников не совпадает ни с сортировкой, ни с порядком
# регистрации: кэш обязан сохранить его как есть
created = create_chat(client, bob, eve, alice, title="Кэш «карточки»")
path = f"{CHATS}/{created['id']}"
first = client.get(path, headers=headers(alice)).json()
second = client.get(path, headers=headers(eve)).json()
assert first == second == created
assert first["member_ids"] == [bob["id"], eve["id"], alice["id"]]
def test_new_chat_membership_works_at_once(client: httpx.Client) -> None:
alice, bob, eve = (register(client, name) for name in ("alice", "bob", "eve"))
chat = create_chat(client, alice, bob)
assert send(client, bob, chat, "сразу после создания").status_code == 201
assert_error(
client.get(f"{CHATS}/{chat['id']}", headers=headers(eve)), 404, "not_found"
)
assert_error(send(client, eve, chat, "посторонний"), 404, "not_found")
def test_message_is_visible_to_the_next_read(client: httpx.Client) -> None:
alice, bob = register(client, "alice"), register(client, "bob")
chat = create_chat(client, alice, bob)
# история уже прочитана: если бы она кэшировалась, второе чтение
# отдало бы старую страницу
assert read_history(client, bob, chat, limit=50)[0] == []
message = send(client, alice, chat, "видно сразу").json()
assert read_history(client, bob, chat, limit=50)[0] == [message]
def test_new_chat_is_listed_at_once(client: httpx.Client) -> None:
alice, bob = register(client, "alice"), register(client, "bob")
first = create_chat(client, alice, bob)
assert chat_ids(client, bob) == [first["id"]]
second = create_chat(client, alice, bob, title="Второй")
assert chat_ids(client, bob) == [first["id"], second["id"]]

Some files were not shown because too many files have changed in this diff Show More