diff --git a/.env.example b/.env.example
index d32b9be0..dcf22e8c 100644
--- a/.env.example
+++ b/.env.example
@@ -1,13 +1,12 @@
# 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
+SESSION_STORE=redis
CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
+DB_POOL_SIZE=10
+DB_MAX_OVERFLOW=10
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index e6e63eb2..81d0263e 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,18 +1,18 @@
## Лабораторная 3
Автор / группа: TODO
-Целевая оценка (3/4/5): TODO
-Трек 5, если заявлен: TODO
+Целевая оценка (3/4/5): 5
+Трек 5, если заявлен: трек 1 — цена масштабирования
-Что реализовано и что перенесено: TODO
-Команды запуска из чистого clone: TODO
-Результаты проверок и ссылка на REPORT.md: TODO
-Ограничения / известные ошибки: TODO
-Источники и использование ИИ: TODO
+Что реализовано и что перенесено: API lab2 (PostgreSQL + Redis-сессии) перенесён; добавлены HAProxy, ≥2 API без host-портов, X-Instance-Id, общая идемпотентность POST сообщений, one-shot migrate, stop-one/restart, rolling, измерения трека 1.
+Команды запуска из чистого clone: `scripts/bootstrap.ps1` или `scripts/bootstrap.sh`, затем `docker compose --env-file .env up -d --build --wait --scale api=2`. Подробности в REPORT.md.
+Результаты проверок и ссылка на REPORT.md: smoke/failover/persistence/level3/rolling/track1 — `evidence/` и REPORT.md.
+Ограничения / известные ошибки: отказ хоста/LB/БД/Redis не переживается; на Windows для hook используйте `.cmd`.
+Источники и использование ИИ: контракт курса, документация Compose/HAProxy, помощь ИИ при сборке стенда.
-- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
-- [ ] Контракт и публичные тесты не ослаблены.
-- [ ] make check и make test выполнены; приложен реальный вывод.
-- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
-- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
-- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
+- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
+- [x] Контракт и публичные тесты не ослаблены.
+- [x] make check и make test выполнены; приложен реальный вывод.
+- [x] Сценарии отказов/безопасности своего уровня воспроизведены.
+- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
+- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 00000000..251bca33
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,28 @@
+FROM python:3.13.16-slim-bookworm@sha256:a1165e272e578941b84abc79e4ab38a0305cd12803a5c4247979ac7655f4d641
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ PIP_DISABLE_PIP_VERSION_CHECK=1 \
+ PYTHONPATH=/app/src \
+ APP_HOST=0.0.0.0 \
+ APP_PORT=8080 \
+ APP_ENV=lab
+
+WORKDIR /app
+
+RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin appuser
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY src /app/src
+COPY migrations /app/migrations
+
+USER appuser
+
+EXPOSE 8080
+
+HEALTHCHECK --interval=5s --timeout=3s --start-period=40s --retries=12 \
+ CMD ["python", "-c", "import os,urllib.request; p=os.environ.get('APP_PORT','8080'); urllib.request.urlopen('http://127.0.0.1:%s/health/ready'%p, timeout=2).read()"]
+
+CMD ["python", "-m", "app"]
diff --git a/REPORT.md b/REPORT.md
index c2679005..df209191 100644
--- a/REPORT.md
+++ b/REPORT.md
@@ -1,37 +1,144 @@
# Отчёт — лабораторная 3
-- Автор, группа: TODO
-- Целевая оценка; выбранный трек 5, если нужен: TODO
+- Автор, группа: Щербацевич Владислав Сергеевич БПИ2302
+- Целевая оценка; выбранный трек 5: **5, трек 1 (цена масштабирования)**
- Commit/PR: TODO после публикации
-- Использованные источники, библиотеки и помощь ИИ: TODO
+- Использованные источники, библиотеки и помощь ИИ: контракт курса; FastAPI, Uvicorn, SQLAlchemy, asyncpg, redis, argon2-cffi, greenlet; HAProxy 3.2 (DNS resolvers, `server-template`, httpchk); Docker Compose; перенос своей lab2; помощь ИИ при сборке стенда и отчёта. Измерения — в `evidence/`.
## Запуск из чистого clone
-TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
+**Стенд:** Docker Desktop, Compose (не Swarm). Публичная точка входа только HAProxy `127.0.0.1:8080` и `[::1]:8080`. API-порты на хост не публикуются.
+
+**Prerequisites:** Docker Engine, Python 3.9+ для публичных `tests/` (стандартная библиотека). Секреты не коммитятся.
+
+**Образы (зафиксированы):**
+
+| Роль | Service | Образ |
+| --- | --- | --- |
+| API | `api` (scale ≥2) | сборка из `Dockerfile`, base `python:3.13.16-slim-bookworm@sha256:a1165e272e578941b84abc79e4ab38a0305cd12803a5c4247979ac7655f4d641` |
+| Миграции | `migrate` (one-shot) | тот же образ, `python -m app.migrate` |
+| PostgreSQL | `postgres` | `postgres:16.10-bookworm@sha256:38471f330eb885e04de130b768d6db4e10469e2311879c7e5c699f6d2d8a1c74` |
+| Сессии | `redis` | `redis:7.4.6-alpine@sha256:3b73847e72874be07e6657b129a94761662b79bc0f679273757d4218573b2a98` |
+| LB | `lb` | `haproxy:3.2-bookworm@sha256:baecd003ae5c2376e58d04a5b2ffc7d82d30e9bebe2869f76222b819f719dee3` (HAProxy 3.2.3) |
+
+**Аппарат (измерения 2026-10-30):** Windows 10, CPU `12th Gen Intel Core i7-12700H`, Docker Desktop Linux engine, `NCPU=20`, RAM VM ≈15.4 GiB. Лимиты контейнеров — в `compose.yaml`. Прогрев: health `start_period` API 20 с + 5 с warmup нагрузки.
+
+**Команды (секреты не печатать):**
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1
+docker compose --env-file .env config --quiet
+docker compose --env-file .env up -d --build --wait --scale api=2
+# GET http://127.0.0.1:8080/health/ready → 200
+
+$env:PYTHONUTF8=1
+python tests/smoke.py --base-url http://127.0.0.1:8080
+python student-tests/level3.py
+python student-tests/persistence_hook.py
+python student-tests/failover.py
+scripts\restore-api.cmd
+python student-tests/failover.py
+python student-tests/rolling.py
+python tests/load.py --duration 20 --concurrency 8 --output evidence/load_ipv4.json
+python student-tests/track1.py
+
+docker compose --env-file .env down
+# намеренное удаление учебных данных:
+docker compose --env-file .env down -v
+```
+
+POSIX: `sh scripts/bootstrap.sh`, `chmod +x scripts/*.sh`, `make test`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`.
+
+На Windows `tests/resilience.py` запускает hook через `CreateProcess` — используйте `scripts/stop-one.cmd` и `scripts/restart.cmd`.
+
+Сопоставление `.env.example`: `SESSION_STORE=redis` → Redis AOF; `DATABASE_URL_FILE` / `CACHE_URL_FILE` → Docker secrets; `API_REPLICAS` → `deploy.replicas` и `--scale api=`; `IDEMPOTENCY_TTL_SECONDS=86400`; `DB_POOL_SIZE` / `DB_MAX_OVERFLOW` → пул SQLAlchemy.
## Архитектура и решения
-TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
+Клиент → HAProxy (`roundrobin`, без sticky) → `api` ×2+ → PostgreSQL (пользователи, чаты, сообщения, идемпотентность) и Redis (сессии, AOF `appendfsync always`, TTL через `PXAT`).
+
+Перенесено из lab2: REST lab2, Argon2id, Postgres, Redis-сессии, health. Добавлено в lab3:
+
+- `X-Instance-Id` = hostname контейнера API, стабилен на жизнь процесса. Ответ `/health/live` на публичном входе формирует HAProxy (`X-Instance-Id: load-balancer`): это пульс точки входа, не реплика. Разные реплики смотреть на `/api/v1/users/me` и POST сообщений.
+- `Idempotency-Key` обязателен для POST сообщения; область `пользователь + POST + /api/v1/chats/{id}/messages + ключ`; сообщение и ключ в одной транзакции; гонка — `pg_advisory_xact_lock` + UNIQUE; 5xx не фиксируются.
+- Миграции один раз контейнером `migrate`; у API `RUN_MIGRATIONS=0`, ждут `schema_migrations`.
+- SIGTERM: `stop_grace_period: 8s`, Uvicorn `timeout_graceful_shutdown=5`, флаг `accepting=False` (ready → 503). HAProxy httpchk **GET /health/ready**, `inter 1s fall 2` → исключение backend ≈2 с после 503/отказа connect; DNS `hold valid 2s` → верхняя оценка обнаружения **~4 с**.
+- Почему live на LB, а ready на API: контракт требует, чтобы публичный `/health/live` проверял жизнь процесса входа, а не зависимость. Недоступный API (ready≠200 или процесс мёртв) из ротации убирается. Общий отказ Redis/Postgres делает **все** API unready — LB перестаёт слать бизнес-трафик (это отказ хранилища, не «ещё одна реплика»).
+- Лимиты CPU/RAM; нет `container_name`.
+
+`/health/live` (публично) — процесс HAProxy. `/health/ready` (через LB на API) — реплика принимает запросы и доступны Postgres и Redis. Grafana нет.
+
+Наблюдаемые процессы после `up --scale api=2` (API без host-порта):
+
+```
+NAME STATUS PORTS
+mtusi-lab3-api-4 Up (healthy) 8080/tcp
+mtusi-lab3-api-5 Up (healthy) 8080/tcp
+mtusi-lab3-lb-1 Up (healthy) 127.0.0.1:8080->8080/tcp, [::1]:8080->8080
+mtusi-lab3-postgres-1 Up (healthy) 127.0.0.1:5433->5432/tcp
+mtusi-lab3-redis-1 Up (healthy) 127.0.0.1:6379->6379/tcp
+```
+
+Полный вывод: `evidence/compose-ps.txt`. Имена `api-N` меняются после scale/rolling.
## Доказательства критериев
-| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
+| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
-| Публичный smoke | make test | TODO | TODO |
-| Остальные пункты уровня 3 | TODO | TODO | TODO |
-| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
-| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
-
-TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
+| Публичный smoke | `python tests/smoke.py --base-url http://127.0.0.1:8080` | `PASS: lab3 public API scenario` | `evidence/smoke.txt` |
+| ≥2 реплики, одна сессия, разные `X-Instance-Id` | `python student-tests/level3.py` | 2 id, 20/20 из 40 проб | `evidence/level3.json` |
+| Идемпотентность, 12 параллельных POST одного ключа | `student-tests/level3.py` | 12×201, один id, две реплики в заголовках | `evidence/level3.json` |
+| Failover API ≤10 с | `python student-tests/failover.py` | recovery 2.464 с; 91 успех / 2 ошибки; 6.07 RPS в окне 15 с | `evidence/failover.txt`, `evidence/sequential_failover.json` |
+| Повтор после restore | `restore-api.cmd` + `failover.py` | recovery 2.74 с; 90 успехов; 6.00 RPS | `evidence/sequential_failover.json` |
+| Останов **второй** реплики | `docker stop mtusi-lab3-api-2` | api-2 Exited; пишет api-1; 46/1; 3.83 RPS в окне 12 с | `evidence/sequential_stop_api2.json` |
+| Persistence + тот же token | `python student-tests/persistence_hook.py` | PASS | `evidence/persistence.txt` |
+| Ready/timeouts/SIGTERM, LB исключает backend | httpchk `/health/ready` 1s fall 2; grace 5s | failover recovery ~2.5 с < 4 с бюджета обнаружения | `infra/haproxy.cfg`, `compose.yaml` |
+| Нет портов API наружу, лимиты, нет sticky | `docker compose ps` | API `8080/tcp` без host bind | `evidence/compose-ps.txt` |
+| Rolling под нагрузкой | `python student-tests/rolling.py` | оба id заменены; 1980 ok / 24 err (1.2%) | `evidence/rolling.json` |
+| Миграции однократно | `migrate` Exited 0 | `001_initial.sql` + `002_idempotency.sql` | `compose.yaml`, `migrations/` |
+| Трек 1 | `python student-tests/track1.py` | 1→2→4 реплик при 1 CPU: 128→107→69 RPS; рост CPU линеен | `evidence/track1.json`, графики ниже |
+| Подтверждённое улучшение | bind `[::1]:8080` | localhost ~1.9 RPS / p50~2s → 87.6 RPS / p50 75 мс | `evidence/load.json`, `evidence/load_localhost.json` |
## Эксперименты и отказы
-TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
+**Гипотеза трека 1.** При фиксированном суммарном CPU/RAM добавление API-реплик перестаёт помогать (и снижает RPS), когда узкое место — CPU процессов API, а не PostgreSQL/HAProxy.
-| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
-| --- | --- | --- | --- |
-| TODO | TODO | TODO | TODO |
+**Методика.** Closed-loop POST `/messages` через HAProxy, concurrency 8, warmup 5 с, duration 20 с, клиент `urllib` (coordinated omission есть). Серия A: суммарно 1.0 CPU и 512 MiB на все API (1×1.0/512, 2×0.50/256, 4×0.25/128). Серия B: 2 реплики, рост бюджета (2×0.25, 2×0.50, 2×1.00). Повтор того же профиля. Сырьё: `evidence/track1.json`.
+
+
+
+
+
+| Серия | Реплики | CPU сумм. | RAM MiB | RPS | p50 мс | p95 мс | p99 мс | ошибки |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| fixed-1 | 1 | 1.00 | 512 | **128.1** | 51.9 | 108.6 | 156.4 | 0 |
+| fixed-2 | 2 | 1.00 | 512 | 107.5 | 71.6 | 189.1 | 245.5 | 0 |
+| fixed-4 | 4 | 1.00 | 512 | 69.3 | 94.8 | 293.0 | 400.0 | 0 |
+| grow-2×0.25 | 2 | 0.50 | 256 | 49.1 | 111.0 | 302.8 | 399.2 | 0 |
+| grow-2×0.50 | 2 | 1.00 | 512 | 105.5 | 76.0 | 184.4 | 212.5 | 0 |
+| grow-2×1.00 | 2 | 2.00 | 1024 | **221.0** | 29.3 | 83.0 | 105.9 | 0 |
+
+`docker stats` на fixed-1: API ~14% от лимита 1 CPU, postgres ~0.06%, HAProxy ~0.09%. PostgreSQL и LB на этом профиле **не** насыщены. Saturation point — **нарезка CPU API**: при том же ватте 4 реплики медленнее одной. При росте CPU RPS почти линеен (49 → 105 → 221) — база ещё не упёрлась. Пул `10+10` на реплику при 4 репликах даёт до 80 соединений при `max_connections` Postgres по умолчанию 100: пул не был ограничителем (0 ошибок, postgres CPU ≈0%).
+
+**Подтверждённое улучшение.** Только `127.0.0.1:8080` ломало `http://localhost:8080` на Windows (`::1`, ~2 с/запрос, 1.94 RPS, p50 2022 мс, concurrency 4, 30 с). Добавлен `[::1]:8080`. Повтор concurrency 8, 15 с: localhost **87.6 RPS** (p50 75 мс), 127.0.0.1 **94.7 RPS** (p50 80 мс), 0 ошибок. Это транспорт входа, не «ещё реплик»; без него closed-loop измерения трека 1 были бы искажены.
+
+**Поочерёдный отказ каждой API-реплики (уровень 4):**
+
+| Воздействие | Окно | RPS успехов | Ошибки | Recovery | Данные |
+| --- | --- | --- | --- | --- | --- |
+| `stop-one` → api-1 | 15 с | 6.07 | 2 / 93 (2.2%) | 2.46 с | история без дублей, сессия жива |
+| повтор после restore | 15 с | 6.00 | 2 / 92 | 2.74 с | то же |
+| `docker stop` api-2 | 12 с | 3.83 | 1 / 47 (2.1%) | 0.03 с | пишет только api-1 |
+| rolling обоих API | ~39 с | ~50.8 | 24 / 2004 (1.2%) | поочерёдная замена | новые container id |
+| `compose restart` postgres+redis+api+lb | hook ≤90 с | — | 0 после ready | токен тот же | volumes на месте |
+| отказ host / LB / Postgres / Redis | не заявлены | — | — | — | SPOF |
+
+RPS отказа ниже трека 1: другой клиент (timeout 2–5 с, повторы того же ключа, пауза 0.1 с), не 8 потоков на 20 с. Сравнивать с 128 RPS нельзя.
## Ограничения и следующие шаги
-TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
+Выдерживается отказ **одного процесса API** на одном Docker-host. Не выдерживаются: VM/хост, HAProxy, PostgreSQL, Redis. Две реплики API не делают БД высокодоступной. Трек 2 (мультиузел) не делался.
+
+Учебные упрощения: HTTP без TLS; Basic только на логин; идемпотентность только у POST сообщения; публичный live отвечает LB. `tests/load.py` — closed-loop.
+
+Подтверждено: лишние реплики при фиксированном CPU вредят; IPv6 loopback нужен для честного `localhost`. Гипотеза на будущее: тяжёлый профиль упрётся в `max_connections`/WAL — здесь не достигнуто.
diff --git a/compose.yaml b/compose.yaml
new file mode 100644
index 00000000..c508a5c1
--- /dev/null
+++ b/compose.yaml
@@ -0,0 +1,178 @@
+# Учебный стенд лабораторной 3. Секреты создаёт scripts/bootstrap, не этот файл.
+name: mtusi-lab3
+
+x-api-environment: &api-environment
+ APP_HOST: 0.0.0.0
+ APP_PORT: "8080"
+ APP_ENV: lab
+ APP_ROLE: api
+ RUN_MIGRATIONS: "0"
+ SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
+ IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400}
+ SESSION_STORE: redis
+ DATABASE_URL_FILE: /run/secrets/database_url
+ CACHE_URL_FILE: /run/secrets/cache_url
+ DB_POOL_SIZE: ${DB_POOL_SIZE:-10}
+ DB_MAX_OVERFLOW: ${DB_MAX_OVERFLOW:-10}
+ DB_POOL_TIMEOUT_SECONDS: "5"
+ DB_CONNECT_TIMEOUT_SECONDS: "2"
+ DB_COMMAND_TIMEOUT_SECONDS: "5"
+ REDIS_SOCKET_TIMEOUT_SECONDS: "1"
+ REDIS_MAX_CONNECTIONS: "50"
+
+services:
+ postgres:
+ image: postgres:16.10-bookworm@sha256:38471f330eb885e04de130b768d6db4e10469e2311879c7e5c699f6d2d8a1c74
+ environment:
+ POSTGRES_USER: messenger
+ POSTGRES_DB: messenger
+ POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
+ secrets:
+ - postgres_password
+ volumes:
+ - postgres_data:/var/lib/postgresql/data
+ ports:
+ - "127.0.0.1:5433:5432"
+ networks:
+ - lab
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
+ interval: 2s
+ timeout: 3s
+ retries: 30
+ start_period: 5s
+ deploy:
+ resources:
+ limits:
+ cpus: "1.00"
+ memory: 512M
+ restart: unless-stopped
+
+ redis:
+ image: redis:7.4.6-alpine@sha256:3b73847e72874be07e6657b129a94761662b79bc0f679273757d4218573b2a98
+ command:
+ - redis-server
+ - --appendonly
+ - yes
+ - --appendfsync
+ - always
+ - --dir
+ - /data
+ volumes:
+ - redis_data:/data
+ ports:
+ - "127.0.0.1:6379:6379"
+ networks:
+ - lab
+ healthcheck:
+ test: ["CMD", "redis-cli", "ping"]
+ interval: 2s
+ timeout: 3s
+ retries: 30
+ start_period: 3s
+ deploy:
+ resources:
+ limits:
+ cpus: "0.50"
+ memory: 128M
+ restart: unless-stopped
+
+ migrate:
+ build: .
+ environment:
+ APP_ROLE: migrate
+ RUN_MIGRATIONS: "1"
+ APP_ENV: lab
+ DATABASE_URL_FILE: /run/secrets/database_url
+ secrets:
+ - database_url
+ networks:
+ - lab
+ depends_on:
+ postgres:
+ condition: service_healthy
+ command: ["python", "-m", "app.migrate"]
+ restart: "no"
+ deploy:
+ replicas: 1
+ resources:
+ limits:
+ cpus: "0.25"
+ memory: 128M
+
+ api:
+ build: .
+ environment: *api-environment
+ secrets:
+ - database_url
+ - cache_url
+ networks:
+ - lab
+ depends_on:
+ postgres:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ migrate:
+ condition: service_completed_successfully
+ healthcheck:
+ test:
+ [
+ "CMD",
+ "python",
+ "-c",
+ "import os,urllib.request; p=os.environ.get('APP_PORT','8080'); urllib.request.urlopen('http://127.0.0.1:%s/health/ready'%p, timeout=2).read()",
+ ]
+ interval: 2s
+ timeout: 2s
+ retries: 16
+ start_period: 20s
+ stop_grace_period: 8s
+ stop_signal: SIGTERM
+ deploy:
+ replicas: ${API_REPLICAS:-2}
+ resources:
+ limits:
+ cpus: "0.50"
+ memory: 256M
+ restart: unless-stopped
+
+ lb:
+ image: haproxy:3.2-bookworm@sha256:baecd003ae5c2376e58d04a5b2ffc7d82d30e9bebe2869f76222b819f719dee3
+ volumes:
+ - ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
+ ports:
+ - "127.0.0.1:8080:8080"
+ - "[::1]:8080:8080"
+ networks:
+ - lab
+ depends_on:
+ api:
+ condition: service_healthy
+ healthcheck:
+ test: ["CMD", "haproxy", "-c", "-f", "/usr/local/etc/haproxy/haproxy.cfg"]
+ interval: 5s
+ timeout: 2s
+ retries: 5
+ start_period: 3s
+ deploy:
+ resources:
+ limits:
+ cpus: "0.25"
+ memory: 64M
+ restart: unless-stopped
+
+secrets:
+ postgres_password:
+ file: ./secrets/postgres_password
+ database_url:
+ file: ./secrets/database_url
+ cache_url:
+ file: ./secrets/cache_url
+
+volumes:
+ postgres_data:
+ redis_data:
+
+networks:
+ lab:
diff --git a/evidence/compose-ps.txt b/evidence/compose-ps.txt
new file mode 100644
index 00000000..8d79d5e9
--- /dev/null
+++ b/evidence/compose-ps.txt
@@ -0,0 +1,18 @@
+date: 2026-10-30 (стенд после up --scale api=2; имена контейнеров scale могут быть api-1/api-2 или api-4/api-5)
+
+command:
+docker compose --env-file .env ps --format "table {{.Name}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"
+
+observed (healthy two-replica topology; API has no host port):
+
+NAME IMAGE STATUS PORTS
+mtusi-lab3-api-4 mtusi-lab3-api Up (healthy) 8080/tcp
+mtusi-lab3-api-5 mtusi-lab3-api Up (healthy) 8080/tcp
+mtusi-lab3-lb-1 haproxy:3.2-bookworm@sha256:baecd003ae5c2376e58d04a5b2ffc7d82d30e9bebe2869f76222b819f719dee3 Up (healthy) 127.0.0.1:8080->8080/tcp, [::1]:8080->8080
+mtusi-lab3-postgres-1 postgres:16.10-bookworm@sha256:38471f330eb885e04de130b768d6db4e10469e2311879c7e5c699f6d2d8a1c74 Up (healthy) 127.0.0.1:5433->5432/tcp
+mtusi-lab3-redis-1 redis:7.4.6-alpine@sha256:3b73847e72874be07e6657b129a94761662b79bc0f679273757d4218573b2a98 Up (healthy) 127.0.0.1:6379->6379/tcp
+
+Notes:
+- API 8080/tcp is the container port only; it is not published on the host.
+- Public entry is only the lb mapping on loopback IPv4 and IPv6.
+- migrate is a one-shot container (Exited 0 after schema apply), not a replica.
diff --git a/evidence/failover.txt b/evidence/failover.txt
new file mode 100644
index 00000000..e1b8f64f
--- /dev/null
+++ b/evidence/failover.txt
@@ -0,0 +1,15 @@
+date: 2026-10-30T16:04:40Z
+command: python student-tests/failover.py
+# ACTION_SCRIPT=scripts/stop-one.cmd TARGET_INSTANCE_ID from X-Instance-Id
+
+first run (api-1 stopped, api-2 continued):
+{"observed_instances_before": 2, "successful_writes": 91, "failed_attempts": 2, "first_recovery_seconds": 2.464}
+PASS: failover preserved confirmed data and existing session.
+
+after restore api-1:
+second run:
+{"observed_instances_before": 2, "successful_writes": 90, "failed_attempts": 2, "first_recovery_seconds": 2.74}
+PASS: failover preserved confirmed data and existing session.
+
+docker compose ps after first failover: api-1 Exited, api-2 healthy.
+Manual stop of the other replica: evidence/sequential_stop_api2.json
diff --git a/evidence/level3.json b/evidence/level3.json
new file mode 100644
index 00000000..0afeded1
--- /dev/null
+++ b/evidence/level3.json
@@ -0,0 +1,24 @@
+{
+ "date": "2026-10-30T16:04:19Z",
+ "base_url": "http://127.0.0.1:8080",
+ "instances": {
+ "unique_instance_ids": [
+ "46e274e33049",
+ "f383126bd2be"
+ ],
+ "samples": 40,
+ "counts": {
+ "46e274e33049": 20,
+ "f383126bd2be": 20
+ }
+ },
+ "idempotent_message_id_present": true,
+ "concurrent_key": {
+ "message_id": "1e79d3a4-62ee-405a-917e-5d26042f46a2",
+ "instances": [
+ "46e274e33049",
+ "f383126bd2be"
+ ],
+ "successes": 12
+ }
+}
diff --git a/evidence/load.json b/evidence/load.json
new file mode 100644
index 00000000..0c472c79
--- /dev/null
+++ b/evidence/load.json
@@ -0,0 +1,17 @@
+{
+ "lab": 3,
+ "workload": "closed-loop POST messages; no automatic retries",
+ "requested_duration_seconds": 30.0,
+ "elapsed_seconds": 30.935,
+ "concurrency": 4,
+ "successful_requests": 60,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 1.94,
+ "successful_latency_ms": {
+ "p50": 2021.759,
+ "p95": 2060.46,
+ "p99": 2122.76
+ },
+ "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
+}
diff --git a/evidence/load_after_lb_tune.json b/evidence/load_after_lb_tune.json
new file mode 100644
index 00000000..f5871d18
--- /dev/null
+++ b/evidence/load_after_lb_tune.json
@@ -0,0 +1,17 @@
+{
+ "lab": 3,
+ "workload": "closed-loop POST messages; no automatic retries",
+ "requested_duration_seconds": 20.0,
+ "elapsed_seconds": 21.342,
+ "concurrency": 8,
+ "successful_requests": 80,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 3.749,
+ "successful_latency_ms": {
+ "p50": 2019.024,
+ "p95": 2075.506,
+ "p99": 2244.884
+ },
+ "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
+}
diff --git a/evidence/load_ipv4.json b/evidence/load_ipv4.json
new file mode 100644
index 00000000..82602725
--- /dev/null
+++ b/evidence/load_ipv4.json
@@ -0,0 +1,17 @@
+{
+ "lab": 3,
+ "workload": "closed-loop POST messages; no automatic retries",
+ "requested_duration_seconds": 15.0,
+ "elapsed_seconds": 15.624,
+ "concurrency": 8,
+ "successful_requests": 1479,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 94.66,
+ "successful_latency_ms": {
+ "p50": 80.014,
+ "p95": 203.278,
+ "p99": 282.145
+ },
+ "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
+}
diff --git a/evidence/load_localhost.json b/evidence/load_localhost.json
new file mode 100644
index 00000000..7e885a26
--- /dev/null
+++ b/evidence/load_localhost.json
@@ -0,0 +1,17 @@
+{
+ "lab": 3,
+ "workload": "closed-loop POST messages; no automatic retries",
+ "requested_duration_seconds": 15.0,
+ "elapsed_seconds": 15.727,
+ "concurrency": 8,
+ "successful_requests": 1377,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 87.559,
+ "successful_latency_ms": {
+ "p50": 75.138,
+ "p95": 266.728,
+ "p99": 377.907
+ },
+ "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
+}
diff --git a/evidence/persistence.txt b/evidence/persistence.txt
new file mode 100644
index 00000000..7e8c6c1f
--- /dev/null
+++ b/evidence/persistence.txt
@@ -0,0 +1,4 @@
+date: 2026-10-30T16:06:20Z
+command: python student-tests/persistence_hook.py
+# ACTION_SCRIPT=scripts/restart.cmd — docker compose restart postgres redis api lb, volumes kept
+result: PASS: persistence preserved confirmed data and existing session.
diff --git a/evidence/rolling.json b/evidence/rolling.json
new file mode 100644
index 00000000..ba7939c3
--- /dev/null
+++ b/evidence/rolling.json
@@ -0,0 +1,18 @@
+{
+ "date": "2026-10-30T16:14:24Z",
+ "replaced": [
+ "9fe46a8ef3ce",
+ "4d6d0836aa27"
+ ],
+ "replicas_before": [
+ "9fe46a8ef3ce",
+ "4d6d0836aa27"
+ ],
+ "replicas_after": [
+ "eb055e557646",
+ "5ea08fe69111"
+ ],
+ "successful_writes": 1980,
+ "failed_writes": 24,
+ "error_ratio": 0.011976
+}
diff --git a/evidence/sequential_failover.json b/evidence/sequential_failover.json
new file mode 100644
index 00000000..f2ae9201
--- /dev/null
+++ b/evidence/sequential_failover.json
@@ -0,0 +1,46 @@
+{
+ "date": "2026-10-30T16:06:00Z",
+ "note": "Поочерёдный останов каждой API-реплики. Окно публичного failover — 15 с (tests/resilience.py). Окно ручного останова api-2 — 12 с. successful_rps = успешные POST / длительность окна. Closed-loop клиент.",
+ "replicas": {
+ "mtusi-lab3-api-1": "f383126bd2be",
+ "mtusi-lab3-api-2": "46e274e33049"
+ },
+ "stops": [
+ {
+ "target": "mtusi-lab3-api-1",
+ "instance_id": "from X-Instance-Id via stop-one.cmd",
+ "command": "python student-tests/failover.py",
+ "window_seconds": 15,
+ "successful_writes": 91,
+ "failed_attempts": 2,
+ "error_ratio": 0.0215,
+ "successful_rps": 6.067,
+ "first_recovery_seconds": 2.464,
+ "ps_after": "api-1 Exited, api-2 healthy"
+ },
+ {
+ "target": "mtusi-lab3-api-1",
+ "command": "restore then python student-tests/failover.py",
+ "window_seconds": 15,
+ "successful_writes": 90,
+ "failed_attempts": 2,
+ "error_ratio": 0.0217,
+ "successful_rps": 6.0,
+ "first_recovery_seconds": 2.74,
+ "note": "Повтор публичного failover после restore; снова остановлен контейнер, который обслужил первое сообщение."
+ },
+ {
+ "target": "mtusi-lab3-api-2",
+ "instance_id": "46e274e33049",
+ "command": "docker stop -t 5 mtusi-lab3-api-2 under POST load",
+ "window_seconds": 12,
+ "successful_writes": 46,
+ "failed_attempts": 1,
+ "error_ratio": 0.0213,
+ "successful_rps": 3.833,
+ "first_recovery_seconds": 0.031,
+ "instances_after_stop": ["f383126bd2be"],
+ "ps_after": "api-2 Exited, api-1 healthy"
+ }
+ ]
+}
diff --git a/evidence/sequential_stop_api2.json b/evidence/sequential_stop_api2.json
new file mode 100644
index 00000000..6d82d977
--- /dev/null
+++ b/evidence/sequential_stop_api2.json
@@ -0,0 +1,14 @@
+{
+ "replicas": {
+ "mtusi-lab3-api-1": "f383126bd2be",
+ "mtusi-lab3-api-2": "46e274e33049"
+ },
+ "writes_ok": 46,
+ "writes_err": 1,
+ "first_recovery_s": 0.03141460000006191,
+ "instances_after_stop": [
+ "f383126bd2be"
+ ],
+ "ps_before": "mtusi-lab3-api-1 Up 23 seconds (healthy)\nmtusi-lab3-api-2 Up 23 seconds (healthy)\nmtusi-lab3-lb-1 Up 24 seconds (healthy)\nmtusi-lab3-migrate-1 Exited (0) 34 seconds ago\nmtusi-lab3-postgres-1 Up 23 seconds (healthy)\nmtusi-lab3-redis-1 Up 23 seconds (healthy)\n",
+ "ps_after": "mtusi-lab3-api-1 Up 36 seconds (healthy)\nmtusi-lab3-api-2 Exited (0) 12 seconds ago\nmtusi-lab3-lb-1 Up 37 seconds (healthy)\nmtusi-lab3-migrate-1 Exited (0) 48 seconds ago\nmtusi-lab3-postgres-1 Up 36 seconds (healthy)\nmtusi-lab3-redis-1 Up 37 seconds (healthy)\n"
+}
diff --git a/evidence/smoke.txt b/evidence/smoke.txt
new file mode 100644
index 00000000..8f8e66f6
--- /dev/null
+++ b/evidence/smoke.txt
@@ -0,0 +1,3 @@
+date: 2026-10-30T16:04:00Z
+command: python tests/smoke.py --base-url http://127.0.0.1:8080
+result: PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
diff --git a/evidence/track1.json b/evidence/track1.json
new file mode 100644
index 00000000..94be0b53
--- /dev/null
+++ b/evidence/track1.json
@@ -0,0 +1,295 @@
+{
+ "date": "2026-10-30T16:17:53Z",
+ "hypothesis": "При фиксированном суммарном CPU/RAM добавление API-реплик перестаёт помогать (и может снизить RPS), когда узкое место — CPU процессов API: PostgreSQL на этом профиле не насыщается.",
+ "profile": {
+ "duration_seconds": 20.0,
+ "concurrency": 8,
+ "warmup_seconds": 5.0,
+ "workload": "closed-loop POST /messages through HAProxy"
+ },
+ "fixed_total_budget": [
+ {
+ "elapsed_seconds": 20.907,
+ "concurrency": 8,
+ "successful_requests": 2678,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 128.093,
+ "successful_latency_ms": {
+ "p50": 51.921,
+ "p95": 108.599,
+ "p99": 156.367
+ },
+ "docker_stats": [
+ {
+ "name": "mtusi-lab3-api-4",
+ "cpu": "13.84%",
+ "mem": "89.5MiB / 512MiB"
+ },
+ {
+ "name": "mtusi-lab3-lb-1",
+ "cpu": "0.09%",
+ "mem": "28.19MiB / 64MiB"
+ },
+ {
+ "name": "mtusi-lab3-postgres-1",
+ "cpu": "0.06%",
+ "mem": "52.93MiB / 512MiB"
+ },
+ {
+ "name": "mtusi-lab3-redis-1",
+ "cpu": "2.34%",
+ "mem": "9.738MiB / 128MiB"
+ }
+ ],
+ "label": "fixed-1",
+ "replicas": 1,
+ "cpus_each": 1.0,
+ "memory_mb_each": 512,
+ "total_cpu": 1.0,
+ "total_memory_mb": 512
+ },
+ {
+ "elapsed_seconds": 20.894,
+ "concurrency": 8,
+ "successful_requests": 2246,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 107.496,
+ "successful_latency_ms": {
+ "p50": 71.633,
+ "p95": 189.116,
+ "p99": 245.528
+ },
+ "docker_stats": [
+ {
+ "name": "mtusi-lab3-api-5",
+ "cpu": "24.21%",
+ "mem": "72.12MiB / 256MiB"
+ },
+ {
+ "name": "mtusi-lab3-api-4",
+ "cpu": "0.71%",
+ "mem": "91.05MiB / 256MiB"
+ },
+ {
+ "name": "mtusi-lab3-lb-1",
+ "cpu": "0.31%",
+ "mem": "28.9MiB / 64MiB"
+ },
+ {
+ "name": "mtusi-lab3-postgres-1",
+ "cpu": "4.47%",
+ "mem": "73.19MiB / 512MiB"
+ },
+ {
+ "name": "mtusi-lab3-redis-1",
+ "cpu": "0.33%",
+ "mem": "9.035MiB / 128MiB"
+ }
+ ],
+ "label": "fixed-2",
+ "replicas": 2,
+ "cpus_each": 0.5,
+ "memory_mb_each": 256,
+ "total_cpu": 1.0,
+ "total_memory_mb": 512
+ },
+ {
+ "elapsed_seconds": 21.006,
+ "concurrency": 8,
+ "successful_requests": 1456,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 69.315,
+ "successful_latency_ms": {
+ "p50": 94.785,
+ "p95": 292.96,
+ "p99": 400.018
+ },
+ "docker_stats": [
+ {
+ "name": "mtusi-lab3-api-7",
+ "cpu": "16.08%",
+ "mem": "79.37MiB / 128MiB"
+ },
+ {
+ "name": "mtusi-lab3-api-6",
+ "cpu": "11.19%",
+ "mem": "76.64MiB / 128MiB"
+ },
+ {
+ "name": "mtusi-lab3-api-5",
+ "cpu": "8.82%",
+ "mem": "83.37MiB / 128MiB"
+ },
+ {
+ "name": "mtusi-lab3-api-4",
+ "cpu": "5.77%",
+ "mem": "98.27MiB / 128MiB"
+ },
+ {
+ "name": "mtusi-lab3-lb-1",
+ "cpu": "0.48%",
+ "mem": "29.2MiB / 64MiB"
+ },
+ {
+ "name": "mtusi-lab3-postgres-1",
+ "cpu": "0.05%",
+ "mem": "94.67MiB / 512MiB"
+ },
+ {
+ "name": "mtusi-lab3-redis-1",
+ "cpu": "2.17%",
+ "mem": "8.914MiB / 128MiB"
+ }
+ ],
+ "label": "fixed-4",
+ "replicas": 4,
+ "cpus_each": 0.25,
+ "memory_mb_each": 128,
+ "total_cpu": 1.0,
+ "total_memory_mb": 512
+ }
+ ],
+ "growing_resources": [
+ {
+ "elapsed_seconds": 21.009,
+ "concurrency": 8,
+ "successful_requests": 1031,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 49.073,
+ "successful_latency_ms": {
+ "p50": 111.033,
+ "p95": 302.796,
+ "p99": 399.196
+ },
+ "docker_stats": [
+ {
+ "name": "mtusi-lab3-api-5",
+ "cpu": "4.23%",
+ "mem": "76.67MiB / 128MiB"
+ },
+ {
+ "name": "mtusi-lab3-api-4",
+ "cpu": "0.43%",
+ "mem": "89.02MiB / 128MiB"
+ },
+ {
+ "name": "mtusi-lab3-lb-1",
+ "cpu": "0.13%",
+ "mem": "29.92MiB / 64MiB"
+ },
+ {
+ "name": "mtusi-lab3-postgres-1",
+ "cpu": "4.40%",
+ "mem": "76.54MiB / 512MiB"
+ },
+ {
+ "name": "mtusi-lab3-redis-1",
+ "cpu": "2.30%",
+ "mem": "9.145MiB / 128MiB"
+ }
+ ],
+ "label": "grow-2x0.25",
+ "replicas": 2,
+ "cpus_each": 0.25,
+ "memory_mb_each": 128,
+ "total_cpu": 0.5,
+ "total_memory_mb": 256
+ },
+ {
+ "elapsed_seconds": 20.917,
+ "concurrency": 8,
+ "successful_requests": 2206,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 105.463,
+ "successful_latency_ms": {
+ "p50": 75.963,
+ "p95": 184.365,
+ "p99": 212.521
+ },
+ "docker_stats": [
+ {
+ "name": "mtusi-lab3-api-5",
+ "cpu": "0.58%",
+ "mem": "83.3MiB / 256MiB"
+ },
+ {
+ "name": "mtusi-lab3-api-4",
+ "cpu": "18.11%",
+ "mem": "89.97MiB / 256MiB"
+ },
+ {
+ "name": "mtusi-lab3-lb-1",
+ "cpu": "4.50%",
+ "mem": "30.62MiB / 64MiB"
+ },
+ {
+ "name": "mtusi-lab3-postgres-1",
+ "cpu": "0.08%",
+ "mem": "78.58MiB / 512MiB"
+ },
+ {
+ "name": "mtusi-lab3-redis-1",
+ "cpu": "0.36%",
+ "mem": "9.082MiB / 128MiB"
+ }
+ ],
+ "label": "grow-2x0.50",
+ "replicas": 2,
+ "cpus_each": 0.5,
+ "memory_mb_each": 256,
+ "total_cpu": 1.0,
+ "total_memory_mb": 512
+ },
+ {
+ "elapsed_seconds": 20.827,
+ "concurrency": 8,
+ "successful_requests": 4602,
+ "failed_requests": 0,
+ "error_ratio": 0.0,
+ "successful_rps": 220.96,
+ "successful_latency_ms": {
+ "p50": 29.331,
+ "p95": 82.961,
+ "p99": 105.895
+ },
+ "docker_stats": [
+ {
+ "name": "mtusi-lab3-api-5",
+ "cpu": "1.21%",
+ "mem": "87.79MiB / 512MiB"
+ },
+ {
+ "name": "mtusi-lab3-api-4",
+ "cpu": "27.65%",
+ "mem": "90.96MiB / 512MiB"
+ },
+ {
+ "name": "mtusi-lab3-lb-1",
+ "cpu": "5.02%",
+ "mem": "31.52MiB / 64MiB"
+ },
+ {
+ "name": "mtusi-lab3-postgres-1",
+ "cpu": "0.18%",
+ "mem": "82.41MiB / 512MiB"
+ },
+ {
+ "name": "mtusi-lab3-redis-1",
+ "cpu": "0.35%",
+ "mem": "8.906MiB / 128MiB"
+ }
+ ],
+ "label": "grow-2x1.00",
+ "replicas": 2,
+ "cpus_each": 1.0,
+ "memory_mb_each": 512,
+ "total_cpu": 2.0,
+ "total_memory_mb": 1024
+ }
+ ]
+}
diff --git a/evidence/track1_fixed_budget.svg b/evidence/track1_fixed_budget.svg
new file mode 100644
index 00000000..e534d8df
--- /dev/null
+++ b/evidence/track1_fixed_budget.svg
@@ -0,0 +1,12 @@
+
diff --git a/evidence/track1_growing_cpu.svg b/evidence/track1_growing_cpu.svg
new file mode 100644
index 00000000..999106d1
--- /dev/null
+++ b/evidence/track1_growing_cpu.svg
@@ -0,0 +1,12 @@
+
diff --git a/infra/haproxy.cfg b/infra/haproxy.cfg
new file mode 100644
index 00000000..50a953b2
--- /dev/null
+++ b/infra/haproxy.cfg
@@ -0,0 +1,43 @@
+global
+ log stdout format raw local0
+ maxconn 4096
+
+defaults
+ log global
+ mode http
+ option httplog
+ option dontlognull
+ option http-keep-alive
+ timeout connect 500ms
+ timeout client 15s
+ timeout server 15s
+ timeout http-request 5s
+ timeout http-keep-alive 5s
+ timeout check 1s
+ retries 2
+
+resolvers docker
+ nameserver dns 127.0.0.11:53
+ resolve_retries 3
+ timeout resolve 1s
+ timeout retry 1s
+ hold other 2s
+ hold refused 2s
+ hold nx 2s
+ hold timeout 2s
+ hold valid 2s
+ hold obsolete 2s
+
+frontend public
+ bind *:8080
+ # Публичный live — процесс точки входа. Ready и бизнес-трафик идут на API.
+ http-request return status 200 content-type application/json hdr X-Request-Id "lb-live" hdr X-Instance-Id "load-balancer" string "{\"status\":\"ok\"}" if { path /health/live }
+ default_backend api
+
+backend api
+ balance roundrobin
+ option httpchk
+ http-check send meth GET uri /health/ready ver HTTP/1.1 hdr Host api
+ http-check expect status 200
+ default-server inter 1s fall 2 rise 1 resolvers docker resolve-prefer ipv4 init-addr none
+ server-template api 4 api:8080 check
diff --git a/migrations/001_initial.sql b/migrations/001_initial.sql
new file mode 100644
index 00000000..b9e03697
--- /dev/null
+++ b/migrations/001_initial.sql
@@ -0,0 +1,52 @@
+-- Пользователи, чаты, состав и сообщения. Пароли и тексты сообщений
+-- не пишутся приложением в логи. password_hash — только Argon2id.
+-- Сессии в этой схеме нет: их источник истины — Redis (см. compose.yaml).
+
+CREATE TABLE users (
+ id UUID PRIMARY KEY,
+ username TEXT NOT NULL,
+ display_name TEXT NOT NULL,
+ password_hash TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL,
+ CONSTRAINT uq_users_username UNIQUE (username),
+ CONSTRAINT ck_users_username_format CHECK (username ~ '^[a-z0-9_]{3,32}$'),
+ CONSTRAINT ck_users_display_name_len CHECK (
+ char_length(btrim(display_name)) >= 1 AND char_length(display_name) <= 100
+ ),
+ CONSTRAINT ck_users_password_hash_len CHECK (char_length(password_hash) >= 20)
+);
+
+CREATE TABLE chats (
+ id UUID PRIMARY KEY,
+ title TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL,
+ CONSTRAINT ck_chats_title CHECK (char_length(btrim(title)) >= 1 AND char_length(title) <= 100)
+);
+
+-- Состав чата пишется в той же транзакции, что и строка chats.
+-- Откат до COMMIT не оставляет чат без участников.
+CREATE TABLE chat_members (
+ chat_id UUID NOT NULL REFERENCES chats (id),
+ user_id UUID NOT NULL REFERENCES users (id),
+ ordinal SMALLINT NOT NULL,
+ PRIMARY KEY (chat_id, user_id),
+ CONSTRAINT ck_chat_members_ordinal CHECK (ordinal >= 0 AND ordinal < 100)
+);
+
+-- Список чатов пользователя: фильтр по user_id, затем порядок (created_at, id) чата.
+CREATE INDEX ix_chat_members_user ON chat_members (user_id, chat_id);
+
+CREATE TABLE messages (
+ id UUID PRIMARY KEY,
+ chat_id UUID NOT NULL REFERENCES chats (id),
+ sender_id UUID NOT NULL REFERENCES users (id),
+ body TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL,
+ CONSTRAINT ck_messages_text CHECK (char_length(btrim(body)) >= 1 AND char_length(body) <= 4000)
+);
+
+-- История: WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
+-- ORDER BY created_at, id LIMIT $4.
+-- Ведущий chat_id отсекает чужие чаты, пара (created_at, id) продолжает
+-- keyset с cursor и не читает предыдущие строки этой истории.
+CREATE INDEX ix_messages_history ON messages (chat_id, created_at, id);
diff --git a/migrations/002_idempotency.sql b/migrations/002_idempotency.sql
new file mode 100644
index 00000000..f7cbcf54
--- /dev/null
+++ b/migrations/002_idempotency.sql
@@ -0,0 +1,22 @@
+-- Общая идемпотентность POST сообщения для всех API-реплик.
+-- Результат пишется в той же транзакции, что и messages: 5xx не сохраняется.
+
+CREATE TABLE idempotency_records (
+ user_id UUID NOT NULL REFERENCES users (id),
+ method TEXT NOT NULL,
+ request_path TEXT NOT NULL,
+ idempotency_key TEXT NOT NULL,
+ request_hash TEXT NOT NULL,
+ status_code SMALLINT NOT NULL,
+ message_id UUID NOT NULL REFERENCES messages (id),
+ created_at TIMESTAMPTZ NOT NULL,
+ PRIMARY KEY (user_id, method, request_path, idempotency_key),
+ CONSTRAINT ck_idem_method CHECK (method = 'POST'),
+ CONSTRAINT ck_idem_status CHECK (status_code = 201),
+ CONSTRAINT ck_idem_key CHECK (idempotency_key ~ '^[A-Za-z0-9._:-]{1,128}$'),
+ CONSTRAINT ck_idem_path CHECK (char_length(request_path) BETWEEN 1 AND 300),
+ CONSTRAINT ck_idem_hash CHECK (char_length(request_hash) = 64)
+);
+
+CREATE INDEX ix_idempotency_message ON idempotency_records (message_id);
+CREATE INDEX ix_idempotency_created ON idempotency_records (created_at);
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 00000000..876fcfeb
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,9 @@
+fastapi==0.115.6
+uvicorn==0.34.0
+sqlalchemy==2.0.36
+greenlet==3.1.1
+asyncpg==0.30.0
+redis==5.2.1
+argon2-cffi==23.1.0
+pydantic==2.10.4
+starlette==0.41.3
diff --git a/scripts/bootstrap.ps1 b/scripts/bootstrap.ps1
new file mode 100644
index 00000000..6d5cadcc
--- /dev/null
+++ b/scripts/bootstrap.ps1
@@ -0,0 +1,21 @@
+$ErrorActionPreference = "Stop"
+$Root = Split-Path -Parent $PSScriptRoot
+if (-not $Root) { $Root = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path }
+Set-Location $Root
+New-Item -ItemType Directory -Force -Path "secrets" | Out-Null
+$passFile = Join-Path $Root "secrets\postgres_password"
+if (-not (Test-Path $passFile)) {
+ $bytes = New-Object byte[] 24
+ [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
+ $password = [Convert]::ToBase64String($bytes).TrimEnd("=").Replace("+","-").Replace("/","_")
+ Set-Content -Path $passFile -Value $password -NoNewline -Encoding ascii
+}
+$password = ((Get-Content -Raw $passFile) -replace "`r","" -replace "`n","").Trim()
+Set-Content -Path (Join-Path $Root "secrets\database_url") -Value "postgresql+asyncpg://messenger:${password}@postgres:5432/messenger" -NoNewline -Encoding ascii
+Set-Content -Path (Join-Path $Root "secrets\host_database_url") -Value "postgresql+asyncpg://messenger:${password}@127.0.0.1:5433/messenger" -NoNewline -Encoding ascii
+Set-Content -Path (Join-Path $Root "secrets\cache_url") -Value "redis://redis:6379/0" -NoNewline -Encoding ascii
+Set-Content -Path (Join-Path $Root "secrets\host_cache_url") -Value "redis://127.0.0.1:6379/0" -NoNewline -Encoding ascii
+if (-not (Test-Path (Join-Path $Root ".env"))) {
+ Copy-Item (Join-Path $Root ".env.example") (Join-Path $Root ".env")
+}
+Write-Output "secrets and .env are ready"
diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh
new file mode 100644
index 00000000..9e3fb528
--- /dev/null
+++ b/scripts/bootstrap.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+set -eu
+ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+cd "$ROOT"
+mkdir -p secrets
+if [ ! -f secrets/postgres_password ]; then
+ python -c "import secrets,pathlib; pathlib.Path('secrets/postgres_password').write_text(secrets.token_urlsafe(24)+'\n', encoding='utf-8')"
+fi
+PASSWORD=$(tr -d '\r\n' < secrets/postgres_password)
+printf '%s\n' "postgresql+asyncpg://messenger:${PASSWORD}@postgres:5432/messenger" > secrets/database_url
+printf '%s\n' "postgresql+asyncpg://messenger:${PASSWORD}@127.0.0.1:5433/messenger" > secrets/host_database_url
+printf '%s\n' "redis://redis:6379/0" > secrets/cache_url
+printf '%s\n' "redis://127.0.0.1:6379/0" > secrets/host_cache_url
+if [ ! -f .env ]; then
+ cp .env.example .env
+fi
+printf '%s\n' "secrets and .env are ready"
diff --git a/scripts/restart.cmd b/scripts/restart.cmd
new file mode 100644
index 00000000..bb58e043
--- /dev/null
+++ b/scripts/restart.cmd
@@ -0,0 +1,5 @@
+@echo off
+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 100644
index 00000000..280b1bf9
--- /dev/null
+++ b/scripts/restart.sh
@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+cd "$ROOT"
+docker compose --env-file .env restart postgres redis api lb
diff --git a/scripts/restore-api.cmd b/scripts/restore-api.cmd
new file mode 100644
index 00000000..1c25a6db
--- /dev/null
+++ b/scripts/restore-api.cmd
@@ -0,0 +1,7 @@
+@echo off
+setlocal
+cd /d "%~dp0.."
+if "%API_REPLICAS%"=="" set API_REPLICAS=2
+docker compose --env-file .env start api
+docker compose --env-file .env up -d --no-deps --scale api=%API_REPLICAS% api
+exit /b %ERRORLEVEL%
diff --git a/scripts/restore-api.sh b/scripts/restore-api.sh
new file mode 100644
index 00000000..6ef0ce84
--- /dev/null
+++ b/scripts/restore-api.sh
@@ -0,0 +1,6 @@
+#!/bin/sh
+set -eu
+ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+cd "$ROOT"
+docker compose --env-file .env start api
+docker compose --env-file .env up -d --no-deps --scale "api=${API_REPLICAS:-2}" api
diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh
new file mode 100644
index 00000000..8e91582f
--- /dev/null
+++ b/scripts/rolling-update.sh
@@ -0,0 +1,45 @@
+#!/bin/sh
+set -eu
+ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+cd "$ROOT"
+REPLICAS=$(docker compose ps -q api | wc -l | tr -d ' ')
+if [ "$REPLICAS" -lt 2 ]; then
+ printf '%s\n' "need at least two API replicas" >&2
+ exit 1
+fi
+docker compose --env-file .env build api
+old_ids=$(docker compose ps -q api)
+for old in $old_ids; do
+ next=$((REPLICAS + 1))
+ docker compose --env-file .env up -d --no-deps --scale "api=${next}" --no-recreate api
+ deadline=$(( $(date +%s) + 60 ))
+ while [ "$(docker compose ps -q api | wc -l | tr -d ' ')" -lt "$next" ]; do
+ if [ "$(date +%s)" -ge "$deadline" ]; then
+ printf '%s\n' "new replica did not appear" >&2
+ exit 1
+ fi
+ sleep 1
+ done
+ docker stop -t 5 "$old" >/dev/null
+ docker rm "$old" >/dev/null
+ docker compose --env-file .env up -d --no-deps --scale "api=${REPLICAS}" api
+done
+deadline=$(( $(date +%s) + 60 ))
+until docker compose exec -T lb sh -c 'true' >/dev/null 2>&1; do
+ sleep 1
+done
+python -c "
+import json,urllib.request,time
+deadline=time.time()+60
+last=''
+while time.time()&2
+ exit /b 2
+)
+for /f "delims=" %%I in ('docker compose ps -aq -- api') do (
+ for /f "delims=" %%H in ('docker inspect -f "{{.Config.Hostname}}" %%I') do (
+ if /I "%%H"=="%TARGET_INSTANCE_ID%" (
+ docker stop -t 5 %%I >nul
+ exit /b 0
+ )
+ )
+)
+echo no API replica matches TARGET_INSTANCE_ID 1>&2
+exit /b 1
diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh
new file mode 100644
index 00000000..09ff3cc4
--- /dev/null
+++ b/scripts/stop-one.sh
@@ -0,0 +1,27 @@
+#!/bin/sh
+set -eu
+: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
+ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+cd "$ROOT"
+found=""
+for id in $(docker compose ps -aq -- api); do
+ hostname=$(docker inspect -f '{{.Config.Hostname}}' "$id")
+ name=$(docker inspect -f '{{.Name}}' "$id")
+ name=${name#/}
+ cid=$(docker inspect -f '{{.Id}}' "$id")
+ short=$(printf '%s' "$cid" | cut -c1-12)
+ if [ "$TARGET_INSTANCE_ID" = "$hostname" ] \
+ || [ "$TARGET_INSTANCE_ID" = "$name" ] \
+ || [ "$TARGET_INSTANCE_ID" = "$id" ] \
+ || [ "$TARGET_INSTANCE_ID" = "$cid" ] \
+ || [ "$TARGET_INSTANCE_ID" = "$short" ]; then
+ found=$id
+ break
+ fi
+done
+if [ -z "$found" ]; then
+ printf '%s\n' "no API replica matches TARGET_INSTANCE_ID" >&2
+ exit 1
+fi
+docker stop -t 5 "$found" >/dev/null
+exit 0
diff --git a/scripts/up.ps1 b/scripts/up.ps1
new file mode 100644
index 00000000..97d9e797
--- /dev/null
+++ b/scripts/up.ps1
@@ -0,0 +1,6 @@
+$ErrorActionPreference = "Stop"
+$Root = Split-Path -Parent $PSScriptRoot
+Set-Location $Root
+if (-not $env:API_REPLICAS) { $env:API_REPLICAS = "2" }
+docker compose --env-file .env up -d --build --wait --scale "api=$($env:API_REPLICAS)"
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
diff --git a/scripts/up.sh b/scripts/up.sh
new file mode 100644
index 00000000..9b41f34d
--- /dev/null
+++ b/scripts/up.sh
@@ -0,0 +1,6 @@
+#!/bin/sh
+set -eu
+ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+cd "$ROOT"
+REPLICAS=${API_REPLICAS:-2}
+docker compose --env-file .env up -d --build --wait --scale "api=${REPLICAS}"
diff --git a/src/app/__init__.py b/src/app/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/app/__main__.py b/src/app/__main__.py
new file mode 100644
index 00000000..9472a36b
--- /dev/null
+++ b/src/app/__main__.py
@@ -0,0 +1,40 @@
+import logging
+import sys
+
+import uvicorn
+
+from app.config import load_settings
+
+
+def main() -> None:
+ settings = load_settings()
+ logging.basicConfig(
+ level=logging.INFO,
+ format="%(asctime)s %(levelname)s %(name)s %(message)s",
+ stream=sys.stdout,
+ force=True,
+ )
+ logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
+ logging.getLogger("sqlalchemy.pool").setLevel(logging.WARNING)
+ logging.getLogger("asyncpg").setLevel(logging.WARNING)
+ logging.getLogger("app").info(
+ "starting host=%s port=%s env=%s instance_id=%s",
+ settings.host,
+ settings.port,
+ settings.env,
+ settings.instance_id,
+ )
+ uvicorn.run(
+ "app.main:app",
+ host=settings.host,
+ port=settings.port,
+ workers=1,
+ access_log=False,
+ timeout_keep_alive=5,
+ timeout_graceful_shutdown=5,
+ log_config=None,
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/src/app/api/__init__.py b/src/app/api/__init__.py
new file mode 100644
index 00000000..abb38bb2
--- /dev/null
+++ b/src/app/api/__init__.py
@@ -0,0 +1,12 @@
+from fastapi import APIRouter
+
+from app.api.auth import router as auth_router
+from app.api.chats import router as chats_router
+from app.api.messages import router as messages_router
+from app.api.users import router as users_router
+
+api_router = APIRouter(prefix="/api/v1")
+api_router.include_router(users_router)
+api_router.include_router(auth_router)
+api_router.include_router(chats_router)
+api_router.include_router(messages_router)
diff --git a/src/app/api/auth.py b/src/app/api/auth.py
new file mode 100644
index 00000000..b41dbb20
--- /dev/null
+++ b/src/app/api/auth.py
@@ -0,0 +1,37 @@
+from fastapi import APIRouter, Depends, Header
+from starlette.responses import Response
+
+from app.crud.users import authenticate
+from app.deps import BASIC_CHALLENGE, BEARER_CHALLENGE, require_token, unauthorized
+from app.schemas.session import SessionOut
+from app.security import parse_basic, verify_password
+from app.sessions import create_session, revoke_session
+from app.timeutil import format_time
+
+router = APIRouter()
+
+
+@router.post("/auth/sessions", status_code=201, response_model=SessionOut)
+async def create_session_route(authorization: str | None = Header(default=None)) -> dict:
+ parsed = parse_basic(authorization or "")
+ if parsed is None:
+ verify_password("invalid-basic-auth", None)
+ raise unauthorized(BASIC_CHALLENGE)
+ username, password = parsed
+ user = await authenticate(username, password)
+ if user is None:
+ raise unauthorized(BASIC_CHALLENGE)
+ token, expires_at = await create_session(user.id)
+ return {
+ "token": token,
+ "token_type": "Bearer",
+ "expires_at": format_time(expires_at),
+ "user": user.to_dict(),
+ }
+
+
+@router.delete("/auth/sessions/current", status_code=204)
+async def revoke_current_session(token: str = Depends(require_token)) -> Response:
+ if not await revoke_session(token):
+ raise unauthorized(BEARER_CHALLENGE)
+ return Response(status_code=204)
diff --git a/src/app/api/chats.py b/src/app/api/chats.py
new file mode 100644
index 00000000..9015540d
--- /dev/null
+++ b/src/app/api/chats.py
@@ -0,0 +1,31 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query
+
+from app.crud.chats import chat_for_member, chats_for_user, create_chat as save_chat
+from app.deps import get_current_user
+from app.present import PublicUser
+from app.schemas.chat import ChatOut, ChatPage, CreateChat
+
+router = APIRouter()
+
+
+@router.post("/chats", status_code=201, response_model=ChatOut)
+async def create_chat(body: CreateChat, user: PublicUser = Depends(get_current_user)) -> dict:
+ chat = await save_chat(user.id, body.title, tuple(body.member_ids))
+ return chat.to_dict()
+
+
+@router.get("/chats", response_model=ChatPage)
+async def list_chats(
+ user: PublicUser = Depends(get_current_user),
+ limit: int = Query(default=50, ge=1, le=100),
+ cursor: str | None = Query(default=None, min_length=1),
+) -> dict:
+ return await chats_for_user(user.id, limit, cursor)
+
+
+@router.get("/chats/{chat_id}", response_model=ChatOut)
+async def get_chat(chat_id: UUID, user: PublicUser = Depends(get_current_user)) -> dict:
+ chat = await chat_for_member(chat_id, user.id)
+ return chat.to_dict()
diff --git a/src/app/api/health.py b/src/app/api/health.py
new file mode 100644
index 00000000..8e61555a
--- /dev/null
+++ b/src/app/api/health.py
@@ -0,0 +1,39 @@
+import logging
+
+from fastapi import APIRouter, Request
+from pydantic import BaseModel
+from sqlalchemy import text
+
+from app.db import is_dependency_error
+from app.errors import AppError
+
+router = APIRouter()
+logger = logging.getLogger("app.health")
+
+
+class HealthOut(BaseModel):
+ status: str
+
+
+@router.get("/health/live", response_model=HealthOut)
+async def live() -> dict:
+ return {"status": "ok"}
+
+
+@router.get("/health/ready", response_model=HealthOut)
+async def ready(request: Request) -> dict:
+ if not getattr(request.app.state, "accepting", False):
+ raise AppError(503, "unavailable", "Сервер не готов")
+ engine = getattr(request.app.state, "engine", None)
+ redis = getattr(request.app.state, "redis", None)
+ if engine is None or redis is None:
+ raise AppError(503, "unavailable", "Сервис временно недоступен")
+ try:
+ async with engine.connect() as conn:
+ await conn.execute(text("SELECT 1"))
+ await redis.ping()
+ except Exception as exc:
+ if not is_dependency_error(exc):
+ logger.warning("readiness check failed type=%s", type(exc).__name__)
+ raise AppError(503, "unavailable", "Сервис временно недоступен") from None
+ return {"status": "ok"}
diff --git a/src/app/api/messages.py b/src/app/api/messages.py
new file mode 100644
index 00000000..04181be7
--- /dev/null
+++ b/src/app/api/messages.py
@@ -0,0 +1,43 @@
+import re
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query, Request
+
+from app.crud.messages import create_message as save_message
+from app.crud.messages import messages_for_member
+from app.deps import get_current_user
+from app.errors import AppError
+from app.present import PublicUser
+from app.schemas.message import CreateMessage, MessageOut, MessagePage
+
+router = APIRouter()
+_IDEMPOTENCY_KEY = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
+
+
+def require_idempotency_key(request: Request) -> str:
+ value = request.headers.get("idempotency-key")
+ if value is None or _IDEMPOTENCY_KEY.fullmatch(value) is None:
+ raise AppError(400, "invalid_request", "Некорректный Idempotency-Key")
+ return value
+
+
+@router.post("/chats/{chat_id}/messages", status_code=201, response_model=MessageOut)
+async def create_message(
+ chat_id: UUID,
+ body: CreateMessage,
+ request: Request,
+ user: PublicUser = Depends(get_current_user),
+) -> dict:
+ key = require_idempotency_key(request)
+ message = await save_message(chat_id, user.id, body.text, key)
+ return message.to_dict()
+
+
+@router.get("/chats/{chat_id}/messages", response_model=MessagePage)
+async def list_messages(
+ chat_id: UUID,
+ user: PublicUser = Depends(get_current_user),
+ limit: int = Query(default=50, ge=1, le=100),
+ cursor: str | None = Query(default=None, min_length=1),
+) -> dict:
+ return await messages_for_member(chat_id, user.id, limit, cursor)
diff --git a/src/app/api/users.py b/src/app/api/users.py
new file mode 100644
index 00000000..72a90b27
--- /dev/null
+++ b/src/app/api/users.py
@@ -0,0 +1,19 @@
+from fastapi import APIRouter, Depends
+
+from app.crud.users import create_user
+from app.deps import get_current_user
+from app.present import PublicUser
+from app.schemas.user import CreateUser, UserOut
+
+router = APIRouter()
+
+
+@router.post("/users", status_code=201, response_model=UserOut)
+async def register(body: CreateUser) -> dict:
+ user = await create_user(body.username, body.display_name, body.password)
+ return user.to_dict()
+
+
+@router.get("/users/me", response_model=UserOut)
+async def me(user: PublicUser = Depends(get_current_user)) -> dict:
+ return user.to_dict()
diff --git a/src/app/config.py b/src/app/config.py
new file mode 100644
index 00000000..3703969c
--- /dev/null
+++ b/src/app/config.py
@@ -0,0 +1,130 @@
+import os
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Settings:
+ host: str
+ port: int
+ env: str
+ app_role: str
+ instance_id: str
+ run_migrations: bool
+ session_ttl_seconds: int
+ idempotency_ttl_seconds: int
+ database_url: str
+ cache_url: str
+ migrations_dir: Path
+ db_pool_size: int
+ db_max_overflow: int
+ db_pool_timeout_seconds: float
+ db_connect_timeout_seconds: float
+ db_command_timeout_seconds: float
+ redis_socket_timeout_seconds: float
+ redis_max_connections: int
+
+
+def _int(name: str, default: int, low: int, high: int) -> int:
+ raw = os.environ.get(name, str(default)).strip()
+ try:
+ value = int(raw)
+ except ValueError as exc:
+ raise SystemExit(f"{name} must be an integer") from exc
+ if not low <= value <= high:
+ raise SystemExit(f"{name} is out of range")
+ return value
+
+
+def _float(name: str, default: float, low: float, high: float) -> float:
+ raw = os.environ.get(name, str(default)).strip()
+ try:
+ value = float(raw)
+ except ValueError as exc:
+ raise SystemExit(f"{name} must be a number") from exc
+ if not low <= value <= high:
+ raise SystemExit(f"{name} is out of range")
+ return value
+
+
+def _secret(direct_name: str, file_name: str) -> str:
+ direct = os.environ.get(direct_name, "").strip()
+ if direct:
+ return direct
+ path = os.environ.get(file_name, "").strip()
+ if not path:
+ raise SystemExit(f"set {direct_name} or {file_name}")
+ try:
+ value = Path(path).read_text(encoding="utf-8").strip()
+ except OSError as exc:
+ raise SystemExit(f"cannot read {file_name}") from exc
+ if not value:
+ raise SystemExit(f"{file_name} is empty")
+ return value
+
+
+def _migrations_dir() -> Path:
+ configured = os.environ.get("MIGRATIONS_DIR", "").strip()
+ if configured:
+ return Path(configured)
+ return Path(__file__).resolve().parents[2] / "migrations"
+
+
+def _flag(name: str, default: bool) -> bool:
+ raw = os.environ.get(name, "1" if default else "0").strip().lower()
+ if raw in {"1", "true", "yes", "on"}:
+ return True
+ if raw in {"0", "false", "no", "off"}:
+ return False
+ raise SystemExit(f"{name} must be a boolean")
+
+
+def _instance_id() -> str:
+ configured = os.environ.get("INSTANCE_ID", "").strip()
+ if configured:
+ return configured
+ host = os.environ.get("HOSTNAME", "").strip() or socket.gethostname()
+ if not host:
+ raise SystemExit("INSTANCE_ID is empty")
+ return host
+
+
+def load_settings() -> Settings:
+ host = os.environ.get("APP_HOST", "0.0.0.0").strip() or "0.0.0.0"
+ env_name = os.environ.get("APP_ENV", "lab").strip() or "lab"
+ role = os.environ.get("APP_ROLE", "api").strip() or "api"
+ if role not in {"api", "migrate"}:
+ raise SystemExit("APP_ROLE must be api or migrate")
+ port = _int("APP_PORT", 8080, 1, 65535)
+ database_url = _secret("DATABASE_URL", "DATABASE_URL_FILE")
+ cache_url = ""
+ if role != "migrate":
+ cache_url = _secret("REDIS_URL", "CACHE_URL_FILE")
+ if not cache_url.startswith(("redis://", "rediss://")):
+ raise SystemExit("REDIS_URL must start with redis:// or rediss://")
+ if not database_url.startswith("postgresql+asyncpg://"):
+ raise SystemExit("DATABASE_URL must start with postgresql+asyncpg://")
+ migrations = _migrations_dir()
+ if not migrations.is_dir():
+ raise SystemExit("migrations directory is missing")
+ return Settings(
+ host=host,
+ port=port,
+ env=env_name,
+ app_role=role,
+ instance_id=_instance_id(),
+ run_migrations=_flag("RUN_MIGRATIONS", True),
+ session_ttl_seconds=_int("SESSION_TTL_SECONDS", 3600, 1, 30 * 24 * 3600),
+ idempotency_ttl_seconds=_int("IDEMPOTENCY_TTL_SECONDS", 86400, 60, 30 * 24 * 3600),
+ database_url=database_url,
+ cache_url=cache_url,
+ migrations_dir=migrations,
+ db_pool_size=_int("DB_POOL_SIZE", 10, 1, 50),
+ db_max_overflow=_int("DB_MAX_OVERFLOW", 10, 0, 50),
+ db_pool_timeout_seconds=_float("DB_POOL_TIMEOUT_SECONDS", 5, 0.1, 30),
+ db_connect_timeout_seconds=_float("DB_CONNECT_TIMEOUT_SECONDS", 2, 0.1, 30),
+ db_command_timeout_seconds=_float("DB_COMMAND_TIMEOUT_SECONDS", 5, 0.1, 60),
+ redis_socket_timeout_seconds=_float("REDIS_SOCKET_TIMEOUT_SECONDS", 1, 0.1, 30),
+ redis_max_connections=_int("REDIS_MAX_CONNECTIONS", 50, 1, 200),
+ )
diff --git a/src/app/crud/__init__.py b/src/app/crud/__init__.py
new file mode 100644
index 00000000..cbee6a29
--- /dev/null
+++ b/src/app/crud/__init__.py
@@ -0,0 +1 @@
+"""Чтение и изменение PostgreSQL. Сессии живут в Redis, не в этих таблицах."""
diff --git a/src/app/crud/chats.py b/src/app/crud/chats.py
new file mode 100644
index 00000000..5bd42e9f
--- /dev/null
+++ b/src/app/crud/chats.py
@@ -0,0 +1,101 @@
+from uuid import UUID, uuid4
+
+from sqlalchemy import select, tuple_
+from sqlalchemy.exc import IntegrityError
+
+from app.db import map_integrity, session_scope
+from app.errors import AppError
+from app.models import Chat, ChatMember, User
+from app.pagination import decode_position, slice_page
+from app.present import PublicChat
+from app.timeutil import utcnow
+
+
+def _invalid_members() -> AppError:
+ return AppError(400, "invalid_request", "Некорректный список участников")
+
+
+async def create_chat(
+ owner_id: UUID,
+ title: str,
+ member_ids: tuple[UUID, ...],
+ *,
+ fail_after_insert: bool = False,
+) -> PublicChat:
+ if (
+ not member_ids
+ or len(member_ids) > 100
+ or len(set(member_ids)) != len(member_ids)
+ or owner_id not in member_ids
+ ):
+ raise _invalid_members()
+ chat_id = uuid4()
+ created_at = utcnow()
+ async with session_scope() as session:
+ try:
+ async with session.begin():
+ found = set((await session.scalars(select(User.id).where(User.id.in_(member_ids)))).all())
+ if found != set(member_ids):
+ raise _invalid_members()
+ session.add(Chat(id=chat_id, title=title, created_at=created_at))
+ await session.flush()
+ # Точка для проверки отката: строка чата уже вставлена, COMMIT ещё нет.
+ if fail_after_insert:
+ raise RuntimeError("rollback-check")
+ for ordinal, member_id in enumerate(member_ids):
+ session.add(ChatMember(chat_id=chat_id, user_id=member_id, ordinal=ordinal))
+ await session.flush()
+ except IntegrityError as exc:
+ raise map_integrity(exc, "Конфликт записи") from None
+ return PublicChat(id=chat_id, title=title, member_ids=tuple(member_ids), created_at=created_at)
+
+
+async def _member_ids(session, chat_id: UUID) -> tuple[UUID, ...]:
+ rows = await session.execute(
+ select(ChatMember.user_id).where(ChatMember.chat_id == chat_id).order_by(ChatMember.ordinal)
+ )
+ return tuple(row[0] for row in rows)
+
+
+async def chat_for_member(chat_id: UUID, user_id: UUID) -> PublicChat:
+ async with session_scope() as session:
+ async with session.begin():
+ member = await session.scalar(
+ select(ChatMember.user_id).where(ChatMember.chat_id == chat_id, ChatMember.user_id == user_id)
+ )
+ chat = await session.get(Chat, chat_id)
+ if member is None or chat is None:
+ raise AppError(404, "not_found", "Объект не найден")
+ return PublicChat(
+ id=chat.id,
+ title=chat.title,
+ member_ids=await _member_ids(session, chat.id),
+ created_at=chat.created_at,
+ )
+
+
+async def chats_for_user(user_id: UUID, limit: int, cursor: str | None) -> dict:
+ position = decode_position(cursor, "c", user_id) if cursor else None
+ async with session_scope() as session:
+ async with session.begin():
+ stmt = (
+ select(Chat)
+ .join(ChatMember, ChatMember.chat_id == Chat.id)
+ .where(ChatMember.user_id == user_id)
+ )
+ if position is not None:
+ created_at, cursor_id = position
+ stmt = stmt.where(tuple_(Chat.created_at, Chat.id) > tuple_(created_at, cursor_id))
+ stmt = stmt.order_by(Chat.created_at.asc(), Chat.id.asc()).limit(limit + 1)
+ chats = (await session.scalars(stmt)).unique().all()
+ public = []
+ for chat in chats:
+ public.append(
+ PublicChat(
+ id=chat.id,
+ title=chat.title,
+ member_ids=await _member_ids(session, chat.id),
+ created_at=chat.created_at,
+ )
+ )
+ return slice_page(public, limit, "c", user_id)
diff --git a/src/app/crud/messages.py b/src/app/crud/messages.py
new file mode 100644
index 00000000..926b1943
--- /dev/null
+++ b/src/app/crud/messages.py
@@ -0,0 +1,145 @@
+import hashlib
+import json
+from datetime import timedelta
+from uuid import UUID, uuid4
+
+from sqlalchemy import delete, select, text, tuple_
+from sqlalchemy.exc import IntegrityError
+
+from app.db import map_integrity, session_scope
+from app.errors import AppError
+from app.models import ChatMember, IdempotencyRecord, Message
+from app.pagination import decode_position, slice_page
+from app.present import PublicMessage
+from app.runtime import require_settings
+from app.timeutil import utcnow
+
+
+def message_path(chat_id: UUID) -> str:
+ return "/api/v1/chats/%s/messages" % chat_id
+
+
+def request_fingerprint(text_value: str) -> str:
+ payload = json.dumps({"text": text_value}, ensure_ascii=False, separators=(",", ":"))
+ return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _lock_keys(scope: str) -> tuple[int, int]:
+ digest = hashlib.sha256(scope.encode("utf-8")).digest()
+ first = int.from_bytes(digest[:4], "big", signed=True)
+ second = int.from_bytes(digest[4:8], "big", signed=True)
+ return first, second
+
+
+def _public(row: Message) -> PublicMessage:
+ return PublicMessage(
+ id=row.id,
+ chat_id=row.chat_id,
+ sender_id=row.sender_id,
+ text=row.text,
+ created_at=row.created_at,
+ )
+
+
+async def _require_member(session, chat_id: UUID, user_id: UUID) -> None:
+ member = await session.scalar(
+ select(ChatMember.user_id).where(ChatMember.chat_id == chat_id, ChatMember.user_id == user_id)
+ )
+ if member is None:
+ raise AppError(404, "not_found", "Объект не найден")
+
+
+async def create_message(
+ chat_id: UUID,
+ sender_id: UUID,
+ text_value: str,
+ idempotency_key: str,
+) -> PublicMessage:
+ settings = require_settings()
+ path = message_path(chat_id)
+ request_hash = request_fingerprint(text_value)
+ lock_a, lock_b = _lock_keys("POST:%s:%s:%s" % (sender_id, path, idempotency_key))
+ ttl = timedelta(seconds=settings.idempotency_ttl_seconds)
+ async with session_scope() as session:
+ try:
+ async with session.begin():
+ await session.execute(
+ text("SELECT pg_advisory_xact_lock(:a, :b)"),
+ {"a": lock_a, "b": lock_b},
+ )
+ await _require_member(session, chat_id, sender_id)
+ existing = await session.scalar(
+ select(IdempotencyRecord).where(
+ IdempotencyRecord.user_id == sender_id,
+ IdempotencyRecord.method == "POST",
+ IdempotencyRecord.request_path == path,
+ IdempotencyRecord.idempotency_key == idempotency_key,
+ )
+ )
+ now = utcnow()
+ if existing is not None and existing.created_at + ttl >= now:
+ if existing.request_hash != request_hash:
+ raise AppError(409, "conflict", "Повтор ключа с другим сообщением")
+ row = await session.get(Message, existing.message_id)
+ if row is None:
+ raise AppError(500, "internal_error", "Внутренняя ошибка")
+ return _public(row)
+ if existing is not None:
+ await session.execute(
+ delete(IdempotencyRecord).where(
+ IdempotencyRecord.user_id == existing.user_id,
+ IdempotencyRecord.method == existing.method,
+ IdempotencyRecord.request_path == existing.request_path,
+ IdempotencyRecord.idempotency_key == existing.idempotency_key,
+ )
+ )
+ await session.flush()
+ message_id = uuid4()
+ created_at = now
+ session.add(
+ Message(
+ id=message_id,
+ chat_id=chat_id,
+ sender_id=sender_id,
+ text=text_value,
+ created_at=created_at,
+ )
+ )
+ await session.flush()
+ session.add(
+ IdempotencyRecord(
+ user_id=sender_id,
+ method="POST",
+ request_path=path,
+ idempotency_key=idempotency_key,
+ request_hash=request_hash,
+ status_code=201,
+ message_id=message_id,
+ created_at=created_at,
+ )
+ )
+ await session.flush()
+ except IntegrityError as exc:
+ raise map_integrity(exc, "Конфликт записи") from None
+ return PublicMessage(
+ id=message_id,
+ chat_id=chat_id,
+ sender_id=sender_id,
+ text=text_value,
+ created_at=created_at,
+ )
+
+
+async def messages_for_member(chat_id: UUID, user_id: UUID, limit: int, cursor: str | None) -> dict:
+ async with session_scope() as session:
+ async with session.begin():
+ await _require_member(session, chat_id, user_id)
+ position = decode_position(cursor, "m", chat_id) if cursor else None
+ stmt = select(Message).where(Message.chat_id == chat_id)
+ if position is not None:
+ created_at, message_id = position
+ stmt = stmt.where(tuple_(Message.created_at, Message.id) > tuple_(created_at, message_id))
+ stmt = stmt.order_by(Message.created_at.asc(), Message.id.asc()).limit(limit + 1)
+ rows = (await session.scalars(stmt)).all()
+ public = [_public(row) for row in rows]
+ return slice_page(public, limit, "m", chat_id)
diff --git a/src/app/crud/users.py b/src/app/crud/users.py
new file mode 100644
index 00000000..884381fc
--- /dev/null
+++ b/src/app/crud/users.py
@@ -0,0 +1,78 @@
+import re
+from uuid import UUID, uuid4
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+
+from app.db import map_integrity, session_scope
+from app.models import User
+from app.present import PublicUser
+from app.security import hash_password, verify_password
+from app.timeutil import utcnow
+
+_USERNAME = re.compile(r"^[a-z0-9_]{3,32}$")
+
+
+async def get_user(user_id: UUID) -> PublicUser | None:
+ async with session_scope() as session:
+ async with session.begin():
+ row = (
+ await session.execute(
+ select(User.id, User.username, User.display_name, User.created_at).where(User.id == user_id)
+ )
+ ).one_or_none()
+ if row is None:
+ return None
+ return PublicUser(id=row.id, username=row.username, display_name=row.display_name, created_at=row.created_at)
+
+
+async def create_user(username: str, display_name: str, password: str) -> PublicUser:
+ # Argon2 считается до открытия транзакции, чтобы не держать соединение пула.
+ password_hash = hash_password(password)
+ user_id = uuid4()
+ created_at = utcnow()
+ async with session_scope() as session:
+ try:
+ async with session.begin():
+ session.add(
+ User(
+ id=user_id,
+ username=username,
+ display_name=display_name,
+ password_hash=password_hash,
+ created_at=created_at,
+ )
+ )
+ await session.flush()
+ except IntegrityError as exc:
+ raise map_integrity(exc, "Имя пользователя занято") from None
+ return PublicUser(id=user_id, username=username, display_name=display_name, created_at=created_at)
+
+
+async def authenticate(username: str, password: str) -> PublicUser | None:
+ if _USERNAME.fullmatch(username) is None or not 12 <= len(password) <= 128:
+ verify_password("rejected-credential", None)
+ return None
+ async with session_scope() as session:
+ async with session.begin():
+ row = (
+ await session.execute(
+ select(User.id, User.username, User.display_name, User.created_at, User.password_hash).where(
+ User.username == username
+ )
+ )
+ ).one_or_none()
+ if row is None:
+ stored = None
+ snapshot = None
+ else:
+ stored = row.password_hash
+ snapshot = PublicUser(
+ id=row.id,
+ username=row.username,
+ display_name=row.display_name,
+ created_at=row.created_at,
+ )
+ if not verify_password(password, stored):
+ return None
+ return snapshot
diff --git a/src/app/db.py b/src/app/db.py
new file mode 100644
index 00000000..422ae050
--- /dev/null
+++ b/src/app/db.py
@@ -0,0 +1,79 @@
+import logging
+from contextlib import asynccontextmanager
+
+from redis.exceptions import RedisError
+from sqlalchemy.exc import DBAPIError, IntegrityError, InterfaceError, OperationalError
+from sqlalchemy.exc import TimeoutError as SATimeout
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+
+from app.config import Settings
+from app.errors import AppError
+
+logger = logging.getLogger("app.db")
+
+
+def build_engine(settings: Settings) -> AsyncEngine:
+ command_ms = str(int(settings.db_command_timeout_seconds * 1000))
+ lock_ms = str(int(settings.db_pool_timeout_seconds * 1000))
+ return create_async_engine(
+ settings.database_url,
+ pool_size=settings.db_pool_size,
+ max_overflow=settings.db_max_overflow,
+ pool_timeout=settings.db_pool_timeout_seconds,
+ pool_pre_ping=True,
+ pool_recycle=1800,
+ echo=False,
+ connect_args={
+ "timeout": settings.db_connect_timeout_seconds,
+ "command_timeout": settings.db_command_timeout_seconds,
+ "server_settings": {
+ "statement_timeout": command_ms,
+ "lock_timeout": lock_ms,
+ "idle_in_transaction_session_timeout": "10000",
+ },
+ },
+ )
+
+
+def build_session_factory(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
+ return async_sessionmaker(engine, expire_on_commit=False, autoflush=False)
+
+
+def is_dependency_error(exc: BaseException) -> bool:
+ if isinstance(exc, (OperationalError, InterfaceError, SATimeout, RedisError, ConnectionError, TimeoutError)):
+ return True
+ return isinstance(exc, DBAPIError) and bool(getattr(exc, "connection_invalidated", False))
+
+
+def map_integrity(exc: IntegrityError, duplicate_message: str) -> AppError:
+ orig = getattr(exc, "orig", None)
+ code = getattr(orig, "sqlstate", None) or getattr(orig, "pgcode", None)
+ if code == "23505":
+ return AppError(409, "conflict", duplicate_message)
+ if code in {"23503", "23514", "23502"}:
+ return AppError(400, "invalid_request", "Некорректный запрос")
+ return AppError(500, "internal_error", "Внутренняя ошибка")
+
+
+@asynccontextmanager
+async def session_scope():
+ from app.runtime import require_factory
+
+ factory = require_factory()
+ try:
+ session = factory()
+ except Exception as exc:
+ if is_dependency_error(exc):
+ logger.warning("database unavailable type=%s", type(exc).__name__)
+ raise AppError(503, "unavailable", "Сервис временно недоступен") from None
+ raise
+ try:
+ async with session:
+ yield session
+ except AppError:
+ raise
+ except Exception as exc:
+ if is_dependency_error(exc):
+ logger.warning("database unavailable type=%s", type(exc).__name__)
+ raise AppError(503, "unavailable", "Сервис временно недоступен") from None
+ raise
diff --git a/src/app/deps.py b/src/app/deps.py
new file mode 100644
index 00000000..7fdf11c8
--- /dev/null
+++ b/src/app/deps.py
@@ -0,0 +1,50 @@
+from fastapi import Depends, Header, Request
+from app.crud.users import get_user
+from app.errors import AppError
+from app.present import PublicUser
+from app.sessions import resolve_session
+
+BEARER_CHALLENGE = 'Bearer realm="messenger"'
+BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"'
+
+
+def unauthorized(challenge: str) -> AppError:
+ return AppError(
+ 401,
+ "unauthorized",
+ "Требуется идентификация",
+ headers={"WWW-Authenticate": challenge},
+ )
+
+
+async def get_current_user(
+ request: Request,
+ authorization: str | None = Header(default=None),
+) -> PublicUser:
+ # Нет заголовка — клиент анонимный. Redis для этого не нужен и не делает его доверенным.
+ if authorization is None:
+ raise unauthorized(BEARER_CHALLENGE)
+ scheme, _, token = authorization.partition(" ")
+ token = token.strip()
+ if scheme.lower() != "bearer" or not token or len(token) > 512:
+ raise unauthorized(BEARER_CHALLENGE)
+ user_id = await resolve_session(token)
+ if user_id is None:
+ raise unauthorized(BEARER_CHALLENGE)
+ user = await get_user(user_id)
+ if user is None:
+ raise unauthorized(BEARER_CHALLENGE)
+ request.state.session_token = token
+ return user
+
+
+def current_token(request: Request) -> str:
+ token = getattr(request.state, "session_token", "")
+ if not token:
+ raise unauthorized(BEARER_CHALLENGE)
+ return token
+
+
+def require_token(request: Request, user: PublicUser = Depends(get_current_user)) -> str:
+ del user
+ return current_token(request)
diff --git a/src/app/errors.py b/src/app/errors.py
new file mode 100644
index 00000000..c0785a12
--- /dev/null
+++ b/src/app/errors.py
@@ -0,0 +1,54 @@
+import logging
+
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
+
+
+class AppError(Exception):
+ def __init__(self, status: int, code: str, message: str, headers: dict | None = None) -> None:
+ super().__init__(message)
+ self.status = status
+ self.code = code
+ self.message = message
+ self.headers = headers
+
+
+def request_id_of(request: Request) -> str:
+ return getattr(request.state, "request_id", "") or "missing"
+
+
+def error_response(
+ status: int,
+ code: str,
+ message: str,
+ request_id: str,
+ headers: dict | None = None,
+) -> JSONResponse:
+ return JSONResponse(
+ status_code=status,
+ content={"error": {"code": code, "message": message, "request_id": request_id}},
+ headers=headers,
+ )
+
+
+async def handle_app_error(request: Request, exc: AppError) -> JSONResponse:
+ return error_response(exc.status, exc.code, exc.message, request_id_of(request), exc.headers)
+
+
+async def handle_dependency(request: Request, exc: Exception) -> JSONResponse:
+ # Текст исключения может содержать SQL или параметры. В ответ и лог его не кладём.
+ logging.getLogger("app").warning("dependency unavailable type=%s", type(exc).__name__)
+ return error_response(503, "unavailable", "Сервис временно недоступен", request_id_of(request))
+
+
+async def handle_validation_error(request: Request, _exc: RequestValidationError) -> JSONResponse:
+ return error_response(400, "invalid_request", "Некорректный запрос", request_id_of(request))
+
+
+async def handle_http_error(request: Request, exc: HTTPException) -> JSONResponse:
+ # Тело не в UTF-8 FastAPI превращает в HTTPException 400 с полем detail.
+ if exc.status_code == 400:
+ return error_response(400, "invalid_request", "Некорректный запрос", request_id_of(request))
+ return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail}, headers=exc.headers)
diff --git a/src/app/main.py b/src/app/main.py
new file mode 100644
index 00000000..714ad559
--- /dev/null
+++ b/src/app/main.py
@@ -0,0 +1,97 @@
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from redis.exceptions import RedisError
+from sqlalchemy.exc import InterfaceError, OperationalError, ProgrammingError
+from sqlalchemy.exc import TimeoutError as SATimeout
+from starlette.exceptions import HTTPException
+
+from app.api import api_router
+from app.api.health import router as health_router
+from app.config import load_settings
+from app.db import build_engine, build_session_factory, is_dependency_error
+from app.errors import AppError, handle_app_error, handle_dependency, handle_http_error, handle_validation_error
+from app.migrate import apply_migrations, wait_for_database, wait_for_schema
+from app.middleware import request_context
+from app.runtime import configure
+from app.security import init_security
+from app.sessions import build_redis
+
+logger = logging.getLogger("app")
+
+
+async def open_stores(engine, redis, settings) -> None:
+ await wait_for_database(engine)
+ for attempt in range(40):
+ try:
+ await redis.ping()
+ break
+ except Exception as exc:
+ if not is_dependency_error(exc):
+ logger.error("redis probe failed type=%s", type(exc).__name__)
+ raise SystemExit("redis probe failed") from None
+ logger.warning("redis not ready type=%s attempt=%s", type(exc).__name__, attempt + 1)
+ if attempt == 39:
+ raise SystemExit("redis is not ready") from None
+ await asyncio.sleep(0.5)
+ if settings.run_migrations:
+ try:
+ applied = await apply_migrations(engine, settings.migrations_dir)
+ logger.info("migrations newly_applied=%s", applied)
+ except ProgrammingError as exc:
+ sqlstate = getattr(getattr(exc, "orig", None), "sqlstate", "")
+ logger.error("migration rejected type=%s sqlstate=%s", type(exc).__name__, sqlstate)
+ raise SystemExit("migration failed") from None
+ else:
+ await wait_for_schema(engine, settings.migrations_dir)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+ settings = load_settings()
+ init_security()
+ engine = build_engine(settings)
+ redis = build_redis(settings)
+ app.state.engine = engine
+ app.state.redis = redis
+ app.state.settings = settings
+ app.state.instance_id = settings.instance_id
+ app.state.accepting = False
+ try:
+ await open_stores(engine, redis, settings)
+ configure(build_session_factory(engine), redis, settings)
+ app.state.accepting = True
+ logger.info(
+ "ready env=%s instance_id=%s session_ttl_seconds=%s db_pool=%s",
+ settings.env,
+ settings.instance_id,
+ settings.session_ttl_seconds,
+ settings.db_pool_size,
+ )
+ yield
+ finally:
+ app.state.accepting = False
+ logger.info("shutdown: new requests are no longer accepted")
+ await redis.aclose()
+ await engine.dispose()
+
+
+def create_app() -> FastAPI:
+ app = FastAPI(title="MTUSI Messenger", version="1.3.0", lifespan=lifespan)
+ app.state.instance_id = "starting"
+ app.state.accepting = False
+ app.add_exception_handler(AppError, handle_app_error)
+ app.add_exception_handler(RequestValidationError, handle_validation_error)
+ app.add_exception_handler(HTTPException, handle_http_error)
+ for cls in (OperationalError, InterfaceError, SATimeout, RedisError):
+ app.add_exception_handler(cls, handle_dependency)
+ app.middleware("http")(request_context)
+ app.include_router(health_router)
+ app.include_router(api_router)
+ return app
+
+
+app = create_app()
diff --git a/src/app/middleware.py b/src/app/middleware.py
new file mode 100644
index 00000000..9908a959
--- /dev/null
+++ b/src/app/middleware.py
@@ -0,0 +1,52 @@
+import logging
+import time
+from uuid import uuid4
+
+from fastapi import Request
+
+from app.db import is_dependency_error
+from app.errors import error_response
+
+logger = logging.getLogger("app.access")
+
+
+def _instance_id(request: Request) -> str:
+ settings = getattr(request.app.state, "settings", None)
+ if settings is not None:
+ return settings.instance_id
+ return getattr(request.app.state, "instance_id", "starting")
+
+
+async def request_context(request: Request, call_next):
+ request_id = uuid4().hex
+ request.state.request_id = request_id
+ started = time.perf_counter()
+ status = 500
+ try:
+ accepting = getattr(request.app.state, "accepting", True)
+ if not accepting and request.url.path != "/health/live":
+ response = error_response(503, "unavailable", "Сервер останавливается", request_id)
+ else:
+ try:
+ response = await call_next(request)
+ except Exception as exc:
+ if is_dependency_error(exc):
+ logger.warning("dependency unavailable type=%s", type(exc).__name__)
+ response = error_response(503, "unavailable", "Сервис временно недоступен", request_id)
+ else:
+ logger.error("internal error request_id=%s type=%s", request_id, type(exc).__name__)
+ response = error_response(500, "internal_error", "Внутренняя ошибка", request_id)
+ response.headers["X-Request-Id"] = request_id
+ response.headers["X-Instance-Id"] = _instance_id(request)
+ status = response.status_code
+ return response
+ finally:
+ elapsed_ms = int((time.perf_counter() - started) * 1000)
+ logger.info(
+ "request method=%s path=%s status=%s request_id=%s duration_ms=%s",
+ request.method,
+ request.url.path,
+ status,
+ request_id,
+ elapsed_ms,
+ )
diff --git a/src/app/migrate.py b/src/app/migrate.py
new file mode 100644
index 00000000..3d6770e5
--- /dev/null
+++ b/src/app/migrate.py
@@ -0,0 +1,141 @@
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+from sqlalchemy import text
+from sqlalchemy.exc import ProgrammingError
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from app.config import load_settings
+from app.db import build_engine, is_dependency_error
+
+logger = logging.getLogger("app.migrate")
+
+# Один номер на все процессы, чтобы две миграции не применяли DDL одновременно.
+_ADVISORY_LOCK = 842021
+
+
+def sql_statements(script: str) -> list[str]:
+ lines = []
+ for line in script.splitlines():
+ if line.strip().startswith("--"):
+ continue
+ lines.append(line)
+ statements = []
+ for part in "\n".join(lines).split(";"):
+ statement = part.strip()
+ if statement:
+ statements.append(statement)
+ return statements
+
+
+def expected_versions(directory: Path) -> list[str]:
+ files = sorted(path for path in directory.glob("*.sql") if path.is_file())
+ if not files:
+ raise SystemExit("no SQL migrations found")
+ return [path.name for path in files]
+
+
+async def apply_migrations(engine: AsyncEngine, directory: Path) -> int:
+ files = sorted(path for path in directory.glob("*.sql") if path.is_file())
+ if not files:
+ raise SystemExit("no SQL migrations found")
+ applied = 0
+ async with engine.begin() as conn:
+ await conn.execute(text("SELECT pg_advisory_xact_lock(:lock_id)"), {"lock_id": _ADVISORY_LOCK})
+ await conn.execute(
+ text(
+ """
+ CREATE TABLE IF NOT EXISTS schema_migrations (
+ version TEXT PRIMARY KEY,
+ applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ )
+ """
+ )
+ )
+ for path in files:
+ version = path.name
+ exists = await conn.scalar(
+ text("SELECT version FROM schema_migrations WHERE version = :version"),
+ {"version": version},
+ )
+ if exists:
+ continue
+ for statement in sql_statements(path.read_text(encoding="utf-8")):
+ await conn.execute(text(statement))
+ await conn.execute(
+ text("INSERT INTO schema_migrations (version) VALUES (:version)"),
+ {"version": version},
+ )
+ applied += 1
+ logger.info("migration applied version=%s", version)
+ return applied
+
+
+async def wait_for_database(engine: AsyncEngine) -> None:
+ for attempt in range(40):
+ try:
+ async with engine.connect() as conn:
+ await conn.execute(text("SELECT 1"))
+ return
+ except Exception as exc:
+ if not is_dependency_error(exc):
+ logger.error("database probe failed type=%s", type(exc).__name__)
+ raise SystemExit("database probe failed") from None
+ logger.warning("database not ready type=%s attempt=%s", type(exc).__name__, attempt + 1)
+ if attempt == 39:
+ raise SystemExit("database is not ready") from None
+ await asyncio.sleep(0.5)
+
+
+async def wait_for_schema(engine: AsyncEngine, directory: Path) -> None:
+ needed = set(expected_versions(directory))
+ for attempt in range(40):
+ try:
+ async with engine.connect() as conn:
+ rows = (await conn.execute(text("SELECT version FROM schema_migrations"))).all()
+ found = {row[0] for row in rows}
+ if needed <= found:
+ logger.info("schema ready versions=%s", ",".join(sorted(found)))
+ return
+ logger.warning("schema incomplete attempt=%s", attempt + 1)
+ except ProgrammingError:
+ logger.warning("schema_migrations missing attempt=%s", attempt + 1)
+ except Exception as exc:
+ if not is_dependency_error(exc):
+ logger.error("schema probe failed type=%s", type(exc).__name__)
+ raise SystemExit("schema probe failed") from None
+ logger.warning("schema probe unavailable type=%s attempt=%s", type(exc).__name__, attempt + 1)
+ if attempt == 39:
+ raise SystemExit("schema is not ready")
+ await asyncio.sleep(0.5)
+
+
+async def run_job() -> None:
+ settings = load_settings()
+ engine = build_engine(settings)
+ try:
+ await wait_for_database(engine)
+ applied = await apply_migrations(engine, settings.migrations_dir)
+ logger.info("migrations newly_applied=%s", applied)
+ except ProgrammingError as exc:
+ sqlstate = getattr(getattr(exc, "orig", None), "sqlstate", "")
+ logger.error("migration rejected type=%s sqlstate=%s", type(exc).__name__, sqlstate)
+ raise SystemExit("migration failed") from None
+ finally:
+ await engine.dispose()
+
+
+def main() -> None:
+ logging.basicConfig(
+ level=logging.INFO,
+ format="%(asctime)s %(levelname)s %(name)s %(message)s",
+ stream=sys.stdout,
+ force=True,
+ )
+ asyncio.run(run_job())
+
+
+if __name__ == "__main__":
+ main()
diff --git a/src/app/models.py b/src/app/models.py
new file mode 100644
index 00000000..bb840123
--- /dev/null
+++ b/src/app/models.py
@@ -0,0 +1,119 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+ CheckConstraint,
+ DateTime,
+ ForeignKey,
+ Index,
+ SmallInteger,
+ Text,
+ UniqueConstraint,
+)
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+ pass
+
+
+class User(Base):
+ __tablename__ = "users"
+ __table_args__ = (
+ UniqueConstraint("username", name="uq_users_username"),
+ CheckConstraint("username ~ '^[a-z0-9_]{3,32}$'", name="ck_users_username_format"),
+ CheckConstraint(
+ "char_length(btrim(display_name)) >= 1 AND char_length(display_name) <= 100",
+ name="ck_users_display_name_len",
+ ),
+ CheckConstraint("char_length(password_hash) >= 20", name="ck_users_password_hash_len"),
+ )
+
+ id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+ username: Mapped[str] = mapped_column(Text, nullable=False)
+ display_name: Mapped[str] = mapped_column(Text, nullable=False)
+ password_hash: Mapped[str] = mapped_column(Text, nullable=False)
+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+
+class Chat(Base):
+ __tablename__ = "chats"
+ __table_args__ = (
+ CheckConstraint(
+ "char_length(btrim(title)) >= 1 AND char_length(title) <= 100",
+ name="ck_chats_title",
+ ),
+ )
+
+ id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+ title: Mapped[str] = mapped_column(Text, nullable=False)
+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+
+class ChatMember(Base):
+ __tablename__ = "chat_members"
+ __table_args__ = (
+ CheckConstraint("ordinal >= 0 AND ordinal < 100", name="ck_chat_members_ordinal"),
+ Index("ix_chat_members_user", "user_id", "chat_id"),
+ )
+
+ chat_id: Mapped[uuid.UUID] = mapped_column(
+ UUID(as_uuid=True),
+ ForeignKey("chats.id"),
+ primary_key=True,
+ )
+ user_id: Mapped[uuid.UUID] = mapped_column(
+ UUID(as_uuid=True),
+ ForeignKey("users.id"),
+ primary_key=True,
+ )
+ ordinal: Mapped[int] = mapped_column(SmallInteger, nullable=False)
+
+
+class Message(Base):
+ __tablename__ = "messages"
+ __table_args__ = (
+ CheckConstraint(
+ "char_length(btrim(body)) >= 1 AND char_length(body) <= 4000",
+ name="ck_messages_text",
+ ),
+ # Keyset: WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4
+ Index("ix_messages_history", "chat_id", "created_at", "id"),
+ )
+
+ id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
+ chat_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("chats.id"), nullable=False)
+ sender_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
+ text: Mapped[str] = mapped_column("body", Text, nullable=False)
+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+
+class IdempotencyRecord(Base):
+ __tablename__ = "idempotency_records"
+ __table_args__ = (
+ CheckConstraint("method = 'POST'", name="ck_idem_method"),
+ CheckConstraint("status_code = 201", name="ck_idem_status"),
+ CheckConstraint("idempotency_key ~ '^[A-Za-z0-9._:-]{1,128}$'", name="ck_idem_key"),
+ CheckConstraint("char_length(request_path) BETWEEN 1 AND 300", name="ck_idem_path"),
+ CheckConstraint("char_length(request_hash) = 64", name="ck_idem_hash"),
+ Index("ix_idempotency_message", "message_id"),
+ Index("ix_idempotency_created", "created_at"),
+ )
+
+ user_id: Mapped[uuid.UUID] = mapped_column(
+ UUID(as_uuid=True),
+ ForeignKey("users.id"),
+ primary_key=True,
+ )
+ method: Mapped[str] = mapped_column(Text, primary_key=True)
+ request_path: Mapped[str] = mapped_column(Text, primary_key=True)
+ idempotency_key: Mapped[str] = mapped_column(Text, primary_key=True)
+ request_hash: Mapped[str] = mapped_column(Text, nullable=False)
+ status_code: Mapped[int] = mapped_column(SmallInteger, nullable=False)
+ message_id: Mapped[uuid.UUID] = mapped_column(
+ UUID(as_uuid=True),
+ ForeignKey("messages.id"),
+ nullable=False,
+ )
+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
diff --git a/src/app/pagination.py b/src/app/pagination.py
new file mode 100644
index 00000000..f536d6c6
--- /dev/null
+++ b/src/app/pagination.py
@@ -0,0 +1,50 @@
+import base64
+import json
+from datetime import datetime
+from uuid import UUID
+
+from app.errors import AppError
+from app.timeutil import format_time, parse_time
+
+
+def encode_cursor(kind: str, resource_id: UUID, created_at: datetime, entity_id: UUID) -> str:
+ payload = {
+ "i": str(entity_id),
+ "k": kind,
+ "r": str(resource_id),
+ "t": format_time(created_at),
+ }
+ raw = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("ascii")
+ return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def decode_position(token: str, kind: str, resource_id: UUID) -> tuple[datetime, UUID]:
+ if len(token) > 1024:
+ raise AppError(400, "invalid_request", "Некорректный cursor")
+ padding = "=" * (-len(token) % 4)
+ try:
+ data = json.loads(base64.urlsafe_b64decode(token + padding))
+ if (
+ not isinstance(data, dict)
+ or data.get("k") != kind
+ or data.get("r") != str(resource_id)
+ or not isinstance(data.get("t"), str)
+ or not isinstance(data.get("i"), str)
+ ):
+ raise ValueError("cursor")
+ created_at = parse_time(data["t"])
+ entity_id = UUID(data["i"])
+ except (KeyError, TypeError, ValueError, AttributeError, json.JSONDecodeError):
+ raise AppError(400, "invalid_request", "Некорректный cursor") from None
+ return created_at, entity_id
+
+
+def slice_page(rows: list, limit: int, kind: str, resource_id: UUID) -> dict:
+ # SQL уже вернул не больше limit + 1 строк, отфильтрованных keyset-условием.
+ has_more = len(rows) > limit
+ page = rows[:limit]
+ next_cursor = None
+ if has_more and page:
+ last = page[-1]
+ next_cursor = encode_cursor(kind, resource_id, last.created_at, last.id)
+ return {"items": [row.to_dict() for row in page], "next_cursor": next_cursor}
diff --git a/src/app/present.py b/src/app/present.py
new file mode 100644
index 00000000..42569f5b
--- /dev/null
+++ b/src/app/present.py
@@ -0,0 +1,55 @@
+from dataclasses import dataclass
+from datetime import datetime
+from uuid import UUID
+
+from app.timeutil import format_time
+
+
+@dataclass(frozen=True)
+class PublicUser:
+ id: UUID
+ username: str
+ display_name: str
+ created_at: datetime
+
+ def to_dict(self) -> dict:
+ return {
+ "id": self.id,
+ "username": self.username,
+ "display_name": self.display_name,
+ "created_at": format_time(self.created_at),
+ }
+
+
+@dataclass(frozen=True)
+class PublicChat:
+ id: UUID
+ title: str
+ member_ids: tuple[UUID, ...]
+ created_at: datetime
+
+ def to_dict(self) -> dict:
+ return {
+ "id": self.id,
+ "title": self.title,
+ "member_ids": list(self.member_ids),
+ "created_at": format_time(self.created_at),
+ }
+
+
+@dataclass(frozen=True)
+class PublicMessage:
+ id: UUID
+ chat_id: UUID
+ sender_id: UUID
+ text: str
+ created_at: datetime
+
+ def to_dict(self) -> dict:
+ return {
+ "id": self.id,
+ "chat_id": self.chat_id,
+ "sender_id": self.sender_id,
+ "text": self.text,
+ "created_at": format_time(self.created_at),
+ }
diff --git a/src/app/runtime.py b/src/app/runtime.py
new file mode 100644
index 00000000..58fe7d50
--- /dev/null
+++ b/src/app/runtime.py
@@ -0,0 +1,36 @@
+from app.config import Settings
+
+_factory = None
+_redis = None
+_settings: Settings | None = None
+
+
+def configure(factory, redis, settings: Settings) -> None:
+ global _factory, _redis, _settings
+ _factory = factory
+ _redis = redis
+ _settings = settings
+
+
+def require_factory():
+ if _factory is None:
+ from app.errors import AppError
+
+ raise AppError(503, "unavailable", "Сервис временно недоступен")
+ return _factory
+
+
+def require_redis():
+ if _redis is None:
+ from app.errors import AppError
+
+ raise AppError(503, "unavailable", "Сервис временно недоступен")
+ return _redis
+
+
+def require_settings() -> Settings:
+ if _settings is None:
+ from app.errors import AppError
+
+ raise AppError(503, "unavailable", "Сервис временно недоступен")
+ return _settings
diff --git a/src/app/schemas/__init__.py b/src/app/schemas/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/app/schemas/chat.py b/src/app/schemas/chat.py
new file mode 100644
index 00000000..ea694c63
--- /dev/null
+++ b/src/app/schemas/chat.py
@@ -0,0 +1,35 @@
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class CreateChat(BaseModel):
+ model_config = ConfigDict(extra="forbid")
+ title: str
+ member_ids: list[UUID] = Field(min_length=1, max_length=100)
+
+ @field_validator("title")
+ @classmethod
+ def check_title(cls, value: str) -> str:
+ if value.strip() == "" or len(value) > 100:
+ raise ValueError("title")
+ return value
+
+ @field_validator("member_ids")
+ @classmethod
+ def unique_members(cls, value: list[UUID]) -> list[UUID]:
+ if len(set(value)) != len(value):
+ raise ValueError("duplicate members")
+ return value
+
+
+class ChatOut(BaseModel):
+ id: UUID
+ title: str
+ member_ids: list[UUID]
+ created_at: str
+
+
+class ChatPage(BaseModel):
+ items: list[ChatOut]
+ next_cursor: str | None
diff --git a/src/app/schemas/message.py b/src/app/schemas/message.py
new file mode 100644
index 00000000..ab5658e2
--- /dev/null
+++ b/src/app/schemas/message.py
@@ -0,0 +1,28 @@
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+
+class CreateMessage(BaseModel):
+ model_config = ConfigDict(extra="forbid")
+ text: str
+
+ @field_validator("text")
+ @classmethod
+ def check_text(cls, value: str) -> str:
+ if value.strip() == "" or len(value) > 4000:
+ raise ValueError("text")
+ return value
+
+
+class MessageOut(BaseModel):
+ id: UUID
+ chat_id: UUID
+ sender_id: UUID
+ text: str
+ created_at: str
+
+
+class MessagePage(BaseModel):
+ items: list[MessageOut]
+ next_cursor: str | None
diff --git a/src/app/schemas/session.py b/src/app/schemas/session.py
new file mode 100644
index 00000000..beb07f13
--- /dev/null
+++ b/src/app/schemas/session.py
@@ -0,0 +1,10 @@
+from pydantic import BaseModel
+
+from app.schemas.user import UserOut
+
+
+class SessionOut(BaseModel):
+ token: str
+ token_type: str
+ expires_at: str
+ user: UserOut
diff --git a/src/app/schemas/user.py b/src/app/schemas/user.py
new file mode 100644
index 00000000..2e313359
--- /dev/null
+++ b/src/app/schemas/user.py
@@ -0,0 +1,41 @@
+import re
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+
+class CreateUser(BaseModel):
+ model_config = ConfigDict(extra="forbid")
+ username: str
+ display_name: str
+ password: str
+
+ @field_validator("username")
+ @classmethod
+ def check_username(cls, value: str) -> str:
+ if re.fullmatch(r"[a-z0-9_]{3,32}", value) is None:
+ raise ValueError("username")
+ return value
+
+ @field_validator("display_name")
+ @classmethod
+ def check_display_name(cls, value: str) -> str:
+ if value.strip() == "" or len(value) > 100:
+ raise ValueError("display_name")
+ return value
+
+ @field_validator("password")
+ @classmethod
+ def check_password(cls, value: str) -> str:
+ # Длина в code points. Пароль не обрезается и не нормализуется.
+ if not 12 <= len(value) <= 128:
+ raise ValueError("password")
+ return value
+
+
+class UserOut(BaseModel):
+ id: UUID
+ username: str
+ display_name: str
+ created_at: str
diff --git a/src/app/security.py b/src/app/security.py
new file mode 100644
index 00000000..40b9a3ca
--- /dev/null
+++ b/src/app/security.py
@@ -0,0 +1,65 @@
+import base64
+import binascii
+
+from argon2 import PasswordHasher
+from argon2.exceptions import InvalidHashError, VerifyMismatchError
+from argon2.low_level import Type
+
+# Учебные параметры Argon2id: устойчивее SHA-256, но подъём на ноутбуке
+_TIME_COST = 2
+_MEMORY_COST = 32768
+_PARALLELISM = 1
+
+_hasher: PasswordHasher | None = None
+_dummy_hash: str | None = None
+
+
+def get_hasher() -> PasswordHasher:
+ global _hasher
+ if _hasher is None:
+ _hasher = PasswordHasher(
+ time_cost=_TIME_COST,
+ memory_cost=_MEMORY_COST,
+ parallelism=_PARALLELISM,
+ hash_len=32,
+ salt_len=16,
+ type=Type.ID,
+ )
+ return _hasher
+
+
+def init_security() -> None:
+ global _dummy_hash
+ if _dummy_hash is None:
+ _dummy_hash = get_hasher().hash("messenger-dummy-password-not-used-for-login")
+
+
+def hash_password(password: str) -> str:
+ return get_hasher().hash(password)
+
+
+def verify_password(password: str, password_hash: str | None) -> bool:
+ init_security()
+ try:
+ get_hasher().verify(password_hash or _dummy_hash, password)
+ matched = True
+ except (VerifyMismatchError, InvalidHashError):
+ matched = False
+ return password_hash is not None and matched
+
+
+def parse_basic(header: str) -> tuple[str, str] | None:
+ if not header:
+ return None
+ scheme, _, rest = header.partition(" ")
+ if scheme.lower() != "basic" or not rest.strip():
+ return None
+ try:
+ decoded = base64.b64decode(rest.strip(), validate=True)
+ text = decoded.decode("utf-8")
+ except (ValueError, UnicodeError, binascii.Error):
+ return None
+ username, separator, password = text.partition(":")
+ if separator != ":" or len(username) > 256 or len(password) > 1024:
+ return None
+ return username, password
diff --git a/src/app/sessions.py b/src/app/sessions.py
new file mode 100644
index 00000000..7c9b0274
--- /dev/null
+++ b/src/app/sessions.py
@@ -0,0 +1,90 @@
+import hashlib
+import json
+import logging
+import secrets
+from datetime import timedelta
+from uuid import UUID
+
+from redis.asyncio import Redis
+from redis.exceptions import RedisError
+
+from app.config import Settings
+from app.errors import AppError
+from app.runtime import require_redis, require_settings
+from app.timeutil import format_time, parse_time, utcnow
+
+logger = logging.getLogger("app.sessions")
+
+
+def build_redis(settings: Settings) -> Redis:
+ return Redis.from_url(
+ settings.cache_url,
+ decode_responses=True,
+ socket_timeout=settings.redis_socket_timeout_seconds,
+ socket_connect_timeout=settings.redis_socket_timeout_seconds,
+ health_check_interval=30,
+ max_connections=settings.redis_max_connections,
+ )
+
+
+def session_key(token: str) -> str:
+ digest = hashlib.sha256(token.encode("utf-8")).hexdigest()
+ return "sess:" + digest
+
+
+async def _call(awaitable):
+ try:
+ return await awaitable
+ except RedisError:
+ logger.warning("redis unavailable type=%s", "RedisError")
+ raise AppError(503, "unavailable", "Сервис временно недоступен") from None
+
+
+def _read_payload(raw: str) -> tuple[UUID, object] | None:
+ try:
+ data = json.loads(raw)
+ if not isinstance(data, dict):
+ raise ValueError("payload")
+ return UUID(str(data["user_id"])), parse_time(data["expires_at"])
+ except (ValueError, KeyError, TypeError):
+ return None
+
+
+async def create_session(user_id: UUID) -> tuple[str, object]:
+ settings = require_settings()
+ token = secrets.token_urlsafe(32)
+ expires_at = utcnow() + timedelta(seconds=settings.session_ttl_seconds)
+ payload = json.dumps(
+ {"user_id": str(user_id), "expires_at": format_time(expires_at)},
+ separators=(",", ":"),
+ )
+ # PXAT — абсолютное время. Повтор AOF после рестарта не продлевает TTL.
+ await _call(require_redis().set(session_key(token), payload, pxat=int(expires_at.timestamp() * 1000)))
+ return token, expires_at
+
+
+async def resolve_session(token: str) -> UUID | None:
+ key = session_key(token)
+ raw = await _call(require_redis().get(key))
+ if raw is None:
+ return None
+ parsed = _read_payload(raw)
+ if parsed is None:
+ await _call(require_redis().delete(key))
+ return None
+ user_id, expires_at = parsed
+ if expires_at <= utcnow():
+ await _call(require_redis().delete(key))
+ return None
+ return user_id
+
+
+async def revoke_session(token: str) -> bool:
+ raw = await _call(require_redis().getdel(session_key(token)))
+ if raw is None:
+ return False
+ parsed = _read_payload(raw)
+ if parsed is None:
+ return False
+ _, expires_at = parsed
+ return expires_at > utcnow()
diff --git a/src/app/storage/__init__.py b/src/app/storage/__init__.py
new file mode 100644
index 00000000..f1a2a517
--- /dev/null
+++ b/src/app/storage/__init__.py
@@ -0,0 +1 @@
+"""Состояние лабораторной 2 хранится в PostgreSQL и Redis, не в памяти процесса."""
diff --git a/src/app/storage/memory.py b/src/app/storage/memory.py
new file mode 100644
index 00000000..e8b0b7f0
--- /dev/null
+++ b/src/app/storage/memory.py
@@ -0,0 +1,5 @@
+"""Память процесса больше не хранит пользователей, чаты и сообщения.
+
+Источник истины для этих данных — PostgreSQL.
+Источник истины для сессий — Redis с AOF и абсолютным PXAT.
+"""
diff --git a/src/app/timeutil.py b/src/app/timeutil.py
new file mode 100644
index 00000000..08421fb4
--- /dev/null
+++ b/src/app/timeutil.py
@@ -0,0 +1,20 @@
+from datetime import datetime, timezone
+
+
+def utcnow() -> datetime:
+ return datetime.now(timezone.utc)
+
+
+def format_time(value: datetime) -> str:
+ if value.tzinfo is None:
+ value = value.replace(tzinfo=timezone.utc)
+ return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def parse_time(value: str) -> datetime:
+ if not isinstance(value, str) or not value.endswith("Z"):
+ raise ValueError("time")
+ parsed = datetime.fromisoformat(value[:-1] + "+00:00")
+ if parsed.tzinfo is None:
+ raise ValueError("time")
+ return parsed.astimezone(timezone.utc)
diff --git a/student-tests/failover.py b/student-tests/failover.py
new file mode 100644
index 00000000..a655e074
--- /dev/null
+++ b/student-tests/failover.py
@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Запуск публичного failover на Windows и POSIX с тем же scripts/stop-one.sh."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def script():
+ if os.name == "nt":
+ cmd = ROOT / "scripts" / "stop-one.cmd"
+ if cmd.is_file():
+ return str(cmd)
+ sh = ROOT / "scripts" / "stop-one.sh"
+ return str(sh)
+
+
+def main():
+ env = os.environ.copy()
+ command = [
+ sys.executable,
+ str(ROOT / "tests" / "resilience.py"),
+ "--mode",
+ "failover",
+ "--action-script",
+ script(),
+ "--base-url",
+ env.get("BASE_URL", "http://127.0.0.1:8080"),
+ ]
+ completed = subprocess.run(command, cwd=str(ROOT), env=env)
+ raise SystemExit(completed.returncode)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/student-tests/level3.py b/student-tests/level3.py
new file mode 100644
index 00000000..057caabc
--- /dev/null
+++ b/student-tests/level3.py
@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Проверки lab3: разные реплики, идемпотентность через LB, гонка одного ключа."""
+
+import json
+import os
+import sys
+import threading
+import time
+import uuid
+from collections import Counter
+from pathlib import Path
+from urllib.parse import quote
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "tests"))
+from client import Client, Failure, check, run
+
+EVIDENCE = ROOT / "evidence"
+BASE = os.environ.get("BASE_URL", "http://127.0.0.1:8080").rstrip("/")
+
+
+def history(client, actor, chat):
+ path = "/api/v1/chats/" + chat["id"] + "/messages?limit=100"
+ result = []
+ seen = set()
+ for _ in range(1000):
+ page = client.call("GET", path, actor=actor, schema="MessagePage")["json"]
+ result.extend(page["items"])
+ cursor = page["next_cursor"]
+ if cursor is None:
+ return result
+ check(cursor not in seen, "cursor cycle")
+ seen.add(cursor)
+ path = "/api/v1/chats/" + chat["id"] + "/messages?limit=100&cursor=" + quote(cursor, safe="")
+ raise Failure("history pagination exceeded safety bound")
+
+
+def test_instances(client, actor):
+ seen = []
+ for _ in range(40):
+ seen.append(client.call("GET", "/api/v1/users/me", actor=actor, schema="User")["headers"]["X-Instance-Id"])
+ unique = sorted(set(seen))
+ check(len(unique) >= 2, "less than two API instances observed: %s" % unique)
+ return {"unique_instance_ids": unique, "samples": len(seen), "counts": dict(Counter(seen))}
+
+
+def test_idempotency(client, alice, bob, chat):
+ key = uuid.uuid4().hex
+ first = client.message(alice, chat, "Один ключ", key=key)
+ replay = client.message(alice, chat, "Один ключ", key=key)
+ check(first["json"] == replay["json"], "idempotent replay differs")
+ check(first["json"]["id"] == replay["json"]["id"], "idempotent replay allocated a new id")
+ conflict = client.call(
+ "POST",
+ "/api/v1/chats/" + chat["id"] + "/messages",
+ 409,
+ actor=alice,
+ body={"text": "другой body"},
+ headers={"Idempotency-Key": key},
+ )
+ check(conflict["json"]["error"]["code"] == "conflict", "wrong body code")
+ missing = client.call(
+ "POST",
+ "/api/v1/chats/" + chat["id"] + "/messages",
+ 400,
+ actor=alice,
+ body={"text": "без ключа"},
+ )
+ check(missing["json"]["error"]["code"] == "invalid_request", "missing key code")
+ other_user = client.message(bob, chat, "Один ключ", key=key)
+ check(other_user["json"]["id"] != first["json"]["id"], "key leaked across users")
+ return first["json"]["id"]
+
+
+def test_concurrent_key(client, alice, chat):
+ key = uuid.uuid4().hex
+ text = "Гонка ключа " + key
+ barrier = threading.Barrier(12)
+ results = []
+ errors = []
+ lock = threading.Lock()
+
+ def worker():
+ local = Client(BASE, timeout=20)
+ try:
+ barrier.wait(20)
+ response = local.message(alice, chat, text, key=key)
+ with lock:
+ results.append((response["status"], response["json"]["id"], response["headers"]["X-Instance-Id"]))
+ except Exception as exc:
+ with lock:
+ errors.append("%s: %s" % (type(exc).__name__, exc))
+
+ threads = [threading.Thread(target=worker) for _ in range(12)]
+ for thread in threads:
+ thread.start()
+ for thread in threads:
+ thread.join()
+ check(not errors, "concurrent idempotent POST failed: " + "; ".join(errors[:5]))
+ check(len(results) == 12, "expected 12 successes, got %s" % len(results))
+ ids = {item[1] for item in results}
+ instances = sorted({item[2] for item in results})
+ check(len(ids) == 1, "concurrent key created %s messages" % len(ids))
+ listed = history(client, alice, chat)
+ matches = [item for item in listed if item["text"] == text]
+ check(len(matches) == 1, "history contains %s copies of the concurrent key" % len(matches))
+ return {"message_id": next(iter(ids)), "instances": instances, "successes": len(results)}
+
+
+def main():
+ client = Client(BASE, timeout=10)
+ alice, bob, _eve, chat = client.bootstrap()
+ instances = test_instances(client, alice)
+ message_id = test_idempotency(client, alice, bob, chat)
+ race = test_concurrent_key(client, alice, chat)
+ EVIDENCE.mkdir(exist_ok=True)
+ report = {
+ "date": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+ "base_url": BASE,
+ "instances": instances,
+ "idempotent_message_id_present": bool(message_id),
+ "concurrent_key": race,
+ }
+ (EVIDENCE / "level3.json").write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ print("PASS: level 3 replica routing and shared idempotency")
+
+
+if __name__ == "__main__":
+ run(main)
diff --git a/student-tests/level4.py b/student-tests/level4.py
new file mode 100644
index 00000000..1ac1e535
--- /dev/null
+++ b/student-tests/level4.py
@@ -0,0 +1,635 @@
+#!/usr/bin/env python3
+"""Проверки уровня 4: гонка, откат, EXPLAIN, TTL, logout и отказ Redis/PostgreSQL.
+
+Стенд уже должен быть поднят: scripts/bootstrap и docker compose up.
+Скрипт останавливает redis и postgres и снова их запускает.
+Токены и пароли не печатаются и не пишутся в evidence.
+"""
+
+import asyncio
+import base64
+import json
+import os
+import socket
+import subprocess
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+EVIDENCE = ROOT / "evidence"
+sys.path.insert(0, str(ROOT / "src"))
+
+BASE = os.environ.get("BASE_URL", "http://127.0.0.1:8080").rstrip("/")
+
+
+class Failure(AssertionError):
+ pass
+
+
+def check(condition, message):
+ if not condition:
+ raise Failure(message)
+
+
+def host_secret(name):
+ path = ROOT / "secrets" / name
+ if not path.is_file():
+ raise Failure("missing secrets/%s; run scripts/bootstrap first" % name)
+ value = path.read_text(encoding="utf-8").strip()
+ if not value:
+ raise Failure("empty secrets/%s" % name)
+ return value
+
+
+def call(method, path, expected, body=None, token=None, authorization=None, user_id=None, timeout=15, headers=None):
+ extra = headers or {}
+ headers = {"Accept": "application/json"}
+ headers.update(extra)
+ data = None
+ if body is not None:
+ data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+ headers["Content-Type"] = "application/json"
+ if authorization:
+ headers["Authorization"] = authorization
+ elif token:
+ headers["Authorization"] = "Bearer " + token
+ if user_id:
+ headers["X-User-Id"] = user_id
+ request = urllib.request.Request(BASE + path, data=data, headers=headers, method=method)
+ try:
+ response = urllib.request.urlopen(request, timeout=timeout)
+ except urllib.error.HTTPError as error:
+ response = error
+ except (urllib.error.URLError, TimeoutError, OSError) as exc:
+ raise Failure(method + " " + path.split("?")[0] + " failed: " + type(exc).__name__) from None
+ with response:
+ status = response.status
+ payload = response.read()
+ header_id = response.headers.get("X-Request-Id")
+ challenge = response.headers.get("WWW-Authenticate", "")
+ allowed = [expected] if isinstance(expected, int) else list(expected)
+ check(status in allowed, "%s %s: expected %s, got %s" % (method, path.split("?")[0], allowed, status))
+ check(header_id and header_id.strip(), "missing X-Request-Id")
+ parsed = None
+ if payload:
+ try:
+ parsed = json.loads(payload)
+ except json.JSONDecodeError as exc:
+ raise Failure("response is not JSON") from exc
+ if status >= 400:
+ check(isinstance(parsed, dict) and set(parsed) == {"error"}, "error envelope")
+ error = parsed["error"]
+ check(set(error) == {"code", "message", "request_id"}, "error fields")
+ check(error["request_id"] == header_id, "request_id differs from header")
+ lowered = error["message"].lower()
+ for leaked in ("traceback", "select ", "password", "syntax", "asyncpg", "sqlalchemy"):
+ check(leaked not in lowered, "error message leaked internals")
+ if status == 204:
+ check(not payload, "204 must not contain a body")
+ return {"status": status, "json": parsed, "www": challenge}
+
+
+def basic(username, password):
+ raw = base64.b64encode(("%s:%s" % (username, password)).encode("utf-8")).decode("ascii")
+ return "Basic " + raw
+
+
+def register(label, password=None):
+ username = ("u_%s_%s" % (label, uuid.uuid4().hex[:10])).lower()
+ password = password or ("T3st-" + uuid.uuid4().hex)
+ created = call(
+ "POST",
+ "/api/v1/users",
+ 201,
+ body={"username": username, "display_name": "Студент " + label, "password": password},
+ )["json"]
+ check("password" not in created, "password leaked")
+ session = call("POST", "/api/v1/auth/sessions", 201, authorization=basic(username, password))["json"]
+ check(session["token_type"] == "Bearer" and session["user"]["id"] == created["id"], "session shape")
+ check(len(session["token"]) >= 32, "token is too short")
+ return {"id": created["id"], "username": username, "password": password, "token": session["token"]}
+
+
+def compose(*args, timeout=120):
+ proc = subprocess.run(
+ ["docker", "compose", *args],
+ cwd=str(ROOT),
+ capture_output=True,
+ text=True,
+ timeout=timeout,
+ encoding="utf-8",
+ errors="replace",
+ )
+ if proc.returncode != 0:
+ raise Failure("docker compose %s failed with code %s" % (args[0], proc.returncode))
+ return proc.stdout
+
+
+def psql(sql, timeout=60):
+ proc = subprocess.run(
+ [
+ "docker",
+ "compose",
+ "exec",
+ "-T",
+ "postgres",
+ "psql",
+ "-U",
+ "messenger",
+ "-d",
+ "messenger",
+ "-v",
+ "ON_ERROR_STOP=1",
+ "-At",
+ "-c",
+ sql,
+ ],
+ cwd=str(ROOT),
+ capture_output=True,
+ text=True,
+ timeout=timeout,
+ encoding="utf-8",
+ errors="replace",
+ )
+ if proc.returncode != 0:
+ raise Failure("psql failed")
+ return proc.stdout.strip()
+
+
+def redis_cli(*args):
+ proc = subprocess.run(
+ ["docker", "compose", "exec", "-T", "redis", "redis-cli", *args],
+ cwd=str(ROOT),
+ capture_output=True,
+ text=True,
+ timeout=20,
+ encoding="utf-8",
+ errors="replace",
+ )
+ if proc.returncode != 0:
+ raise Failure("redis-cli failed")
+ return proc.stdout.strip()
+
+
+def sql_quote(value):
+ text = str(value)
+ if "'" in text or ";" in text or "\n" in text:
+ raise Failure("refusing unsafe SQL literal")
+ return "'" + text + "'"
+
+
+def free_port():
+ with socket.socket() as sock:
+ sock.bind(("127.0.0.1", 0))
+ return sock.getsockname()[1]
+
+
+def wait_ready(timeout=90):
+ deadline = time.monotonic() + timeout
+ last = ""
+ while time.monotonic() < deadline:
+ try:
+ call("GET", "/health/ready", 200, timeout=5)
+ return
+ except Failure as exc:
+ last = str(exc)
+ time.sleep(0.5)
+ raise Failure("API did not become ready: " + last)
+
+
+def test_credentials():
+ user = register("cred")
+ wrong = call(
+ "POST",
+ "/api/v1/auth/sessions",
+ 401,
+ authorization=basic(user["username"], "wrong-password-value"),
+ )
+ missing = call(
+ "POST",
+ "/api/v1/auth/sessions",
+ 401,
+ authorization=basic("no_such_user_zz", "wrong-password-value"),
+ )
+ check(wrong["json"]["error"]["code"] == "unauthorized", "wrong password code")
+ check(wrong["json"]["error"]["message"] == missing["json"]["error"]["message"], "credential errors differ")
+ check(wrong["www"].lower().startswith("basic "), "basic challenge")
+ bare = call("GET", "/api/v1/users/me", 401)
+ check(bare["www"].lower().startswith("bearer "), "bearer challenge")
+ only_header = call("GET", "/api/v1/users/me", 401, user_id=user["id"])
+ check(only_header["json"]["error"]["code"] == "unauthorized", "X-User-Id alone was accepted")
+ other = register("other")
+ me = call("GET", "/api/v1/users/me", 200, token=user["token"], user_id=other["id"])["json"]
+ check(me["id"] == user["id"], "X-User-Id overrode bearer")
+ basic_on_api = call("GET", "/api/v1/users/me", 401, authorization=basic(user["username"], user["password"]))
+ check(basic_on_api["www"].lower().startswith("bearer "), "basic accepted on business API")
+ print("PASS: credentials, same 401, X-User-Id ignored")
+
+
+def test_unicode_password():
+ password = "Пароль:пример-12"
+ check(12 <= len(password) <= 128 and ":" in password, "fixture password")
+ user = register("uni", password=password)
+ again = call("POST", "/api/v1/auth/sessions", 201, authorization=basic(user["username"], password))["json"]
+ check(again["user"]["id"] == user["id"], "unicode password login failed")
+ print("PASS: unicode password with colon")
+
+
+def test_logout():
+ user = register("bye")
+ call("DELETE", "/api/v1/auth/sessions/current", 204, token=user["token"])
+ rejected = call("GET", "/api/v1/users/me", 401, token=user["token"])
+ check(rejected["www"].lower().startswith("bearer "), "revoked token challenge")
+ again = call("DELETE", "/api/v1/auth/sessions/current", 401, token=user["token"])
+ check(again["json"]["error"]["code"] == "unauthorized", "second logout")
+ print("PASS: logout revokes the session")
+
+
+def test_injection_and_rollback():
+ user = register("sql")
+ chat = call(
+ "POST",
+ "/api/v1/chats",
+ 201,
+ token=user["token"],
+ body={"title": "SQL", "member_ids": [user["id"]]},
+ )["json"]
+ payload = "'; DROP TABLE messages; --"
+ sent = call(
+ "POST",
+ "/api/v1/chats/%s/messages" % chat["id"],
+ 201,
+ token=user["token"],
+ body={"text": payload},
+ headers={"Idempotency-Key": uuid.uuid4().hex},
+ )["json"]
+ check(sent["text"] == payload, "text was rewritten")
+ check(psql("SELECT to_regclass('public.messages')") == "messages", "messages table disappeared")
+ listed = call("GET", "/api/v1/chats/%s/messages?limit=10" % chat["id"], 200, token=user["token"])["json"]
+ check(listed["items"][0]["text"] == payload, "stored text differs")
+
+ before = int(psql("SELECT count(*) FROM chats"))
+ title = "partial-" + uuid.uuid4().hex
+ rejected = call(
+ "POST",
+ "/api/v1/chats",
+ 400,
+ token=user["token"],
+ body={"title": title, "member_ids": [user["id"], str(uuid.uuid4())]},
+ )
+ check(rejected["json"]["error"]["code"] == "invalid_request", "unknown member code")
+ after = int(psql("SELECT count(*) FROM chats"))
+ check(before == after, "unknown member committed a chat")
+ check(psql("SELECT count(*) FROM chats WHERE title = %s" % sql_quote(title)) == "0", "partial chat row exists")
+ print("PASS: parameterized text and unknown-member chat is not stored")
+ return user, chat
+
+
+async def failpoint(owner_id, other_id, title):
+ os.environ["DATABASE_URL"] = host_secret("host_database_url")
+ os.environ["REDIS_URL"] = host_secret("host_cache_url")
+ from app.config import load_settings
+ from app.crud.chats import create_chat
+ from app.db import build_engine, build_session_factory
+ from app.runtime import configure
+ from app.sessions import build_redis
+
+ settings = load_settings()
+ engine = build_engine(settings)
+ redis = build_redis(settings)
+ configure(build_session_factory(engine), redis, settings)
+ try:
+ try:
+ await create_chat(
+ uuid.UUID(owner_id),
+ title,
+ (uuid.UUID(owner_id), uuid.UUID(other_id)),
+ fail_after_insert=True,
+ )
+ except RuntimeError as exc:
+ check(str(exc) == "rollback-check", "failpoint raised a different error")
+ else:
+ raise Failure("failpoint committed a chat")
+ finally:
+ await redis.aclose()
+ await engine.dispose()
+
+
+def test_failpoint(owner_id, other_id):
+ title = "rollback-" + uuid.uuid4().hex
+ before = int(psql("SELECT count(*) FROM chats"))
+ try:
+ asyncio.run(failpoint(owner_id, other_id, title))
+ except Failure:
+ raise
+ except Exception as exc:
+ raise Failure("rollback check failed: " + type(exc).__name__) from None
+ after = int(psql("SELECT count(*) FROM chats"))
+ left = psql("SELECT count(*) FROM chats WHERE title = %s" % sql_quote(title))
+ check(before == after and left == "0", "chat insert survived the rollback")
+ print("PASS: composite chat insert rolls back before commit")
+ return {"chats_before": before, "chats_after": after, "title_rows": int(left)}
+
+
+def test_race():
+ username = "race_" + uuid.uuid4().hex[:8]
+ password = "Race-password-" + uuid.uuid4().hex[:8]
+ body = {"username": username, "display_name": "Гонка", "password": password}
+ barrier = threading.Barrier(16)
+ statuses = []
+ lock = threading.Lock()
+
+ def worker():
+ try:
+ barrier.wait(20)
+ result = call("POST", "/api/v1/users", [201, 409], body=body, timeout=30)
+ with lock:
+ statuses.append(result["status"])
+ except Exception as exc:
+ with lock:
+ statuses.append(str(exc)[:120])
+
+ threads = [threading.Thread(target=worker) for _ in range(16)]
+ for thread in threads:
+ thread.start()
+ for thread in threads:
+ thread.join()
+ created = statuses.count(201)
+ conflict = statuses.count(409)
+ check(created == 1 and conflict == 15 and len(statuses) == 16, "race statuses %s" % statuses)
+ print("PASS: 16 parallel registrations, one 201 and fifteen 409")
+ return {"created": created, "conflict": conflict}
+
+
+def assert_plan(name, plan):
+ check("ix_messages_history" in plan, name + " plan ignores ix_messages_history")
+ check("Seq Scan" not in plan, name + " plan seq-scans messages")
+ check("Index Scan" in plan or "Index Only Scan" in plan, name + " plan is not an index scan")
+ check("Buffers:" in plan, name + " plan has no buffer stats")
+
+
+def test_explain(user):
+ chat = call(
+ "POST",
+ "/api/v1/chats",
+ 201,
+ token=user["token"],
+ body={"title": "План", "member_ids": [user["id"]]},
+ )["json"]
+ chat_sql = sql_quote(chat["id"])
+ user_sql = sql_quote(user["id"])
+ psql(
+ "INSERT INTO messages (id, chat_id, sender_id, body, created_at) "
+ "SELECT gen_random_uuid(), %s, %s, 'row-' || g, "
+ "TIMESTAMPTZ '2026-01-01 00:00:00+00' + (g || ' microseconds')::interval "
+ "FROM generate_series(1, 10000) AS g" % (chat_sql, user_sql),
+ timeout=60,
+ )
+ count = int(psql("SELECT count(*) FROM messages WHERE chat_id = %s" % chat_sql))
+ check(count >= 10000, "expected at least 10000 messages, got %s" % count)
+ psql("ANALYZE messages")
+ midpoint = psql(
+ "SELECT to_char(created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS.US'), id::text "
+ "FROM messages WHERE chat_id = %s ORDER BY created_at, id OFFSET 5000 LIMIT 1" % chat_sql
+ )
+ created_at, message_id = midpoint.split("|")
+ late = psql(
+ "EXPLAIN (ANALYZE, BUFFERS) SELECT id, body FROM messages "
+ "WHERE chat_id = %s AND (created_at, id) > (%s::timestamptz, %s::uuid) "
+ "ORDER BY created_at, id LIMIT 50"
+ % (chat_sql, sql_quote(created_at + "+00"), sql_quote(message_id)),
+ timeout=60,
+ )
+ first = psql(
+ "EXPLAIN (ANALYZE, BUFFERS) SELECT id, body FROM messages "
+ "WHERE chat_id = %s ORDER BY created_at, id LIMIT 50" % chat_sql,
+ timeout=60,
+ )
+ EVIDENCE.mkdir(exist_ok=True)
+ (EVIDENCE / "explain_messages.txt").write_text(
+ "messages=%s\n\n-- first page\n%s\n\n-- page after row 5000\n%s\n" % (count, first, late),
+ encoding="utf-8",
+ )
+ assert_plan("first", first)
+ assert_plan("late", late)
+ print("PASS: EXPLAIN uses ix_messages_history on %s messages" % count)
+ return {"messages": count, "chat_id": chat["id"]}
+
+
+def test_expiry_and_migrations():
+ from app.timeutil import parse_time
+
+ users_before = int(psql("SELECT count(*) FROM users"))
+ port = free_port()
+ env = os.environ.copy()
+ env["PYTHONPATH"] = str(ROOT / "src")
+ env["PYTHONUNBUFFERED"] = "1"
+ env["APP_HOST"] = "127.0.0.1"
+ env["APP_PORT"] = str(port)
+ env["APP_ENV"] = "lab"
+ env["DATABASE_URL"] = host_secret("host_database_url")
+ env["REDIS_URL"] = host_secret("host_cache_url")
+ env["SESSION_TTL_SECONDS"] = "2"
+ env.pop("DATABASE_URL_FILE", None)
+ env.pop("CACHE_URL_FILE", None)
+ proc = subprocess.Popen(
+ [sys.executable, "-m", "app"],
+ cwd=str(ROOT),
+ env=env,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ )
+ logs = []
+
+ def read_logs():
+ if proc.stdout is None:
+ return
+ for line in proc.stdout:
+ if "://" not in line and "password" not in line.lower():
+ logs.append(line)
+
+ reader = threading.Thread(target=read_logs, daemon=True)
+ reader.start()
+ base = "http://127.0.0.1:%s" % port
+ try:
+ deadline = time.monotonic() + 40
+ ready = False
+ while time.monotonic() < deadline:
+ if proc.poll() is not None:
+ raise Failure("short-ttl server exited: " + "".join(logs[-8:]))
+ try:
+ urllib.request.urlopen(base + "/health/ready", timeout=2).read()
+ ready = True
+ break
+ except (urllib.error.URLError, TimeoutError, OSError):
+ time.sleep(0.2)
+ check(ready, "short-ttl server did not become ready: " + "".join(logs[-8:]))
+ username = "ttl_" + uuid.uuid4().hex[:8]
+ password = "Ttl-password-" + uuid.uuid4().hex[:8]
+ body = json.dumps(
+ {"username": username, "display_name": "TTL", "password": password},
+ ensure_ascii=False,
+ ).encode("utf-8")
+ request = urllib.request.Request(
+ base + "/api/v1/users",
+ data=body,
+ headers={"Content-Type": "application/json", "Accept": "application/json"},
+ method="POST",
+ )
+ with urllib.request.urlopen(request, timeout=20) as response:
+ created = json.loads(response.read())
+ login = urllib.request.Request(
+ base + "/api/v1/auth/sessions",
+ data=b"",
+ headers={"Authorization": basic(username, password), "Accept": "application/json"},
+ method="POST",
+ )
+ with urllib.request.urlopen(login, timeout=20) as response:
+ session = json.loads(response.read())
+ expires = parse_time(session["expires_at"])
+ delta = (expires - datetime.now(timezone.utc)).total_seconds()
+ check(0 < delta <= 3, "SESSION_TTL_SECONDS=2 was not applied")
+ time.sleep(delta + 1.0)
+ probe = urllib.request.Request(
+ base + "/api/v1/users/me",
+ headers={"Authorization": "Bearer " + session["token"], "Accept": "application/json"},
+ )
+ try:
+ with urllib.request.urlopen(probe, timeout=10) as response:
+ status = response.status
+ except urllib.error.HTTPError as error:
+ status = error.status
+ check(status == 401, "expired session status %s" % status)
+ finally:
+ if proc.poll() is None:
+ proc.terminate()
+ try:
+ proc.wait(timeout=8)
+ except subprocess.TimeoutExpired:
+ proc.kill()
+ proc.wait(timeout=5)
+ reader.join(timeout=2)
+ users_after = int(psql("SELECT count(*) FROM users"))
+ versions = psql("SELECT count(*) FROM schema_migrations")
+ version_name = psql("SELECT version FROM schema_migrations ORDER BY version")
+ check(users_after == users_before + 1, "migrations duplicated or dropped users")
+ names = psql("SELECT version FROM schema_migrations ORDER BY version")
+ check(versions == "2", "expected two applied migrations, got %s" % versions)
+ check("001_initial.sql" in names and "002_idempotency.sql" in names, "migration set changed: %s" % names)
+ print("PASS: short TTL expires and migrations stay idempotent")
+ return {"users_before": users_before, "users_after": users_after, "migration": version_name}
+
+
+def test_redis_persistence(user):
+ from app.sessions import session_key
+
+ before = int(redis_cli("PTTL", session_key(user["token"])))
+ check(before > 300000, "session ttl is unexpectedly short")
+ compose("restart", "redis")
+ wait_ready()
+ after = int(redis_cli("PTTL", session_key(user["token"])))
+ check(after > 0, "session disappeared after redis restart")
+ check(after <= before + 1000, "redis restart extended the session ttl")
+ me = call("GET", "/api/v1/users/me", 200, token=user["token"])["json"]
+ check(me["id"] == user["id"], "token did not survive redis restart")
+ print("PASS: Redis AOF kept the session and did not refresh TTL")
+ return {"pttl_before_ms": before, "pttl_after_ms": after}
+
+
+def test_dependency_loss(user, chat_id):
+ observed = {}
+ compose("stop", "redis")
+ try:
+ live = call("GET", "/health/live", 200)
+ ready = call("GET", "/health/ready", 503)
+ anonymous = call("GET", "/api/v1/users/me", 401)
+ trusted = call("GET", "/api/v1/users/me", 503, token=user["token"])
+ check(live["json"]["status"] == "ok", "live failed while redis is down")
+ check(ready["json"]["error"]["code"] == "unavailable", "ready code")
+ check(anonymous["json"]["error"]["code"] == "unauthorized", "anonymous became trusted")
+ check(trusted["json"]["error"]["code"] == "unavailable", "unverified token was accepted")
+ observed["redis_down"] = {
+ "live": live["status"],
+ "ready": ready["status"],
+ "anonymous": anonymous["status"],
+ "bearer": trusted["status"],
+ }
+ finally:
+ compose("start", "redis")
+ wait_ready()
+ me = call("GET", "/api/v1/users/me", 200, token=user["token"])["json"]
+ check(me["id"] == user["id"], "token lost after redis came back")
+
+ compose("stop", "postgres")
+ try:
+ live = call("GET", "/health/live", 200)
+ ready = call("GET", "/health/ready", 503, timeout=20)
+ anonymous = call("GET", "/api/v1/users/me", 401, timeout=20)
+ denied = call("GET", "/api/v1/chats/" + chat_id, 503, token=user["token"], timeout=20)
+ check(live["json"]["status"] == "ok", "live depends on postgres")
+ check(ready["json"]["error"]["code"] == "unavailable", "ready while postgres is down")
+ check(anonymous["json"]["error"]["code"] == "unauthorized", "anonymous trusted without postgres")
+ check(denied["json"]["error"]["code"] == "unavailable", "request served without postgres")
+ observed["postgres_down"] = {
+ "live": live["status"],
+ "ready": ready["status"],
+ "anonymous": anonymous["status"],
+ "bearer": denied["status"],
+ }
+ finally:
+ compose("start", "postgres")
+ wait_ready(timeout=90)
+ history = call("GET", "/api/v1/chats/%s/messages?limit=5" % chat_id, 200, token=user["token"])["json"]
+ check(history["items"], "messages lost after postgres restart")
+ print("PASS: redis and postgres outages return 503 and do not trust anonymous clients")
+ return observed
+
+
+def main():
+ os.environ["DATABASE_URL"] = host_secret("host_database_url")
+ os.environ["REDIS_URL"] = host_secret("host_cache_url")
+ wait_ready(timeout=60)
+ test_credentials()
+ test_unicode_password()
+ test_logout()
+ user, chat = test_injection_and_rollback()
+ other = register("pair")
+ rollback = test_failpoint(user["id"], other["id"])
+ race = test_race()
+ explain = test_explain(user)
+ expiry = test_expiry_and_migrations()
+ pttl = test_redis_persistence(user)
+ faults = test_dependency_loss(user, chat["id"])
+ remaining = int(psql("SELECT count(*) FROM messages WHERE chat_id = %s" % sql_quote(explain["chat_id"])))
+ check(remaining == explain["messages"], "bulk history lost after postgres restart")
+ EVIDENCE.mkdir(exist_ok=True)
+ report = {
+ "date": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+ "base_url": BASE,
+ "race": race,
+ "rollback": rollback,
+ "explain": {"messages": explain["messages"]},
+ "expiry_and_migrations": expiry,
+ "redis_restart": pttl,
+ "dependency_loss": faults,
+ "messages_after_postgres_restart": remaining,
+ }
+ (EVIDENCE / "level4.json").write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ print("PASS: level 4 checks")
+
+
+if __name__ == "__main__":
+ try:
+ main()
+ except Failure as exc:
+ print("FAIL:", exc)
+ sys.exit(1)
diff --git a/student-tests/persistence.py b/student-tests/persistence.py
new file mode 100644
index 00000000..d2edcf6c
--- /dev/null
+++ b/student-tests/persistence.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Тот же сценарий, что tests/resilience.py, но hook запускается так, как умеет ОС.
+
+Linux выполняет scripts/restart.sh напрямую.
+Windows не умеет CreateProcess для shell-скрипта, поэтому здесь используется Git Bash.
+Скрипт тот же: перезапуск api, postgres и redis без удаления томов.
+"""
+
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from urllib.parse import quote
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "tests"))
+
+from client import Client, Failure, check, run
+
+
+def hook_command():
+ script = ROOT / "scripts" / "restart.sh"
+ if os.name != "nt":
+ return [str(script)]
+ bash = Path(os.environ.get("BASH", r"C:\Program Files\Git\bin\bash.exe"))
+ check(bash.is_file(), "Git Bash is required to launch scripts/restart.sh on Windows")
+ return [str(bash), "-c", "sh scripts/restart.sh"]
+
+
+def history(client, actor, chat):
+ path = "/api/v1/chats/" + chat["id"] + "/messages?limit=100"
+ result = []
+ seen = set()
+ for _ in range(1000):
+ page = client.call("GET", path, actor=actor, schema="MessagePage")["json"]
+ result.extend(page["items"])
+ cursor = page["next_cursor"]
+ if cursor is None:
+ return result
+ check(cursor not in seen, "cursor cycle")
+ seen.add(cursor)
+ path = "/api/v1/chats/" + chat["id"] + "/messages?limit=100&cursor=" + quote(cursor, safe="")
+ raise Failure("history pagination exceeded safety bound")
+
+
+def main():
+ client = Client("http://127.0.0.1:8080", timeout=5)
+ alice, bob, _eve, chat = client.bootstrap()
+ original = client.message(alice, chat, "Сохранить при отказе")["json"]
+ print("Executing scripts/restart.sh")
+ completed = subprocess.run(hook_command(), cwd=str(ROOT))
+ check(completed.returncode == 0, "restart hook failed")
+ deadline = time.monotonic() + 90
+ while True:
+ try:
+ client.call("GET", "/health/ready", schema="Health")
+ client.call("GET", "/api/v1/users/me", actor=alice, schema="User")
+ break
+ except Failure:
+ check(time.monotonic() < deadline, "stack/session did not recover within 90 seconds")
+ time.sleep(0.5)
+ messages = history(client, bob, chat)
+ check(any(item == original for item in messages), "confirmed message lost or altered")
+ print("PASS: persistence preserved confirmed data and existing session")
+
+
+if __name__ == "__main__":
+ run(main)
diff --git a/student-tests/persistence_hook.py b/student-tests/persistence_hook.py
new file mode 100644
index 00000000..db14fd87
--- /dev/null
+++ b/student-tests/persistence_hook.py
@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Публичный persistence-сценарий с restart.cmd на Windows и restart.sh на POSIX."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def script():
+ if os.name == "nt":
+ cmd = ROOT / "scripts" / "restart.cmd"
+ if cmd.is_file():
+ return str(cmd)
+ return str(ROOT / "scripts" / "restart.sh")
+
+
+def main():
+ env = os.environ.copy()
+ command = [
+ sys.executable,
+ str(ROOT / "tests" / "resilience.py"),
+ "--mode",
+ "persistence",
+ "--action-script",
+ script(),
+ "--base-url",
+ env.get("BASE_URL", "http://127.0.0.1:8080"),
+ ]
+ completed = subprocess.run(command, cwd=str(ROOT), env=env)
+ raise SystemExit(completed.returncode)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/student-tests/rolling.py b/student-tests/rolling.py
new file mode 100644
index 00000000..e697ee2a
--- /dev/null
+++ b/student-tests/rolling.py
@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Поочерёдная замена API-реплик под нагрузкой POST сообщений."""
+
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "tests"))
+from client import Client, Failure, check, run
+
+EVIDENCE = ROOT / "evidence"
+BASE = os.environ.get("BASE_URL", "http://127.0.0.1:8080").rstrip("/")
+
+
+def compose(*args, timeout=180):
+ proc = subprocess.run(
+ ["docker", "compose", "--env-file", ".env", *args],
+ cwd=str(ROOT),
+ capture_output=True,
+ text=True,
+ timeout=timeout,
+ encoding="utf-8",
+ errors="replace",
+ )
+ if proc.returncode != 0:
+ raise Failure("docker compose %s failed" % args[0])
+ return proc.stdout
+
+
+def api_ids():
+ return [line.strip() for line in compose("ps", "-q", "api").splitlines() if line.strip()]
+
+
+def inspect_health(container_id):
+ proc = subprocess.run(
+ ["docker", "inspect", "-f", "{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}", container_id],
+ capture_output=True,
+ text=True,
+ timeout=20,
+ encoding="utf-8",
+ errors="replace",
+ )
+ return proc.stdout.strip()
+
+
+def wait_healthy(container_id, timeout=90):
+ deadline = time.monotonic() + timeout
+ last = ""
+ while time.monotonic() < deadline:
+ last = inspect_health(container_id)
+ if last == "healthy":
+ return
+ time.sleep(0.5)
+ raise Failure("replica %s did not become healthy: %s" % (container_id[:12], last))
+
+
+def wait_ready(timeout=90):
+ client = Client(BASE, timeout=3)
+ deadline = time.monotonic() + timeout
+ last = ""
+ while time.monotonic() < deadline:
+ try:
+ client.call("GET", "/health/ready", schema="Health")
+ return
+ except Failure as exc:
+ last = str(exc)
+ time.sleep(0.4)
+ raise Failure("LB ready wait failed: " + last)
+
+
+def main():
+ client = Client(BASE, timeout=8)
+ alice, _bob, _eve, chat = client.bootstrap()
+ halt = threading.Event()
+ latencies = []
+ errors = []
+ lock = threading.Lock()
+
+ def worker(index):
+ local = Client(BASE, timeout=5)
+ n = 0
+ while not halt.is_set():
+ started = time.monotonic()
+ try:
+ local.message(alice, chat, "rolling-%s-%s" % (index, n))
+ with lock:
+ latencies.append(time.monotonic() - started)
+ except Failure:
+ with lock:
+ errors.append(time.monotonic())
+ n += 1
+
+ threads = [threading.Thread(target=worker, args=(i,), daemon=True) for i in range(4)]
+ for thread in threads:
+ thread.start()
+ time.sleep(5)
+ before = api_ids()
+ check(len(before) >= 2, "rolling update needs >=2 replicas")
+ compose("build", "api")
+ replaced = []
+ for old in list(before):
+ current = api_ids()
+ compose("up", "-d", "--no-deps", "--scale", "api=%d" % (len(current) + 1), "--no-recreate", "api")
+ deadline = time.monotonic() + 60
+ new_ids = api_ids()
+ while len(new_ids) <= len(current) and time.monotonic() < deadline:
+ time.sleep(0.5)
+ new_ids = api_ids()
+ added = [item for item in new_ids if item not in current]
+ check(added, "new replica was not created")
+ wait_healthy(added[-1])
+ wait_ready()
+ subprocess.run(["docker", "stop", "-t", "5", old], capture_output=True)
+ subprocess.run(["docker", "rm", "-f", old], capture_output=True)
+ remaining = api_ids()
+ check(old not in remaining, "old replica %s still in service" % old[:12])
+ compose("up", "-d", "--no-deps", "--scale", "api=%d" % len(before), "api")
+ wait_ready()
+ replaced.append(old[:12])
+ time.sleep(5)
+ halt.set()
+ for thread in threads:
+ thread.join(timeout=10)
+ after = api_ids()
+ check(len(after) >= 2, "lost replicas after rolling update")
+ check(len(latencies) > 0, "no successful writes during rolling update")
+ report = {
+ "date": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+ "replaced": replaced,
+ "replicas_before": [item[:12] for item in before],
+ "replicas_after": [item[:12] for item in after],
+ "successful_writes": len(latencies),
+ "failed_writes": len(errors),
+ "error_ratio": round(len(errors) / max(1, len(latencies) + len(errors)), 6),
+ }
+ EVIDENCE.mkdir(exist_ok=True)
+ (EVIDENCE / "rolling.json").write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ print("PASS: rolling update under load")
+ print(json.dumps(report, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+ run(main)
diff --git a/student-tests/run.py b/student-tests/run.py
new file mode 100644
index 00000000..4d57eb14
--- /dev/null
+++ b/student-tests/run.py
@@ -0,0 +1,505 @@
+#!/usr/bin/env python3
+
+import base64
+import json
+import os
+import socket
+import subprocess
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from pathlib import Path
+from urllib.parse import quote
+
+ROOT = Path(__file__).resolve().parents[1]
+EVIDENCE = ROOT / "evidence"
+SECRET = "SECRET_MESSAGE_DO_NOT_LOG_7f3a"
+CLIENTS = 10
+PER_CLIENT = 10
+
+
+class Failure(AssertionError):
+ pass
+
+
+def check(condition, message):
+ if not condition:
+ raise Failure(message)
+
+
+def free_port():
+ with socket.socket() as sock:
+ sock.bind(("127.0.0.1", 0))
+ return sock.getsockname()[1]
+
+
+class Server:
+ def __init__(self, port):
+ self.base = "http://127.0.0.1:%d" % port
+ env = os.environ.copy()
+ env["PYTHONPATH"] = str(ROOT / "src")
+ env["PYTHONUNBUFFERED"] = "1"
+ env["APP_HOST"] = "127.0.0.1"
+ env["APP_PORT"] = str(port)
+ env["APP_ENV"] = "lab"
+ env["DATABASE_URL"] = host_secret("host_database_url")
+ env["REDIS_URL"] = host_secret("host_cache_url")
+ env["SESSION_TTL_SECONDS"] = "3600"
+ env.pop("DATABASE_URL_FILE", None)
+ env.pop("CACHE_URL_FILE", None)
+ self.logs = []
+ self.proc = subprocess.Popen(
+ [sys.executable, "-m", "app"],
+ cwd=str(ROOT),
+ env=env,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ )
+ self._reader = threading.Thread(target=self._read, daemon=True)
+ self._reader.start()
+
+ def _read(self):
+ assert self.proc.stdout is not None
+ for line in self.proc.stdout:
+ self.logs.append(line)
+
+ def wait_ready(self):
+ deadline = time.monotonic() + 40
+ last = ""
+ while time.monotonic() < deadline:
+ if self.proc.poll() is not None:
+ raise Failure("server exited early:\n" + "".join(self.logs[-40:]))
+ try:
+ call(self.base, "GET", "/health/ready", 200)
+ return
+ except Failure as exc:
+ last = str(exc)
+ except (urllib.error.URLError, TimeoutError, OSError) as exc:
+ last = type(exc).__name__
+ time.sleep(0.1)
+ raise Failure("server did not become ready: " + last + "\n" + "".join(self.logs[-40:]))
+
+ def stop(self):
+ if self.proc.poll() is None:
+ self.proc.terminate()
+ try:
+ self.proc.wait(timeout=8)
+ except subprocess.TimeoutExpired:
+ self.proc.kill()
+ self.proc.wait(timeout=5)
+ self._reader.join(timeout=2)
+
+ def output(self):
+ return "".join(self.logs)
+
+
+def host_secret(name):
+ path = ROOT / "secrets" / name
+ if not path.is_file():
+ raise Failure("missing secrets/%s; run scripts/bootstrap.ps1 or scripts/bootstrap.sh" % name)
+ value = path.read_text(encoding="utf-8").strip()
+ if not value:
+ raise Failure("empty secrets/%s" % name)
+ return value
+
+
+def call(
+ base,
+ method,
+ path,
+ expected,
+ body=None,
+ token=None,
+ user_id=None,
+ authorization=None,
+ raw=None,
+ content_type="application/json",
+ timeout=20,
+ headers=None,
+):
+ extra_headers = headers or {}
+ headers = {"Accept": "application/json"}
+ headers.update(extra_headers)
+ data = None
+ if raw is not None:
+ data = raw
+ headers["Content-Type"] = content_type
+ elif body is not None:
+ data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+ headers["Content-Type"] = content_type
+ if authorization:
+ headers["Authorization"] = authorization
+ elif token:
+ headers["Authorization"] = "Bearer " + token
+ if user_id:
+ headers["X-User-Id"] = user_id
+ request = urllib.request.Request(base + path, data=data, headers=headers, method=method)
+ try:
+ response = urllib.request.urlopen(request, timeout=timeout)
+ except urllib.error.HTTPError as error:
+ response = error
+ except (urllib.error.URLError, TimeoutError, OSError) as exc:
+ raise Failure(method + " " + path.split("?")[0] + " failed: " + type(exc).__name__) from None
+ with response:
+ status = response.status
+ payload = response.read()
+ header_id = response.headers.get("X-Request-Id")
+ instance_id = response.headers.get("X-Instance-Id")
+ content_type_value = response.headers.get_content_type()
+ allowed = [expected] if isinstance(expected, int) else list(expected)
+ check(status in allowed, "%s %s: expected %s, got %s" % (method, path.split("?")[0], allowed, status))
+ check(header_id and header_id.strip() and "," not in header_id, "missing or duplicated X-Request-Id")
+ check(instance_id and instance_id.strip() and "," not in instance_id, "missing or duplicated X-Instance-Id")
+ parsed = None
+ if payload:
+ check(content_type_value == "application/json", "expected application/json")
+ try:
+ parsed = json.loads(payload)
+ except json.JSONDecodeError as exc:
+ raise Failure("response is not JSON") from exc
+ if status >= 400:
+ check(isinstance(parsed, dict) and set(parsed) == {"error"}, "error envelope")
+ error = parsed["error"]
+ check(set(error) == {"code", "message", "request_id"}, "error fields")
+ check(error["request_id"] == header_id, "request_id differs from header")
+ check(error["message"] and "Traceback" not in error["message"], "error message leaked internals")
+ return {"status": status, "json": parsed, "request_id": header_id, "instance_id": instance_id}
+
+
+def send_message(base, chat_id, token, text, expected=201, key=None):
+ headers = {"Idempotency-Key": key or uuid.uuid4().hex}
+ return call(
+ base,
+ "POST",
+ "/api/v1/chats/%s/messages" % chat_id,
+ expected,
+ token=token,
+ body={"text": text},
+ headers=headers,
+ )
+
+
+def create_user(base, label):
+ username = ("u_%s_%s" % (label, uuid.uuid4().hex[:10])).lower()
+ password = "T3st-" + uuid.uuid4().hex
+ body = {"username": username, "display_name": "Студент " + label, "password": password}
+ created = call(base, "POST", "/api/v1/users", 201, body=body)["json"]
+ check(created["username"] == username, "username changed")
+ check("password" not in created, "password leaked in user response")
+ raw = base64.b64encode(("%s:%s" % (username, password)).encode("utf-8")).decode("ascii")
+ session = call(base, "POST", "/api/v1/auth/sessions", 201, authorization="Basic " + raw)["json"]
+ check(session["token_type"] == "Bearer", "token type")
+ check(session["user"]["id"] == created["id"], "session user")
+ check("password" not in session["user"], "password leaked in session")
+ created["token"] = session["token"]
+ created["instance_id"] = session.get("instance_id")
+ return created
+
+
+def replace_cursor(token, fields):
+ padding = "=" * (-len(token) % 4)
+ data = json.loads(base64.urlsafe_b64decode(token + padding))
+ data.update(fields)
+ raw = json.dumps(data, separators=(",", ":"), sort_keys=True).encode("ascii")
+ return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def test_invalid_json(base):
+ broken = call(base, "POST", "/api/v1/users", 400, raw=b"{")
+ check(broken["json"]["error"]["code"] == "invalid_request", "malformed JSON code")
+ extra = call(
+ base,
+ "POST",
+ "/api/v1/users",
+ 400,
+ body={"username": "abc_user", "display_name": "Имя", "extra": True},
+ )
+ check(extra["json"]["error"]["code"] == "invalid_request", "extra field code")
+ bad_utf = call(base, "POST", "/api/v1/users", 400, raw=b"\xff")
+ check(bad_utf["json"]["error"]["code"] == "invalid_request", "invalid utf-8 code")
+ alice = create_user(base, "utf")
+ chat = call(
+ base,
+ "POST",
+ "/api/v1/chats",
+ 201,
+ token=alice["token"],
+ body={"title": "UTF", "member_ids": [alice["id"]]},
+ )["json"]
+ bad_message = call(
+ base,
+ "POST",
+ "/api/v1/chats/%s/messages" % chat["id"],
+ 400,
+ token=alice["token"],
+ raw=b"\xff",
+ headers={"Idempotency-Key": uuid.uuid4().hex},
+ )
+ check(bad_message["json"]["error"]["code"] == "invalid_request", "invalid utf-8 message code")
+ print("PASS: invalid JSON")
+
+
+def test_duplicate_username(base):
+ first = create_user(base, "dup")
+ again = call(
+ base,
+ "POST",
+ "/api/v1/users",
+ 409,
+ body={
+ "username": first["username"],
+ "display_name": "Другой",
+ "password": "T3st-" + uuid.uuid4().hex,
+ },
+ )
+ check(again["json"]["error"]["code"] == "conflict", "duplicate username code")
+ me = call(base, "GET", "/api/v1/users/me", 200, token=first["token"])["json"]
+ check(me["id"] == first["id"], "first user disappeared after duplicate")
+ print("PASS: duplicate username")
+
+
+def test_empty_and_foreign(base):
+ alice = create_user(base, "alice")
+ bob = create_user(base, "bob")
+ chat = call(
+ base,
+ "POST",
+ "/api/v1/chats",
+ 201,
+ token=alice["token"],
+ body={"title": "Только Алиса", "member_ids": [alice["id"]]},
+ )["json"]
+ path = "/api/v1/chats/" + chat["id"]
+ for text in ("", " ", "\n\t"):
+ denied = call(
+ base,
+ "POST",
+ path + "/messages",
+ 400,
+ token=alice["token"],
+ body={"text": text},
+ headers={"Idempotency-Key": uuid.uuid4().hex},
+ )
+ check(denied["json"]["error"]["code"] == "invalid_request", "empty message code")
+ for method, target, payload in (
+ ("GET", path, None),
+ ("GET", path + "/messages", None),
+ ("POST", path + "/messages", {"text": "чужое"}),
+ ):
+ extra = {"Idempotency-Key": uuid.uuid4().hex} if method == "POST" else None
+ hidden = call(base, method, target, 404, token=bob["token"], body=payload, headers=extra)
+ check(hidden["json"]["error"]["code"] == "not_found", "foreign chat code")
+ check(chat["title"] not in hidden["json"]["error"]["message"], "foreign chat leaked title")
+ listed = call(base, "GET", "/api/v1/chats?limit=100", 200, token=bob["token"])["json"]
+ check(all(item["id"] != chat["id"] for item in listed["items"]), "foreign chat listed")
+ missing = call(base, "GET", "/api/v1/chats/" + str(uuid.uuid4()), 404, token=bob["token"])
+ check(missing["json"]["error"]["code"] == "not_found", "missing chat code")
+ bad_limit = call(base, "GET", path + "/messages?limit=0", 400, token=alice["token"])
+ check(bad_limit["json"]["error"]["code"] == "invalid_request", "limit=0 code")
+ print("PASS: empty message and foreign chat")
+
+
+def test_pagination(base):
+ alice = create_user(base, "page")
+ other = create_user(base, "other")
+ chat = call(
+ base,
+ "POST",
+ "/api/v1/chats",
+ 201,
+ token=alice["token"],
+ body={"title": "Страницы", "member_ids": [alice["id"]]},
+ )["json"]
+ other_chat = call(
+ base,
+ "POST",
+ "/api/v1/chats",
+ 201,
+ token=other["token"],
+ body={"title": "Другой", "member_ids": [other["id"]]},
+ )["json"]
+ texts = ["p0", "Привет, мир 👋", "p2", "p3", "p4"]
+ created = []
+ for text in texts:
+ created.append(send_message(base, chat["id"], alice["token"], text)["json"])
+ send_message(base, other_chat["id"], other["token"], "x")
+ send_message(base, other_chat["id"], other["token"], "y")
+ collected = []
+ cursor = None
+ pages = 0
+ while True:
+ target = "/api/v1/chats/%s/messages?limit=2" % chat["id"]
+ if cursor:
+ target += "&cursor=" + quote(cursor, safe="")
+ page = call(base, "GET", target, 200, token=alice["token"])["json"]
+ pages += 1
+ collected.extend(page["items"])
+ cursor = page["next_cursor"]
+ if cursor is None:
+ break
+ check(pages < 10, "pagination did not finish")
+ check(pages == 3, "expected 3 pages, got %d" % pages)
+ check(collected == created, "pagination lost, duplicated or reordered messages")
+ stolen = call(
+ base,
+ "GET",
+ "/api/v1/chats/%s/messages?limit=1" % other_chat["id"],
+ 200,
+ token=other["token"],
+ )["json"]
+ check(stolen["next_cursor"], "foreign page should expose a cursor")
+ rejected = call(
+ base,
+ "GET",
+ "/api/v1/chats/%s/messages?limit=2&cursor=%s" % (chat["id"], quote(stolen["next_cursor"], safe="")),
+ 400,
+ token=alice["token"],
+ )
+ check(rejected["json"]["error"]["code"] == "invalid_request", "foreign cursor code")
+ first_page = call(
+ base,
+ "GET",
+ "/api/v1/chats/%s/messages?limit=1" % chat["id"],
+ 200,
+ token=alice["token"],
+ )["json"]
+ for fields in ({"t": None}, {"t": 123}, {"i": 123}):
+ broken = call(
+ base,
+ "GET",
+ "/api/v1/chats/%s/messages?limit=1&cursor=%s"
+ % (chat["id"], quote(replace_cursor(first_page["next_cursor"], fields), safe="")),
+ 400,
+ token=alice["token"],
+ )
+ check(broken["json"]["error"]["code"] == "invalid_request", "tampered cursor code")
+ print("PASS: pagination")
+
+
+def test_concurrency(base):
+ users = [create_user(base, "c%d" % index) for index in range(CLIENTS)]
+ chat = call(
+ base,
+ "POST",
+ "/api/v1/chats",
+ 201,
+ token=users[0]["token"],
+ body={"title": "Гонка", "member_ids": [user["id"] for user in users]},
+ )["json"]
+ barrier = threading.Barrier(CLIENTS)
+ found = []
+ errors = []
+ lock = threading.Lock()
+
+ def worker(user):
+ try:
+ barrier.wait(10)
+ local = []
+ for index in range(PER_CLIENT):
+ message = send_message(
+ base,
+ chat["id"],
+ user["token"],
+ "m-%s-%d" % (user["id"][:8], index),
+ )["json"]
+ local.append(message["id"])
+ with lock:
+ found.extend(local)
+ except Exception as exc:
+ with lock:
+ errors.append("%s: %s" % (type(exc).__name__, exc))
+
+ threads = [threading.Thread(target=worker, args=(user,)) for user in users]
+ for thread in threads:
+ thread.start()
+ for thread in threads:
+ thread.join()
+ check(not errors, "concurrent sends failed: " + "; ".join(errors[:5]))
+ check(len(found) == CLIENTS * PER_CLIENT, "submitted count")
+ check(len(set(found)) == CLIENTS * PER_CLIENT, "duplicate message ids")
+
+ listed = []
+ cursor = None
+ while True:
+ target = "/api/v1/chats/%s/messages?limit=40" % chat["id"]
+ if cursor:
+ target += "&cursor=" + quote(cursor, safe="")
+ page = call(base, "GET", target, 200, token=users[0]["token"])["json"]
+ listed.extend(item["id"] for item in page["items"])
+ cursor = page["next_cursor"]
+ if cursor is None:
+ break
+ check(len(listed) == 100 and len(set(listed)) == 100, "history does not contain 100 unique messages")
+ check(set(listed) == set(found), "history ids differ from accepted sends")
+ EVIDENCE.mkdir(exist_ok=True)
+ report = {
+ "date": "2026-10-25",
+ "command": "python student-tests/run.py",
+ "clients": CLIENTS,
+ "messages_per_client": PER_CLIENT,
+ "submitted": len(found),
+ "unique_ids": len(set(found)),
+ "listed": len(listed),
+ "failed_requests": len(errors),
+ "pass": True,
+ }
+ (EVIDENCE / "concurrency.json").write_text(
+ json.dumps(report, ensure_ascii=False, indent=2) + "\n",
+ encoding="utf-8",
+ )
+ print("PASS: concurrency 100 unique messages from 10 clients")
+
+
+def test_logs(server):
+ alice = create_user(server.base, "logs")
+ chat = call(
+ server.base,
+ "POST",
+ "/api/v1/chats",
+ 201,
+ token=alice["token"],
+ body={"title": "Логи", "member_ids": [alice["id"]]},
+ )["json"]
+ send_message(server.base, chat["id"], alice["token"], SECRET)
+ time.sleep(0.2)
+ output = server.output()
+ check("duration_ms=" in output and "method=POST" in output, "request log line missing")
+ check(SECRET not in output, "message text leaked into logs")
+ check(alice["token"] not in output, "session token leaked into logs")
+ check("lab-only-password" not in output and "postgresql+asyncpg://" not in output, "database url leaked into logs")
+ print("PASS: logs omit message text")
+
+
+def main():
+ port = free_port()
+ server = Server(port)
+ try:
+ server.wait_ready()
+ call(server.base, "GET", "/health/live", 200)
+ call(server.base, "GET", "/api/v1/users/me", 401)
+ header_only = create_user(server.base, "header")
+ rejected = call(server.base, "GET", "/api/v1/users/me", 401, user_id=header_only["id"])
+ check(rejected["json"]["error"]["code"] == "unauthorized", "X-User-Id was accepted")
+ test_invalid_json(server.base)
+ test_duplicate_username(server.base)
+ test_empty_and_foreign(server.base)
+ test_pagination(server.base)
+ test_concurrency(server.base)
+ test_logs(server)
+ finally:
+ server.stop()
+ print("PASS: student tests")
+
+
+if __name__ == "__main__":
+ try:
+ main()
+ except Failure as exc:
+ print("FAIL:", exc)
+ sys.exit(1)
diff --git a/student-tests/track1.py b/student-tests/track1.py
new file mode 100644
index 00000000..6cb94f5b
--- /dev/null
+++ b/student-tests/track1.py
@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Трек 5.1: цена масштабирования API при фиксированном и растущем бюджете CPU/RAM."""
+
+import json
+import math
+import os
+import subprocess
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "tests"))
+from client import Client, Failure, check, run
+
+EVIDENCE = ROOT / "evidence"
+BASE = os.environ.get("BASE_URL", "http://127.0.0.1:8080").rstrip("/")
+DURATION = float(os.environ.get("TRACK1_DURATION", "30"))
+CONCURRENCY = int(os.environ.get("TRACK1_CONCURRENCY", "8"))
+WARMUP = float(os.environ.get("TRACK1_WARMUP", "8"))
+
+
+def compose(*args, timeout=180):
+ proc = subprocess.run(
+ ["docker", "compose", "--env-file", ".env", *args],
+ cwd=str(ROOT),
+ capture_output=True,
+ text=True,
+ timeout=timeout,
+ encoding="utf-8",
+ errors="replace",
+ )
+ if proc.returncode != 0:
+ raise Failure("docker compose %s failed: %s" % (args[0], proc.stderr[-400:]))
+ return proc.stdout
+
+
+def api_ids():
+ return [line.strip() for line in compose("ps", "-q", "api").splitlines() if line.strip()]
+
+
+def wait_ready(timeout=90):
+ client = Client(BASE, timeout=3)
+ deadline = time.monotonic() + timeout
+ last = ""
+ while time.monotonic() < deadline:
+ try:
+ client.call("GET", "/health/ready", schema="Health")
+ return
+ except Failure as exc:
+ last = str(exc)
+ time.sleep(0.4)
+ raise Failure("ready wait failed: " + last)
+
+
+def scale_api(n):
+ compose("up", "-d", "--no-deps", "--scale", "api=%d" % n, "api")
+ deadline = time.monotonic() + 90
+ while time.monotonic() < deadline:
+ if len(api_ids()) >= n:
+ wait_ready()
+ return
+ time.sleep(0.5)
+ raise Failure("failed to scale api to %s" % n)
+
+
+def apply_limits(cpus_each, memory_mb_each):
+ for container_id in api_ids():
+ args = ["docker", "update", "--cpus", "%.3f" % cpus_each, "--memory", "%dm" % memory_mb_each, container_id]
+ proc = subprocess.run(args, capture_output=True, text=True, timeout=30)
+ if proc.returncode != 0:
+ raise Failure("docker update failed")
+
+
+def docker_stats():
+ proc = subprocess.run(
+ ["docker", "stats", "--no-stream", "--format", "{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"],
+ capture_output=True,
+ text=True,
+ timeout=30,
+ encoding="utf-8",
+ errors="replace",
+ )
+ rows = []
+ for line in proc.stdout.splitlines():
+ parts = line.split("\t")
+ if len(parts) == 3:
+ rows.append({"name": parts[0], "cpu": parts[1], "mem": parts[2]})
+ return rows
+
+
+def run_load(duration, concurrency, warmup):
+ client = Client(BASE, timeout=8)
+ alice, _bob, _eve, chat = client.bootstrap()
+ if warmup > 0:
+ deadline = time.monotonic() + warmup
+ index = 0
+ while time.monotonic() < deadline:
+ client.message(alice, chat, "warmup-%s" % index)
+ index += 1
+ barrier = threading.Barrier(concurrency)
+
+ def worker(worker_id):
+ local = Client(BASE, timeout=5)
+ barrier.wait()
+ end = time.monotonic() + duration
+ latencies, errors = [], 0
+ index = 0
+ while time.monotonic() < end:
+ started = time.monotonic()
+ try:
+ local.message(alice, chat, "track1-%s-%s" % (worker_id, index))
+ latencies.append(time.monotonic() - started)
+ except Failure:
+ errors += 1
+ index += 1
+ return latencies, errors
+
+ started = time.monotonic()
+ with ThreadPoolExecutor(max_workers=concurrency) as pool:
+ results = list(pool.map(worker, range(concurrency)))
+ elapsed = time.monotonic() - started
+ latencies = sorted(item for values, _ in results for item in values)
+ errors = sum(n for _, n in results)
+ total = len(latencies) + errors
+
+ def percentile(p):
+ if not latencies:
+ return None
+ return round(1000 * latencies[max(0, math.ceil(p * len(latencies)) - 1)], 3)
+
+ return {
+ "elapsed_seconds": round(elapsed, 3),
+ "concurrency": concurrency,
+ "successful_requests": len(latencies),
+ "failed_requests": errors,
+ "error_ratio": round(errors / total, 6) if total else None,
+ "successful_rps": round(len(latencies) / elapsed, 3) if elapsed else None,
+ "successful_latency_ms": {"p50": percentile(0.50), "p95": percentile(0.95), "p99": percentile(0.99)},
+ "docker_stats": docker_stats(),
+ }
+
+
+def measure(label, replicas, cpus_each, memory_mb_each):
+ scale_api(replicas)
+ apply_limits(cpus_each, memory_mb_each)
+ wait_ready()
+ time.sleep(2)
+ result = run_load(DURATION, CONCURRENCY, WARMUP)
+ result.update(
+ {
+ "label": label,
+ "replicas": replicas,
+ "cpus_each": cpus_each,
+ "memory_mb_each": memory_mb_each,
+ "total_cpu": round(replicas * cpus_each, 3),
+ "total_memory_mb": replicas * memory_mb_each,
+ }
+ )
+ print(json.dumps({k: result[k] for k in ("label", "replicas", "total_cpu", "successful_rps", "error_ratio")}, ensure_ascii=False))
+ return result
+
+
+def main():
+ wait_ready()
+ fixed_budget = [
+ measure("fixed-1", 1, 1.00, 512),
+ measure("fixed-2", 2, 0.50, 256),
+ measure("fixed-4", 4, 0.25, 128),
+ ]
+ growing = [
+ measure("grow-2x0.25", 2, 0.25, 128),
+ measure("grow-2x0.50", 2, 0.50, 256),
+ measure("grow-2x1.00", 2, 1.00, 512),
+ ]
+ scale_api(2)
+ apply_limits(0.50, 256)
+ report = {
+ "date": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+ "hypothesis": "При фиксированном суммарном CPU/RAM добавление реплик перестаёт помогать, когда узким местом становится PostgreSQL/HAProxy, а не CPU процесса API.",
+ "profile": {
+ "duration_seconds": DURATION,
+ "concurrency": CONCURRENCY,
+ "warmup_seconds": WARMUP,
+ "workload": "closed-loop POST /messages through HAProxy",
+ },
+ "fixed_total_budget": fixed_budget,
+ "growing_resources": growing,
+ }
+ EVIDENCE.mkdir(exist_ok=True)
+ (EVIDENCE / "track1.json").write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ check(all(item["successful_requests"] > 0 for item in fixed_budget + growing), "a track1 series had no successes")
+ print("PASS: track1 series written to evidence/track1.json")
+
+
+if __name__ == "__main__":
+ run(main)