From 2c4f0a5a6156e3729a15ffedf078b66d390401b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A7=D0=B8=D0=BD=D1=8F=D0=B5=D0=B2=D0=B0?= Date: Sat, 7 Nov 2026 00:57:10 +0300 Subject: [PATCH 1/3] =?UTF-8?q?=D0=A0=D0=B5=D0=B0=D0=BB=D0=B8=D0=B7=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=D1=82=D1=8C=20=D0=BB=D0=B0=D0=B1=D0=BE=D1=80=D0=B0?= =?UTF-8?q?=D1=82=D0=BE=D1=80=D0=BD=D1=83=D1=8E=203=20=D0=BD=D0=B0=20?= =?UTF-8?q?=D0=BE=D1=86=D0=B5=D0=BD=D0=BA=D1=83=205=20(=D1=82=D1=80=D0=B5?= =?UTF-8?q?=D0=BA=201)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 43 +- .gitattributes | 6 + .github/pull_request_template.md | 32 +- Dockerfile | 32 + Makefile | 43 +- REPORT.md | 269 +++++++- app/__init__.py | 1 + app/config.py | 80 +++ app/db.py | 158 +++++ app/errors.py | 36 ++ app/main.py | 578 ++++++++++++++++++ app/migrate.py | 33 + app/sessions.py | 101 +++ app/validation.py | 152 +++++ compose.yaml | 148 +++++ evidence/README.md | 35 +- evidence/auth_negative.txt | Bin 0 -> 142 bytes evidence/check.txt | Bin 0 -> 180 bytes evidence/compose_config.txt | 190 ++++++ evidence/container_limits_ports.txt | Bin 0 -> 1726 bytes evidence/containers-after-restart.txt | Bin 0 -> 1818 bytes evidence/containers-before-restart.txt | Bin 0 -> 1710 bytes evidence/containers.txt | Bin 0 -> 2010 bytes evidence/expiry.txt | Bin 0 -> 132 bytes evidence/explain_history.txt | Bin 0 -> 1896 bytes evidence/explain_history_full.txt | 15 + evidence/failover.txt | Bin 0 -> 598 bytes evidence/failover_matrix.json | 117 ++++ evidence/failover_matrix.txt | Bin 0 -> 2222 bytes evidence/fault_matrix.txt | Bin 0 -> 710 bytes evidence/idempotency.txt | Bin 0 -> 342 bytes evidence/idempotency_persistence.txt | Bin 0 -> 1666 bytes evidence/migrate_logs.txt | Bin 0 -> 1640 bytes evidence/migrate_service.txt | Bin 0 -> 516 bytes evidence/persistence.txt | Bin 0 -> 380 bytes evidence/pool_settings.txt | Bin 0 -> 398 bytes evidence/race_username.txt | Bin 0 -> 154 bytes evidence/rollback_chat.txt | Bin 0 -> 166 bytes evidence/rolling_update.json | 90 +++ evidence/rolling_update.txt | Bin 0 -> 1324 bytes evidence/routing.txt | Bin 0 -> 260 bytes evidence/schema.txt | Bin 0 -> 8528 bytes evidence/schema_queries.sql | 15 + evidence/smoke.txt | Bin 0 -> 174 bytes evidence/track1/bench_1x2.0cpu_1g_r1.json | 20 + evidence/track1/bench_1x2.0cpu_1g_r2.json | 20 + evidence/track1/bench_2x1.0cpu_512m_r1.json | 21 + evidence/track1/bench_2x1.0cpu_512m_r2.json | 21 + evidence/track1/bench_4x0.5cpu_256m_r1.json | 23 + evidence/track1/bench_4x0.5cpu_256m_r2.json | 23 + evidence/track1/bench_4x1.0cpu_512m_r1.json | 23 + evidence/track1/bench_4x1.0cpu_512m_r2.json | 23 + evidence/track1/bench_4x2.0cpu_1g_r1.json | 23 + evidence/track1/bench_4x2.0cpu_1g_r2.json | 23 + evidence/track1/metrics_1x2.0cpu_1g_r1.json | 172 ++++++ evidence/track1/metrics_1x2.0cpu_1g_r2.json | 172 ++++++ evidence/track1/metrics_2x1.0cpu_512m_r1.json | 202 ++++++ evidence/track1/metrics_2x1.0cpu_512m_r2.json | 202 ++++++ evidence/track1/metrics_4x0.5cpu_256m_r1.json | 262 ++++++++ evidence/track1/metrics_4x0.5cpu_256m_r2.json | 262 ++++++++ evidence/track1/metrics_4x1.0cpu_512m_r1.json | 262 ++++++++ evidence/track1/metrics_4x1.0cpu_512m_r2.json | 262 ++++++++ evidence/track1/metrics_4x2.0cpu_1g_r1.json | 262 ++++++++ evidence/track1/metrics_4x2.0cpu_1g_r2.json | 262 ++++++++ evidence/track1_fixed_total.svg | 8 + evidence/track1_growth.svg | 8 + evidence/track1_report.json | 575 +++++++++++++++++ evidence/track1_report.txt | 34 ++ evidence/track1_run.txt | Bin 0 -> 1176 bytes evidence/track1_summary.json | 380 ++++++++++++ infra/nginx/nginx.conf | 57 ++ migrations/001_init.sql | 51 ++ migrations/002_lab3.sql | 29 + requirements.txt | 5 + scripts/restart.cmd | 6 + scripts/restart.sh | 6 + scripts/stop-one.cmd | 19 + scripts/stop-one.sh | 19 + student-tests/README.md | 56 ++ student-tests/auth_negative.py | 58 ++ student-tests/common.py | 76 +++ student-tests/expiry.py | 35 ++ student-tests/explain_history.py | 101 +++ student-tests/failover_matrix.py | 206 +++++++ student-tests/fault_matrix.py | 126 ++++ student-tests/idempotency_persistence.py | 88 +++ student-tests/idempotency_race.py | 124 ++++ student-tests/instance_routing.py | 37 ++ student-tests/pool_settings.py | 39 ++ student-tests/race_username.py | 45 ++ student-tests/rollback_chat.py | 86 +++ student-tests/rolling_update.py | 195 ++++++ student-tests/sample_metrics.py | 85 +++ student-tests/track1_bench.py | 168 +++++ student-tests/track1_experiment.py | 198 ++++++ student-tests/track1_report.py | 195 ++++++ 96 files changed, 7784 insertions(+), 45 deletions(-) create mode 100644 .gitattributes create mode 100644 Dockerfile create mode 100644 app/__init__.py create mode 100644 app/config.py create mode 100644 app/db.py create mode 100644 app/errors.py create mode 100644 app/main.py create mode 100644 app/migrate.py create mode 100644 app/sessions.py create mode 100644 app/validation.py create mode 100644 compose.yaml create mode 100644 evidence/auth_negative.txt create mode 100644 evidence/check.txt create mode 100644 evidence/compose_config.txt create mode 100644 evidence/container_limits_ports.txt create mode 100644 evidence/containers-after-restart.txt create mode 100644 evidence/containers-before-restart.txt create mode 100644 evidence/containers.txt create mode 100644 evidence/expiry.txt create mode 100644 evidence/explain_history.txt create mode 100644 evidence/explain_history_full.txt create mode 100644 evidence/failover.txt create mode 100644 evidence/failover_matrix.json create mode 100644 evidence/failover_matrix.txt create mode 100644 evidence/fault_matrix.txt create mode 100644 evidence/idempotency.txt create mode 100644 evidence/idempotency_persistence.txt create mode 100644 evidence/migrate_logs.txt create mode 100644 evidence/migrate_service.txt create mode 100644 evidence/persistence.txt create mode 100644 evidence/pool_settings.txt create mode 100644 evidence/race_username.txt create mode 100644 evidence/rollback_chat.txt create mode 100644 evidence/rolling_update.json create mode 100644 evidence/rolling_update.txt create mode 100644 evidence/routing.txt create mode 100644 evidence/schema.txt create mode 100644 evidence/schema_queries.sql create mode 100644 evidence/smoke.txt create mode 100644 evidence/track1/bench_1x2.0cpu_1g_r1.json create mode 100644 evidence/track1/bench_1x2.0cpu_1g_r2.json create mode 100644 evidence/track1/bench_2x1.0cpu_512m_r1.json create mode 100644 evidence/track1/bench_2x1.0cpu_512m_r2.json create mode 100644 evidence/track1/bench_4x0.5cpu_256m_r1.json create mode 100644 evidence/track1/bench_4x0.5cpu_256m_r2.json create mode 100644 evidence/track1/bench_4x1.0cpu_512m_r1.json create mode 100644 evidence/track1/bench_4x1.0cpu_512m_r2.json create mode 100644 evidence/track1/bench_4x2.0cpu_1g_r1.json create mode 100644 evidence/track1/bench_4x2.0cpu_1g_r2.json create mode 100644 evidence/track1/metrics_1x2.0cpu_1g_r1.json create mode 100644 evidence/track1/metrics_1x2.0cpu_1g_r2.json create mode 100644 evidence/track1/metrics_2x1.0cpu_512m_r1.json create mode 100644 evidence/track1/metrics_2x1.0cpu_512m_r2.json create mode 100644 evidence/track1/metrics_4x0.5cpu_256m_r1.json create mode 100644 evidence/track1/metrics_4x0.5cpu_256m_r2.json create mode 100644 evidence/track1/metrics_4x1.0cpu_512m_r1.json create mode 100644 evidence/track1/metrics_4x1.0cpu_512m_r2.json create mode 100644 evidence/track1/metrics_4x2.0cpu_1g_r1.json create mode 100644 evidence/track1/metrics_4x2.0cpu_1g_r2.json create mode 100644 evidence/track1_fixed_total.svg create mode 100644 evidence/track1_growth.svg create mode 100644 evidence/track1_report.json create mode 100644 evidence/track1_report.txt create mode 100644 evidence/track1_run.txt create mode 100644 evidence/track1_summary.json create mode 100644 infra/nginx/nginx.conf create mode 100644 migrations/001_init.sql create mode 100644 migrations/002_lab3.sql create mode 100644 requirements.txt create mode 100644 scripts/restart.cmd create mode 100755 scripts/restart.sh create mode 100644 scripts/stop-one.cmd create mode 100755 scripts/stop-one.sh create mode 100644 student-tests/README.md create mode 100644 student-tests/auth_negative.py create mode 100644 student-tests/common.py create mode 100644 student-tests/expiry.py create mode 100644 student-tests/explain_history.py create mode 100644 student-tests/failover_matrix.py create mode 100644 student-tests/fault_matrix.py create mode 100644 student-tests/idempotency_persistence.py create mode 100644 student-tests/idempotency_race.py create mode 100644 student-tests/instance_routing.py create mode 100644 student-tests/pool_settings.py create mode 100644 student-tests/race_username.py create mode 100644 student-tests/rollback_chat.py create mode 100644 student-tests/rolling_update.py create mode 100644 student-tests/sample_metrics.py create mode 100644 student-tests/track1_bench.py create mode 100644 student-tests/track1_experiment.py create mode 100644 student-tests/track1_report.py diff --git a/.env.example b/.env.example index d32b9be0..82f13a81 100644 --- a/.env.example +++ b/.env.example @@ -1,13 +1,36 @@ # Copy to .env for your LOCAL synthetic test environment; never commit .env. -# These are logical interface suggestions; map actual framework names in REPORT.md. -APP_HOST=0.0.0.0 -APP_PORT=8080 -APP_ENV=lab -SESSION_TTL_SECONDS=3600 -# Choose credentials locally. File paths contain no secret values. -DATABASE_URL_FILE=/run/secrets/database_url -# Optional on 3, required use on 4 in lab2; Redis OR Valkey: -SESSION_STORE=postgres -CACHE_URL_FILE=/run/secrets/cache_url +# Replace the placeholder password and keep the two values in sync. +POSTGRES_DB=messenger +POSTGRES_USER=messenger +POSTGRES_PASSWORD=change-me-local +DATABASE_URL=postgresql://messenger:change-me-local@postgres:5432/messenger +CACHE_URL=redis://redis:6379/0 + +# Public entry point and number of interchangeable API replicas. +API_PORT=8080 API_REPLICAS=2 +SESSION_TTL_SECONDS=3600 IDEMPOTENCY_TTL_SECONDS=86400 + +# Bounded pool per API process and dependency timeouts. +DB_POOL_MIN=1 +DB_POOL_MAX=10 +DB_POOL_ACQUIRE_TIMEOUT_SECONDS=3 +DB_CONNECT_TIMEOUT_SECONDS=3 +DB_STATEMENT_TIMEOUT_MS=5000 +REDIS_CONNECT_TIMEOUT_SECONDS=2 +REDIS_SOCKET_TIMEOUT_SECONDS=2 +MAX_BODY_BYTES=1048576 + +# Per-container limits. For the track-1 experiment keep the *total* API +# budget constant, e.g. 1x2.0/1G, 2x1.0/512M, 4x0.5/256M. +API_CPU_LIMIT=1.0 +API_MEM_LIMIT=512M +POSTGRES_CPU_LIMIT=1.0 +POSTGRES_MEM_LIMIT=512M +REDIS_CPU_LIMIT=0.5 +REDIS_MEM_LIMIT=256M +LB_CPU_LIMIT=0.5 +LB_MEM_LIMIT=128M +MIGRATE_CPU_LIMIT=0.5 +MIGRATE_MEM_LIMIT=256M diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..822563d3 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,6 @@ +* text=auto +*.sh text eol=lf +*.cmd text eol=crlf +Dockerfile text eol=lf +Makefile text eol=lf +*.sql text eol=lf diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e6e63eb2..23a24231 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,22 @@ ## Лабораторная 3 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +Автор / группа: Чиняева / БВТ2301 +Целевая оценка (3/4/5): 5 +Трек 5, если заявлен: Трек 1 «Цена масштабирования» (1/2/4 реплики при фиксированном CPU/RAM + серия роста ресурсов) -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +Что реализовано и что перенесено: перенесены PostgreSQL-схема, Argon2id, Basic→Bearer-сессии, keyset-пагинация, bounded pool и student-tests из lab2. Добавлены nginx LB, ≥2 API-реплики без локального состояния, `X-Instance-Id`, обязательный `Idempotency-Key` с общей идемпотентностью в PostgreSQL, one-shot migrate service, graceful shutdown, лимиты CPU/RAM, `scripts/restart.*`, `scripts/stop-one.*`, проверки failover/rolling update и трек 1. -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +Команды запуска из чистого clone: см. `REPORT.md`, раздел «Запуск из чистого clone». Кратко: `cp .env.example .env`, заполнить локальный пароль, `docker compose --env-file .env up -d --build`, дождаться `/health/ready`, затем `tests/smoke.py`, `tests/resilience.py --mode persistence` и `--mode failover`. + +Результаты проверок и ссылка на REPORT.md: `make check` / `scripts/check_contract.py` — PASS; smoke lab3 — PASS; persistence — PASS; failover — PASS; конкурентная идемпотентность 24 повтора — одно сообщение; rolling update — 2113 успешных, 12 ошибок (0.56%); трек 1 — 4×1.0 CPU даёт +121% RPS к 4×0.5, дальнейший рост упирается в PostgreSQL (~102–107% одного ядра). Подробности и evidence — `REPORT.md`. + +Ограничения / известные ошибки: один Docker host, PostgreSQL/Redis/LB — SPOF; трек 2 не заявлен; Redis AOF `everysec` допускает потерю до ~1 с сессионных записей при аварии хоста; трек 1 — closed-loop клиент на том же хосте, это сравнительный, а не production-capacity результат. + +Источники и использование ИИ: документация PostgreSQL, Redis, nginx, Docker Compose, gunicorn, Flask, psycopg 3, argon2-cffi; ИИ-ассистент — черновик кода, проверка контракта, подготовка отчёта; все результаты воспроизведены локально. + +- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. +- [x] Контракт и публичные тесты не ослаблены. +- [x] `make check` и `make test` выполнены (на Windows — эквивалентные `python ...`); приложен реальный вывод. +- [x] Сценарии отказов/безопасности своего уровня воспроизведены. +- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. +- [x] README задания сохранён, `REPORT.md` содержит инструкцию именно моего решения. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..6b1b6a84 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,32 @@ +# Runtime image for the lab3 API. The base tag is pinned; dependencies are +# installed from requirements.txt, never from a mutable latest tag. + +FROM python:3.12.7-slim-bookworm + +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 \ + PIP_NO_CACHE_DIR=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 + +WORKDIR /app + +RUN groupadd --system --gid 10001 app \ + && useradd --system --uid 10001 --gid app --home-dir /app --shell /usr/sbin/nologin app + +COPY requirements.txt ./ +RUN python -m pip install --requirement requirements.txt + +COPY app ./app +COPY migrations ./migrations +COPY student-tests ./student-tests + +USER app +EXPOSE 8080 + +HEALTHCHECK --interval=5s --timeout=3s --start-period=20s --retries=6 \ + CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).read()"] + +# One gunicorn worker with a bounded thread pool per API replica. SIGTERM is +# handled gracefully: in-flight requests finish before the process exits, so the +# load balancer can drain the replica during a rolling update. +CMD ["gunicorn", "--bind=0.0.0.0:8080", "--workers=1", "--threads=16", "--timeout=30", "--graceful-timeout=20", "--keep-alive=5", "--access-logfile=-", "--error-logfile=-", "app.main:app"] diff --git a/Makefile b/Makefile index 5d86d171..7b41da51 100644 --- a/Makefile +++ b/Makefile @@ -4,10 +4,22 @@ CA_FILE ?= ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) -.PHONY: help check validate test load test-persistence test-failover +.PHONY: help check validate up down test load test-persistence test-failover \ + test-student test-expiry test-idempotency test-routing \ + test-idempotency-persistence test-failover-matrix test-rolling test-track1 help: - @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" + @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt)" + @echo "up/down: local compose stack; test: public smoke against running LB" + @echo "test-persistence ACTION_SCRIPT=scripts/restart.sh" + @echo "test-failover ACTION_SCRIPT=scripts/stop-one.sh" + @echo "test-student/test-expiry/test-idempotency/test-routing: extra checks" + +up: + docker compose --env-file .env up -d --build + +down: + docker compose --env-file .env down check: $(PYTHON) scripts/check_contract.py @@ -28,3 +40,30 @@ 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) + +test-student: + $(PYTHON) student-tests/auth_negative.py --base-url "$(BASE_URL)" + $(PYTHON) student-tests/race_username.py --base-url "$(BASE_URL)" + $(PYTHON) student-tests/idempotency_race.py --base-url "$(BASE_URL)" + $(PYTHON) student-tests/instance_routing.py --base-url "$(BASE_URL)" + +test-expiry: + $(PYTHON) student-tests/expiry.py --base-url "$(BASE_URL)" + +test-idempotency: + $(PYTHON) student-tests/idempotency_race.py --base-url "$(BASE_URL)" + +test-routing: + $(PYTHON) student-tests/instance_routing.py --base-url "$(BASE_URL)" + +test-idempotency-persistence: + $(PYTHON) student-tests/idempotency_persistence.py --base-url "$(BASE_URL)" + +test-failover-matrix: + $(PYTHON) student-tests/failover_matrix.py --base-url "$(BASE_URL)" + +test-rolling: + $(PYTHON) student-tests/rolling_update.py --base-url "$(BASE_URL)" + +test-track1: + $(PYTHON) student-tests/track1_experiment.py --base-url "$(BASE_URL)" diff --git a/REPORT.md b/REPORT.md index c2679005..b6c245d3 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,272 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: **Чиняева, БВТ2301** +- Целевая оценка: **5**; выбран **трек 1 «Цена масштабирования»**. +- Commit/PR: ветка `solution/BVT2301-Chinyaeva` в форке + `aliror/mtusi2026lab3-Chinyaeva`; PR в `mtusi2026/mtusi2026lab3` — + **TODO: ссылка после публикации**. Коммит реализации — **TODO**. +- Источники, библиотеки и помощь ИИ: официальная документация PostgreSQL + (транзакции, `ON CONFLICT`, EXPLAIN), Redis (AOF/expiry), nginx + (`resolve`, `proxy_next_upstream`), Docker Compose, gunicorn, Flask, + psycopg 3, redis-py, argon2-cffi. ИИ-ассистент использовался для черновика + кода, проверки контракта и подготовки отчёта; все команды и результаты ниже + воспроизведены на локальном стенде. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Стенд проверялся на Windows 11 + Docker Desktop 29.9.2 (Compose v5.6.1, +16 logical CPU, ~15.2 GiB доступно Docker). Образы закреплены тегами: + +| Роль | Образ | Порты/volume | +| --- | --- | --- | +| LB | `nginx:1.27.5-alpine` | `${API_PORT:-8080}:8080` | +| API | `python:3.12.7-slim-bookworm`, gunicorn 23.0.0, Flask 3.1.0 | только `expose: 8080` | +| PostgreSQL | `postgres:16.4-alpine` | внутренняя сеть, `pgdata` | +| Redis | `redis:7.4.0-alpine`, AOF `everysec` | внутренняя сеть, `redisdata` | +| migrate | тот же API-образ | one-shot, без портов | + +```sh +git clone https://gitea.privcloud.tech/aliror/mtusi2026lab3-Chinyaeva.git +cd mtusi2026lab3-Chinyaeva +git checkout solution/BVT2301-Chinyaeva + +# Локальные синтетические credentials; .env в .gitignore. +cp .env.example .env +# замените POSTGRES_PASSWORD и тот же пароль внутри DATABASE_URL + +docker compose --env-file .env up -d --build +# ждать именно readiness, не только /health/live: +until curl -fsS http://localhost:8080/health/ready; do sleep 1; done + +python tests/smoke.py --base-url http://localhost:8080 +python tests/resilience.py --mode persistence \ + --action-script scripts/restart.sh --base-url http://localhost:8080 +python tests/resilience.py --mode failover \ + --action-script scripts/stop-one.sh --base-url http://localhost:8080 +``` + +На проверочной машине порт `8080` был занят lab1, а `18080` — lab2, поэтому +локально использовался `API_PORT=18081`; это единственное отличие команд. +`make` на Windows не установлен, поэтому те же цели запускались напрямую +`python ...`; Makefile содержит эквивалентные targets. Для Windows есть +`scripts/restart.cmd` и `scripts/stop-one.cmd`, для Linux/macOS — +`scripts/restart.sh` и `scripts/stop-one.sh`. + +Остановка и намеренное удаление учебных данных: + +```sh +docker compose --env-file .env down # остановка, volumes сохраняются +docker compose --env-file .env down -v # ТОЛЬКО осознанный сброс данных +rm .env # локальные credentials +``` + +Секреты не попадают в Git: `.env`, `secrets/`, `*.key`, `*.pem` перечислены в +`.gitignore`; `compose.yaml` получает `DATABASE_URL`/`CACHE_URL` из окружения. +`postgres`, `redis` и `api` не публикуют порты на хост; наружу смотрит только LB. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +client --HTTP--> nginx :8080 (public) + | + +--> api replica 1 (gunicorn, 1 worker, 16 threads) + +--> api replica 2 ... N + |-- PostgreSQL: users, chats, chat_members, messages, + | idempotency_keys (источник истины) + '-- Redis: session: -> {user_id, expires_at}, TTL +``` + +- **Перенесено из lab2:** PostgreSQL-схема и миграция `001_init`, Argon2id, + Basic только на `POST /auth/sessions`, opaque Bearer-сессии в Redis с TTL, + keyset-пагинация, bounded pool, SQL-таймауты, единый формат ошибок, + `X-Request-Id`, Dockerfile и student-tests. +- **Добавлено в lab3:** nginx как единственная публичная точка входа, + ≥2 API-реплики без локального состояния, `X-Instance-Id`, обязательный + `Idempotency-Key` для сообщений, общая идемпотентность в PostgreSQL, + one-shot миграции, graceful shutdown, лимиты CPU/RAM и failover-скрипты. +- **`X-Instance-Id`** — hostname контейнера, стабильный для жизни процесса. + `scripts/stop-one.*` сопоставляет это значение с `Config.Hostname` и + останавливает ровно один контейнер, оставляя его остановленным. +- **Сессии** — в общем Redis, поэтому вход не зависит от реплики. Redis AOF + `everysec` + `redisdata` переживают штатный рестарт; TTL не продлевается + рестартом. При полной потере Redis активные сессии станут недействительны, + но пользователи/чаты/сообщения останутся в PostgreSQL. +- **Идемпотентность.** Таблица `idempotency_keys`: + `UNIQUE (user_id, method, path, key)`, `request_hash`, `status_code`, + `response_body jsonb`, `message_id`, `expires_at` (24 ч по умолчанию). + Сообщение и запись ключа вставляются/обновляются в одной транзакции. + Конкурентный повтор ждёт `INSERT ... ON CONFLICT DO NOTHING`; после коммита + первый запрос возвращает сохранённый `201` и тот же `Message`. Другой body + при том же ключе — `409`; разные пользователи/чаты имеют независимую область. + Транзиентная ошибка откатывает и сообщение, и ключ, поэтому клиент может + безопасно повторить запрос с тем же ключом. +- **Миграции.** Отдельный сервис `migrate` выполняет `python -m app.migrate` + один раз и завершается; API ждёт `service_completed_successfully` и только + проверяет наличие всех версий в `schema_migrations`. Advisory lock защищает + от параллельного запуска. Повторный `up` не дублирует данные. +- **LB.** nginx с `resolver 127.0.0.11 valid=2s` и + `server api:8080 resolve max_fails=3 fail_timeout=2s` подхватывает + scale-up/down и замену контейнеров без reload. `proxy_connect_timeout 1s`, + `proxy_read_timeout 5s`, `proxy_next_upstream error timeout http_502 http_504`; + POST не повторяется прозрачно — повтор делает клиент с тем же + `Idempotency-Key`. Ответ прикладного `503` проходит клиенту как есть. +- **Graceful shutdown.** gunicorn `--graceful-timeout=20`, Compose + `stop_grace_period: 30s`; при SIGTERM реплика дорабатывает in-flight запросы. + Healthcheck API: interval 2 s, timeout 2 s, retries 15, start_period 15 s. + Пассивная проверка LB: 3 ошибки, `fail_timeout=2 s`; измеренное обнаружение + отказа — доли секунды, публичный failover — 1–2 с. +- **Лимиты.** API: 1.0 CPU / 512 MiB на реплику по умолчанию; PostgreSQL: + 1.0 CPU / 512 MiB; Redis: 0.5 CPU / 256 MiB; LB: 0.5 CPU / 128 MiB. + Нет `container_name`, поэтому Compose может масштабировать сервис. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +Все команды выполнялись 2026-11-06/07 на указанном стенде; файлы — в `evidence/`. -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл | +| --- | --- | --- | --- | +| Offline-структура | `python scripts/check_contract.py` | `PASS: offline skeleton structure...` | `check.txt` | +| Публичный smoke lab3 | `python tests/smoke.py --base-url ...` | `PASS: lab3 public API scenario` | `smoke.txt` | +| ≥2 реплики, одна сессия | `python student-tests/instance_routing.py` | 2 разных `X-Instance-Id`, один bearer-токен | `routing.txt` | +| Остановка любой одной реплики | `python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd` | `PASS`, first recovery 1.09–1.98 с, 0–1 ошибка | `failover.txt` | +| Поочерёдная остановка каждой реплики | `python student-tests/failover_matrix.py` | обе реплики остановлены по очереди; 1–3 ошибки на прогон; target отсутствует в ответах во время отказа и возвращается после старта | `failover_matrix.json/.txt` | +| Данные и сессия переживают рестарт | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd` | `PASS`; контейнеры до/после | `persistence.txt`, `containers-*.txt` | +| Идемпотентность, конкурентный повтор через реплики | `python student-tests/idempotency_race.py --workers 24` | 24 повтора → один `Message`; 2 реплики; 409/400 | `idempotency.txt` | +| Идемпотентность переживает рестарт | `python student-tests/idempotency_persistence.py` | тот же ключ → тот же `Message`, одна запись в истории | `idempotency_persistence.txt` | +| Схема, ключи, индексы, миграции | `psql`-запросы из `schema_queries.sql` | 6 таблиц, 12 индексов, `001_init`+`002_lab3` | `schema.txt` | +| One-shot миграции | `docker compose ps -a migrate`, `logs migrate` | `Exited (0)`, миграции применены один раз | `migrate_service.txt`, `migrate_logs.txt` | +| Пул и SQL-таймауты | `docker compose exec -T api python student-tests/pool_settings.py` | pool 1–10, statement 5 s, idle 10 s, lock 3 s | `pool_settings.txt` | +| Индекс истории и EXPLAIN на 10 000 | `docker compose exec -T api python student-tests/explain_history.py` | `Index Scan using messages_chat_created_at_id_idx`, 0.138 ms, shared hit=4 | `explain_history.txt` | +| Гонка username | `python student-tests/race_username.py --workers 8` | один `201`, семь `409` | `race_username.txt` | +| Откат составной операции | `docker compose exec -T api python student-tests/rollback_chat.py` | чат не остался после сбоя | `rollback_chat.txt` | +| Expiry при коротком TTL | `SESSION_TTL_SECONDS=2`, `python student-tests/expiry.py --wait 4` | свежая сессия 200, через 4 с — 401 + Bearer | `expiry.txt` | +| Отказ Redis/PostgreSQL | `python student-tests/fault_matrix.py` | 503 в обоих случаях; Redis recovery 0.5 с, PostgreSQL 2.52 с, тот же токен снова 200 | `fault_matrix.txt` | +| Rolling update под нагрузкой | `python student-tests/rolling_update.py` | 2113 успешных записей, 12 ошибок (0.56%), stop command 0.58–0.60 с | `rolling_update.json/.txt` | +| CPU/RAM-лимиты и порты | `docker inspect`, `docker compose config` | API без published ports; только LB `18081→8080`; лимиты заданы | `container_limits_ports.txt`, `compose_config.txt` | +| Трек 1 | `python student-tests/track1_experiment.py`, `track1_report.py` | таблицы, сырые JSON, графики | `track1_report.txt/.json`, `track1_*.svg`, `track1/*.json` | + +### Комментарии к доказательствам + +- Публичный failover-тест сам наблюдает ≥2 реплики до отказа, останавливает + именно ту, что обслужила запрос, и проверяет, что она не появляется в + последних ответах. `stop-one.*` не трогает БД, LB и volumes. +- `failover_matrix` дополнительно показывает, что во время отказа цель не + обслуживает запросы, а после `docker compose start api` снова появляется; + первые успешные записи после остановки — через 0.009–0.038 с. +- `rolling_update` использует SIGTERM (`docker stop --time 20`), а не kill: + команда остановки занимает ~0.6 с, краткие ошибки (12 из 2125) приходятся + только на моменты остановки. Это и есть проверка graceful drain. +- `persistence.txt` дополнен `containers-*.txt`: в `after` у API, PostgreSQL, + Redis и LB малое время работы, то есть hook действительно перезапустил + процессы, а не только приложение. +- `fault_matrix` сначала проверяет, что при недоступной зависимости ответ — + ограниченный `503`, а не `200`/`401` с анонимным доступом; после старта + PostgreSQL первый readiness может быть 200 раньше, чем все реплики + переподключат пул, поэтому тест отдельно ждёт восстановления того же токена + (0.27 с) — это честно измеренное окно, а не скрытая ошибка. +- В `schema.txt` и `migrate_logs.txt` нет паролей и токенов; в evidence нет + `.env`, session tokens и приватных ключей. ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Стенд: один Docker host; API + PostgreSQL + Redis + nginx в одной Compose-сети; +синтетические пользователи и сообщения. Это не production-HA. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +| Воздействие | Что ожидали | Что наблюдали | Восстановление/потери | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `docker stop` одной API-реплики | вторая продолжает читать/писать | 1–3 ошибки на 16-секундное окно; target исчезает из ответов; запись продолжается | первые записи через 0.009–0.038 с; данные не потеряны | +| Поочерёдная замена (SIGTERM + start) | краткие ошибки, затем оба backends | 2113 успешных, 12 ошибок (0.56%); stop command ~0.6 с | обе реплики возвращаются, сессия и сообщения живы | +| `docker compose restart` (API+PostgreSQL+Redis+LB), volumes сохранены | данные и прежний токен живы | `PASS` persistence | данные не потеряны; TTL не продлён | +| Остановка Redis | readiness/запросы с Bearer — 503 | 503 `unavailable`; после старта readiness 0.5 с, тот же токен 200 за 0.01 с | AOF сохранил сессию | +| Остановка PostgreSQL | readiness/запросы — 503 | 503 `unavailable`; после старта readiness 2.52 с, тот же токен 200 за 0.27 с | пользователи/сообщения сохранены | +| 24 одновременных повтора одного `Idempotency-Key` через LB | ровно одно сообщение | один `Message`, 2 реплики, история содержит одну копию | дублей нет | +| Тот же ключ с другим body | 409 | `409 conflict` | — | +| Тот же ключ после полного рестарта | тот же `Message` | тот же `id`, одна запись | состояние в PostgreSQL | +| 8 одновременных регистраций username | один пользователь | один `201`, семь `409` | дубликатов нет | +| Инъекция ошибки во вставку `chat_members` | чат не остаётся | откат транзакции | целостность сохранена | + +### Трек 1. Цена масштабирования + +**Гипотеза.** При фиксированном суммарном бюджете CPU/RAM добавление +API-реплик не увеличивает пропускную способность после того, как суммарный +CPU уже насыщен; при росте ресурсов кривая упирается в общий PostgreSQL, +а не в число реплик. + +**Методика.** `student-tests/track1_bench.py`: closed-loop POST сообщений через +LB, 24 конкурирующих клиента, 2 с прогрев, 20 с измерение, 2 повтора на +профиль; каждый запрос — уникальный `Idempotency-Key`. Клиент — на том же +хосте, поэтому это сравнительный, а не открытый load-generator. PostgreSQL +зафиксирован на 1.0 CPU/512 MiB, Redis — 0.5 CPU/256 MiB, LB — 0.5 CPU/128 MiB. +Метрики CPU/RAM и `pg_stat_activity` снимались `student-tests/sample_metrics.py`. + +**Фиксированный суммарный бюджет API (2 CPU / 1 GiB):** + +| Профиль | RPS median (min..max) | p95, ms | Ошибки | +| --- | --- | --- | --- | +| 1 × 2.0 CPU / 1G | 100.2 (98.5..101.9) | 308.6 | 0 | +| 2 × 1.0 CPU / 512M | 99.0 (95.2..103.0) | 655.2 | 0 | +| 4 × 0.5 CPU / 256M | 88.6 (85.6..91.6) | 1199.7 | 0 | + +**Рост ресурсов при 4 репликах:** + +| Профиль | RPS median (min..max) | p95, ms | Ошибки | +| --- | --- | --- | --- | +| 4 × 0.5 CPU / 256M | 90.7 (89.7..91.7) | 1205.1 | 0 | +| 4 × 1.0 CPU / 512M | 200.7 (199.0..202.4) | 422.8 | 0 | +| 4 × 2.0 CPU / 1G | 279.1 (277.9..280.3) | 214.8 | 0 | + +**Ресурсы (максимум по сэмплам):** + +| Профиль | API CPU, % | PostgreSQL CPU, % | LB CPU, % | PG connections | +| --- | --- | --- | --- | --- | +| 1 × 2.0 / 1G | 189 | 33 | 4.5 | 11 | +| 2 × 1.0 / 512M | 203 | 40 | 5.0 | 21 | +| 4 × 0.5 / 256M | 146 | 31 | 5.0 | 36 | +| 4 × 1.0 / 512M | 337 | 102 | 10.6 | 41 | +| 4 × 2.0 / 1G | 527 | 107 | 16.2 | 41 | + +Docker CPU % считает один core за 100%; 527% ≈ 5.27 ядра. + +**Выводы.** + +1. При фиксированных 2 CPU разбиение на 2 или 4 реплики не даёт прироста + (100 → 99 → 89 RPS), а p95 ухудшается (309 → 655 → 1200 мс): суммарный + CPU уже является ограничением, а несколько процессов добавляют + планирование, соединения и конкуренцию за общий PostgreSQL. +2. В серии роста 4 × 0.5 → 4 × 1.0 даёт подтверждённое улучшение: + **+121% RPS** (90.7 → 200.7) и **−65% p95** (1205 → 423 мс). + Это одно подтверждённое улучшение трека. +3. Дальнейшее 4 × 1.0 → 4 × 2.0 добавляет только **+39% RPS** при удвоении + CPU: PostgreSQL уже на ~102% одного ядра, а на 4 × 2.0 остаётся ~107%. + API CPU при этом растёт до 527%, то есть дополнительные ядра API простаивают + в ожидании общей БД/транзакции идемпотентности. Saturation point — + примерно **200–280 RPS** при PostgreSQL 1 CPU и данной схеме записи. +4. Ограничения: closed-loop клиент на том же хосте (coordinated omission, + клиентский CPU), один PostgreSQL без реплик, один чат/пользователь, + синтетические сообщения, Docker Desktop. Это локальный сравнительный + эксперимент, не сертификат production-capacity. Для следующего шага нужны + pgBouncer/реплики чтения, open-loop generator и отдельный клиентский хост. + +Графики: `evidence/track1_fixed_total.svg`, `evidence/track1_growth.svg`. +Сырые данные: `evidence/track1_summary.json`, `evidence/track1/bench_*.json`, +`evidence/track1/metrics_*.json`. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Один Docker host: PostgreSQL, Redis и LB остаются SPOF; отказ узла и + репликация БД не заявлены (трек 2 не выбран). При потере единственного + PostgreSQL или Redis приложение возвращает ограниченный `503`, но не + продолжает работу. +- Redis хранит только сессии; при полной потере AOF пользователи, чаты и + сообщения сохранятся, но активные сессии станут недействительны. AOF + `everysec` допускает потерю до ~1 секунды последних сессионных записей при + аварийном завершении хоста. +- Идемпотентность гарантируется в пределах 24 ч и области + `пользователь + метод + путь + ключ`. Просроченные строки удаляются + оппортунистически при обращении; фоновый purge не входит в минимум. +- HTTP без TLS допустим только для локального изолированного стенда с + синтетическими данными; для удалённой демонстрации нужен TLS (lab7). +- Нет rate limiting, WebSocket, UI, фоновой обработки вложений — это + следующие лабораторные, не обязательный минимум lab3. +- Трек 1 измеряет локальную saturation point, а не максимальную пропускную + способность PostgreSQL; закрытый генератор и общий хост ограничивают вывод. diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 00000000..edec7955 --- /dev/null +++ b/app/__init__.py @@ -0,0 +1 @@ +# Messenger API for MTUSI high-load course, laboratory 2. diff --git a/app/config.py b/app/config.py new file mode 100644 index 00000000..9be8d5cd --- /dev/null +++ b/app/config.py @@ -0,0 +1,80 @@ +"""Runtime configuration. + +The application never embeds credentials. Local Compose passes environment +variables from an ignored .env file; *_FILE variants are accepted as well so a +container platform can mount secrets without copying them into the image. +""" +from __future__ import annotations + +import os +import socket +from dataclasses import dataclass +from pathlib import Path + + +def _value(name: str, fallback_name: str | None = None, default: str | None = None) -> str: + raw = os.environ.get(name) + if raw: + return raw + if fallback_name: + filename = os.environ.get(fallback_name) + if filename: + path = Path(filename) + text = path.read_text(encoding="utf-8").strip() + if text: + return text + if default is not None: + return default + raise RuntimeError(f"missing required configuration: {name}") + + +def _positive_int(name: str, default: int) -> int: + raw = os.environ.get(name, str(default)) + try: + value = int(raw) + except ValueError as exc: + raise RuntimeError(f"{name} must be an integer") from exc + if value < 1: + raise RuntimeError(f"{name} must be positive") + return value + + +@dataclass(frozen=True) +class Settings: + database_url: str + cache_url: str + session_ttl_seconds: int + idempotency_ttl_seconds: int + db_pool_min: int + db_pool_max: int + db_pool_acquire_timeout: float + db_connect_timeout: int + db_statement_timeout_ms: int + redis_connect_timeout: float + redis_socket_timeout: float + max_body_bytes: int + instance_id: str + + +def load_settings() -> Settings: + # The container hostname is stable for the life of the process and unique + # per API replica. Lab7 replaces this with a random public alias. + instance_id = os.environ.get("INSTANCE_ID") or socket.gethostname() + return Settings( + database_url=_value("DATABASE_URL", "DATABASE_URL_FILE"), + cache_url=_value("CACHE_URL", "CACHE_URL_FILE"), + session_ttl_seconds=_positive_int("SESSION_TTL_SECONDS", 3600), + idempotency_ttl_seconds=_positive_int("IDEMPOTENCY_TTL_SECONDS", 86400), + db_pool_min=_positive_int("DB_POOL_MIN", 1), + db_pool_max=_positive_int("DB_POOL_MAX", 10), + db_pool_acquire_timeout=float(os.environ.get("DB_POOL_ACQUIRE_TIMEOUT_SECONDS", "3")), + db_connect_timeout=_positive_int("DB_CONNECT_TIMEOUT_SECONDS", 3), + db_statement_timeout_ms=_positive_int("DB_STATEMENT_TIMEOUT_MS", 5000), + redis_connect_timeout=float(os.environ.get("REDIS_CONNECT_TIMEOUT_SECONDS", "2")), + redis_socket_timeout=float(os.environ.get("REDIS_SOCKET_TIMEOUT_SECONDS", "2")), + max_body_bytes=_positive_int("MAX_BODY_BYTES", 1024 * 1024), + instance_id=instance_id, + ) + + +settings = load_settings() diff --git a/app/db.py b/app/db.py new file mode 100644 index 00000000..9c67be05 --- /dev/null +++ b/app/db.py @@ -0,0 +1,158 @@ +"""PostgreSQL access: bounded pool, timeouts, and versioned migrations. + +The API does not race migrations on every replica. Compose runs the one-shot +``migrate`` service first; API processes only verify that the expected schema is +present. ``python -m app.migrate`` is also the local/manual entry point. +""" +from __future__ import annotations + +import logging +import threading +import time +from pathlib import Path + +import psycopg +from psycopg.rows import dict_row +from psycopg_pool import ConnectionPool + +from .config import settings + +log = logging.getLogger("messenger.db") +MIGRATIONS_DIR = Path(__file__).resolve().parents[1] / "migrations" +LOCK_ID = 0x4D545553 # stable application-wide advisory lock + +_pool: ConnectionPool | None = None +_pool_lock = threading.Lock() +_migrated = threading.Event() +_started = False +_start_lock = threading.Lock() + + +def _create_pool() -> ConnectionPool: + options = ( + f"-c statement_timeout={settings.db_statement_timeout_ms} " + "-c idle_in_transaction_session_timeout=10000 " + "-c lock_timeout=3000" + ) + return ConnectionPool( + conninfo=settings.database_url, + min_size=settings.db_pool_min, + max_size=settings.db_pool_max, + timeout=settings.db_pool_acquire_timeout, + open=False, + kwargs={ + "row_factory": dict_row, + "connect_timeout": settings.db_connect_timeout, + "application_name": "mtusi-messenger-lab3", + "options": options, + }, + ) + + +def pool() -> ConnectionPool: + global _pool + with _pool_lock: + if _pool is None: + _pool = _create_pool() + return _pool + + +def _migration_files() -> list[Path]: + return sorted(MIGRATIONS_DIR.glob("*.sql")) + + +def apply_migrations() -> None: + """Apply every migration exactly once. + + A session-level advisory lock serialises concurrent migration runners. + Each migration and its schema_migrations row share one transaction. + """ + with pool().connection() as conn: + conn.execute("SELECT pg_advisory_lock(%s)", (LOCK_ID,)) + try: + conn.execute( + """ + CREATE TABLE IF NOT EXISTS schema_migrations ( + version text PRIMARY KEY, + applied_at timestamptz NOT NULL DEFAULT clock_timestamp() + ) + """ + ) + applied = { + row["version"] + for row in conn.execute("SELECT version FROM schema_migrations").fetchall() + } + for path in _migration_files(): + version = path.stem + if version in applied: + continue + log.info("applying migration %s", version) + conn.execute(path.read_text(encoding="utf-8")) + conn.execute( + "INSERT INTO schema_migrations(version) VALUES (%s)", (version,) + ) + finally: + conn.execute("SELECT pg_advisory_unlock(%s)", (LOCK_ID,)) + + +def schema_is_current() -> bool: + """True when every migration shipped in this image is already applied.""" + expected = {path.stem for path in _migration_files()} + if not expected: + return False + try: + with pool().connection(timeout=1.0) as conn: + row = conn.execute( + "SELECT to_regclass('public.schema_migrations') IS NOT NULL AS present" + ).fetchone() + if not row or not row["present"]: + return False + applied = { + item["version"] + for item in conn.execute("SELECT version FROM schema_migrations").fetchall() + } + return expected.issubset(applied) + except Exception: + return False + + +def start_background_initialisation() -> None: + """Open the pool and verify schema without making /health/live depend on DB.""" + global _started + with _start_lock: + if _started: + return + _started = True + + def run() -> None: + backoff = 0.5 + opened = False + while True: + try: + if not opened: + pool().open(wait=True, timeout=5) + opened = True + if not schema_is_current(): + log.warning("database schema is not current; waiting for migrate service") + raise RuntimeError("schema is not current") + _migrated.set() + log.info("database pool is ready and schema is current") + return + except Exception as exc: # startup is retried; request path stays bounded + log.warning("database initialisation is not ready: %s", type(exc).__name__) + time.sleep(backoff) + backoff = min(backoff * 2, 5.0) + + threading.Thread(target=run, name="db-init", daemon=True).start() + + +def is_migrated() -> bool: + return _migrated.is_set() + + +def close_pool() -> None: + global _pool + with _pool_lock: + if _pool is not None: + _pool.close() + _pool = None diff --git a/app/errors.py b/app/errors.py new file mode 100644 index 00000000..cce3352f --- /dev/null +++ b/app/errors.py @@ -0,0 +1,36 @@ +"""Typed public errors. Internal details never cross the HTTP boundary.""" +from __future__ import annotations + + +class ApiError(Exception): + def __init__(self, status: int, code: str, message: str, headers: dict[str, str] | None = None): + super().__init__(message) + self.status = status + self.code = code + self.message = message + self.headers = headers or {} + + +def bad_request(message: str = "Некорректный запрос") -> ApiError: + return ApiError(400, "invalid_request", message) + + +def unauthorized(*, basic: bool = False) -> ApiError: + challenge = ( + 'Basic realm="messenger", charset="UTF-8"' + if basic + else 'Bearer realm="messenger"' + ) + return ApiError(401, "unauthorized", "Требуется аутентификация", {"WWW-Authenticate": challenge}) + + +def not_found(message: str = "Объект не найден") -> ApiError: + return ApiError(404, "not_found", message) + + +def conflict(message: str = "Конфликт") -> ApiError: + return ApiError(409, "conflict", message) + + +def unavailable(message: str = "Сервис временно недоступен") -> ApiError: + return ApiError(503, "unavailable", message) diff --git a/app/main.py b/app/main.py new file mode 100644 index 00000000..7840b0b3 --- /dev/null +++ b/app/main.py @@ -0,0 +1,578 @@ +"""HTTP API for laboratory 3 (balanced replicas + shared idempotency).""" +from __future__ import annotations + +import hashlib +import json +import logging +import time +import uuid +from datetime import datetime, timedelta, timezone + +import psycopg +import psycopg_pool +import redis +from argon2 import PasswordHasher +from argon2.exceptions import InvalidHashError, VerifyMismatchError +from flask import Flask, Response, g, request +from psycopg.types.json import Jsonb + +from . import db, sessions +from .config import settings +from .errors import ApiError, bad_request, conflict, not_found, unauthorized, unavailable +from .validation import ( + cursor_time, + decode_cursor, + display_name, + encode_cursor, + exact_keys, + idempotency_key, + json_object, + limit_arg, + message_text, + non_blank, + password, + username, + uuid_list, + uuid_value, +) + +logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s") +log = logging.getLogger("messenger.api") + +app = Flask(__name__) +app.config["MAX_CONTENT_LENGTH"] = settings.max_body_bytes +hasher = PasswordHasher() + + +# --------------------------------------------------------------------------- +# Response helpers and middleware +# --------------------------------------------------------------------------- + +def _json(payload: object, status: int = 200, headers: dict[str, str] | None = None) -> Response: + body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + response = Response(body, status=status, mimetype="application/json") + for key, value in (headers or {}).items(): + response.headers[key] = value + return response + + +def _error_response(error: ApiError, request_id: str) -> Response: + return _json( + { + "error": { + "code": error.code, + "message": error.message, + "request_id": request_id, + } + }, + error.status, + error.headers, + ) + + +@app.before_request +def _request_context() -> None: + g.request_id = uuid.uuid4().hex + g.started_at = time.monotonic() + db.start_background_initialisation() + + +@app.after_request +def _response_headers(response: Response) -> Response: + response.headers["X-Request-Id"] = g.get("request_id", uuid.uuid4().hex) + response.headers["X-Instance-Id"] = settings.instance_id + response.headers["Cache-Control"] = "no-store" + return response + + +@app.errorhandler(ApiError) +def _handle_api_error(error: ApiError) -> Response: + return _error_response(error, g.get("request_id", uuid.uuid4().hex)) + + +@app.errorhandler(413) +def _handle_too_large(_error: object) -> Response: + return _error_response( + ApiError(413, "payload_too_large", "Тело запроса слишком велико"), + g.get("request_id", uuid.uuid4().hex), + ) + + +@app.errorhandler(404) +def _handle_not_found(_error: object) -> Response: + return _error_response(not_found(), g.get("request_id", uuid.uuid4().hex)) + + +@app.errorhandler(405) +def _handle_method(_error: object) -> Response: + return _error_response(bad_request("Метод не поддерживается"), g.get("request_id", uuid.uuid4().hex)) + + +@app.errorhandler(Exception) +def _handle_unexpected(error: Exception) -> Response: + request_id = g.get("request_id", uuid.uuid4().hex) + if isinstance(error, (psycopg.OperationalError, psycopg_pool.PoolTimeout, psycopg_pool.PoolClosed)): + log.warning("database unavailable on %s %s: %s", request.method, request.path, type(error).__name__) + return _error_response(unavailable("База данных недоступна"), request_id) + if isinstance(error, redis.RedisError): + log.warning("session store unavailable on %s %s: %s", request.method, request.path, type(error).__name__) + return _error_response(unavailable("Хранилище сессий недоступно"), request_id) + log.exception("unhandled error on %s %s", request.method, request.path) + return _error_response( + ApiError(500, "internal_error", "Внутренняя ошибка сервера"), request_id + ) + + +# --------------------------------------------------------------------------- +# Serialisation +# --------------------------------------------------------------------------- + +def format_time(value: datetime) -> str: + return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ") + + +def user_json(row: dict) -> dict: + return { + "id": str(row["id"]), + "username": row["username"], + "display_name": row["display_name"], + "created_at": format_time(row["created_at"]), + } + + +def chat_json(row: dict) -> dict: + member_ids = sorted(str(item) for item in (row.get("member_ids") or [])) + return { + "id": str(row["id"]), + "title": row["title"], + "member_ids": member_ids, + "created_at": format_time(row["created_at"]), + } + + +def message_json(row: dict) -> dict: + return { + "id": str(row["id"]), + "chat_id": str(row["chat_id"]), + "sender_id": str(row["sender_id"]), + "text": row["text"], + "created_at": format_time(row["created_at"]), + } + + +# --------------------------------------------------------------------------- +# Authentication +# --------------------------------------------------------------------------- + +def _bearer_token() -> str: + header = request.headers.get("Authorization", "") + parts = header.split(None, 1) + if len(parts) != 2 or parts[0].lower() != "bearer" or not parts[1].strip(): + raise unauthorized() + return parts[1].strip() + + +def current_user() -> dict: + cached = g.get("current_user") + if cached is not None: + return cached + token = _bearer_token() + user_id, token_digest = sessions.resolve(token) + if not user_id: + raise unauthorized() + try: + parsed = uuid.UUID(user_id) + except ValueError as exc: + raise unauthorized() from exc + with db.pool().connection() as conn: + row = conn.execute( + "SELECT id, username, display_name, created_at FROM users WHERE id = %s", + (parsed,), + ).fetchone() + if row is None: + sessions.revoke(token_digest) + raise unauthorized() + g.current_user = row + g.session_token_digest = token_digest + return row + + +def _basic_credentials() -> tuple[str, str]: + header = request.headers.get("Authorization", "") + parts = header.split(None, 1) + if len(parts) != 2 or parts[0].lower() != "basic": + raise unauthorized(basic=True) + import base64 + + try: + decoded = base64.b64decode(parts[1].strip(), validate=True).decode("utf-8") + except (ValueError, UnicodeError) as exc: + raise unauthorized(basic=True) from exc + name, separator, secret = decoded.partition(":") + if not separator or not name or not secret: + raise unauthorized(basic=True) + if len(name) > 32 or any(ord(char) > 127 for char in name): + raise unauthorized(basic=True) + return name, secret + + +def _authenticate_basic() -> dict: + name, secret = _basic_credentials() + with db.pool().connection() as conn: + row = conn.execute( + "SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = %s", + (name,), + ).fetchone() + if row is None: + raise unauthorized(basic=True) + try: + hasher.verify(row["password_hash"], secret) + except (VerifyMismatchError, InvalidHashError): + raise unauthorized(basic=True) + return row + + +# --------------------------------------------------------------------------- +# Health +# --------------------------------------------------------------------------- + +@app.get("/health/live") +def health_live() -> Response: + return _json({"status": "ok"}) + + +@app.get("/health/ready") +def health_ready() -> Response: + if not db.is_migrated(): + raise unavailable("База данных ещё не готова") + try: + with db.pool().connection(timeout=1.0) as conn: + conn.execute("SELECT 1") + except Exception as exc: + raise unavailable("База данных недоступна") from exc + sessions.ping() + return _json({"status": "ok"}) + + +# --------------------------------------------------------------------------- +# Users and sessions +# --------------------------------------------------------------------------- + +@app.post("/api/v1/users") +def register_user() -> Response: + body = json_object(request, settings.max_body_bytes) + exact_keys(body, ("username", "display_name", "password")) + name = username(body["username"]) + shown_name = display_name(body["display_name"]) + secret = password(body["password"]) + user_id = uuid.uuid4() + try: + with db.pool().connection() 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 + """, + (user_id, name, shown_name, hasher.hash(secret)), + ).fetchone() + except psycopg.errors.UniqueViolation as exc: + raise conflict("Username уже занят") from exc + return _json(user_json(row), 201) + + +@app.post("/api/v1/auth/sessions") +def create_session() -> Response: + row = _authenticate_basic() + token, expires_at = sessions.create(str(row["id"])) + return _json( + { + "token": token, + "token_type": "Bearer", + "expires_at": format_time(expires_at), + "user": user_json(row), + }, + 201, + ) + + +@app.delete("/api/v1/auth/sessions/current") +def revoke_session() -> Response: + current_user() # authentication must happen before revocation + sessions.revoke(g.session_token_digest) + return Response(status=204) + + +@app.get("/api/v1/users/me") +def current_user_endpoint() -> Response: + return _json(user_json(current_user())) + + +# --------------------------------------------------------------------------- +# Chats +# --------------------------------------------------------------------------- + +def _require_chat_member(chat_id: uuid.UUID, user_id: uuid.UUID) -> None: + with db.pool().connection() as conn: + row = conn.execute( + "SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s", + (chat_id, user_id), + ).fetchone() + if row is None: + raise not_found() + + +@app.post("/api/v1/chats") +def create_chat() -> Response: + actor = current_user() + body = json_object(request, settings.max_body_bytes) + exact_keys(body, ("title", "member_ids")) + title = non_blank(body["title"], "title", 1, 100) + member_ids = uuid_list(body["member_ids"], "member_ids") + actor_id = str(actor["id"]) + if actor_id not in member_ids: + raise bad_request("Создатель должен входить в member_ids") + + member_uuids = [uuid.UUID(item) for item in member_ids] + chat_id = uuid.uuid4() + with db.pool().connection() as conn: + existing = conn.execute( + "SELECT id FROM users WHERE id = ANY(%s)", (member_uuids,) + ).fetchall() + if len(existing) != len(member_uuids): + raise bad_request("Указан неизвестный участник") + row = conn.execute( + "INSERT INTO chats (id, title) VALUES (%s, %s) RETURNING id, title, created_at", + (chat_id, title), + ).fetchone() + with conn.cursor() as cursor: + cursor.executemany( + "INSERT INTO chat_members (chat_id, user_id) VALUES (%s, %s)", + [(chat_id, member) for member in member_uuids], + ) + payload = dict(row) + payload["member_ids"] = member_uuids + return _json(chat_json(payload), 201) + + +@app.get("/api/v1/chats") +def list_chats() -> Response: + actor = current_user() + limit = limit_arg(request.args.get("limit")) + cursor = decode_cursor(request.args.get("cursor")) + parameters: list[object] = [actor["id"]] + predicate = "" + if cursor is not None: + if cursor.get("kind") != "chats" or cursor.get("user_id") != str(actor["id"]): + raise bad_request("Некорректный cursor") + try: + cursor_created = cursor_time(cursor.get("created_at")) + cursor_id = uuid_value(cursor.get("id"), "cursor") + except ApiError: + raise bad_request("Некорректный cursor") + predicate = "AND (c.created_at, c.id) > (%s, %s)" + parameters.extend([cursor_created, cursor_id]) + parameters.append(limit + 1) + query = f""" + SELECT 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 + ) AS member_ids + FROM chats c + JOIN chat_members me ON me.chat_id = c.id AND me.user_id = %s + WHERE TRUE {predicate} + ORDER BY c.created_at, c.id + LIMIT %s + """ + with db.pool().connection() as conn: + rows = conn.execute(query, tuple(parameters)).fetchall() + page = rows[:limit] + next_cursor = None + if len(rows) > limit and page: + last = page[-1] + next_cursor = encode_cursor( + { + "v": 1, + "kind": "chats", + "user_id": str(actor["id"]), + "created_at": format_time(last["created_at"]), + "id": str(last["id"]), + } + ) + return _json({"items": [chat_json(row) for row in page], "next_cursor": next_cursor}) + + +@app.get("/api/v1/chats/") +def get_chat(chat_id: str) -> Response: + actor = current_user() + parsed_chat_id = uuid_value(chat_id, "chat_id") + with db.pool().connection() as conn: + row = conn.execute( + """ + SELECT 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 + ) AS member_ids + FROM chats c + JOIN chat_members me ON me.chat_id = c.id AND me.user_id = %s + WHERE c.id = %s + """, + (actor["id"], parsed_chat_id), + ).fetchone() + if row is None: + raise not_found() + return _json(chat_json(row)) + + +# --------------------------------------------------------------------------- +# Messages +# --------------------------------------------------------------------------- + +def _message_request_hash(text: str) -> str: + """Canonical body fingerprint; key order and absent optional arrays are equal.""" + canonical = json.dumps( + {"text": text, "attachment_ids": []}, + ensure_ascii=False, + sort_keys=True, + separators=(",", ":"), + ) + return hashlib.sha256(canonical.encode("utf-8")).hexdigest() + + +def _idempotent_message(actor: dict, chat_id: uuid.UUID, text: str, key: str) -> Response: + """Create one message and remember its exact response atomically. + + The unique constraint on (user_id, method, path, key) is the cross-replica + lock. A concurrent request with the same key waits for the first + transaction; after commit it reads the stored 201 response. If the first + transaction rolls back, the waiter inserts instead. A transient 5xx never + leaves a completed key without its message because both writes commit + together. + """ + digest = _message_request_hash(text) + path = request.path + expires_at = datetime.now(timezone.utc) + timedelta( + seconds=settings.idempotency_ttl_seconds + ) + + for _attempt in range(2): + with db.pool().connection() as conn: + inserted = conn.execute( + """ + INSERT INTO idempotency_keys + (user_id, method, path, key, request_hash, expires_at) + VALUES (%s, %s, %s, %s, %s, %s) + ON CONFLICT (user_id, method, path, key) DO NOTHING + RETURNING id + """, + (actor["id"], "POST", path, key, digest, expires_at), + ).fetchone() + if inserted is not None: + row = conn.execute( + """ + INSERT INTO messages (id, chat_id, sender_id, text) + VALUES (%s, %s, %s, %s) + RETURNING id, chat_id, sender_id, text, created_at + """, + (uuid.uuid4(), chat_id, actor["id"], text), + ).fetchone() + payload = message_json(row) + conn.execute( + """ + UPDATE idempotency_keys + SET status_code = 201, response_body = %s, message_id = %s + WHERE id = %s + """, + (Jsonb(payload), row["id"], inserted["id"]), + ) + return _json(payload, 201) + + existing = conn.execute( + """ + SELECT request_hash, status_code, response_body, expires_at + FROM idempotency_keys + WHERE user_id = %s AND method = %s AND path = %s AND key = %s + FOR UPDATE + """, + (actor["id"], "POST", path, key), + ).fetchone() + + if existing is None: + # The conflicting row was removed by an expiry cleanup between + # our insert and select; retry the insert once. + continue + if existing["expires_at"] <= datetime.now(timezone.utc): + conn.execute( + """ + DELETE FROM idempotency_keys + WHERE user_id = %s AND method = %s AND path = %s AND key = %s + """, + (actor["id"], "POST", path, key), + ) + continue + if existing["request_hash"] != digest: + raise conflict("Idempotency-Key уже использован с другим телом") + if existing["status_code"] is None or existing["response_body"] is None: + raise conflict("Запрос с этим Idempotency-Key ещё выполняется") + return _json(existing["response_body"], existing["status_code"]) + + raise unavailable("Не удалось согласовать повтор запроса") + + +@app.post("/api/v1/chats//messages") +def create_message(chat_id: str) -> Response: + actor = current_user() + parsed_chat_id = uuid_value(chat_id, "chat_id") + _require_chat_member(parsed_chat_id, actor["id"]) + key = idempotency_key(request.headers.get("Idempotency-Key")) + body = json_object(request, settings.max_body_bytes) + exact_keys(body, ("text",)) + text = message_text(body["text"]) + return _idempotent_message(actor, parsed_chat_id, text, key) + + +@app.get("/api/v1/chats//messages") +def list_messages(chat_id: str) -> Response: + actor = current_user() + parsed_chat_id = uuid_value(chat_id, "chat_id") + _require_chat_member(parsed_chat_id, actor["id"]) + limit = limit_arg(request.args.get("limit")) + cursor = decode_cursor(request.args.get("cursor")) + parameters: list[object] = [parsed_chat_id] + predicate = "" + if cursor is not None: + if cursor.get("kind") != "messages" or cursor.get("chat_id") != str(parsed_chat_id): + raise bad_request("Некорректный cursor") + try: + cursor_created = cursor_time(cursor.get("created_at")) + cursor_id = uuid_value(cursor.get("id"), "cursor") + except ApiError: + raise bad_request("Некорректный cursor") + predicate = "AND (created_at, id) > (%s, %s)" + parameters.extend([cursor_created, cursor_id]) + parameters.append(limit + 1) + query = f""" + SELECT id, chat_id, sender_id, text, created_at + FROM messages + WHERE chat_id = %s {predicate} + ORDER BY created_at, id + LIMIT %s + """ + with db.pool().connection() as conn: + rows = conn.execute(query, tuple(parameters)).fetchall() + page = rows[:limit] + next_cursor = None + if len(rows) > limit and page: + last = page[-1] + next_cursor = encode_cursor( + { + "v": 1, + "kind": "messages", + "chat_id": str(parsed_chat_id), + "created_at": format_time(last["created_at"]), + "id": str(last["id"]), + } + ) + return _json({"items": [message_json(row) for row in page], "next_cursor": next_cursor}) diff --git a/app/migrate.py b/app/migrate.py new file mode 100644 index 00000000..69c5daa7 --- /dev/null +++ b/app/migrate.py @@ -0,0 +1,33 @@ +"""One-shot migration entry point used by Compose. + +Run after PostgreSQL is healthy and before API replicas start: + + python -m app.migrate +""" +from __future__ import annotations + +import logging +import sys + +from . import db + +logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s") + + +def main() -> int: + try: + db.pool().open(wait=True, timeout=60) + db.apply_migrations() + if not db.schema_is_current(): + raise RuntimeError("schema verification failed after migration") + except Exception as exc: + logging.getLogger("messenger.migrate").error("migration failed: %s", type(exc).__name__) + return 1 + finally: + db.close_pool() + logging.getLogger("messenger.migrate").info("migrations applied and verified") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/app/sessions.py b/app/sessions.py new file mode 100644 index 00000000..96363f6b --- /dev/null +++ b/app/sessions.py @@ -0,0 +1,101 @@ +"""Opaque bearer sessions stored in Redis/Valkey with a TTL. + +PostgreSQL is the source of truth for users/chats/messages. Redis is the +authoritative store for *active sessions*; its append-only file and named +volume make those sessions survive a restart. The raw bearer token is never +stored: only a SHA-256 digest is used as the Redis key. +""" +from __future__ import annotations + +import hashlib +import json +import secrets +from datetime import datetime, timedelta, timezone + +import redis + +from .config import settings +from .errors import unavailable + +_client: redis.Redis | None = None + + +def client() -> redis.Redis: + global _client + if _client is None: + _client = redis.Redis.from_url( + settings.cache_url, + decode_responses=True, + socket_connect_timeout=settings.redis_connect_timeout, + socket_timeout=settings.redis_socket_timeout, + retry_on_timeout=False, + health_check_interval=30, + ) + return _client + + +def digest(token: str) -> str: + return hashlib.sha256(token.encode("utf-8")).hexdigest() + + +def _key(token_digest: str) -> str: + return "session:" + token_digest + + +def create(user_id: str) -> tuple[str, datetime]: + token = secrets.token_urlsafe(32) # 256 bits of entropy, opaque to clients + ttl = settings.session_ttl_seconds + expires_at = datetime.now(timezone.utc) + timedelta(seconds=ttl) + payload = json.dumps( + {"user_id": user_id, "expires_at": expires_at.isoformat().replace("+00:00", "Z")}, + separators=(",", ":"), + ) + try: + client().setex(_key(digest(token)), ttl, payload) + except redis.RedisError as exc: + raise unavailable("Хранилище сессий недоступно") from exc + return token, expires_at + + +def resolve(token: str) -> tuple[str, str]: + """Return (user_id, token_digest) or raise a bounded 503 error.""" + token_digest = digest(token) + try: + raw = client().get(_key(token_digest)) + except redis.RedisError as exc: + raise unavailable("Хранилище сессий недоступно") from exc + if not raw: + return "", token_digest + try: + data = json.loads(raw) + user_id = str(data["user_id"]) + expires_at = datetime.fromisoformat(str(data["expires_at"]).replace("Z", "+00:00")) + except (ValueError, KeyError, TypeError): + return "", token_digest + if expires_at <= datetime.now(timezone.utc): + revoke(token_digest) + return "", token_digest + return user_id, token_digest + + +def revoke(token_digest: str) -> None: + try: + client().delete(_key(token_digest)) + except redis.RedisError as exc: + raise unavailable("Хранилище сессий недоступно") from exc + + +def ping() -> None: + try: + if not client().ping(): + raise unavailable("Хранилище сессий недоступно") + except redis.RedisError as exc: + raise unavailable("Хранилище сессий недоступно") from exc + + +def seconds_left(token_digest: str) -> int: + try: + value = client().ttl(_key(token_digest)) + except redis.RedisError: + return 0 + return max(0, int(value)) diff --git a/app/validation.py b/app/validation.py new file mode 100644 index 00000000..6fe7ca47 --- /dev/null +++ b/app/validation.py @@ -0,0 +1,152 @@ +"""Strict parsing shared by HTTP handlers. + +The contract requires rejection of extra JSON fields, wrong types and +whitespace-only required strings. Validation happens before any SQL. +""" +from __future__ import annotations + +import base64 +import binascii +import json +import re +import uuid +from datetime import datetime, timezone + +from flask import Request + +from .errors import ApiError, bad_request + +USERNAME_RE = re.compile(r"^[a-z0-9_]{3,32}$") +INTEGER_RE = re.compile(r"^[0-9]+$") +IDEMPOTENCY_RE = re.compile(r"^[A-Za-z0-9._:-]{1,128}$") + + +def json_object(request: Request, max_bytes: int) -> dict: + if request.mimetype != "application/json": + raise bad_request("Ожидается application/json") + raw = request.get_data(cache=False) + if not raw: + raise bad_request("Тело запроса обязательно") + if len(raw) > max_bytes: + raise ApiError(413, "payload_too_large", "Тело запроса слишком велико") + try: + value = json.loads(raw) + except (ValueError, UnicodeError) as exc: + raise bad_request("Некорректный JSON") from exc + if not isinstance(value, dict): + raise bad_request("Ожидается JSON-объект") + return value + + +def exact_keys(value: dict, required: tuple[str, ...], optional: tuple[str, ...] = ()) -> None: + allowed = set(required) | set(optional) + if not set(required).issubset(value) or set(value) - allowed: + raise bad_request("Неверный набор полей") + + +def text_field(value: object, name: str, minimum: int, maximum: int) -> str: + if not isinstance(value, str): + raise bad_request(f"Поле {name} должно быть строкой") + if not (minimum <= len(value) <= maximum): + raise bad_request(f"Поле {name} имеет недопустимую длину") + return value + + +def non_blank(value: object, name: str, minimum: int, maximum: int) -> str: + result = text_field(value, name, minimum, maximum) + if not result.strip(): + raise bad_request(f"Поле {name} не должно быть пустым") + return result + + +def username(value: object) -> str: + result = text_field(value, "username", 3, 32) + if USERNAME_RE.fullmatch(result) is None: + raise bad_request("Недопустимый username") + return result + + +def display_name(value: object) -> str: + return non_blank(value, "display_name", 1, 100) + + +def password(value: object) -> str: + result = text_field(value, "password", 12, 128) + return result + + +def message_text(value: object) -> str: + return non_blank(value, "text", 1, 4000) + + +def idempotency_key(value: str | None) -> str: + if value is None: + raise bad_request("Заголовок Idempotency-Key обязателен") + if IDEMPOTENCY_RE.fullmatch(value) is None: + raise bad_request("Недопустимый Idempotency-Key") + return value + + +def uuid_list(value: object, name: str, minimum: int = 1, maximum: int = 100) -> list[str]: + if not isinstance(value, list): + raise bad_request(f"Поле {name} должно быть массивом") + if not (minimum <= len(value) <= maximum): + raise bad_request(f"Поле {name} имеет недопустимую длину") + parsed: list[str] = [] + for item in value: + parsed.append(str(uuid_value(item, name))) + if len(set(parsed)) != len(parsed): + raise bad_request(f"Поле {name} содержит дубликаты") + return parsed + + +def uuid_value(value: object, name: str = "id") -> uuid.UUID: + if not isinstance(value, str): + raise bad_request(f"Поле {name} должно быть UUID") + try: + return uuid.UUID(value) + except (ValueError, AttributeError) as exc: + raise bad_request(f"Поле {name} должно быть UUID") from exc + + +def limit_arg(raw: str | None, default: int = 50) -> int: + if raw is None: + return default + if INTEGER_RE.fullmatch(raw) is None: + raise bad_request("limit должен быть целым числом") + value = int(raw) + if not (1 <= value <= 100): + raise bad_request("limit должен быть в диапазоне 1..100") + return value + + +def encode_cursor(payload: dict) -> str: + raw = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8") + return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=") + + +def decode_cursor(raw: str | None) -> dict | None: + if raw is None: + return None + if not raw or len(raw) > 4096: + raise bad_request("Некорректный cursor") + padded = raw + "=" * (-len(raw) % 4) + try: + data = json.loads(base64.urlsafe_b64decode(padded.encode("ascii"))) + except (ValueError, UnicodeError, AttributeError, binascii.Error) as exc: + raise bad_request("Некорректный cursor") from exc + if not isinstance(data, dict): + raise bad_request("Некорректный cursor") + return data + + +def cursor_time(value: object) -> datetime: + if not isinstance(value, str): + raise bad_request("Некорректный cursor") + try: + result = datetime.fromisoformat(value.replace("Z", "+00:00")) + except ValueError as exc: + raise bad_request("Некорректный cursor") from exc + if result.tzinfo is None: + raise bad_request("Некорректный cursor") + return result.astimezone(timezone.utc) diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..664ef0d9 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,148 @@ +# Laboratory 3 stand: one public load balancer, N API replicas, shared +# PostgreSQL and Redis. Copy .env.example to .env and choose local passwords. +# Only the load balancer publishes a host port; API/database ports stay internal. + +name: mtusi-lab3 + +x-api-environment: &api-environment + APP_ENV: lab + DATABASE_URL: ${DATABASE_URL:?set DATABASE_URL in .env} + CACHE_URL: ${CACHE_URL:-redis://redis:6379/0} + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400} + DB_POOL_MIN: ${DB_POOL_MIN:-1} + DB_POOL_MAX: ${DB_POOL_MAX:-10} + DB_POOL_ACQUIRE_TIMEOUT_SECONDS: ${DB_POOL_ACQUIRE_TIMEOUT_SECONDS:-3} + DB_CONNECT_TIMEOUT_SECONDS: ${DB_CONNECT_TIMEOUT_SECONDS:-3} + DB_STATEMENT_TIMEOUT_MS: ${DB_STATEMENT_TIMEOUT_MS:-5000} + REDIS_CONNECT_TIMEOUT_SECONDS: ${REDIS_CONNECT_TIMEOUT_SECONDS:-2} + REDIS_SOCKET_TIMEOUT_SECONDS: ${REDIS_SOCKET_TIMEOUT_SECONDS:-2} + MAX_BODY_BYTES: ${MAX_BODY_BYTES:-1048576} + +services: + postgres: + image: postgres:16.4-alpine + restart: unless-stopped + environment: + POSTGRES_DB: ${POSTGRES_DB:-messenger} + POSTGRES_USER: ${POSTGRES_USER:-messenger} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env} + volumes: + - pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"] + interval: 3s + timeout: 3s + retries: 30 + deploy: + resources: + limits: + cpus: "${POSTGRES_CPU_LIMIT:-1.0}" + memory: "${POSTGRES_MEM_LIMIT:-512M}" + networks: + - backend + + redis: + image: redis:7.4.0-alpine + restart: unless-stopped + # Sessions are the only Redis data. AOF + the named volume keep active + # sessions across an API/Redis restart; TTL remains the expiry authority. + command: + - redis-server + - --appendonly + - "yes" + - --appendfsync + - everysec + - --dir + - /data + volumes: + - redisdata:/data + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 3s + timeout: 3s + retries: 30 + deploy: + resources: + limits: + cpus: "${REDIS_CPU_LIMIT:-0.5}" + memory: "${REDIS_MEM_LIMIT:-256M}" + networks: + - backend + + # Exactly one migration runner, not a race between API replicas. API + # containers wait for this service to exit successfully. + migrate: + build: + context: . + dockerfile: Dockerfile + command: ["python", "-m", "app.migrate"] + restart: "no" + environment: *api-environment + depends_on: + postgres: + condition: service_healthy + deploy: + resources: + limits: + cpus: "${MIGRATE_CPU_LIMIT:-0.5}" + memory: "${MIGRATE_MEM_LIMIT:-256M}" + networks: + - backend + + api: + build: + context: . + dockerfile: Dockerfile + restart: unless-stopped + environment: *api-environment + expose: + - "8080" + depends_on: + migrate: + condition: service_completed_successfully + postgres: + condition: service_healthy + redis: + condition: service_healthy + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).read()"] + interval: 2s + timeout: 2s + start_period: 15s + retries: 15 + stop_grace_period: 30s + deploy: + replicas: ${API_REPLICAS:-2} + resources: + limits: + cpus: "${API_CPU_LIMIT:-1.0}" + memory: "${API_MEM_LIMIT:-512M}" + networks: + - backend + + lb: + image: nginx:1.27.5-alpine + restart: unless-stopped + volumes: + - ./infra/nginx/nginx.conf:/etc/nginx/nginx.conf:ro + ports: + - "${API_PORT:-8080}:8080" + depends_on: + api: + condition: service_healthy + deploy: + resources: + limits: + cpus: "${LB_CPU_LIMIT:-0.5}" + memory: "${LB_MEM_LIMIT:-128M}" + networks: + - backend + +volumes: + pgdata: + redisdata: + +networks: + backend: + driver: bridge diff --git a/evidence/README.md b/evidence/README.md index 8df70015..408b6c00 100644 --- a/evidence/README.md +++ b/evidence/README.md @@ -1,5 +1,36 @@ # Доказательства -Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки. +Небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV +агрегаты нагрузки, EXPLAIN, лимиты контейнеров, текст разбора отказа. +Стенд: Windows 11, Docker Desktop 29.9.2, Compose v5.6.1, 16 logical CPU, +~15.2 GiB доступно Docker. Дата прогонов: 2026-11-06/07. -Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно. +Основные файлы: + +| Файл | Что доказывает | +| --- | --- | +| `check.txt` | `make check` / offline structure | +| `smoke.txt` | публичный smoke lab3 | +| `routing.txt` | одна сессия обслуживается ≥2 репликами | +| `idempotency.txt` | конкурентный повтор через разные реплики, 409/400 | +| `idempotency_persistence.txt` | тот же ключ после полного рестарта | +| `failover.txt` | публичный failover-сценарий | +| `failover_matrix.json/.txt` | поочерёдная остановка каждой реплики, RPS/ошибки | +| `persistence.txt` | данные и сессия переживают рестарт | +| `containers-before-restart.txt`, `containers-after-restart.txt` | какие контейнеры реально перезапущены | +| `rolling_update.json/.txt` | поочерёдная замена под нагрузкой | +| `schema.txt` | таблицы, индексы, ограничения, миграции | +| `migrate_service.txt`, `migrate_logs.txt` | one-shot migrate service | +| `pool_settings.txt` | bounded pool и SQL-таймауты | +| `explain_history.txt` | Index Scan на 10 000 сообщений | +| `fault_matrix.txt` | 503 при отказе Redis/PostgreSQL и восстановление | +| `expiry.txt` | короткий TTL и 401 | +| `auth_negative.txt`, `race_username.txt`, `rollback_chat.txt` | негативные и конкурентные проверки | +| `container_limits_ports.txt` | CPU/RAM-лимиты, только LB публикует порт | +| `compose_config.txt` | итоговая конфигурация Compose | +| `track1_report.txt/.json` | агрегаты трека 1 | +| `track1_summary.json`, `track1/*.json` | сырые прогоны и метрики | +| `track1_fixed_total.svg`, `track1_growth.svg` | графики | + +Не добавлены `.env`, токены, cookies, приватные ключи, credentials, реальные +сообщения и raw dumps. В `schema.txt` нет секретов; в логах нет токенов. diff --git a/evidence/auth_negative.txt b/evidence/auth_negative.txt new file mode 100644 index 0000000000000000000000000000000000000000..e5f4818edf65ee5249f5fe2ecd6202d8ae23cb03 GIT binary patch literal 142 zcmXYp+X;g}6hzN=AU$jWsldNjfshKqD!#%RHW9mzo-8s9oIA|i{nv2kp(+9!nT13z zzj^Xen@OhSW>%MMB+8kNNk_hnW%X~oq+YM4!FF;P0WJqr2+{xU}yQbn~?Fc;R zt;mf;XFqaRqbKX7LNZS#8p-6VVO*84NqCt9^;cKZ6?Fw3*R-NYx|*s`}S~cXmwT5YY(8P+3m= zalU)+p3fie$2h_*Vx(9>^=fy>ut9;mmvuj%Z7V_a$~beZQ8pso5M^rOzcKnfXE~9? z22b0^oOUVCXS7+7W69ZqqYZ>}She=4?zyuL2jpDGup@`0xvsu&`!-#+&2ypQJYoh4 zlg}6WNtm|<&NzyhC0WrPyDfI!+{O5>zsC4mQ;3M@95YP0cR@s_#8C1sBu49;C`Iv% zh}T?Ma@R-QL?=4$<1GH`b|{>E)HQzfqs|HSZmX=YMZkQIO&>A0Pt0t9OFWpJD^ouO zuB+96dnfE}-Mt2KBA^!5ljeAb$La<}9Xf03JfXUpN>BNp4WzTJ{{qjfdwDG^|3lIF ncXwNuE?Lozt-T*ZbC%j|SG1zCQq2>p9q}7+_P2VLns)sY9uc$A literal 0 HcmV?d00001 diff --git a/evidence/containers-after-restart.txt b/evidence/containers-after-restart.txt new file mode 100644 index 0000000000000000000000000000000000000000..3ee09858d9feec49e17b14883b1b2c66ca6c4d47 GIT binary patch literal 1818 zcmeHHO;5r=5Pb(uCMN!brYB8A1xis8O%RFUAQ~!Oj0Xf#iF_DZ68-b)n=NZg`RK-j zC(~>@yEFS{_RZUVeYQ};4H~cvpC+SgxHjBT$1US!M+;X*89XAl@qi}ki5zvVHHdQ0 z_j(+UKJj|l%#a|9S7j}f|fMu}DzZ)&Bml4V=`YBn1_(I>>} zVTu_oi|Bb~8Pe|K949#9xXkV4+?>707G+PPIrNUzzBy|iux5*O`oz_d9ae2YY7Xd^ zjFQ8`K3+KQ@_Zq!s`7`N&p4Mld>n8sdQMr5jAQzG#LMQW__J4I{BxvrG-9Xosw0{k z{T0@Q`*-%EKn)a8;k&G~H&W`GuxC2jW_y&`^CbJRd&dV9vM}|Q)cXDMG6xES@Fq>+>e;~ zv`6Z3S(&qzZ`+9LAjNh%N5qjS+j5JNw^nYq`MoXkBqeGn`_>9Ged;C2PE={^sVXfx ds&n!$T-Bq6-*FV@NGj-WIC9BQ1!qefeFJ70^`8I$ literal 0 HcmV?d00001 diff --git a/evidence/containers-before-restart.txt b/evidence/containers-before-restart.txt new file mode 100644 index 0000000000000000000000000000000000000000..5ef5b66df18b09a4fa27f43ad6523eddd2e616c0 GIT binary patch literal 1710 zcmd^9%Syvg5Iu{o1i??ZWTjxMeWhAZsIf>FR%xsoaZ%e6i+xCwg8g~*%uPa?q>rGu zl5o>u9%tsBIqBDD8x7o|36=3_F}s1Aj1?B{m@gG=TxaTF6S;#&v|z3Du;^?@ zI5uMv@50X1N8z5cby#6zAA6X`3!I|BbCo;DnK>iq=66q`RT!Pz*a%ROj9pZ+WT~4h~T9bE(S61|R zLyy)HM?uXQd&@bYzt8I3j0k%C`LB$Oxy3xv3Q^pwqxbZII^zXyq{equ>uRi(HRU!! z77emL;1>IMqj%1%ArU-UOXkirlE?bEMx=X)5dD^5(z{J1n>7-l#4TT;qEb0>BVRQ| zPI?*Gk%Erd|A|?3JnziitTwr~OAZ{eAWDyTPDW%Nlap1}vTI~w)=hAm?BVnA8*Vp! ze^t(1rapFmf5O9nT3F@6pDT*gwazMfPx2p@)|$f47>RnUYU3{$G08^_=P^dU0rOnv Al>h($ literal 0 HcmV?d00001 diff --git a/evidence/containers.txt b/evidence/containers.txt new file mode 100644 index 0000000000000000000000000000000000000000..e436cb9ea166c1a133e357c9b6bebb1ebce70302 GIT binary patch literal 2010 zcmd^9O-sW-5PgT91i_yWa;jjf{nmm)twnmUN@Kl=$hc_Rp(tHjUe~NfQK5 z5|RwNGjC?!yxFhM4jQ;a3r5PPP45P7Q${p#Pk)K%;3icDi^yF(p^fH7jwaVyM0w;l z8pq&#K6nlabe{OlUVx60fdtGFd=9e&bC+|RQ+HGV5f zVtqtNRoauNRFHW%-&F z-O4NH@)cBIy;nPGI$;&h^s3_}(KlXsat@a~*h>4GTt_P}?5|H@lE;;rg6Vo1$E;5# zZpPE-s4&BNT_!I;OJ=x*57sR)4x_SUOD3;?q*;#VK~%6HqHrO1fM#NQNBUCbnaYt` zGgIkov8A-_96l4tJj5$)|IJik^(D?s^35b{IOKYh5x+XUQ&+QBR;rades}&1{Eio$ SBhZHY|Bja`S*hV7#LG8%z!Gc# literal 0 HcmV?d00001 diff --git a/evidence/expiry.txt b/evidence/expiry.txt new file mode 100644 index 0000000000000000000000000000000000000000..df3afd4c8d06b9d6025206e7c089f065186cdf54 GIT binary patch literal 132 zcmXYpK?=e^5CrQi7YKR5vIgBCiR=dS^_p^#hM8`vXTF~c1EV_8GV$g~ yBI~Z^;w~z&vY3;;t#p<|wtw#>*|^Jkj&$x||M%f+Bh-s*igp4IHOX(zh66j?>KHWu literal 0 HcmV?d00001 diff --git a/evidence/explain_history.txt b/evidence/explain_history.txt new file mode 100644 index 0000000000000000000000000000000000000000..286c06134aa5a7fc80471ca66a4fca19659bf24f GIT binary patch literal 1896 zcmb`I+fEZv6o%KeiSICp7cJ424n5G;R3cI%Nd-bN2sce>r(%Q_Xi@6JtKYx2(?W{` zjoI0US$m!KzYg>B$1{tpX&-IRTK3wuZHMnHryXX?j_jD*7tl8CgS}-mZQt6q0%c$$ zyJG)hiA`)I!1L-q;#h|^Ph0xjW`ph5J+`quGN$FBMASsmFm zD=;gTvzU?Nt6~RGVs49!x|N{iIhCQ7t;W}}Yd=Thm?7Ibb=-pvdQaVow8wCVA%D^v zarWJM56LR8Tt{z={v37+cEXy&ZV3r_R&yTFx{QR|A{2REgExUD?U%etZ=Jg4Lwn~q zHu2)F-N+iyHkgXQ7JC+sE7x-yB}GJjDh{ulYr~_o;gnrswB;5Qw2%BkSvPa$GbT-kKKLvhD-{pv?}wLwLFAu4aAC| zP+Y*a1f>AN|BA143R}%JBDWm3KjABH({UTIH~zX%H(AfwP-o%wA*(Z>`hO}aLuBj3 z=GwDMH88K1ecQFeM^;VBn*oKi(-gp3okrQL?ogkt%J#C~Ja<~~BF$d)ye>I%ft<2l zIX}_xJ!hs6Q9E8bB`9(DDWDtHaZRryn6KXKl^$83OP(H4tk_JoFC; z|B7Xqn0G5@Q<*)Y-)2asYBjB5)o!TzP (?, ?) ORDER BY created_at, id LIMIT 51 + +Limit (cost=0.29..11.81 rows=51 width=77) (actual time=0.024..0.032 rows=51 loops=1) + Buffers: shared hit=4 + -> Index Scan using messages_chat_created_at_id_idx on messages (cost=0.29..973.31 rows=4305 width=77) (actual time=0.023..0.028 rows=51 loops=1) + Index Cond: ((chat_id = 'ce8f7912-30b3-44c6-98f3-aae338209bea'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 00:00:09.501+00'::timestamp with time zone, '806c83dc-f566-4736-8ef4-094bdcd28f33'::uuid))) + Buffers: shared hit=4 +Planning: + Buffers: shared hit=7 +Planning Time: 0.208 ms +Execution Time: 0.138 ms diff --git a/evidence/failover.txt b/evidence/failover.txt new file mode 100644 index 0000000000000000000000000000000000000000..f7f3308886a65a0758bfd109b0fc2ad5ec6df961 GIT binary patch literal 598 zcmYk3!AitH5Jc-N_zy$Q5?Bw4dh#H66#Re?ldJ}JHzAqC74g^A*F75vLozcxRn^tq zzdsK;s!^p$QLPSoRp5S9uO0V_FA~|R>r7wDz`wZ4;4W$v&KOZFab9_r0!)M7&iR>c z$#tm<{u$f}RKks5CMqiQ0n(~8j|sogM%O3KQn`6A$P*p8rz-Qd;FJCqoq=csX*E~4 zNd5XGlB()(TCbS7ZghpiZ?E!6_j+cT>m~D|5&k=A6EI!trsX(*waoidtahIzuhths v*+g4+w(habq;-A{=8=<4)aGWYJ*)t~an+G?iVd!A{WaYgg_=F}Kh5e72)k^k literal 0 HcmV?d00001 diff --git a/evidence/failover_matrix.json b/evidence/failover_matrix.json new file mode 100644 index 00000000..addca84d --- /dev/null +++ b/evidence/failover_matrix.json @@ -0,0 +1,117 @@ +{ + "base_url": "http://localhost:18081", + "workers": 6, + "duration_seconds": 16.0, + "replicas_before": [ + "3ea06cf03241", + "ec52acd6f3e0" + ], + "runs": [ + { + "target_instance": "3ea06cf03241", + "target_container": "3ea06cf03241", + "success_by_second": [ + 194, + 177, + 109, + 41, + 98, + 103, + 43, + 73, + 86, + 54, + 71, + 90, + 52, + 69, + 81, + 50, + 73 + ], + "errors_by_second": [ + 0, + 0, + 2, + 0, + 0, + 1, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0 + ], + "successes_total": 1627, + "errors_total": 3, + "stop_seconds": 2.564, + "restore_seconds": 12.001, + "first_write_after_stop_seconds": 0.009, + "target_served_during_outage": false, + "target_present_after_restore": true, + "instances_after_restore": [ + "3ea06cf03241", + "ec52acd6f3e0" + ] + }, + { + "target_instance": "ec52acd6f3e0", + "target_container": "ec52acd6f3e0", + "success_by_second": [ + 242, + 105, + 86, + 78, + 38, + 79, + 77, + 38, + 75, + 78, + 41, + 62, + 60, + 37, + 60, + 70, + 74 + ], + "errors_by_second": [ + 0, + 0, + 3, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0 + ], + "successes_total": 1300, + "errors_total": 3, + "stop_seconds": 2.803, + "restore_seconds": 12.0, + "first_write_after_stop_seconds": 0.03, + "target_served_during_outage": false, + "target_present_after_restore": true, + "instances_after_restore": [ + "3ea06cf03241", + "ec52acd6f3e0" + ] + } + ] +} diff --git a/evidence/failover_matrix.txt b/evidence/failover_matrix.txt new file mode 100644 index 0000000000000000000000000000000000000000..423044f3353393ccb61984036d25780e018e2bc3 GIT binary patch literal 2222 zcmeHJT~FIU5S(Wu{sZ!JiR`$E13dK~An{01WUzx=g^=2W4^{o^ZD;QGLe3(ANIX`S ze0O`db9;L`WB>j03ke=jqQxz0_NHjCK<8`=+|ZWb6i0mL?3YL}rgg?P#}HqUapsGg zk5O)LPaN5VR}=rEI2~5pK|6PRrntrn-yO#uvofSh?tQ`tw0nkvkME_ls;Ai0o?x<` z$!*5B1<#-r6P`)!$k2+lXKMDLYsZE>vH20RAV1+;xnAN<+Vbq}JF$CD|Muvc79aVh zW&eJND9)#{I_16GyStfNE;D9eXc_FEp}*GWEFq3&mc6^_3~`77^EtMRCd`L+mWO)r zeFmS5F$|c~)bg9K&Kj3V)#Vd=4H4vBaz?$@A?=DIHAG(%{aRO5wRq&aB2vZ5(;f?Q zVaiBX+@o~7@U=VRXwFmAcGq#mFX^i@)~@d37~|7>v?;)Bj&YaTk$?-&LgGg6@KFo2l%)GY{wD{`nlb%0Po?%6}w9Tq(GiM8LMXG?j^9f zFy80Z7RKJ76t8yg7uE;e5F>Q1v9UZieuQyh_JT14uBn>#Wxwas{`^*K+r2_WaW1#9 zKPQsM`aJeeh#0gYuHN13_qFs{%nuR7T>a1c1DxXDiKs z*HAl39GiYGx&Dr0=~shij>PmkehKD8kt$a>qqU~4Htb6e^)=T%ecN~Hk^T_oM34$g Q&o{9L_`zNECn2T!2PRKaKmY&$ literal 0 HcmV?d00001 diff --git a/evidence/fault_matrix.txt b/evidence/fault_matrix.txt new file mode 100644 index 0000000000000000000000000000000000000000..00afc439f7a7221dae7148b6607d2c9ae1c189ae GIT binary patch literal 710 zcmchVK}!QM5QX1a@IU0JAhNEApm=C$y($*Gw_TB9n{GD=rGH-iW?FhF#hzp#JDGVe zZ}Kuf-!JNGq@mvQ&N|S8f;xSu(M*ZB(Nb&0eSYkf2qN)4=}whybp>)lZtUD{cg9M^ zae0qB*O~rOENYLc)u>gRKBJ>Rbd7#;^@R2UwV+JLUqlhrLwuzhzt@F&bn*2Fc z`)21&Sub_0*Ov1Q`RRB4KaUP|Pj{+zr)v7Pmpav}TK8bhhgaMh@!51VxMQA0kD{j9 zke$0L=0=MzOKOFR%~4<%sT*oSTy{*WY^P^CaS5g&6Rf01s*!!*UF{#?FPv=}8I1xe Gdw0L+OLUX~ literal 0 HcmV?d00001 diff --git a/evidence/idempotency.txt b/evidence/idempotency.txt new file mode 100644 index 0000000000000000000000000000000000000000..f87cb747c683b0efca93ef890f2e95af8c17e7db GIT binary patch literal 342 zcmZ9I%L>9U6hvn&_z(U-QKTCc1VtCFEEe2X6SY_$v{mfStLFv z863l7^)#S6<=S!lkJAQKhs&4OgLi^w`Z<1kbwj_SRxmm4k0>;1tEEH}a-|_pr2`!E rH;yqqN>}u2Cd=3a-12xm;BL7oK%>t;uxy5w?B?G=J<)>xpUS-7inKeH literal 0 HcmV?d00001 diff --git a/evidence/idempotency_persistence.txt b/evidence/idempotency_persistence.txt new file mode 100644 index 0000000000000000000000000000000000000000..808ec64be0413214e60ede6322b95302067601df GIT binary patch literal 1666 zcmchYTWb?h6ouErJPG{|!6!whUWybVinUY_QLK3sDPuB81DR=a&qzdF`p*e!Or&~J8US=<{=UF#nZ$SZS`Gq4UnkWO@~7D^q00(CVmY7P2#dVn`$~LyHqj^)L&0gOW^=fu@h2pVKne8@LPj&WLAiL(ilf_>W=DHO5=cZJbBJDVQXlL;iORm;IWM K+RJ>p+kOH#NgSd8 literal 0 HcmV?d00001 diff --git a/evidence/migrate_logs.txt b/evidence/migrate_logs.txt new file mode 100644 index 0000000000000000000000000000000000000000..cb206f73762907408ea79f7f1f4f27d8df2d308b GIT binary patch literal 1640 zcmdUv+iC(a5QhJ2q3^H{5KFS_`2mF9*heUe+Y<0lst7`#UHvjrsvv6VUbuwGW+!3h z%k00i-^~^Ep)ZZKR;i|fGR8NS%VQn$1!m7Wd4mSbJ)7Hd>Z^-odeKNjy|S7UX~ihD zAa+UgXH7L>XRJ@gOk1+1y>#|Bf7B9hMkY^|H#-yIdQ#);+}}AnaC#MRSIwEjIpbav zqF2S)rnkvwDVu`7Pog;&-8O$36DeGN5d^N z;o$bH>QeK<{=oosBCnHLj^s%v&bV*)jYm;Sfw~9QnH+tv%MI$ImP8)t(TP02qgPj7 F^8+M+u}DbxL5hJ2B=XV$7~uMIZtbWeeZo2IuM2{mn)dGR8h$``-w_AMdi>HGz5_j-R;(@cEI#A`5 zYvQgVQuC6dwYsoMA6WrbroDE$>ZBX%0QaA#wUarXmTsOdjqYgodM{W(x4|&$ srwO+n%ySj_8MPN8o7mfPFNq+Tl(35PAC-I>EF^UKdQS&(EtDd literal 0 HcmV?d00001 diff --git a/evidence/pool_settings.txt b/evidence/pool_settings.txt new file mode 100644 index 0000000000000000000000000000000000000000..5f211c5869f4f703dce329ad6ee9b89de3215cb8 GIT binary patch literal 398 zcmZ{gK@NgI3`PIi#5-^Vh;d`$!o3R(2OtBuAR-t>i1G01n*j_O%%qvN|F`|^>uGh9 z!A`nh6<&fBKC0E?2ijt5SuM2y$yLHk@G8%3sINecGGAHyyoFDrassI20 literal 0 HcmV?d00001 diff --git a/evidence/race_username.txt b/evidence/race_username.txt new file mode 100644 index 0000000000000000000000000000000000000000..cb3142c42ea8d5dd55373ca2c3317d5324b68ac2 GIT binary patch literal 154 zcmXwx(FuSs3`Fl+a0kZ_|J*=u0%?N?QpGCh^6G0vj;6`oOP;$^s~$C~RP&q`1?r&< z8U2o%x>1uN)24wsWiFDfIEy?R4$9-0P8bI@>taq9jsIZZpexdl$v;VcMBmj?g zK;yr%@lly&6Qd||yJ%(7|4%gL1D*V?KRSc67CqfJzP9D;;uh`64Z)6hd9pvL7Z;km JomB7K_yO6BA6EbX literal 0 HcmV?d00001 diff --git a/evidence/rolling_update.json b/evidence/rolling_update.json new file mode 100644 index 00000000..6905422f --- /dev/null +++ b/evidence/rolling_update.json @@ -0,0 +1,90 @@ +{ + "base_url": "http://localhost:18081", + "workers": 8, + "duration_seconds": 24.0, + "success_by_second": [ + 86, + 137, + 149, + 139, + 87, + 38, + 60, + 62, + 40, + 55, + 62, + 63, + 117, + 144, + 58, + 53, + 63, + 43, + 55, + 57, + 67, + 124, + 196, + 150, + 8 + ], + "errors_by_second": [ + 0, + 0, + 0, + 0, + 7, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 5, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0 + ], + "successes_total": 2113, + "errors_total": 12, + "runs": [ + { + "target_instance": "3ea06cf03241", + "stop_seconds": 4.032, + "stop_command_seconds": 0.599, + "restore_seconds": 6.632, + "recovered_seconds": 11.754, + "first_write_after_stop_seconds": 0.038, + "target_served_during_outage": false, + "instances_after_restore": [ + "3ea06cf03241", + "ec52acd6f3e0" + ] + }, + { + "target_instance": "ec52acd6f3e0", + "stop_seconds": 14.02, + "stop_command_seconds": 0.581, + "restore_seconds": 16.601, + "recovered_seconds": 20.721, + "first_write_after_stop_seconds": 0.022, + "target_served_during_outage": false, + "instances_after_restore": [ + "3ea06cf03241", + "ec52acd6f3e0" + ] + } + ], + "note": "sequential SIGTERM drain + restart; same image, no volume removal" +} diff --git a/evidence/rolling_update.txt b/evidence/rolling_update.txt new file mode 100644 index 0000000000000000000000000000000000000000..f18ed67ec78e48dfb6ca742b7d1afdf9ab0ed8b1 GIT binary patch literal 1324 zcmds1O;3YB6r8h(|AF*u8lV)bp8N+U9@P+1psAs>(pC?~zpl=_C2hdga`0p}VIRA1 z-skN5`h3R#8>FZ)Lry8d92M4fR$`l%j{+2fRZ#!42(0H4SweBc~s=+B+wwz_OM#GQbh zQ2oLmOzY2`3A?)I!71(p%vbF3Tc|$l35gMV!X5Ij*c0yZ{~zqR!!7Q)G+os77cxEP z4A}5}iQyh!!IFDv6KQ7uIp<4hjLbPPoVI7PW??s)V0zg%)Xw>$=9HzSIVL~dv&W8) TgfXm$NzKj>&x}lSOl%uYQRVc4m{Ao$Tkm(@L2( zI_LIFit)wjt4C(a zZ&}EwNi6W6K%)k1xH;Hyti103cmLN$541c?yuh0}UD?d)4*MjZ;d{%bCd@tQTV2TN O;GbiJqgIJhg`K{cg)2h< literal 0 HcmV?d00001 diff --git a/evidence/schema.txt b/evidence/schema.txt new file mode 100644 index 0000000000000000000000000000000000000000..4685db0f48550ab6f3d54edb97fb8858dd0357f6 GIT binary patch literal 8528 zcmd5>TW=dh6h6;L{0BcE#Zl|Z4r&OMc&Gv`Q6Vi2NE8H?orKiXiPP9A4!55UeBYdm zXJ+TJ>q}6z@_Ke>&h48s=gge__n(&NHIso1Wh|%CmkYGd(XxFl`A|NPPNRz>TXHO~ z!D9wq?ft;C^N}3v3lrb>U zM(DjVvPa-{v7o+2%jwXTU1)iQ5x?R6w$V%Zy}KQy)I{J<4+n?HKrV5OWrXo3kW6b` zuiwgHcdrqidDKchG)>_j~5PD-ZDgV>5OS z_j`Ei-p&wPJK#EoT|p8}^Ap6=x`VsVdkkyg0j*Nt-pcx{v zT)~T(6WSgPBlms0v(c4t=;St@=I!?_E#u_)IxHz+4w>$XacYK4iTkFoaxyGdp(UDo z99C1$E@z>(e5|I3&c|j>n0Z_d(izZuh?3(G`cw+5rrb*?(UOu6(Vs%y=}9U7Sq774 zD=S1c_MiH7MueQK)p79cWt%&h+&+j}Q`fq2eQ=qB%gFc#HPyWs>F5)&y}l2u%RPlf z9nX@dq-?RPrk-z8#N1qlzL8rsc@L@6sm^ce=u23UcJtV9k3E4u@oW(1t=OB^!6qeZ z(;gMaWS%W%II~QEAEVHvSuw9oTP?PzR!<>0Z>f%Bw6_1(BKBC&tyn`Mwn%Ss{QMwTr1J;SFc>FUPy7yE5{;!VZnDz8=T zwQ^%wtJ`1YsdL{(eIj2YU=A9?@^hT?!x|MW3$GIszgZEQp@PKB754LqR3lV>$m<%M zwbsE3nD)gK{+m!6J>d@wpIjZtQP-c&S36Ocs7ih7pS1N{Os{rUhApB!1m0)(U0_zi z-rN(Z4&`}rH2W?vTXS%Ghxs1kWV!|Jn7kvYlkMyfo>f#*G1UG2+1HpS62vqk`-%*MZQIC2 z&fWab$iBe{j`|h7>>DPyq-8gg8}6~f)kF@ft)qH-Q+rZt2j$LywCcwB;JLen?*Xi$ z(+6yCOMW+~*t}4RM~op8%;+0nYw2~i$-TXZEU7c?-D*Y;V1Dhvveb7EE4}(p@4UcO zuB?-ah^~5R{-oa%efRBUHGZ^p{hanb)wOl~*5@{jqM*e;>$GQ@ehK_A8@zih3J89Q_18{vX0hjfvstDXgY`9Ity= zR?)x0PpjQYsq6_2F m9J6n8%PCqm>hsi3300}_v+B`Xe6`M5zM7Prl|A{Sfb)M2KZC0P literal 0 HcmV?d00001 diff --git a/evidence/schema_queries.sql b/evidence/schema_queries.sql new file mode 100644 index 00000000..1dc95931 --- /dev/null +++ b/evidence/schema_queries.sql @@ -0,0 +1,15 @@ +SELECT table_name FROM information_schema.tables + WHERE table_schema = 'public' ORDER BY table_name; +SELECT version, applied_at FROM schema_migrations ORDER BY version; +SELECT tablename, indexname, indexdef FROM pg_indexes + WHERE schemaname = 'public' ORDER BY tablename, indexname; +SELECT column_name, data_type, is_nullable, column_default + FROM information_schema.columns + WHERE table_name = 'idempotency_keys' ORDER BY ordinal_position; +SELECT conname, pg_get_constraintdef(oid) AS definition + FROM pg_constraint WHERE conrelid = 'idempotency_keys'::regclass + ORDER BY conname; +SELECT count(*) AS messages FROM messages; +SELECT count(*) AS idempotency_rows FROM idempotency_keys; +SHOW max_connections; +SELECT count(*) AS connections FROM pg_stat_activity; diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 0000000000000000000000000000000000000000..9155c94f2bba3373ba257ce54467ccbf29946ffc GIT binary patch literal 174 zcmW-bF%H5o5Co@2;tzfS4INY|(?#M12Ae2S5>QBZK4ffJ^6lP@_U`}dXt?<<1V$ov z&Z;+?YGmM{Yv^dLA6;gaTAaMN+8gvweRR57H<{IckqmZclC`fys&uc + +Fixed total API budget (2 CPU / 1G): 1 vs 2 vs 4 replicas +successful RPS + + +100.21 replica99.02 replica88.64 replica + \ No newline at end of file diff --git a/evidence/track1_growth.svg b/evidence/track1_growth.svg new file mode 100644 index 00000000..f8d8da16 --- /dev/null +++ b/evidence/track1_growth.svg @@ -0,0 +1,8 @@ + + +4 replicas: effect of per-replica resources +successful RPS + + +90.70.5 CPU200.71.0 CPU279.12.0 CPU + \ No newline at end of file diff --git a/evidence/track1_report.json b/evidence/track1_report.json new file mode 100644 index 00000000..f7b704e7 --- /dev/null +++ b/evidence/track1_report.json @@ -0,0 +1,575 @@ +{ + "fixed_total": [ + { + "profile": "1x2.0cpu_1g", + "replicas": 1, + "cpu_per_replica": "2.0", + "memory_per_replica": "1G", + "repetitions": 2, + "rps_median": 100.175, + "rps_min": 98.45, + "rps_max": 101.9, + "p95_ms_median": 308.635, + "errors_total": 0 + }, + { + "profile": "2x1.0cpu_512m", + "replicas": 2, + "cpu_per_replica": "1.0", + "memory_per_replica": "512M", + "repetitions": 2, + "rps_median": 99.05, + "rps_min": 95.15, + "rps_max": 102.95, + "p95_ms_median": 655.161, + "errors_total": 0 + }, + { + "profile": "4x0.5cpu_256m", + "replicas": 4, + "cpu_per_replica": "0.5", + "memory_per_replica": "256M", + "repetitions": 2, + "rps_median": 88.6, + "rps_min": 85.6, + "rps_max": 91.6, + "p95_ms_median": 1199.748, + "errors_total": 0 + } + ], + "growth": [ + { + "profile": "4x0.5cpu_256m", + "replicas": 4, + "cpu_per_replica": "0.5", + "memory_per_replica": "256M", + "repetitions": 2, + "rps_median": 90.675, + "rps_min": 89.65, + "rps_max": 91.7, + "p95_ms_median": 1205.082, + "errors_total": 0 + }, + { + "profile": "4x1.0cpu_512m", + "replicas": 4, + "cpu_per_replica": "1.0", + "memory_per_replica": "512M", + "repetitions": 2, + "rps_median": 200.725, + "rps_min": 199.0, + "rps_max": 202.45, + "p95_ms_median": 422.798, + "errors_total": 0 + }, + { + "profile": "4x2.0cpu_1g", + "replicas": 4, + "cpu_per_replica": "2.0", + "memory_per_replica": "1G", + "repetitions": 2, + "rps_median": 279.1, + "rps_min": 277.9, + "rps_max": 280.3, + "p95_ms_median": 214.816, + "errors_total": 0 + } + ], + "runs": [ + { + "label": "1x2.0cpu_1g_r1", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 2038, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 101.9, + "successful_latency_ms": { + "p50": 228.683, + "p95": 303.852, + "p99": 341.608 + }, + "instances": { + "7a402f4155a4": 2038 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "1x2.0cpu_1g", + "replicas": 1, + "cpu": "2.0", + "mem": "1G", + "concurrency": 24 + }, + "repetition": 1, + "metrics_file": "evidence\\track1\\metrics_1x2.0cpu_1g_r1.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 169.3, + "api_cpu_percent_max": 188.95, + "postgres_cpu_percent_max": 32.8, + "lb_cpu_percent_max": 4.54, + "postgres_connections_max": 11, + "postgres_active_max": 1, + "postgres_waiting_max": 0 + } + }, + { + "label": "1x2.0cpu_1g_r2", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 1969, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 98.45, + "successful_latency_ms": { + "p50": 237.575, + "p95": 313.417, + "p99": 367.208 + }, + "instances": { + "7a402f4155a4": 1969 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "1x2.0cpu_1g", + "replicas": 1, + "cpu": "2.0", + "mem": "1G", + "concurrency": 24 + }, + "repetition": 2, + "metrics_file": "evidence\\track1\\metrics_1x2.0cpu_1g_r2.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 169.49, + "api_cpu_percent_max": 181.64, + "postgres_cpu_percent_max": 29.27, + "lb_cpu_percent_max": 4.29, + "postgres_connections_max": 11, + "postgres_active_max": 3, + "postgres_waiting_max": 0 + } + }, + { + "label": "2x1.0cpu_512m_r1", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 2059, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 102.95, + "successful_latency_ms": { + "p50": 250.436, + "p95": 628.531, + "p99": 747.701 + }, + "instances": { + "4192c1dc1495": 1030, + "b1b9281ba7d5": 1029 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "2x1.0cpu_512m", + "replicas": 2, + "cpu": "1.0", + "mem": "512M", + "concurrency": 24 + }, + "repetition": 1, + "metrics_file": "evidence\\track1\\metrics_2x1.0cpu_512m_r1.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 154.57, + "api_cpu_percent_max": 202.63, + "postgres_cpu_percent_max": 40.47, + "lb_cpu_percent_max": 5.04, + "postgres_connections_max": 21, + "postgres_active_max": 2, + "postgres_waiting_max": 0 + } + }, + { + "label": "2x1.0cpu_512m_r2", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 1903, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 95.15, + "successful_latency_ms": { + "p50": 268.314, + "p95": 681.792, + "p99": 778.125 + }, + "instances": { + "4192c1dc1495": 951, + "b1b9281ba7d5": 952 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "2x1.0cpu_512m", + "replicas": 2, + "cpu": "1.0", + "mem": "512M", + "concurrency": 24 + }, + "repetition": 2, + "metrics_file": "evidence\\track1\\metrics_2x1.0cpu_512m_r2.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 173.27, + "api_cpu_percent_max": 202.01, + "postgres_cpu_percent_max": 35.54, + "lb_cpu_percent_max": 5.54, + "postgres_connections_max": 21, + "postgres_active_max": 2, + "postgres_waiting_max": 0 + } + }, + { + "label": "4x0.5cpu_256m_r1", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 1712, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 85.6, + "successful_latency_ms": { + "p50": 54.575, + "p95": 1227.076, + "p99": 1441.681 + }, + "instances": { + "31647cf38f06": 428, + "366fd6ad531d": 427, + "5e8eec640f41": 429, + "b454ab735e17": 428 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "4x0.5cpu_256m", + "replicas": 4, + "cpu": "0.5", + "mem": "256M", + "concurrency": 24 + }, + "repetition": 1, + "metrics_file": "evidence\\track1\\metrics_4x0.5cpu_256m_r1.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 117.26, + "api_cpu_percent_max": 145.59, + "postgres_cpu_percent_max": 31.42, + "lb_cpu_percent_max": 4.97, + "postgres_connections_max": 36, + "postgres_active_max": 1, + "postgres_waiting_max": 0 + } + }, + { + "label": "4x0.5cpu_256m_r2", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 1832, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 91.6, + "successful_latency_ms": { + "p50": 54.465, + "p95": 1172.42, + "p99": 1391.664 + }, + "instances": { + "31647cf38f06": 458, + "366fd6ad531d": 457, + "5e8eec640f41": 458, + "b454ab735e17": 459 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "4x0.5cpu_256m", + "replicas": 4, + "cpu": "0.5", + "mem": "256M", + "concurrency": 24 + }, + "repetition": 2, + "metrics_file": "evidence\\track1\\metrics_4x0.5cpu_256m_r2.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 102.6, + "api_cpu_percent_max": 128.44, + "postgres_cpu_percent_max": 28.98, + "lb_cpu_percent_max": 5.56, + "postgres_connections_max": 36, + "postgres_active_max": 1, + "postgres_waiting_max": 0 + } + }, + { + "label": "4x0.5cpu_256m_r1", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 1793, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 89.65, + "successful_latency_ms": { + "p50": 54.121, + "p95": 1214.111, + "p99": 1402.774 + }, + "instances": { + "31647cf38f06": 447, + "366fd6ad531d": 448, + "5e8eec640f41": 448, + "b454ab735e17": 450 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "4x0.5cpu_256m", + "replicas": 4, + "cpu": "0.5", + "mem": "256M", + "concurrency": 24 + }, + "repetition": 1, + "metrics_file": "evidence\\track1\\metrics_4x0.5cpu_256m_r1.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 117.26, + "api_cpu_percent_max": 145.59, + "postgres_cpu_percent_max": 31.42, + "lb_cpu_percent_max": 4.97, + "postgres_connections_max": 36, + "postgres_active_max": 1, + "postgres_waiting_max": 0 + } + }, + { + "label": "4x0.5cpu_256m_r2", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 1834, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 91.7, + "successful_latency_ms": { + "p50": 54.092, + "p95": 1196.053, + "p99": 1393.438 + }, + "instances": { + "31647cf38f06": 459, + "366fd6ad531d": 459, + "5e8eec640f41": 458, + "b454ab735e17": 458 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "4x0.5cpu_256m", + "replicas": 4, + "cpu": "0.5", + "mem": "256M", + "concurrency": 24 + }, + "repetition": 2, + "metrics_file": "evidence\\track1\\metrics_4x0.5cpu_256m_r2.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 102.6, + "api_cpu_percent_max": 128.44, + "postgres_cpu_percent_max": 28.98, + "lb_cpu_percent_max": 5.56, + "postgres_connections_max": 36, + "postgres_active_max": 1, + "postgres_waiting_max": 0 + } + }, + { + "label": "4x1.0cpu_512m_r1", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 4049, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 202.45, + "successful_latency_ms": { + "p50": 54.105, + "p95": 434.635, + "p99": 584.07 + }, + "instances": { + "8fa1148dad80": 1012, + "a0f4177ca995": 1012, + "c05c147b6fd6": 1013, + "d407b1c5f7da": 1012 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "4x1.0cpu_512m", + "replicas": 4, + "cpu": "1.0", + "mem": "512M", + "concurrency": 24 + }, + "repetition": 1, + "metrics_file": "evidence\\track1\\metrics_4x1.0cpu_512m_r1.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 256.84, + "api_cpu_percent_max": 335.58, + "postgres_cpu_percent_max": 101.78, + "lb_cpu_percent_max": 10.55, + "postgres_connections_max": 36, + "postgres_active_max": 2, + "postgres_waiting_max": 0 + } + }, + { + "label": "4x1.0cpu_512m_r2", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 3980, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 199.0, + "successful_latency_ms": { + "p50": 54.843, + "p95": 410.962, + "p99": 581.582 + }, + "instances": { + "8fa1148dad80": 996, + "a0f4177ca995": 995, + "c05c147b6fd6": 995, + "d407b1c5f7da": 994 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "4x1.0cpu_512m", + "replicas": 4, + "cpu": "1.0", + "mem": "512M", + "concurrency": 24 + }, + "repetition": 2, + "metrics_file": "evidence\\track1\\metrics_4x1.0cpu_512m_r2.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 266.73, + "api_cpu_percent_max": 336.77, + "postgres_cpu_percent_max": 74.69, + "lb_cpu_percent_max": 9.84, + "postgres_connections_max": 41, + "postgres_active_max": 2, + "postgres_waiting_max": 0 + } + }, + { + "label": "4x2.0cpu_1g_r1", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 5558, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 277.9, + "successful_latency_ms": { + "p50": 64.486, + "p95": 216.9, + "p99": 285.827 + }, + "instances": { + "2a0a9d8f3c8f": 1390, + "3318d5ed950d": 1389, + "d160639a0384": 1391, + "fc4afe6a9bb3": 1388 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "4x2.0cpu_1g", + "replicas": 4, + "cpu": "2.0", + "mem": "1G", + "concurrency": 24 + }, + "repetition": 1, + "metrics_file": "evidence\\track1\\metrics_4x2.0cpu_1g_r1.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 380.51, + "api_cpu_percent_max": 399.93, + "postgres_cpu_percent_max": 106.4, + "lb_cpu_percent_max": 15.19, + "postgres_connections_max": 41, + "postgres_active_max": 6, + "postgres_waiting_max": 0 + } + }, + { + "label": "4x2.0cpu_1g_r2", + "base_url": "http://localhost:18081", + "concurrency": 24, + "warmup_seconds": 2.0, + "duration_seconds": 20.0, + "successful_requests": 5606, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 280.3, + "successful_latency_ms": { + "p50": 64.3, + "p95": 212.732, + "p99": 306.857 + }, + "instances": { + "2a0a9d8f3c8f": 1402, + "3318d5ed950d": 1402, + "d160639a0384": 1401, + "fc4afe6a9bb3": 1401 + }, + "note": "closed-loop client on the same host; latency covers successes only; compare runs under the same client and host conditions", + "profile": { + "name": "4x2.0cpu_1g", + "replicas": 4, + "cpu": "2.0", + "mem": "1G", + "concurrency": 24 + }, + "repetition": 2, + "metrics_file": "evidence\\track1\\metrics_4x2.0cpu_1g_r2.json", + "metrics": { + "samples": 5, + "api_cpu_percent_avg": 438.81, + "api_cpu_percent_max": 526.87, + "postgres_cpu_percent_max": 106.65, + "lb_cpu_percent_max": 16.2, + "postgres_connections_max": 41, + "postgres_active_max": 3, + "postgres_waiting_max": 0 + } + } + ], + "note": "Closed-loop client on the same Docker host. RPS is HTTP 201 throughput, not a COMMIT counter; p95 covers successful requests only. Two repetitions per profile; medians are reported." +} diff --git a/evidence/track1_report.txt b/evidence/track1_report.txt new file mode 100644 index 00000000..ea448fe2 --- /dev/null +++ b/evidence/track1_report.txt @@ -0,0 +1,34 @@ +Track 1. Cost of scaling (closed-loop POST /messages) +Fixed total API budget: 1x2.0/1G, 2x1.0/512M, 4x0.5/256M +Profile reps RPS median (min..max) p95 ms median errors +1x2.0cpu_1g 2 100.2 (98.5..101.9) 308.6 0 +2x1.0cpu_512m 2 99.0 (95.2..103.0) 655.2 0 +4x0.5cpu_256m 2 88.6 (85.6..91.6) 1199.7 0 + +Growth series: 4 replicas, per-replica CPU/RAM +Profile reps RPS median (min..max) p95 ms median errors +4x0.5cpu_256m 2 90.7 (89.7..91.7) 1205.1 0 +4x1.0cpu_512m 2 200.7 (199.0..202.4) 422.8 0 +4x2.0cpu_1g 2 279.1 (277.9..280.3) 214.8 0 + +Resource samples (max over sampled runs): +1x2.0cpu_1g api_cpu=188.95% pg_cpu=32.8% lb_cpu=4.54% pg_conn=11 pg_active=1 pg_wait=0 +1x2.0cpu_1g api_cpu=181.64% pg_cpu=29.27% lb_cpu=4.29% pg_conn=11 pg_active=3 pg_wait=0 +2x1.0cpu_512m api_cpu=202.63% pg_cpu=40.47% lb_cpu=5.04% pg_conn=21 pg_active=2 pg_wait=0 +2x1.0cpu_512m api_cpu=202.01% pg_cpu=35.54% lb_cpu=5.54% pg_conn=21 pg_active=2 pg_wait=0 +4x0.5cpu_256m api_cpu=145.59% pg_cpu=31.42% lb_cpu=4.97% pg_conn=36 pg_active=1 pg_wait=0 +4x0.5cpu_256m api_cpu=128.44% pg_cpu=28.98% lb_cpu=5.56% pg_conn=36 pg_active=1 pg_wait=0 +4x0.5cpu_256m api_cpu=145.59% pg_cpu=31.42% lb_cpu=4.97% pg_conn=36 pg_active=1 pg_wait=0 +4x0.5cpu_256m api_cpu=128.44% pg_cpu=28.98% lb_cpu=5.56% pg_conn=36 pg_active=1 pg_wait=0 +4x1.0cpu_512m api_cpu=335.58% pg_cpu=101.78% lb_cpu=10.55% pg_conn=36 pg_active=2 pg_wait=0 +4x1.0cpu_512m api_cpu=336.77% pg_cpu=74.69% lb_cpu=9.84% pg_conn=41 pg_active=2 pg_wait=0 +4x2.0cpu_1g api_cpu=399.93% pg_cpu=106.4% lb_cpu=15.19% pg_conn=41 pg_active=6 pg_wait=0 +4x2.0cpu_1g api_cpu=526.87% pg_cpu=106.65% lb_cpu=16.2% pg_conn=41 pg_active=3 pg_wait=0 + +Interpretation: +- At a fixed total 2 CPU budget, splitting the budget across replicas does not + increase throughput; the per-request CPU cost dominates and p95 grows. +- In the growth series, 4 replicas improve from ~90 to ~280 RPS as total API CPU + grows from 2 to 8 cores, then the curve flattens: PostgreSQL (1 CPU) and the + write/idempotency transaction become the shared bottleneck. +- This is a local comparative experiment, not a production capacity guarantee. diff --git a/evidence/track1_run.txt b/evidence/track1_run.txt new file mode 100644 index 0000000000000000000000000000000000000000..91e08dbbc3791558262fc00d42c04c3b5fe1cb1c GIT binary patch literal 1176 zcmb`HOH0E*6ot=P@IT}aSd!6pp)09t5yf3V#yZrfX-bm%`19&_M-XG7HK~Mo+><+J z4s#zL@0YsPxe_&+$?Hjl7Mf#cdX>{iDfm(=-GCTgD_{q;c-pA&H}8Gz>3_J~MlOf0 ztfOm;?Nkob)}L>)z9aOd=o^2(n`1v2tgk;`SKpk7ReB*-_q&LcD+t6xQ*Y$U%FHILZ)fL|{5p0R4C$}DTK;9?hm5*3K-X-7_$dWp?3Jp2|3wowb z?^qZ750PccoKyJ?cFmk~gVny}N{w~KI-}~#c&d#aC5$U}1=W@^CY (?, ?) +-- ORDER BY created_at, id LIMIT ? +-- It supports the range scan without reading the whole chat history. +CREATE INDEX IF NOT EXISTS messages_chat_created_at_id_idx + ON messages (chat_id, created_at, id); diff --git a/migrations/002_lab3.sql b/migrations/002_lab3.sql new file mode 100644 index 00000000..479026b2 --- /dev/null +++ b/migrations/002_lab3.sql @@ -0,0 +1,29 @@ +-- Laboratory 3: shared idempotency for POST messages. +-- +-- Scope is exactly (user_id, method, path, key): the same key may be reused by +-- another user or another chat independently. The message row and the stored +-- response are written in one transaction, so a transient failure never leaves +-- a "completed" key without its side effect (and vice versa). + +CREATE TABLE IF NOT EXISTS idempotency_keys ( + id bigserial PRIMARY KEY, + user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE, + method text NOT NULL, + path text NOT NULL, + key text NOT NULL, + request_hash text NOT NULL, + status_code integer, + response_body jsonb, + message_id uuid REFERENCES messages(id) ON DELETE CASCADE, + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + expires_at timestamptz NOT NULL, + CONSTRAINT idempotency_keys_scope_key UNIQUE (user_id, method, path, key), + CONSTRAINT idempotency_keys_key_format + CHECK (key ~ '^[A-Za-z0-9._:-]{1,128}$'), + CONSTRAINT idempotency_keys_method CHECK (method IN ('POST')) +); + +-- Expired rows are removed opportunistically by the API. This index keeps the +-- cleanup and expiry checks cheap without scanning the whole table. +CREATE INDEX IF NOT EXISTS idempotency_keys_expires_at_idx + ON idempotency_keys (expires_at); diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..e47067e0 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +Flask==3.1.0 +gunicorn==23.0.0 +psycopg[binary,pool]==3.2.3 +redis==5.2.1 +argon2-cffi==23.1.0 diff --git a/scripts/restart.cmd b/scripts/restart.cmd new file mode 100644 index 00000000..d24ce67b --- /dev/null +++ b/scripts/restart.cmd @@ -0,0 +1,6 @@ +@echo off +rem Restart API replicas, LB and state stores; named volumes are preserved. +setlocal +cd /d "%~dp0.." +docker compose --env-file .env restart postgres redis api lb +exit /b %ERRORLEVEL% diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..667a8bc1 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,6 @@ +#!/bin/sh +# Restart the API replicas, the load balancer and every state store while +# keeping named volumes. Never run "down -v", flush Redis or re-seed data. +set -eu +cd "$(dirname "$0")/.." +exec docker compose --env-file .env restart postgres redis api lb diff --git a/scripts/stop-one.cmd b/scripts/stop-one.cmd new file mode 100644 index 00000000..18cb4650 --- /dev/null +++ b/scripts/stop-one.cmd @@ -0,0 +1,19 @@ +@echo off +rem Stop exactly ONE API replica identified by TARGET_INSTANCE_ID. +rem The container hostname is the X-Instance-Id value used by the API. +setlocal enabledelayedexpansion +cd /d "%~dp0.." +if "%TARGET_INSTANCE_ID%"=="" ( + echo TARGET_INSTANCE_ID is required 1>&2 + exit /b 2 +) +for /f %%i in ('docker compose --env-file .env ps -q api') do ( + for /f %%h in ('docker inspect --format "{{.Config.Hostname}}" %%i') do ( + if "%%h"=="%TARGET_INSTANCE_ID%" ( + docker stop --time 1 %%i >nul + exit /b 0 + ) + ) +) +echo target API replica not found: %TARGET_INSTANCE_ID% 1>&2 +exit /b 1 diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..e9ccc98e --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,19 @@ +#!/bin/sh +# Stop exactly ONE API replica identified by the X-Instance-Id value supplied +# in TARGET_INSTANCE_ID. The container hostname is the instance id, so the +# mapping is deterministic and does not rely on container names. +# Leave the replica stopped; restore it explicitly after the test. +set -eu +cd "$(dirname "$0")/.." +target="${TARGET_INSTANCE_ID:?test provides target API instance alias}" + +for id in $(docker compose --env-file .env ps -q api); do + host=$(docker inspect --format '{{.Config.Hostname}}' "$id") + if [ "$host" = "$target" ]; then + docker stop --time 1 "$id" >/dev/null + exit 0 + fi +done + +printf '%s\n' "target API replica not found: $target" >&2 +exit 1 diff --git a/student-tests/README.md b/student-tests/README.md new file mode 100644 index 00000000..a56c6016 --- /dev/null +++ b/student-tests/README.md @@ -0,0 +1,56 @@ +# Студенческие проверки уровня 4 и трека 5 + +Все проверки, кроме `rollback_chat.py` и `explain_history.py`, запускаются на +хосте и обращаются к API по HTTP через LB. Две проверки используют `psycopg` и +запускаются внутри контейнера `api`, где зависимость уже установлена. + +```sh +# 1. Негативная аутентификация и logout +python student-tests/auth_negative.py --base-url http://localhost:8080 + +# 2. Гонка регистрации одного username +python student-tests/race_username.py --base-url http://localhost:8080 --workers 8 + +# 3. Откат составной операции (внутри контейнера) +docker compose exec -T api python student-tests/rollback_chat.py + +# 4. EXPLAIN на 10 000 сообщений (внутри контейнера) +docker compose exec -T api python student-tests/explain_history.py \ + --output /tmp/explain_history.txt + +# 5. Отказы Redis и PostgreSQL (с хоста; управляет docker compose) +python student-tests/fault_matrix.py --base-url http://localhost:8080 + +# 6. Истечение сессии: API должен быть запущен с коротким TTL +# SESSION_TTL_SECONDS=2 docker compose up -d --no-deps api +python student-tests/expiry.py --base-url http://localhost:8080 --wait 4 + +# 7. Одна сессия обслуживается несколькими репликами +python student-tests/instance_routing.py --base-url http://localhost:8080 + +# 8. Конкурентная идемпотентность через разные реплики +python student-tests/idempotency_race.py --base-url http://localhost:8080 --workers 24 + +# 9. Идемпотентность переживает полный рестарт стека +python student-tests/idempotency_persistence.py --base-url http://localhost:8080 \ + --restart-script scripts/restart.sh + +# 10. Поочерёдная остановка каждой реплики с метриками +python student-tests/failover_matrix.py --base-url http://localhost:8080 + +# 11. Поочерёдная замена (rolling update) под нагрузкой +python student-tests/rolling_update.py --base-url http://localhost:8080 + +# 12. Трек 5: 1/2/4 реплики при фиксированном бюджете и рост ресурсов +python student-tests/track1_experiment.py --base-url http://localhost:8080 +python student-tests/track1_report.py +``` + +`fault_matrix.py` останавливает `redis`/`postgres` и обязательно запускает их +обратно в `finally`. Он проверяет только ограниченные `503`, отсутствие +доверенного анонимного доступа и сохранность сессии после рестарта Redis с AOF. + +`failover_matrix.py`, `rolling_update.py` и `track1_experiment.py` управляют +Docker-контейнерами. Они не удаляют volumes и не печатают токены/пароли. +`track1_experiment.py` временно меняет `API_REPLICAS`/лимиты и восстанавливает +профиль 2×1.0 CPU/512M в `finally`. diff --git a/student-tests/auth_negative.py b/student-tests/auth_negative.py new file mode 100644 index 00000000..3ae34f04 --- /dev/null +++ b/student-tests/auth_negative.py @@ -0,0 +1,58 @@ +#!/usr/bin/env python3 +"""Wrong password, Basic-on-business-endpoint, logout and reuse checks.""" +from __future__ import annotations + +import argparse +import base64 + +from common import HttpClient, assert_status, error_code + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + args = parser.parse_args() + client = HttpClient(args.base_url) + user, registration = client.register() + + wrong = base64.b64encode( + (registration["username"] + ":wrong-password-value").encode("utf-8") + ).decode("ascii") + status, headers, payload, _ = client.call( + "POST", "/api/v1/auth/sessions", headers={"Authorization": "Basic " + wrong} + ) + assert_status(status, 401, "wrong password") + assert error_code(payload) == "unauthorized" + assert headers.get("WWW-Authenticate", "").lower().startswith("basic") + + good = base64.b64encode( + (registration["username"] + ":" + registration["password"]).encode("utf-8") + ).decode("ascii") + status, headers, _, _ = client.call( + "GET", "/api/v1/users/me", headers={"Authorization": "Basic " + good} + ) + assert_status(status, 401, "Basic on business endpoint") + assert headers.get("WWW-Authenticate", "").lower().startswith("bearer") + + session = client.login(registration) + token = session["token"] + status, _, me, _ = client.call("GET", "/api/v1/users/me", token=token) + assert_status(status, 200, "login") + assert me["id"] == user["id"] + + status, _, _, raw = client.call("DELETE", "/api/v1/auth/sessions/current", token=token) + assert_status(status, 204, "logout") + assert raw == b"", "204 must have an empty body" + + status, headers, payload, _ = client.call("GET", "/api/v1/users/me", token=token) + assert_status(status, 401, "token after logout") + assert error_code(payload) == "unauthorized" + assert headers.get("WWW-Authenticate", "").lower().startswith("bearer") + + status, _, _, _ = client.call("DELETE", "/api/v1/auth/sessions/current", token=token) + assert_status(status, 401, "second logout") + print("PASS: wrong password, Basic rejection, logout and token reuse checks") + + +if __name__ == "__main__": + main() diff --git a/student-tests/common.py b/student-tests/common.py new file mode 100644 index 00000000..bbb4761a --- /dev/null +++ b/student-tests/common.py @@ -0,0 +1,76 @@ +#!/usr/bin/env python3 +"""Small standard-library HTTP helpers for the student checks.""" +from __future__ import annotations + +import base64 +import json +import os +import uuid +import urllib.error +import urllib.request + +BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080").rstrip("/") + + +class HttpClient: + def __init__(self, base_url: str | None = None): + self.base = (base_url or BASE_URL).rstrip("/") + + def call(self, method: str, path: str, body=None, token: str | None = None, headers=None): + h = {"Accept": "application/json"} + data = None + if body is not None: + data = json.dumps(body, ensure_ascii=False).encode("utf-8") + h["Content-Type"] = "application/json" + if token: + h["Authorization"] = "Bearer " + token + h.update(headers or {}) + request = urllib.request.Request(self.base + path, data=data, headers=h, method=method) + try: + response = urllib.request.urlopen(request, timeout=10) + except urllib.error.HTTPError as error: + response = error + with response: + raw = response.read() + payload = None + if raw: + try: + payload = json.loads(raw) + except ValueError: + payload = None + return response.code, response.headers, payload, raw + + def register(self) -> tuple[dict, dict]: + suffix = uuid.uuid4().hex[:12] + registration = { + "username": "st_" + suffix, + "display_name": "Студент " + suffix, + "password": "T3st-" + uuid.uuid4().hex, + } + status, _headers, user, _raw = self.call("POST", "/api/v1/users", registration) + if status != 201: + raise AssertionError(f"registration failed: HTTP {status}") + return user, registration + + def login(self, registration: dict) -> dict: + credential = base64.b64encode( + (registration["username"] + ":" + registration["password"]).encode("utf-8") + ).decode("ascii") + status, _headers, session, _raw = self.call( + "POST", "/api/v1/auth/sessions", headers={"Authorization": "Basic " + credential} + ) + if status != 201: + raise AssertionError(f"login failed: HTTP {status}") + return session + + +def assert_status(actual: int, expected: int, label: str) -> None: + if actual != expected: + raise AssertionError(f"{label}: expected HTTP {expected}, received {actual}") + + +def error_code(payload) -> str | None: + if not isinstance(payload, dict): + return None + error = payload.get("error") + return error.get("code") if isinstance(error, dict) else None diff --git a/student-tests/expiry.py b/student-tests/expiry.py new file mode 100644 index 00000000..d48da0f6 --- /dev/null +++ b/student-tests/expiry.py @@ -0,0 +1,35 @@ +#!/usr/bin/env python3 +"""Expiry check: run against an API with SESSION_TTL_SECONDS=2 (or pass --wait).""" +from __future__ import annotations + +import argparse +import time + +from common import HttpClient, assert_status, error_code + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument("--wait", type=float, default=3.0) + args = parser.parse_args() + + client = HttpClient(args.base_url) + user, registration = client.register() + session = client.login(registration) + token = session["token"] + + status, headers, payload, _ = client.call("GET", "/api/v1/users/me", token=token) + assert_status(status, 200, "fresh session") + assert payload["id"] == user["id"], "wrong current user" + + time.sleep(args.wait) + status, headers, payload, _ = client.call("GET", "/api/v1/users/me", token=token) + assert_status(status, 401, "expired session") + assert error_code(payload) == "unauthorized", "expired session must be unauthorized" + assert headers.get("WWW-Authenticate", "").lower().startswith("bearer"), "missing Bearer challenge" + print("PASS: expired session is rejected with 401 and Bearer challenge") + + +if __name__ == "__main__": + main() diff --git a/student-tests/explain_history.py b/student-tests/explain_history.py new file mode 100644 index 00000000..d7c7df0b --- /dev/null +++ b/student-tests/explain_history.py @@ -0,0 +1,101 @@ +#!/usr/bin/env python3 +"""Create 10 000 synthetic messages and record EXPLAIN (ANALYZE, BUFFERS). + +Run inside the API container (psycopg is installed there): + docker compose exec -T api python student-tests/explain_history.py \ + --output /app/evidence/explain_history.txt + +The evidence directory is mounted read-only in the container, so the example +below is normally executed with a writable bind mount or copied out. +""" +from __future__ import annotations + +import argparse +import os +import uuid +from datetime import datetime, timezone +from pathlib import Path + +import psycopg + +MESSAGES = 10_000 + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--database-url", default=os.environ.get("DATABASE_URL")) + parser.add_argument("--output", default="evidence/explain_history.txt") + parser.add_argument("--messages", type=int, default=MESSAGES) + args = parser.parse_args() + if not args.database_url: + raise SystemExit("DATABASE_URL is required") + + tag = uuid.uuid4().hex[:10] + user_id = uuid.uuid4() + chat_id = uuid.uuid4() + with psycopg.connect(args.database_url) as conn: + conn.execute( + "INSERT INTO users (id, username, display_name, password_hash) VALUES (%s, %s, %s, %s)", + (user_id, "perf_" + tag, "Performance synthetic", "not-a-real-password-hash"), + ) + conn.execute("INSERT INTO chats (id, title) VALUES (%s, %s)", (chat_id, "perf-" + tag)) + conn.execute( + "INSERT INTO chat_members (chat_id, user_id) VALUES (%s, %s)", (chat_id, user_id) + ) + conn.execute( + """ + INSERT INTO messages (id, chat_id, sender_id, text, created_at) + SELECT gen_random_uuid(), %s, %s, 'synthetic message ' || g, + timestamptz '2026-01-01 00:00:00+00' + (g || ' milliseconds')::interval + FROM generate_series(1, %s) AS g + """, + (chat_id, user_id, args.messages), + ) + total = conn.execute( + "SELECT count(*) FROM messages WHERE chat_id = %s", (chat_id,) + ).fetchone()[0] + conn.execute("ANALYZE messages") + cursor = conn.execute( + """ + SELECT created_at, id FROM messages + WHERE chat_id = %s ORDER BY created_at, id + OFFSET %s LIMIT 1 + """, + (chat_id, max(0, args.messages - 500)), + ).fetchone() + plan_rows = conn.execute( + """ + EXPLAIN (ANALYZE, BUFFERS) + 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 51 + """, + (chat_id, cursor[0], cursor[1]), + ).fetchall() + conn.commit() + + plan = "\n".join(row[0] for row in plan_rows) + if "messages_chat_created_at_id_idx" not in plan: + raise AssertionError("history query did not use the keyset index:\n" + plan) + if "Seq Scan" in plan: + raise AssertionError("history query performed a sequential scan:\n" + plan) + + header = ( + "# EXPLAIN (ANALYZE, BUFFERS) for keyset history pagination\n" + f"generated_at_utc: {datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')}\n" + f"messages_in_chat: {total}\n" + f"chat_id: {chat_id}\n" + "query: WHERE chat_id = ? AND (created_at, id) > (?, ?) " + "ORDER BY created_at, id LIMIT 51\n\n" + ) + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(header + plan + "\n", encoding="utf-8") + print(header + plan) + print(f"PASS: index used on {total} messages; evidence written to {output}") + + +if __name__ == "__main__": + main() diff --git a/student-tests/failover_matrix.py b/student-tests/failover_matrix.py new file mode 100644 index 00000000..82e8bcc3 --- /dev/null +++ b/student-tests/failover_matrix.py @@ -0,0 +1,206 @@ +#!/usr/bin/env python3 +"""Sequential one-replica-at-a-time failure matrix under continuous writes. + +For every running API replica: + * run a small closed-loop writer against the public LB; + * stop exactly that container (by X-Instance-Id -> hostname -> container id); + * keep writing, then restore the replica and wait until it serves again; + * record per-second successes/errors, first recovery and post-recovery RPS. + +This is an operator measurement, not a production HA proof. It never removes +volumes and never prints credentials or tokens. +""" +from __future__ import annotations + +import argparse +import json +import subprocess +import threading +import time +import uuid +from collections import defaultdict +from pathlib import Path + +from common import HttpClient + +ROOT = Path(__file__).resolve().parents[1] + + +def compose(*args: str) -> str: + return subprocess.check_output( + ["docker", "compose", "--env-file", ".env", *args], + cwd=ROOT, + stderr=subprocess.STDOUT, + text=True, + ) + + +def api_containers() -> list[dict]: + ids = compose("ps", "-q", "api").split() + result = [] + for container_id in ids: + hostname = subprocess.check_output( + ["docker", "inspect", "--format", "{{.Config.Hostname}}", container_id], + text=True, + ).strip() + status = subprocess.check_output( + ["docker", "inspect", "--format", "{{.State.Status}}", container_id], + text=True, + ).strip() + if status == "running": + result.append({"id": container_id, "hostname": hostname}) + return result + + +def wait_instances(client: HttpClient, token: str, expected: int, timeout: float = 30) -> set[str]: + deadline = time.monotonic() + timeout + seen: set[str] = set() + while time.monotonic() < deadline: + try: + status, headers, _payload, _raw = client.call("GET", "/api/v1/users/me", token=token) + if status == 200: + seen.add(headers.get("X-Instance-Id", "")) + if len(seen) >= expected: + return seen + except OSError: + pass + time.sleep(0.25) + return seen + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument("--duration", type=float, default=16.0) + parser.add_argument("--workers", type=int, default=6) + parser.add_argument("--output", default="evidence/failover_matrix.json") + args = parser.parse_args() + + client = HttpClient(args.base_url) + user, registration = client.register() + session = client.login(registration) + token = session["token"] + status, _headers, chat, _raw = client.call( + "POST", + "/api/v1/chats", + body={"title": "Failover matrix", "member_ids": [user["id"]]}, + token=token, + ) + if status != 201: + raise AssertionError(f"chat creation failed: HTTP {status}") + + targets = api_containers() + if len(targets) < 2: + raise AssertionError("at least two running API replicas are required") + + report = { + "base_url": args.base_url, + "workers": args.workers, + "duration_seconds": args.duration, + "replicas_before": sorted(item["hostname"] for item in targets), + "runs": [], + } + + for target in targets: + stop_event = threading.Event() + lock = threading.Lock() + successes = defaultdict(int) + errors = defaultdict(int) + events: list[tuple[float, str]] = [] + started = time.monotonic() + stop_at = started + 2.0 + + def worker(worker_id: int) -> None: + local = HttpClient(args.base_url) + index = 0 + while not stop_event.is_set(): + index += 1 + key = uuid.uuid4().hex + body = {"text": f"matrix-{target['hostname'][:6]}-{worker_id}-{index}"} + try: + status, headers, _payload, _raw = local.call( + "POST", + f"/api/v1/chats/{chat['id']}/messages", + body=body, + token=token, + headers={"Idempotency-Key": key}, + ) + bucket = int(time.monotonic() - started) + with lock: + if status == 201: + successes[bucket] += 1 + events.append((time.monotonic(), headers.get("X-Instance-Id", ""))) + else: + errors[bucket] += 1 + except Exception: + bucket = int(time.monotonic() - started) + with lock: + errors[bucket] += 1 + time.sleep(0.005) + + threads = [threading.Thread(target=worker, args=(i,), daemon=True) for i in range(args.workers)] + for thread in threads: + thread.start() + + while time.monotonic() < stop_at: + time.sleep(0.05) + stop_time = time.monotonic() + subprocess.run( + ["docker", "stop", "--time", "1", target["id"]], + check=True, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + stopped_at = time.monotonic() + + # Keep writing for the rest of the window, then restore the replica. + time.sleep(max(0.0, args.duration - (time.monotonic() - started) - 4.0)) + restore_at = time.monotonic() + compose("start", "api") + seen_after = wait_instances(client, token, len(targets), timeout=30) + recovered_at = time.monotonic() + time.sleep(max(0.0, args.duration - (time.monotonic() - started))) + + stop_event.set() + for thread in threads: + thread.join(timeout=3) + + with lock: + after_stop = [event for event in events if event[0] > stopped_at] + first_after_stop = min((event[0] for event in after_stop), default=None) + target_during_outage = any( + event[1] == target["hostname"] for event in events if stopped_at < event[0] < restore_at + ) + target_after_restore = any( + event[1] == target["hostname"] for event in events if event[0] >= restore_at + ) + run = { + "target_instance": target["hostname"], + "target_container": target["id"][:12], + "success_by_second": [successes[i] for i in range(int(args.duration) + 1)], + "errors_by_second": [errors[i] for i in range(int(args.duration) + 1)], + "successes_total": sum(successes.values()), + "errors_total": sum(errors.values()), + "stop_seconds": round(stopped_at - started, 3), + "restore_seconds": round(restore_at - started, 3), + "first_write_after_stop_seconds": ( + round(first_after_stop - stopped_at, 3) if first_after_stop else None + ), + "target_served_during_outage": target_during_outage, + "target_present_after_restore": target_after_restore, + "instances_after_restore": sorted(item for item in seen_after if item), + } + report["runs"].append(run) + print(json.dumps(run, ensure_ascii=False)) + + # Give the LB a moment to see the restored replica before the next run. + time.sleep(1.0) + + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + print("PASS: sequential replica-stop matrix completed; evidence:", output) + + +if __name__ == "__main__": + main() diff --git a/student-tests/fault_matrix.py b/student-tests/fault_matrix.py new file mode 100644 index 00000000..32ddcb92 --- /dev/null +++ b/student-tests/fault_matrix.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python3 +"""Dependency-failure matrix: Redis and PostgreSQL outages must be bounded. + +The check uses the local Compose project. It stops one dependency, verifies +503 (never 200 and never a trusted anonymous request), starts it again, waits +for readiness and confirms the original bearer session still works after the +Redis restart (AOF persistence). +""" +from __future__ import annotations + +import argparse +import os +import subprocess +import time +from pathlib import Path + +from common import HttpClient, assert_status, error_code + +ROOT = Path(__file__).resolve().parents[1] + + +def compose(*args: str) -> None: + subprocess.run( + ["docker", "compose", "--env-file", ".env", *args], + cwd=ROOT, + check=True, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + + +def wait_ready(client: HttpClient, expected: int, seconds: float = 90) -> None: + deadline = time.monotonic() + seconds + last = None + while time.monotonic() < deadline: + try: + status, _, _, _ = client.call("GET", "/health/ready") + last = status + if status == expected: + return + except OSError: + last = "connection error" + time.sleep(0.5) + raise AssertionError(f"readiness did not become {expected}; last={last}") + + +def wait_authenticated(client: HttpClient, token: str, seconds: float = 30) -> float: + """Wait until every LB-routed request can use the existing token again. + + A replica may still be reconnecting its pool or resolving the restarted + database for a few seconds after the first readiness=200. This is a + bounded recovery window; the session and data are not lost. + """ + started = time.monotonic() + deadline = started + seconds + last = None + while time.monotonic() < deadline: + try: + status, _, me, _ = client.call("GET", "/api/v1/users/me", token=token) + last = status + if status == 200 and me: + return round(time.monotonic() - started, 2) + except OSError: + last = "connection error" + time.sleep(0.25) + raise AssertionError(f"authenticated request did not recover; last={last}") + + +def expect_503(client: HttpClient, path: str, token: str | None, label: str) -> None: + status, _headers, payload, _raw = client.call("GET", path, token=token) + if status != 503: + raise AssertionError(f"{label}: expected 503, received {status}") + if error_code(payload) != "unavailable": + raise AssertionError(f"{label}: expected unavailable error code") + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + args = parser.parse_args() + client = HttpClient(args.base_url) + user, registration = client.register() + session = client.login(registration) + token = session["token"] + + results = [] + try: + compose("stop", "redis") + expect_503(client, "/health/ready", None, "Redis down readiness") + expect_503(client, "/api/v1/users/me", token, "Redis down authenticated request") + results.append("redis down: readiness=503, bearer request=503") + started = time.monotonic() + compose("start", "redis") + wait_ready(client, 200) + redis_recovery = round(time.monotonic() - started, 2) + auth_recovery = wait_authenticated(client, token) + results.append( + f"redis up: readiness=200 in {redis_recovery}s, " + f"same token=200 in {auth_recovery}s (AOF persistence)" + ) + + compose("stop", "postgres") + time.sleep(1) + expect_503(client, "/health/ready", None, "PostgreSQL down readiness") + expect_503(client, "/api/v1/users/me", token, "PostgreSQL down authenticated request") + results.append("postgres down: readiness=503, bearer request=503") + started = time.monotonic() + compose("start", "postgres") + wait_ready(client, 200) + postgres_recovery = round(time.monotonic() - started, 2) + auth_recovery = wait_authenticated(client, token) + results.append( + f"postgres up: readiness=200 in {postgres_recovery}s, " + f"same token=200 in {auth_recovery}s" + ) + finally: + compose("start", "redis") + compose("start", "postgres") + + for line in results: + print("OBSERVED:", line) + print("PASS: dependency loss produced only bounded 503 responses; no anonymous trust") + + +if __name__ == "__main__": + main() diff --git a/student-tests/idempotency_persistence.py b/student-tests/idempotency_persistence.py new file mode 100644 index 00000000..d3e8f816 --- /dev/null +++ b/student-tests/idempotency_persistence.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +"""Idempotency state must survive a full API/PostgreSQL/Redis restart.""" +from __future__ import annotations + +import argparse +import os +import subprocess +import sys +import time +import uuid +from pathlib import Path + +from common import HttpClient, assert_status + +ROOT = Path(__file__).resolve().parents[1] + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument( + "--restart-script", + default="scripts/restart.cmd" if os.name == "nt" else "scripts/restart.sh", + ) + args = parser.parse_args() + script = (ROOT / args.restart_script).resolve() + if not script.is_file(): + raise SystemExit(f"restart script not found: {script}") + + client = HttpClient(args.base_url) + user, registration = client.register() + session = client.login(registration) + token = session["token"] + status, _headers, chat, _raw = client.call( + "POST", + "/api/v1/chats", + body={"title": "Idempotency persistence", "member_ids": [user["id"]]}, + token=token, + ) + assert_status(status, 201, "chat") + key = uuid.uuid4().hex + text = "persist replay " + uuid.uuid4().hex + status, _headers, first, _raw = client.call( + "POST", + f"/api/v1/chats/{chat['id']}/messages", + body={"text": text}, + token=token, + headers={"Idempotency-Key": key}, + ) + assert_status(status, 201, "first message") + + subprocess.run([str(script)], cwd=ROOT, check=True, stdout=subprocess.DEVNULL) + deadline = time.monotonic() + 90 + while True: + try: + status, _headers, _payload, _raw = client.call("GET", "/health/ready") + if status == 200: + break + except OSError: + pass + if time.monotonic() > deadline: + raise AssertionError("stack did not become ready after restart") + time.sleep(0.5) + + status, _headers, replay, _raw = client.call( + "POST", + f"/api/v1/chats/{chat['id']}/messages", + body={"text": text}, + token=token, + headers={"Idempotency-Key": key}, + ) + assert_status(status, 201, "replay after restart") + if replay != first: + raise AssertionError("replay after restart returned a different Message") + + status, _headers, page, _raw = client.call( + "GET", f"/api/v1/chats/{chat['id']}/messages?limit=100", token=token + ) + assert_status(status, 200, "history") + copies = [item for item in page["items"] if item["text"] == text] + if len(copies) != 1: + raise AssertionError(f"history contains {len(copies)} copies after restart") + + print("PASS: same Idempotency-Key returned the same Message after full restart") + + +if __name__ == "__main__": + main() diff --git a/student-tests/idempotency_race.py b/student-tests/idempotency_race.py new file mode 100644 index 00000000..a67f7d07 --- /dev/null +++ b/student-tests/idempotency_race.py @@ -0,0 +1,124 @@ +#!/usr/bin/env python3 +"""Concurrent idempotency check through the public load balancer. + +The same Idempotency-Key is sent from many threads at once; exactly one message +must be created and every successful response must carry the same Message. The +check also covers different-body conflict, missing/invalid key, and independent +scopes for another user and another chat. +""" +from __future__ import annotations + +import argparse +import uuid +from concurrent.futures import ThreadPoolExecutor + +from common import HttpClient, assert_status, error_code + + +def chat_for(client: HttpClient, token: str, members: list[str], title: str) -> dict: + status, _headers, chat, _raw = client.call( + "POST", + "/api/v1/chats", + body={"title": title, "member_ids": members}, + token=token, + ) + assert_status(status, 201, "create chat") + return chat + + +def message(client: HttpClient, token: str, chat_id: str, text: str, key: str | None): + headers = {"Idempotency-Key": key} if key is not None else {} + return client.call( + "POST", + f"/api/v1/chats/{chat_id}/messages", + body={"text": text}, + token=token, + headers=headers, + ) + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument("--workers", type=int, default=24) + args = parser.parse_args() + + client = HttpClient(args.base_url) + alice, alice_registration = client.register() + alice_session = client.login(alice_registration) + alice_token = alice_session["token"] + bob, bob_registration = client.register() + bob_session = client.login(bob_registration) + bob_token = bob_session["token"] + + chat = chat_for(client, alice_token, [alice["id"], bob["id"]], "Idempotency race") + key = uuid.uuid4().hex + text = "concurrent replay " + uuid.uuid4().hex + + def send(_index: int): + return message(client, alice_token, chat["id"], text, key) + + with ThreadPoolExecutor(max_workers=args.workers) as executor: + results = list(executor.map(send, range(args.workers))) + + statuses = [status for status, _headers, _payload, _raw in results] + if statuses != [201] * args.workers: + raise AssertionError(f"concurrent replay statuses: {statuses}") + + ids = {payload["id"] for _status, _headers, payload, _raw in results} + if len(ids) != 1: + raise AssertionError(f"concurrent replay created {len(ids)} different messages") + + instances = {headers.get("X-Instance-Id") for _status, headers, _payload, _raw in results} + if len(instances) < 2: + raise AssertionError("concurrent replay did not cross at least two replicas") + + status, _headers, page, _raw = client.call( + "GET", f"/api/v1/chats/{chat['id']}/messages?limit=100", token=bob_token + ) + assert_status(status, 200, "history") + matching = [item for item in page["items"] if item["text"] == text] + if len(matching) != 1: + raise AssertionError(f"history contains {len(matching)} copies of the replayed message") + + status, _headers, payload, _raw = message( + client, alice_token, chat["id"], "different body", key + ) + if status != 409 or error_code(payload) != "conflict": + raise AssertionError(f"same key with another body: expected 409 conflict, got {status}") + + status, _headers, payload, _raw = message(client, alice_token, chat["id"], "no key", None) + if status != 400 or error_code(payload) != "invalid_request": + raise AssertionError(f"missing key: expected 400 invalid_request, got {status}") + + status, _headers, payload, _raw = message( + client, alice_token, chat["id"], "bad key", "bad key with spaces" + ) + if status != 400 or error_code(payload) != "invalid_request": + raise AssertionError(f"invalid key: expected 400 invalid_request, got {status}") + + # Same key, same body, different user: independent scope. + status, _headers, bob_message, _raw = message( + client, bob_token, chat["id"], text, key + ) + if status != 201 or bob_message["id"] in ids or bob_message["sender_id"] != bob["id"]: + raise AssertionError("another user's identical key was not independent") + + # Same key, same user, different chat: independent scope. + second_chat = chat_for(client, alice_token, [alice["id"], bob["id"]], "Second chat") + status, _headers, other_chat_message, _raw = message( + client, alice_token, second_chat["id"], text, key + ) + if status != 201 or other_chat_message["id"] in ids: + raise AssertionError("same key in another chat was not independent") + + print( + "OBSERVED: " + f"{args.workers} concurrent replays -> one message id; " + f"{len(instances)} replicas; 409 different body; 400 missing/invalid key" + ) + print("PASS: shared idempotency is exactly-once across API replicas") + + +if __name__ == "__main__": + main() diff --git a/student-tests/instance_routing.py b/student-tests/instance_routing.py new file mode 100644 index 00000000..e95e6e79 --- /dev/null +++ b/student-tests/instance_routing.py @@ -0,0 +1,37 @@ +#!/usr/bin/env python3 +"""Verify that the public LB spreads one session over at least two replicas.""" +from __future__ import annotations + +import argparse +from common import HttpClient, assert_status + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument("--requests", type=int, default=40) + args = parser.parse_args() + client = HttpClient(args.base_url) + user, registration = client.register() + session = client.login(registration) + token = session["token"] + + instances = set() + for _ in range(args.requests): + status, headers, payload, _raw = client.call("GET", "/api/v1/users/me", token=token) + assert_status(status, 200, "users/me") + instance = headers.get("X-Instance-Id") + if not instance: + raise AssertionError("missing X-Instance-Id") + instances.add(instance) + + if len(instances) < 2: + raise AssertionError( + "only one API instance observed; LB must spread requests, not use sticky sessions" + ) + print(f"OBSERVED: {len(instances)} API instances: {', '.join(sorted(instances))}") + print("PASS: one bearer session is served by multiple replicas without re-login") + + +if __name__ == "__main__": + main() diff --git a/student-tests/pool_settings.py b/student-tests/pool_settings.py new file mode 100644 index 00000000..59fae653 --- /dev/null +++ b/student-tests/pool_settings.py @@ -0,0 +1,39 @@ +#!/usr/bin/env python3 +"""Print the effective PostgreSQL timeouts and pool limits. + +Run inside the API container: + docker compose exec -T api python student-tests/pool_settings.py +""" +from __future__ import annotations + +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from app import db + + +def main() -> None: + db.pool().open(wait=True, timeout=5) + if not db.schema_is_current(): + raise SystemExit("schema is not current; run python -m app.migrate first") + with db.pool().connection() as conn: + statement = conn.execute("SHOW statement_timeout").fetchone()["statement_timeout"] + idle = conn.execute("SHOW idle_in_transaction_session_timeout").fetchone()[ + "idle_in_transaction_session_timeout" + ] + lock = conn.execute("SHOW lock_timeout").fetchone()["lock_timeout"] + stats = db.pool().get_stats() + print("statement_timeout =", statement) + print("idle_in_transaction_session_timeout =", idle) + print("lock_timeout =", lock) + print("pool_min =", stats["pool_min"]) + print("pool_max =", stats["pool_max"]) + print("pool_size =", stats["pool_size"]) + print("pool_available =", stats["pool_available"]) + print("PASS: bounded pool and SQL timeouts are active") + + +if __name__ == "__main__": + main() diff --git a/student-tests/race_username.py b/student-tests/race_username.py new file mode 100644 index 00000000..c2c30e6a --- /dev/null +++ b/student-tests/race_username.py @@ -0,0 +1,45 @@ +#!/usr/bin/env python3 +"""Concurrent registration with the same username: one 201, the rest 409.""" +from __future__ import annotations + +import argparse +import uuid +from concurrent.futures import ThreadPoolExecutor + +from common import HttpClient, assert_status, error_code + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument("--workers", type=int, default=8) + args = parser.parse_args() + client = HttpClient(args.base_url) + username = "race_" + uuid.uuid4().hex[:16] + body = { + "username": username, + "display_name": "Race candidate", + "password": "T3st-" + uuid.uuid4().hex, + } + + def register(_index: int): + status, _, payload, _ = client.call("POST", "/api/v1/users", body) + return status, error_code(payload) + + with ThreadPoolExecutor(max_workers=args.workers) as executor: + results = list(executor.map(register, range(args.workers))) + + statuses = [status for status, _code in results] + if statuses.count(201) != 1 or statuses.count(409) != args.workers - 1: + raise AssertionError(f"expected one 201 and {args.workers - 1} conflicts, got {statuses}") + for status, code in results: + if status == 409 and code != "conflict": + raise AssertionError("409 must carry conflict code") + + session = client.login(body) + assert session["user"]["username"] == username + print(f"PASS: {args.workers} concurrent registrations produced exactly one user and one session") + + +if __name__ == "__main__": + main() diff --git a/student-tests/rollback_chat.py b/student-tests/rollback_chat.py new file mode 100644 index 00000000..46804f21 --- /dev/null +++ b/student-tests/rollback_chat.py @@ -0,0 +1,86 @@ +#!/usr/bin/env python3 +"""Prove that a failure after the chat insert rolls back the whole chat. + +Run inside the API container (psycopg is installed there): + docker compose exec -T api python student-tests/rollback_chat.py + +A temporary trigger aborts the second chat_members insert. The API must +return a bounded 500 and leave no chat row, because chat + membership share +one transaction. +""" +from __future__ import annotations + +import argparse +import os +import uuid + +import psycopg + +from common import HttpClient, assert_status, error_code + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument("--database-url", default=os.environ.get("DATABASE_URL")) + args = parser.parse_args() + if not args.database_url: + raise SystemExit("DATABASE_URL is required") + + client = HttpClient(args.base_url) + actor, actor_registration = client.register() + victim, _victim_registration = client.register() + session = client.login(actor_registration) + token = session["token"] + + title = "rollback-" + uuid.uuid4().hex + function_name = "test_fail_member_" + uuid.uuid4().hex[:8] + victim_id = str(uuid.UUID(victim["id"])) + + with psycopg.connect(args.database_url, autocommit=True) as conn: + conn.execute( + f""" + CREATE FUNCTION {function_name}() RETURNS trigger AS $$ + BEGIN + IF NEW.user_id = '{victim_id}'::uuid THEN + RAISE EXCEPTION 'injected membership failure'; + END IF; + RETURN NEW; + END + $$ LANGUAGE plpgsql + """ + ) + conn.execute( + f"CREATE TRIGGER {function_name} BEFORE INSERT ON chat_members " + f"FOR EACH ROW EXECUTE FUNCTION {function_name}()" + ) + try: + status, _, payload, _ = client.call( + "POST", + "/api/v1/chats", + {"title": title, "member_ids": [actor["id"], victim["id"]]}, + token=token, + ) + assert_status(status, 500, "injected membership failure") + if error_code(payload) != "internal_error": + raise AssertionError("unexpected error code for injected failure") + rows = conn.execute("SELECT count(*) FROM chats WHERE title = %s", (title,)).fetchone() + if rows[0] != 0: + raise AssertionError("chat survived a failed membership transaction") + finally: + conn.execute(f"DROP TRIGGER IF EXISTS {function_name} ON chat_members") + conn.execute(f"DROP FUNCTION IF EXISTS {function_name}()") + + status, _, chat, _ = client.call( + "POST", + "/api/v1/chats", + {"title": title + "-ok", "member_ids": [actor["id"], victim["id"]]}, + token=token, + ) + assert_status(status, 201, "chat after trigger cleanup") + assert set(chat["member_ids"]) == {actor["id"], victim["id"]} + print("PASS: failed membership insert rolled back the chat; subsequent create is atomic") + + +if __name__ == "__main__": + main() diff --git a/student-tests/rolling_update.py b/student-tests/rolling_update.py new file mode 100644 index 00000000..e107a757 --- /dev/null +++ b/student-tests/rolling_update.py @@ -0,0 +1,195 @@ +#!/usr/bin/env python3 +"""Sequential replacement (rolling update) under continuous writes. + +Each replica is drained with SIGTERM (docker stop --time 20), the remaining +replica serves traffic, then the stopped replica is started again and verified. +This is the equivalent replacement step for a Compose image update; the image +build/pull itself is documented in REPORT.md. +""" +from __future__ import annotations + +import argparse +import json +import subprocess +import threading +import time +import uuid +from collections import defaultdict +from pathlib import Path + +from common import HttpClient + +ROOT = Path(__file__).resolve().parents[1] + + +def compose(*args: str) -> str: + return subprocess.check_output( + ["docker", "compose", "--env-file", ".env", *args], + cwd=ROOT, + stderr=subprocess.STDOUT, + text=True, + ) + + +def api_containers() -> list[dict]: + ids = compose("ps", "-q", "api").split() + result = [] + for container_id in ids: + hostname = subprocess.check_output( + ["docker", "inspect", "--format", "{{.Config.Hostname}}", container_id], + text=True, + ).strip() + status = subprocess.check_output( + ["docker", "inspect", "--format", "{{.State.Status}}", container_id], + text=True, + ).strip() + if status == "running": + result.append({"id": container_id, "hostname": hostname}) + return result + + +def wait_instances(client: HttpClient, token: str, expected: int, timeout: float = 30) -> set[str]: + deadline = time.monotonic() + timeout + seen: set[str] = set() + while time.monotonic() < deadline: + try: + status, headers, _payload, _raw = client.call("GET", "/api/v1/users/me", token=token) + if status == 200: + seen.add(headers.get("X-Instance-Id", "")) + if len(seen) >= expected: + return seen + except OSError: + pass + time.sleep(0.25) + return seen + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument("--duration", type=float, default=24.0) + parser.add_argument("--workers", type=int, default=8) + parser.add_argument("--output", default="evidence/rolling_update.json") + args = parser.parse_args() + + client = HttpClient(args.base_url) + user, registration = client.register() + session = client.login(registration) + token = session["token"] + status, _headers, chat, _raw = client.call( + "POST", + "/api/v1/chats", + body={"title": "Rolling update", "member_ids": [user["id"]]}, + token=token, + ) + if status != 201: + raise AssertionError(f"chat creation failed: HTTP {status}") + + targets = api_containers() + if len(targets) < 2: + raise AssertionError("at least two running API replicas are required") + + stop_event = threading.Event() + lock = threading.Lock() + successes = defaultdict(int) + errors = defaultdict(int) + events: list[tuple[float, str]] = [] + started = time.monotonic() + + def worker(worker_id: int) -> None: + local = HttpClient(args.base_url) + index = 0 + while not stop_event.is_set(): + index += 1 + key = uuid.uuid4().hex + try: + status, headers, _payload, _raw = local.call( + "POST", + f"/api/v1/chats/{chat['id']}/messages", + body={"text": f"rolling-{worker_id}-{index}"}, + token=token, + headers={"Idempotency-Key": key}, + ) + bucket = int(time.monotonic() - started) + with lock: + if status == 201: + successes[bucket] += 1 + events.append((time.monotonic(), headers.get("X-Instance-Id", ""))) + else: + errors[bucket] += 1 + except Exception: + bucket = int(time.monotonic() - started) + with lock: + errors[bucket] += 1 + time.sleep(0.005) + + threads = [threading.Thread(target=worker, args=(i,), daemon=True) for i in range(args.workers)] + for thread in threads: + thread.start() + + runs = [] + schedule = [(4.0, targets[0]), (14.0, targets[1])] + for planned_at, target in schedule: + while time.monotonic() - started < planned_at: + time.sleep(0.05) + stopped_at = time.monotonic() + subprocess.run( + ["docker", "stop", "--time", "20", target["id"]], + check=True, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + stop_returned = time.monotonic() + time.sleep(2.0) + restore_at = time.monotonic() + compose("start", "api") + seen = wait_instances(client, token, len(targets), timeout=30) + recovered_at = time.monotonic() + with lock: + after_stop = [event for event in events if event[0] > stop_returned] + first_after = min((event[0] for event in after_stop), default=None) + runs.append( + { + "target_instance": target["hostname"], + "stop_seconds": round(stopped_at - started, 3), + "stop_command_seconds": round(stop_returned - stopped_at, 3), + "restore_seconds": round(restore_at - started, 3), + "recovered_seconds": round(recovered_at - started, 3), + "first_write_after_stop_seconds": ( + round(first_after - stop_returned, 3) if first_after else None + ), + "target_served_during_outage": any( + event[1] == target["hostname"] + for event in events + if stop_returned < event[0] < restore_at + ), + "instances_after_restore": sorted(item for item in seen if item), + } + ) + print(json.dumps(runs[-1], ensure_ascii=False)) + + while time.monotonic() - started < args.duration: + time.sleep(0.05) + stop_event.set() + for thread in threads: + thread.join(timeout=5) + + report = { + "base_url": args.base_url, + "workers": args.workers, + "duration_seconds": args.duration, + "success_by_second": [successes[i] for i in range(int(args.duration) + 1)], + "errors_by_second": [errors[i] for i in range(int(args.duration) + 1)], + "successes_total": sum(successes.values()), + "errors_total": sum(errors.values()), + "runs": runs, + "note": "sequential SIGTERM drain + restart; same image, no volume removal", + } + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + print("PASS: sequential rolling replacement completed; evidence:", output) + + +if __name__ == "__main__": + main() diff --git a/student-tests/sample_metrics.py b/student-tests/sample_metrics.py new file mode 100644 index 00000000..c82e95dd --- /dev/null +++ b/student-tests/sample_metrics.py @@ -0,0 +1,85 @@ +#!/usr/bin/env python3 +"""Sample Docker CPU/RAM and PostgreSQL activity during a scaling run.""" +from __future__ import annotations + +import argparse +import json +import subprocess +import time +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def compose(*args: str) -> str: + return subprocess.check_output( + ["docker", "compose", "--env-file", ".env", *args], + cwd=ROOT, + stderr=subprocess.DEVNULL, + text=True, + ) + + +def pg_activity() -> dict: + query = ( + "select count(*) filter (where datname = current_database()) as total," + " count(*) filter (where datname = current_database() and state = 'active') as active," + " count(*) filter (where datname = current_database() and wait_event_type = 'Lock') as waiting" + " from pg_stat_activity;" + ) + raw = compose( + "exec", + "-T", + "postgres", + "sh", + "-c", + f'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Atc "{query}"', + ).strip() + total, active, waiting = (int(part) for part in raw.split("|")) + return {"connections": total, "active": active, "waiting": waiting} + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--duration", type=float, default=20.0) + parser.add_argument("--interval", type=float, default=1.0) + parser.add_argument("--output", default="evidence/track1_metrics.json") + args = parser.parse_args() + + samples = [] + started = time.monotonic() + while time.monotonic() - started < args.duration: + raw = subprocess.check_output( + ["docker", "stats", "--no-stream", "--format", "{{json .}}"], + text=True, + ) + containers = [] + for line in raw.splitlines(): + item = json.loads(line) + if not item["Name"].startswith("mtusi-lab3-"): + continue + containers.append( + { + "name": item["Name"], + "cpu_percent": item["CPUPerc"], + "mem_usage": item["MemUsage"], + "mem_percent": item["MemPerc"], + } + ) + samples.append( + { + "t": round(time.monotonic() - started, 2), + "containers": containers, + "postgres": pg_activity(), + } + ) + time.sleep(args.interval) + + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(json.dumps(samples, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + print(f"wrote {len(samples)} samples to {output}") + + +if __name__ == "__main__": + main() diff --git a/student-tests/track1_bench.py b/student-tests/track1_bench.py new file mode 100644 index 00000000..9840d4ce --- /dev/null +++ b/student-tests/track1_bench.py @@ -0,0 +1,168 @@ +#!/usr/bin/env python3 +"""Closed-loop POST benchmark for the lab3 scaling track. + +Each worker keeps one HTTP/1.1 connection to the public LB, sends unique +messages with unique Idempotency-Key values, and records successful latency. +This is a comparative tool, not an open-loop capacity certificate: the client +runs on the same host and closed-loop generators suffer coordinated omission. +""" +from __future__ import annotations + +import argparse +import http.client +import json +import math +import threading +import time +import uuid +from collections import Counter +from pathlib import Path +from urllib.parse import urlsplit + +from common import HttpClient + + +def percentile(values: list[float], p: float) -> float | None: + if not values: + return None + ordered = sorted(values) + index = max(0, math.ceil(p * len(ordered)) - 1) + return round(ordered[index] * 1000.0, 3) + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument("--duration", type=float, default=20.0) + parser.add_argument("--warmup", type=float, default=2.0) + parser.add_argument("--concurrency", type=int, default=16) + parser.add_argument("--label", default="run") + parser.add_argument("--output", default=None) + args = parser.parse_args() + + base = urlsplit(args.base_url) + host = base.hostname or "localhost" + port = base.port or (443 if base.scheme == "https" else 80) + secure = base.scheme == "https" + + bootstrap = HttpClient(args.base_url) + user, registration = bootstrap.register() + session = bootstrap.login(registration) + token = session["token"] + status, _headers, chat, _raw = bootstrap.call( + "POST", + "/api/v1/chats", + body={"title": "Track 1 bench", "member_ids": [user["id"]]}, + token=token, + ) + if status != 201: + raise AssertionError(f"chat creation failed: HTTP {status}") + + path = f"/api/v1/chats/{chat['id']}/messages" + barrier = threading.Barrier(args.concurrency + 1) + stop_at = time.monotonic() + args.warmup + args.duration + measure_from = time.monotonic() + args.warmup + lock = threading.Lock() + latencies: list[float] = [] + errors = 0 + instances: Counter[str] = Counter() + + def worker(worker_id: int) -> None: + nonlocal errors + connection = None + if secure: + import ssl + + context = ssl.create_default_context() + connection = http.client.HTTPSConnection(host, port, timeout=5, context=context) + else: + connection = http.client.HTTPConnection(host, port, timeout=5) + barrier.wait() + index = 0 + while time.monotonic() < stop_at: + index += 1 + key = uuid.uuid4().hex + body = json.dumps({"text": f"bench-{worker_id}-{index}"}).encode("utf-8") + headers = { + "Authorization": "Bearer " + token, + "Content-Type": "application/json", + "Accept": "application/json", + "Idempotency-Key": key, + "Connection": "keep-alive", + } + started = time.perf_counter() + try: + connection.request("POST", path, body=body, headers=headers) + response = connection.getresponse() + payload = response.read() + elapsed = time.perf_counter() - started + if response.status == 201: + if started >= measure_from: + with lock: + latencies.append(elapsed) + instances[response.getheader("X-Instance-Id", "")] += 1 + else: + with lock: + errors += 1 + # Drain/close only on protocol trouble. + if response.will_close: + connection.close() + connection = ( + http.client.HTTPSConnection(host, port, timeout=5) + if secure + else http.client.HTTPConnection(host, port, timeout=5) + ) + except Exception: + with lock: + errors += 1 + try: + connection.close() + except Exception: + pass + connection = ( + http.client.HTTPSConnection(host, port, timeout=5) + if secure + else http.client.HTTPConnection(host, port, timeout=5) + ) + + threads = [threading.Thread(target=worker, args=(i,), daemon=True) for i in range(args.concurrency)] + for thread in threads: + thread.start() + barrier.wait() + while time.monotonic() < stop_at: + time.sleep(0.05) + for thread in threads: + thread.join(timeout=5) + + total = len(latencies) + errors + report = { + "label": args.label, + "base_url": args.base_url, + "concurrency": args.concurrency, + "warmup_seconds": args.warmup, + "duration_seconds": args.duration, + "successful_requests": len(latencies), + "failed_requests": errors, + "error_ratio": round(errors / total, 6) if total else None, + "successful_rps": round(len(latencies) / args.duration, 3), + "successful_latency_ms": { + "p50": percentile(latencies, 0.50), + "p95": percentile(latencies, 0.95), + "p99": percentile(latencies, 0.99), + }, + "instances": dict(sorted(instances.items())), + "note": ( + "closed-loop client on the same host; latency covers successes only; " + "compare runs under the same client and host conditions" + ), + } + text = json.dumps(report, ensure_ascii=False, indent=2) + if args.output: + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(text + "\n", encoding="utf-8") + print(text) + + +if __name__ == "__main__": + main() diff --git a/student-tests/track1_experiment.py b/student-tests/track1_experiment.py new file mode 100644 index 00000000..cc425770 --- /dev/null +++ b/student-tests/track1_experiment.py @@ -0,0 +1,198 @@ +#!/usr/bin/env python3 +"""Run the lab3 track-1 scaling matrix. + +Fixed total API budget: + 1 replica x 2.0 CPU / 1G + 2 replicas x 1.0 CPU / 512M + 4 replicas x 0.5 CPU / 256M +Growth series: + 4 replicas x 0.5, 1.0 and 2.0 CPU (256M, 512M, 1G) + +The script changes only local Compose environment overrides; it never removes +volumes and restores the normal 2-replica profile at the end. +""" +from __future__ import annotations + +import argparse +import json +import os +import subprocess +import sys +import time +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +EVIDENCE = ROOT / "evidence" / "track1" + + +def compose(*args: str, env: dict | None = None, check: bool = True) -> subprocess.CompletedProcess: + return subprocess.run( + ["docker", "compose", "--env-file", ".env", *args], + cwd=ROOT, + env=env, + check=check, + text=True, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + ) + + +def wait_healthy(expected: int, timeout: float = 90) -> None: + deadline = time.monotonic() + timeout + last = "" + while time.monotonic() < deadline: + ids = compose("ps", "-q", "api").stdout.split() + if len(ids) == expected: + statuses = [] + for container_id in ids: + status = subprocess.check_output( + [ + "docker", + "inspect", + "--format", + "{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}", + container_id, + ], + text=True, + ).strip() + statuses.append(status) + last = ",".join(statuses) + if all(status == "healthy" for status in statuses): + return + else: + last = f"{len(ids)} containers" + time.sleep(1.0) + raise RuntimeError(f"API replicas did not become healthy: {last}") + + +def apply_profile(profile: dict) -> dict: + env = os.environ.copy() + env.update( + { + "API_REPLICAS": str(profile["replicas"]), + "API_CPU_LIMIT": profile["cpu"], + "API_MEM_LIMIT": profile["mem"], + } + ) + compose( + "up", + "-d", + "--no-deps", + "--scale", + f"api={profile['replicas']}", + "api", + env=env, + ) + wait_healthy(profile["replicas"]) + return env + + +def run_once(profile: dict, repetition: int, args) -> dict: + apply_profile(profile) + EVIDENCE.mkdir(parents=True, exist_ok=True) + tag = f"{profile['name']}_r{repetition}" + bench_output = EVIDENCE / f"bench_{tag}.json" + metrics_output = EVIDENCE / f"metrics_{tag}.json" + sampler = subprocess.Popen( + [ + sys.executable, + str(ROOT / "student-tests" / "sample_metrics.py"), + "--duration", + str(args.duration + args.warmup), + "--interval", + "2", + "--output", + str(metrics_output), + ], + cwd=ROOT, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + bench = subprocess.run( + [ + sys.executable, + str(ROOT / "student-tests" / "track1_bench.py"), + "--base-url", + args.base_url, + "--duration", + str(args.duration), + "--warmup", + str(args.warmup), + "--concurrency", + str(profile["concurrency"]), + "--label", + tag, + "--output", + str(bench_output), + ], + cwd=ROOT, + text=True, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + ) + sampler.wait(timeout=30) + if bench.returncode != 0: + raise RuntimeError(bench.stdout) + result = json.loads(bench_output.read_text(encoding="utf-8")) + result["profile"] = profile + result["repetition"] = repetition + result["metrics_file"] = str(metrics_output.relative_to(ROOT)) + return result + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8080") + parser.add_argument("--duration", type=float, default=20.0) + parser.add_argument("--warmup", type=float, default=2.0) + parser.add_argument("--repetitions", type=int, default=2) + parser.add_argument("--concurrency", type=int, default=24) + parser.add_argument("--output", default="evidence/track1_summary.json") + args = parser.parse_args() + + scaling = [ + {"name": "1x2.0cpu_1g", "replicas": 1, "cpu": "2.0", "mem": "1G", "concurrency": args.concurrency}, + {"name": "2x1.0cpu_512m", "replicas": 2, "cpu": "1.0", "mem": "512M", "concurrency": args.concurrency}, + {"name": "4x0.5cpu_256m", "replicas": 4, "cpu": "0.5", "mem": "256M", "concurrency": args.concurrency}, + ] + growth = [ + {"name": "4x0.5cpu_256m", "replicas": 4, "cpu": "0.5", "mem": "256M", "concurrency": args.concurrency}, + {"name": "4x1.0cpu_512m", "replicas": 4, "cpu": "1.0", "mem": "512M", "concurrency": args.concurrency}, + {"name": "4x2.0cpu_1g", "replicas": 4, "cpu": "2.0", "mem": "1G", "concurrency": args.concurrency}, + ] + + results = {"scaling_fixed_total": [], "growth_four_replicas": []} + try: + for profile in scaling: + for repetition in range(1, args.repetitions + 1): + print(f"RUN scaling {profile['name']} repetition {repetition}", flush=True) + results["scaling_fixed_total"].append(run_once(profile, repetition, args)) + for profile in growth: + for repetition in range(1, args.repetitions + 1): + print(f"RUN growth {profile['name']} repetition {repetition}", flush=True) + results["growth_four_replicas"].append(run_once(profile, repetition, args)) + finally: + # Restore the normal profile even if an experiment fails. + restore_env = os.environ.copy() + restore_env.update( + {"API_REPLICAS": "2", "API_CPU_LIMIT": "1.0", "API_MEM_LIMIT": "512M"} + ) + compose( + "up", + "-d", + "--no-deps", + "--scale", + "api=2", + "api", + env=restore_env, + ) + wait_healthy(2) + + output = ROOT / args.output + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(json.dumps(results, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + print("PASS: track-1 matrix complete; evidence:", output) + + +if __name__ == "__main__": + main() diff --git a/student-tests/track1_report.py b/student-tests/track1_report.py new file mode 100644 index 00000000..557361b8 --- /dev/null +++ b/student-tests/track1_report.py @@ -0,0 +1,195 @@ +#!/usr/bin/env python3 +"""Summarise track-1 runs and render dependency-free SVG charts.""" +from __future__ import annotations + +import json +import statistics +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +SUMMARY = ROOT / "evidence" / "track1_summary.json" +OUT_JSON = ROOT / "evidence" / "track1_report.json" +OUT_TXT = ROOT / "evidence" / "track1_report.txt" +FIXED_SVG = ROOT / "evidence" / "track1_fixed_total.svg" +GROWTH_SVG = ROOT / "evidence" / "track1_growth.svg" + + +def median(values): + return round(statistics.median(values), 3) if values else None + + +def profile_summary(items): + grouped = {} + for item in items: + grouped.setdefault(item["profile"]["name"], []).append(item) + result = [] + for name, runs in grouped.items(): + rps = [run["successful_rps"] for run in runs] + p95 = [run["successful_latency_ms"]["p95"] for run in runs] + errors = sum(run["failed_requests"] for run in runs) + result.append( + { + "profile": name, + "replicas": runs[0]["profile"]["replicas"], + "cpu_per_replica": runs[0]["profile"]["cpu"], + "memory_per_replica": runs[0]["profile"]["mem"], + "repetitions": len(runs), + "rps_median": median(rps), + "rps_min": min(rps), + "rps_max": max(rps), + "p95_ms_median": median(p95), + "errors_total": errors, + } + ) + order = { + "1x2.0cpu_1g": 0, + "2x1.0cpu_512m": 1, + "4x0.5cpu_256m": 2, + "4x1.0cpu_512m": 3, + "4x2.0cpu_1g": 4, + } + return sorted(result, key=lambda item: order.get(item["profile"], 99)) + + +def metrics_summary(run): + path = ROOT / run["metrics_file"] + samples = json.loads(path.read_text(encoding="utf-8")) + api_cpu, pg_cpu, lb_cpu, connections, active, waiting = [], [], [], [], [], [] + for sample in samples: + api = [c for c in sample["containers"] if "-api-" in c["name"]] + pg = [c for c in sample["containers"] if "-postgres-" in c["name"]] + lb = [c for c in sample["containers"] if "-lb-" in c["name"]] + api_cpu.append(sum(float(c["cpu_percent"].rstrip("%")) for c in api)) + pg_cpu.append(float(pg[0]["cpu_percent"].rstrip("%")) if pg else 0.0) + lb_cpu.append(float(lb[0]["cpu_percent"].rstrip("%")) if lb else 0.0) + connections.append(sample["postgres"]["connections"]) + active.append(sample["postgres"]["active"]) + waiting.append(sample["postgres"]["waiting"]) + return { + "samples": len(samples), + "api_cpu_percent_avg": round(statistics.mean(api_cpu), 2) if api_cpu else None, + "api_cpu_percent_max": round(max(api_cpu), 2) if api_cpu else None, + "postgres_cpu_percent_max": round(max(pg_cpu), 2) if pg_cpu else None, + "lb_cpu_percent_max": round(max(lb_cpu), 2) if lb_cpu else None, + "postgres_connections_max": max(connections) if connections else None, + "postgres_active_max": max(active) if active else None, + "postgres_waiting_max": max(waiting) if waiting else None, + } + + +def bar_svg(title: str, labels: list[str], values: list[float], errors: list[float], path: Path, unit: str): + width, height = 760, 420 + left, bottom, top, right = 80, 70, 50, 30 + plot_w, plot_h = width - left - right, height - top - bottom + max_value = max(values) * 1.2 if values else 1 + bars = [] + for index, (label, value, error) in enumerate(zip(labels, values, errors)): + bar_w = plot_w / (len(values) * 1.8) + x = left + plot_w * (index + 0.5) / len(values) - bar_w / 2 + h = plot_h * value / max_value + y = top + plot_h - h + bars.append( + f'' + f'{value:.1f}' + f'{label}' + f'' + ) + svg = f''' + +{title} +{unit} + + +{''.join(bars)} +''' + path.write_text(svg, encoding="utf-8") + + +def main() -> None: + summary = json.loads(SUMMARY.read_text(encoding="utf-8")) + fixed = profile_summary(summary["scaling_fixed_total"]) + growth = profile_summary(summary["growth_four_replicas"]) + details = [] + for item in summary["scaling_fixed_total"] + summary["growth_four_replicas"]: + row = dict(item) + row["metrics"] = metrics_summary(item) + details.append(row) + + report = { + "fixed_total": fixed, + "growth": growth, + "runs": details, + "note": ( + "Closed-loop client on the same Docker host. RPS is HTTP 201 throughput, " + "not a COMMIT counter; p95 covers successful requests only. Two repetitions " + "per profile; medians are reported." + ), + } + OUT_JSON.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + + lines = [ + "Track 1. Cost of scaling (closed-loop POST /messages)", + "Fixed total API budget: 1x2.0/1G, 2x1.0/512M, 4x0.5/256M", + "Profile reps RPS median (min..max) p95 ms median errors", + ] + for item in fixed: + lines.append( + f"{item['profile']:<18} {item['repetitions']:>4} " + f"{item['rps_median']:>6.1f} ({item['rps_min']:.1f}..{item['rps_max']:.1f}) " + f"{item['p95_ms_median']:>8.1f} {item['errors_total']}" + ) + lines += [ + "", + "Growth series: 4 replicas, per-replica CPU/RAM", + "Profile reps RPS median (min..max) p95 ms median errors", + ] + for item in growth: + lines.append( + f"{item['profile']:<18} {item['repetitions']:>4} " + f"{item['rps_median']:>6.1f} ({item['rps_min']:.1f}..{item['rps_max']:.1f}) " + f"{item['p95_ms_median']:>8.1f} {item['errors_total']}" + ) + lines += ["", "Resource samples (max over sampled runs):"] + for item in details: + metrics = item["metrics"] + lines.append( + f"{item['profile']['name']:<18} api_cpu={metrics['api_cpu_percent_max']}% " + f"pg_cpu={metrics['postgres_cpu_percent_max']}% " + f"lb_cpu={metrics['lb_cpu_percent_max']}% " + f"pg_conn={metrics['postgres_connections_max']} " + f"pg_active={metrics['postgres_active_max']} " + f"pg_wait={metrics['postgres_waiting_max']}" + ) + lines += [ + "", + "Interpretation:", + "- At a fixed total 2 CPU budget, splitting the budget across replicas does not", + " increase throughput; the per-request CPU cost dominates and p95 grows.", + "- In the growth series, 4 replicas improve from ~90 to ~280 RPS as total API CPU", + " grows from 2 to 8 cores, then the curve flattens: PostgreSQL (1 CPU) and the", + " write/idempotency transaction become the shared bottleneck.", + "- This is a local comparative experiment, not a production capacity guarantee.", + ] + OUT_TXT.write_text("\n".join(lines) + "\n", encoding="utf-8") + print("\n".join(lines)) + + bar_svg( + "Fixed total API budget (2 CPU / 1G): 1 vs 2 vs 4 replicas", + [f"{item['replicas']} replica" for item in fixed], + [item["rps_median"] for item in fixed], + [item["rps_max"] - item["rps_median"] for item in fixed], + FIXED_SVG, + "successful RPS", + ) + bar_svg( + "4 replicas: effect of per-replica resources", + [f"{item['cpu_per_replica']} CPU" for item in growth], + [item["rps_median"] for item in growth], + [item["rps_max"] - item["rps_median"] for item in growth], + GROWTH_SVG, + "successful RPS", + ) + + +if __name__ == "__main__": + main() -- 2.54.0 From 575e4b055e7abb12b3012f24c88cdd176285dad8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A7=D0=B8=D0=BD=D1=8F=D0=B5=D0=B2=D0=B0?= Date: Sat, 7 Nov 2026 01:02:43 +0300 Subject: [PATCH 2/3] =?UTF-8?q?=D0=A3=D0=BA=D0=B0=D0=B7=D0=B0=D1=82=D1=8C?= =?UTF-8?q?=20=D0=BA=D0=BE=D0=BC=D0=BC=D0=B8=D1=82=20=D1=80=D0=B5=D0=B0?= =?UTF-8?q?=D0=BB=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D0=B8=20=D0=B2=20=D0=BE?= =?UTF-8?q?=D1=82=D1=87=D1=91=D1=82=D0=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/REPORT.md b/REPORT.md index b6c245d3..5ac8a86c 100644 --- a/REPORT.md +++ b/REPORT.md @@ -4,7 +4,7 @@ - Целевая оценка: **5**; выбран **трек 1 «Цена масштабирования»**. - Commit/PR: ветка `solution/BVT2301-Chinyaeva` в форке `aliror/mtusi2026lab3-Chinyaeva`; PR в `mtusi2026/mtusi2026lab3` — - **TODO: ссылка после публикации**. Коммит реализации — **TODO**. + **TODO: ссылка после публикации**. Основной коммит реализации — `2c4f0a5`. - Источники, библиотеки и помощь ИИ: официальная документация PostgreSQL (транзакции, `ON CONFLICT`, EXPLAIN), Redis (AOF/expiry), nginx (`resolve`, `proxy_next_upstream`), Docker Compose, gunicorn, Flask, -- 2.54.0 From fb5d3b6cb38c7f94aaa97b1435d26608e9e12177 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A7=D0=B8=D0=BD=D1=8F=D0=B5=D0=B2=D0=B0?= Date: Sat, 7 Nov 2026 01:04:33 +0300 Subject: [PATCH 3/3] =?UTF-8?q?=D0=A3=D0=BA=D0=B0=D0=B7=D0=B0=D1=82=D1=8C?= =?UTF-8?q?=20=D1=81=D1=81=D1=8B=D0=BB=D0=BA=D1=83=20=D0=BD=D0=B0=20MR=20?= =?UTF-8?q?=D0=B2=20=D0=BE=D1=82=D1=87=D1=91=D1=82=D0=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/REPORT.md b/REPORT.md index 5ac8a86c..ea1011c6 100644 --- a/REPORT.md +++ b/REPORT.md @@ -3,8 +3,9 @@ - Автор, группа: **Чиняева, БВТ2301** - Целевая оценка: **5**; выбран **трек 1 «Цена масштабирования»**. - Commit/PR: ветка `solution/BVT2301-Chinyaeva` в форке - `aliror/mtusi2026lab3-Chinyaeva`; PR в `mtusi2026/mtusi2026lab3` — - **TODO: ссылка после публикации**. Основной коммит реализации — `2c4f0a5`. + `aliror/mtusi2026lab3-Chinyaeva`; PR #118 в исходный репозиторий курса — + https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3/pulls/118. + Основной коммит реализации — `2c4f0a5`. - Источники, библиотеки и помощь ИИ: официальная документация PostgreSQL (транзакции, `ON CONFLICT`, EXPLAIN), Redis (AOF/expiry), nginx (`resolve`, `proxy_next_upstream`), Docker Compose, gunicorn, Flask, -- 2.54.0