Author SHA1 Message Date
ng14 f7f689c7c2 исправление 2026-10-15 19:44:46 +03:00
ng14 825f6fdbf5 Обновить REPORT.md 2026-10-15 00:31:20 +03:00
ng14 d9b9e8593c ЛР3 2026-10-15 00:24:46 +03:00
73 changed files with 5112 additions and 37 deletions
+8 -20
View File
@@ -1,20 +1,8 @@
.git
.github
.env
.env.*
!.env.example
secrets
certs
volumes
data
backups
*.key
*.pem
*.p12
*.pfx
*.jks
.venv
__pycache__
node_modules
evidence
.DS_Store
# Белый список: в контекст сборки попадает только то, что явно разрешено ниже.
# Так в образ точно не утекут .env, secrets/, .git, тесты и отчёты.
*
!requirements.txt
!src/
!migrations/
**/__pycache__
**/*.pyc
+21
View File
@@ -11,3 +11,24 @@ SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
# --- Дополнительные настройки этого решения (значения по умолчанию из src/messenger/config.py) ---
# API_REPLICAS — число реплик API за балансировщиком (deploy.replicas в compose.yaml).
# IDEMPOTENCY_TTL_SECONDS приложением не читается: ключ хранится вместе с сообщением
# бессрочно, то есть не меньше 24 ч из контракта (migrations/004_message_idempotency.sql).
# Сколько секунд сессия может лежать в кэше Valkey (не дольше самой сессии).
SESSION_CACHE_TTL_SECONDS=30
# Пул соединений с PostgreSQL и таймауты.
DB_POOL_MIN_SIZE=1
DB_POOL_MAX_SIZE=10
DB_POOL_TIMEOUT_SECONDS=3
DB_CONNECT_TIMEOUT_SECONDS=3
DB_STATEMENT_TIMEOUT_MS=5000
# Valkey: таймаут операции, размер пула соединений, период фоновой проверки (PING).
CACHE_TIMEOUT_MS=300
CACHE_POOL_MAX_SIZE=20
CACHE_CHECK_INTERVAL_SECONDS=1
# Остановка по SIGTERM: сначала столько секунд /health/ready = 503 (уход из балансировки),
# потом не дольше GRACEFUL_SHUTDOWN_SECONDS на начатые запросы.
SHUTDOWN_DRAIN_SECONDS=3
GRACEFUL_SHUTDOWN_SECONDS=8
+8
View File
@@ -0,0 +1,8 @@
# Git на Windows (core.autocrlf=true) меняет LF на CRLF при checkout. Для этих файлов это ломает запуск:
# sh-скрипт с \r не выполняется, а конфиги Valkey и HAProxy читаются внутри Linux-контейнеров.
*.sh text eol=lf
*.sql text eol=lf
*.conf text eol=lf
*.cfg text eol=lf
# cmd.exe ожидает CRLF.
*.cmd text eol=crlf
+42
View File
@@ -0,0 +1,42 @@
# Базовый образ закреплён точной версией (не latest), чтобы сборка была воспроизводимой.
FROM python:3.12.8-slim-bookworm
# Не создавать .pyc, сразу выводить логи (без буфера), не кэшировать скачанные пакеты.
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /srv
# Сначала только список зависимостей: пока он не меняется, Docker берёт этот слой
# из кэша и не переустанавливает пакеты при каждой правке кода.
# --only-binary: только готовые wheel (psycopg-binary, argon2), без компиляции в образе.
COPY requirements.txt .
RUN pip install --only-binary=:all: -r requirements.txt
COPY src/ ./
# SQL-миграции едут в образе вместе с кодом: версия схемы всегда соответствует версии приложения.
# Применяет их сервис migrate (`python -m messenger.migrate`), реплики API только проверяют схему.
COPY migrations/ ./migrations/
# Непривилегированный пользователь: если приложение взломают, у атакующего не будет root.
RUN useradd --system --uid 10001 --no-create-home --shell /usr/sbin/nologin app
USER app
# Версия сборки (с lab3): пишется в лог при старте, по ней student-tests/rolling_update.py
# проверяет, что все реплики заменены новой версией. ARG стоит в конце, чтобы смена версии
# не пересобирала слои с зависимостями и кодом.
ARG APP_VERSION=dev
ENV APP_VERSION=${APP_VERSION}
EXPOSE 8080
# Docker сам периодически опрашивает /health/ready и показывает статус healthy/unhealthy.
# Ready проверяет PostgreSQL, а после SIGTERM отвечает 503 (реплика уходит из балансировки).
# curl в slim-образе нет, поэтому проверяем средствами Python. Частоту задаёт compose.yaml.
HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \
CMD ["python", "-c", "import os, urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/health/ready' % os.environ.get('APP_PORT', '8080'), timeout=2)"]
# Exec-форма (JSON-массив): python запускается напрямую как PID 1 и сам получает SIGTERM.
CMD ["python", "-m", "messenger"]
+116 -2
View File
@@ -1,13 +1,25 @@
PYTHON ?= python3
BASE_URL ?= http://localhost:8080
# 127.0.0.1, а не localhost: на части Windows-машин localhost резолвится очень медленно.
# С lab3 это адрес балансировщика HAProxy — единственной точки входа API.
BASE_URL ?= http://127.0.0.1:8080
# API с SESSION_TTL_SECONDS=2 (сервис api-short-ttl, профиль ttl), тоже через балансировщик.
BASE_URL_TTL ?= http://127.0.0.1:8081
CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
# Передаём адреса собственным тестам через окружение (работает и в cmd, и в sh).
export BASE_URL
export BASE_URL_TTL
.PHONY: help check validate test load test-persistence test-failover
.PHONY: help check validate test load test-persistence test-failover \
secrets up down ps logs restore student-test race expiry failure-valkey failure-postgres \
failure-valkey-pause db-test explain demo cache-stats \
balancing idempotency failover persistence failover-metrics rolling-update load-profile check-stack report-tables
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "secrets/up/down/ps/logs/restore: stand; student-test, race, expiry, failure-valkey, failure-postgres, failure-valkey-pause, db-test, explain, demo, cache-stats: own checks (lab2)"
@echo "balancing, idempotency, failover, persistence, failover-metrics, rolling-update, load-profile, check-stack, report-tables: own checks (lab3)"
check:
$(PYTHON) scripts/check_contract.py
@@ -28,3 +40,105 @@ 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)
# ---------- стенд ----------
secrets:
sh scripts/init-secrets.sh
up:
docker compose up -d --build --wait
# Без -v: volumes с данными сохраняются. Удаление данных — только осознанно: docker compose down -v
down:
docker compose --profile ttl --profile tools down
# ID контейнера + состояние. ID реплики api = её X-Instance-Id.
ps:
docker compose ps -a --format "table {{.Service}}\t{{.ID}}\t{{.Status}}"
logs:
docker compose logs --tail 50 api lb
# Вернуть остановленные реплики (после make test-failover): запустить всё, что должно работать,
# и дождаться, пока HAProxy снова возьмёт в работу все реплики.
restore:
docker compose up -d --wait
$(PYTHON) student-tests/stand.py
# ---------- собственные проверки lab1–lab2 (теперь через балансировщик) ----------
student-test:
$(PYTHON) -m unittest discover -s student-tests -p "test_*.py" -v
race:
$(PYTHON) student-tests/race.py
# Поднимает API с TTL сессии 2 с (за балансировщиком, 127.0.0.1:8081), проверяет и убирает его.
expiry:
docker compose --profile ttl up -d --wait api-short-ttl
$(PYTHON) student-tests/expiry.py; status=$$?; docker compose --profile ttl rm -sf api-short-ttl >/dev/null 2>&1; exit $$status
failure-valkey:
$(PYTHON) student-tests/dependency_failure.py valkey
failure-postgres:
$(PYTHON) student-tests/dependency_failure.py postgres
# Valkey на паузе (данные в нём сохраняются), logout, снова в строю: токен должен остаться отозванным.
failure-valkey-pause:
$(PYTHON) student-tests/cache_revocation.py
db-test:
docker compose --profile tools run --rm db-test
explain:
docker compose exec -T postgres psql -X -q -U messenger -d messenger -v ON_ERROR_STOP=1 < infra/sql/explain_history.sql
demo:
$(PYTHON) student-tests/demo.py
# Роль Valkey: сколько ключей в кэше и сколько попаданий/промахов; права пользователя health.
VALKEY_HEALTH = docker compose exec -T valkey valkey-cli --user health --pass none --no-auth-warning
cache-stats:
$(VALKEY_HEALTH) dbsize
$(VALKEY_HEALTH) info stats | grep -E "keyspace_(hits|misses)"
-$(VALKEY_HEALTH) get sess:anything
# ---------- собственные проверки lab3 ----------
# Реплики, общие сессии и кэш, X-Instance-Id (входит и в student-test).
balancing:
$(PYTHON) -m unittest discover -s student-tests -p "test_balancing.py" -v
# Idempotency-Key: повторы, конкурентные запросы через разные реплики (входит и в student-test).
idempotency:
$(PYTHON) -m unittest discover -s student-tests -p "test_idempotency.py" -v
# Публичный failover-тест для КАЖДОЙ реплики по очереди + какой контейнер реально остановлен.
failover:
$(PYTHON) student-tests/run_failover.py
# Публичный persistence-тест + время старта каждого контейнера до и после hook.
persistence:
$(PYTHON) student-tests/run_persistence.py
# Уровень 4: остановка (SIGTERM) и авария (SIGKILL) каждой реплики под нагрузкой: RPS, ошибки, восстановление.
failover-metrics:
$(PYTHON) student-tests/failover_metrics.py
# Уровень 4: поочерёдная замена реплик новой версией под нагрузкой.
rolling-update:
$(PYTHON) student-tests/rolling_update.py
# Профиль нагрузки: публичный tests/load.py (30 с, 4 потока) + CPU/RAM контейнеров во время нагрузки.
load-profile:
$(PYTHON) student-tests/load_profile.py
# Уровень 4: лимиты CPU/RAM, нет портов API в обход LB, нет container_name, сети, версии.
check-stack:
$(PYTHON) student-tests/check_stack.py
# Таблицы замеров из evidence/*.json -> REPORT.md (между метками measurements).
report-tables:
$(PYTHON) student-tests/report_tables.py
+148 -15
View File
@@ -1,37 +1,170 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Гаджиев Нухбала, БВТ2303
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
- Commit/PR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3/pulls/9
- Использованные источники, библиотеки и помощь ИИ: всё из lab2 (FastAPI, uvicorn, pydantic, psycopg 3 + psycopg-pool, argon2-cffi, valkey-py; версии в requirements.txt); образы haproxy:3.2.25-alpine, python:3.12.8-slim-bookworm, postgres:17.10-bookworm, valkey/valkey:8.1.9; документация HAProxy 3.2 (resolvers, server-template, http-check, retries, observe), Docker Compose (deploy.replicas и resources, depends_on с condition, healthcheck), PostgreSQL (INSERT ... ON CONFLICT, уникальные ограничения). ИИ использовался как вспомогательный ресурс: для оценки решения, написания комментариев к коду и составления текстовых документов.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Проверял на Windows 11 в Git Bash: Docker Desktop (Docker 29.6.2, Compose 5.3.1 — `evidence/stack.txt`), Python 3 (нужен только для тестов, только стандартная библиотека), GNU Make. Образы закреплены в `compose.yaml` и `Dockerfile`: haproxy:3.2.25-alpine, python:3.12.8-slim-bookworm (основа образа API), postgres:17.10-bookworm, valkey/valkey:8.1.9. Перед запуском остановить стенд lab2 (`docker compose -p mtusi-lab2 down` из любой папки), иначе занят порт 8080.
```sh
git clone https://gitea.privcloud.tech/ng14/mtusi2026lab3.git && cd mtusi2026lab3
git checkout solution/bvt2303-gadzhiev
cp .env.example .env
sed -i 's/\r$//' .env # только Windows: убрать \r из .env
sh scripts/init-secrets.sh # secrets/ со случайными паролями (каталог в .gitignore)
docker compose up -d --build --wait # migrate -> 2 реплики api -> lb; ждёт healthy
make ps # api x2, lb, postgres, valkey: healthy; migrate: Exited (0)
make check PYTHON=python
make test PYTHON=python
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python # Linux/macOS: scripts/stop-one.sh
make restore PYTHON=python # вернуть реплику и дождаться её в HAProxy
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python # Linux/macOS: scripts/restart.sh
```
Собственные проверки (каждая печатает PASS/OK, вывод сохранён в `evidence/`): `make student-test`, `race`, `db-test`, `expiry`, `failure-valkey`, `failure-postgres`, `failure-valkey-pause`, `cache-stats`, `explain` (как в lab2) и новые `make failover`, `persistence`, `failover-metrics`, `load-profile`, `rolling-update`, `check-stack`, `report-tables` (с `PYTHON=python` на Windows). Все тесты ходят на `http://127.0.0.1:8080` — это балансировщик.
Миграции применяет одноразовый сервис `migrate` при каждом `docker compose up`, отдельной команды нет. Для новой версии их можно применить заранее: `docker compose run --rm migrate`. Действие оператора одно: один раз создать секреты (`sh scripts/init-secrets.sh`), значения не выводятся и не попадают в Git.
Безопасная остановка: `make down` (контейнеры удаляются, volume `pgdata` остаётся). Намеренное удаление учебных данных: `docker compose down -v`, затем `rm -rf secrets` и заново `sh scripts/init-secrets.sh`.
Почему у hook два варианта: тест запускает hook напрямую, без shell, а Python на Windows не запускает `.sh` (WinError 193). Поэтому есть `scripts/stop-one.cmd` и `scripts/restart.cmd` для Windows и `.sh` для Linux/macOS. Логика stop-one одна (`scripts/stop_one.py`), оба варианта вызывают её. Остановленную реплику hook оставляет остановленной, вернуть её: `make restore PYTHON=python` (`docker compose up -d --wait`, затем ожидание, пока HAProxy снова возьмёт в работу все реплики).
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```text
клиент --HTTP--> lb: HAProxy 3.2, 127.0.0.1:8080 (единственная точка входа; :8404 — статистика)
| round robin, без привязки клиента к реплике
+--> api-1 --+
+--> api-2 --+--> postgres: пользователи, чаты, сообщения, ключи идемпотентности, сессии (volume pgdata)
+--> valkey: общий кэш сессий (без persistence)
migrate (одноразовый): применяет migrations/*.sql до старта api и завершается с кодом 0
сети: edge (lb <-> api) и backend (api, migrate <-> postgres, valkey; internal — без выхода наружу)
```
| Роль | Сервис | Версия | Health / готовность | Volume | Сеть / порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| Балансировщик | `lb` | haproxy:3.2.25-alpine | `/lb-health` на :8404 (есть куда отправить запрос) | нет | edge; 127.0.0.1:8080, :8081, :8404 | не нужны |
| API ×2 | `api` (`deploy.replicas: 2`) | образ из Dockerfile (python:3.12.8-slim-bookworm) | `/health/ready`: Docker раз в 5 с, HAProxy раз в 1 с | нет | edge + backend, портов наружу нет | `/run/secrets/database_url`, `cache_url` |
| Миграции | `migrate` | тот же образ | завершается с кодом 0 | нет | backend | только `database_url` |
| База данных | `postgres` | postgres:17.10-bookworm | `pg_isready` | `pgdata` | backend, 5432 | `POSTGRES_PASSWORD_FILE` |
| Кэш сессий | `valkey` | valkey/valkey:8.1.9 | `valkey-cli ping` (пользователь health) | нет | backend, 6379 | ACL из `secrets/valkey_users.acl` |
Что перенесено из lab2: весь код API (`src/messenger`), миграции 001–003, свои тесты, Dockerfile, `compose.yaml`, конфиг Valkey, `scripts/init-secrets.sh`, restart-скрипты. Данные и сессии и так лежали в PostgreSQL, кэш — в Valkey, поэтому в памяти реплики нет ничего, от чего зависит правильность ответа, и реплики взаимозаменяемы.
Что изменено в lab3:
- `compose.yaml`: две реплики `api` без `ports` и `container_name`, балансировщик `lb`, одноразовый `migrate`, лимиты CPU/RAM у всех контейнеров, две сети. API с коротким TTL (`api-short-ttl`, только для `make expiry`) тоже доступен лишь через балансировщик (:8081).
- `infra/haproxy/haproxy.cfg`: список реплик HAProxy берёт из DNS Docker (имя `api` -> IP всех запущенных реплик, перечитывается раз в 2 с), поэтому сам замечает остановленные и новые реплики. Sticky session нет.
- `X-Instance-Id` в каждом ответе (middleware в `api.py`) — hostname контейнера, то есть его короткий ID. По заголовку контейнер сразу находится в `make ps`, а `scripts/stop_one.py` останавливает именно его.
- Обязательный `Idempotency-Key` у POST сообщения (`api.py`, `store.add_message`, `migrations/004_message_idempotency.sql`).
- Миграции больше не применяет API: это делает `python -m messenger.migrate` (сервис `migrate`). Реплика при старте только ждёт, пока схема станет актуальной (`db.wait_for_schema`).
- Остановка по SIGTERM в два шага (`__main__.py`, `DrainingServer`).
- Кэш сессий стал по-настоящему общим: у записей общее поколение `sess:gen` в Valkey (в lab2 поколение было своё у каждого процесса, это было записано в ограничениях lab2).
Идемпотентность. Ключ и SHA-256 тела запроса хранятся прямо в строке сообщения. Уникальное ограничение `(chat_id, sender_id, idempotency_key)` — это область ключа из контракта: пользователь + чат (метод и путь у ключа всегда `POST .../messages`). Запись — один `INSERT ... ON CONFLICT DO NOTHING`, поэтому сообщение и «запомненный результат» сохраняются атомарно, одной строкой. Ключ уже есть: то же тело (сравнивается хеш разобранного JSON, пробелы и порядок полей не важны) — тот же 201 и то же сообщение, другое тело — 409. Если два запроса с одним ключом пришли одновременно на разные реплики, PostgreSQL заставляет второй `INSERT` ждать конца транзакции первого, после чего второй читает готовую строку. Повтор снова проверяет сессию (middleware, 401) и членство в чате (404). Ответы 400/404/503 ничего не сохраняют, после них тот же ключ можно использовать. Ключ хранится столько же, сколько сообщение (удаления в API нет), то есть не меньше 24 ч.
Балансировщик, проверки и отказ реплики:
- HAProxy раз в 1 с запрашивает `/health/ready` у каждой реплики (при смене состояния раз в 0,5 с, `timeout check 1s`). 2 неудачи подряд — реплика выведена, 2 удачи — возвращена. Худший случай для зависшей реплики: 1 + 1 + 0,5 + 1 ≈ 3,5 с. Ещё два пути быстрее: `observe layer4` выводит реплику после первой же ошибки соединения у живого запроса, а DNS Docker перестаёт отдавать IP остановленного контейнера (HAProxy замечает за 2–4 с).
- Плановая остановка (`docker stop`, SIGTERM): реплика сразу отвечает 503 на `/health/ready`, но ещё 3 с обслуживает запросы (`SHUTDOWN_DRAIN_SECONDS`); HAProxy за это время выводит её. Потом uvicorn закрывает приём и доделывает начатые запросы (не дольше 8 с: ожидание пула 3 с + statement_timeout 5 с). Docker ждёт 15 с (`stop_grace_period`), затем SIGKILL. Hook ждёт не дольше 8 с, поэтому укладывается в 10 с теста.
- Таймауты согласованы снизу вверх: запрос к БД ≤ 8 с < `timeout server 15s` в HAProxy < 15 с `stop_grace_period`; `timeout connect 1s`.
- HAProxy повторяет запрос только при ошибке соединения (запрос ещё не ушёл) и на другой реплике (`retries 2`, `option redispatch`). Уже отправленный POST сам не повторяет: это делает клиент с тем же `Idempotency-Key`.
- Запросы получают только реплики, прошедшие проверку готовности, резервных серверов без проверки нет. Если не готова ни одна реплика (например, недоступна PostgreSQL), балансировщик сам отвечает 503 и запрос до API не передаёт, даже если реплика могла бы ответить из кэша. Ответы самого балансировщика (503, 502, 504) отдаются в формате ошибки контракта с `X-Request-Id`; `X-Instance-Id` у них нет, потому что ни одна реплика их не создавала.
Миграции. `migrate` запускается после healthy PostgreSQL, применяет новые файлы (учёт в `schema_migrations`, `pg_advisory_lock` от двух одновременных запусков) и завершается. `api` стартует только после его успешного завершения (`depends_on: condition: service_completed_successfully`). Миграция 004 только добавляет столбцы, которые могут быть NULL, поэтому совместима с уже работающей версией: старый код пишет сообщения без ключа. Порядок обновления: сначала `docker compose run --rm migrate`, потом замена реплик по одной (`make rolling-update`).
Сессии и общий кэш. Источник истины — таблица `sessions` в PostgreSQL. Valkey — общий для всех реплик кэш «hash токена -> пользователь», запись положила одна реплика — используют все. Отзыв после сбоя Valkey для нескольких реплик: каждая запись помечена поколением, текущее поколение лежит в Valkey (`sess:gen`) и читается тем же запросом `MGET`, что и запись. Каждая реплика раз в 1 с проверяет Valkey. Реплика, заметившая сбой, перестаёт пользоваться кэшем, а когда Valkey вернулся, сначала записывает новое поколение и только потом включает кэш. Записи до сбоя (в том числе запись сессии, отозванной во время сбоя) после этого не доверяет ни одна реплика: проверка идёт в PostgreSQL, там сессия отозвана — 401.
Соответствие .env.example:
| Переменная | Что делает в этом решении |
| --- | --- |
| APP_HOST, APP_PORT, APP_ENV | где слушает uvicorn (0.0.0.0:8080), APP_ENV пишется в лог |
| SESSION_TTL_SECONDS | срок жизни сессии (3600; у api-short-ttl — 2) |
| DATABASE_URL_FILE, CACHE_URL_FILE | пути к секретам с адресами PostgreSQL и Valkey (`/run/secrets/...`) |
| SESSION_STORE=postgres | источник истины сессий — PostgreSQL, Valkey — кэш |
| API_REPLICAS | число реплик api (`deploy.replicas` в compose.yaml), по умолчанию 2 |
| IDEMPOTENCY_TTL_SECONDS | не используется: ключ хранится вместе с сообщением бессрочно (это не меньше 24 ч) |
| SHUTDOWN_DRAIN_SECONDS, GRACEFUL_SHUTDOWN_SECONDS | остановка по SIGTERM: 3 с ухода из балансировки, затем до 8 с на начатые запросы |
| CACHE_CHECK_INTERVAL_SECONDS | как часто каждая реплика проверяет Valkey (1 с) |
| SESSION_CACHE_TTL_SECONDS, DB_*, CACHE_* | как в lab2: TTL записи в кэше, размер пулов и таймауты |
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Публичный smoke | make test | PASS: lab3 public API scenario (в том числе повтор с ключом, 409, 400 без ключа) | evidence/test.txt |
| Структура skeleton и контракт не изменены | make check | PASS: offline skeleton structure | evidence/check.txt |
| Замечание к MR: резервные слоты fallback без проверки обходили readiness | убраны из infra/haproxy/haproxy.cfg; make failure-postgres; make check-stack | PostgreSQL остановлена: HAProxy за 2,5–2,8 с вывел обе реплики (изнутри контейнеров live 200, ready 503); /users/me с действующим токеном из кэша через LB — 503 от балансировщика без X-Instance-Id, до реплики не дошёл; запись не сохранилась; check-stack: в backend нет резервных серверов и серверов без проверки. На старом конфиге тот же тест падает (/users/me — 200) | evidence/failure-postgres.txt, evidence/stack.txt |
| 3: стенд в compose.yaml, одна команда; ≥2 API, одна точка входа, общая БД и общий кэш сессий | docker compose up -d --build --wait; make check-stack | 2 реплики api без портов; опубликован только lb на 127.0.0.1; одна postgres и один valkey | evidence/stack.txt |
| 3: запросы одного пользователя обслуживают разные реплики без повторного входа (X-Instance-Id) | make student-test (test_one_session_is_served_by_every_replica), make demo | 20 запросов с одним токеном — 2 разных X-Instance-Id по 10 раз; это ID запущенных контейнеров api | evidence/student-test.txt |
| 3: доступ через LB — основной маршрут | все тесты на BASE_URL=http://127.0.0.1:8080 (HAProxy) | порт наружу есть только у lb | evidence/stack.txt |
| 3: можно остановить любую одну реплику; ≤10 с — новые чтения/записи; подтверждённое на месте; ошибки измерены | make failover (публичный test-failover для каждой реплики по очереди) | PASS 2 раза; observed_instances_before 2; failed_attempts и first_recovery_seconds — в JSON-строке теста; остановлен именно контейнер из X-Instance-Id, остальные не тронуты | evidence/failover.txt |
| 3: повтор с тем же Idempotency-Key без дублей, включая конкурентный повтор и смену реплики | make idempotency (входит в student-test); make failover | повтор через другую реплику — тот же 201 и то же сообщение; 20 одновременных через 2 реплики — 1 сообщение; в failover-тесте дублей нет | evidence/student-test.txt, evidence/failover.txt |
| 3: make test, persistence и failover проходят; в failover ≥2 реплики | make test; make persistence; make failover | все PASS; observed_instances_before = 2 | evidence/test.txt, persistence.txt, failover.txt |
| 3: hook перезапуска реально перезапускает процессы | make persistence (публичный test-persistence + время старта контейнеров) | у api ×2, postgres, valkey и lb тот же ID и новое время старта; данные и прежний токен на месте | evidence/persistence.txt |
| 3: в API нет локальных сессий и данных | test_logout_applies_on_every_replica, test_write_on_one_replica_read_on_another | logout через одну реплику — 401 на обеих; запись через одну — сразу видна через другую | evidence/student-test.txt |
| 3: миграции отдельно и согласованно, не гонкой реплик | сервис migrate; docker compose logs migrate api; make db-test | «Миграции применены: 001…004» только в логе migrate, у реплик «Схема БД актуальна»; повторный migrate ничего не применяет | evidence/stack.txt, evidence/db-test.txt |
| 3: Swarm | — | выбран Compose, отдельная сборка образа для узлов не нужна | — |
| 3: возможности lab1/lab2 сохранены | make student-test, race, db-test, expiry, failure-valkey, failure-postgres, failure-valkey-pause, explain — через балансировщик | все PASS/OK; student-test: Ran 36 tests, OK; db-test: 7 тестов OK | evidence/*.txt |
| 4: health/readiness, таймауты и SIGTERM согласованы; LB исключает недоступную реплику; период проверок и время обнаружения | infra/haproxy/haproxy.cfg, src/messenger/__main__.py; make failover-metrics | проверка раз в 1 с (0,5 с при смене), 2 неудачи; худший случай ≈ 3,5 с; при `docker stop` реплика уходит из LB до выхода; измеренное время — в таблице ниже | evidence/failover-metrics.txt |
| 4: каждая реплика остановлена по очереди с восстановлением; RPS, ошибки, время восстановления | make failover-metrics (stop и kill для каждой реплики) | таблица ниже; потерь и дублей нет; остановленная реплика после остановки не отвечала | evidence/failover-metrics.json |
| 4: общая идемпотентность параллельными запросами с одним ключом | make idempotency; make db-test | 20 одновременных через 2 реплики — 1 сообщение; 10 разных тел — 201 ×1, 409 ×9; в БД 20 потоков — 1 строка | evidence/student-test.txt, evidence/db-test.txt |
| 4: CPU/RAM-лимиты; API без портов; секреты и хранилища общие только где нужно; нет container_name | make check-stack | PASS: лимиты у всех контейнеров; порты только у lb и только на 127.0.0.1; секреты по сервисам; postgres и valkey только во внутренней сети | evidence/stack.txt |
| 4: rolling update под нагрузкой | make rolling-update | 2 реплики заменены новой версией по одной; ошибки, RPS и задержки — ниже | evidence/rolling-update.json |
| 4: миграции однократно и совместимы с работающей версией | сервис migrate; make db-test (test_old_version_insert_without_key_still_works); make rolling-update | 004 только добавляет столбцы с NULL; INSERT без ключа, как в lab2, работает после 004; в rolling update migrate запускается один раз до замены реплик | evidence/db-test.txt, evidence/rolling-update.txt |
| lab2-замечание для нескольких реплик: общий кэш и отзыв токена после сбоя Valkey | make student-test (test_session_cache_is_shared_between_replicas); make failure-valkey-pause | 10 запросов через 2 реплики — промахов кэша 0; после pause → logout → unpause отозванный токен всегда 401 | evidence/student-test.txt, evidence/failure-valkey-pause.txt |
| Выбранный трек 5 | — | не выбран | — |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Ноутбук: AMD Ryzen 7 4700U (8 ядер), 7,4 ГБ памяти, Windows 11, Docker Desktop. Лимиты контейнеров (compose.yaml): api — 1 CPU и 512 МиБ каждая реплика, postgres — 1 CPU и 512 МиБ, lb и valkey — по 0,5 CPU и 128 МиБ. Данные синтетические, их создают сами тесты. Нагрузка — простой closed-loop генератор на той же машине, поэтому RPS ограничен и клиентом, и лимитами CPU: это не предельная пропускная способность стенда. Под нагрузкой каждая реплика API упирается в свой лимит 1 CPU (около 100 % в таблице CPU/RAM), поэтому после остановки одной реплики число записей в секунду падает примерно вдвое: вся нагрузка ложится на оставшуюся. Это ожидаемо и не ошибка: запросы продолжают обслуживаться, потерь нет, после возврата реплики RPS восстанавливается.
<!-- measurements:begin -->
Остановка каждой реплики под нагрузкой (`make failover-metrics`, evidence/failover-metrics.json): 4 потока пишут сообщения без пауз, 1 читает историю, timeout клиента 2 с, неподтверждённая запись повторяется с тем же ключом; 3 с до отказа и 10 с после. stop = `docker stop` (SIGTERM, плановая остановка), kill = `docker kill` (SIGKILL, авария).
| Реплика | Отказ | Вывод из LB, с | Ошибок (коды) | Ошибки закончились через, с | Записей/с до → после | p95 записи после, мс | Возврат в LB после `docker start`, с | Потери / дубли |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1c773748bc05 | stop | 1.16 | 0 (-) | 0.0 | 114.7 → 65.9 | 125.0 | 4.5 | 0 / 0 (подтверждено 1006) |
| 1c773748bc05 | kill | 0.11 | 1 (502: 1) | 0.11 | 151.3 → 70.3 | 109.0 | 5.64 | 0 / 0 (подтверждено 1160) |
| aa3dac85e7ed | stop | 1.59 | 0 (-) | 0.0 | 104.0 → 57.8 | 141.0 | 3.97 | 0 / 0 (подтверждено 892) |
| aa3dac85e7ed | kill | 0.25 | 1 (502: 1) | 0.14 | 155.3 → 79.7 | 94.0 | 4.25 | 0 / 0 (подтверждено 1266) |
Rolling update под той же нагрузкой (`make rolling-update`, evidence/rolling-update.json): версия dev → rolling-20261015-193851, 2 реплики заменены по одной за 22.38 с (1c773748bc05 → e8baa1b553a1: новая готова через 6.64 с, шаг 11.8 с; aa3dac85e7ed → db0d1f669f44: новая готова через 5.89 с, шаг 10.55 с). Записей/с до: 104.3, во время замены: 138.7; ошибок: 0 (-); p95 63.0 мс, максимум 312.0 мс; подтверждено 3867 сообщений, потерь и дублей нет.
Публичный генератор нагрузки (`make load-profile` = `tests/load.py`, closed loop, 4 потока, 30 с, 2 реплики): 130.05 успешных POST/с, ошибок 0 (доля 0.0), задержка успешных: p50 16.0 мс, p95 78.0 мс, p99 141.0 мс.
| Сервис | CPU, % макс. (100 % = 1 ядро) | RAM макс. / лимит, МиБ |
| --- | --- | --- |
| api | 97.5 | 83 / 512 |
| api | 90.2 | 122 / 512 |
| lb | 24.2 | 20 / 128 |
| postgres | 31.1 | 52 / 512 |
| valkey | 9.6 | 8 / 128 |
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| `docker stop` одной реплики (по очереди каждой) | реплика сама уходит из балансировки до выхода; ошибок нет | ошибок всего 0 за 2 прогона; HAProxy вывел реплику не позже 1.59 с; остановленная реплика после остановки не отвечала | ошибок не было; потерь и дублей 0 |
| `docker kill` одной реплики (по очереди каждой) | несколько 502 у запросов, начатых на ней; клиент повторяет с тем же ключом | ошибок всего 2 за 2 прогона; HAProxy вывел реплику не позже 0.25 с; остановленная реплика после остановки не отвечала | ошибки закончились не позже 0.14 с после отказа; потерь и дублей 0 |
| Rolling update 2 реплик под нагрузкой | замена по одной без простоя | ошибок 0, записей/с 138.7 | 22.38 с на замену; потерь и дублей 0 |
| Перезапуск всего стенда (`make persistence`, hook restart) | данные и действующий токен сохраняются | PASS: те же контейнеры с новым временем старта, прежний токен работает | 19.6 с на весь тест (hook + готовность); потерь нет |
| `docker compose stop valkey` | API работает без кэша | ready 200; вход, сообщения и logout работают через PostgreSQL | кэш снова включается за 1–2 с после start; потерь нет |
| `docker compose stop postgres` | неготовые реплики исключены из маршрутизации, клиенту 503 | HAProxy вывел обе реплики (ready 503, live 200); запрос с действующим токеном из кэша -> 503 от балансировщика, до реплики не дошёл; запись не сохранилась | после start прежний токен и данные на месте; запросы во время отказа не сохранены (503) |
| `docker compose pause valkey`, logout, `unpause` | отозванный токен не оживает ни на одной реплике | после unpause отозванный токен всегда 401 | поколение кэша сменилось после возвращения Valkey; отзыв не потерян |
<!-- measurements:end -->
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Выдерживается отказ одной реплики API. Не выдерживается отказ единственных `lb`, `postgres`, `valkey` (без Valkey API работает, но медленнее) и всей машины: стенд на одном узле, это единые точки отказа.
- При аварийной остановке реплики (SIGKILL) запросы, начатые на ней, получают 502 от HAProxy. Клиент повторяет POST сообщения с тем же ключом, дублей нет; HAProxy сам такие запросы не повторяет.
- Первый запрос после внезапной остановки Valkey ждёт около 4 с (на нём обнаруживается сбой: подключение к пропавшему контейнеру на Docker Desktop), следующие идут без кэша сразу (10–30 мс), `evidence/failure-valkey.txt`.
- Создание чата и регистрация по контракту не идемпотентны: их повтор после timeout может создать второй чат (регистрация получит 409).
- Миграция 004 строит уникальный индекс: на большой таблице это заблокировало бы запись в `messages`. Для большой базы нужен `CREATE UNIQUE INDEX CONCURRENTLY` отдельным шагом; на учебной базе это доли секунды.
- Rolling update сделан скриптом: Compose сам не заменяет реплики по одной (в Swarm это `update_config: order: start-first`).
- `X-Instance-Id` раскрывает ID контейнера; в lab7 его нужно заменить случайным alias.
- Ключи идемпотентности хранятся вместе с сообщениями бессрочно, индекс растёт вместе с числом сообщений.
- Общее поколение кэша закрывает сценарий «отзыв во время сбоя Valkey» для всех реплик, которые заметили сбой. Если сбой Valkey короче интервала проверки (1 с) и logout пришёлся ровно на него, реплика, не заметившая сбой, теоретически может до следующей проверки другой реплики (≤ 1 с) доверять старой записи.
- Если PostgreSQL недоступна, через балансировщик недоступно всё, включая `/health/live` (готовых реплик нет, HAProxy отвечает 503). Что сами реплики живы, видно изнутри контейнеров и по статистике HAProxy.
- API подключается к PostgreSQL владельцем базы, Basic идёт по HTTP — только для локального стенда (минимальные права и TLS — lab7).
+184
View File
@@ -0,0 +1,184 @@
# Стенд lab3: HAProxy (единственная точка входа) -> API x2 -> PostgreSQL (источник истины)
# + Valkey (общий кэш сессий).
# Запуск: docker compose up -d --build --wait
# Секреты: sh scripts/init-secrets.sh (создаёт каталог secrets/, он в .gitignore)
#
# Сети: edge (lb <-> api) и backend (api, migrate <-> postgres, valkey; internal = без выхода наружу).
# Наружу опубликованы только порты балансировщика и только на 127.0.0.1 хоста.
# У api нет ports и container_name: реплик может быть сколько угодно (deploy.replicas),
# все они видны балансировщику по DNS-имени сервиса "api".
name: mtusi-lab3
# Сборка образа приложения. APP_VERSION меняет только student-tests/rolling_update.py.
x-build: &build
context: .
args:
APP_VERSION: ${APP_VERSION:-dev}
# Docker-статус healthy/unhealthy для API (для `up --wait` и rolling update).
# Из балансировки реплику выводит HAProxy по своим, более частым проверкам (infra/haproxy/haproxy.cfg).
x-api-healthcheck: &api-healthcheck
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"]
interval: 5s
timeout: 3s
retries: 3
start_period: 30s
start_interval: 1s
# Общие настройки процессов приложения (реплики API, API с коротким TTL, тесты БД).
x-app: &app
image: mtusi-messenger:lab3
env_file: .env
secrets: [database_url, cache_url]
networks: [edge, backend]
services:
# Одноразовый сервис: применяет migrations/*.sql и завершается с кодом 0.
# Реплики API стартуют только после него и схему не меняют (нет гонки миграций).
migrate:
image: mtusi-messenger:lab3
build: *build
env_file: .env
command: ["python", "-m", "messenger.migrate"]
# Миграциям нужен только адрес PostgreSQL: секрет Valkey сюда не монтируется (минимум прав).
environment:
CACHE_URL_FILE: ""
secrets: [database_url]
networks: [backend]
depends_on:
postgres: {condition: service_healthy}
healthcheck:
disable: true
restart: "no"
deploy:
resources:
limits: {cpus: "0.50", memory: 128M}
api:
<<: *app
build: *build
depends_on:
migrate: {condition: service_completed_successfully}
postgres: {condition: service_healthy}
valkey: {condition: service_healthy}
healthcheck: *api-healthcheck
restart: unless-stopped
# SIGTERM -> 3 с readiness 503 (уход из балансировки) -> до 8 с на начатые запросы -> выход.
# Docker ждёт 15 с и только потом SIGKILL.
stop_grace_period: 15s
deploy:
replicas: ${API_REPLICAS:-2}
resources:
# 512 МиБ: Argon2id берёт 19 МиБ на каждую одновременную проверку пароля.
limits: {cpus: "1.00", memory: 512M}
lb:
image: haproxy:3.2.25-alpine
ports:
- "127.0.0.1:8080:8080" # единственная точка входа API
- "127.0.0.1:8081:8081" # API с коротким TTL (make expiry), тоже через балансировщик
- "127.0.0.1:8404:8404" # статистика HAProxy: http://127.0.0.1:8404/stats
volumes:
- ./infra/haproxy/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
networks: [edge]
depends_on:
api: {condition: service_started}
healthcheck:
test: ["CMD", "wget", "-q", "-T", "2", "-O", "/dev/null", "http://127.0.0.1:8404/lb-health"]
interval: 5s
timeout: 3s
retries: 3
start_period: 20s
start_interval: 1s
restart: unless-stopped
stop_grace_period: 15s
deploy:
resources:
limits: {cpus: "0.50", memory: 128M}
# Второй экземпляр API с SESSION_TTL_SECONDS=2 — только для проверки истечения сессии.
# Та же база, тот же код; запускается явно (make expiry). Порт наружу не публикуется:
# доступ через балансировщик, 127.0.0.1:8081.
api-short-ttl:
<<: *app
profiles: [ttl]
pull_policy: never # образ собирается сервисом api, а не скачивается
environment:
SESSION_TTL_SECONDS: "2"
depends_on:
postgres: {condition: service_healthy}
valkey: {condition: service_healthy}
healthcheck: *api-healthcheck
restart: unless-stopped
deploy:
resources:
limits: {cpus: "0.50", memory: 256M}
# Интеграционные тесты хранилища (откат транзакции, повтор миграций, гонки, идемпотентность).
# Запуск: docker compose --profile tools run --rm db-test
db-test:
<<: *app
profiles: [tools]
pull_policy: never
networks: [backend]
volumes: ["./student-tests:/srv/student-tests:ro"]
command: ["python", "-m", "unittest", "discover", "-s", "student-tests/db", "-v"]
depends_on:
postgres: {condition: service_healthy}
deploy:
resources:
limits: {cpus: "1.00", memory: 512M}
postgres:
image: postgres:17.10-bookworm
environment:
POSTGRES_USER: messenger
POSTGRES_DB: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password # пароль из файла, не из переменной
# Значения по умолчанию, выписанные явно: COMMIT возвращается только после записи WAL на диск.
command: ["postgres", "-c", "fsync=on", "-c", "synchronous_commit=on", "-c", "full_page_writes=on"]
secrets: [postgres_password]
volumes: ["pgdata:/var/lib/postgresql/data"] # именованный volume: данные переживают пересоздание контейнера
healthcheck:
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U messenger -d messenger"]
interval: 5s
timeout: 3s
retries: 12
start_period: 10s
restart: unless-stopped
stop_grace_period: 30s # PostgreSQL успевает корректно завершиться (checkpoint)
networks: [backend]
deploy:
resources:
limits: {cpus: "1.00", memory: 512M}
valkey:
image: valkey/valkey:8.1.9
command: ["valkey-server", "/usr/local/etc/valkey/valkey.conf"]
volumes: ["./infra/valkey/valkey.conf:/usr/local/etc/valkey/valkey.conf:ro"]
secrets: [valkey_acl] # пользователи и пароль Valkey (ACL), генерируются init-secrets.sh
healthcheck:
# Пользователь health без пароля может только ping/info/dbsize — данных он не видит.
test: ["CMD-SHELL", "valkey-cli --user health --pass none --no-auth-warning ping | grep -q PONG"]
interval: 5s
timeout: 3s
retries: 12
restart: unless-stopped
networks: [backend]
deploy:
resources:
limits: {cpus: "0.50", memory: 128M}
volumes:
pgdata: {}
secrets:
postgres_password: {file: ./secrets/postgres_password}
database_url: {file: ./secrets/database_url}
cache_url: {file: ./secrets/cache_url}
valkey_acl: {file: ./secrets/valkey_users.acl}
networks:
edge: {}
backend:
internal: true # postgres и valkey недоступны снаружи и сами не ходят в интернет
+2
View File
@@ -0,0 +1,2 @@
python scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
+32
View File
@@ -0,0 +1,32 @@
docker compose --profile tools run --rm db-test
Container mtusi-lab3-postgres-1 Running
Container mtusi-lab3-postgres-1 Waiting
Container mtusi-lab3-postgres-1 Healthy
Container mtusi-lab3-db-test-run-4288ad929232 Creating
Container mtusi-lab3-db-test-run-4288ad929232 Created
test_concurrent_registration_has_one_winner (test_store.StoreIntegrationTest.test_concurrent_registration_has_one_winner) ...
20 параллельных create_user: 1 создан, 19 получили Conflict (409)
ok
test_concurrent_same_idempotency_key_creates_one_row (test_store.StoreIntegrationTest.test_concurrent_same_idempotency_key_creates_one_row) ... ok
test_create_chat_rolls_back_when_failing_midway (test_store.StoreIntegrationTest.test_create_chat_rolls_back_when_failing_midway) ...
20 одновременных add_message с одним ключом: 1 строка, 1 новое + 19 повторов с тем же сообщением
чат с несуществующим участником: транзакция откатилась, строк chats/chat_members не осталось
ok
test_database_rejects_message_from_non_member (test_store.StoreIntegrationTest.test_database_rejects_message_from_non_member) ...
INSERT сообщения от не-участника напрямую в БД: ForeignKeyViolation
ok
test_migrations_rerun_is_noop (test_store.StoreIntegrationTest.test_migrations_rerun_is_noop) ...
schema_migrations: ['001_core', '002_sessions', '003_text_as_bytes', '004_message_idempotency']; повторный migrate() ничего не применил
ok
test_old_version_insert_without_key_still_works (test_store.StoreIntegrationTest.test_old_version_insert_without_key_still_works) ...
INSERT как в lab2 (без ключа) после миграции 004 работает: старая версия совместима со схемой
ok
test_same_key_other_body_is_conflict (test_store.StoreIntegrationTest.test_same_key_other_body_is_conflict) ...
тот же ключ с другим телом: Conflict (409), в базе по-прежнему одна строка
ok
----------------------------------------------------------------------
Ran 7 tests in 0.493s
OK
+22
View File
@@ -0,0 +1,22 @@
docker compose --profile ttl up -d --wait api-short-ttl
Container mtusi-lab3-postgres-1 Running
Container mtusi-lab3-valkey-1 Running
Container mtusi-lab3-api-short-ttl-1 Creating
Container mtusi-lab3-api-short-ttl-1 Created
Container mtusi-lab3-postgres-1 Waiting
Container mtusi-lab3-valkey-1 Waiting
Container mtusi-lab3-valkey-1 Healthy
Container mtusi-lab3-postgres-1 Healthy
Container mtusi-lab3-api-short-ttl-1 Starting
Container mtusi-lab3-api-short-ttl-1 Started
Container mtusi-lab3-valkey-1 Waiting
Container mtusi-lab3-api-short-ttl-1 Waiting
Container mtusi-lab3-postgres-1 Waiting
Container mtusi-lab3-valkey-1 Healthy
Container mtusi-lab3-postgres-1 Healthy
Container mtusi-lab3-api-short-ttl-1 Healthy
python student-tests/expiry.py; status=$?; docker compose --profile ttl rm -sf api-short-ttl >/dev/null 2>&1; exit $status
session issued by short-TTL API, expires in 1.98s
before expiry: GET /users/me -> 200 (short API twice, main API once)
after expiry: GET /users/me -> 401 on both instances
PASS: session expired after SESSION_TTL_SECONDS; cache did not extend it
+76
View File
@@ -0,0 +1,76 @@
docker compose exec -T postgres psql -X -q -U messenger -d messenger -v ON_ERROR_STOP=1 < infra/sql/explain_history.sql
=== Объём данных
messages_total | messages_in_big_chat
----------------+----------------------
39193 | 12000
=== Индекс истории (migrations/001_core.sql)
indexdef
-------------------------------------------------------------------------------------------------
CREATE INDEX messages_chat_history_idx ON public.messages USING btree (chat_id, created_at, id)
=== 1. Первая страница (limit=50, приложение просит 51 строку, чтобы понять, есть ли следующая)
QUERY PLAN
---------------------------------------------------------------------------------------------------------
Limit (actual time=0.016..0.031 rows=51 loops=1)
Buffers: shared hit=5
-> Index Scan using messages_chat_history_idx on messages (actual time=0.015..0.026 rows=51 loops=1)
Index Cond: (chat_id = 'c4170f65-25c8-486b-a880-dcf11a354bca'::uuid)
Buffers: shared hit=5
Planning:
Buffers: shared hit=6
Planning Time: 0.186 ms
Execution Time: 0.054 ms
=== 2. Страница из середины истории по keyset-курсору (после 6000-го сообщения)
QUERY PLAN
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Limit (actual time=0.012..0.031 rows=51 loops=1)
Buffers: shared hit=6
-> Index Scan using messages_chat_history_idx on messages (actual time=0.011..0.026 rows=51 loops=1)
Index Cond: ((chat_id = 'c4170f65-25c8-486b-a880-dcf11a354bca'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 01:40:00+00'::timestamp with time zone, '4cf0e1fe-ddbf-4da7-b5d3-e610ab7325b9'::uuid)))
Buffers: shared hit=6
Planning Time: 0.105 ms
Execution Time: 0.115 ms
=== 3. Для сравнения: та же страница через OFFSET (так приложение НЕ делает)
QUERY PLAN
-----------------------------------------------------------------------------------------------------------
Limit (actual time=1.711..1.729 rows=51 loops=1)
Buffers: shared hit=169
-> Index Scan using messages_chat_history_idx on messages (actual time=0.025..1.504 rows=6051 loops=1)
Index Cond: (chat_id = 'c4170f65-25c8-486b-a880-dcf11a354bca'::uuid)
Buffers: shared hit=169
Planning Time: 0.112 ms
Execution Time: 1.751 ms
=== 4. Для сравнения: запрос 2 без индекса (индекс удалён только внутри этой транзакции)
QUERY PLAN
-----------------------------------------------------------------------------------------------------------------------------------------------------
Limit (actual time=4.045..4.053 rows=51 loops=1)
Buffers: shared hit=180
-> Sort (actual time=4.044..4.047 rows=51 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 31kB
Buffers: shared hit=180
-> Bitmap Heap Scan on messages (actual time=0.996..2.398 rows=6000 loops=1)
Recheck Cond: (chat_id = 'c4170f65-25c8-486b-a880-dcf11a354bca'::uuid)
Filter: (ROW(created_at, id) > ROW('2026-01-01 01:40:00+00'::timestamp with time zone, '4cf0e1fe-ddbf-4da7-b5d3-e610ab7325b9'::uuid))
Rows Removed by Filter: 6000
Heap Blocks: exact=168
Buffers: shared hit=180
-> Bitmap Index Scan on messages_idempotency_unique (actual time=0.253..0.253 rows=12000 loops=1)
Index Cond: (chat_id = 'c4170f65-25c8-486b-a880-dcf11a354bca'::uuid)
Buffers: shared hit=12
Planning:
Buffers: shared hit=5
Planning Time: 0.126 ms
Execution Time: 4.078 ms
=== ROLLBACK: синтетические данные удалены, индекс на месте
+169
View File
@@ -0,0 +1,169 @@
{
"profile": {
"writers": 4,
"readers": 1,
"client_timeout_seconds": 2,
"warmup_seconds": 3,
"after_seconds": 10,
"replicas": 2,
"client_python": "3.11.5"
},
"runs": [
{
"replica": "1c773748bc05",
"mode": "stop",
"command_seconds": 4.56,
"lb_excluded_after_seconds": 1.16,
"errors": 0,
"error_codes": {},
"errors_stopped_after_seconds": 0.0,
"before": {
"seconds": 3.0,
"write_rps": 114.7,
"reads": 34,
"errors": 0,
"error_codes": {},
"write_p50_ms": 31.0,
"write_p95_ms": 94.0,
"write_max_ms": 172.0
},
"after": {
"seconds": 10.0,
"write_rps": 65.9,
"reads": 87,
"errors": 0,
"error_codes": {},
"write_p50_ms": 47.0,
"write_p95_ms": 125.0,
"write_max_ms": 250.0
},
"stopped_replica_answers_after_stop": 0,
"integrity": {
"confirmed_writes": 1006,
"messages_in_history": 1006,
"duplicates": 0,
"lost": 0
},
"rejoin_seconds": 4.5
},
{
"replica": "1c773748bc05",
"mode": "kill",
"command_seconds": 0.84,
"lb_excluded_after_seconds": 0.11,
"errors": 1,
"error_codes": {
"502": 1
},
"errors_stopped_after_seconds": 0.11,
"before": {
"seconds": 3.0,
"write_rps": 151.3,
"reads": 38,
"errors": 0,
"error_codes": {},
"write_p50_ms": 31.0,
"write_p95_ms": 47.0,
"write_max_ms": 109.0
},
"after": {
"seconds": 10.0,
"write_rps": 70.3,
"reads": 93,
"errors": 1,
"error_codes": {
"502": 1
},
"write_p50_ms": 47.0,
"write_p95_ms": 109.0,
"write_max_ms": 1031.0
},
"stopped_replica_answers_after_stop": 0,
"integrity": {
"confirmed_writes": 1160,
"messages_in_history": 1160,
"duplicates": 0,
"lost": 0
},
"rejoin_seconds": 5.64
},
{
"replica": "aa3dac85e7ed",
"mode": "stop",
"command_seconds": 4.78,
"lb_excluded_after_seconds": 1.59,
"errors": 0,
"error_codes": {},
"errors_stopped_after_seconds": 0.0,
"before": {
"seconds": 3.0,
"write_rps": 104.0,
"reads": 33,
"errors": 0,
"error_codes": {},
"write_p50_ms": 31.0,
"write_p95_ms": 78.0,
"write_max_ms": 234.0
},
"after": {
"seconds": 10.0,
"write_rps": 57.8,
"reads": 78,
"errors": 0,
"error_codes": {},
"write_p50_ms": 63.0,
"write_p95_ms": 141.0,
"write_max_ms": 265.0
},
"stopped_replica_answers_after_stop": 0,
"integrity": {
"confirmed_writes": 892,
"messages_in_history": 892,
"duplicates": 0,
"lost": 0
},
"rejoin_seconds": 3.97
},
{
"replica": "aa3dac85e7ed",
"mode": "kill",
"command_seconds": 0.94,
"lb_excluded_after_seconds": 0.25,
"errors": 1,
"error_codes": {
"502": 1
},
"errors_stopped_after_seconds": 0.14,
"before": {
"seconds": 3.0,
"write_rps": 155.3,
"reads": 38,
"errors": 0,
"error_codes": {},
"write_p50_ms": 31.0,
"write_p95_ms": 47.0,
"write_max_ms": 78.0
},
"after": {
"seconds": 10.0,
"write_rps": 79.7,
"reads": 95,
"errors": 1,
"error_codes": {
"502": 1
},
"write_p50_ms": 47.0,
"write_p95_ms": 94.0,
"write_max_ms": 1094.0
},
"stopped_replica_answers_after_stop": 0,
"integrity": {
"confirmed_writes": 1266,
"messages_in_history": 1266,
"duplicates": 0,
"lost": 0
},
"rejoin_seconds": 4.25
}
]
}
+25
View File
@@ -0,0 +1,25 @@
python student-tests/failover_metrics.py
api replicas: ['1c773748bc05', 'aa3dac85e7ed']; load: 4 writers without pauses + 1 reader, client timeout 2 s, retry with the same Idempotency-Key; 3 s before and 10 s after the failure
--- stop 1c773748bc05 ...
docker stop: 4.56 s; HAProxy excluded it after 1.16 s; errors: 0 {}, last error ended 0.0 s after the failure
write RPS before 114.7 -> after 65.9; p95 after 125.0 ms, max 250.0 ms; answers from the stopped replica after stop: 0
confirmed 1006, in history 1006, lost 0, duplicates 0; back in the balancer 4.5 s after docker start
--- kill 1c773748bc05 ...
docker kill: 0.84 s; HAProxy excluded it after 0.11 s; errors: 1 {'502': 1}, last error ended 0.11 s after the failure
write RPS before 151.3 -> after 70.3; p95 after 109.0 ms, max 1031.0 ms; answers from the stopped replica after stop: 0
confirmed 1160, in history 1160, lost 0, duplicates 0; back in the balancer 5.64 s after docker start
--- stop aa3dac85e7ed ...
docker stop: 4.78 s; HAProxy excluded it after 1.59 s; errors: 0 {}, last error ended 0.0 s after the failure
write RPS before 104.0 -> after 57.8; p95 after 141.0 ms, max 265.0 ms; answers from the stopped replica after stop: 0
confirmed 892, in history 892, lost 0, duplicates 0; back in the balancer 3.97 s after docker start
--- kill aa3dac85e7ed ...
docker kill: 0.94 s; HAProxy excluded it after 0.25 s; errors: 1 {'502': 1}, last error ended 0.14 s after the failure
write RPS before 155.3 -> after 79.7; p95 after 94.0 ms, max 1094.0 ms; answers from the stopped replica after stop: 0
confirmed 1266, in history 1266, lost 0, duplicates 0; back in the balancer 4.25 s after docker start
replica mode cmd,s lb_out,s errors errors_end,s rps_before rps_after p95_after,ms rejoin,s
1c773748bc05 stop 4.56 1.16 0 0.0 114.7 65.9 125.0 4.5
1c773748bc05 kill 0.84 0.11 1 0.11 151.3 70.3 109.0 5.64
aa3dac85e7ed stop 4.78 1.59 0 0.0 104.0 57.8 141.0 3.97
aa3dac85e7ed kill 0.94 0.25 1 0.14 155.3 79.7 94.0 4.25
PASS: every replica was stopped (stop, kill) and restored; no lost or duplicated messages; saved evidence/failover-metrics.json
+48
View File
@@ -0,0 +1,48 @@
python student-tests/run_failover.py
hook: scripts/stop-one.cmd; api replicas: ['1c773748bc05', 'aa3dac85e7ed']
=== run 1: containers before (HAProxy: api1 UP, api2 UP)
SERVICE CONTAINER STATE STARTED AT (UTC)
api 1c773748bc05 running (healthy) 2026-10-15T16:32:38.776
api aa3dac85e7ed running (healthy) 2026-10-15T16:32:38.423
lb f9c8bda9ea4c running (healthy) 2026-10-15T16:32:39.190
migrate 7420f3f1ddda exited 2026-10-15T16:32:47.434
postgres 5c16b9b684f2 running (healthy) 2026-10-15T16:35:06.670
valkey c74935587700 running (healthy) 2026-10-15T16:34:57.760
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.␍
{"observed_instances_before": 2, "successful_writes": 125, "failed_attempts": 0, "first_recovery_seconds": 5.703}␍
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
containers after (HAProxy: api1 UP)
SERVICE CONTAINER STATE STARTED AT (UTC)
api 1c773748bc05 running (healthy) 2026-10-15T16:32:38.776
api aa3dac85e7ed exited 2026-10-15T16:32:38.423
lb f9c8bda9ea4c running (healthy) 2026-10-15T16:32:39.190
migrate 7420f3f1ddda exited 2026-10-15T16:32:47.434
postgres 5c16b9b684f2 running (healthy) 2026-10-15T16:35:06.670
valkey c74935587700 running (healthy) 2026-10-15T16:34:57.760
the hook stopped aa3dac85e7ed (X-Instance-Id of that replica = container ID); other api containers, postgres, valkey and lb kept running
restored: docker start aa3dac85e7ed -> healthy and back in HAProxy (api1 UP, api2 UP)
=== run 2: containers before (HAProxy: api1 UP, api2 UP)
SERVICE CONTAINER STATE STARTED AT (UTC)
api 1c773748bc05 running (healthy) 2026-10-15T16:32:38.776
api aa3dac85e7ed running (healthy) 2026-10-15T16:36:08.417
lb f9c8bda9ea4c running (healthy) 2026-10-15T16:32:39.190
migrate 7420f3f1ddda exited 2026-10-15T16:32:47.434
postgres 5c16b9b684f2 running (healthy) 2026-10-15T16:35:06.670
valkey c74935587700 running (healthy) 2026-10-15T16:34:57.760
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.␍
{"observed_instances_before": 2, "successful_writes": 125, "failed_attempts": 0, "first_recovery_seconds": 4.843}␍
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
containers after (HAProxy: api2 UP)
SERVICE CONTAINER STATE STARTED AT (UTC)
api 1c773748bc05 exited 2026-10-15T16:32:38.776
api aa3dac85e7ed running (healthy) 2026-10-15T16:36:08.417
lb f9c8bda9ea4c running (healthy) 2026-10-15T16:32:39.190
migrate 7420f3f1ddda exited 2026-10-15T16:32:47.434
postgres 5c16b9b684f2 running (healthy) 2026-10-15T16:35:06.670
valkey c74935587700 running (healthy) 2026-10-15T16:34:57.760
the hook stopped 1c773748bc05 (X-Instance-Id of that replica = container ID); other api containers, postgres, valkey and lb kept running
restored: docker start 1c773748bc05 -> healthy and back in HAProxy (api1 UP, api2 UP)
PASS: public failover test passed 2 times; every api replica was stopped once and restored
+11
View File
@@ -0,0 +1,11 @@
python student-tests/dependency_failure.py postgres
stopping postgres (docker compose stop postgres)
HAProxy вывел все реплики из балансировки через 2.8 с после остановки PostgreSQL (api1 DOWN, api2 DOWN)
реплика 1c773748bc05 изнутри контейнера: /health/live -> 200, /health/ready -> 503 (жива, но не готова)
реплика aa3dac85e7ed изнутри контейнера: /health/live -> 200, /health/ready -> 503 (жива, но не готова)
GET /users/me с действующим токеном (он есть в кэше) -> 503 от балансировщика, без X-Instance-Id: до неготовой реплики запрос не дошёл
бизнес-запросы (список чатов, история, отправка сообщения) -> 503 от балансировщика
без токена, регистрация и /health/ready через балансировщик -> 503: успешного ответа нет ни у кого
starting postgres again
after recovery: прежний токен работает, подтверждённые сообщения на месте
PASS: postgres outage: not ready replicas were excluded by the balancer, no request reached them, nothing was stored; data and the existing token survived
+7
View File
@@ -0,0 +1,7 @@
python student-tests/cache_revocation.py
pausing valkey (docker compose pause valkey): данные в кэше сохраняются
во время паузы: logout -> 204, тот же токен -> 401
unpausing valkey
после unpause: 23 проверок за 12 с, отозванный токен всегда 401 (и GET, и POST)
действующие токены других пользователей работают
PASS: revoked session stays revoked after Valkey comes back with stale data
+12
View File
@@ -0,0 +1,12 @@
python student-tests/dependency_failure.py valkey
stopping valkey (docker compose stop valkey)
/health/ready -> 200 (15 ms): Valkey не критичен, API готов
existing token: GET /users/me -> 200 (0 ms), сессия проверена по PostgreSQL (этот запрос и обнаружил сбой кэша)
POST message -> 201, история читается
register + login new user -> 201
logout -> 204, затем тот же токен -> 401 (отзыв записан в PostgreSQL)
10 x GET /users/me без кэша: max 16 ms (кэш не ждём на каждом запросе)
через 6 с, ещё 10 x GET /users/me: max 31 ms (повторные попытки — в фоне)
starting valkey again
after recovery: прежний токен работает, подтверждённые сообщения на месте
PASS: valkey outage handled without the cache; revoked tokens stay revoked
+26
View File
@@ -0,0 +1,26 @@
python student-tests/load_profile.py
{␍
"lab": 3,␍
"workload": "closed-loop POST messages; no automatic retries",␍
"requested_duration_seconds": 30.0,␍
"elapsed_seconds": 30.25,␍
"concurrency": 4,␍
"successful_requests": 3934,␍
"failed_requests": 0,␍
"error_ratio": 0.0,␍
"successful_rps": 130.05,␍
"successful_latency_ms": {␍
"p50": 16.0,␍
"p95": 78.0,␍
"p99": 141.0␍
},␍
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."␍
}
service cpu % max RAM max / limit, MiB
api 97.5 83.3 / 512
api 90.2 122.3 / 512
lb 24.2 19.6 / 128
postgres 31.1 51.5 / 512
valkey 9.6 8.3 / 128
PASS: load profile saved to evidence/load.json and evidence/load-stats.json
+36
View File
@@ -0,0 +1,36 @@
{
"duration_seconds": 30,
"concurrency": 4,
"containers": [
{
"service": "api",
"cpu_percent_max": 97.47,
"mem_mib_max": 83.3,
"mem_limit_mib": 512
},
{
"service": "api",
"cpu_percent_max": 90.24,
"mem_mib_max": 122.3,
"mem_limit_mib": 512
},
{
"service": "lb",
"cpu_percent_max": 24.22,
"mem_mib_max": 19.6,
"mem_limit_mib": 128
},
{
"service": "postgres",
"cpu_percent_max": 31.15,
"mem_mib_max": 51.5,
"mem_limit_mib": 512
},
{
"service": "valkey",
"cpu_percent_max": 9.56,
"mem_mib_max": 8.3,
"mem_limit_mib": 128
}
]
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30.0,
"elapsed_seconds": 30.25,
"concurrency": 4,
"successful_requests": 3934,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 130.05,
"successful_latency_ms": {
"p50": 16.0,
"p95": 78.0,
"p99": 141.0
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+26
View File
@@ -0,0 +1,26 @@
python student-tests/run_persistence.py
hook: scripts/restart.cmd
=== containers before
SERVICE CONTAINER STATE STARTED AT (UTC)
api 1c773748bc05 running (healthy) 2026-10-15T16:36:31.798
api aa3dac85e7ed running (healthy) 2026-10-15T16:36:08.417
lb f9c8bda9ea4c running (healthy) 2026-10-15T16:32:39.190
migrate 7420f3f1ddda exited 2026-10-15T16:32:47.434
postgres 5c16b9b684f2 running (healthy) 2026-10-15T16:35:06.670
valkey c74935587700 running (healthy) 2026-10-15T16:34:57.760
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.␍
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
=== containers after (test took 19.6 s: hook + waiting for readiness + data checks)
SERVICE CONTAINER STATE STARTED AT (UTC)
api 1c773748bc05 running (healthy) 2026-10-15T16:36:52.431
api aa3dac85e7ed running (healthy) 2026-10-15T16:36:52.088
lb f9c8bda9ea4c running (healthy) 2026-10-15T16:36:56.814
migrate 7420f3f1ddda exited 2026-10-15T16:36:50.153
postgres 5c16b9b684f2 running (healthy) 2026-10-15T16:36:44.391
valkey c74935587700 running (healthy) 2026-10-15T16:36:44.221
api aa3dac85e7ed: same container, start time 16:36:08 -> 16:36:52
api 1c773748bc05: same container, start time 16:36:31 -> 16:36:52
lb f9c8bda9ea4c: same container, start time 16:32:39 -> 16:36:56
postgres 5c16b9b684f2: same container, start time 16:35:06 -> 16:36:44
valkey c74935587700: same container, start time 16:34:57 -> 16:36:44
PASS: api replicas, postgres, valkey and lb were restarted (same containers and volumes, new start time); data and the existing token survived
+6
View File
@@ -0,0 +1,6 @@
python student-tests/race.py
messages: sent 100 from 10 parallel clients in 1.55s
messages: read 100 in 4 pages, unique ids: 100
PASS: 100 concurrent messages stored without loss or duplicates
registration: 20 parallel requests for one username -> 201 x1, 409 x19
PASS: concurrent registration of the same username created exactly one user
+51
View File
@@ -0,0 +1,51 @@
{
"from_version": "dev",
"to_version": "rolling-20261015-193851",
"replicas": 2,
"profile": {
"writers": 4,
"readers": 1,
"client_timeout_seconds": 2
},
"steps": [
{
"old": "1c773748bc05",
"new": "e8baa1b553a1",
"new_ready_seconds": 6.64,
"step_seconds": 11.8
},
{
"old": "aa3dac85e7ed",
"new": "db0d1f669f44",
"new_ready_seconds": 5.89,
"step_seconds": 10.55
}
],
"update_seconds": 22.38,
"before": {
"seconds": 3.0,
"write_rps": 104.3,
"reads": 33,
"errors": 0,
"error_codes": {},
"write_p50_ms": 31.0,
"write_p95_ms": 94.0,
"write_max_ms": 157.0
},
"during": {
"seconds": 22.38,
"write_rps": 138.7,
"reads": 277,
"errors": 0,
"error_codes": {},
"write_p50_ms": 16.0,
"write_p95_ms": 63.0,
"write_max_ms": 312.0
},
"integrity": {
"confirmed_writes": 3867,
"messages_in_history": 3867,
"duplicates": 0,
"lost": 0
}
}
+10
View File
@@ -0,0 +1,10 @@
python student-tests/rolling_update.py
old replicas ['1c773748bc05', 'aa3dac85e7ed'], version dev; building version rolling-20261015-193851
image built in 3.8 s
migrations (one run, before replacing replicas): Миграции: новых нет, схема актуальна
replaced 1c773748bc05 -> e8baa1b553a1: new replica healthy and UP in HAProxy after 6.6 s, then the old one drained and stopped; step 11.8 s (HAProxy: api1 DOWN, api2 UP, api3 UP)
replaced aa3dac85e7ed -> db0d1f669f44: new replica healthy and UP in HAProxy after 5.9 s, then the old one drained and stopped; step 10.55 s (HAProxy: api1 UP, api2 DOWN, api3 UP)
now: replicas ['db0d1f669f44', 'e8baa1b553a1'], versions ['rolling-20261015-193851']
under load: write RPS before 104.3, during the update 138.7; errors 0 {}; p95 63.0 ms, max 312.0 ms; update took 22.4 s
confirmed 3867, in history 3867, lost 0, duplicates 0
PASS: all 2 replicas replaced one by one under load, 0 errors, no lost or duplicated messages; saved evidence/rolling-update.json
+36
View File
@@ -0,0 +1,36 @@
python student-tests/check_stack.py
docker: 29.6.2
compose: 5.3.1
container_name: not set for any service (replicas of one service are possible)
api replicas running: 2 -> ['1c773748bc05', 'aa3dac85e7ed'] (deploy.replicas = 2)
service container cpus memory published ports networks
api 1c773748bc05 1.00 512Mi - backend, edge
postgres 5c16b9b684f2 1.00 512Mi - backend
api aa3dac85e7ed 1.00 512Mi - backend, edge
valkey c74935587700 0.50 128Mi - backend
lb f9c8bda9ea4c 0.50 128Mi 127.0.0.1:8080->8080/tcp, 127.0.0.1:8081->8081/tcp, 127.0.0.1:8404->8404/tcp edge
published: only lb, only on 127.0.0.1 (api replicas have no ports)
balancer: every api server is under the /health/ready check, no backup servers -> api1 UP (L7OK), api2 UP (L7OK)
limits: every running container has CPU and RAM limits
networks: lb -> edge; api -> edge + backend; postgres, valkey -> backend (internal: no way out)
secrets: api -> cache_url, database_url; migrate -> database_url; lb -> none; postgres -> postgres_password; valkey -> valkey_acl
images: lb haproxy:3.2.25-alpine; api mtusi-messenger:lab3; postgres postgres:17.10-bookworm; valkey valkey/valkey:8.1.9
PASS: one entry point (lb on 127.0.0.1), >= 2 api replicas without ports and container_name, only ready replicas get traffic, CPU/RAM limits everywhere, stores only on the internal network
docker compose ps -a --format "table {{.Service}}\t{{.ID}}\t{{.Status}}"
SERVICE CONTAINER ID STATUS
api aa3dac85e7ed Up About a minute (healthy)
api 1c773748bc05 Up About a minute (healthy)
lb f9c8bda9ea4c Up About a minute (healthy)
migrate 7420f3f1ddda Exited (0) About a minute ago
postgres 5c16b9b684f2 Up 30 seconds (healthy)
valkey c74935587700 Up 8 minutes (healthy)
api-3 | 2026-10-15 16:32:41,372 INFO messenger.db: Схема БД актуальна (миграции применены сервисом migrate)
api-3 | 2026-10-15 16:32:41,376 INFO messenger: Реплика aa3dac85e7ed запущена: версия dev, env=lab, TTL сессии=3600 c, кэш сессий: Valkey
migrate-1 | 2026-10-15 16:32:37,955 INFO messenger.db: Миграции: новых нет, схема актуальна
migrate-1 | 2026-10-15 16:32:49,046 INFO messenger.db: Миграции: новых нет, схема актуальна
api-4 | 2026-10-15 16:32:41,595 INFO messenger.db: Схема БД актуальна (миграции применены сервисом migrate)
api-4 | 2026-10-15 16:32:41,600 INFO messenger: Реплика 1c773748bc05 запущена: версия dev, env=lab, TTL сессии=3600 c, кэш сессий: Valkey
.gitignore:2:.env .env
.gitignore:5:secrets/ secrets/database_url
+70
View File
@@ -0,0 +1,70 @@
python -m unittest discover -s student-tests -p "test_*.py" -v
test_auth_checked_before_access_and_body (test_api.MessengerApiTest.test_auth_checked_before_access_and_body) ... ok
test_bad_cursor_returns_400 (test_api.MessengerApiTest.test_bad_cursor_returns_400) ... ok
test_chat_list_pagination (test_api.MessengerApiTest.test_chat_list_pagination) ... ok
test_chat_membership_rules (test_api.MessengerApiTest.test_chat_membership_rules) ... ok
test_duplicate_username_returns_409 (test_api.MessengerApiTest.test_duplicate_username_returns_409) ... ok
test_empty_blank_and_too_long_messages_return_400 (test_api.MessengerApiTest.test_empty_blank_and_too_long_messages_return_400) ... ok
test_malformed_json_returns_400 (test_api.MessengerApiTest.test_malformed_json_returns_400) ... ok
test_nul_character_is_stored (test_api.MessengerApiTest.test_nul_character_is_stored) ... ok
test_outsider_gets_404_for_foreign_chat (test_api.MessengerApiTest.test_outsider_gets_404_for_foreign_chat) ... ok
test_pagination_walks_several_pages (test_api.MessengerApiTest.test_pagination_walks_several_pages) ... ok
test_unicode_roundtrip (test_api.MessengerApiTest.test_unicode_roundtrip) ... ok
test_wrong_types_and_extra_fields_return_400 (test_api.MessengerApiTest.test_wrong_types_and_extra_fields_return_400) ... ok
test_bearer_required_on_business_endpoints (test_auth.AuthTest.test_bearer_required_on_business_endpoints) ... ok
test_login_returns_opaque_token_with_expiry (test_auth.AuthTest.test_login_returns_opaque_token_with_expiry) ... ok
test_logout_revokes_only_current_session (test_auth.AuthTest.test_logout_revokes_only_current_session) ... ok
test_malformed_basic_returns_401 (test_auth.AuthTest.test_malformed_basic_returns_401) ... ok
test_password_length_rules (test_auth.AuthTest.test_password_length_rules) ... ok
test_password_with_colon_and_unicode (test_auth.AuthTest.test_password_with_colon_and_unicode) ... ok
test_relogin_after_logout (test_auth.AuthTest.test_relogin_after_logout) ... ok
test_user_never_contains_password (test_auth.AuthTest.test_user_never_contains_password) ... ok
test_wrong_password_and_unknown_user_look_the_same (test_auth.AuthTest.test_wrong_password_and_unknown_user_look_the_same) ... ok
test_x_user_id_does_not_change_identity (test_auth.AuthTest.test_x_user_id_does_not_change_identity) ... ok
test_instance_id_on_errors_and_health (test_balancing.BalancingTest.test_instance_id_on_errors_and_health) ... ok
test_logout_applies_on_every_replica (test_balancing.BalancingTest.test_logout_applies_on_every_replica) ... ok
test_one_session_is_served_by_every_replica (test_balancing.BalancingTest.test_one_session_is_served_by_every_replica) ... ok
test_session_cache_is_shared_between_replicas (test_balancing.BalancingTest.test_session_cache_is_shared_between_replicas) ... ok
test_write_on_one_replica_read_on_another (test_balancing.BalancingTest.test_write_on_one_replica_read_on_another) ... ok
test_failed_request_does_not_burn_key (test_idempotency.IdempotencyTest.test_failed_request_does_not_burn_key) ... ok
test_json_formatting_does_not_matter (test_idempotency.IdempotencyTest.test_json_formatting_does_not_matter) ... ok
test_key_is_required_and_validated (test_idempotency.IdempotencyTest.test_key_is_required_and_validated) ... ok
test_key_scope_is_user_and_chat (test_idempotency.IdempotencyTest.test_key_scope_is_user_and_chat) ... ok
test_parallel_different_bodies_same_key (test_idempotency.IdempotencyTest.test_parallel_different_bodies_same_key) ... ok
test_parallel_same_key_through_replicas_creates_one_message (test_idempotency.IdempotencyTest.test_parallel_same_key_through_replicas_creates_one_message) ... ok
test_replay_rechecks_session_and_access (test_idempotency.IdempotencyTest.test_replay_rechecks_session_and_access) ... ok
test_replay_through_another_replica_returns_same_message (test_idempotency.IdempotencyTest.test_replay_through_another_replica_returns_same_message) ... ok
test_same_key_other_body_is_409 (test_idempotency.IdempotencyTest.test_same_key_other_body_is_409) ... ok
----------------------------------------------------------------------
Ran 36 tests in 11.028s
OK
X-Instance-Id есть в health, 404, 401 и 400
logout через одну реплику -> 401 на ['1c773748bc05', 'aa3dac85e7ed']
20 x GET /users/me с одним токеном -> реплики {'aa3dac85e7ed': 10, '1c773748bc05': 10}; это ID запущенных контейнеров api, повторный вход не нужен
10 x GET /users/me через реплики {'aa3dac85e7ed': 5, '1c773748bc05': 5}: попаданий в кэш +20, промахов +0 — кэш общий
сообщение записала реплика aa3dac85e7ed, сразу прочитали ['1c773748bc05', 'aa3dac85e7ed']
с тем же ключом: сначала 400 (пустой текст), потом 201 — ошибка ключ не заняла
тот же JSON с другими пробелами и переносами -> тот же 201 и то же сообщение
нет ключа, пустой, 129 символов, пробел, '/', кириллица -> 400; 128 символов и ._:- -> 201
тот же ключ у другого пользователя и в другом чате -> независимые сообщения
10 одновременных разных тел с одним ключом: 201 x1, 409 x9, в истории 1 сообщение
20 одновременных POST с одним ключом через реплики {'1c773748bc05': 10, 'aa3dac85e7ed': 10}: все 201 с одним id, в истории 1 сообщение
повтор: посторонний -> 404, после logout -> 401, после нового входа -> то же сообщение
1 запрос + 4 повтора через реплики ['1c773748bc05', 'aa3dac85e7ed']: 201 и то же сообщение, в истории 1
другой текст с тем же ключом -> 409 conflict, второе сообщение не создано
+2
View File
@@ -0,0 +1,2 @@
python tests/smoke.py --base-url "http://127.0.0.1:8080"
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
+8
View File
@@ -0,0 +1,8 @@
docker compose exec -T valkey valkey-cli --user health --pass none --no-auth-warning dbsize
6
docker compose exec -T valkey valkey-cli --user health --pass none --no-auth-warning info stats | grep -E "keyspace_(hits|misses)"
keyspace_hits:105
keyspace_misses:1
docker compose exec -T valkey valkey-cli --user health --pass none --no-auth-warning get sess:anything
NOPERM User health has no permissions to run the 'get' command
+91
View File
@@ -0,0 +1,91 @@
# HAProxy — балансировщик и единственная точка входа стенда lab3.
# Клиент -> 127.0.0.1:8080 -> HAProxy -> одна из реплик api (порт 8080 внутри сети edge).
# Данные и сессии общие (PostgreSQL, Valkey), поэтому любой запрос может обслужить любая
# реплика: балансировка round robin, без привязки клиента к реплике (без sticky session).
global
log stdout format raw local0 info
maxconn 2000
# При остановке контейнера (SIGUSR1, мягкая остановка) доделать начатые запросы, но не дольше 10 с.
hard-stop-after 10s
# Список реплик берётся из DNS Docker: имя сервиса "api" -> IP всех ЗАПУЩЕННЫХ реплик.
# Остановили реплику или добавили новую — HAProxy увидит это сам, без перезапуска.
resolvers docker
nameserver dns 127.0.0.11:53
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 2s # перечитывать список реплик раз в 2 с
hold obsolete 2s # IP, пропавший из DNS (контейнер остановлен), убрать через 2 с
hold nx 2s
hold other 2s
hold refused 2s
hold timeout 2s
accepted_payload_size 8192
defaults
mode http
log global
option httplog
option dontlog-normal # в лог только ошибки и смены состояния реплик, а не каждый запрос
timeout connect 1s # сеть внутри Docker быстрая: мёртвый адрес не держит запрос дольше 1 с
timeout client 30s
timeout server 15s # дольше самого долгого ответа API (8 с: пул 3 с + statement_timeout 5 с)
timeout http-request 10s
timeout http-keep-alive 5s
timeout queue 5s
timeout check 1s
# Ошибка СОЕДИНЕНИЯ (запрос ещё не отправлен) — повторить, причём на другой реплике.
# Это безопасно для любого метода. Запрос, который уже ушёл в API, HAProxy сам НЕ повторяет:
# POST сообщения повторяет клиент с тем же Idempotency-Key.
retries 2
option redispatch 1
# Ошибки, которые создаёт сам балансировщик (нет ни одной готовой реплики — 503, реплика оборвала
# соединение — 502, не ответила вовремя — 504), отдаются в формате ошибки из контракта
# с X-Request-Id. X-Instance-Id у них нет: ни одна реплика API этот ответ не создавала.
unique-id-format %[uuid]
http-error status 503 content-type application/json lf-string '{"error":{"code":"unavailable","message":"Нет готовой реплики API, повторите запрос позже","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
http-error status 502 content-type application/json lf-string '{"error":{"code":"unavailable","message":"Реплика API оборвала соединение, повторите запрос","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 не ответила вовремя, повторите запрос","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
frontend api_in
bind :8080
default_backend api
backend api
balance roundrobin
# Проверка готовности: /health/ready = процесс отвечает, PostgreSQL доступна, нет SIGTERM.
option httpchk
http-check send meth GET uri /health/ready ver HTTP/1.1 hdr Host lb
http-check expect status 200
# До 6 реплик (обычно 2, во время rolling update 3); пустые слоты стоят в MAINT.
# Проверка раз в 1 с, при смене состояния раз в 0,5 с; 2 неудачи подряд -> DOWN, 2 удачи -> UP.
# observe layer4: первая же ошибка соединения у живого запроса сразу выводит реплику из балансировки.
# Запросы получают ТОЛЬКО реплики, прошедшие проверку готовности. Резервных слотов без проверки нет:
# если не готова ни одна реплика (например, недоступна PostgreSQL), балансировщик сам отвечает 503
# и никуда запрос не передаёт, даже если реплика могла бы ответить из кэша.
server-template api 6 api:8080 check inter 1s fastinter 500ms downinter 2s fall 2 rise 2 observe layer4 error-limit 1 on-error mark-down resolvers docker resolve-prefer ipv4 init-addr none
# Второй вход только для проверки истечения сессии (make expiry): API с SESSION_TTL_SECONDS=2
# (сервис api-short-ttl, профиль ttl). Он тоже доступен только через балансировщик.
frontend ttl_in
bind :8081
default_backend api_short_ttl
backend api_short_ttl
option httpchk
http-check send meth GET uri /health/ready ver HTTP/1.1 hdr Host lb
http-check expect status 200
server-template ttl 2 api-short-ttl:8080 check inter 1s fall 2 rise 2 resolvers docker resolve-prefer ipv4 init-addr none
# Статистика HAProxy: http://127.0.0.1:8404/stats (только на 127.0.0.1 хоста, только чтение).
# Там видно, какие реплики UP/DOWN. /lb-health — healthcheck контейнера lb:
# 503, пока в backend api нет ни одной готовой реплики.
frontend stats
bind :8404
monitor-uri /lb-health
monitor fail if { nbsrv(api) lt 1 }
stats enable
stats uri /stats
stats refresh 2s
+74
View File
@@ -0,0 +1,74 @@
-- Обоснование индекса истории сообщений: EXPLAIN (ANALYZE, BUFFERS) на синтетических данных.
-- Запуск: make explain > evidence/explain-history.txt
-- (= docker compose exec -T postgres psql -U messenger -d messenger < infra/sql/explain_history.sql)
--
-- Всё выполняется в одной транзакции и в конце откатывается (ROLLBACK):
-- синтетические данные не остаются в базе, скрипт можно запускать сколько угодно раз.
-- DROP INDEX внутри транзакции на время скрипта блокирует запись в messages — запускать на учебном стенде.
\pset footer off
BEGIN;
-- 1 «большой» чат на 12 000 сообщений и 19 чатов по 500 (всего 21 500 сообщений):
-- в таблице есть чужие сообщения, как в настоящей базе.
CREATE TEMP TABLE seed_chats AS
SELECT gen_random_uuid() AS chat_id, n, CASE WHEN n = 0 THEN 12000 ELSE 500 END AS size
FROM generate_series(0, 19) AS n;
CREATE TEMP TABLE seed_user AS SELECT gen_random_uuid() AS user_id;
INSERT INTO users (id, username, display_name, password_hash)
SELECT user_id, 'explain_' || substr(md5(random()::text), 1, 12), convert_to('EXPLAIN', 'UTF8'), 'not-a-real-hash' FROM seed_user;
INSERT INTO chats (id, title) SELECT chat_id, convert_to('explain ' || n, 'UTF8') FROM seed_chats;
INSERT INTO chat_members (chat_id, user_id) SELECT chat_id, user_id FROM seed_chats, seed_user;
INSERT INTO messages (id, chat_id, sender_id, text, created_at)
SELECT gen_random_uuid(), c.chat_id, u.user_id, convert_to('synthetic message ' || g, 'UTF8'),
timestamptz '2026-01-01 00:00:00+00' + g * interval '1 second'
FROM seed_chats c, seed_user u, generate_series(1, c.size) AS g;
ANALYZE messages;
SELECT chat_id AS big_chat FROM seed_chats WHERE n = 0 \gset
-- Курсор «середины истории»: ключ (created_at, id) 6000-го сообщения большого чата.
SELECT created_at AS cur_ts, id AS cur_id FROM messages
WHERE chat_id = :'big_chat' ORDER BY created_at, id OFFSET 5999 LIMIT 1 \gset
\echo '=== Объём данных'
SELECT count(*) AS messages_total,
count(*) FILTER (WHERE chat_id = :'big_chat') AS messages_in_big_chat
FROM messages;
\echo ''
\echo '=== Индекс истории (migrations/001_core.sql)'
SELECT indexdef FROM pg_indexes WHERE indexname = 'messages_chat_history_idx';
\echo ''
\echo '=== 1. Первая страница (limit=50, приложение просит 51 строку, чтобы понять, есть ли следующая)'
EXPLAIN (ANALYZE, BUFFERS, COSTS OFF)
SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = :'big_chat'
ORDER BY created_at, id LIMIT 51;
\echo ''
\echo '=== 2. Страница из середины истории по keyset-курсору (после 6000-го сообщения)'
EXPLAIN (ANALYZE, BUFFERS, COSTS OFF)
SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = :'big_chat' AND (created_at, id) > (:'cur_ts'::timestamptz, :'cur_id'::uuid)
ORDER BY created_at, id LIMIT 51;
\echo ''
\echo '=== 3. Для сравнения: та же страница через OFFSET (так приложение НЕ делает)'
EXPLAIN (ANALYZE, BUFFERS, COSTS OFF)
SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = :'big_chat'
ORDER BY created_at, id OFFSET 6000 LIMIT 51;
\echo ''
\echo '=== 4. Для сравнения: запрос 2 без индекса (индекс удалён только внутри этой транзакции)'
DROP INDEX messages_chat_history_idx;
EXPLAIN (ANALYZE, BUFFERS, COSTS OFF)
SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = :'big_chat' AND (created_at, id) > (:'cur_ts'::timestamptz, :'cur_id'::uuid)
ORDER BY created_at, id LIMIT 51;
ROLLBACK;
\echo ''
\echo '=== ROLLBACK: синтетические данные удалены, индекс на месте'
+22
View File
@@ -0,0 +1,22 @@
# Valkey в этой работе — КЭШ сессий, один на все реплики API. Источник истины — таблица
# sessions в PostgreSQL. Поэтому persistence выключена: после рестарта кэш пустой,
# данные заново берутся из БД.
bind 0.0.0.0
port 6379
protected-mode yes
# Пользователи и пароли — в секрете (scripts/init-secrets.sh создаёт secrets/valkey_users.acl):
# default — выключен (анонимный доступ запрещён);
# health — без пароля, только ping/info/dbsize (для healthcheck и наблюдения);
# messenger — пароль, только ключи sess:* и только команды get/mget/set/del/ping.
aclfile /run/secrets/valkey_acl
# Без сохранения на диск: ни RDB-снимков, ни AOF.
save ""
appendonly no
# Ограничение памяти. При нехватке выбрасываются давно не читанные записи С TTL (это все
# записи о сессиях). Ключ sess:gen (общее поколение кэша) без TTL и поэтому не выбрасывается.
maxmemory 64mb
maxmemory-policy volatile-lru
+45
View File
@@ -0,0 +1,45 @@
-- 001: пользователи, чаты, участники, сообщения.
-- Применяется один раз; номер версии записывается в schema_migrations (см. src/messenger/db.py).
-- Все проверки, которые важны для целостности, продублированы в базе: даже если в коде
-- появится ошибка, PostgreSQL не даст записать некорректные данные.
CREATE TABLE users (
id uuid PRIMARY KEY,
username text NOT NULL,
display_name text NOT NULL,
password_hash text NOT NULL, -- строка Argon2id ($argon2id$...), не сам пароль
created_at timestamptz NOT NULL DEFAULT now(),
CONSTRAINT users_username_key UNIQUE (username), -- защищает от гонки двух регистраций
CONSTRAINT users_username_format CHECK (username ~ '^[a-z0-9_]{3,32}$'),
CONSTRAINT users_display_name_len CHECK (char_length(display_name) BETWEEN 1 AND 100)
);
CREATE TABLE chats (
id uuid PRIMARY KEY,
title text NOT NULL CHECK (char_length(title) BETWEEN 1 AND 100),
created_at timestamptz NOT NULL DEFAULT now()
);
-- Членство: какой пользователь в каком чате. Первичный ключ исключает дубликаты.
CREATE TABLE chat_members (
chat_id uuid NOT NULL REFERENCES chats (id),
user_id uuid NOT NULL REFERENCES users (id),
PRIMARY KEY (chat_id, user_id)
);
-- «Список чатов пользователя»: поиск по user_id (PK начинается с chat_id и тут не помогает).
CREATE INDEX chat_members_user_idx ON chat_members (user_id, chat_id);
CREATE TABLE messages (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL,
sender_id uuid NOT NULL,
text text NOT NULL CHECK (char_length(text) BETWEEN 1 AND 4000),
created_at timestamptz NOT NULL DEFAULT now(),
-- Отправитель обязан быть участником этого чата: внешний ключ на пару (чат, участник).
CONSTRAINT messages_sender_is_member FOREIGN KEY (chat_id, sender_id)
REFERENCES chat_members (chat_id, user_id)
);
-- История чата: WHERE chat_id = ? AND (created_at, id) > (?, ?) ORDER BY created_at, id LIMIT ?
-- Индекс уже отсортирован в нужном порядке, поэтому страница читается без сортировки
-- и без просмотра всей истории. Обоснование и EXPLAIN: evidence/explain-history.txt.
CREATE INDEX messages_chat_history_idx ON messages (chat_id, created_at, id);
+13
View File
@@ -0,0 +1,13 @@
-- 002: серверные сессии (источник истины для Bearer-токенов).
-- Хранится не сам токен, а его SHA-256: утечка таблицы не даёт рабочих токенов.
CREATE TABLE sessions (
token_hash bytea PRIMARY KEY CHECK (octet_length(token_hash) = 32),
user_id uuid NOT NULL REFERENCES users (id),
created_at timestamptz NOT NULL DEFAULT now(),
expires_at timestamptz NOT NULL, -- абсолютное время: рестарт не продлевает сессию
revoked_at timestamptz, -- заполнено = logout
CONSTRAINT sessions_expiry_after_creation CHECK (expires_at > created_at)
);
-- Очистка старых сессий пользователя при входе (DELETE ... WHERE user_id = ?).
CREATE INDEX sessions_user_idx ON sessions (user_id);
+28
View File
@@ -0,0 +1,28 @@
-- 003: свободный текст хранится как байты UTF-8 (bytea), а не как text.
--
-- Причина: тип text в PostgreSQL не может содержать символ U+0000 (байт 0x00), а контракт
-- этот символ в display_name, title и text не запрещает. Строка "hello\u0000world" давала 500.
-- В bytea байт 0x00 допустим, поэтому такие строки теперь сохраняются и возвращаются без изменений.
-- Кодирование/декодирование UTF-8 — в src/messenger/store.py (to_db/from_db).
--
-- Это новая миграция, а не правка 001: 001 уже применена на существующих стендах.
-- Уже сохранённые данные переводятся через convert_to и не теряются.
--
-- Точное число символов (1–100, 1–4000) проверяет API. Функции PostgreSQL, которые считают
-- символы в bytea, отвергают байт 0x00, поэтому CHECK в базе ограничивает длину в байтах:
-- не пусто и не больше 4 байт на символ (максимальный размер символа в UTF-8).
ALTER TABLE users DROP CONSTRAINT users_display_name_len;
ALTER TABLE users ALTER COLUMN display_name TYPE bytea USING convert_to(display_name, 'UTF8');
ALTER TABLE users ADD CONSTRAINT users_display_name_len
CHECK (octet_length(display_name) BETWEEN 1 AND 400);
ALTER TABLE chats DROP CONSTRAINT chats_title_check;
ALTER TABLE chats ALTER COLUMN title TYPE bytea USING convert_to(title, 'UTF8');
ALTER TABLE chats ADD CONSTRAINT chats_title_len
CHECK (octet_length(title) BETWEEN 1 AND 400);
ALTER TABLE messages DROP CONSTRAINT messages_text_check;
ALTER TABLE messages ALTER COLUMN text TYPE bytea USING convert_to(text, 'UTF8');
ALTER TABLE messages ADD CONSTRAINT messages_text_len
CHECK (octet_length(text) BETWEEN 1 AND 16000);
+30
View File
@@ -0,0 +1,30 @@
-- 004 (lab3): идемпотентность отправки сообщения (заголовок Idempotency-Key).
--
-- Ключ и SHA-256 тела запроса хранятся прямо в строке сообщения. Уникальное ограничение
-- (chat_id, sender_id, idempotency_key) = область ключа из контракта: пользователь + чат
-- (метод и путь у этого ключа всегда POST /chats/{id}/messages). Повтор с тем же ключом
-- не может создать второе сообщение даже при одновременных запросах через разные реплики.
-- Ключ живёт столько же, сколько сообщение (бессрочно; контракт требует не меньше 24 ч).
--
-- Совместимость с уже работающей версией (lab2): добавляются только НОВЫЕ столбцы,
-- которые могут быть NULL. Старый код пишет сообщения без ключа (NULL) и читает только
-- свои столбцы — он продолжает работать с новой схемой. Строки без ключа уникальность
-- не нарушают: в PostgreSQL значения NULL не считаются одинаковыми.
-- Ограничение: на большой таблице построение уникального индекса блокирует запись в messages.
-- Для большой базы индекс строят заранее через CREATE UNIQUE INDEX CONCURRENTLY (вне транзакции),
-- а затем добавляют ограничение USING INDEX. На учебной базе это доли секунды.
ALTER TABLE messages
ADD COLUMN idempotency_key text,
ADD COLUMN request_hash bytea;
ALTER TABLE messages
ADD CONSTRAINT messages_idempotency_key_format
CHECK (idempotency_key ~ '^[A-Za-z0-9._:-]{1,128}$'),
ADD CONSTRAINT messages_request_hash_len
CHECK (octet_length(request_hash) = 32),
-- ключ и отпечаток тела всегда вместе: оба заданы или оба NULL
ADD CONSTRAINT messages_key_with_hash
CHECK ((idempotency_key IS NULL) = (request_hash IS NULL)),
ADD CONSTRAINT messages_idempotency_unique
UNIQUE (chat_id, sender_id, idempotency_key);
+22
View File
@@ -0,0 +1,22 @@
# Все зависимости закреплены точными версиями (включая транзитивные),
# чтобы сборка образа через месяц дала то же самое, что сегодня.
annotated-types==0.8.0
anyio==4.15.1
argon2-cffi==25.1.0 # Argon2id для паролей
argon2-cffi-bindings==26.1.0
cffi==2.1.1
click==8.5.0
fastapi==0.115.12
h11==0.16.0
idna==3.20
psycopg==3.3.6 # драйвер PostgreSQL
psycopg-binary==3.3.6
psycopg-pool==3.3.3 # пул соединений
pycparser==3.1
pydantic==2.13.5
pydantic_core==2.46.5
starlette==0.46.2
typing-inspection==0.4.4
typing_extensions==4.16.0
uvicorn==0.34.3
valkey==6.1.1 # клиент Valkey (кэш сессий)
+35
View File
@@ -0,0 +1,35 @@
#!/bin/sh
# Создаёт локальные секреты стенда в каталоге secrets/ (он в .gitignore и в Git не попадает).
# Запуск один раз: sh scripts/init-secrets.sh
# Повторный запуск ничего не меняет: у уже созданного volume PostgreSQL пароль сменить так нельзя.
set -eu
cd "$(dirname "$0")/.."
if [ -e secrets/postgres_password ]; then
echo "secrets/ уже существует, оставляю как есть."
echo "Чтобы начать с нуля: docker compose down -v (удалит данные!), затем удалить secrets/ и запустить снова."
exit 0
fi
umask 077 # каталог secrets/ доступен только владельцу
mkdir -p secrets
# 24 случайных байта -> 48 hex-символов. /dev/urandom есть и в Linux/macOS, и в Git Bash.
random_hex() { od -An -tx1 -N24 /dev/urandom | tr -d ' \n'; }
PG_PASSWORD=$(random_hex)
CACHE_PASSWORD=$(random_hex)
# printf без перевода строки в конце: в файле только значение.
printf '%s' "$PG_PASSWORD" > secrets/postgres_password
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$PG_PASSWORD" > secrets/database_url
printf 'valkey://messenger:%s@valkey:6379/0' "$CACHE_PASSWORD" > secrets/cache_url
printf '%s\n' \
'user default off' \
'user health on nopass -@all +ping +info +dbsize' \
"user messenger on >$CACHE_PASSWORD ~sess:* resetchannels -@all +get +mget +set +del +ping" \
> secrets/valkey_users.acl
# Файлы читают процессы в контейнерах под своими пользователями (postgres, valkey, app),
# поэтому сами файлы доступны на чтение; посторонних на хосте не пускает каталог (700).
chmod 644 secrets/*
echo "Готово: secrets/postgres_password, database_url, cache_url, valkey_users.acl (значения не выводятся)."
+11
View File
@@ -0,0 +1,11 @@
@echo off
rem Windows restart hook for make test-persistence: same steps as scripts/restart.sh.
rem Python on Windows cannot run .sh directly (WinError 193), so this .cmd is used instead.
rem Restarts ALL api replicas and ALL stores (PostgreSQL, Valkey), then the balancer.
rem Volumes are kept (no down -v). Containers are the same (same ID, new start time).
cd /d "%~dp0.."
docker compose stop api || exit /b 1
docker compose restart postgres valkey || exit /b 1
docker compose start api || exit /b 1
docker compose restart lb || exit /b 1
exit /b 0
+12
View File
@@ -0,0 +1,12 @@
#!/bin/sh
# Restart hook для make test-persistence (Linux/macOS).
# Перезапускает ВСЕ реплики API и ВСЕ используемые хранилища (PostgreSQL, Valkey),
# а затем балансировщик. Volumes сохраняются: нет down -v, flush или повторного seed.
# Контейнеры те же (restart/stop/start, не recreate): ID не меняется, меняется время старта.
set -eu
cd "$(dirname "$0")/.."
docker compose stop api # все реплики: readiness 503 -> уход из балансировки -> выход
docker compose restart postgres valkey # корректная остановка (SIGINT/SIGTERM) и запуск тех же контейнеров
docker compose start api # реплики ждут готовности PostgreSQL и проверяют схему
docker compose restart lb # балансировщик заново находит реплики по DNS
+6
View File
@@ -0,0 +1,6 @@
@echo off
rem Failover hook for make test-failover on Windows (same as scripts/stop-one.sh).
rem Python on Windows cannot start .sh files directly (WinError 193), a .cmd file works.
rem Stops ONE api replica from TARGET_INSTANCE_ID; the logic is in scripts\stop_one.py.
python "%~dp0stop_one.py"
exit /b %ERRORLEVEL%
+9
View File
@@ -0,0 +1,9 @@
#!/bin/sh
# Failover hook для make test-failover (Linux/macOS): останавливает ОДНУ реплику API —
# ту, чей X-Instance-Id тест передал в TARGET_INSTANCE_ID, и оставляет её остановленной.
# Логика (проверка значения, поиск контейнера, docker stop) — в scripts/stop_one.py,
# общем для этого скрипта и для scripts/stop-one.cmd (Windows).
# Восстановить реплику после теста: make restore (docker compose up -d --wait).
set -eu
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
exec "${PYTHON:-python3}" "$(dirname "$0")/stop_one.py"
+49
View File
@@ -0,0 +1,49 @@
"""Failover hook logic for tests/resilience.py --mode failover (lab3).
Called by scripts/stop-one.sh (Linux/macOS) and scripts/stop-one.cmd (Windows).
The test puts X-Instance-Id of the replica that served its first message into
TARGET_INSTANCE_ID. In this solution X-Instance-Id is the container hostname, and
Docker sets the hostname to the short container ID. So the script finds that ID
among the RUNNING containers of the "api" service of this Compose project and
stops only that one container. Postgres, Valkey, the balancer and volumes are not
touched. The replica stays stopped; restore it with `make restore`
(docker compose up -d --wait) or `docker start <id>`.
docker stop sends SIGTERM: the replica first answers 503 on /health/ready for
SHUTDOWN_DRAIN_SECONDS (HAProxy takes it out of rotation), then finishes started
requests and exits. --time 8: SIGKILL after 8 s at most, so the hook always returns
within the 10 s the test allows.
This file is plain ASCII on purpose: scripts/check_contract.py reads every
scripts/*.py with the default encoding, which is cp1251 on a Russian Windows.
"""
import os
import re
import subprocess
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
STOP_TIMEOUT_SECONDS = 8
def main() -> int:
target = os.environ.get("TARGET_INSTANCE_ID", "").strip().lower()
# The value comes from an HTTP header: accept only a hex container ID, nothing else.
if not re.fullmatch(r"[0-9a-f]{12,64}", target):
print("TARGET_INSTANCE_ID must be a container id (X-Instance-Id)", file=sys.stderr)
return 2
running = subprocess.run(["docker", "compose", "ps", "-q", "api"], cwd=ROOT,
capture_output=True, text=True, check=True).stdout.split()
matches = [container for container in running if container.startswith(target)]
if len(matches) != 1:
print("no running api container with id " + target, file=sys.stderr)
return 1
subprocess.run(["docker", "stop", "--time", str(STOP_TIMEOUT_SECONDS), matches[0]],
cwd=ROOT, check=True, stdout=subprocess.DEVNULL)
print("stopped api container " + matches[0][:12])
return 0
if __name__ == "__main__":
sys.exit(main())
+1
View File
@@ -0,0 +1 @@
"""Учебный мессенджер МТУСИ: REST API по contracts/openapi.json, данные в PostgreSQL."""
+51
View File
@@ -0,0 +1,51 @@
"""Точка входа: `python -m messenger`.
В контейнере этот процесс — главный (PID 1) и сам получает SIGTERM от `docker stop`.
С lab3 остановка идёт в два шага, чтобы балансировщик успел увести трафик:
1. SIGTERM -> флаг draining: /health/ready сразу отвечает 503, но запросы ещё обслуживаются.
HAProxy видит 503 (проверка раз в 1 с, 2 неудачи подряд) и перестаёт слать сюда запросы.
2. Через SHUTDOWN_DRAIN_SECONDS — обычная остановка uvicorn: закрыть приём соединений,
доделать начатые запросы (не дольше GRACEFUL_SHUTDOWN_SECONDS) и выйти.
Без шага 1 запрос, пришедший в момент остановки, получил бы от балансировщика 502.
Повторный сигнал останавливает процесс сразу, без ожидания.
"""
import logging
import threading
import uvicorn
from . import config
from .api import app, draining
log = logging.getLogger("messenger")
class DrainingServer(uvicorn.Server):
def handle_exit(self, sig, frame):
if draining.is_set() or config.SHUTDOWN_DRAIN_SECONDS == 0:
return super().handle_exit(sig, frame)
draining.set()
log.info("Сигнал %s: /health/ready -> 503, ухожу из балансировки, остановка через %s с",
sig, config.SHUTDOWN_DRAIN_SECONDS)
# Таймер в отдельном потоке: обработчик сигнала должен вернуться сразу.
threading.Timer(config.SHUTDOWN_DRAIN_SECONDS, super().handle_exit, (sig, frame)).start()
def main():
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
DrainingServer(uvicorn.Config(
app,
host=config.APP_HOST,
port=config.APP_PORT,
access_log=False, # строку на каждый запрос пишет наш middleware (без тел и query)
timeout_graceful_shutdown=config.GRACEFUL_SHUTDOWN_SECONDS,
# Соединение от HAProxy держим дольше, чем HAProxy держит свои простаивающие соединения:
# тогда закрывает их HAProxy, и запрос не попадёт в соединение, которое закрывает API.
timeout_keep_alive=65,
)).run()
if __name__ == "__main__":
main()
+305
View File
@@ -0,0 +1,305 @@
"""HTTP-слой: маршруты из contracts/openapi.json, проверка входных данных, единый формат ошибок.
Здесь нет правил предметной области (кто может писать в чат и т.п.) — они в store.py.
Что изменилось с lab2:
- в каждом ответе заголовок X-Instance-Id: какая реплика API обслужила запрос;
- POST сообщения требует Idempotency-Key: повтор того же запроса не создаёт второе сообщение;
- миграции больше не применяются при старте: их применяет отдельный сервис migrate,
а реплика только ждёт актуальную схему (db.wait_for_schema);
- по SIGTERM /health/ready сразу отвечает 503 (флаг draining, см. __main__.py).
В памяти процесса нет ничего, от чего зависит правильность ответа: данные и сессии —
в PostgreSQL, кэш сессий — в общем Valkey. Поэтому любой запрос может обслужить любая реплика.
"""
import hashlib
import json
import logging
import threading
import time
import uuid
from contextlib import asynccontextmanager
from dataclasses import asdict
from typing import Annotated
from fastapi import Depends, FastAPI, Header, Query, Request, Response
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import AfterValidator, BaseModel, ConfigDict, Field
from starlette.concurrency import run_in_threadpool
from starlette.exceptions import HTTPException as StarletteHTTPException
from . import config, db, security
from .cursor import decode_cursor, encode_cursor
from .errors import AppError, Unauthorized, Unavailable
from .sessions import AuthContext, SessionCache, Sessions
from .store import PostgresStore, User, sort_key
log = logging.getLogger("messenger")
# Один набор объектов на процесс. Пул соединений открывается при старте (lifespan).
pool = db.create_pool()
store = PostgresStore(pool)
cache = SessionCache(config.CACHE_URL)
sessions = Sessions(store, cache, config.SESSION_TTL_SECONDS)
# Выставляется по SIGTERM (__main__.py): реплика уходит из балансировки, но ещё отвечает.
draining = threading.Event()
@asynccontextmanager
async def lifespan(_app: FastAPI):
config.validate()
await run_in_threadpool(db.wait_for_schema) # миграции применяет сервис migrate, мы только ждём
pool.open()
cache.start_monitor() # фоновая проверка Valkey раз в CACHE_CHECK_INTERVAL_SECONDS
log.info("Реплика %s запущена: версия %s, env=%s, TTL сессии=%s c, кэш сессий: %s",
config.INSTANCE_ID, config.APP_VERSION, config.APP_ENV, config.SESSION_TTL_SECONDS,
"Valkey" if cache.enabled else "выключен")
yield
pool.close() # аккуратно закрываем соединения с БД при остановке
log.info("Реплика %s остановлена: соединения с PostgreSQL закрыты, данные остаются в базе",
config.INSTANCE_ID)
app = FastAPI(title="MTUSI Messenger, lab3", lifespan=lifespan)
# ---------- ошибки и служебная обёртка каждого запроса ----------
def error_response(request: Request, status: int, code: str, message: str,
headers: dict[str, str] | None = None) -> JSONResponse:
body = {"error": {"code": code, "message": message, "request_id": request.state.request_id}}
return JSONResponse(body, status_code=status, headers=headers)
# Эти два адреса доступны без токена. Всё остальное под /api/ требует Bearer.
PUBLIC_ENDPOINTS = {("POST", "/api/v1/users"), ("POST", "/api/v1/auth/sessions")}
def needs_bearer(request: Request) -> bool:
return request.url.path.startswith("/api/") and (request.method, request.url.path) not in PUBLIC_ENDPOINTS
def authenticate(authorization: str | None) -> AuthContext:
"""Bearer-токен -> пользователь. Любая проблема с токеном -> 401 с WWW-Authenticate: Bearer."""
token = security.parse_bearer(authorization)
auth = sessions.authenticate(token) if token else None
if auth is None:
raise Unauthorized("Нужен действующий Bearer-токен сессии")
return auth
@app.middleware("http")
async def request_context(request: Request, call_next):
"""Выполняется вокруг каждого запроса: X-Request-Id, X-Instance-Id, аутентификация, лог.
Аутентификация стоит здесь, а не в обработчике: она выполняется ДО разбора тела
и поиска чата. Так соблюдается порядок из контракта: сначала «кто ты» (401),
потом «можно ли тебе этот объект» (404) и «правильный ли запрос» (400).
"""
request.state.request_id = uuid.uuid4().hex
started = time.perf_counter()
try:
if needs_bearer(request):
# Проверка токена ходит в Valkey/PostgreSQL (блокирующий код) — выполняем в пуле потоков.
request.state.auth = await run_in_threadpool(authenticate, request.headers.get("Authorization"))
response = await call_next(request)
except AppError as exc: # 401 от аутентификации или 503, если хранилище недоступно
response = error_response(request, exc.status, exc.code, exc.message, exc.headers)
except Exception:
# Подробности (stack trace) — только в лог сервера, клиенту — общий ответ 500.
log.exception("Необработанная ошибка, request_id=%s", request.state.request_id)
response = error_response(request, 500, "internal_error", "Внутренняя ошибка сервера")
response.headers["X-Request-Id"] = request.state.request_id
# С lab3: в каждом ответе (и в ошибках, и в health) — какая реплика его создала.
response.headers["X-Instance-Id"] = config.INSTANCE_ID
# В лог не пишем тела, query-параметры и заголовки: там тексты сообщений, пароли и токены.
log.info("%s %s -> %d (%.1f ms) request_id=%s", request.method, request.url.path,
response.status_code, (time.perf_counter() - started) * 1000, request.state.request_id)
return response
@app.exception_handler(AppError)
async def handle_app_error(request: Request, exc: AppError):
return error_response(request, exc.status, exc.code, exc.message, exc.headers)
@app.exception_handler(RequestValidationError)
async def handle_validation_error(request: Request, exc: RequestValidationError):
# FastAPI по умолчанию отвечает 422 со своим форматом; контракт требует 400 и наш формат.
# Детали pydantic клиенту не отдаём: в них может быть эхо входных данных (например, пароль).
first = exc.errors()[0]
if first["type"] == "json_invalid":
message = "Тело запроса не является корректным JSON"
else:
message = "Неверное значение: " + ".".join(str(part) for part in first["loc"])
return error_response(request, 400, "invalid_request", message)
@app.exception_handler(StarletteHTTPException)
async def handle_http_error(request: Request, exc: StarletteHTTPException):
# Ошибки, которые создаёт сам фреймворк: неизвестный путь (404), не тот метод (405) и т.п.
if exc.status_code == 404:
return error_response(request, 404, "not_found", "Ресурс не найден")
return error_response(request, exc.status_code, "invalid_request", "Запрос не может быть обработан")
# ---------- входные данные (схемы из contracts/openapi.json) ----------
def _not_blank(value: str) -> str:
if not value.strip():
raise ValueError("строка состоит только из пробелов")
return value
# Длины в символах Unicode (code points): len("👋") == 1 в Python.
Name = Annotated[str, Field(min_length=1, max_length=100), AfterValidator(_not_blank)]
Text = Annotated[str, Field(min_length=1, max_length=4000), AfterValidator(_not_blank)]
Password = Annotated[str, Field(min_length=security.PASSWORD_MIN, max_length=security.PASSWORD_MAX),
AfterValidator(_not_blank)]
class StrictModel(BaseModel):
model_config = ConfigDict(extra="forbid") # лишние поля в JSON -> 400
class CreateUser(StrictModel):
username: Annotated[str, Field(pattern=r"^[a-z0-9_]{3,32}$")]
display_name: Name
password: Password
class CreateChat(StrictModel):
title: Name
member_ids: Annotated[list[uuid.UUID], Field(min_length=1, max_length=100)]
class CreateMessage(StrictModel):
text: Text # поля sender_id нет: прислать его = лишнее поле = 400
# Ключ идемпотентности (с lab3): ASCII [A-Za-z0-9._:-], 1–128 символов. Нет или неверный -> 400.
IdempotencyKey = Annotated[str, Header(alias="Idempotency-Key", min_length=1, max_length=128,
pattern=r"^[A-Za-z0-9._:-]+$")]
def request_fingerprint(body: BaseModel) -> bytes:
"""SHA-256 «смысла» запроса: тело после разбора, ключи по алфавиту, без лишних пробелов.
Поэтому порядок полей и форматирование JSON не важны: {"text":"a"} и { "text" : "a" }
дают одинаковый отпечаток. Сравнивается при повторе с тем же Idempotency-Key.
"""
canonical = json.dumps(body.model_dump(mode="json"), sort_keys=True, ensure_ascii=False,
separators=(",", ":"))
return hashlib.sha256(canonical.encode("utf-8")).digest()
# ---------- текущий пользователь ----------
def current_auth(request: Request) -> AuthContext:
"""Сессия, которую middleware уже проверил для этого запроса."""
auth = getattr(request.state, "auth", None)
if auth is None: # защита от ошибки в PUBLIC_ENDPOINTS: без проверки токена доступа нет
raise Unauthorized("Нужен действующий Bearer-токен сессии")
return auth
def current_user(auth: Annotated[AuthContext, Depends(current_auth)]) -> User:
return auth.user
CurrentAuth = Annotated[AuthContext, Depends(current_auth)]
CurrentUser = Annotated[User, Depends(current_user)]
Limit = Annotated[int, Query(ge=1, le=100)]
Cursor = Annotated[str | None, Query(min_length=1)]
def page_response(scope: str, items: list, has_more: bool) -> dict:
next_cursor = encode_cursor(scope, sort_key(items[-1])) if has_more else None
return {"items": [asdict(item) for item in items], "next_cursor": next_cursor}
# ---------- маршруты ----------
# Обработчики объявлены через def (не async def): FastAPI запускает их в пуле потоков,
# поэтому запросы обрабатываются параллельно. Согласованность данных обеспечивает
# PostgreSQL (транзакции и ограничения), а не замок в памяти процесса.
@app.get("/health/live")
def health_live():
return {"status": "ok"} # процесс жив; от зависимостей не зависит
@app.get("/health/ready")
def health_ready():
# Готовность = можно обслужить обязательный путь. Критична только PostgreSQL:
# без Valkey API работает (медленнее), поэтому его недоступность не делает нас «не готовыми».
if draining.is_set():
# Получен SIGTERM: просим балансировщик больше не присылать запросы (см. __main__.py).
raise Unavailable("Реплика останавливается")
store.ping() # если БД недоступна -> Unavailable -> 503 в общем формате ошибки
return {"status": "ok"}
@app.post("/api/v1/users", status_code=201)
def register_user(body: CreateUser):
password_hash = security.hash_password(body.password) # сам пароль нигде не сохраняется
return asdict(store.create_user(body.username, body.display_name, password_hash))
@app.post("/api/v1/auth/sessions", status_code=201)
def create_session(response: Response, authorization: Annotated[str | None, Header()] = None):
credentials = security.parse_basic(authorization)
result = sessions.login(*credentials) if credentials else None
if result is None:
# Один и тот же ответ для «нет такого пользователя», «неверный пароль» и «кривой заголовок».
raise Unauthorized("Неверное имя пользователя или пароль", Unauthorized.BASIC)
token, expires_at, user = result
response.headers["Cache-Control"] = "no-store" # ответ с токеном нельзя кэшировать
return {"token": token, "token_type": "Bearer", "expires_at": expires_at, "user": asdict(user)}
@app.delete("/api/v1/auth/sessions/current", status_code=204)
def revoke_session(auth: CurrentAuth):
sessions.logout(auth)
return Response(status_code=204)
@app.get("/api/v1/users/me")
def get_me(user: CurrentUser):
return asdict(user)
@app.post("/api/v1/chats", status_code=201)
def create_chat(body: CreateChat, user: CurrentUser):
member_ids = [str(member_id) for member_id in body.member_ids]
return asdict(store.create_chat(user.id, body.title, member_ids))
@app.get("/api/v1/chats")
def list_chats(user: CurrentUser, limit: Limit = 50, cursor: Cursor = None):
scope = f"chats:{user.id}"
items, has_more = store.list_chats(user.id, decode_cursor(scope, cursor), limit)
return page_response(scope, items, has_more)
@app.get("/api/v1/chats/{chat_id}")
def get_chat(chat_id: uuid.UUID, user: CurrentUser):
return asdict(store.get_chat(user.id, str(chat_id)))
@app.post("/api/v1/chats/{chat_id}/messages", status_code=201)
def send_message(chat_id: uuid.UUID, body: CreateMessage, user: CurrentUser,
idempotency_key: IdempotencyKey):
# Область ключа из контракта: пользователь + метод + путь чата + ключ.
# Метод и путь у этого обработчика всегда одни, поэтому в БД ключ уникален в паре (чат, отправитель).
message, replayed = store.add_message(user.id, str(chat_id), body.text,
idempotency_key, request_fingerprint(body))
if replayed:
log.info("Повтор с тем же Idempotency-Key: возвращаю уже сохранённое сообщение %s", message.id)
return asdict(message)
@app.get("/api/v1/chats/{chat_id}/messages")
def list_messages(chat_id: uuid.UUID, user: CurrentUser, limit: Limit = 50, cursor: Cursor = None):
scope = f"messages:{chat_id}"
items, has_more = store.list_messages(user.id, str(chat_id), decode_cursor(scope, cursor), limit)
return page_response(scope, items, has_more)
+107
View File
@@ -0,0 +1,107 @@
"""Настройки из переменных окружения.
Конфигурация не зашита в код и в образ: один и тот же образ запускается
с разными настройками (обычный API, API с коротким TTL сессии, сервис миграций).
Секреты (адреса БД и Valkey с паролями) передаются не значением переменной,
а путём к файлу: *_FILE=/run/secrets/... Так пароль не виден в `docker inspect`.
"""
import os
import socket
from pathlib import Path
def _int(name: str, default: int, minimum: int = 1) -> int:
value = int(os.environ.get(name, str(default)))
if value < minimum:
raise ValueError(f"{name} должен быть не меньше {minimum}")
return value
def _secret(file_var: str, plain_var: str) -> str:
"""Значение секрета: из файла, указанного в *_FILE, иначе из обычной переменной.
strip() убирает перевод строки в конце файла, в том числе \\r из Windows-редакторов:
иначе он попал бы внутрь пароля и подключение к БД не прошло бы.
"""
path = os.environ.get(file_var, "").strip()
if path:
return Path(path).read_text(encoding="utf-8").strip()
return os.environ.get(plain_var, "").strip()
APP_HOST = os.environ.get("APP_HOST", "0.0.0.0") # 0.0.0.0 = слушать на всех интерфейсах контейнера
APP_PORT = _int("APP_PORT", 8080)
APP_ENV = os.environ.get("APP_ENV", "lab")
# Версия сборки (build arg APP_VERSION в Dockerfile). Пишется в лог при старте;
# по ней student-tests/rolling_update.py проверяет, что все реплики заменены новой версией.
APP_VERSION = os.environ.get("APP_VERSION", "dev")
# --- реплики (с lab3) ---
# X-Instance-Id: какая реплика обслужила запрос. В Docker hostname контейнера — это первые
# 12 символов его ID, поэтому по заголовку контейнер сразу находится в `docker ps`.
# Значение не меняется, пока жив процесс. В lab7 его нужно заменить случайным alias.
INSTANCE_ID = os.environ.get("INSTANCE_ID", "").strip() or socket.gethostname()
# Остановка по SIGTERM в два шага (см. __main__.py):
# 1) SHUTDOWN_DRAIN_SECONDS: /health/ready уже отвечает 503, но запросы ещё обслуживаются.
# HAProxy проверяет готовность раз в 1 с и после 2 неудач подряд (через ~1,5 с)
# перестаёт слать сюда запросы. 3 с — с запасом;
# 2) GRACEFUL_SHUTDOWN_SECONDS: uvicorn закрывает приём и доделывает начатые запросы.
# Самый долгий запрос: ожидание соединения из пула (3 с) + statement_timeout (5 с) = 8 с.
# Docker ждёт дольше суммы (stop_grace_period: 15s в compose.yaml), потом SIGKILL.
SHUTDOWN_DRAIN_SECONDS = _int("SHUTDOWN_DRAIN_SECONDS", 3, minimum=0)
GRACEFUL_SHUTDOWN_SECONDS = _int("GRACEFUL_SHUTDOWN_SECONDS", 8)
# --- сессии ---
SESSION_TTL_SECONDS = _int("SESSION_TTL_SECONDS", 3600)
# Источник истины для сессий. Поддерживается только postgres: Valkey в этой работе — кэш.
SESSION_STORE = os.environ.get("SESSION_STORE", "postgres").strip()
# Сколько секунд запись о сессии может жить в кэше (не дольше самой сессии).
# Это верхняя граница «устаревания»: см. sessions.py и REPORT.md.
SESSION_CACHE_TTL_SECONDS = _int("SESSION_CACHE_TTL_SECONDS", 30)
# --- PostgreSQL ---
DATABASE_URL = _secret("DATABASE_URL_FILE", "DATABASE_URL")
DB_POOL_MIN_SIZE = _int("DB_POOL_MIN_SIZE", 1)
DB_POOL_MAX_SIZE = _int("DB_POOL_MAX_SIZE", 10) # пул ограничен: не больше 10 соединений с БД
DB_POOL_TIMEOUT_SECONDS = _int("DB_POOL_TIMEOUT_SECONDS", 3) # ждать свободное соединение не дольше
DB_CONNECT_TIMEOUT_SECONDS = _int("DB_CONNECT_TIMEOUT_SECONDS", 3)
DB_STATEMENT_TIMEOUT_MS = _int("DB_STATEMENT_TIMEOUT_MS", 5000) # один SQL-запрос не дольше 5 с
DB_STARTUP_WAIT_SECONDS = _int("DB_STARTUP_WAIT_SECONDS", 60) # сколько ждать БД и миграции при старте
# --- Valkey (кэш сессий, общий для всех реплик) ---
CACHE_URL = _secret("CACHE_URL_FILE", "CACHE_URL") # пусто = работать без кэша
CACHE_TIMEOUT_MS = _int("CACHE_TIMEOUT_MS", 300) # кэш должен отвечать быстро, иначе обходим его
CACHE_POOL_MAX_SIZE = _int("CACHE_POOL_MAX_SIZE", 20)
# Как часто фоновый поток каждой реплики проверяет Valkey (PING). Так реплика замечает сбой
# Valkey, даже если в этот момент через неё не шли запросы (см. sessions.py).
CACHE_CHECK_INTERVAL_SECONDS = _int("CACHE_CHECK_INTERVAL_SECONDS", 1)
# IDEMPOTENCY_TTL_SECONDS из .env.example не используется: ключ идемпотентности хранится
# в строке сообщения столько же, сколько само сообщение (бессрочно, то есть дольше 24 ч
# из контракта). См. migrations/004_message_idempotency.sql и REPORT.md.
def _migrations_dir() -> Path:
"""Каталог SQL-миграций: в образе /srv/migrations, в репозитории ./migrations."""
explicit = os.environ.get("MIGRATIONS_DIR")
if explicit:
return Path(explicit)
here = Path(__file__).resolve()
for candidate in (here.parents[1] / "migrations", here.parents[2] / "migrations"):
if candidate.is_dir():
return candidate
return here.parents[1] / "migrations"
MIGRATIONS_DIR = _migrations_dir()
def validate() -> None:
"""Проверка при старте: лучше упасть сразу с понятной ошибкой, чем на первом запросе."""
if not DATABASE_URL:
raise RuntimeError("Не задан адрес PostgreSQL: DATABASE_URL_FILE (или DATABASE_URL)")
if SESSION_STORE != "postgres":
raise RuntimeError("SESSION_STORE поддерживает только значение postgres (Valkey здесь — кэш)")
if DB_POOL_MIN_SIZE > DB_POOL_MAX_SIZE:
raise RuntimeError("DB_POOL_MIN_SIZE больше DB_POOL_MAX_SIZE")
+44
View File
@@ -0,0 +1,44 @@
"""Непрозрачный курсор пагинации.
Внутри курсора: «область» (какой именно список листаем) и ключ последнего
элемента страницы (created_at, id). Всё это упаковано в base64, клиент курсор
не разбирает, а просто передаёт обратно. Сервер проверяет, что курсор выдан
для того же списка: курсор от другого чата даёт 400.
С lab2 ключ уходит в SQL-запрос, поэтому перед этим он проверяется:
испорченное время или UUID должны дать 400, а не ошибку базы данных (500).
"""
import base64
import json
import uuid
from datetime import datetime, timezone
from .errors import InvalidRequest
def encode_cursor(scope: str, key: tuple[str, str]) -> str:
raw = json.dumps([scope, *key]).encode()
return base64.urlsafe_b64encode(raw).decode()
def decode_cursor(scope: str, cursor: str | None) -> tuple[datetime, uuid.UUID] | None:
if cursor is None:
return None
try:
data = json.loads(base64.urlsafe_b64decode(cursor.encode("ascii")))
except (ValueError, RecursionError): # не ASCII, не base64, не JSON или слишком глубокая вложенность
raise InvalidRequest("Неверный cursor") from None
well_formed = isinstance(data, list) and len(data) == 3 and all(isinstance(x, str) for x in data)
if not well_formed or data[0] != scope:
raise InvalidRequest("Неверный cursor")
try:
created_at = datetime.fromisoformat(data[1].replace("Z", "+00:00"))
item_id = uuid.UUID(data[2])
if created_at.tzinfo is None:
raise ValueError("время без часового пояса")
# Перевод в UTC может выйти за пределы годов 1–9999 (например, 0001-01-01T00:00+14:00):
# Python бросает OverflowError. Это тоже испорченный курсор -> 400, а не 500.
created_at = created_at.astimezone(timezone.utc)
except (ValueError, OverflowError):
raise InvalidRequest("Неверный cursor") from None
return created_at, item_id
+148
View File
@@ -0,0 +1,148 @@
"""Подключение к PostgreSQL: пул соединений, таймауты и миграции.
Пул — это набор заранее открытых соединений. Запрос берёт соединение из пула,
выполняет SQL и возвращает его обратно. Пул ограничен (DB_POOL_MAX_SIZE), поэтому
даже под нагрузкой API не откроет к базе больше соединений, чем она выдержит.
С lab3 миграции применяет ТОЛЬКО отдельный одноразовый сервис migrate
(`python -m messenger.migrate`, см. compose.yaml). Реплики API при старте лишь ждут,
пока схема станет актуальной (wait_for_schema), и сами ничего не меняют.
Так нет гонки «две реплики одновременно меняют схему».
"""
import logging
import time
import psycopg
from psycopg_pool import ConnectionPool
from . import config
log = logging.getLogger("messenger.db")
# Произвольное постоянное число: «номер замка» для миграций (pg_advisory_lock).
# Если миграции всё-таки запустят дважды одновременно (например, два `docker compose run migrate`),
# выполнит их только один процесс, второй подождёт и увидит, что всё уже применено.
MIGRATION_LOCK_ID = 2026_0002
def connection_kwargs() -> dict:
return {
"connect_timeout": config.DB_CONNECT_TIMEOUT_SECONDS,
"application_name": "messenger-api",
# Таймауты на стороне сервера: зависший запрос или забытая транзакция
# не будут держать соединение и блокировки бесконечно.
"options": (f"-c statement_timeout={config.DB_STATEMENT_TIMEOUT_MS}"
" -c idle_in_transaction_session_timeout=10000"),
}
def create_pool() -> ConnectionPool:
return ConnectionPool(
conninfo=config.DATABASE_URL,
kwargs=connection_kwargs(),
min_size=config.DB_POOL_MIN_SIZE,
max_size=config.DB_POOL_MAX_SIZE,
timeout=config.DB_POOL_TIMEOUT_SECONDS, # сколько ждать свободное соединение из пула
# Перед выдачей соединение проверяется: после рестарта PostgreSQL старые
# соединения «мертвы», и пул заменит их, а не отдаст запросу.
check=ConnectionPool.check_connection,
open=False,
name="messenger",
)
def migration_files() -> list:
"""Файлы migrations/NNN_*.sql этой версии приложения, по порядку."""
files = sorted(config.MIGRATIONS_DIR.glob("*.sql"))
if not files:
raise RuntimeError(f"Нет файлов миграций в {config.MIGRATIONS_DIR}")
return files
def _connect(application_name: str):
return psycopg.connect(config.DATABASE_URL, autocommit=True,
connect_timeout=config.DB_CONNECT_TIMEOUT_SECONDS,
application_name=application_name)
def migrate() -> list[str]:
"""Применяет новые файлы migrations/NNN_*.sql по порядку. Возвращает список применённых.
Каждая миграция и запись о ней выполняются в одной транзакции: либо файл применён
полностью и отмечен, либо ничего не изменилось. Повторный запуск ничего не дублирует.
"""
files = migration_files()
applied_now = []
# Отдельное соединение без statement_timeout: создание индекса на большой таблице может быть долгим.
with _connect("messenger-migrate") as conn:
conn.execute("SELECT pg_advisory_lock(%s)", (MIGRATION_LOCK_ID,))
try:
conn.execute("""
CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
applied_at timestamptz NOT NULL DEFAULT now()
)""")
done = {row[0] for row in conn.execute("SELECT version FROM schema_migrations")}
for path in files:
if path.stem in done:
continue
with conn.transaction():
# Без параметров psycopg разрешает несколько SQL-команд в одном вызове.
conn.execute(path.read_text(encoding="utf-8"))
conn.execute("INSERT INTO schema_migrations (version) VALUES (%s)", (path.stem,))
applied_now.append(path.stem)
finally:
conn.execute("SELECT pg_advisory_unlock(%s)", (MIGRATION_LOCK_ID,))
return applied_now
def migrate_with_retry() -> None:
"""Для сервиса migrate: БД может подниматься дольше — ждём её, а не падаем сразу."""
deadline = time.monotonic() + config.DB_STARTUP_WAIT_SECONDS
while True:
try:
applied = migrate()
if applied:
log.info("Миграции применены: %s", ", ".join(applied))
else:
log.info("Миграции: новых нет, схема актуальна")
return
except psycopg.OperationalError as exc:
if time.monotonic() > deadline:
raise
log.warning("PostgreSQL пока недоступен (%s), повтор через 1 с", type(exc).__name__)
time.sleep(1)
def pending_migrations() -> list[str]:
"""Какие миграции этой версии ещё не применены (только чтение, схему не меняет)."""
expected = [path.stem for path in migration_files()]
with _connect("messenger-api-schema-check") as conn:
try:
done = {row[0] for row in conn.execute("SELECT version FROM schema_migrations")}
except psycopg.errors.UndefinedTable:
done = set() # миграции ещё ни разу не запускались
return [version for version in expected if version not in done]
def wait_for_schema() -> None:
"""Для реплики API: дождаться, пока сервис migrate применит все миграции этой версии.
Реплика схему не меняет. Если за DB_STARTUP_WAIT_SECONDS схема так и не стала
актуальной, процесс завершается с ошибкой: лучше не стартовать, чем работать
со схемой, которой код не понимает.
"""
deadline = time.monotonic() + config.DB_STARTUP_WAIT_SECONDS
while True:
try:
pending = pending_migrations()
if not pending:
log.info("Схема БД актуальна (миграции применены сервисом migrate)")
return
reason = "не применены миграции " + ", ".join(pending)
except psycopg.OperationalError as exc:
reason = f"PostgreSQL недоступен ({type(exc).__name__})"
if time.monotonic() > deadline:
raise RuntimeError(f"Схема БД не готова: {reason}. Запустите сервис migrate")
log.warning("Жду схему БД: %s; повтор через 1 с", reason)
time.sleep(1)
+43
View File
@@ -0,0 +1,43 @@
"""Ошибки приложения.
Каждый класс знает свой HTTP-статус и код из контракта, поэтому в api.py
достаточно одного обработчика, который превращает любую из них в JSON-ответ.
"""
class AppError(Exception):
status = 500
code = "internal_error"
def __init__(self, message: str, headers: dict[str, str] | None = None):
super().__init__(message)
self.message = message
self.headers = headers or {}
class InvalidRequest(AppError):
status, code = 400, "invalid_request"
class Unauthorized(AppError):
"""401. Контракт требует заголовок WWW-Authenticate: какую схему ждёт сервер."""
status, code = 401, "unauthorized"
BASIC = 'Basic realm="messenger", charset="UTF-8"' # только для POST /auth/sessions
BEARER = 'Bearer realm="messenger"' # для всех остальных защищённых запросов
def __init__(self, message: str, challenge: str = BEARER):
super().__init__(message, {"WWW-Authenticate": challenge})
class NotFound(AppError):
status, code = 404, "not_found"
class Conflict(AppError):
status, code = 409, "conflict"
class Unavailable(AppError):
"""503: нужная зависимость (PostgreSQL) недоступна. Клиент может повторить позже."""
status, code = 503, "unavailable"
+25
View File
@@ -0,0 +1,25 @@
"""Миграции схемы БД отдельным процессом: `python -m messenger.migrate`.
Это команда одноразового сервиса migrate в compose.yaml. Он стартует после того,
как PostgreSQL стал healthy, применяет новые migrations/*.sql и завершается с кодом 0.
Реплики API запускаются только после успешного завершения migrate
(depends_on: condition: service_completed_successfully) и сами схему не меняют.
Повторный запуск безопасен: применённые файлы отмечены в schema_migrations
и второй раз не выполняются, а pg_advisory_lock не даёт двум запускам идти одновременно.
"""
import logging
import sys
from . import config, db
def main() -> int:
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
config.validate()
db.migrate_with_retry()
return 0
if __name__ == "__main__":
sys.exit(main())
+80
View File
@@ -0,0 +1,80 @@
"""Пароли, токены и разбор заголовка Authorization.
Две разные задачи хеширования:
- пароль хешируется МЕДЛЕННОЙ функцией Argon2id с солью: перебор паролей по украденной
базе стоит дорого (каждая попытка — десятки миллисекунд и 19 МиБ памяти);
- токен сессии хешируется БЫСТРЫМ SHA-256: токен — 256 случайных бит, перебирать
его бессмысленно, а проверять его нужно на каждом запросе.
"""
import base64
import binascii
import hashlib
import re
import secrets
from argon2 import PasswordHasher
from argon2.exceptions import InvalidHashError, VerificationError
# Параметры Argon2id — минимальные из рекомендаций OWASP: m=19 МиБ, t=2, p=1.
# Больше памяти — дороже перебор, но и каждый вход дороже для сервера.
_hasher = PasswordHasher(time_cost=2, memory_cost=19 * 1024, parallelism=1)
# Hash заведомо неверного пароля. Если пользователя нет, всё равно выполняем проверку:
# ответ занимает столько же времени, и по задержке нельзя узнать, существует ли username.
_DUMMY_HASH = _hasher.hash("timing-equalizer-not-a-password")
TOKEN_BYTES = 32 # 32 байта = 256 бит энтропии (требование контракта)
PASSWORD_MIN, PASSWORD_MAX = 12, 128
USERNAME_RE = re.compile(r"[a-z0-9_]{3,32}") # то же правило, что при регистрации
MAX_BASIC_HEADER = 1024 # длинный заголовок не проверяем: не тратим CPU на заведомый мусор
def hash_password(password: str) -> str:
return _hasher.hash(password) # строка вида $argon2id$v=19$m=19456,t=2,p=1$<соль>$<hash>
def verify_password(password_hash: str | None, password: str) -> bool:
try:
return _hasher.verify(password_hash or _DUMMY_HASH, password) and password_hash is not None
except (VerificationError, InvalidHashError):
return False
def new_token() -> str:
"""Непрозрачный случайный токен: не username, не UUID и не JWT."""
return secrets.token_urlsafe(TOKEN_BYTES)
def token_hash(token: str) -> bytes:
"""В БД и в кэше хранится только SHA-256 токена — сам токен знает лишь клиент."""
return hashlib.sha256(token.encode("utf-8")).digest()
def _split_scheme(header: str | None) -> tuple[str, str]:
scheme, _, value = (header or "").strip().partition(" ")
return scheme.lower(), value.strip()
def parse_basic(header: str | None) -> tuple[str, str] | None:
"""Authorization: Basic base64(username:password) -> (username, password) или None.
Пароль в UTF-8 и может содержать двоеточие: делим по ПЕРВОМУ двоеточию (RFC 7617).
"""
scheme, value = _split_scheme(header)
if scheme != "basic" or not value or len(value) > MAX_BASIC_HEADER:
return None
try:
decoded = base64.b64decode(value, validate=True).decode("utf-8")
except (binascii.Error, ValueError):
return None
username, sep, password = decoded.partition(":")
if not sep or not username.isascii():
return None
return username, password
def parse_bearer(header: str | None) -> str | None:
scheme, value = _split_scheme(header)
if scheme != "bearer" or not value or len(value) > 512 or " " in value:
return None
return value
+228
View File
@@ -0,0 +1,228 @@
"""Сессии: вход (Basic -> токен), проверка Bearer-токена, выход.
Где что хранится:
- ИСТОЧНИК ИСТИНЫ — таблица sessions в PostgreSQL. Она переживает рестарт и решает,
действует ли сессия (не отозвана и не истекла).
- Valkey — КЭШ «hash токена -> пользователь», ОДИН НА ВСЕ РЕПЛИКИ API. Он избавляет от
SQL-запроса на каждом обращении с токеном. Запись, положенную одной репликой, используют
все остальные. Кэш можно в любой момент очистить или потерять: при промахе данные
берутся из PostgreSQL и снова кладутся в кэш.
Политика кэша:
- запись живёт min(SESSION_CACHE_TTL_SECONDS, остаток жизни сессии): кэш никогда
не продлевает сессию, а истёкшая запись к тому же отбрасывается по expires_at;
- logout: сначала отметка revoked_at в PostgreSQL, затем в кэш вместо записи о сессии
кладётся отметка «отозвано» (tombstone). Новая запись о сессии кладётся только если ключа
нет (SET NX), поэтому запрос, который прочитал сессию из базы до logout, не сможет
«воскресить» её в кэше после logout;
- ОБЩЕЕ поколение кэша (с lab3): в Valkey лежит ключ sess:gen, каждая запись о сессии помечена
поколением, в котором её положили. Запись читается одним запросом MGET вместе с текущим
поколением и считается доверенной, только если поколения совпадают. Каждая реплика раз
в CACHE_CHECK_INTERVAL_SECONDS проверяет Valkey (фоновый поток). Реплика, заметившая сбой, перестаёт
пользоваться кэшем, а когда Valkey вернулся, СНАЧАЛА записывает новое случайное поколение
и только потом снова включает кэш. Зачем: пока Valkey был недоступен, logout не мог положить
отметку «отозвано», и в кэше могла остаться старая запись «токен -> пользователь». После смены
поколения её не доверяет ни одна реплика: проверка идёт в PostgreSQL, где сессия отозвана -> 401.
Отметки «отозвано» действуют в любом поколении: они только запрещают, а не разрешают;
- если Valkey недоступен, его обходят: всё работает напрямую через PostgreSQL.
Ожидание подключения (в Docker это ещё и поиск DNS-имени остановленного контейнера,
до нескольких секунд) достаётся фоновому потоку, а не запросам пользователей.
"""
import json
import logging
import secrets
import threading
import time
from dataclasses import asdict, dataclass
from datetime import datetime, timedelta, timezone
import valkey
from . import config, security
from .store import PostgresStore, User, ts
log = logging.getLogger("messenger.sessions")
@dataclass(frozen=True)
class AuthContext:
"""Результат успешной проверки токена: кто пришёл и какой сессией (нужно для logout)."""
user: User
token_hash: bytes
class SessionCache:
PREFIX = "sess:" # пользователю Valkey разрешены только ключи sess:* (ACL: secrets/valkey_users.acl)
GENERATION_KEY = PREFIX + "gen" # общее для всех реплик поколение кэша
NO_GENERATION = "-" # sess:gen ещё не создан (свежий Valkey)
def __init__(self, url: str):
self._client = None
self._down = False # True = кэш считается недоступным, запросы его не трогают
self._lock = threading.Lock()
self._monitor = None
if url:
timeout = config.CACHE_TIMEOUT_MS / 1000
pool = valkey.BlockingConnectionPool.from_url(
url,
max_connections=config.CACHE_POOL_MAX_SIZE, # ограниченный пул соединений
timeout=timeout, # сколько ждать свободное соединение
socket_timeout=timeout, # сколько ждать ответ
socket_connect_timeout=timeout, # сколько ждать подключение
lib_name=None, lib_version=None,
)
self._client = valkey.Valkey(connection_pool=pool)
@property
def enabled(self) -> bool:
return self._client is not None
def _available(self) -> bool:
return self._client is not None and not self._down
def _failed(self, operation: str, exc: Exception) -> None:
with self._lock:
if self._down: # уже знаем о сбое
return
self._down = True
log.warning("Valkey недоступен (%s при %s): работаем напрямую с PostgreSQL",
type(exc).__name__, operation)
# --- фоновая проверка Valkey (один поток на процесс) ---
def start_monitor(self) -> None:
if self._client is None or self._monitor is not None:
return
self._monitor = threading.Thread(target=self._watch, name="valkey-monitor", daemon=True)
self._monitor.start()
def _watch(self) -> None:
while True:
if not self._down:
try:
# Проверка связи и заодно «создать поколение, если его ещё нет» (свежий Valkey).
# NX: существующее поколение не трогаем.
self._client.set(self.GENERATION_KEY, secrets.token_hex(8), nx=True)
except valkey.ValkeyError as exc:
self._failed("heartbeat", exc)
else:
try:
# Valkey вернулся. Сначала НОВОЕ общее поколение: всё, что лежало в кэше до сбоя,
# перестаёт быть доверенным для ВСЕХ реплик. Только потом снова пользуемся кэшем.
self._client.set(self.GENERATION_KEY, secrets.token_hex(8))
with self._lock:
self._down = False
log.info("Valkey снова доступен: новое поколение кэша, записи до сбоя не используются")
except valkey.ValkeyError:
pass
time.sleep(config.CACHE_CHECK_INTERVAL_SECONDS)
# --- операции с кэшем; любая ошибка -> кэш выключается до возвращения Valkey ---
def lookup(self, key: bytes) -> tuple[dict | None, str] | None:
"""(запись или None, текущее поколение) одним запросом MGET. None — кэш недоступен."""
if not self._available():
return None
try:
raw, generation = self._client.mget(self.PREFIX + key.hex(), self.GENERATION_KEY)
except valkey.ValkeyError as exc:
self._failed("mget", exc)
return None
entry = None if raw is None else json.loads(raw)
return entry, (generation.decode() if generation else self.NO_GENERATION)
def generation(self) -> str | None:
"""Текущее поколение (перед созданием сессии). None — кэш недоступен."""
if not self._available():
return None
try:
value = self._client.get(self.GENERATION_KEY)
except valkey.ValkeyError as exc:
self._failed("get", exc)
return None
return value.decode() if value else self.NO_GENERATION
def add(self, key: bytes, value: dict, ttl_ms: int) -> None:
"""Положить запись, только если ключа ещё нет (SET NX): отметку «отозвано» не затираем."""
if not self._available() or ttl_ms < 100:
return
try:
self._client.set(self.PREFIX + key.hex(), json.dumps(value), px=ttl_ms, nx=True)
except valkey.ValkeyError as exc:
self._failed("set", exc)
def mark_revoked(self, key: bytes) -> None:
"""Заменить запись о сессии отметкой «отозвано» на SESSION_CACHE_TTL_SECONDS."""
if not self._available():
return # запись в кэше осталась, но после возвращения Valkey сменится поколение
try:
self._client.set(self.PREFIX + key.hex(), json.dumps({"revoked": True}),
px=config.SESSION_CACHE_TTL_SECONDS * 1000)
except valkey.ValkeyError as exc:
self._failed("set", exc)
def ping(self) -> bool:
try:
return bool(self._client and self._client.ping())
except valkey.ValkeyError:
return False
class Sessions:
def __init__(self, store: PostgresStore, cache: SessionCache, ttl_seconds: int):
self.store = store
self.cache = cache
self.ttl_seconds = ttl_seconds
def login(self, username: str, password: str) -> tuple[str, str, User] | None:
"""Проверяет пароль и создаёт сессию. None — неверные credentials (без уточнений)."""
if not security.PASSWORD_MIN <= len(password) <= security.PASSWORD_MAX:
return None
if not security.USERNAME_RE.fullmatch(username):
return None # такого username не может существовать — в базу даже не ходим
found = self.store.get_credentials(username)
user, password_hash = found if found else (None, None)
# Проверка выполняется и для несуществующего пользователя (с фиктивным hash):
# одинаковое время ответа и одинаковый 401 не раскрывают, есть ли такой username.
if not security.verify_password(password_hash, password) or user is None:
return None
token = security.new_token()
key = security.token_hash(token)
generation = self.cache.generation()
expires_at = self.store.create_session(key, user.id, self.ttl_seconds)
self._remember(key, user, expires_at, generation) # следующий запрос сразу попадёт в кэш
return token, ts(expires_at), user
def authenticate(self, token: str) -> AuthContext | None:
key = security.token_hash(token)
# Поколение читаем ДО обращения к базе (вместе с записью, одним MGET): если во время
# запроса случится сбой Valkey и поколение сменится, наша запись окажется недоверенной.
looked = self.cache.lookup(key)
generation = None
if looked is not None:
cached, generation = looked
if cached is not None:
if cached.get("revoked"):
return None # logout уже был
expires_at = datetime.fromisoformat(cached["expires_at"])
if cached.get("gen") == generation and expires_at > datetime.now(timezone.utc):
return AuthContext(User(**cached["user"]), key)
# запись другого поколения или истёкшая -> проверяем по источнику истины
found = self.store.get_session(key) # промах кэша, недоверенная запись или кэш недоступен
if found is None:
return None
user, expires_at = found
self._remember(key, user, expires_at, generation)
return AuthContext(user, key)
def logout(self, auth: AuthContext) -> None:
self.store.revoke_session(auth.token_hash) # сначала источник истины
self.cache.mark_revoked(auth.token_hash) # затем инвалидация кэша
def _remember(self, key: bytes, user: User, expires_at: datetime, generation: str | None) -> None:
if generation is None:
return # кэш был недоступен, когда мы начинали: ничего не кладём
left = expires_at - datetime.now(timezone.utc)
ttl = min(timedelta(seconds=config.SESSION_CACHE_TTL_SECONDS), left)
self.cache.add(key, {"user": asdict(user), "expires_at": expires_at.isoformat(), "gen": generation},
int(ttl.total_seconds() * 1000))
+301
View File
@@ -0,0 +1,301 @@
"""Хранилище на PostgreSQL.
С lab2 источник истины — база данных, а не память процесса. Методы и их смысл
те же, что у InMemoryStore из lab1, поэтому api.py почти не изменился.
Модуль по-прежнему ничего не знает про HTTP: он хранит данные и соблюдает правила.
Все SQL-запросы параметризованные: значения передаются отдельно от текста запроса
(%s), поэтому ввод пользователя никогда не становится частью SQL (нет SQL-инъекций).
"""
import logging
import uuid
from contextlib import contextmanager
from dataclasses import dataclass
from datetime import datetime, timezone
import psycopg
from psycopg import errors as pg_errors
from psycopg_pool import ConnectionPool, PoolTimeout
from .errors import Conflict, InvalidRequest, NotFound, Unavailable
log = logging.getLogger("messenger.store")
@dataclass(frozen=True)
class User:
id: str
username: str
display_name: str
created_at: str
@dataclass(frozen=True)
class Chat:
id: str
title: str
member_ids: tuple[str, ...]
created_at: str
@dataclass(frozen=True)
class Message:
id: str
chat_id: str
sender_id: str
text: str
created_at: str
def sort_key(item) -> tuple[str, str]:
"""Порядок по контракту: (created_at, id) по возрастанию. Из этой пары строится курсор."""
return item.created_at, item.id
def ts(value: datetime) -> str:
"""Время из БД -> строка RFC 3339 в UTC с Z и микросекундами (как в lab1)."""
return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
# Свободный текст (display_name, title, text) хранится в БД как байты UTF-8 (bytea), а не text:
# тип text в PostgreSQL не может содержать символ U+0000, а контракт его не запрещает.
# См. migrations/003_text_as_bytes.sql. Перед записью кодируем, после чтения декодируем.
def to_db(value: str) -> bytes:
return value.encode("utf-8")
def from_db(value) -> str:
return bytes(value).decode("utf-8")
def _user(row) -> User:
return User(str(row[0]), row[1], from_db(row[2]), ts(row[3]))
def _chat(row) -> Chat:
return Chat(str(row[0]), from_db(row[1]), tuple(str(m) for m in row[3]), ts(row[2]))
def _message(row) -> Message:
return Message(str(row[0]), str(row[1]), str(row[2]), from_db(row[3]), ts(row[4]))
# Участники чата всегда в одном порядке (по UUID), чтобы POST и GET отвечали одинаково.
_CHAT_COLUMNS = """c.id, c.title, c.created_at,
ARRAY(SELECT cm.user_id FROM chat_members cm WHERE cm.chat_id = c.id ORDER BY cm.user_id)"""
class PostgresStore:
def __init__(self, pool: ConnectionPool):
self.pool = pool
@contextmanager
def _conn(self, timeout: float | None = None):
"""Соединение из пула. В конце блока — COMMIT, при исключении — ROLLBACK.
Если база недоступна (нет соединения, истёк таймаут пула или запроса),
клиент получает 503 без подробностей, а не 500 со stack trace.
"""
try:
with self.pool.connection(timeout=timeout) as conn:
yield conn
except (psycopg.OperationalError, PoolTimeout) as exc:
log.warning("PostgreSQL недоступен: %s", type(exc).__name__)
raise Unavailable("Хранилище временно недоступно") from None
except psycopg.DataError as exc:
# База отвергла само значение (например, недопустимый символ): это ошибка входа -> 400,
# а не внутренняя ошибка сервера (500).
log.warning("PostgreSQL отверг значение: %s", type(exc).__name__)
raise InvalidRequest("Недопустимое значение в запросе") from None
def ping(self, timeout: float = 1.0) -> None:
"""Проверка готовности: короткий таймаут, чтобы healthcheck (3 с) успел получить 503."""
with self._conn(timeout) as conn:
conn.execute("SELECT 1")
# --- пользователи ---
def create_user(self, username: str, display_name: str, password_hash: str) -> User:
try:
with self._conn() as conn:
row = conn.execute(
"""INSERT INTO users (id, username, display_name, password_hash)
VALUES (%s, %s, %s, %s)
RETURNING id, username, display_name, created_at""",
(uuid.uuid4(), username, to_db(display_name), password_hash)).fetchone()
except pg_errors.UniqueViolation:
# Не «проверить, потом вставить» (между этими шагами успеет вклиниться другой запрос),
# а сразу вставить: уникальный индекс в БД пропустит ровно одну регистрацию.
raise Conflict("Имя пользователя уже занято") from None
return _user(row)
def get_credentials(self, username: str) -> tuple[User, str] | None:
"""Пользователь и hash его пароля — только для проверки при входе."""
with self._conn() as conn:
row = conn.execute(
"""SELECT id, username, display_name, created_at, password_hash
FROM users WHERE username = %s""", (username,)).fetchone()
return None if row is None else (_user(row), row[4])
# --- чаты ---
def create_chat(self, creator_id: str, title: str, member_ids: list[str]) -> Chat:
if len(set(member_ids)) != len(member_ids):
raise InvalidRequest("Участники чата повторяются")
if creator_id not in member_ids:
raise InvalidRequest("Создатель чата должен входить в member_ids")
members = sorted(uuid.UUID(m) for m in member_ids)
chat_id = uuid.uuid4()
try:
with self._conn() as conn:
# Одна транзакция: чат и все участники записываются вместе или не записываются вовсе.
with conn.transaction():
self._check_members_exist(conn, members)
created_at = conn.execute(
"INSERT INTO chats (id, title) VALUES (%s, %s) RETURNING created_at",
(chat_id, to_db(title))).fetchone()[0]
with conn.cursor() as cur:
cur.executemany("INSERT INTO chat_members (chat_id, user_id) VALUES (%s, %s)",
[(chat_id, m) for m in members])
except pg_errors.ForeignKeyViolation:
# Сюда попадаем, только если проверка выше пропустила несуществующего участника.
# Транзакция уже откатилась: строки чата в базе не осталось.
raise InvalidRequest("Среди участников есть несуществующий пользователь") from None
return Chat(str(chat_id), title, tuple(str(m) for m in members), ts(created_at))
@staticmethod
def _check_members_exist(conn, members: list[uuid.UUID]) -> None:
found = conn.execute("SELECT count(*) FROM users WHERE id = ANY(%s)", (members,)).fetchone()[0]
if found != len(members):
raise InvalidRequest("Среди участников есть несуществующий пользователь")
def get_chat(self, user_id: str, chat_id: str) -> Chat:
with self._conn() as conn:
row = conn.execute(
f"""SELECT {_CHAT_COLUMNS} FROM chats c
WHERE c.id = %s AND EXISTS (
SELECT 1 FROM chat_members cm WHERE cm.chat_id = c.id AND cm.user_id = %s)""",
(uuid.UUID(chat_id), uuid.UUID(user_id))).fetchone()
if row is None:
# Один и тот же ответ для «чата нет» и «чат чужой»:
# посторонний не должен узнать, что такой чат существует.
raise NotFound("Чат не найден")
return _chat(row)
def list_chats(self, user_id: str, after: tuple[datetime, uuid.UUID] | None, limit: int):
query = f"""SELECT {_CHAT_COLUMNS}
FROM chat_members me JOIN chats c ON c.id = me.chat_id
WHERE me.user_id = %s {{after}}
ORDER BY c.created_at, c.id
LIMIT %s"""
params: list = [uuid.UUID(user_id)]
if after is None:
query = query.format(after="")
else:
query = query.format(after="AND (c.created_at, c.id) > (%s, %s)")
params += [after[0], after[1]]
with self._conn() as conn:
rows = conn.execute(query, (*params, limit + 1)).fetchall()
return [_chat(r) for r in rows[:limit]], len(rows) > limit
# --- сообщения ---
def add_message(self, user_id: str, chat_id: str, text: str,
idempotency_key: str, request_hash: bytes) -> tuple[Message, bool]:
"""Сохраняет сообщение ровно один раз на ключ. Возвращает (сообщение, это_повтор).
Ключ и SHA-256 тела запроса лежат прямо в строке сообщения, а уникальное ограничение
(chat_id, sender_id, idempotency_key) не даёт записать второе сообщение с тем же ключом.
Поэтому само сообщение и «запомненный результат» — одна строка и один INSERT:
они сохраняются атомарно, по отдельности их записать нельзя.
Два одновременных запроса с одним ключом (даже через разные реплики): PostgreSQL
заставляет второй INSERT ждать, пока завершится транзакция первого. Первый закоммитил —
у второго ON CONFLICT DO NOTHING ничего не вставляет, и он читает готовую строку.
Первый откатился (ошибка, 5xx) — второй просто вставляет: неудача ключ не «занимает».
"""
chat, user = uuid.UUID(chat_id), uuid.UUID(user_id)
with self._conn() as conn:
# Один SQL-оператор: вставка произойдёт, только если отправитель — участник чата.
# Отправитель берётся из сессии, а не из тела запроса.
row = conn.execute(
"""INSERT INTO messages (id, chat_id, sender_id, text, idempotency_key, request_hash)
SELECT %s, cm.chat_id, cm.user_id, %s, %s, %s
FROM chat_members cm WHERE cm.chat_id = %s AND cm.user_id = %s
ON CONFLICT (chat_id, sender_id, idempotency_key) DO NOTHING
RETURNING id, chat_id, sender_id, text, created_at""",
(uuid.uuid4(), to_db(text), idempotency_key, request_hash, chat, user)).fetchone()
if row is not None:
return _message(row), False # новое сообщение
# Ничего не вставилось: либо пользователь не участник чата, либо ключ уже использован.
# Повтор тоже заново проверяет доступ (сессию уже проверил middleware).
member = conn.execute("SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s",
(chat, user)).fetchone()
if member is None:
raise NotFound("Чат не найден")
saved = conn.execute(
"""SELECT id, chat_id, sender_id, text, created_at, request_hash FROM messages
WHERE chat_id = %s AND sender_id = %s AND idempotency_key = %s""",
(chat, user, idempotency_key)).fetchone()
if saved is None:
# Не должно случаться (строка с ключом есть, раз INSERT ничего не вставил).
# Ответ 503 ничего не фиксирует: клиент повторит запрос с тем же ключом.
raise Unavailable("Повторите запрос")
if bytes(saved[5]) != request_hash:
raise Conflict("Idempotency-Key уже использован с другим телом запроса")
return _message(saved[:5]), True # тот же ответ, что и в первый раз
def list_messages(self, user_id: str, chat_id: str,
after: tuple[datetime, uuid.UUID] | None, limit: int):
chat, user = uuid.UUID(chat_id), uuid.UUID(user_id)
# Keyset-пагинация: «следующие limit записей после ключа», а не OFFSET.
# С индексом (chat_id, created_at, id) база сразу встаёт на нужное место индекса
# и читает только limit+1 строк, сколько бы сообщений ни было в чате.
if after is None:
query = """SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = %s
ORDER BY created_at, id LIMIT %s"""
params = (chat, limit + 1)
else:
query = """SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = %s AND (created_at, id) > (%s, %s)
ORDER BY created_at, id LIMIT %s"""
params = (chat, after[0], after[1], limit + 1)
with self._conn() as conn:
member = conn.execute("SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s",
(chat, user)).fetchone()
if member is None:
raise NotFound("Чат не найден")
rows = conn.execute(query, params).fetchall()
return [_message(r) for r in rows[:limit]], len(rows) > limit
# --- сессии (источник истины; Valkey — только кэш, см. sessions.py) ---
def create_session(self, token_hash: bytes, user_id: str, ttl_seconds: int) -> datetime:
with self._conn() as conn, conn.transaction():
# Заодно убираем у этого пользователя истёкшие и отозванные сессии: они уже не нужны.
conn.execute("""DELETE FROM sessions
WHERE user_id = %s AND (expires_at <= now() OR revoked_at IS NOT NULL)""",
(uuid.UUID(user_id),))
# Срок жизни считает часами PostgreSQL — теми же, по которым он потом проверяется.
return conn.execute(
"""INSERT INTO sessions (token_hash, user_id, expires_at)
VALUES (%s, %s, now() + make_interval(secs => %s))
RETURNING expires_at""",
(token_hash, uuid.UUID(user_id), ttl_seconds)).fetchone()[0]
def get_session(self, token_hash: bytes) -> tuple[User, datetime] | None:
"""Пользователь действующей сессии: не отозвана и не истекла. Иначе None."""
with self._conn() as conn:
row = conn.execute(
"""SELECT u.id, u.username, u.display_name, u.created_at, s.expires_at
FROM sessions s JOIN users u ON u.id = s.user_id
WHERE s.token_hash = %s AND s.revoked_at IS NULL AND s.expires_at > now()""",
(token_hash,)).fetchone()
return None if row is None else (_user(row), row[4])
def revoke_session(self, token_hash: bytes) -> bool:
with self._conn() as conn:
cur = conn.execute("UPDATE sessions SET revoked_at = now() "
"WHERE token_hash = %s AND revoked_at IS NULL", (token_hash,))
return cur.rowcount == 1
+51
View File
@@ -0,0 +1,51 @@
"""Отозванный токен не «воскресает» из кэша после возвращения Valkey (замечание к MR).
Запуск: make failure-valkey-pause
Сценарий преподавателя: Valkey ставится на паузу (docker compose pause) — процесс жив,
данные в его памяти сохраняются, но он не отвечает. В это время делается logout: PostgreSQL
отзывает сессию, а убрать запись из кэша нельзя. После unpause в кэше всё ещё лежит старая
запись «токен -> пользователь». Она не должна снова пропускать этот токен.
"""
import time
from helpers import Client, compose, run, wait_ready
def main():
api = Client()
alice, bob, _eve, chat = api.bootstrap()
dave = api.user("dave")
for _ in range(2): # запись о сессии dave точно лежит в кэше
api.call("GET", "/api/v1/users/me", actor=dave, schema="User")
print("pausing valkey (docker compose pause valkey): данные в кэше сохраняются")
compose("pause", "valkey")
try:
api.call("GET", "/api/v1/users/me", actor=dave, schema="User") # этот запрос обнаруживает сбой кэша
api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=dave)
api.call("GET", "/api/v1/users/me", 401, actor=dave)
print("во время паузы: logout -> 204, тот же токен -> 401")
finally:
print("unpausing valkey")
compose("unpause", "valkey")
wait_ready(api)
# Фоновая проверка возвращает кэш в работу в течение 5 с. Смотрим 12 с — дольше, чем она.
deadline = time.monotonic() + 12
checks = 0
while time.monotonic() < deadline:
api.call("GET", "/api/v1/users/me", 401, actor=dave)
api.call("POST", "/api/v1/chats", 401, actor=dave, body={"title": "x", "member_ids": [dave["id"]]})
checks += 1
time.sleep(0.5)
print(f"после unpause: {checks} проверок за 12 с, отозванный токен всегда 401 (и GET, и POST)")
api.call("GET", "/api/v1/users/me", actor=alice, schema="User")
api.message(bob, chat, "после возвращения Valkey")
print("действующие токены других пользователей работают")
print("PASS: revoked session stays revoked after Valkey comes back with stale data")
if __name__ == "__main__":
run(main)
+95
View File
@@ -0,0 +1,95 @@
"""lab3, уровень 4: проверка устройства стенда по реальным контейнерам и docker compose config.
make check-stack (= python student-tests/check_stack.py)
- не меньше 2 работающих реплик api, у них нет опубликованных портов (обойти балансировщик нельзя);
- в балансировщике каждая реплика под проверкой готовности, резервных серверов без проверки нет
(неготовая реплика не получает запросы ни при каких условиях);
- ни у одного сервиса нет container_name (иначе нельзя запустить несколько реплик одного сервиса);
- наружу опубликован только балансировщик и только на 127.0.0.1;
- у каждого работающего контейнера есть лимиты CPU и RAM;
- сети: postgres и valkey только во внутренней сети backend, lb только в edge, api в обеих;
- секреты получает только тот, кому они нужны;
- версии Docker, Compose и образов (для отчёта).
"""
import json
from helpers import check, run
from stand import api_containers, compose_config, compose_output, docker, inspect, lb_rows
def main():
config = compose_config()
services = config["services"]
networks = config.get("networks", {})
print("docker: " + docker("version", "--format", "{{.Server.Version}}"))
print("compose: " + compose_output("version", "--short").strip())
check(not [name for name, svc in services.items() if "container_name" in svc], "container_name is set")
print("container_name: not set for any service (replicas of one service are possible)")
replicas = api_containers()
check(len(replicas) >= 2, f"need >= 2 running api replicas, got {len(replicas)}")
print(f"api replicas running: {len(replicas)} -> {[c[:12] for c in replicas]} "
f"(deploy.replicas = {services['api'].get('deploy', {}).get('replicas')})")
print()
print(f"{'service':<14} {'container':<13} {'cpus':>5} {'memory':>8} {'published ports':<34} networks")
published = {}
for container in sorted(compose_output("ps", "-q").split()):
service = inspect(container, '{{index .Config.Labels "com.docker.compose.service"}}')
nano_cpus = int(inspect(container, "{{.HostConfig.NanoCpus}}") or 0)
memory = int(inspect(container, "{{.HostConfig.Memory}}") or 0)
ports = json.loads(inspect(container, "{{json .NetworkSettings.Ports}}") or "{}") or {}
bindings = [f"{b['HostIp']}:{b['HostPort']}->{port}" for port, items in ports.items() for b in (items or [])]
nets = sorted(json.loads(inspect(container, "{{json .NetworkSettings.Networks}}") or "{}"))
nets = [name.split("_", 1)[-1] for name in nets]
published[service] = published.get(service, []) + bindings
print(f"{service:<14} {container[:12]:<13} {nano_cpus / 1e9:>5.2f} {memory // 2**20:>6}Mi "
f"{', '.join(bindings) or '-':<34} {', '.join(nets)}")
check(nano_cpus > 0 and memory > 0, f"{service} {container[:12]} has no CPU/RAM limit")
print()
check(not published.get("api"), "api publishes ports and can be reached bypassing the balancer")
others = {service: ports for service, ports in published.items() if ports and service != "lb"}
check(not others, f"only the balancer may publish ports, got {others}")
check(published.get("lb") and all(b.startswith("127.0.0.1:") for b in published["lb"]),
"the balancer must be published on 127.0.0.1 only")
print("published: only lb, only on 127.0.0.1 (api replicas have no ports)")
servers = lb_rows("api")
backups = [row["svname"] for row in servers if row.get("bck") == "1"]
unchecked = [row["svname"] for row in servers
if not row.get("status", "").startswith("MAINT") and not row.get("check_status")]
check(not backups, f"backup servers in the balancer: {backups}")
check(not unchecked, f"servers without a readiness check in the balancer: {unchecked}")
in_use = [f"{row['svname']} {row['status']} ({row['check_status']})" for row in servers
if not row.get("status", "").startswith("MAINT")]
print(f"balancer: every api server is under the /health/ready check, no backup servers -> {', '.join(in_use)}")
print("limits: every running container has CPU and RAM limits")
def nets_of(name):
return sorted(services[name].get("networks", {}))
check(nets_of("postgres") == ["backend"] and nets_of("valkey") == ["backend"], "stores must be on backend only")
check(nets_of("lb") == ["edge"], "lb must be on edge only")
check(nets_of("api") == ["backend", "edge"], "api must be on edge and backend")
check(networks.get("backend", {}).get("internal") is True, "backend network must be internal")
print("networks: lb -> edge; api -> edge + backend; postgres, valkey -> backend (internal: no way out)")
def secrets_of(name):
return sorted(item["source"] for item in services[name].get("secrets", []))
expected = {"api": ["cache_url", "database_url"], "migrate": ["database_url"], "lb": [],
"postgres": ["postgres_password"], "valkey": ["valkey_acl"]}
for name, wanted in expected.items():
check(secrets_of(name) == wanted, f"{name} secrets {secrets_of(name)} != {wanted}")
print("secrets: " + "; ".join(f"{name} -> {', '.join(wanted) or 'none'}" for name, wanted in expected.items()))
print("images: " + "; ".join(f"{name} {services[name]['image']}" for name in ("lb", "api", "postgres", "valkey")))
print("PASS: one entry point (lb on 127.0.0.1), >= 2 api replicas without ports and container_name, "
"only ready replicas get traffic, CPU/RAM limits everywhere, stores only on the internal network")
if __name__ == "__main__":
run(main)
+150
View File
@@ -0,0 +1,150 @@
"""Интеграционные тесты хранилища на настоящей PostgreSQL (уровень 4).
Выполняются ВНУТРИ контейнера приложения (там есть psycopg и доступ к БД по сети стенда):
make db-test == docker compose --profile tools run --rm db-test
Что проверяется:
- повторный запуск миграций ничего не меняет;
- составная операция «создать чат» откатывается целиком, если упала на середине;
- одновременная регистрация одного username даёт ровно одного пользователя;
- сама база не даёт записать сообщение от не-участника (внешний ключ);
- (lab3) 20 одновременных add_message с одним Idempotency-Key создают одну строку;
- (lab3) тот же ключ с другим телом — Conflict (409), строка одна;
- (lab3) миграция 004 совместима со старой версией: INSERT сообщения без ключа, как делает
код lab2, по-прежнему работает (поэтому миграцию можно применить до замены реплик).
"""
import hashlib
import threading
import unittest
import uuid
from unittest import mock
import psycopg
from psycopg import errors as pg_errors
from messenger import config, db
from messenger.errors import Conflict, InvalidRequest
from messenger.store import PostgresStore
class StoreIntegrationTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
config.validate()
db.migrate()
cls.pool = db.create_pool()
cls.pool.open(wait=True)
cls.store = PostgresStore(cls.pool)
@classmethod
def tearDownClass(cls):
cls.pool.close()
def scalar(self, sql, *params):
with self.pool.connection() as conn:
return conn.execute(sql, params).fetchone()[0]
def new_user(self):
return self.store.create_user("db_" + uuid.uuid4().hex[:12], "DB test", "not-a-real-hash")
def test_migrations_rerun_is_noop(self):
versions = self.scalar("SELECT array_agg(version ORDER BY version) FROM schema_migrations")
users = self.scalar("SELECT count(*) FROM users")
self.assertEqual(db.migrate(), []) # второй прогон: применять нечего
self.assertEqual(self.scalar("SELECT array_agg(version ORDER BY version) FROM schema_migrations"), versions)
self.assertEqual(self.scalar("SELECT count(*) FROM users"), users)
print(f"\n schema_migrations: {versions}; повторный migrate() ничего не применил")
def test_create_chat_rolls_back_when_failing_midway(self):
alice = self.new_user()
ghost = str(uuid.uuid4()) # такого пользователя нет
title = "rollback-" + uuid.uuid4().hex[:8]
# Отключаем предварительную проверку участников, чтобы ошибка случилась ВНУТРИ транзакции:
# строка чата уже вставлена, а вставка участника-призрака нарушает внешний ключ.
with mock.patch.object(PostgresStore, "_check_members_exist", staticmethod(lambda conn, members: None)):
with self.assertRaises(InvalidRequest):
self.store.create_chat(alice.id, title, [alice.id, ghost])
self.assertEqual(self.scalar("SELECT count(*) FROM chats WHERE title = %s", title), 0)
self.assertEqual(self.scalar("SELECT count(*) FROM chat_members WHERE user_id = %s", uuid.UUID(alice.id)), 0)
print("\n чат с несуществующим участником: транзакция откатилась, строк chats/chat_members не осталось")
def test_concurrent_registration_has_one_winner(self):
username = "dbrace_" + uuid.uuid4().hex[:10]
threads, barrier, results = 20, threading.Barrier(20), []
def register():
barrier.wait()
try:
self.store.create_user(username, "Race", "not-a-real-hash")
results.append("created")
except Conflict:
results.append("conflict")
workers = [threading.Thread(target=register) for _ in range(threads)]
for w in workers:
w.start()
for w in workers:
w.join()
self.assertEqual(results.count("created"), 1)
self.assertEqual(results.count("conflict"), threads - 1)
self.assertEqual(self.scalar("SELECT count(*) FROM users WHERE username = %s", username), 1)
print(f"\n {threads} параллельных create_user: 1 создан, {threads - 1} получили Conflict (409)")
def test_concurrent_same_idempotency_key_creates_one_row(self):
alice = self.new_user()
chat = self.store.create_chat(alice.id, "idem", [alice.id])
key, digest = "db-" + uuid.uuid4().hex, hashlib.sha256(b"same body").digest()
threads, barrier, results, errors = 20, threading.Barrier(20), [], []
def send():
barrier.wait()
try:
results.append(self.store.add_message(alice.id, chat.id, "один раз", key, digest))
except Exception as exc: # noqa: BLE001 — любая ошибка = провал теста
errors.append(exc)
workers = [threading.Thread(target=send) for _ in range(threads)]
for w in workers:
w.start()
for w in workers:
w.join()
self.assertEqual(errors, [])
self.assertEqual(len({message.id for message, _ in results}), 1)
self.assertEqual(sum(1 for _, replayed in results if not replayed), 1)
self.assertEqual(self.scalar("SELECT count(*) FROM messages WHERE chat_id = %s", uuid.UUID(chat.id)), 1)
print(f"\n {threads} одновременных add_message с одним ключом: 1 строка, 1 новое + "
f"{threads - 1} повторов с тем же сообщением")
def test_same_key_other_body_is_conflict(self):
alice = self.new_user()
chat = self.store.create_chat(alice.id, "idem409", [alice.id])
key = "db-" + uuid.uuid4().hex
self.store.add_message(alice.id, chat.id, "первый", key, hashlib.sha256(b"first").digest())
with self.assertRaises(Conflict):
self.store.add_message(alice.id, chat.id, "другой", key, hashlib.sha256(b"other").digest())
self.assertEqual(self.scalar("SELECT count(*) FROM messages WHERE chat_id = %s", uuid.UUID(chat.id)), 1)
print("\n тот же ключ с другим телом: Conflict (409), в базе по-прежнему одна строка")
def test_old_version_insert_without_key_still_works(self):
alice = self.new_user()
chat = self.store.create_chat(alice.id, "compat", [alice.id])
with psycopg.connect(config.DATABASE_URL) as conn:
for _ in range(2): # две строки без ключа: NULL не нарушает уникальность
conn.execute("INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s, %s, %s, %s)",
(uuid.uuid4(), uuid.UUID(chat.id), uuid.UUID(alice.id), b"lab2 style"))
self.assertEqual(self.scalar("SELECT count(*) FROM messages WHERE chat_id = %s AND idempotency_key IS NULL",
uuid.UUID(chat.id)), 2)
print("\n INSERT как в lab2 (без ключа) после миграции 004 работает: старая версия совместима со схемой")
def test_database_rejects_message_from_non_member(self):
alice, mallory = self.new_user(), self.new_user()
chat = self.store.create_chat(alice.id, "fk", [alice.id])
with self.assertRaises(pg_errors.ForeignKeyViolation):
with psycopg.connect(config.DATABASE_URL) as conn:
conn.execute("INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s, %s, %s, 'x')",
(uuid.uuid4(), uuid.UUID(chat.id), uuid.UUID(mallory.id)))
print("\n INSERT сообщения от не-участника напрямую в БД: ForeignKeyViolation")
if __name__ == "__main__":
unittest.main()
+44
View File
@@ -0,0 +1,44 @@
"""Демонстрация для защиты: пользователи, вход, чат, сообщения, logout — через балансировщик.
Запуск: make demo (печатает шаги; пароли и токены не выводятся)
У каждого шага в скобках — какая реплика API ответила (X-Instance-Id = ID контейнера в `make ps`).
"""
import uuid
from helpers import Client, read_history, run
def main():
api = Client()
def who(reply):
return reply["headers"]["X-Instance-Id"]
ready = api.call("GET", "/health/ready", schema="Health")
print(f"1. /health/ready -> 200 ({who(ready)}): API запущен, PostgreSQL доступна, схема актуальна")
alice, bob, eve, chat = api.bootstrap() # регистрация с паролем + вход через Basic у каждого
for name, actor in (("alice", alice), ("bob", bob), ("eve", eve)):
print(f"2. зарегистрирован {name}: {actor['user']['username']}, вход через Basic -> Bearer-токен")
print(f"3. alice создала чат {chat['id']} с bob (eve не участник)")
served = [who(api.call("GET", "/api/v1/users/me", actor=alice, schema="User")) for _ in range(4)]
print(f"4. один и тот же токен alice, 4 запроса -> реплики {served}: повторный вход не нужен")
key = uuid.uuid4().hex
first = api.message(alice, chat, "Привет, Боб! Это сообщение лежит в PostgreSQL", key=key)
again = api.message(alice, chat, "Привет, Боб! Это сообщение лежит в PostgreSQL", key=key)
print(f"5. alice отправила сообщение ({who(first)}) и повторила его с тем же Idempotency-Key "
f"({who(again)}): тот же id {again['json']['id'] == first['json']['id']}")
api.message(bob, chat, "Привет, Алиса! Переживёт перезапуск и отказ реплики")
history, pages = read_history(api, bob, chat["id"], limit=1)
print(f"6. история чата (по 1 сообщению на страницу, страниц: {pages}) — дубля нет:")
names = {alice["id"]: "alice", bob["id"]: "bob"}
for m in history:
print(f" {m['created_at']} {names[m['sender_id']]}: {m['text']}")
api.call("GET", f"/api/v1/chats/{chat['id']}/messages", 404, actor=eve)
print("7. eve читает чужой чат -> 404 (существование чата не раскрывается)")
api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=alice)
after = [who(api.call("GET", "/api/v1/users/me", 401, actor=alice)) for _ in range(2)]
print(f"8. alice logout -> 204, тот же токен -> 401 на репликах {after}")
if __name__ == "__main__":
run(main)
+137
View File
@@ -0,0 +1,137 @@
"""Отказ зависимости (уровень 4). Запуск: make failure-valkey или make failure-postgres
Тест сам останавливает указанный контейнер (docker compose stop), проверяет поведение API
и запускает контейнер обратно (docker compose start). Volumes не трогаются.
valkey — кэш недоступен: API обходит его и работает через PostgreSQL; logout действует сразу.
postgres — источник истины недоступен: обе реплики не готовы (/health/ready = 503), и балансировщик
исключает их из маршрутизации. Даже запрос с действующим токеном, который реплика могла бы
подтвердить из кэша Valkey, через балансировщик получает 503 и до реплики не доходит
(замечание к MR: раньше резервные слоты без проверки пропускали его, и он получал 200).
Сами реплики при этом живы (/health/live = 200 изнутри контейнера).
Запись во время отказа не сохраняется. После запуска БД прежний токен и данные доступны.
"""
import sys
import time
import uuid
from helpers import Client, check, compose, idempotency, read_history, run, wait_ready
from stand import api_containers, lb_summary, lb_up_count, replica_status, try_call
LB_EXCLUDE_TIMEOUT_SECONDS = 15
LOST_TEXT = "во время отказа PostgreSQL, не должно сохраниться " + uuid.uuid4().hex
def timed(fn):
started = time.monotonic()
result = fn()
return result, (time.monotonic() - started) * 1000
def valkey_down(api, alice, bob, chat):
ready, ms = timed(lambda: api.call("GET", "/health/ready", schema="Health"))
print(f"/health/ready -> 200 ({ms:.0f} ms): Valkey не критичен, API готов")
_, ms = timed(lambda: api.call("GET", "/api/v1/users/me", actor=alice, schema="User"))
print(f"existing token: GET /users/me -> 200 ({ms:.0f} ms), сессия проверена по PostgreSQL (этот запрос и обнаружил сбой кэша)")
sent = api.message(bob, chat, "во время отказа Valkey")["json"]
history, _ = read_history(api, alice, chat["id"])
check(sent["id"] in [m["id"] for m in history], "message written during Valkey outage is missing")
print("POST message -> 201, история читается")
carol = api.user("carol") # регистрация и вход тоже работают без кэша
print("register + login new user -> 201")
api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=carol)
api.call("GET", "/api/v1/users/me", 401, actor=carol)
print("logout -> 204, затем тот же токен -> 401 (отзыв записан в PostgreSQL)")
latencies = [timed(lambda: api.call("GET", "/api/v1/users/me", actor=alice))[1] for _ in range(10)]
print(f"10 x GET /users/me без кэша: max {max(latencies):.0f} ms (кэш не ждём на каждом запросе)")
check(max(latencies) < 1000, "requests must not wait for the dead cache on every call")
# Фоновая проверка Valkey идёт раз в 5 с. Ждём дольше и убеждаемся, что запросы её не ждут.
time.sleep(6)
latencies = [timed(lambda: api.call("GET", "/api/v1/users/me", actor=alice))[1] for _ in range(10)]
print(f"через 6 с, ещё 10 x GET /users/me: max {max(latencies):.0f} ms (повторные попытки — в фоне)")
check(max(latencies) < 1000, "periodic reconnect attempts must not block user requests")
return carol
def refused_by_lb(method, path, token=None, body=None, headers=None):
"""Запрос через балансировщик: ждём 503 от САМОГО балансировщика в формате ошибки контракта.
Признак того, что запрос не дошёл до реплики API: в ответе нет X-Instance-Id
(его ставит каждая реплика), а X-Request-Id и request_id в теле — от балансировщика.
"""
reply = try_call(method, path, token=token, body=body, headers=headers, timeout=5)
check(reply is not None, f"{method} {path}: no response from the balancer")
check(reply.status == 503, f"{method} {path}: expected 503 from the balancer, got {reply.status}")
check(not reply.instance, f"{method} {path}: answered by a NOT READY API replica {reply.instance}")
error = (reply.json or {}).get("error") or {}
check(error.get("code") == "unavailable", f"{method} {path}: wrong error format {reply.json}")
check(error.get("request_id") and error["request_id"] == reply.headers.get("x-request-id"),
f"{method} {path}: request_id differs from X-Request-Id")
def postgres_down(api, alice, chat):
started = time.monotonic()
while lb_up_count() > 0:
check(time.monotonic() - started < LB_EXCLUDE_TIMEOUT_SECONDS,
f"HAProxy still routes to a replica {LB_EXCLUDE_TIMEOUT_SECONDS} s after the failure")
time.sleep(0.2)
print(f"HAProxy вывел все реплики из балансировки через {time.monotonic() - started:.1f} с "
f"после остановки PostgreSQL ({lb_summary()})")
for container in api_containers():
live, ready = replica_status(container, "/health/live"), replica_status(container, "/health/ready")
check(live == 200 and ready == 503, f"replica {container[:12]}: live {live}, ready {ready}")
print(f"реплика {container[:12]} изнутри контейнера: /health/live -> {live}, /health/ready -> {ready} "
f"(жива, но не готова)")
# Главное (замечание к MR): токен alice лежит в кэше Valkey, и реплика могла бы ответить 200 без базы.
refused_by_lb("GET", "/api/v1/users/me", token=alice["token"])
print("GET /users/me с действующим токеном (он есть в кэше) -> 503 от балансировщика, без X-Instance-Id: "
"до неготовой реплики запрос не дошёл")
refused_by_lb("GET", "/api/v1/chats", token=alice["token"])
refused_by_lb("GET", f"/api/v1/chats/{chat['id']}/messages", token=alice["token"])
refused_by_lb("POST", f"/api/v1/chats/{chat['id']}/messages", token=alice["token"],
body={"text": LOST_TEXT}, headers=idempotency())
print("бизнес-запросы (список чатов, история, отправка сообщения) -> 503 от балансировщика")
refused_by_lb("GET", "/api/v1/users/me")
refused_by_lb("POST", "/api/v1/users", body={"username": "pg_" + uuid.uuid4().hex[:10],
"display_name": "x", "password": "Pg-down-password"})
refused_by_lb("GET", "/health/ready")
print("без токена, регистрация и /health/ready через балансировщик -> 503: успешного ответа нет ни у кого")
def main():
target = sys.argv[1] if len(sys.argv) > 1 else ""
check(target in ("valkey", "postgres"), "usage: dependency_failure.py valkey|postgres")
api = Client()
alice, bob, _eve, chat = api.bootstrap()
before = api.message(alice, chat, "до отказа " + target)["json"]
for _ in range(4): # запись о сессии alice точно лежит в общем кэше Valkey
api.call("GET", "/api/v1/users/me", actor=alice, schema="User")
print(f"stopping {target} (docker compose stop {target})")
compose("stop", target)
try:
if target == "valkey":
carol = valkey_down(api, alice, bob, chat)
else:
postgres_down(api, alice, chat)
finally:
print(f"starting {target} again")
compose("start", target)
wait_ready(api)
history, _ = read_history(api, alice, chat["id"])
check(before in history, "message confirmed before the outage is lost or changed")
check(all(m["text"] != LOST_TEXT for m in history), "a write refused during the outage was stored")
api.call("GET", "/api/v1/users/me", actor=alice, schema="User")
if target == "valkey":
api.call("GET", "/api/v1/users/me", 401, actor=carol) # отозванный токен не «воскрес» из кэша
print("after recovery: прежний токен работает, подтверждённые сообщения на месте")
if target == "postgres":
print("PASS: postgres outage: not ready replicas were excluded by the balancer, no request reached them, "
"nothing was stored; data and the existing token survived")
else:
print("PASS: valkey outage handled without the cache; revoked tokens stay revoked")
if __name__ == "__main__":
run(main)
+46
View File
@@ -0,0 +1,46 @@
"""Проверка истечения сессии при коротком TTL (уровень 4). Запуск: make expiry
Нужен второй экземпляр API с SESSION_TTL_SECONDS=2 (сервис api-short-ttl, make expiry
поднимает его сам). С lab3 он, как и основные реплики, доступен только через балансировщик:
127.0.0.1:8081. База и кэш общие с основным API.
Сценарий: вход -> токен работает (и попадает в кэш Valkey) -> ждём истечения ->
токен отклоняется с 401 и на коротком, и на основном API. Значит, срок жизни — свойство
сессии в PostgreSQL, а кэш не продлевает её.
"""
import datetime as dt
import os
import time
import uuid
from helpers import Client, check, login, run, wait_ready
def main():
short = Client(os.environ.get("BASE_URL_TTL", "http://127.0.0.1:8081"))
main_api = Client()
# Контейнер уже healthy, но балансировщику нужно ещё пару секунд: найти его по DNS
# и пройти 2 проверки готовности. Ждём готовности именно через балансировщик (:8081).
wait_ready(short, seconds=60)
body = {"username": "ttl_" + uuid.uuid4().hex[:12], "display_name": "TTL", "password": "Ttl-password-123"}
short.call("POST", "/api/v1/users", 201, body=body, schema="User")
session = login(short, body["username"], body["password"])
auth = {"Authorization": "Bearer " + session["token"]}
expires_at = dt.datetime.fromisoformat(session["expires_at"].replace("Z", "+00:00"))
ttl = (expires_at - dt.datetime.now(dt.timezone.utc)).total_seconds()
print(f"session issued by short-TTL API, expires in {ttl:.2f}s")
check(0 < ttl <= 3, "short-TTL instance must issue ~2 second sessions")
for api in (short, short, main_api): # два раза подряд: второй ответ уже из кэша
api.call("GET", "/api/v1/users/me", 200, headers=auth, schema="User")
print("before expiry: GET /users/me -> 200 (short API twice, main API once)")
time.sleep(max(0.0, (expires_at - dt.datetime.now(dt.timezone.utc)).total_seconds()) + 1.0)
for api in (short, main_api):
api.call("GET", "/api/v1/users/me", 401, headers=auth) # клиент проверяет WWW-Authenticate: Bearer
print("after expiry: GET /users/me -> 401 on both instances")
print("PASS: session expired after SESSION_TTL_SECONDS; cache did not extend it")
if __name__ == "__main__":
run(main)
+148
View File
@@ -0,0 +1,148 @@
"""lab3, уровень 4: по очереди останавливаем КАЖДУЮ реплику API под нагрузкой и меряем.
make failover-metrics (= python student-tests/failover_metrics.py: stop и kill)
python student-tests/failover_metrics.py stop (только плановая остановка)
Режимы:
stop — docker stop (SIGTERM): плановая остановка. Реплика сначала отвечает 503 на /health/ready,
HAProxy выводит её из балансировки, и только потом она закрывает приём (__main__.py).
kill — docker kill (SIGKILL): авария. Процесс умирает сразу, начатые на нём запросы обрываются,
клиент повторяет их с тем же Idempotency-Key.
Нагрузка (loadgen.py): 4 потока пишут сообщения без пауз, 1 поток читает историю, timeout клиента 2 с.
Меряем: успешные записи в секунду до и после отказа, ошибки и их коды, через сколько HAProxy вывел
реплику (по его статистике, опрос раз в 0,1 с), через сколько прекратились ошибки, отвечала ли
остановленная реплика после остановки, нет ли потерь и дублей. Затем реплика запускается снова
(docker start) и ждём, пока HAProxy вернёт её, — только потом следующий прогон.
Итог: таблица в консоли и evidence/failover-metrics.json (без токенов).
"""
import json
import platform
import sys
import threading
import time
from helpers import ROOT, check, run
from loadgen import CLIENT_TIMEOUT_SECONDS, WRITERS, Load, summary
from stand import api_containers, docker, lb_up_count, wait_balanced
WARMUP_SECONDS = 3
AFTER_SECONDS = 10
OUTPUT = ROOT / "evidence" / "failover-metrics.json"
class LbWatch:
"""Раз в 0,1 с спрашивает у HAProxy, сколько реплик в балансировке (UP)."""
def __init__(self):
self.points, self.stopping = [], threading.Event()
self.thread = threading.Thread(target=self._run, daemon=True)
def _run(self):
while not self.stopping.is_set():
try:
self.points.append((time.monotonic(), lb_up_count()))
except OSError:
pass
time.sleep(0.1)
def start(self):
self.thread.start()
def stop(self):
self.stopping.set()
self.thread.join(timeout=3)
def first_drop(self, after, replicas):
return next((t for t, up in self.points if t >= after and up < replicas), None)
def measure(container, mode, replicas):
wait_balanced(replicas)
load, watch = Load(), LbWatch()
watch.start()
load.start()
time.sleep(WARMUP_SECONDS)
t0 = time.monotonic()
if mode == "stop":
docker("stop", "--time", "8", container)
else:
docker("kill", container)
command_seconds = time.monotonic() - t0
time.sleep(max(0.0, AFTER_SECONDS - command_seconds))
end = t0 + AFTER_SECONDS
load.stop()
watch.stop()
errors = [e for e in load.window(t0 - WARMUP_SECONDS, end) if not e[2]]
errors_end = max((e[0] + e[5] for e in errors), default=None)
drop = watch.first_drop(t0, replicas)
served_after = [e[4] for e in load.window(t0 + command_seconds, end) if e[2]]
target_hits = sum(1 for instance in served_after if instance and container.startswith(instance))
integrity = load.verify()
started = time.monotonic()
docker("start", container)
wait_balanced(replicas)
rejoin_seconds = time.monotonic() - started
return {
"replica": container[:12],
"mode": mode,
"command_seconds": round(command_seconds, 2),
"lb_excluded_after_seconds": round(drop - t0, 2) if drop else None,
"errors": len(errors),
"error_codes": summary(load, t0 - WARMUP_SECONDS, end)["error_codes"],
"errors_stopped_after_seconds": round(errors_end - t0, 2) if errors_end else 0.0,
"before": summary(load, t0 - WARMUP_SECONDS, t0),
"after": summary(load, t0, end),
"stopped_replica_answers_after_stop": target_hits,
"integrity": integrity,
"rejoin_seconds": round(rejoin_seconds, 2),
}
def main():
modes = sys.argv[1:] or ["stop", "kill"]
check(set(modes) <= {"stop", "kill"}, "usage: python student-tests/failover_metrics.py [stop] [kill]")
containers = api_containers()
replicas = len(containers)
check(replicas >= 2, "need at least 2 running api replicas")
print(f"api replicas: {[c[:12] for c in containers]}; load: {WRITERS} writers without pauses + 1 reader, "
f"client timeout {CLIENT_TIMEOUT_SECONDS} s, retry with the same Idempotency-Key; "
f"{WARMUP_SECONDS} s before and {AFTER_SECONDS} s after the failure")
runs = []
for container in containers:
for mode in modes:
print(f"--- {mode} {container[:12]} ...")
run = measure(container, mode, replicas)
runs.append(run)
print(f" docker {mode}: {run['command_seconds']} s; HAProxy excluded it after "
f"{run['lb_excluded_after_seconds']} s; errors: {run['errors']} {run['error_codes']}, "
f"last error ended {run['errors_stopped_after_seconds']} s after the failure")
print(f" write RPS before {run['before']['write_rps']} -> after {run['after']['write_rps']}; "
f"p95 after {run['after']['write_p95_ms']} ms, max {run['after']['write_max_ms']} ms; "
f"answers from the stopped replica after stop: {run['stopped_replica_answers_after_stop']}")
print(f" confirmed {run['integrity']['confirmed_writes']}, in history "
f"{run['integrity']['messages_in_history']}, lost 0, duplicates 0; "
f"back in the balancer {run['rejoin_seconds']} s after docker start")
check(run["stopped_replica_answers_after_stop"] == 0, "the stopped replica still answered")
check(run["after"]["write_rps"] > 0, "no successful writes after the failure")
print()
print("replica mode cmd,s lb_out,s errors errors_end,s rps_before rps_after p95_after,ms rejoin,s")
for r in runs:
print(f"{r['replica']} {r['mode']:<4} {r['command_seconds']:>5} {str(r['lb_excluded_after_seconds']):>8} "
f"{r['errors']:>6} {r['errors_stopped_after_seconds']:>12} {r['before']['write_rps']:>10} "
f"{r['after']['write_rps']:>9} {str(r['after']['write_p95_ms']):>12} {r['rejoin_seconds']:>8}")
OUTPUT.parent.mkdir(exist_ok=True)
OUTPUT.write_text(json.dumps({
"profile": {"writers": WRITERS, "readers": 1, "client_timeout_seconds": CLIENT_TIMEOUT_SECONDS,
"warmup_seconds": WARMUP_SECONDS, "after_seconds": AFTER_SECONDS, "replicas": replicas,
"client_python": platform.python_version()},
"runs": runs,
}, indent=2) + "\n", encoding="utf-8")
print(f"PASS: every replica was stopped ({', '.join(modes)}) and restored; no lost or duplicated messages; "
f"saved {OUTPUT.relative_to(ROOT).as_posix()}")
if __name__ == "__main__":
run(main)
+71
View File
@@ -0,0 +1,71 @@
"""Общие помощники для собственных тестов.
Переиспользуем публичный HTTP-клиент курса (tests/client.py), а не пишем свой:
он уже проверяет X-Request-Id, X-Instance-Id (с lab3), формат ошибок, WWW-Authenticate
и схемы ответов из контракта.
С lab2 клиент сам регистрирует пользователя с паролем, входит через Basic
и подставляет Bearer-токен (токен живёт только в памяти теста и не печатается).
"""
import base64
import subprocess
import sys
import time
import uuid
from pathlib import Path
from urllib.parse import quote
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "tests"))
from client import Client, Failure, check, run # noqa: E402 (импорт после правки sys.path)
__all__ = ["Client", "Failure", "check", "run", "read_history", "basic", "login", "compose", "wait_ready",
"idempotency", "ROOT"]
def idempotency(key=None):
"""Заголовок Idempotency-Key (обязателен для POST сообщения с lab3). Без аргумента — новый ключ."""
return {"Idempotency-Key": key or uuid.uuid4().hex}
def read_history(api, actor, chat_id, limit=100):
"""Читает всю историю чата по страницам. Возвращает (сообщения, число_страниц)."""
items, pages, cursor = [], 0, None
while True:
query = f"?limit={limit}" + (f"&cursor={quote(cursor, safe='')}" if cursor else "")
page = api.call("GET", f"/api/v1/chats/{chat_id}/messages{query}",
actor=actor, schema="MessagePage")["json"]
items += page["items"]
pages += 1
cursor = page["next_cursor"]
if cursor is None:
return items, pages
def basic(username, password):
"""Значение заголовка Authorization: Basic base64(username:password), пароль в UTF-8."""
return "Basic " + base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("ascii")
def login(api, username, password, expected=201):
"""POST /auth/sessions; при успехе возвращает тело Session (токен — только в памяти)."""
schema = "Session" if expected == 201 else None
return api.call("POST", "/api/v1/auth/sessions", expected,
headers={"Authorization": basic(username, password)}, schema=schema)["json"]
def compose(*args):
"""docker compose <args> из корня репозитория; вывод скрыт (там могут быть имена/секреты)."""
subprocess.run(["docker", "compose", *args], cwd=ROOT, check=True,
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
def wait_ready(api, seconds=90):
deadline = time.monotonic() + seconds
while True:
try:
api.call("GET", "/health/ready", schema="Health")
return
except Failure:
check(time.monotonic() < deadline, f"API не стал готов за {seconds} с")
time.sleep(0.5)
+78
View File
@@ -0,0 +1,78 @@
"""Профиль нагрузки для отчёта: публичный tests/load.py + CPU/RAM контейнеров во время нагрузки.
python student-tests/load_profile.py (30 с, 4 потока — как в tests/README.md)
Запускает tests/load.py (closed loop: каждый поток шлёт следующий POST сразу после ответа)
и параллельно раз в ~2 с снимает `docker stats --no-stream` по контейнерам стенда.
Сохраняет evidence/load.json (вывод load.py: успешные RPS, ошибки, p50/p95/p99)
и evidence/load-stats.json (максимум CPU % и RAM по каждому сервису за время нагрузки).
Числа зависят от машины и Docker Desktop; это замер этого стенда, а не предел пропускной способности.
"""
import json
import subprocess
import sys
import threading
import time
from helpers import ROOT, check, run
from stand import BASE_URL, compose_output, inspect
DURATION, CONCURRENCY = 30, 4
LOAD_JSON = ROOT / "evidence" / "load.json"
STATS_JSON = ROOT / "evidence" / "load-stats.json"
def mib(text):
"""'123.4MiB' / '1.2GiB' / '512kB' -> MiB."""
text = text.strip()
units = {"KiB": 1 / 1024, "kB": 1 / 1024, "MiB": 1, "MB": 1, "GiB": 1024, "GB": 1024, "B": 1 / 2**20}
for unit in sorted(units, key=len, reverse=True):
if text.endswith(unit):
return float(text[: -len(unit)]) * units[unit]
return 0.0
def main():
# Только основной путь запроса: балансировщик, реплики API, PostgreSQL, Valkey.
names = {c[:12]: inspect(c, '{{index .Config.Labels "com.docker.compose.service"}}')
for c in compose_output("ps", "-q").split()}
names = {cid: service for cid, service in names.items() if service in ("lb", "api", "postgres", "valkey")}
containers = list(names)
peaks, stopping = {}, threading.Event()
def sample():
while not stopping.is_set():
result = subprocess.run(["docker", "stats", "--no-stream", "--format", "{{json .}}", *containers],
capture_output=True, text=True)
for line in result.stdout.splitlines():
item = json.loads(line)
key = item["ID"][:12]
cpu = float(item["CPUPerc"].rstrip("%") or 0)
used, _, limit = item["MemUsage"].partition("/")
peak = peaks.setdefault(key, {"service": names.get(key, "?"), "cpu_percent_max": 0.0,
"mem_mib_max": 0.0, "mem_limit_mib": round(mib(limit))})
peak["cpu_percent_max"] = max(peak["cpu_percent_max"], cpu)
peak["mem_mib_max"] = round(max(peak["mem_mib_max"], mib(used)), 1)
time.sleep(1)
sampler = threading.Thread(target=sample, daemon=True)
sampler.start()
result = subprocess.run([sys.executable, "tests/load.py", "--base-url", BASE_URL, "--duration", str(DURATION),
"--concurrency", str(CONCURRENCY), "--output", str(LOAD_JSON)],
cwd=ROOT, capture_output=True)
stopping.set()
sampler.join(timeout=10)
print(result.stdout.decode("utf-8", "replace").strip())
check(result.returncode == 0, "tests/load.py failed: " + result.stderr.decode("utf-8", "replace")[-300:])
rows = sorted(peaks.values(), key=lambda row: row["service"])
STATS_JSON.write_text(json.dumps({"duration_seconds": DURATION, "concurrency": CONCURRENCY,
"containers": rows}, indent=2) + "\n", encoding="utf-8")
print("\nservice cpu % max RAM max / limit, MiB")
for row in rows:
print(f"{row['service']:<14} {row['cpu_percent_max']:>9.1f} {row['mem_mib_max']:>7.1f} / {row['mem_limit_mib']}")
print(f"PASS: load profile saved to {LOAD_JSON.relative_to(ROOT).as_posix()} and "
f"{STATS_JSON.relative_to(ROOT).as_posix()}")
if __name__ == "__main__":
run(main)
+120
View File
@@ -0,0 +1,120 @@
"""Фоновая нагрузка для замеров во время отказа и rolling update
(используют failover_metrics.py и rolling_update.py). Только стандартная библиотека.
WRITERS потоков без пауз пишут сообщения в один чат (closed loop: следующий запрос — сразу после
ответа на предыдущий). Если запрос не подтверждён (обрыв, timeout, 5xx), поток повторяет ТОТ ЖЕ
запрос с ТЕМ ЖЕ Idempotency-Key — так по контракту делает клиент. Один поток параллельно читает
историю. Каждая попытка записывается: время, успех, код, реплика, задержка.
В конце verify() читает всю историю и проверяет, что все подтверждённые сообщения на месте
и дублей нет (тексты уникальны, поэтому дубль сразу виден).
"""
import math
import threading
import time
import uuid
from helpers import Client, check, read_history
from stand import try_call
WRITERS = 4
CLIENT_TIMEOUT_SECONDS = 2
class Load:
def __init__(self, writers=WRITERS, timeout=CLIENT_TIMEOUT_SECONDS):
self.api = Client()
self.alice, self.bob = self.api.user("load_a"), self.api.user("load_b")
self.chat = self.api.call("POST", "/api/v1/chats", 201, actor=self.alice, schema="Chat",
body={"title": "load", "member_ids": [self.alice["id"], self.bob["id"]]})["json"]
self.writers, self.timeout = writers, timeout
self.events = [] # (время старта, "write"/"read", ok, код или "conn", реплика, задержка в с)
self.confirmed = [] # сообщения, на которые пришёл 201
self.lock = threading.Lock()
self.stopping = threading.Event()
self.threads = []
def _record(self, kind, started, reply, ok):
code = reply.status if reply is not None else "conn"
instance = reply.instance if reply is not None else None
with self.lock:
self.events.append((started, kind, ok, code, instance, time.monotonic() - started))
def _writer(self, number):
path = f"/api/v1/chats/{self.chat['id']}/messages"
sent = 0
key, text = uuid.uuid4().hex, f"load-{number}-{sent}"
while not self.stopping.is_set():
started = time.monotonic()
reply = try_call("POST", path, body={"text": text}, token=self.alice["token"],
headers={"Idempotency-Key": key}, timeout=self.timeout)
ok = reply is not None and reply.status == 201
self._record("write", started, reply, ok)
if ok:
with self.lock:
self.confirmed.append(reply.json)
sent += 1
key, text = uuid.uuid4().hex, f"load-{number}-{sent}"
else:
time.sleep(0.05) # и повторить тот же text с тем же ключом
def _reader(self):
path = f"/api/v1/chats/{self.chat['id']}/messages?limit=20"
while not self.stopping.is_set():
started = time.monotonic()
reply = try_call("GET", path, token=self.bob["token"], timeout=self.timeout)
self._record("read", started, reply, reply is not None and reply.status == 200)
time.sleep(0.05)
def start(self):
self.threads = [threading.Thread(target=self._writer, args=(n,), daemon=True) for n in range(self.writers)]
self.threads.append(threading.Thread(target=self._reader, daemon=True))
for thread in self.threads:
thread.start()
def stop(self):
self.stopping.set()
for thread in self.threads:
thread.join(timeout=self.timeout + 5)
def window(self, start, end, kind=None):
with self.lock:
return [e for e in self.events if start <= e[0] < end and (kind is None or e[1] == kind)]
def verify(self):
"""Все подтверждённые сообщения есть в истории, id и тексты не повторяются."""
history, _ = read_history(self.api, self.bob, self.chat["id"])
ids = [message["id"] for message in history]
texts = [message["text"] for message in history]
by_id = {message["id"]: message for message in history}
check(len(ids) == len(set(ids)), "duplicated message ids in history")
check(len(texts) == len(set(texts)), "a retried request created a duplicate message")
lost = [m for m in self.confirmed if by_id.get(m["id"]) != m]
check(not lost, f"{len(lost)} confirmed messages are lost or changed")
return {"confirmed_writes": len(self.confirmed), "messages_in_history": len(history),
"duplicates": 0, "lost": 0}
def summary(load, start, end):
"""Успешные записи в секунду, ошибки по кодам и задержки успешных записей на отрезке [start, end)."""
events = load.window(start, end)
writes = [e for e in events if e[1] == "write"]
ok_writes = sorted(e[5] for e in writes if e[2])
errors = [e for e in events if not e[2]]
seconds = max(end - start, 1e-6)
def percentile(p):
return round(1000 * ok_writes[max(0, math.ceil(p * len(ok_writes)) - 1)], 1) if ok_writes else None
codes = {}
for e in errors:
codes[str(e[3])] = codes.get(str(e[3]), 0) + 1
return {
"seconds": round(seconds, 2),
"write_rps": round(len(ok_writes) / seconds, 1),
"reads": len([e for e in events if e[1] == "read"]),
"errors": len(errors),
"error_codes": codes,
"write_p50_ms": percentile(0.50),
"write_p95_ms": percentile(0.95),
"write_max_ms": round(1000 * ok_writes[-1], 1) if ok_writes else None,
}
+75
View File
@@ -0,0 +1,75 @@
"""Проверка гонок (уровень 4). Запуск: make race
1. 10 клиентов одновременно отправляют по 10 сообщений в один чат:
в истории ровно 100 сообщений, все id уникальны, ни один текст не потерян.
2. 20 клиентов одновременно регистрируют ОДИН И ТОТ ЖЕ username:
ровно один получает 201, остальные 409; в базе один такой пользователь.
Защита — уникальный индекс users.username в PostgreSQL, а не проверка в коде.
"""
import threading
import time
import uuid
from concurrent.futures import ThreadPoolExecutor
from helpers import Client, check, idempotency, read_history, run
CLIENTS = 10
PER_CLIENT = 10
REGISTRATIONS = 20
def concurrent_messages(api):
users = [api.user(f"race{i}") for i in range(CLIENTS)]
chat = api.call("POST", "/api/v1/chats", 201, actor=users[0], schema="Chat",
body={"title": "race", "member_ids": [u["id"] for u in users]})["json"]
path = f"/api/v1/chats/{chat['id']}/messages"
start_together = threading.Barrier(CLIENTS) # все потоки стартуют одновременно
def send_all(index):
client = Client() # у каждого «клиента» свои HTTP-соединения
start_together.wait()
for n in range(PER_CLIENT):
client.call("POST", path, 201, actor=users[index], body={"text": f"client-{index}-msg-{n}"},
headers=idempotency())
started = time.monotonic()
with ThreadPoolExecutor(max_workers=CLIENTS) as pool:
list(pool.map(send_all, range(CLIENTS))) # list() пробрасывает ошибки из потоков
elapsed = time.monotonic() - started
history, pages = read_history(api, users[0], chat["id"], limit=25)
expected = {f"client-{i}-msg-{n}" for i in range(CLIENTS) for n in range(PER_CLIENT)}
print(f"messages: sent {CLIENTS * PER_CLIENT} from {CLIENTS} parallel clients in {elapsed:.2f}s")
print(f"messages: read {len(history)} in {pages} pages, unique ids: {len({m['id'] for m in history})}")
check(len(history) == CLIENTS * PER_CLIENT, "wrong number of messages")
check(len({m["id"] for m in history}) == len(history), "duplicate message ids")
check({m["text"] for m in history} == expected, "lost or corrupted message texts")
print("PASS: 100 concurrent messages stored without loss or duplicates")
def concurrent_registration():
username = "race_" + uuid.uuid4().hex[:12]
start_together = threading.Barrier(REGISTRATIONS)
def register(index):
client = Client()
body = {"username": username, "display_name": f"Участник {index}", "password": f"Race-password-{index:03d}"}
start_together.wait()
return client.call("POST", "/api/v1/users", [201, 409], body=body)["status"]
with ThreadPoolExecutor(max_workers=REGISTRATIONS) as pool:
statuses = list(pool.map(register, range(REGISTRATIONS)))
created, conflicts = statuses.count(201), statuses.count(409)
print(f"registration: {REGISTRATIONS} parallel requests for one username -> 201 x{created}, 409 x{conflicts}")
check(created == 1 and conflicts == REGISTRATIONS - 1, "exactly one registration must win")
print("PASS: concurrent registration of the same username created exactly one user")
def main():
api = Client()
concurrent_messages(api)
concurrent_registration()
if __name__ == "__main__":
run(main)
+142
View File
@@ -0,0 +1,142 @@
"""Таблицы замеров для REPORT.md из evidence/*.json (без ручного переписывания чисел).
make report-tables (= python student-tests/report_tables.py)
Берёт evidence/failover-metrics.json, rolling-update.json, load.json, load-stats.json
и время из evidence/persistence.txt, собирает markdown-таблицы и вставляет их в REPORT.md
между метками <!-- measurements:begin --> и <!-- measurements:end -->. Запускать после
make failover-metrics, make rolling-update, make load-profile и make persistence.
"""
import json
import re
from helpers import ROOT, check, run
EVIDENCE = ROOT / "evidence"
REPORT = ROOT / "REPORT.md"
BEGIN, END = "<!-- measurements:begin -->", "<!-- measurements:end -->"
def load(name):
path = EVIDENCE / name
return json.loads(path.read_text(encoding="utf-8")) if path.exists() else None
def codes(mapping):
return ", ".join(f"{code}: {count}" for code, count in mapping.items()) or "-"
def failover_table(data):
lines = [
f"Остановка каждой реплики под нагрузкой (`make failover-metrics`, evidence/failover-metrics.json): "
f"{data['profile']['writers']} потока пишут сообщения без пауз, 1 читает историю, timeout клиента "
f"{data['profile']['client_timeout_seconds']} с, неподтверждённая запись повторяется с тем же ключом; "
f"{data['profile']['warmup_seconds']} с до отказа и {data['profile']['after_seconds']} с после. "
"stop = `docker stop` (SIGTERM, плановая остановка), kill = `docker kill` (SIGKILL, авария).",
"",
"| Реплика | Отказ | Вывод из LB, с | Ошибок (коды) | Ошибки закончились через, с | Записей/с до → после | "
"p95 записи после, мс | Возврат в LB после `docker start`, с | Потери / дубли |",
"| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
]
for r in data["runs"]:
lines.append(f"| {r['replica']} | {r['mode']} | {r['lb_excluded_after_seconds']} | {r['errors']} "
f"({codes(r['error_codes'])}) | {r['errors_stopped_after_seconds']} | "
f"{r['before']['write_rps']} → {r['after']['write_rps']} | {r['after']['write_p95_ms']} | "
f"{r['rejoin_seconds']} | 0 / 0 (подтверждено {r['integrity']['confirmed_writes']}) |")
return lines
def rolling_lines(data):
during = data["during"]
steps = "; ".join(f"{s['old']} → {s['new']}: новая готова через {s['new_ready_seconds']} с, шаг {s['step_seconds']} с"
for s in data["steps"])
return [f"Rolling update под той же нагрузкой (`make rolling-update`, evidence/rolling-update.json): версия "
f"{data['from_version']} → {data['to_version']}, {data['replicas']} реплики заменены по одной за "
f"{data['update_seconds']} с ({steps}). Записей/с до: {data['before']['write_rps']}, во время замены: "
f"{during['write_rps']}; ошибок: {during['errors']} ({codes(during['error_codes'])}); p95 "
f"{during['write_p95_ms']} мс, максимум {during['write_max_ms']} мс; подтверждено "
f"{data['integrity']['confirmed_writes']} сообщений, потерь и дублей нет."]
def load_lines(data, stats):
latency = data["successful_latency_ms"]
lines = [f"Публичный генератор нагрузки (`make load-profile` = `tests/load.py`, closed loop, {data['concurrency']} "
f"потока, {data['requested_duration_seconds']:.0f} с, 2 реплики): {data['successful_rps']} успешных "
f"POST/с, ошибок {data['failed_requests']} (доля {data['error_ratio']}), задержка успешных: p50 "
f"{latency['p50']} мс, p95 {latency['p95']} мс, p99 {latency['p99']} мс."]
if stats:
lines += ["", "| Сервис | CPU, % макс. (100 % = 1 ядро) | RAM макс. / лимит, МиБ |", "| --- | --- | --- |"]
lines += [f"| {row['service']} | {row['cpu_percent_max']:.1f} | {row['mem_mib_max']:.0f} / {row['mem_limit_mib']} |"
for row in stats["containers"]]
return lines
def impacts(failover, rolling):
rows = ["| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |",
"| --- | --- | --- | --- |"]
if failover:
for mode, title, expect in (
("stop", "`docker stop` одной реплики (по очереди каждой)",
"реплика сама уходит из балансировки до выхода; ошибок нет"),
("kill", "`docker kill` одной реплики (по очереди каждой)",
"несколько 502 у запросов, начатых на ней; клиент повторяет с тем же ключом")):
runs = [r for r in failover["runs"] if r["mode"] == mode]
if not runs:
continue
errors = sum(r["errors"] for r in runs)
out = max(r["lb_excluded_after_seconds"] or 0 for r in runs)
end = max(r["errors_stopped_after_seconds"] for r in runs)
recovery = f"ошибки закончились не позже {end} с после отказа" if errors else "ошибок не было"
rows.append(f"| {title} | {expect} | ошибок всего {errors} за {len(runs)} прогона; HAProxy вывел реплику "
f"не позже {out} с; остановленная реплика после остановки не отвечала | {recovery}; "
f"потерь и дублей 0 |")
if rolling:
rows.append(f"| Rolling update 2 реплик под нагрузкой | замена по одной без простоя | ошибок "
f"{rolling['during']['errors']}, записей/с {rolling['during']['write_rps']} | "
f"{rolling['update_seconds']} с на замену; потерь и дублей 0 |")
persistence = EVIDENCE / "persistence.txt"
if persistence.exists():
found = re.search(r"test took ([\d.]+) s", persistence.read_text(encoding="utf-8"))
if found:
rows.append(f"| Перезапуск всего стенда (`make persistence`, hook restart) | данные и действующий токен "
f"сохраняются | PASS: те же контейнеры с новым временем старта, прежний токен работает | "
f"{found.group(1)} с на весь тест (hook + готовность); потерь нет |")
# Отказы зависимостей (проверки lab2, теперь через балансировщик): строка — если тест прошёл.
for name, title, expect, seen, recovery in (
("failure-valkey.txt", "`docker compose stop valkey`", "API работает без кэша",
"ready 200; вход, сообщения и logout работают через PostgreSQL",
"кэш снова включается за 1–2 с после start; потерь нет"),
("failure-postgres.txt", "`docker compose stop postgres`",
"неготовые реплики исключены из маршрутизации, клиенту 503",
"HAProxy вывел обе реплики (ready 503, live 200); запрос с действующим токеном из кэша -> 503 "
"от балансировщика, до реплики не дошёл; запись не сохранилась",
"после start прежний токен и данные на месте; запросы во время отказа не сохранены (503)"),
("failure-valkey-pause.txt", "`docker compose pause valkey`, logout, `unpause`",
"отозванный токен не оживает ни на одной реплике", "после unpause отозванный токен всегда 401",
"поколение кэша сменилось после возвращения Valkey; отзыв не потерян")):
path = EVIDENCE / name
if path.exists() and "PASS" in path.read_text(encoding="utf-8"):
rows.append(f"| {title} | {expect} | {seen} | {recovery} |")
return rows if len(rows) > 2 else []
def main():
failover, rolling = load("failover-metrics.json"), load("rolling-update.json")
load_result, stats = load("load.json"), load("load-stats.json")
parts = []
for block in (failover and failover_table(failover), rolling and rolling_lines(rolling),
load_result and load_lines(load_result, stats), impacts(failover, rolling)):
if block:
parts += block + [""]
check(parts, "no evidence/*.json yet: run make failover-metrics, rolling-update, load-profile first")
text = REPORT.read_text(encoding="utf-8")
check(BEGIN in text and END in text, "REPORT.md has no measurements markers")
head, rest = text.split(BEGIN, 1)
_, tail = rest.split(END, 1)
REPORT.write_text(head + BEGIN + "\n" + "\n".join(parts).strip() + "\n" + END + tail, encoding="utf-8")
print("\n".join(parts).strip())
print("\nPASS: tables inserted into REPORT.md between the measurements markers")
if __name__ == "__main__":
run(main)
+108
View File
@@ -0,0 +1,108 @@
"""lab3, уровень 4: rolling update под нагрузкой — реплики по одной заменяются новой версией.
make rolling-update (= python student-tests/rolling_update.py)
1. Собирается новый образ с APP_VERSION=rolling-<время> (docker compose build api migrate).
2. Миграции новой версии применяются ОДИН раз отдельным запуском: docker compose run --rm migrate.
Миграции только добавляют (как 004: новые столбцы, которые могут быть NULL), поэтому старые
реплики продолжают работать с новой схемой, пока их не заменят.
3. Для каждой старой реплики: запустить ещё одну, новую (docker compose up --scale api=N+1
--no-recreate), дождаться healthy и UP в HAProxy, затем остановить старую (docker stop:
сначала readiness 503 и выход из балансировки) и удалить её. Реплик всё время не меньше N.
4. Всё это время идёт нагрузка (loadgen.py): ошибки, RPS, задержки; в конце — проверка,
что подтверждённые сообщения на месте и дублей нет.
Итог: таблица в консоли и evidence/rolling-update.json. После скрипта стенд работает на новой
версии. Обычный `docker compose up -d --build` потом вернёт версию dev, пересоздав реплики разом
(это уже не rolling update).
"""
import json
import os
import time
from helpers import ROOT, check, run
from loadgen import CLIENT_TIMEOUT_SECONDS, WRITERS, Load, summary
from stand import api_containers, compose_output, compose_quiet, docker, health, lb_summary, lb_up_count, wait_balanced
OUTPUT = ROOT / "evidence" / "rolling-update.json"
def version_of(container):
lines = docker("inspect", "-f", "{{range .Config.Env}}{{println .}}{{end}}", container).splitlines()
env = dict(line.split("=", 1) for line in lines if "=" in line)
return env.get("APP_VERSION")
def wait_new_replica(container, up_needed, seconds=90):
deadline = time.monotonic() + seconds
while health(container) != "healthy" or lb_up_count() < up_needed:
check(time.monotonic() < deadline, f"new replica {container[:12]} is not in the balancer after {seconds} s")
time.sleep(0.2)
def main():
old = api_containers()
replicas = len(old)
check(replicas >= 2, "need at least 2 running api replicas")
wait_balanced(replicas)
old_version = version_of(old[0])
version = time.strftime("rolling-%Y%m%d-%H%M%S")
env = dict(os.environ, APP_VERSION=version)
print(f"old replicas {[c[:12] for c in old]}, version {old_version}; building version {version}")
started = time.monotonic()
compose_quiet("build", "api", "migrate", env=env)
print(f"image built in {time.monotonic() - started:.1f} s")
migrate_log = compose_output("run", "--rm", "--no-deps", "-T", "migrate", env=env)
lines = [line for line in migrate_log.splitlines() if "Миграции" in line]
print("migrations (one run, before replacing replicas): " + (lines[-1].split("messenger.db: ")[-1] if lines else "?"))
load = Load()
load.start()
time.sleep(3)
t0 = time.monotonic()
steps = []
for container in old:
step_start = time.monotonic()
before = set(api_containers())
compose_quiet("up", "-d", "--no-deps", "--no-recreate", "--scale", f"api={len(before) + 1}", "api", env=env)
new = sorted(set(api_containers()) - before)
check(len(new) == 1, f"expected one new container, got {len(new)}")
wait_new_replica(new[0], replicas + 1)
ready = time.monotonic() - step_start
docker("stop", "--time", "15", container)
docker("rm", container)
steps.append({"old": container[:12], "new": new[0][:12], "new_ready_seconds": round(ready, 2),
"step_seconds": round(time.monotonic() - step_start, 2)})
print(f"replaced {container[:12]} -> {new[0][:12]}: new replica healthy and UP in HAProxy after "
f"{ready:.1f} s, then the old one drained and stopped; step {steps[-1]['step_seconds']} s "
f"(HAProxy: {lb_summary()})")
t1 = time.monotonic()
time.sleep(3)
load.stop()
final = api_containers()
versions = sorted({version_of(c) for c in final})
integrity = load.verify()
during = summary(load, t0, t1)
before_stats = summary(load, t0 - 3, t0)
print(f"now: replicas {[c[:12] for c in final]}, versions {versions}")
print(f"under load: write RPS before {before_stats['write_rps']}, during the update {during['write_rps']}; "
f"errors {during['errors']} {during['error_codes']}; p95 {during['write_p95_ms']} ms, "
f"max {during['write_max_ms']} ms; update took {t1 - t0:.1f} s")
print(f"confirmed {integrity['confirmed_writes']}, in history {integrity['messages_in_history']}, "
f"lost 0, duplicates 0")
check(len(final) == replicas and not set(final) & set(old), "old replicas are still running")
check(versions == [version], "not every replica runs the new version")
OUTPUT.parent.mkdir(exist_ok=True)
OUTPUT.write_text(json.dumps({
"from_version": old_version, "to_version": version, "replicas": replicas,
"profile": {"writers": WRITERS, "readers": 1, "client_timeout_seconds": CLIENT_TIMEOUT_SECONDS},
"steps": steps, "update_seconds": round(t1 - t0, 2),
"before": before_stats, "during": during, "integrity": integrity,
}, indent=2) + "\n", encoding="utf-8")
print(f"PASS: all {replicas} replicas replaced one by one under load, "
f"{during['errors']} errors, no lost or duplicated messages; saved {OUTPUT.relative_to(ROOT).as_posix()}")
if __name__ == "__main__":
run(main)
+69
View File
@@ -0,0 +1,69 @@
"""Публичный тест отказа (tests/resilience.py --mode failover) для КАЖДОЙ реплики по очереди.
make failover (= python student-tests/run_failover.py)
Публичный тест сам выбирает реплику — ту, что ответила на его первое сообщение, — и вызывает
hook scripts/stop-one.cmd (Windows) или scripts/stop-one.sh, который останавливает именно её.
Этот скрипт печатает контейнеры до и после теста (видно, какой контейнер реально остановлен
и что postgres, valkey и lb не тронуты), запускает реплику обратно (docker start), ждёт,
пока HAProxy вернёт её в балансировку, и повторяет тест, пока каждая реплика не будет
остановлена хотя бы раз (не больше 6 прогонов).
Как попасть в нужную реплику: при 2 репликах HAProxy отвечает строго по очереди, а до первого
сообщения тест делает 9 запросов. Значит, его сообщение (10-й запрос) уйдёт на ту же реплику,
что ответила на наш последний запрос. Поэтому перед прогоном один-два запроса /health/live
«сдвигают» очередь так, чтобы последней ответила ещё не проверенная реплика.
"""
import os
import subprocess
import sys
from helpers import ROOT, Client, check, run
from stand import BASE_URL, api_containers, docker, lb_summary, ps_table, wait_balanced
HOOK = ROOT / "scripts" / ("stop-one.cmd" if os.name == "nt" else "stop-one.sh")
def aim(api, wanted):
"""Для 2 реплик: последним перед тестом должна ответить реплика из wanted."""
probe = api.call("GET", "/health/live", schema="Health")["headers"]["X-Instance-Id"]
if not any(container.startswith(probe) for container in wanted):
api.call("GET", "/health/live", schema="Health") # теперь последней ответила другая реплика
def main():
api = Client()
containers = api_containers()
check(len(containers) >= 2, "need at least 2 running api replicas")
print(f"hook: {HOOK.relative_to(ROOT).as_posix()}; api replicas: {[c[:12] for c in containers]}")
stopped_once = set()
for attempt in range(1, 7):
wait_balanced(len(containers))
if len(containers) == 2:
aim(api, set(containers) - stopped_once)
print(f"\n=== run {attempt}: containers before (HAProxy: {lb_summary()})")
print(ps_table())
env = dict(os.environ, PYTHONUTF8="1", PYTHONIOENCODING="utf-8")
result = subprocess.run([sys.executable, "tests/resilience.py", "--mode", "failover",
"--action-script", str(HOOK), "--base-url", BASE_URL],
cwd=ROOT, capture_output=True, env=env)
print((result.stdout + result.stderr).decode("utf-8", "replace").strip())
check(result.returncode == 0, "public failover test failed")
print(f"containers after (HAProxy: {lb_summary()})")
print(ps_table())
stopped = [container for container in containers if container not in api_containers()]
check(len(stopped) == 1, f"expected exactly one stopped api container, got {len(stopped)}")
print(f"the hook stopped {stopped[0][:12]} (X-Instance-Id of that replica = container ID); "
f"other api containers, postgres, valkey and lb kept running")
stopped_once.add(stopped[0])
docker("start", stopped[0])
wait_balanced(len(containers))
print(f"restored: docker start {stopped[0][:12]} -> healthy and back in HAProxy ({lb_summary()})")
if stopped_once == set(containers):
break
check(stopped_once == set(containers), "not every replica was stopped by the public test")
print(f"\nPASS: public failover test passed {attempt} times; every api replica was stopped once and restored")
if __name__ == "__main__":
run(main)
+60
View File
@@ -0,0 +1,60 @@
"""Публичный тест сохранности (tests/resilience.py --mode persistence) и доказательство,
что hook scripts/restart.cmd (Windows) или scripts/restart.sh действительно перезапустил процессы.
make persistence (= python student-tests/run_persistence.py)
До и после теста печатаются все контейнеры стенда с временем старта (StartedAt). После теста
у postgres, valkey, обеих реплик api и lb должен быть ТОТ ЖЕ ID контейнера (контейнеры и volumes
те же, ничего не пересоздано) и НОВОЕ время старта (процесс перезапущен). Сам тест проверяет,
что данные и прежний токен на месте. Сервис migrate при `docker compose start api` запускается
снова как зависимость: он видит, что новых миграций нет, и сразу завершается.
"""
import os
import subprocess
import sys
import time
from helpers import ROOT, check, run
from stand import BASE_URL, compose_output, inspect, ps_table
HOOK = ROOT / "scripts" / ("restart.cmd" if os.name == "nt" else "restart.sh")
MUST_RESTART = ("api", "postgres", "valkey", "lb")
def started_at():
"""{ID контейнера: (сервис, время старта)} для работающих сервисов стенда."""
result = {}
for container in compose_output("ps", "-q").split():
service = inspect(container, '{{index .Config.Labels "com.docker.compose.service"}}')
result[container] = (service, inspect(container, "{{.State.StartedAt}}"))
return result
def main():
print(f"hook: {HOOK.relative_to(ROOT).as_posix()}")
print("=== containers before")
print(ps_table())
before = started_at()
env = dict(os.environ, PYTHONUTF8="1", PYTHONIOENCODING="utf-8")
t0 = time.monotonic()
result = subprocess.run([sys.executable, "tests/resilience.py", "--mode", "persistence",
"--action-script", str(HOOK), "--base-url", BASE_URL],
cwd=ROOT, capture_output=True, env=env)
took = time.monotonic() - t0
print((result.stdout + result.stderr).decode("utf-8", "replace").strip())
check(result.returncode == 0, "public persistence test failed")
print(f"=== containers after (test took {took:.1f} s: hook + waiting for readiness + data checks)")
print(ps_table())
after = started_at()
for container, (service, start) in sorted(before.items(), key=lambda item: item[1]):
if service not in MUST_RESTART:
continue
check(container in after, f"{service} {container[:12]} was recreated or is not running")
check(after[container][1] != start, f"{service} {container[:12]} was not restarted")
print(f"{service:<9} {container[:12]}: same container, start time {start[11:19]} -> {after[container][1][11:19]}")
print("PASS: api replicas, postgres, valkey and lb were restarted (same containers and volumes, "
"new start time); data and the existing token survived")
if __name__ == "__main__":
run(main)
+193
View File
@@ -0,0 +1,193 @@
"""Помощники lab3 для собственных проверок: реплики, балансировщик, Docker.
Только стандартная библиотека Python. Docker вызывается прямо из Python (`docker compose ...`),
поэтому всё работает одинаково в Git Bash, PowerShell и cmd на Windows.
Вывод проверок — латиницей и кириллицей в UTF-8 (в Git Bash задан PYTHONUTF8=1).
"""
import csv
import http.client
import io
import json
import os
import subprocess
import time
import urllib.error
import urllib.request
from helpers import ROOT, check
BASE_URL = os.environ.get("BASE_URL", "http://127.0.0.1:8080").rstrip("/")
LB_STATS_URL = os.environ.get("LB_STATS_URL", "http://127.0.0.1:8404/stats;csv")
class Reply:
"""Ответ без проверок: для нагрузки во время отказа, где ошибки — ожидаемая часть замера."""
def __init__(self, status, headers, data):
self.status = status
self.headers = {name.lower(): value for name, value in headers.items()}
try:
self.json = json.loads(data.decode("utf-8")) if data else None
except ValueError:
self.json = None
@property
def instance(self):
return self.headers.get("x-instance-id")
def try_call(method, path, *, body=None, raw=None, token=None, headers=None, timeout=2.0):
"""HTTP-запрос через балансировщик. Reply или None, если соединение оборвалось / вышел timeout.
Обрыв возможен и посреди ответа (реплику убили, когда заголовки уже ушли): http.client.HTTPException.
"""
all_headers = dict(headers or {})
data = raw
if body is not None:
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
if data is not None:
all_headers.setdefault("Content-Type", "application/json")
if token is not None:
all_headers["Authorization"] = "Bearer " + token
request = urllib.request.Request(BASE_URL + path, data=data, method=method, headers=all_headers)
try:
with urllib.request.urlopen(request, timeout=timeout) as reply:
return Reply(reply.status, reply.headers, reply.read())
except urllib.error.HTTPError as error:
try:
return Reply(error.code, error.headers, error.read())
except (OSError, http.client.HTTPException):
return None
except (urllib.error.URLError, OSError, http.client.HTTPException):
return None
# ---------- Docker ----------
def docker(*args, check_exit=True):
"""docker <args>; возвращает stdout."""
result = subprocess.run(["docker", *args], cwd=ROOT, capture_output=True, check=check_exit)
return result.stdout.decode("utf-8", "replace").strip()
def compose_output(*args, env=None):
"""docker compose <args> и его вывод (stdout + stderr). Секретов в нём нет: ps, logs, build."""
result = subprocess.run(["docker", "compose", *args], cwd=ROOT, capture_output=True, check=True, env=env)
return result.stdout.decode("utf-8", "replace") + result.stderr.decode("utf-8", "replace")
def compose_config():
"""Итоговая конфигурация стенда (docker compose config) как словарь: только stdout, без предупреждений."""
result = subprocess.run(["docker", "compose", "config", "--format", "json"], cwd=ROOT,
capture_output=True, check=True)
return json.loads(result.stdout.decode("utf-8"))
def compose_quiet(*args, env=None):
subprocess.run(["docker", "compose", *args], cwd=ROOT, check=True, env=env,
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
def api_containers(include_stopped=False):
"""Полные ID контейнеров сервиса api (по умолчанию только запущенные), по порядку."""
args = ["ps", "-q", "-a", "api"] if include_stopped else ["ps", "-q", "api"]
return sorted(compose_output(*args).split())
def inspect(container, template):
return docker("inspect", "-f", template, container, check_exit=False)
def health(container):
"""Статус Docker healthcheck: starting / healthy / unhealthy / ''."""
return inspect(container, "{{if .State.Health}}{{.State.Health.Status}}{{end}}")
def ps_table():
"""Все контейнеры стенда: сервис, короткий ID (= X-Instance-Id у api), состояние, время старта."""
lines = []
for container in sorted(compose_output("ps", "-a", "-q").split()):
info = inspect(container, '{{index .Config.Labels "com.docker.compose.service"}}|{{.State.Status}}|'
'{{.State.StartedAt}}|{{if .State.Health}}{{.State.Health.Status}}{{end}}')
service, status, started, healthy = (info.split("|") + ["", "", "", ""])[:4]
shown = f"{status} ({healthy})" if healthy and status == "running" else status
lines.append((service, container[:12], shown, started[:23]))
lines.sort()
width = max((len(service) for service, *_ in lines), default=7)
text = [f"{'SERVICE':<{width}} CONTAINER STATE STARTED AT (UTC)"]
text += [f"{service:<{width}} {cid} {state:<19} {started}" for service, cid, state, started in lines]
return "\n".join(text)
# ---------- балансировщик ----------
def lb_rows(backend="api"):
"""Строки статистики HAProxy (CSV) по серверам backend: имя, статус, backup-флаг, результат проверки."""
with urllib.request.urlopen(LB_STATS_URL, timeout=2) as reply:
rows = list(csv.reader(io.StringIO(reply.read().decode("utf-8", "replace"))))
header = [name.lstrip("# ") for name in rows[0]]
items = [dict(zip(header, row)) for row in rows[1:]]
return [item for item in items
if item.get("pxname") == backend and item.get("svname") not in ("FRONTEND", "BACKEND")]
def lb_servers(backend="api"):
"""Слоты backend в HAProxy: {имя: статус}, например {'api1': 'UP'}."""
return {item["svname"]: item.get("status", "") for item in lb_rows(backend)}
def lb_up_count():
"""Сколько реплик (слоты api1..api6) HAProxy держит в балансировке (UP)."""
return sum(1 for name, status in lb_servers().items() if name.startswith("api") and status.startswith("UP"))
def lb_summary():
"""Короткая строка состояния основных слотов: 'api1 UP, api2 DOWN' (пустые слоты MAINT не показываем)."""
servers = lb_servers()
shown = [f"{name} {status}" for name, status in sorted(servers.items())
if name.startswith("api") and not status.startswith("MAINT")]
return ", ".join(shown) or "no api servers"
def wait_balanced(replicas, seconds=90):
"""Ждёт, пока replicas контейнеров api healthy и HAProxy держит их в балансировке (UP)."""
deadline = time.monotonic() + seconds
while True:
running = api_containers()
healthy = [container for container in running if health(container) == "healthy"]
try:
up = lb_up_count()
except OSError:
up = 0
if len(healthy) >= replicas and up >= replicas:
return running
check(time.monotonic() < deadline,
f"after {seconds} s: {len(healthy)} healthy api containers, {up} UP in HAProxy, need {replicas}")
time.sleep(0.5)
def replica_status(container, path):
"""Код ответа реплики на GET path изнутри её контейнера, в обход балансировщика.
Так видно состояние самой реплики (жива ли, готова ли), когда балансировщик её уже исключил.
Одна строка без переводов строк: так команда одинаково передаётся и на Windows, и на Linux.
"""
code = ("import http.client as h; c = h.HTTPConnection('127.0.0.1', 8080, timeout=5); "
f"c.request('GET', '{path}'); print(c.getresponse().status)")
return int(docker("exec", container, "python", "-c", code))
def valkey_stats():
"""keyspace_hits и keyspace_misses Valkey (пользователь health без пароля: только info/ping/dbsize)."""
output = compose_output("exec", "-T", "valkey", "valkey-cli", "--user", "health", "--pass", "none",
"--no-auth-warning", "info", "stats")
stats = dict(line.strip().split(":", 1) for line in output.splitlines() if line.startswith("keyspace_"))
return int(stats["keyspace_hits"]), int(stats["keyspace_misses"])
if __name__ == "__main__":
# make restore: после `docker compose up -d --wait` дождаться, пока HAProxy вернёт в работу
# ВСЕ запущенные реплики (DNS + 2 удачные проверки готовности — ещё несколько секунд).
replicas = len(api_containers())
wait_balanced(replicas)
print(f"all {replicas} api replicas are healthy and UP in HAProxy: {lb_summary()}")
+164
View File
@@ -0,0 +1,164 @@
"""Собственные тесты API (перенесены из lab1, переведены на пароль и Bearer).
Тесты «чёрного ящика»: шлют настоящие HTTP-запросы на уже запущенный стенд
(BASE_URL, по умолчанию http://127.0.0.1:8080 из Makefile; с lab3 это балансировщик,
и запросы обслуживают разные реплики). С lab3 POST сообщения несёт Idempotency-Key.
Запуск вместе с остальными test_*.py одной командой: make student-test
"""
import unittest
import uuid
from helpers import Client, basic, idempotency, read_history
PASSWORD = "Test-password-123"
class MessengerApiTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.api = Client()
cls.alice, cls.bob, cls.eve, cls.chat = cls.api.bootstrap() # eve не состоит в чате
def messages_path(self, chat_id):
return f"/api/v1/chats/{chat_id}/messages"
def send(self, actor, chat_id, text, expected=201):
schema = "Message" if expected == 201 else None # клиент разбирает JSON успешного ответа только со схемой
return self.api.call("POST", self.messages_path(chat_id), expected, actor=actor,
body={"text": text}, headers=idempotency(), schema=schema)
def new_chat(self):
body = {"title": "Тест", "member_ids": [self.alice["id"], self.bob["id"]]}
return self.api.call("POST", "/api/v1/chats", 201, actor=self.alice, body=body, schema="Chat")["json"]
def test_malformed_json_returns_400(self):
json_header = {"Content-Type": "application/json"}
for raw in (b'{"username": "abc",', b"not json", b""):
self.api.call("POST", "/api/v1/users", 400, raw=raw, headers=json_header)
self.api.call("POST", self.messages_path(self.chat["id"]), 400,
actor=self.alice, raw=raw, headers={**json_header, **idempotency()})
def test_wrong_types_and_extra_fields_return_400(self):
self.api.call("POST", "/api/v1/users", 400,
body={"username": 123, "display_name": "x", "password": PASSWORD})
self.api.call("POST", "/api/v1/users", 400,
body={"username": "valid_name", "display_name": "x", "password": PASSWORD, "is_admin": True})
self.api.call("POST", "/api/v1/users", 400,
body={"username": "Bad Name!", "display_name": "x", "password": PASSWORD})
# Отправителя нельзя подставить: он берётся из сессии.
self.api.call("POST", self.messages_path(self.chat["id"]), 400, actor=self.alice,
body={"text": "hi", "sender_id": self.bob["id"]}, headers=idempotency())
def test_outsider_gets_404_for_foreign_chat(self):
chat_id = self.chat["id"]
self.api.call("GET", f"/api/v1/chats/{chat_id}", 404, actor=self.eve)
self.api.call("GET", self.messages_path(chat_id), 404, actor=self.eve)
self.send(self.eve, chat_id, "чужое", expected=404)
# Несуществующий чат выглядит так же, как чужой: существование не раскрывается.
self.api.call("GET", f"/api/v1/chats/{uuid.uuid4()}", 404, actor=self.eve)
def test_auth_checked_before_access_and_body(self):
# Без токена — всегда 401, даже если тело кривое или чат чужой: сначала «кто ты».
self.api.call("POST", self.messages_path(self.chat["id"]), 401, raw=b"not json",
headers={"Content-Type": "application/json", **idempotency()})
self.api.call("GET", f"/api/v1/chats/{uuid.uuid4()}", 401)
def test_empty_blank_and_too_long_messages_return_400(self):
for text in ("", " ", "\n\t "):
self.send(self.alice, self.chat["id"], text, expected=400)
self.send(self.alice, self.chat["id"], "я" * 4001, expected=400)
self.send(self.alice, self.chat["id"], "я" * 4000) # ровно на границе — можно
def test_duplicate_username_returns_409(self):
body = {"username": "dup_" + uuid.uuid4().hex[:12], "display_name": "Первый", "password": PASSWORD}
self.api.call("POST", "/api/v1/users", 201, body=body)
self.api.call("POST", "/api/v1/users", 409, body=dict(body, display_name="Второй"))
def test_unicode_roundtrip(self):
text = "Привет 👋 你好 ﷽ é"
sent = self.send(self.alice, self.chat["id"], text)["json"]
self.assertEqual(sent["text"], text)
history, _ = read_history(self.api, self.bob, self.chat["id"])
self.assertIn(text, [m["text"] for m in history])
# Длина считается в символах Unicode: 100 эмодзи можно, 101 — нет.
name = "n_" + uuid.uuid4().hex[:12]
self.api.call("POST", "/api/v1/users", 400,
body={"username": name, "display_name": "👋" * 101, "password": PASSWORD})
self.api.call("POST", "/api/v1/users", 201,
body={"username": name, "display_name": "👋" * 100, "password": PASSWORD})
def test_nul_character_is_stored(self):
# Замечание к MR: U+0000 допустим по контракту и должен сохраняться как есть, а не давать 500.
name = "nul_" + uuid.uuid4().hex[:10]
password = "Pass\u0000word-123"
user = self.api.call("POST", "/api/v1/users", 201, schema="User",
body={"username": name, "display_name": "A\u0000B", "password": password})["json"]
self.assertEqual(user["display_name"], "A\u0000B")
session = self.api.call("POST", "/api/v1/auth/sessions", 201, schema="Session",
headers={"Authorization": basic(name, password)})["json"]
self.assertEqual(session["user"]["display_name"], "A\u0000B")
chat = self.api.call("POST", "/api/v1/chats", 201, actor=self.alice, schema="Chat",
body={"title": "T\u0000itle", "member_ids": [self.alice["id"], self.bob["id"]]})["json"]
self.assertEqual(chat["title"], "T\u0000itle")
sent = self.send(self.alice, chat["id"], "hello\u0000world")["json"]
self.assertEqual(sent["text"], "hello\u0000world")
history, _ = read_history(self.api, self.bob, chat["id"])
self.assertEqual([m["text"] for m in history], ["hello\u0000world"])
got = self.api.call("GET", f"/api/v1/chats/{chat['id']}", actor=self.bob, schema="Chat")["json"]
self.assertEqual(got["title"], "T\u0000itle")
# username с U+0000 существовать не может: вход — обычный 401, а не 500.
self.api.call("POST", "/api/v1/auth/sessions", 401, headers={"Authorization": basic("ab\u0000c", password)})
def test_pagination_walks_several_pages(self):
chat = self.new_chat()
sent = [self.send(self.alice, chat["id"], f"msg {i}")["json"] for i in range(7)]
history, pages = read_history(self.api, self.bob, chat["id"], limit=3)
self.assertEqual(pages, 3) # 3 + 3 + 1
self.assertEqual([m["id"] for m in history], [m["id"] for m in sent]) # без потерь, дублей и перестановок
def test_chat_list_pagination(self):
created = [self.new_chat()["id"] for _ in range(3)]
seen, cursor = [], None
while True:
query = "?limit=2" + (f"&cursor={cursor}" if cursor else "")
page = self.api.call("GET", "/api/v1/chats" + query, actor=self.bob, schema="ChatPage")["json"]
seen += [c["id"] for c in page["items"]]
cursor = page["next_cursor"]
if cursor is None:
break
self.assertEqual(len(seen), len(set(seen)))
self.assertEqual(seen[-3:], created) # новые чаты в конце, порядок (created_at, id)
def test_bad_cursor_returns_400(self):
chat_a, chat_b = self.new_chat(), self.new_chat()
for i in range(2):
self.send(self.alice, chat_a["id"], f"a{i}")
first = self.api.call("GET", self.messages_path(chat_a["id"]) + "?limit=1",
actor=self.alice, schema="MessagePage")["json"]
foreign_cursor = first["next_cursor"]
self.api.call("GET", self.messages_path(chat_b["id"]) + "?cursor=" + foreign_cursor, 400, actor=self.alice)
self.api.call("GET", self.messages_path(chat_a["id"]) + "?cursor=garbage", 400, actor=self.alice)
# Курсор правильной формы, но с испорченным временем/UUID: 400, а не ошибка БД (500).
import base64
import json
scope = "messages:" + chat_a["id"]
for bad in ([scope, "not-a-time", str(uuid.uuid4())],
[scope, "2026-01-01T00:00:00.000000Z", "not-a-uuid"],
[scope, "2026-01-01T00:00:00", str(uuid.uuid4())], # без часового пояса
[scope, "0001-01-01T00:00:00+14:00", str(uuid.uuid4())], # в UTC это год 0
[scope, "9999-12-31T23:59:59-14:00", str(uuid.uuid4())]): # в UTC это год 10000
forged = base64.urlsafe_b64encode(json.dumps(bad).encode()).decode()
self.api.call("GET", self.messages_path(chat_a["id"]) + "?cursor=" + forged, 400, actor=self.alice)
for limit in ("0", "101", "abc"):
self.api.call("GET", self.messages_path(chat_a["id"]) + "?limit=" + limit, 400, actor=self.alice)
def test_chat_membership_rules(self):
alice, bob = self.alice["id"], self.bob["id"]
for members in ([bob], [alice, alice], [alice, str(uuid.uuid4())]): # без себя, дубль, неизвестный
self.api.call("POST", "/api/v1/chats", 400, actor=self.alice, body={"title": "x", "member_ids": members})
chats = self.api.call("GET", "/api/v1/chats?limit=100", actor=self.eve, schema="ChatPage")["json"]
self.assertNotIn(self.chat["id"], [c["id"] for c in chats["items"]])
if __name__ == "__main__":
unittest.main()
+118
View File
@@ -0,0 +1,118 @@
"""Собственные тесты аутентификации (уровень 4): пароль, Basic -> Bearer, logout.
Запуск: make student-test (вместе с test_api.py)
"""
import base64
import datetime as dt
import unittest
import uuid
from helpers import Client, basic, login
PASSWORD = "Test-password-123"
def iso(value):
return dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
class AuthTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.api = Client()
def register(self, password=PASSWORD, expected=201):
body = {"username": "a_" + uuid.uuid4().hex[:12], "display_name": "Auth", "password": password}
user = self.api.call("POST", "/api/v1/users", expected, body=body,
schema="User" if expected == 201 else None)["json"]
return body, user
def me(self, token, expected=200):
return self.api.call("GET", "/api/v1/users/me", expected, headers={"Authorization": "Bearer " + token},
schema="User" if expected == 200 else None)
def test_login_returns_opaque_token_with_expiry(self):
body, user = self.register()
session = login(self.api, body["username"], body["password"])
self.assertEqual(session["user"], user)
token = session["token"]
self.assertGreaterEqual(len(token), 43) # 32 случайных байта в base64url
self.assertNotIn(body["username"], token)
self.assertNotIn(user["id"], token)
# Обычный стенд: TTL не меньше 300 с (по умолчанию 3600).
left = iso(session["expires_at"]) - dt.datetime.now(dt.timezone.utc)
self.assertGreater(left.total_seconds(), 290)
self.assertEqual(self.me(token)["json"], user)
def test_user_never_contains_password(self):
body, user = self.register()
self.assertEqual(set(user), {"id", "username", "display_name", "created_at"})
self.assertNotIn(body["password"], str(user))
def test_wrong_password_and_unknown_user_look_the_same(self):
body, _ = self.register()
wrong = login(self.api, body["username"], "Wrong-password-000", expected=401)
unknown = login(self.api, "nobody_" + uuid.uuid4().hex[:8], body["password"], expected=401)
# Одинаковый код и текст: по ответу нельзя узнать, существует ли username.
self.assertEqual(wrong["error"]["code"], unknown["error"]["code"])
self.assertEqual(wrong["error"]["message"], unknown["error"]["message"])
def test_malformed_basic_returns_401(self):
path = "/api/v1/auth/sessions"
no_colon = base64.b64encode(b"just_username").decode()
for header in (None, "Basic", "Basic !!!not-base64!!!", "Basic " + no_colon, "Bearer something"):
headers = {} if header is None else {"Authorization": header}
self.api.call("POST", path, 401, headers=headers) # клиент проверяет WWW-Authenticate: Basic
def test_password_with_colon_and_unicode(self):
password = "пароль:с:двоеточием 👋"
body, user = self.register(password=password)
session = login(self.api, body["username"], password)
self.assertEqual(session["user"], user)
def test_password_length_rules(self):
self.register(password="x" * 11, expected=400)
self.register(password="x" * 129, expected=400)
self.register(password=" " * 12, expected=400) # только пробелы — нельзя
self.register(password="x" * 12)
self.register(password="я" * 128) # 128 символов Unicode — можно
def test_bearer_required_on_business_endpoints(self):
body, user = self.register()
session = login(self.api, body["username"], body["password"])
for headers in ({}, {"Authorization": basic(body["username"], body["password"])},
{"X-User-Id": user["id"]}, {"Authorization": "Bearer " + "A" * 43},
{"Authorization": "Bearer"}, {"Authorization": "Token " + session["token"]}):
self.api.call("GET", "/api/v1/users/me", 401, headers=headers) # WWW-Authenticate: Bearer
# Схема нечувствительна к регистру (RFC 7235).
self.api.call("GET", "/api/v1/users/me", 200, headers={"Authorization": "bearer " + session["token"]})
def test_x_user_id_does_not_change_identity(self):
body, user = self.register()
_, other = self.register()
session = login(self.api, body["username"], body["password"])
me = self.api.call("GET", "/api/v1/users/me", headers={
"Authorization": "Bearer " + session["token"], "X-User-Id": other["id"]}, schema="User")["json"]
self.assertEqual(me["id"], user["id"])
def test_logout_revokes_only_current_session(self):
body, _ = self.register()
first = login(self.api, body["username"], body["password"])["token"]
second = login(self.api, body["username"], body["password"])["token"]
self.me(first) # запись попадает в кэш Valkey
self.api.call("DELETE", "/api/v1/auth/sessions/current", 204, headers={"Authorization": "Bearer " + first})
self.me(first, expected=401) # кэш инвалидирован: отозванный токен не принимается сразу
self.api.call("DELETE", "/api/v1/auth/sessions/current", 401, headers={"Authorization": "Bearer " + first})
self.me(second) # другая сессия того же пользователя продолжает работать
def test_relogin_after_logout(self):
body, _ = self.register()
token = login(self.api, body["username"], body["password"])["token"]
self.api.call("DELETE", "/api/v1/auth/sessions/current", 204, headers={"Authorization": "Bearer " + token})
again = login(self.api, body["username"], body["password"])["token"]
self.assertNotEqual(token, again)
self.me(again)
if __name__ == "__main__":
unittest.main()
+85
View File
@@ -0,0 +1,85 @@
"""lab3: несколько реплик API за балансировщиком и общее состояние.
Запуск при запущенном стенде: make balancing (или вместе со всеми: make student-test).
Все запросы идут на BASE_URL = балансировщик HAProxy (127.0.0.1:8080).
1. Один токен обслуживают разные реплики (X-Instance-Id), повторный вход не нужен:
сессии в общем PostgreSQL + кэш в общем Valkey, а не в памяти реплики.
2. Записал через одну реплику — сразу читаешь через другую: данные в общем PostgreSQL.
3. Logout через одну реплику действует на всех.
4. X-Instance-Id есть в каждом ответе (и в ошибках, и в health) и совпадает с ID
настоящего запущенного контейнера api: заголовок — не выдумка, это разные процессы.
5. Кэш сессий общий: запись, положенную одной репликой, используют все (промахов кэша нет).
"""
import unittest
from collections import Counter
from helpers import Client, idempotency
from stand import api_containers, valkey_stats
class BalancingTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.api = Client()
cls.alice, cls.bob, cls.eve, cls.chat = cls.api.bootstrap()
def me(self, actor, expected=200):
reply = self.api.call("GET", "/api/v1/users/me", expected, actor=actor,
schema="User" if expected == 200 else None)
return reply["headers"]["X-Instance-Id"], reply["json"]
def test_one_session_is_served_by_every_replica(self):
replies = [self.me(self.alice) for _ in range(20)]
served = Counter(instance for instance, _ in replies)
self.assertTrue(all(user["id"] == self.alice["id"] for _, user in replies), "another user returned")
self.assertGreaterEqual(len(served), 2, "all requests went to one replica: balancing does not work")
running = api_containers()
for instance in served:
self.assertTrue(any(container.startswith(instance) for container in running),
f"X-Instance-Id {instance} is not a running api container")
print(f"\n 20 x GET /users/me с одним токеном -> реплики {dict(served)}; "
f"это ID запущенных контейнеров api, повторный вход не нужен")
def test_write_on_one_replica_read_on_another(self):
sent = self.api.message(self.alice, self.chat, "записано через одну реплику")
writer = sent["headers"]["X-Instance-Id"]
readers = set()
for _ in range(6):
page = self.api.call("GET", f"/api/v1/chats/{self.chat['id']}/messages?limit=100",
actor=self.bob, schema="MessagePage")
self.assertIn(sent["json"], page["json"]["items"], "confirmed message is not visible")
readers.add(page["headers"]["X-Instance-Id"])
self.assertTrue(readers - {writer}, "no read went to another replica")
print(f"\n сообщение записала реплика {writer}, сразу прочитали {sorted(readers)}")
def test_logout_applies_on_every_replica(self):
carol = self.api.user("carol")
self.api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=carol)
after = [self.me(carol, expected=401)[0] for _ in range(6)]
self.assertGreaterEqual(len(set(after)), 2, "401 came from one replica only")
print(f"\n logout через одну реплику -> 401 на {sorted(set(after))}")
def test_instance_id_on_errors_and_health(self):
# Клиент курса сам проверяет X-Request-Id и X-Instance-Id у каждого ответа.
self.api.call("GET", "/health/live", schema="Health")
self.api.call("GET", "/health/ready", schema="Health")
self.api.call("GET", "/api/v1/no-such-path", 404, actor=self.alice)
self.api.call("GET", "/api/v1/users/me", 401)
self.api.call("POST", f"/api/v1/chats/{self.chat['id']}/messages", 400, actor=self.alice,
body={"text": ""}, headers=idempotency())
print("\n X-Instance-Id есть в health, 404, 401 и 400")
def test_session_cache_is_shared_between_replicas(self):
dave = self.api.user("dave") # вход уже положил запись о сессии в общий Valkey
hits_before, misses_before = valkey_stats()
served = Counter(self.me(dave)[0] for _ in range(10))
hits_after, misses_after = valkey_stats()
self.assertGreaterEqual(len(served), 2, "requests did not reach both replicas")
self.assertEqual(misses_after - misses_before, 0, "cache miss: a replica did not use the shared entry")
print(f"\n 10 x GET /users/me через реплики {dict(served)}: попаданий в кэш "
f"+{hits_after - hits_before}, промахов +{misses_after - misses_before} — кэш общий")
if __name__ == "__main__":
unittest.main()
+159
View File
@@ -0,0 +1,159 @@
"""lab3: Idempotency-Key у POST /chats/{id}/messages.
Запуск при запущенном стенде: make idempotency (или вместе со всеми: make student-test).
Все запросы идут через балансировщик, поэтому повторы попадают на разные реплики.
- повтор того же запроса (в том числе через другую реплику) -> тот же 201 и то же сообщение;
- 20 одновременных запросов с одним ключом через обе реплики -> ровно одно сообщение;
- одновременные разные тела с одним ключом -> одно сообщение, остальным 409;
- форматирование JSON не важно; другое тело с тем же ключом -> 409;
- область ключа: пользователь + чат (тот же ключ у другого пользователя или в другом чате независим);
- нет ключа или он неверный -> 400; ошибка 400 ключ не «занимает»;
- повтор заново проверяет сессию (401 после logout) и доступ к чату (404 постороннему).
"""
import threading
import unittest
import uuid
from collections import Counter
from concurrent.futures import ThreadPoolExecutor
from helpers import Client, idempotency, login, read_history
PARALLEL = 20
class IdempotencyTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.api = Client()
cls.alice, cls.bob, cls.eve, cls.chat = cls.api.bootstrap()
def path(self, chat=None):
return f"/api/v1/chats/{(chat or self.chat)['id']}/messages"
def post(self, actor, text, key, expected=201, chat=None, api=None):
return (api or self.api).call("POST", self.path(chat), expected, actor=actor, body={"text": text},
headers=idempotency(key), schema="Message" if expected == 201 else None)
def count_text(self, text, chat=None):
history, _ = read_history(self.api, self.alice, (chat or self.chat)["id"])
return sum(1 for message in history if message["text"] == text)
def test_replay_through_another_replica_returns_same_message(self):
key, text = uuid.uuid4().hex, "повтор " + uuid.uuid4().hex
first = self.post(self.alice, text, key)
replies = [self.post(self.alice, text, key) for _ in range(4)]
self.assertTrue(all(reply["json"] == first["json"] for reply in replies), "replay differs")
instances = {first["headers"]["X-Instance-Id"]} | {r["headers"]["X-Instance-Id"] for r in replies}
self.assertGreaterEqual(len(instances), 2, "replays did not switch replica")
self.assertEqual(self.count_text(text), 1)
print(f"\n 1 запрос + 4 повтора через реплики {sorted(instances)}: 201 и то же сообщение, в истории 1")
def test_parallel_same_key_through_replicas_creates_one_message(self):
key, text = uuid.uuid4().hex, "параллельно " + uuid.uuid4().hex
start = threading.Barrier(PARALLEL)
def send(_):
client = Client() # у каждого «клиента» свои соединения
start.wait()
return self.post(self.alice, text, key, api=client)
with ThreadPoolExecutor(max_workers=PARALLEL) as pool:
replies = list(pool.map(send, range(PARALLEL)))
ids = {reply["json"]["id"] for reply in replies}
instances = Counter(reply["headers"]["X-Instance-Id"] for reply in replies)
self.assertEqual(len(ids), 1, "different messages for one key")
self.assertGreaterEqual(len(instances), 2, "parallel requests did not reach both replicas")
self.assertEqual(self.count_text(text), 1, "duplicate message created")
print(f"\n {PARALLEL} одновременных POST с одним ключом через реплики {dict(instances)}: "
f"все 201 с одним id, в истории 1 сообщение")
def test_parallel_different_bodies_same_key(self):
key = uuid.uuid4().hex
texts = [f"тело {n} {key}" for n in range(10)]
start = threading.Barrier(len(texts))
def send(text):
client = Client()
start.wait()
reply = client.call("POST", self.path(), [201, 409], actor=self.alice, body={"text": text},
headers=idempotency(key))
return text, reply["status"], reply["json"]
with ThreadPoolExecutor(max_workers=len(texts)) as pool:
results = list(pool.map(send, texts))
created = [text for text, status, _ in results if status == 201]
self.assertEqual(len(created), 1, f"expected exactly one 201, got {len(created)}")
self.assertEqual(sum(1 for _, status, _ in results if status == 409), len(texts) - 1)
self.assertEqual(sum(self.count_text(text) for text in texts), 1)
print(f"\n {len(texts)} одновременных разных тел с одним ключом: 201 x1, 409 x{len(texts) - 1}, "
f"в истории 1 сообщение")
def test_json_formatting_does_not_matter(self):
key, text = uuid.uuid4().hex, "формат " + uuid.uuid4().hex
first = self.post(self.alice, text, key)["json"]
for raw in (('{ "text" : "%s" }' % text).encode("utf-8"), ('{\n "text": "%s"\n}' % text).encode("utf-8")):
again = self.api.call("POST", self.path(), 201, actor=self.alice, raw=raw, schema="Message",
headers={"Content-Type": "application/json", **idempotency(key)})["json"]
self.assertEqual(again, first)
print("\n тот же JSON с другими пробелами и переносами -> тот же 201 и то же сообщение")
def test_same_key_other_body_is_409(self):
key, text = uuid.uuid4().hex, "оригинал " + uuid.uuid4().hex
self.post(self.alice, text, key)
error = self.post(self.alice, text + " (изменено)", key, expected=409)["json"]["error"]
self.assertEqual(error["code"], "conflict")
self.assertEqual(self.count_text(text), 1)
self.assertEqual(self.count_text(text + " (изменено)"), 0)
print("\n другой текст с тем же ключом -> 409 conflict, второе сообщение не создано")
def test_key_scope_is_user_and_chat(self):
key, text = uuid.uuid4().hex, "область " + uuid.uuid4().hex
other_chat = self.api.call("POST", "/api/v1/chats", 201, actor=self.alice, schema="Chat",
body={"title": "второй чат", "member_ids": [self.alice["id"], self.bob["id"]]})["json"]
by_alice = self.post(self.alice, text, key)["json"]
by_bob = self.post(self.bob, text, key)["json"]
in_other_chat = self.post(self.alice, text, key, chat=other_chat)["json"]
self.assertEqual(len({by_alice["id"], by_bob["id"], in_other_chat["id"]}), 3)
print("\n тот же ключ у другого пользователя и в другом чате -> независимые сообщения")
def test_key_is_required_and_validated(self):
text = "без ключа " + uuid.uuid4().hex
self.api.call("POST", self.path(), 400, actor=self.alice, body={"text": text})
for bad in ("", "a" * 129, "пробел есть", "a b", "slash/no", "ключ"):
# Не-ASCII отправляем как есть, байтами UTF-8 (так их пришлёт реальный клиент).
header = bad.encode("utf-8").decode("latin-1")
self.api.call("POST", self.path(), 400, actor=self.alice, body={"text": text},
headers={"Idempotency-Key": header})
self.post(self.alice, text + " 128", "k" * 128)
self.post(self.alice, text + " punct", "Az09._:-" + uuid.uuid4().hex)
self.assertEqual(self.count_text(text), 0)
print("\n нет ключа, пустой, 129 символов, пробел, '/', кириллица -> 400; 128 символов и ._:- -> 201")
def test_failed_request_does_not_burn_key(self):
key, text = uuid.uuid4().hex, "после ошибки " + uuid.uuid4().hex
self.post(self.alice, " ", key, expected=400) # пустой текст: 400, ничего не сохранено
created = self.post(self.alice, text, key)["json"]
self.assertEqual(created["text"], text)
print("\n с тем же ключом: сначала 400 (пустой текст), потом 201 — ошибка ключ не заняла")
def test_replay_rechecks_session_and_access(self):
key, text = uuid.uuid4().hex, "проверка доступа " + uuid.uuid4().hex
frank = self.api.user("frank")
chat = self.api.call("POST", "/api/v1/chats", 201, actor=frank, schema="Chat",
body={"title": "frank", "member_ids": [frank["id"], self.bob["id"]]})["json"]
first = self.post(frank, text, key, chat=chat)["json"]
self.post(self.eve, text, key, expected=404, chat=chat) # посторонний: 404, а не сохранённый ответ
token = frank["token"]
self.api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=frank)
self.post(frank, text, key, expected=401, chat=chat) # отозванный токен: 401
session = login(self.api, frank["registration"]["username"], frank["registration"]["password"])
frank_again = dict(frank, token=session["token"]) # новый вход, новый токен
self.assertNotEqual(frank_again["token"], token)
again = self.post(frank_again, text, key, chat=chat)["json"]
self.assertEqual(again, first)
print("\n повтор: посторонний -> 404, после logout -> 401, после нового входа -> то же сообщение")
if __name__ == "__main__":
unittest.main()