feat: add replicated messenger and reproducible lab3 stand
This commit is contained in:
@@ -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"],
|
||||
)
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
@@ -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"]
|
||||
@@ -0,0 +1,13 @@
|
||||
# Известные проблемы
|
||||
|
||||
Найдены попутно и не исправлены без отдельной просьбы (AGENTS.md,
|
||||
раздел 2, п. 17). Формат: что, где, симптом, предложение. Исправленное
|
||||
удаляется отсюда.
|
||||
|
||||
Открытых дефектов нет.
|
||||
|
||||
Закрыто при переносе в лабу 3: косметическая находка лабы 2 в
|
||||
`bench/run.py:render_explain` (подпись раздела «Страница middle без
|
||||
индекса» у чата без средней страницы). Стенд лабы 2 с планами запроса в
|
||||
лабу 3 не переносился — стенд переписан под реплики за HAProxy, функции
|
||||
больше нет; метки и отчёт лабы 2 остались в её репозитории.
|
||||
@@ -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)
|
||||
|
||||
@@ -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
@@ -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
@@ -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 — попросить пользователя запустить команду
|
||||
и прислать вывод.
|
||||
@@ -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 | изменение сломало поведение: вернуть, разобраться, без замеров «после» |
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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
@@ -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-"))
|
||||
@@ -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
File diff suppressed because it is too large
Load Diff
+412
@@ -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
File diff suppressed because it is too large
Load Diff
@@ -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
@@ -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:
|
||||
@@ -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`.
|
||||
@@ -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, опущен.
|
||||
@@ -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/.
|
||||
@@ -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.
|
||||
@@ -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, а не контейнера: новая
|
||||
# реплика получила адрес и слот только что удалённой.
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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/.
|
||||
@@ -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 фиксирован при входе).
|
||||
@@ -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.
|
||||
@@ -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). Абсолютный путь
|
||||
# заменён на <репозиторий>.
|
||||
@@ -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
@@ -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`.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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).
|
||||
@@ -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())
|
||||
@@ -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")
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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
|
||||
Executable
+251
@@ -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())
|
||||
Executable
+20
@@ -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
|
||||
Executable
+422
@@ -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"
|
||||
Executable
+82
@@ -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
@@ -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).
|
||||
@@ -0,0 +1,7 @@
|
||||
"""REST API мессенджера MTUSI, лабораторная 3: реплики за HAProxy.
|
||||
|
||||
PostgreSQL — источник истины (данные, сессии, ключи идемпотентности),
|
||||
Valkey — общий кэш карточек чатов. Пакет намеренно пустой при импорте:
|
||||
`import src.<модуль>` не поднимает приложение, не читает окружение и не
|
||||
подключается к базе.
|
||||
"""
|
||||
@@ -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()
|
||||
@@ -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` и тела. Токен в
|
||||
вывод и отчёт не копировать.
|
||||
+170
@@ -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)]
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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,
|
||||
)
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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)
|
||||
@@ -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()
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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
@@ -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,
|
||||
)
|
||||
@@ -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
@@ -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),
|
||||
)
|
||||
@@ -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"
|
||||
@@ -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()
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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"
|
||||
@@ -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
@@ -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
@@ -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,
|
||||
)
|
||||
@@ -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])))
|
||||
@@ -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
|
||||
@@ -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-тест.
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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`).
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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`."""
|
||||
...
|
||||
@@ -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)
|
||||
@@ -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]
|
||||
@@ -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"),
|
||||
)
|
||||
@@ -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`.
|
||||
@@ -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
|
||||
Executable
+251
@@ -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())
|
||||
@@ -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
|
||||
@@ -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"
|
||||
@@ -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
|
||||
@@ -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())
|
||||
@@ -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")
|
||||
@@ -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)
|
||||
@@ -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
Reference in New Issue
Block a user