ЛР3 - БВТ2301 - Журавский - на 4 #39

Closed
ejur22 wants to merge 3 commits from ejur22/mtusi2026lab3:solution/БВТ2301-Журавский into main
60 changed files with 2941 additions and 21 deletions
+34 -2
View File
@@ -1,10 +1,19 @@
# Keep the image minimal: only src/, migrations/ and requirements.txt are copied.
.git
.github
.gitignore
.dockerignore
Dockerfile
Dockerfile.example
compose*.yaml
compose*.yml
stack*.yaml
# Secrets / local state (never bake these in).
.env
.env.*
!.env.example
secrets
certs
secrets.example
volumes
data
backups
@@ -13,8 +22,31 @@ backups
*.p12
*.pfx
*.jks
# Local tooling and caches.
.venv
venv
__pycache__
*.py[cod]
node_modules
.pytest_cache
.mypy_cache
.ruff_cache
*.log
# Tests, evidence and docs are not needed to run the API.
tests
student-tests
evidence
examples
contracts
scripts
infra
*.md
lab.json
Makefile
# Editor / OS noise.
.idea
.vscode
.DS_Store
+17 -2
View File
@@ -1,5 +1,6 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
# These are logical interface names; the mapping to the implementation is in
# REPORT.md. File paths contain no secret values.
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
@@ -7,7 +8,21 @@ 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=valkey
CACHE_URL_FILE=/run/secrets/cache_url
# lab3: horizontal scaling and shared idempotency.
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
PUBLISH_PORT=8080
# lab3: bounded-staleness session cache and durable invalidation drainer.
SESSION_CACHE_TTL_SECONDS=60
CACHE_INVALIDATION_INTERVAL_SECONDS=0.5
# Bounded DB pool and statement timeout (grade 4).
DB_POOL_MIN=1
DB_POOL_MAX=10
DB_POOL_TIMEOUT=5
DB_STATEMENT_TIMEOUT_MS=5000
LOG_LEVEL=INFO
+2
View File
@@ -0,0 +1,2 @@
# Keep shell hooks LF so they stay executable on Linux/CI.
*.sh text eol=lf
+3
View File
@@ -2,6 +2,9 @@
.env
.env.*
!.env.example
# Personal defence notes; not part of the submitted solution.
EXPLAIN.md
explain.md
secrets/
certs/private/
*.key
+29
View File
@@ -0,0 +1,29 @@
# syntax=docker/dockerfile:1
# Lab3 messenger image. Python is interpreted, so one pinned stage is enough.
# Migrations run from a separate one-shot compose service using the same image.
FROM python:3.11.9-slim-bookworm
ENV PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1 \
APP_HOST=0.0.0.0 \
APP_PORT=8080
WORKDIR /app
COPY requirements.txt ./
RUN python -m pip install --no-cache-dir -r requirements.txt
COPY src ./src
COPY migrations ./migrations
RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin appuser
USER appuser
EXPOSE 8080
HEALTHCHECK --interval=5s --timeout=3s --start-period=20s --retries=5 \
CMD ["python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).status == 200 else 1)"]
CMD ["python", "-m", "src.main"]
+5 -2
View File
@@ -4,10 +4,10 @@ CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence test-failover
.PHONY: help check validate test load test-persistence test-failover test-student
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; test-student: own pytest (grade 4); load: synthetic writes"
check:
$(PYTHON) scripts/check_contract.py
@@ -28,3 +28,6 @@ test-persistence:
test-failover:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2)
$(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
test-student:
$(PYTHON) -m pytest student-tests -q
+112 -15
View File
@@ -1,37 +1,134 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Журавский, БВТ2301
- Целевая оценка; выбранный трек 5, если нужен: **4** (уровень 3 + уровень 4); трек 5 не заявлен
- Commit/PR: TODO после публикации (ветка `solution/БВТ2301-Журавский`)
- Использованные источники, библиотеки и помощь ИИ: FastAPI 0.115.6, Pydantic 2.10.6, Uvicorn 0.34.0, psycopg 3.2.3 + psycopg-pool 3.2.4, argon2-cffi 23.1.0, redis-py 5.2.1 (клиент Valkey), nginx 1.27.4, PostgreSQL 16.6, Valkey 8.0.2, Docker Compose v2.27.1. Документация nginx (`upstream`, `resolve`, `proxy_next_upstream`), PostgreSQL (`pg_advisory_xact_lock`, `EXPLAIN`), RFC 7617. Помощь ИИ: генерация каркаса и текста отчёта, проверено запуском тестов.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
**Версии и prerequisites**
| Компонент | Версия / образ |
| --- | --- |
| Runtime | Python 3.11.9 |
| API-образ | `python:3.11.9-slim-bookworm`, свой `Dockerfile`, тег `messenger-api:lab3` |
| Балансировщик | `nginx:1.27.4-alpine` (встроенный Docker DNS `resolve`) |
| PostgreSQL | `postgres:16.6-bookworm` |
| Valkey | `valkey/valkey:8.0.2-alpine` |
| Docker / Compose | 26.1.4 / v2.27.1 |
| Python-зависимости | `requirements.txt` (пины: fastapi, pydantic, uvicorn, psycopg[binary], psycopg-pool, argon2-cffi, redis) |
| Стенд | Windows 10 Pro 10.0.19045, Ryzen 5 3600 (6C/12T), 15.9 GiB RAM; публичные хуки `restart.sh`/`stop-one.sh` выполняются в WSL Ubuntu (Python 3.12) |
Prerequisites: Docker с Linux-контейнерами и плагином Compose. Публичный smoke и `make check` работают везде; на «родном» Windows для `make check` нужен `PYTHONUTF8=1` (иначе Python читает UTF-8 JSON в кодировке cp1251). Хуки persistence/failover — POSIX-скрипты, их нужно запускать в WSL/Git Bash либо Linux-раннере.
**Создание локальных secrets (не коммитятся)**
```sh
sh scripts/gen-secrets.sh
# создаёт ./secrets/database_password, ./secrets/database_url, ./secrets/cache_url
```
**Запуск, миграции, проверка, остановка**
```sh
docker compose --env-file .env config --quiet # 1. валидация конфигурации
docker compose --env-file .env up -d --build # 2. сборка и запуск lb + api x2 + postgres + valkey
docker compose ps # 3. все healthy, api портов наружу не публикует
# Миграции выполняет одноразовый сервис `migrate` до старта реплик (advisory-lock, идемпотентно):
docker compose exec -T api python -m src.migrate # -> "migrations up to date"
python tests/smoke.py --base-url http://localhost:8080 # 4. публичный smoke
.venv\Scripts\python -m pytest student-tests -v # свои тесты (36 passed)
make test-persistence ACTION_SCRIPT=scripts/restart.sh # выполнять в WSL/Linux
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # одна реплика остаётся остановленной
sh scripts/restore-api.sh # вернуть остановленную реплику
sh scripts/rolling-update.sh # поочерёдная замена под нагрузкой
python scripts/check-revocation.py # отзыв сессии при недоступном Valkey
# Безопасная остановка (данные сохраняются):
docker compose stop
# Намеренное удаление учебных данных (тома):
docker compose down -v
```
Оператору нужно: сгенерировать secrets, выполнить шаги 1–4. Обычная остановка/`down` (без `-v`) сохраняет данные PostgreSQL и Valkey; `down -v` удаляет их.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
**Схема:** `клиент → nginx (LB, единственный публичный порт 127.0.0.1:8080) → api × 2 (FastAPI/Uvicorn) → PostgreSQL (источник истины) + Valkey (кэш сессий)`.
- **Единая точка входа.** Публикуется только `lb` (`127.0.0.1:8080`). Реплики `api` используют `expose: 8080` без `ports`, поэтому обойти балансировщик нельзя. Балансировка — nginx round-robin.
- **Динамический backend-list.** `upstream api_backend { zone …; server api:8080 resolve max_fails=1 fail_timeout=5s; }` + `resolver 127.0.0.11 valid=5s`. nginx перечитывает A-записи Docker DNS: добавление/остановка реплики подхватывается без reload; `proxy_next_upstream error timeout http_502/503/504` повторяет запрос на живой реплике. Максимальное время обнаружения отказа: пассивный `fail_timeout` 5 s + `valid` 5 s, замеренная первая успешная запись после старта хука — **< 1 с**.
- **X-Instance-Id.** `src/instance.py`: `INSTANCE_ID = $INSTANCE_ID` или hostname контейнера (= короткий container id). Ставится middleware на **каждый** ответ, включая ошибки и health; стабилен на время жизни процесса. Проверка в `evidence/lab3-instances.txt`: 12 запросов дают ровно два чередующихся id.
- **Общая идемпотентность.** Таблица `idempotency_keys` (PK `user_id, scope, key`, `scope = "POST /api/v1/chats/{id}/messages"`), `request_hash`, `status_code`, `response_body jsonb`, `expires_at`. `POST …/messages` требует `Idempotency-Key` `[A-Za-z0-9._:-]{1,128}` (нет/неверный — 400). Вставка сообщения и запись журнала — одна транзакция; `pg_advisory_xact_lock(hashtext(user|scope), hashtext(key))` сериализует одинаковые ключи между всеми репликами. Повтор возвращает тот же `201` и тот же Message; другой body — `409`. TTL — `IDEMPOTENCY_TTL_SECONDS` (default 86400).
- **Сессии общие, отзыв корректен при сбое кэша.** Источник истины — PostgreSQL (`sessions`): валидность и отзыв определяет строка с `expires_at > now()`. Valkey — **кэш сессий** `session:{sha256(token)} -> {user_id, expires_at}` с TTL `min(remaining, SESSION_CACHE_TTL_SECONDS)` (по умолчанию 60 c) — это верхняя граница устаревания. Logout в одной транзакции удаляет строку сессии и кладёт токен в `cache_invalidations`; фоновый дренажёр (`src/invalidation.py`, период 0.5 c) удаляет ключ Valkey и строку очереди. Поэтому logout, выполненный при лежащем Valkey, применяется сразу после восстановления кэша, а не «воскресает» до истечения TTL. При недоступности Valkey запросы обходят кэш и идут в PostgreSQL. Sticky-сессии не используются.
- **Одноразовые миграции.** Отдельный сервис `migrate` (`python -m src.migrate`) под `pg_advisory_xact_lock`; реплики стартуют только после `service_completed_successfully`, гонки за схему нет.
- **Graceful shutdown.** `src/main.py` переопределяет `Server.handle_exit`: по SIGTERM/SIGINT выставляет флаг (`src/state.py`), `/health/ready` отвечает `503` (LB выводит реплику из ротации), затем Uvicorn доигрывает запросы (`timeout_graceful_shutdown=10`).
- **Ресурсы и секреты.** У всех сервисов заданы CPU/RAM-лимиты (`deploy.resources.limits`); секреты — файловые compose secrets/`*_FILE`, в образ и Git не попадают. `container_name` не задаётся, масштабирование одной Compose-service работает.
- **Надёжность БД.** Ограниченный пул (`DB_POOL_MAX`), `DB_POOL_TIMEOUT`, `statement_timeout`; все SQL параметризованы; индекс `messages(chat_id, created_at, id)` под keyset-пагинацию.
**Соответствие `.env.example`**
| Переменная | Роль в решении |
| --- | --- |
| `APP_HOST`, `APP_PORT` | адрес/порт Uvicorn; в compose `0.0.0.0:8080` |
| `APP_ENV`, `LOG_LEVEL` | метки логирования запуска |
| `SESSION_TTL_SECONDS` | срок жизни сессии (`sessions.expires_at`) и TTL кэша |
| `SESSION_STORE` | `valkey`/`redis` — включить кэш; `postgres` — без кэша |
| `SESSION_CACHE_TTL_SECONDS` | верхняя граница жизни записи кэша сессий (граница устаревания) |
| `CACHE_INVALIDATION_INTERVAL_SECONDS` | период фонового дренажёра очереди инвалидаций |
| `IDEMPOTENCY_TTL_SECONDS` | срок хранения журнала идемпотентности (24 ч) |
| `DATABASE_URL_FILE`, `CACHE_URL_FILE` | файлы с DSN PostgreSQL и URL Valkey (compose secrets) |
| `API_REPLICAS` | число реплик `api` (`deploy.replicas`) |
| `PUBLISH_PORT` | публикуемый порт LB (по умолчанию 8080) |
| `DB_POOL_*`, `DB_STATEMENT_TIMEOUT_MS` | ограничения пула и таймауты |
## Доказательства критериев
| Критерий 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://localhost:8080` | `PASS: lab3 public API scenario` | `evidence/lab3-smoke.txt` |
| Стенд: ≥2 реплики, LB, общая БД/сессии | `docker compose up -d --build`, `docker compose ps` | 2× `api` healthy, `lb` 127.0.0.1:8080, `postgres`, `valkey`; у `api` порты не публикуются | `evidence/lab3-compose-ps.txt` |
| Разные запросы одной сессии обслуживают разные реплики | 12× `GET /users/me` через LB | чередование двух разных `X-Instance-Id` (2 реплики), один токен | `evidence/lab3-instances.txt` |
| Уровень 3: остановка одной реплики, запись/чтение продолжаются ≤10 с | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 138 успешных записей, 0 ошибок, восстановление **0.67 с**; `api-8 Exited` при живом `api-7` | `evidence/lab3-failover.txt` |
| Общая идемпотентность, в т.ч. конкурентная и через разные реплики | `test_idempotency.py` | повтор = тот же Message; другой body → 409; 8 параллельных запросов с одним ключом → ровно одно сообщение | `evidence/lab3-student-tests.txt` |
| Отзыв сессии не обходится при сбое Valkey | `python scripts/check-revocation.py` (pause Valkey → logout 204 → unpause → 6 c) | старый токен даёт `401` через 2 реплики и не может отправить сообщение | `evidence/lab3-revocation-fix.txt` |
| Кэш сессий реален, очередь инвалидаций дренируется | warm-up → pause/logout/unpause → `valkey-cli --scan 'session:*'` + `cache_invalidations` | ключ `session:*` с TTL `60` → после восстановления 0 ключей и 0 строк очереди; старый токен `401` | `evidence/lab3-cache-invalidation.txt` |
| Деградация кэша без остановки API | pause Valkey, валидный `/users/me` | 5×`200`, `/health/ready` = `200` (кэш обойдён) | `evidence/lab3-valkey-degradation.txt` |
| Persistence: данные и сессия переживают рестарт API и хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session` | `evidence/lab3-persistence.txt` |
| Миграции применяются однократно и повторно идемпотентно | `docker compose exec -T api python -m src.migrate` | `migrations up to date`; в `schema_migrations` 3 строки | `evidence/lab3-migrations.txt` |
| Уровень 4: health/readiness, SIGTERM, LB исключает backend | `scripts/stop-one.sh` + `/health/ready` | остановленная реплика исчезает из ответов; readiness→503 при SIGTERM; пассивные проверки nginx | `evidence/lab3-failover.txt` |
| Уровень 4: CPU/RAM-лимиты, порты API только через LB | `docker compose config`, `docker stats` | лимиты 0.75 CPU / 256M у api; `8080/tcp` без проброса | `evidence/lab3-stats.txt`, `evidence/lab3-compose-ps.txt` |
| Уровень 4: rolling update под нагрузкой | `scripts/rolling-update.sh` при непрерывном опросе LB | 400/400 запросов `200`, реплики заменены по одной | `evidence/lab3-rolling.txt` |
| Уровень 4: индекс под keyset-пагинацию (≥10 000 сообщений) | `EXPLAIN (ANALYZE, BUFFERS)` | `Bitmap Index Scan on messages_chat_created_id_idx`, 0.907 мс | `evidence/lab3-explain.txt` |
| Уровень 4: нагрузочные метрики | `tests/load.py` | 113.6 RPS, 0 ошибок, p50/p95/p99 = 47/172/281 мс | `evidence/lab3-load.txt` |
| Секреты вне Git | `.gitignore`, `secrets.example/`, `gen-secrets.sh` | `git status` без `.env`/`secrets/` | описание в PR |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Гипотеза: LB с динамическим backend-list маскирует отказ одной реплики, общая идемпотентность в PostgreSQL не даёт дублей при переключении реплик, а общий статус позволяет любой реплике обслуживать сессию. Методика: реальный compose-стенд, синтетические данные, хуки в WSL.
**Нагрузочный профиль:** closed-loop POST сообщений, 8 параллельных клиентов, 20 с, прогрева нет; конфигурация — один Docker-host (WSL2), api 0.75 CPU/256 MB ×2, postgres 1 CPU/512 MB.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Остановка одной API-реплики (`stop-one.sh`, TARGET = обслужившая реплика) | записи/чтения продолжаются, без дублей, токен жив | 138 записей за 15 с, 0 ошибок, цель не в последних ответах; `api-8 Exited` | **0.67 с**; потерь нет |
| То же для второй реплики (после восстановления первой) | то же | ≈120–140 записей, 0 ошибок | **≈1 с**; потерь нет |
| `docker compose restart api lb postgres valkey` | данные и сессия сохранены | `PASS: persistence preserved……` | рестарт ≈ секунды; потерь нет |
| Rolling update (`rolling-update.sh`) под непрерывным опросом | замена реплик без недоступности | 400/400 `200` при поочерёдной замене | простоя нет |
| Valkey недоступен во время logout (`check-revocation.py`) | отзыв сессии не обходится, старый токен → 401 | pause → logout 204 → unpause → ключ кэша удалён дренажёром ≤1.5 c, очередь `cache_invalidations`=0; через 6 c 401 через обе реплики, POST отклонён | потерь нет; сессия отозвана в PostgreSQL |
| Нагрузка ~114 RPS на 2 реплики | стабильная пропускная способность | 0 ошибок, p99 281 мс | n/a |
Ограничения измерения: closed-loop генератор страдает coordinated omission и ограничен клиентом; числа — throughput HTTP-подтверждений, не точный счётчик COMMIT; единичный Docker-host не проверяет отказ узла. `docker stats` показывает ~150 MB RSS на реплику при лимите 256 MB.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Выдерживается: отказ **процесса** одной API-реплики, рестарт API и хранилищ с volumes, потеря Valkey (кэш), конкурентные повторы с общим ключом, rolling-замена реплик под нагрузкой, некорректный ввод.
- **Не** выдерживается и не заявлено: отказ Docker-host, отказ единственного PostgreSQL и единственного LB, отказ узла БД. Multi-node/HA БД — это трек 5, он не выбран.
- Учебные упрощения: HTTP без TLS (локальный стенд lab1–6); `scripts/rolling-update.sh` — поочерёдная замена через `docker`+`compose`, эквивалент rolling update оркестратора, а не сам оркестратор; нет rate limiting.
- Граница устаревания сессионного кэша — `SESSION_CACHE_TTL_SECONDS` (60 c). При полностью недоступном Valkey отзыв применяется не мгновенно, а когда дренажёр сможет удалить ключ после восстановления кэша (замерено ≤1.5 c); TTL — страховка на случай, если дренажёр не успеет. Это осознанный компромисс: logout должен возвращать 204 и при недоступном кэше, поэтому «нулевая» задержка инвалидации в этот момент невозможна без отказа от кэша.
- Подтверждено измерениями: смена обслуживающей реплики при отказе, конкуренто-безопасная идемпотентность, сохранность после рестарта, использование индекса (EXPLAIN), отсутствие публикации портов API.
- Возможное улучшение (гипотеза): при большем числе реплик и `proxy_next_upstream_tries` можно снизить долю ошибок при «жёстком» (без ожидания healthy) rolling-обновлении; в этой работе замена ожидает healthy, поэтому ошибок нет.
+139
View File
@@ -0,0 +1,139 @@
# Lab3 topology: one public entrypoint (nginx LB) -> 2+ interchangeable API
# replicas -> shared PostgreSQL (source of truth) and Valkey (session cache).
# Versions are pinned; no API replica publishes a port, so the only reachable
# path is through the balancer. Secrets are file-based and live in ./secrets
# (gitignored). Migrations run once in the dedicated `migrate` service.
name: messenger-lab3
x-api-env: &api-env
APP_HOST: "0.0.0.0"
APP_PORT: "8080"
APP_ENV: ${APP_ENV:-lab}
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
SESSION_STORE: ${SESSION_STORE:-valkey}
SESSION_CACHE_TTL_SECONDS: ${SESSION_CACHE_TTL_SECONDS:-60}
CACHE_INVALIDATION_INTERVAL_SECONDS: ${CACHE_INVALIDATION_INTERVAL_SECONDS:-0.5}
IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400}
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
DB_POOL_MIN: ${DB_POOL_MIN:-1}
DB_POOL_MAX: ${DB_POOL_MAX:-10}
DB_POOL_TIMEOUT: ${DB_POOL_TIMEOUT:-5}
DB_STATEMENT_TIMEOUT_MS: ${DB_STATEMENT_TIMEOUT_MS:-5000}
LOG_LEVEL: ${LOG_LEVEL:-INFO}
services:
lb:
image: nginx:1.27.4-alpine
volumes:
- ./infra/nginx.conf:/etc/nginx/nginx.conf:ro
ports:
- "127.0.0.1:${PUBLISH_PORT:-8080}:8080"
depends_on:
- api
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/health/live >/dev/null 2>&1 || exit 1"]
interval: 10s
timeout: 3s
retries: 5
start_period: 10s
deploy:
resources:
limits:
cpus: "0.50"
memory: 128M
api:
build:
context: .
image: messenger-api:lab3
environment: *api-env
secrets:
- database_url
- cache_url
expose:
- "8080"
depends_on:
migrate:
condition: service_completed_successfully
valkey:
condition: service_healthy
restart: unless-stopped
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).status == 200 else 1)"]
interval: 5s
timeout: 3s
retries: 5
start_period: 20s
deploy:
replicas: ${API_REPLICAS:-2}
resources:
limits:
cpus: "0.75"
memory: 256M
# One-shot schema migration; runs once before replicas start.
migrate:
build:
context: .
image: messenger-api:lab3
command: ["python", "-m", "src.migrate"]
environment: *api-env
secrets:
- database_url
depends_on:
postgres:
condition: service_healthy
restart: "no"
postgres:
image: postgres:16.6-bookworm
environment:
POSTGRES_USER: messenger
POSTGRES_DB: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/database_password
secrets:
- database_password
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
interval: 5s
timeout: 3s
retries: 12
restart: unless-stopped
deploy:
resources:
limits:
cpus: "1.00"
memory: 512M
valkey:
image: valkey/valkey:8.0.2-alpine
command: ["valkey-server", "--appendonly", "yes"]
volumes:
- valkeydata:/data
healthcheck:
test: ["CMD", "valkey-cli", "ping"]
interval: 5s
timeout: 3s
retries: 12
restart: unless-stopped
deploy:
resources:
limits:
cpus: "0.50"
memory: 128M
volumes:
pgdata:
valkeydata:
secrets:
database_url:
file: ./secrets/database_url
database_password:
file: ./secrets/database_password
cache_url:
file: ./secrets/cache_url
+6
View File
@@ -0,0 +1,6 @@
session keys in Valkey after warm-up: 1
sample TTLs (capped at SESSION_CACHE_TTL_SECONDS): {'session:b978298ff28b3a14738e...': '60'}
pausing Valkey, logout, resuming ...
session keys after resume + 1.5s (drainer): 0
pending invalidation rows after drain: 0
old token status: 401
+6
View File
@@ -0,0 +1,6 @@
NAME SERVICE STATUS PORTS
messenger-lab3-api-7 api Up 4 minutes (healthy) 8080/tcp
messenger-lab3-api-8 api Up 4 minutes (healthy) 8080/tcp
messenger-lab3-lb-1 lb Up 7 minutes (healthy) 80/tcp, 127.0.0.1:8080->8080/tcp
messenger-lab3-postgres-1 postgres Up 7 minutes (healthy) 5432/tcp
messenger-lab3-valkey-1 valkey Up 7 minutes (healthy) 6379/tcp
+24
View File
@@ -0,0 +1,24 @@
{"hot_chat_id": "a10c30fb-faf7-4cae-ae8c-15ebde54d7e9", "messages": 10000, "chats": ["a10c30fb-faf7-4cae-ae8c-15ebde54d7e9", "64cb41c4-95b7-4327-a8f7-c9cfda051057", "995f3cbc-f0cf-42bc-acea-bbbb27389434"]}
hot_chat_id=a10c30fb-faf7-4cae-ae8c-15ebde54d7e9
=== EXPLAIN keyset query ===
QUERY PLAN
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Limit (cost=18.69..18.70 rows=4 width=106) (actual time=0.870..0.875 rows=50 loops=1)
Buffers: shared hit=87
-> Sort (cost=18.69..18.70 rows=4 width=106) (actual time=0.869..0.871 rows=50 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 36kB
Buffers: shared hit=87
-> Bitmap Heap Scan on messages (cost=4.32..18.65 rows=4 width=106) (actual time=0.223..0.520 rows=3333 loops=1)
Recheck Cond: ((chat_id = 'a10c30fb-faf7-4cae-ae8c-15ebde54d7e9'::uuid) AND (ROW(created_at, id) > ROW('2020-01-01 00:00:00+00'::timestamp with time zone, '00000000-0000-0000-0000-000000000000'::uuid)))
Heap Blocks: exact=48
Buffers: shared hit=81
-> Bitmap Index Scan on messages_chat_created_id_idx (cost=0.00..4.32 rows=4 width=0) (actual time=0.209..0.209 rows=3333 loops=1)
Index Cond: ((chat_id = 'a10c30fb-faf7-4cae-ae8c-15ebde54d7e9'::uuid) AND (ROW(created_at, id) > ROW('2020-01-01 00:00:00+00'::timestamp with time zone, '00000000-0000-0000-0000-000000000000'::uuid)))
Buffers: shared hit=33
Planning:
Buffers: shared hit=136
Planning Time: 0.313 ms
Execution Time: 0.907 ms
(17 rows)
+11
View File
@@ -0,0 +1,11 @@
=== make test-failover (scripts/stop-one.sh) ===
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 138, "failed_attempts": 0, "first_recovery_seconds": 0.67}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
=== docker compose ps -a right after the hook ===
messenger-lab3-api-7 api Up 26 seconds (healthy)
messenger-lab3-api-8 api Exited (0) 14 seconds ago
messenger-lab3-lb-1 lb Up 11 minutes (healthy)
messenger-lab3-migrate-1 migrate Exited (0) 27 seconds ago
messenger-lab3-postgres-1 postgres Up 11 minutes (healthy)
messenger-lab3-valkey-1 valkey Up 11 minutes (healthy)
+3
View File
@@ -0,0 +1,3 @@
X-Instance-Id sequence over 12 requests through the LB:
['2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901']
distinct: ['2f2d19f8e0e6', 'a17e74060901']
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 20.0,
"elapsed_seconds": 20.39,
"concurrency": 8,
"successful_requests": 2317,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 113.634,
"successful_latency_ms": {
"p50": 47.0,
"p95": 172.0,
"p99": 281.0
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 20.0,
"elapsed_seconds": 20.39,
"concurrency": 8,
"successful_requests": 2317,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 113.634,
"successful_latency_ms": {
"p50": 47.0,
"p95": 172.0,
"p99": 281.0
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+16
View File
@@ -0,0 +1,16 @@
=== docker compose exec -T api python -m src.migrate ===
docker : INFO:messenger.migrate:migrations up to date
строка:1 знак:244
+ ... ations.txt; docker compose exec -T api python -m src.migrate 2>&1 | T ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (INFO:messenger....ions up to date:String) [], RemoteException
+ FullyQualifiedErrorId : NativeCommandError
=== schema_migrations rows ===
version
-----------------------------
001_init.sql
002_idempotency.sql
003_cache_invalidations.sql
(3 rows)
+9
View File
@@ -0,0 +1,9 @@
=== make test-persistence (scripts/restart.sh) ===
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
=== docker compose ps after restart ===
messenger-lab3-api-7 Up 6 seconds (healthy)
messenger-lab3-api-8 Up 6 seconds (healthy)
messenger-lab3-lb-1 Up 6 seconds (health: starting)
messenger-lab3-postgres-1 Up 6 seconds (healthy)
messenger-lab3-valkey-1 Up 6 seconds (healthy)
+4
View File
@@ -0,0 +1,4 @@
Pausing Valkey (messenger-lab3-valkey-1) ...
Logout returned 204 while the cache was unavailable.
Valkey resumed; waiting 6.0s for the cache circuit breaker ...
PASS: revoked session stays 401 through 2 replica(s) and cannot post after a failed cache invalidation.
+10
View File
@@ -0,0 +1,10 @@
Running rolling update under continuous /health/live polling...
Replacing replica 47b92cbda9c814bed107a112fff202e9716d1735192a46861f070cc08c10b6e5 ...
Replacing replica 6077ba4198446b006bfc4a420d2875958a2b640163f1ed0669d9c3a6c0da5c2f ...
Rolling update complete; all replicas healthy.
HTTP status distribution observed by the client during the rolling update:
400 200
Total requests: 400
+1
View File
@@ -0,0 +1 @@
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
+6
View File
@@ -0,0 +1,6 @@
NAME CPU % MEM USAGE / LIMIT
messenger-lab3-api-8 0.24% 152.6MiB / 256MiB
messenger-lab3-api-7 0.21% 146.5MiB / 256MiB
messenger-lab3-lb-1 0.00% 14.97MiB / 128MiB
messenger-lab3-postgres-1 0.16% 68.95MiB / 512MiB
messenger-lab3-valkey-1 0.26% 8.43MiB / 128MiB
+2
View File
@@ -0,0 +1,2 @@
..................................... [100%]
37 passed in 9.10s
+6
View File
@@ -0,0 +1,6 @@
messenger-lab3-valkey-1
messenger-lab3-valkey-1
Pausing Valkey; valid traffic must keep working (cache bypassed).
statuses during pause: [200, 200, 200, 200, 200]
ready: 200
PASS: valid traffic served from PostgreSQL with Valkey unavailable.
+59
View File
@@ -0,0 +1,59 @@
# Lab3 edge load balancer.
#
# Docker's embedded DNS (127.0.0.11) returns one A record per running `api`
# replica. `resolve` + a shared `zone` make nginx re-resolve that name every
# `valid` seconds, so replicas that appear/disappear are picked up without a
# reload. Passive checks (max_fails/fail_timeout) eject a replica that refuses
# connections; proxy_next_upstream retries the same request on a healthy peer.
worker_processes auto;
events {
worker_connections 2048;
}
http {
resolver 127.0.0.11 valid=5s ipv6=off;
resolver_timeout 2s;
access_log /dev/stdout;
error_log /dev/stderr warn;
sendfile on;
tcp_nopush on;
keepalive_timeout 30;
upstream api_backend {
zone api_backend 64k;
server api:8080 resolve max_fails=1 fail_timeout=5s;
}
server {
listen 8080;
server_name _;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection "";
proxy_connect_timeout 2s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;
# Retry a request on another replica if a backend is down mid-flight.
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
proxy_next_upstream_timeout 5s;
location /health/live {
access_log off;
proxy_pass http://api_backend;
}
location / {
proxy_pass http://api_backend;
}
}
}
+42
View File
@@ -0,0 +1,42 @@
-- Lab2 initial schema. Idempotent and safe to re-run via the migration runner.
create table if not exists users (
id uuid primary key,
username text not null unique,
display_name text not null,
password_hash text not null,
created_at timestamptz not null
);
create table if not exists chats (
id uuid primary key,
title text not null,
created_at timestamptz not null
);
create table if not exists chat_members (
chat_id uuid not null references chats (id) on delete cascade,
user_id uuid not null references users (id) on delete cascade,
primary key (chat_id, user_id)
);
create table if not exists messages (
id uuid primary key,
chat_id uuid not null references chats (id) on delete cascade,
sender_id uuid not null references users (id),
text text not null,
created_at timestamptz not null
);
-- Composite index prepared for keyset pagination:
-- where chat_id = $1 and (created_at, id) > ($2, $3) order by created_at, id
create index if not exists messages_chat_created_id_idx
on messages (chat_id, created_at, id);
create table if not exists sessions (
token_hash text primary key,
user_id uuid not null references users (id) on delete cascade,
created_at timestamptz not null,
expires_at timestamptz not null
);
create index if not exists sessions_expires_at_idx on sessions (expires_at);
+19
View File
@@ -0,0 +1,19 @@
-- Lab3 shared idempotency ledger for POST message retries.
--
-- Scope is (user_id, HTTP method + chat path, key); the stored row carries the
-- canonical request hash and the exact 201 body so any replica can replay the
-- same Message. Rows expire after IDEMPOTENCY_TTL_SECONDS (default 24h).
create table if not exists idempotency_keys (
user_id uuid not null references users (id) on delete cascade,
scope text not null,
key text not null,
request_hash text not null,
status_code integer not null,
response_body jsonb not null,
created_at timestamptz not null default now(),
expires_at timestamptz not null,
primary key (user_id, scope, key)
);
create index if not exists idempotency_keys_expires_at_idx
on idempotency_keys (expires_at);
+15
View File
@@ -0,0 +1,15 @@
-- Lab3 durable cache invalidation queue.
--
-- Logout deletes the authoritative session row in PostgreSQL and enqueues the
-- token hash here in the SAME transaction. A lightweight background drainer in
-- each API replica removes the corresponding Valkey cache key and then the row.
-- If Valkey was unreachable at logout time, the row survives and the stale
-- cache entry is removed as soon as the cache comes back, instead of being
-- trusted until its TTL.
create table if not exists cache_invalidations (
token_hash text primary key,
created_at timestamptz not null default now()
);
create index if not exists cache_invalidations_created_at_idx
on cache_invalidations (created_at);
+8
View File
@@ -0,0 +1,8 @@
# Runtime dependencies for the lab3 messenger. Pinned for reproducibility.
fastapi==0.115.6
pydantic==2.10.6
uvicorn[standard]==0.34.0
psycopg[binary]==3.2.3
psycopg-pool==3.2.4
argon2-cffi==23.1.0
redis==5.2.1
+79
View File
@@ -0,0 +1,79 @@
#!/usr/bin/env python3
"""Regression check: logout must not be bypassed while Valkey is unavailable.
Scenario (the one that used to fail):
1. login and warm any session cache;
2. pause Valkey;
3. logout -> 204 (session row removed from PostgreSQL);
4. resume Valkey;
5. after the cache circuit breaker window, the old token must still be 401 on
every replica, and it must not be able to send a message.
Requires the docker CLI and a running lab3 stack.
"""
import argparse
import os
import subprocess
import sys
import time
import uuid
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "tests"))
from client import Client # noqa: E402
def _docker(*args: str) -> None:
subprocess.run(["docker", *args], check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--base-url", default=os.environ.get("BASE_URL", "http://localhost:8080"))
parser.add_argument("--valkey-container", default=os.environ.get("VALKEY_CONTAINER", "messenger-lab3-valkey-1"))
parser.add_argument("--wait", type=float, default=6.0, help="seconds to wait after resuming Valkey")
args = parser.parse_args()
c = Client(args.base_url)
alice, bob, eve, chat = c.bootstrap()
# Warm the cache on both replicas.
for _ in range(6):
c.call("GET", "/api/v1/users/me", actor=alice, schema="User")
c.message(alice, chat, "warm-up before revocation")
print("Pausing Valkey (%s) ..." % args.valkey_container)
_docker("pause", args.valkey_container)
try:
logout = c.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=alice)
assert logout["status"] == 204, logout["status"]
print("Logout returned 204 while the cache was unavailable.")
finally:
_docker("unpause", args.valkey_container)
print("Valkey resumed; waiting %.1fs for the cache circuit breaker ..." % args.wait)
time.sleep(args.wait)
seen = set()
for _ in range(12):
response = c.call("GET", "/api/v1/users/me", 401, actor=alice, schema="Error")
seen.add(response["headers"].get("X-Instance-Id"))
assert len(seen) >= 1, "no replica observed"
blocked = c.call(
"POST",
"/api/v1/chats/" + chat["id"] + "/messages",
401,
actor=alice,
body={"text": "must not be written"},
headers={"Idempotency-Key": uuid.uuid4().hex},
schema="Error",
)
assert blocked["status"] == 401, blocked["status"]
print(
"PASS: revoked session stays 401 through %d replica(s) and cannot post after a "
"failed cache invalidation." % len(seen)
)
if __name__ == "__main__":
main()
+11
View File
@@ -0,0 +1,11 @@
#!/bin/sh
set -eu
# Generate local (gitignored) compose secrets with a random database password.
cd "$(dirname "$0")/.."
mkdir -p secrets
PASSWORD=$(head -c 24 /dev/urandom | od -An -tx1 | tr -d ' \n')
printf '%s' "$PASSWORD" > secrets/database_password
printf '%s' "postgresql://messenger:${PASSWORD}@postgres:5432/messenger" > secrets/database_url
printf '%s' "redis://valkey:6379/0" > secrets/cache_url
chmod 600 secrets/database_password secrets/database_url secrets/cache_url 2>/dev/null || true
echo "Wrote ./secrets/database_password, ./secrets/database_url, ./secrets/cache_url (not committed)."
+8
View File
@@ -0,0 +1,8 @@
#!/bin/sh
set -eu
# Restart the API replicas, the balancer and ALL state stores used by this stack.
# Volumes are preserved; schema and data are never dropped or re-seeded.
# Used by: make test-persistence ACTION_SCRIPT=scripts/restart.sh
cd "$(dirname "$0")/.."
docker compose restart api lb postgres valkey
exit 0
+7
View File
@@ -0,0 +1,7 @@
#!/bin/sh
set -eu
# Restore the API service to the desired replica count after a failover test.
# Stopped replicas are started again; volumes and data are untouched.
cd "$(dirname "$0")/.."
docker compose up -d --no-recreate api
exit 0
+38
View File
@@ -0,0 +1,38 @@
#!/bin/sh
set -eu
# Sequential (rolling) replacement of the API replicas under load.
#
# The image is rebuilt once, then each running replica is stopped (the balancer
# drains it and keeps serving from the peers) and recreated from the new image.
# Before the next replica is touched we wait until every running replica is
# healthy, so the balancer always has somewhere to send traffic.
cd "$(dirname "$0")/.."
N="${API_REPLICAS:-2}"
wait_healthy() {
for _ in $(seq 1 90); do
total=$(docker compose ps -q api | wc -l)
healthy=$(docker ps --filter label=com.docker.compose.service=api --filter health=healthy --format '{{.ID}}' | wc -l)
if [ "$total" -ge "$N" ] && [ "$healthy" -ge "$total" ]; then
return 0
fi
sleep 1
done
}
echo "Building new API image..."
docker compose build api
# Wait for the current generation to be healthy before starting.
wait_healthy
for id in $(docker compose ps -q api); do
echo "Replacing replica $id ..."
docker stop -t 10 "$id" >/dev/null
docker rm "$id" >/dev/null
docker compose up -d --no-recreate api >/dev/null
wait_healthy
done
echo "Rolling update complete; all replicas healthy."
+26
View File
@@ -0,0 +1,26 @@
#!/bin/sh
set -eu
# Stop exactly ONE API replica and leave it stopped.
#
# TARGET_INSTANCE_ID is the X-Instance-Id observed by the test, which equals the
# replica's container hostname (Docker's short container id). We map it to the
# running api container and stop it with a short grace period so the hook
# returns well within the 10 second budget. PostgreSQL, Valkey and the balancer
# are never touched.
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
cd "$(dirname "$0")/.."
target=""
for id in $(docker ps --filter "label=com.docker.compose.service=api" --format '{{.ID}}'); do
case "$id" in
"$TARGET_INSTANCE_ID"*) target="$id" ;;
esac
done
if [ -z "$target" ]; then
echo "no running API replica matches X-Instance-Id=$TARGET_INSTANCE_ID" >&2
exit 1
fi
docker stop -t 5 "$target" >/dev/null
exit 0
+9
View File
@@ -0,0 +1,9 @@
# Example only. Copy the whole directory to ./secrets/ (gitignored) and put a
# real local password in. Never commit real credentials.
#
# mkdir -p secrets
# cp secrets.example/* secrets/
# # then edit ./secrets/database_password and ./secrets/database_url
#
# Or generate everything with random values:
# sh scripts/gen-secrets.sh
+1
View File
@@ -0,0 +1 @@
"""MTUSI Messenger lab3 application package."""
+384
View File
@@ -0,0 +1,384 @@
"""FastAPI application implementing the lab3 HTTP contract.
Canonical contract: ``contracts/openapi.json`` and ``contracts/README.md``.
PostgreSQL is the source of truth; Valkey is a best-effort session cache.
Every response carries a non-empty ``X-Request-Id`` and ``X-Instance-Id``.
Messages are idempotent per ``Idempotency-Key`` across all replicas.
"""
from __future__ import annotations
import base64
import binascii
import logging
import re
import uuid
from contextlib import asynccontextmanager
from typing import Dict, List, Optional
from fastapi import Depends, FastAPI, Query, Request, Response
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import BaseModel, ConfigDict, Field, field_validator
from psycopg import InterfaceError, OperationalError
from psycopg_pool import PoolTimeout
from starlette.exceptions import HTTPException as StarletteHTTPException
from . import invalidation
from . import repositories as repo
from . import security, sessions, state
from .config import settings
from .db import pool
from .errors import ApiError
from .instance import INSTANCE_ID
from .pagination import bound_cursor, encode_cursor
logger = logging.getLogger("messenger")
BEARER_CHALLENGE = 'Bearer realm="messenger"'
BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"'
_BEARER_RE = re.compile(r"^Bearer\s+(\S+)$", re.IGNORECASE)
_IDEMPOTENCY_RE = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
_STATUS_CODES = {
400: "invalid_request",
401: "unauthorized",
404: "not_found",
405: "invalid_request",
409: "conflict",
413: "payload_too_large",
415: "unsupported_media_type",
429: "rate_limited",
503: "unavailable",
}
@asynccontextmanager
async def lifespan(_: FastAPI):
invalidation.start_worker()
try:
yield
finally:
invalidation.stop_worker()
app = FastAPI(
title="MTUSI Messenger — лабораторная 3",
version="1.3.0",
docs_url=None,
redoc_url=None,
openapi_url=None,
lifespan=lifespan,
)
# --------------------------------------------------------------------------- #
# Error envelope
# --------------------------------------------------------------------------- #
def _request_id(request: Request) -> str:
return getattr(request.state, "request_id", None) or uuid.uuid4().hex
def error_response(
request: Request, status: int, code: str, message: str, challenge: Optional[str] = None
) -> JSONResponse:
rid = _request_id(request)
headers = {"X-Request-Id": rid, "X-Instance-Id": INSTANCE_ID}
if challenge:
headers["WWW-Authenticate"] = challenge
return JSONResponse(
status_code=status,
content={"error": {"code": code, "message": message, "request_id": rid}},
headers=headers,
)
@app.middleware("http")
async def request_context(request: Request, call_next):
rid = request.headers.get("X-Request-Id") or uuid.uuid4().hex
request.state.request_id = rid
try:
response = await call_next(request)
except Exception as exc: # noqa: BLE001 - never leak internals
logging.getLogger("messenger").error("unhandled error: %s", type(exc).__name__)
logging.getLogger("messenger").debug("traceback", exc_info=exc)
response = error_response(request, 500, "internal_error", "Внутренняя ошибка")
response.headers["X-Request-Id"] = rid
response.headers["X-Instance-Id"] = INSTANCE_ID
return response
@app.exception_handler(ApiError)
async def handle_api_error(request: Request, exc: ApiError) -> JSONResponse:
challenge = exc.challenge or (BEARER_CHALLENGE if exc.status == 401 else None)
return error_response(request, exc.status, exc.code, exc.message, challenge)
@app.exception_handler(RequestValidationError)
async def handle_validation(request: Request, exc: RequestValidationError) -> JSONResponse:
return error_response(request, 400, "invalid_request", "Некорректный запрос")
@app.exception_handler(StarletteHTTPException)
async def handle_http_error(request: Request, exc: StarletteHTTPException) -> JSONResponse:
code = _STATUS_CODES.get(exc.status_code, "invalid_request")
challenge = BEARER_CHALLENGE if exc.status_code == 401 else None
return error_response(request, exc.status_code, code, "Ошибка запроса", challenge)
def _handle_db_error(request: Request, exc: Exception) -> JSONResponse:
logger.warning("database unavailable: %s", type(exc).__name__)
return error_response(request, 503, "unavailable", "База данных недоступна")
app.add_exception_handler(OperationalError, _handle_db_error)
app.add_exception_handler(InterfaceError, _handle_db_error)
app.add_exception_handler(PoolTimeout, _handle_db_error)
# --------------------------------------------------------------------------- #
# Request schemas
# --------------------------------------------------------------------------- #
class CreateUser(BaseModel):
model_config = ConfigDict(extra="forbid")
username: str = Field(pattern=r"^[a-z0-9_]{3,32}$")
display_name: str = Field(min_length=1, max_length=100)
password: str = Field(min_length=12, max_length=128)
@field_validator("display_name")
@classmethod
def _not_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError("display_name must not be blank")
return value
class CreateChat(BaseModel):
model_config = ConfigDict(extra="forbid")
title: str = Field(min_length=1, max_length=100)
member_ids: List[uuid.UUID] = Field(min_length=1, max_length=100)
@field_validator("title")
@classmethod
def _not_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError("title must not be blank")
return value
class CreateMessage(BaseModel):
model_config = ConfigDict(extra="forbid")
text: str = Field(min_length=1, max_length=4000)
@field_validator("text")
@classmethod
def _not_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError("text must not be blank")
return value
# --------------------------------------------------------------------------- #
# Dependencies and helpers
# --------------------------------------------------------------------------- #
def get_conn():
with pool().connection() as conn:
yield conn
def _canonical_uuid(value: str) -> str:
try:
return str(uuid.UUID(value))
except (ValueError, AttributeError, TypeError):
raise ApiError(400, "invalid_request", "Некорректный идентификатор")
def _parse_basic(request: Request) -> tuple[str, str]:
header = request.headers.get("Authorization", "").strip()
if not header.lower().startswith("basic "):
raise ApiError(401, "unauthorized", "Требуется Basic-аутентификация", challenge=BASIC_CHALLENGE)
encoded = header[6:].strip()
try:
decoded = base64.b64decode(encoded, validate=True).decode("utf-8")
except (binascii.Error, ValueError, UnicodeDecodeError):
raise ApiError(401, "unauthorized", "Неверные учётные данные", challenge=BASIC_CHALLENGE)
if ":" not in decoded:
raise ApiError(401, "unauthorized", "Неверные учётные данные", challenge=BASIC_CHALLENGE)
username, password = decoded.split(":", 1)
return username, password
def _bearer_token(request: Request) -> str:
header = request.headers.get("Authorization", "").strip()
match = _BEARER_RE.match(header)
if not match:
raise ApiError(401, "unauthorized", "Требуется Bearer-токен", challenge=BEARER_CHALLENGE)
return match.group(1)
def _idempotency_key(request: Request) -> str:
value = (request.headers.get("Idempotency-Key") or "").strip()
if not value or not _IDEMPOTENCY_RE.match(value):
raise ApiError(400, "invalid_request", "Требуется корректный Idempotency-Key")
return value
def current_user(request: Request, conn=Depends(get_conn)) -> Dict:
token = _bearer_token(request)
user_id = sessions.resolve(conn, token)
if user_id is None:
raise ApiError(401, "unauthorized", "Сессия недействительна", challenge=BEARER_CHALLENGE)
row = repo.get_user_by_id(conn, user_id)
if row is None:
raise ApiError(401, "unauthorized", "Сессия недействительна", challenge=BEARER_CHALLENGE)
return row
def _require_chat(conn, chat_id: str, user_id: str) -> str:
canonical = _canonical_uuid(chat_id)
if repo.get_chat_for(conn, canonical, user_id) is None:
raise ApiError(404, "not_found", "Чат недоступен")
return canonical
# --------------------------------------------------------------------------- #
# Health
# --------------------------------------------------------------------------- #
@app.get("/health/live")
def liveness() -> dict:
return {"status": "ok"}
@app.get("/health/ready")
def readiness() -> dict:
if state.is_shutting_down():
raise ApiError(503, "unavailable", "Реплика останавливается")
try:
with pool().connection(timeout=2) as conn:
conn.execute("select 1")
except (OperationalError, InterfaceError, PoolTimeout):
raise ApiError(503, "unavailable", "База данных недоступна")
return {"status": "ok"}
# --------------------------------------------------------------------------- #
# Users and sessions
# --------------------------------------------------------------------------- #
@app.post("/api/v1/users", status_code=201)
def register_user(payload: CreateUser, conn=Depends(get_conn)) -> dict:
password_hash = security.hash_password(payload.password)
row = repo.create_user(conn, payload.username, payload.display_name, password_hash)
return repo.user_json(row)
@app.post("/api/v1/auth/sessions", status_code=201)
def create_session(request: Request, conn=Depends(get_conn)) -> dict:
username, password = _parse_basic(request)
row = repo.get_user_with_hash_by_username(conn, username)
if row is None or not security.verify_password(row["password_hash"], password):
raise ApiError(401, "unauthorized", "Неверные учётные данные", challenge=BASIC_CHALLENGE)
token, expires_at = sessions.create(conn, str(row["id"]))
return {
"token": token,
"token_type": "Bearer",
"expires_at": repo.rfc3339(expires_at),
"user": repo.user_json(row),
}
@app.delete("/api/v1/auth/sessions/current", status_code=204)
def revoke_session(
request: Request,
user: Dict = Depends(current_user),
conn=Depends(get_conn),
) -> Response:
sessions.revoke(conn, _bearer_token(request))
return Response(status_code=204)
@app.get("/api/v1/users/me")
def current_user_endpoint(user: Dict = Depends(current_user)) -> dict:
return repo.user_json(user)
# --------------------------------------------------------------------------- #
# Chats
# --------------------------------------------------------------------------- #
@app.post("/api/v1/chats", status_code=201)
def create_chat(payload: CreateChat, user: Dict = Depends(current_user), conn=Depends(get_conn)) -> dict:
members = [str(member) for member in payload.member_ids]
if len(set(members)) != len(members):
raise ApiError(400, "invalid_request", "Дубликаты участников")
if str(user["id"]) not in members:
raise ApiError(400, "invalid_request", "Вызывающий должен входить в участников")
if repo.count_users(conn, members) != len(set(members)):
raise ApiError(400, "invalid_request", "Неизвестный участник")
row = repo.create_chat(conn, payload.title, members)
return repo.chat_json(row)
@app.get("/api/v1/chats")
def list_chats(
limit: int = Query(default=50, ge=1, le=100),
cursor: Optional[str] = Query(default=None),
user: Dict = Depends(current_user),
conn=Depends(get_conn),
) -> dict:
key = bound_cursor(cursor, "chats")
rows = repo.list_chats(conn, str(user["id"]), limit + 1, key)
page = rows[:limit]
next_cursor = None
if len(rows) > limit:
next_cursor = encode_cursor("chats", page[-1]["created_at"], str(page[-1]["id"]))
return {"items": [repo.chat_json(row) for row in page], "next_cursor": next_cursor}
@app.get("/api/v1/chats/{chat_id}")
def get_chat(chat_id: str, user: Dict = Depends(current_user), conn=Depends(get_conn)) -> dict:
canonical = _require_chat(conn, chat_id, str(user["id"]))
row = repo.get_chat_for(conn, canonical, str(user["id"]))
return repo.chat_json(row)
# --------------------------------------------------------------------------- #
# Messages
# --------------------------------------------------------------------------- #
@app.post("/api/v1/chats/{chat_id}/messages", status_code=201)
def create_message(
chat_id: str,
payload: CreateMessage,
request: Request,
user: Dict = Depends(current_user),
conn=Depends(get_conn),
) -> dict:
canonical = _require_chat(conn, chat_id, str(user["id"]))
key = _idempotency_key(request)
scope = f"POST /api/v1/chats/{canonical}/messages"
return repo.create_message_idempotent(
conn,
canonical,
str(user["id"]),
payload.text,
scope,
key,
settings.idempotency_ttl_seconds,
)
@app.get("/api/v1/chats/{chat_id}/messages")
def list_messages(
chat_id: str,
limit: int = Query(default=50, ge=1, le=100),
cursor: Optional[str] = Query(default=None),
user: Dict = Depends(current_user),
conn=Depends(get_conn),
) -> dict:
canonical = _require_chat(conn, chat_id, str(user["id"]))
key = bound_cursor(cursor, canonical)
rows = repo.list_messages(conn, canonical, limit + 1, key)
page = rows[:limit]
next_cursor = None
if len(rows) > limit:
next_cursor = encode_cursor(canonical, page[-1]["created_at"], str(page[-1]["id"]))
return {"items": [repo.message_json(row) for row in page], "next_cursor": next_cursor}
+67
View File
@@ -0,0 +1,67 @@
"""Runtime configuration from environment variables / secret files.
Only logical interface names from ``.env.example`` are consumed; secret values
are read from files (``*_FILE``) so that no credential is baked into the image
or committed. The mapping is documented in REPORT.md.
"""
from __future__ import annotations
import os
from dataclasses import dataclass
from pathlib import Path
def _read_secret(file_key: str, value_key: str, default: str = "") -> str:
path = os.environ.get(file_key)
if path:
try:
return Path(path).read_text(encoding="utf-8").strip()
except OSError:
return default
return os.environ.get(value_key, default)
@dataclass(frozen=True)
class Settings:
app_host: str
app_port: int
app_env: str
session_ttl_seconds: int
session_store: str
session_cache_ttl_seconds: int
cache_invalidation_interval_seconds: float
idempotency_ttl_seconds: int
database_url: str
cache_url: str
db_pool_min: int
db_pool_max: int
db_pool_timeout: float
db_statement_timeout_ms: int
@property
def cache_enabled(self) -> bool:
return bool(self.cache_url) and self.session_store in {"valkey", "redis"}
def load_settings() -> Settings:
return Settings(
app_host=os.environ.get("APP_HOST", "0.0.0.0"),
app_port=int(os.environ.get("APP_PORT", "8080")),
app_env=os.environ.get("APP_ENV", "lab"),
session_ttl_seconds=int(os.environ.get("SESSION_TTL_SECONDS", "3600")),
session_store=os.environ.get("SESSION_STORE", "postgres").lower(),
session_cache_ttl_seconds=int(os.environ.get("SESSION_CACHE_TTL_SECONDS", "60")),
cache_invalidation_interval_seconds=float(
os.environ.get("CACHE_INVALIDATION_INTERVAL_SECONDS", "0.5")
),
idempotency_ttl_seconds=int(os.environ.get("IDEMPOTENCY_TTL_SECONDS", "86400")),
database_url=_read_secret("DATABASE_URL_FILE", "DATABASE_URL"),
cache_url=_read_secret("CACHE_URL_FILE", "CACHE_URL"),
db_pool_min=int(os.environ.get("DB_POOL_MIN", "1")),
db_pool_max=int(os.environ.get("DB_POOL_MAX", "10")),
db_pool_timeout=float(os.environ.get("DB_POOL_TIMEOUT", "5")),
db_statement_timeout_ms=int(os.environ.get("DB_STATEMENT_TIMEOUT_MS", "5000")),
)
settings = load_settings()
+42
View File
@@ -0,0 +1,42 @@
"""PostgreSQL access: a bounded connection pool with timeouts.
All queries elsewhere are parameterized; this module only owns the pool.
A statement timeout and a bounded pool are part of the grade-4 requirements.
"""
from __future__ import annotations
import logging
from typing import Optional
from psycopg.rows import dict_row
from psycopg_pool import ConnectionPool
from .config import settings
logger = logging.getLogger("messenger.db")
_pool: Optional[ConnectionPool] = None
def pool() -> ConnectionPool:
global _pool
if _pool is None:
_pool = ConnectionPool(
conninfo=settings.database_url,
min_size=settings.db_pool_min,
max_size=settings.db_pool_max,
timeout=settings.db_pool_timeout,
kwargs={
"row_factory": dict_row,
"options": f"-c statement_timeout={settings.db_statement_timeout_ms}",
},
open=True,
)
return _pool
def close_pool() -> None:
global _pool
if _pool is not None:
_pool.close()
_pool = None
+20
View File
@@ -0,0 +1,20 @@
"""Shared error type mapped to the contract error envelope."""
from __future__ import annotations
from typing import Optional
class ApiError(Exception):
def __init__(
self,
status: int,
code: str,
message: str,
challenge: Optional[str] = None,
) -> None:
super().__init__(message)
self.status = status
self.code = code
self.message = message
# Optional WWW-Authenticate value (used by 401 responses).
self.challenge = challenge
+21
View File
@@ -0,0 +1,21 @@
"""Stable identity of this API process, exposed as ``X-Instance-Id``.
The value is fixed for the whole life of the process, so clients and the
balancer can tell replicas apart. Inside Docker the default container hostname
already is the (short) container id, which makes the value easy to map back to
a real container without exposing a routable address.
"""
from __future__ import annotations
import os
import socket
def _resolve() -> str:
value = os.environ.get("INSTANCE_ID", "").strip()
if value:
return value
return socket.gethostname() or "api"
INSTANCE_ID = _resolve()
+76
View File
@@ -0,0 +1,76 @@
"""Durable cache-invalidation drainer (lab3).
Logout writes a pending invalidation to PostgreSQL in the same transaction as
the authoritative session delete. This tiny background thread (one per API
replica, not an external broker) removes the corresponding Valkey key and then
the queue row. Multiple replicas may process the same row; cache deletes are
idempotent, so this is safe and needs no distributed lock.
The worker is deliberately not on the request path: it only runs when a cache
is configured, and it retries forever while Valkey is unreachable. That is what
lets a logout survive a Valkey outage: the session is already gone from
PostgreSQL, and the stale cache entry is evicted as soon as the cache returns.
"""
from __future__ import annotations
import logging
import threading
from typing import Optional
from . import repositories as repo
from . import sessions
from .config import settings
from .db import pool
logger = logging.getLogger("messenger.invalidation")
_BATCH = 200
_stop = threading.Event()
_thread: Optional[threading.Thread] = None
def _drain_once() -> None:
with pool().connection() as conn:
pending = repo.list_pending_invalidations(conn, _BATCH)
if not pending:
return
invalidated = [token_hash for token_hash in pending if sessions.invalidate_session_key(token_hash)]
if not invalidated:
# Cache still unreachable; keep the rows for the next attempt.
return
with pool().connection() as conn:
repo.delete_cache_invalidations(conn, invalidated)
logger.debug("drained %d cache invalidations", len(invalidated))
def _loop() -> None:
while not _stop.is_set():
try:
_drain_once()
except Exception as exc: # noqa: BLE001 - never kill the drainer
logger.warning("cache invalidation drain failed: %s", type(exc).__name__)
_stop.wait(settings.cache_invalidation_interval_seconds)
def start_worker() -> None:
global _thread
if not settings.cache_enabled:
return
if _thread is not None and _thread.is_alive():
return
_stop.clear()
_thread = threading.Thread(target=_loop, name="cache-invalidation", daemon=True)
_thread.start()
logger.info(
"cache invalidation drainer started (interval=%.2fs)",
settings.cache_invalidation_interval_seconds,
)
def stop_worker() -> None:
global _thread
_stop.set()
if _thread is not None:
_thread.join(timeout=2)
_thread = None
+60
View File
@@ -0,0 +1,60 @@
"""Container entrypoint: run the HTTP server as PID 1 with graceful shutdown.
Migrations are executed by the dedicated one-shot ``migrate`` compose service
(``python -m src.migrate``) before any replica starts, so replicas do not race
on the schema.
On SIGTERM/SIGINT the handler marks the process as shutting down: readiness
degrades to 503 so the balancer drains this replica, then Uvicorn stops
accepting connections and waits up to ``timeout_graceful_shutdown`` for
in-flight requests to finish.
"""
from __future__ import annotations
import logging
import os
import uvicorn
from . import state
from .config import settings
from .instance import INSTANCE_ID
def main() -> None:
logging.basicConfig(
level=os.environ.get("LOG_LEVEL", "INFO").upper(),
format="%(asctime)s %(levelname)s %(name)s %(message)s",
)
logging.getLogger("messenger").info(
"starting messenger api instance=%s env=%s port=%s sessions=%s cache=%s",
INSTANCE_ID,
settings.app_env,
settings.app_port,
settings.session_store,
"on" if settings.cache_enabled else "off",
)
config = uvicorn.Config(
"src.app:app",
host=settings.app_host,
port=settings.app_port,
log_level=os.environ.get("LOG_LEVEL", "info").lower(),
access_log=True,
timeout_graceful_shutdown=10,
)
server = uvicorn.Server(config)
def handle_exit(sig, frame=None): # noqa: ANN001 - signal handler
state.begin_shutdown()
logging.getLogger("messenger").info("received signal %s; draining", sig)
server.should_exit = True
# Uvicorn installs this exact method as its signal handler; overriding the
# bound attribute keeps cross-platform behaviour while adding our flag.
server.handle_exit = handle_exit
server.run()
if __name__ == "__main__":
main()
+67
View File
@@ -0,0 +1,67 @@
"""Versioned, idempotent migration runner.
Applied versions are recorded in ``schema_migrations``; a transaction-scoped
advisory lock serializes concurrent callers. In lab3 migrations are executed by
a dedicated one-shot ``migrate`` service, not by every API replica, so schema
changes happen exactly once before any replica starts serving traffic.
"""
from __future__ import annotations
import logging
import time
from pathlib import Path
import psycopg
from psycopg_pool import PoolTimeout
from .db import pool
logger = logging.getLogger("messenger.migrate")
MIGRATIONS_DIR = Path(__file__).resolve().parent.parent / "migrations"
LOCK_KEY = 776_2026
def _apply_once() -> None:
files = sorted(MIGRATIONS_DIR.glob("*.sql"))
with pool().connection() as conn:
conn.execute("select pg_advisory_xact_lock(%s)", (LOCK_KEY,))
conn.execute(
"""
create table if not exists schema_migrations (
version text primary key,
applied_at timestamptz not null default now()
)
"""
)
applied = {
row["version"]
for row in conn.execute("select version from schema_migrations").fetchall()
}
for path in files:
if path.name in applied:
continue
logger.info("applying migration %s", path.name)
conn.execute(path.read_text(encoding="utf-8"))
conn.execute(
"insert into schema_migrations (version) values (%s)", (path.name,)
)
def apply_migrations(attempts: int = 30, delay: float = 1.0) -> None:
last: Exception | None = None
for attempt in range(1, attempts + 1):
try:
_apply_once()
logger.info("migrations up to date")
return
except (psycopg.OperationalError, PoolTimeout) as exc:
last = exc
logger.warning("database not ready (attempt %s/%s): %s", attempt, attempts, exc)
time.sleep(delay)
raise RuntimeError(f"database unavailable after {attempts} attempts: {last}")
if __name__ == "__main__":
logging.basicConfig(level=logging.INFO)
apply_migrations()
+53
View File
@@ -0,0 +1,53 @@
"""Opaque keyset cursors for ``(created_at, id)`` ascending pagination."""
from __future__ import annotations
import base64
import binascii
import datetime as dt
import json
import uuid
from typing import Optional, Tuple
from .errors import ApiError
CursorKey = Tuple[dt.datetime, str]
def encode_cursor(resource_id: str, created_at: dt.datetime, item_id: str) -> str:
payload = json.dumps(
{
"r": resource_id,
"t": created_at.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ"),
"i": item_id,
},
separators=(",", ":"),
).encode("utf-8")
return base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
def decode_cursor(cursor: str) -> Tuple[str, CursorKey]:
try:
padded = cursor + "=" * (-len(cursor) % 4)
data = json.loads(base64.urlsafe_b64decode(padded).decode("utf-8"))
if not isinstance(data, dict):
raise ValueError("cursor payload must be an object")
resource = data["r"]
item_id = data["i"]
if not isinstance(resource, str) or not isinstance(item_id, str):
raise ValueError("cursor fields must be strings")
created = dt.datetime.strptime(data["t"], "%Y-%m-%dT%H:%M:%S.%fZ").replace(
tzinfo=dt.timezone.utc
)
return resource, (created, str(uuid.UUID(item_id)))
except (binascii.Error, ValueError, KeyError, TypeError, AttributeError, UnicodeDecodeError):
raise ApiError(400, "invalid_request", "Некорректный cursor")
def bound_cursor(cursor: str, expected_resource: str) -> Optional[CursorKey]:
"""Validate resource binding and return the key, or None for empty cursor."""
if cursor is None:
return None
resource, key = decode_cursor(cursor)
if resource != expected_resource:
raise ApiError(400, "invalid_request", "cursor относится к другому ресурсу")
return key
+357
View File
@@ -0,0 +1,357 @@
"""Parameterized SQL for users, chats, members, messages, sessions and the
shared idempotency ledger.
Every statement uses bound parameters (no string concatenation). Composite
writes happen inside one transaction so the caller gets all-or-nothing.
"""
from __future__ import annotations
import datetime as dt
import hashlib
import json
import uuid
from typing import Dict, List, Optional, Sequence
from psycopg.errors import UniqueViolation
from psycopg.types.json import Jsonb
from .errors import ApiError
from .pagination import CursorKey
def utcnow() -> dt.datetime:
return dt.datetime.now(dt.timezone.utc)
def rfc3339(value: dt.datetime) -> str:
return value.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f") + "Z"
def _members(value) -> List[str]:
if value is None:
return []
return [str(item) for item in value]
def user_json(row: Dict) -> Dict:
return {
"id": str(row["id"]),
"username": row["username"],
"display_name": row["display_name"],
"created_at": rfc3339(row["created_at"]),
}
def chat_json(row: Dict) -> Dict:
return {
"id": str(row["id"]),
"title": row["title"],
"member_ids": _members(row["member_ids"]),
"created_at": rfc3339(row["created_at"]),
}
def message_json(row: Dict) -> Dict:
return {
"id": str(row["id"]),
"chat_id": str(row["chat_id"]),
"sender_id": str(row["sender_id"]),
"text": row["text"],
"created_at": rfc3339(row["created_at"]),
}
# --------------------------------------------------------------------------- #
# Users
# --------------------------------------------------------------------------- #
def create_user(conn, username: str, display_name: str, password_hash: str) -> Dict:
try:
row = conn.execute(
"""
insert into users (id, username, display_name, password_hash, created_at)
values (%s, %s, %s, %s, %s)
returning id, username, display_name, created_at
""",
(str(uuid.uuid4()), username, display_name, password_hash, utcnow()),
).fetchone()
except UniqueViolation:
raise ApiError(409, "conflict", "Имя пользователя уже занято")
return row
def get_user_by_id(conn, user_id: str) -> Optional[Dict]:
return conn.execute(
"select id, username, display_name, created_at from users where id = %s",
(user_id,),
).fetchone()
def get_user_with_hash_by_username(conn, username: str) -> Optional[Dict]:
return conn.execute(
"select id, username, display_name, created_at, password_hash from users where username = %s",
(username,),
).fetchone()
def count_users(conn, user_ids: Sequence[str]) -> int:
row = conn.execute(
"select count(*) as n from users where id = any(%s::uuid[])", (list(user_ids),)
).fetchone()
return int(row["n"])
# --------------------------------------------------------------------------- #
# Chats
# --------------------------------------------------------------------------- #
def create_chat(conn, title: str, member_ids: Sequence[str]) -> Dict:
chat_id = str(uuid.uuid4())
created = utcnow()
conn.execute(
"insert into chats (id, title, created_at) values (%s, %s, %s)",
(chat_id, title, created),
)
with conn.cursor() as cur:
cur.executemany(
"insert into chat_members (chat_id, user_id) values (%s, %s)",
[(chat_id, member) for member in member_ids],
)
return {
"id": chat_id,
"title": title,
"member_ids": list(member_ids),
"created_at": created,
}
_MEMBER_SUBQUERY = (
"(select array_agg(m.user_id) from chat_members m where m.chat_id = c.id)"
)
def get_chat_for(conn, chat_id: str, user_id: str) -> Optional[Dict]:
return conn.execute(
f"""
select c.id, c.title, c.created_at, {_MEMBER_SUBQUERY} as member_ids
from chats c
where c.id = %s
and exists (
select 1 from chat_members cm
where cm.chat_id = c.id and cm.user_id = %s
)
""",
(chat_id, user_id),
).fetchone()
def list_chats(conn, user_id: str, limit: int, cursor: Optional[CursorKey]) -> List[Dict]:
if cursor is None:
return conn.execute(
f"""
select c.id, c.title, c.created_at, {_MEMBER_SUBQUERY} as member_ids
from chats c
join chat_members cm on cm.chat_id = c.id
where cm.user_id = %s
order by c.created_at, c.id
limit %s
""",
(user_id, limit),
).fetchall()
return conn.execute(
f"""
select c.id, c.title, c.created_at, {_MEMBER_SUBQUERY} as member_ids
from chats c
join chat_members cm on cm.chat_id = c.id
where cm.user_id = %s and (c.created_at, c.id) > (%s, %s)
order by c.created_at, c.id
limit %s
""",
(user_id, cursor[0], cursor[1], limit),
).fetchall()
# --------------------------------------------------------------------------- #
# Messages
# --------------------------------------------------------------------------- #
def insert_message(conn, chat_id: str, sender_id: str, text: str) -> Dict:
return conn.execute(
"""
insert into messages (id, chat_id, sender_id, text, created_at)
values (%s, %s, %s, %s, %s)
returning id, chat_id, sender_id, text, created_at
""",
(str(uuid.uuid4()), chat_id, sender_id, text, utcnow()),
).fetchone()
def list_messages(
conn, chat_id: str, limit: int, cursor: Optional[CursorKey]
) -> List[Dict]:
if cursor is None:
return conn.execute(
"""
select id, chat_id, sender_id, text, created_at
from messages
where chat_id = %s
order by created_at, id
limit %s
""",
(chat_id, limit),
).fetchall()
return conn.execute(
"""
select id, chat_id, sender_id, text, created_at
from messages
where chat_id = %s and (created_at, id) > (%s, %s)
order by created_at, id
limit %s
""",
(chat_id, cursor[0], cursor[1], limit),
).fetchall()
# --------------------------------------------------------------------------- #
# Shared idempotency ledger (lab3)
# --------------------------------------------------------------------------- #
def message_request_hash(text: str) -> str:
"""Canonical hash of the semantic body.
JSON key order and an absent ``attachment_ids`` versus ``[]`` must be
equivalent; for lab3 the only field is ``text``. The canonical form is kept
deterministic so any replica computes the same value.
"""
canonical = json.dumps({"text": text}, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
def get_idempotency(conn, user_id: str, scope: str, key: str) -> Optional[Dict]:
return conn.execute(
"""
select request_hash, status_code, response_body
from idempotency_keys
where user_id = %s and scope = %s and key = %s
""",
(user_id, scope, key),
).fetchone()
def insert_idempotency(
conn,
user_id: str,
scope: str,
key: str,
request_hash: str,
status_code: int,
response_body: Dict,
ttl_seconds: int,
) -> None:
conn.execute(
"""
insert into idempotency_keys
(user_id, scope, key, request_hash, status_code, response_body, created_at, expires_at)
values (%s, %s, %s, %s, %s, %s, now(), now() + make_interval(secs => %s))
""",
(user_id, scope, key, request_hash, status_code, Jsonb(response_body), ttl_seconds),
)
def purge_expired_idempotency(conn) -> int:
rows = conn.execute(
"delete from idempotency_keys where expires_at <= now() returning key"
).fetchall()
return len(rows)
def create_message_idempotent(conn, chat_id: str, sender_id: str, text: str, scope: str, key: str, ttl_seconds: int) -> Dict:
"""Create a message exactly once for (sender, scope, key).
A transaction-scoped advisory lock keyed on the logical idempotency scope
serializes concurrent retries across *all* API replicas through PostgreSQL.
The first caller inserts the message and the ledger row in one transaction;
later callers observe the committed row and replay the stored response. A
reused key with different content is a conflict.
"""
request_hash = message_request_hash(text)
conn.execute(
"select pg_advisory_xact_lock(hashtext(%s), hashtext(%s))",
(sender_id + "|" + scope, key),
)
existing = get_idempotency(conn, sender_id, scope, key)
if existing is not None:
if existing["request_hash"] != request_hash:
raise ApiError(409, "conflict", "Idempotency-Key уже использован с другим сообщением")
return existing["response_body"]
message = insert_message(conn, chat_id, sender_id, text)
body = message_json(message)
insert_idempotency(conn, sender_id, scope, key, request_hash, 201, body, ttl_seconds)
return body
# --------------------------------------------------------------------------- #
# Sessions (PostgreSQL is the source of truth)
# --------------------------------------------------------------------------- #
def insert_session(conn, token_hash: str, user_id: str, expires_at: dt.datetime) -> None:
conn.execute(
"""
insert into sessions (token_hash, user_id, created_at, expires_at)
values (%s, %s, %s, %s)
""",
(token_hash, user_id, utcnow(), expires_at),
)
def get_valid_session(conn, token_hash: str) -> Optional[Dict]:
return conn.execute(
"""
select token_hash, user_id, expires_at
from sessions
where token_hash = %s and expires_at > now()
""",
(token_hash,),
).fetchone()
def delete_session(conn, token_hash: str) -> None:
conn.execute("delete from sessions where token_hash = %s", (token_hash,))
def purge_expired_sessions(conn) -> int:
row = conn.execute(
"delete from sessions where expires_at <= now() returning token_hash"
).fetchall()
return len(row)
# --------------------------------------------------------------------------- #
# Durable cache invalidation queue (lab3)
# --------------------------------------------------------------------------- #
def enqueue_cache_invalidation(conn, token_hash: str) -> None:
"""Record a session cache key that must be removed from Valkey.
Written in the same transaction as the authoritative session delete, so a
committed logout can never lose the obligation to invalidate the cache.
"""
conn.execute(
"""
insert into cache_invalidations (token_hash, created_at)
values (%s, now())
on conflict (token_hash) do nothing
""",
(token_hash,),
)
def list_pending_invalidations(conn, limit: int) -> List[str]:
rows = conn.execute(
"select token_hash from cache_invalidations order by created_at limit %s",
(limit,),
).fetchall()
return [str(row["token_hash"]) for row in rows]
def delete_cache_invalidations(conn, token_hashes: Sequence[str]) -> None:
if not token_hashes:
return
conn.execute(
"delete from cache_invalidations where token_hash = any(%s)",
(list(token_hashes),),
)
+33
View File
@@ -0,0 +1,33 @@
"""Password KDF (Argon2id) and opaque bearer-token helpers."""
from __future__ import annotations
import hashlib
import secrets
from argon2 import PasswordHasher
from argon2.exceptions import InvalidHashError, VerifyMismatchError, VerificationError
# Argon2id is the default of argon2-cffi's PasswordHasher. Parameters are kept
# modest so the local test suite stays fast while still using a real KDF.
_hasher = PasswordHasher(time_cost=2, memory_cost=19456, parallelism=1)
def hash_password(password: str) -> str:
return _hasher.hash(password)
def verify_password(password_hash: str, password: str) -> bool:
try:
return _hasher.verify(password_hash, password)
except (VerifyMismatchError, VerificationError, InvalidHashError):
return False
def new_token() -> str:
"""Opaque bearer token with >= 256 bits of entropy."""
return secrets.token_urlsafe(32)
def token_hash(token: str) -> str:
"""Sessions are identified by a SHA-256 of the token, never the token itself."""
return hashlib.sha256(token.encode("utf-8")).hexdigest()
+87
View File
@@ -0,0 +1,87 @@
"""Synthetic data seeder for EXPLAIN evidence (never used by the public smoke).
Runs INSIDE the api container so it can reach PostgreSQL over the compose
network:
docker compose exec -T api python -m src.seed --messages 10000
It writes a small number of users/chats and one "hot" chat with many messages,
then prints the hot chat id so the operator can run EXPLAIN against it.
"""
from __future__ import annotations
import argparse
import datetime as dt
import json
import uuid
from .db import pool
def _now() -> dt.datetime:
return dt.datetime.now(dt.timezone.utc)
def main() -> None:
parser = argparse.ArgumentParser(description="Seed synthetic chat history")
parser.add_argument("--users", type=int, default=10)
parser.add_argument("--chats", type=int, default=3)
parser.add_argument("--messages", type=int, default=10000)
args = parser.parse_args()
user_ids = [str(uuid.uuid4()) for _ in range(args.users)]
chat_ids = [str(uuid.uuid4()) for _ in range(args.chats)]
base = _now()
with pool().connection() as conn:
with conn.cursor() as cur:
cur.executemany(
"""
insert into users (id, username, display_name, password_hash, created_at)
values (%s, %s, %s, %s, %s)
""",
[
(uid, f"seed_{i}_{uuid.uuid4().hex[:6]}", f"Seed {i}", "seed-not-loginable", base)
for i, uid in enumerate(user_ids)
],
)
cur.executemany(
"insert into chats (id, title, created_at) values (%s, %s, %s)",
[(cid, f"Seed chat {i}", base) for i, cid in enumerate(chat_ids)],
)
cur.executemany(
"insert into chat_members (chat_id, user_id) values (%s, %s)",
[(cid, uid) for cid in chat_ids for uid in user_ids],
)
hot_chat = chat_ids[0]
per_chat = max(1, args.messages // len(chat_ids))
rows = []
total = 0
for chat_index, cid in enumerate(chat_ids):
count = args.messages - total if chat_index == len(chat_ids) - 1 else per_chat
count = max(0, count)
for _ in range(count):
rows.append(
(
str(uuid.uuid4()),
cid,
user_ids[0],
"synthetic history message",
base,
)
)
total += count
cur.executemany(
"""
insert into messages (id, chat_id, sender_id, text, created_at)
values (%s, %s, %s, %s, %s)
""",
rows,
)
print(json.dumps({"hot_chat_id": hot_chat, "messages": args.messages, "chats": chat_ids}))
if __name__ == "__main__":
main()
+203
View File
@@ -0,0 +1,203 @@
"""Sessions: PostgreSQL is the source of truth, Valkey is a shared session cache.
Design (lab3):
* ``sessions`` rows in PostgreSQL decide validity (``expires_at > now()``) and
survive restarts with the named volume.
* Valkey caches ``session:{token_hash} -> {user_id, expires_at}`` for at most
``SESSION_CACHE_TTL_SECONDS``. The TTL is a *bounded staleness* guarantee:
even if an invalidation is lost, a cached positive cannot outlive this
window.
* Logout deletes the PostgreSQL row and, in the same transaction, enqueues the
token hash in ``cache_invalidations``. A background drainer (see
``src/invalidation.py``) removes the Valkey key and then the queue row, so
a logout that happened while Valkey was down is still honoured as soon as
the cache returns — instead of being resurrected from a stale entry.
* If Valkey is unreachable every cache operation degrades to PostgreSQL. The
API keeps serving; the cache is never trusted as the source of truth.
Cache calls on the request path are bounded by a hard timeout and a small
circuit breaker (a stopped Valkey can make Docker DNS block for seconds). The
drainer bypasses the breaker on purpose: invalidation must not be skipped.
"""
from __future__ import annotations
import concurrent.futures
import datetime as dt
import json
import logging
import time
from typing import Optional, Tuple
import redis
from redis.backoff import NoBackoff
from redis.retry import Retry
from . import repositories as repo
from . import security
from .config import settings
logger = logging.getLogger("messenger.sessions")
_client: Optional[redis.Redis] = None
_client_disabled = False
_executor = concurrent.futures.ThreadPoolExecutor(max_workers=2, thread_name_prefix="cache")
_OP_TIMEOUT = 0.5
_BREAKER_SECONDS = 5.0
_breaker_until = 0.0
def _cache() -> Optional[redis.Redis]:
global _client, _client_disabled
if not settings.cache_enabled or _client_disabled:
return None
if _client is None:
try:
_client = redis.Redis.from_url(
settings.cache_url,
socket_timeout=0.2,
socket_connect_timeout=0.2,
health_check_interval=0,
retry_on_timeout=False,
retry=Retry(NoBackoff(), 0),
)
except (ValueError, redis.RedisError):
logger.warning("valkey client init failed; cache disabled")
_client_disabled = True
return None
return _client
def _guard(fn, *args):
"""Run a request-path cache operation with a deadline and a small breaker."""
global _breaker_until
if time.monotonic() < _breaker_until:
return None
try:
return _executor.submit(fn, *args).result(timeout=_OP_TIMEOUT)
except (concurrent.futures.TimeoutError, redis.RedisError, OSError):
_breaker_until = time.monotonic() + _BREAKER_SECONDS
logger.warning("valkey unavailable; cache bypassed for %.0fs", _BREAKER_SECONDS)
return None
def _session_key(token_hash: str) -> str:
return f"session:{token_hash}"
def _cache_get(key: str) -> Optional[str]:
client = _cache()
if client is None:
return None
value = _guard(lambda: client.get(key))
if value is None:
return None
return value.decode("utf-8") if isinstance(value, bytes) else str(value)
def _cache_set(key: str, value: str, ttl_seconds: float) -> None:
client = _cache()
if client is None:
return
_guard(lambda: client.set(key, value, ex=max(1, int(ttl_seconds))))
def _cache_delete(key: str) -> None:
client = _cache()
if client is None:
return
_guard(lambda: client.delete(key))
def _encode_session(user_id: str, expires_at: dt.datetime) -> str:
return json.dumps(
{"user_id": user_id, "expires_at": repo.rfc3339(expires_at)},
separators=(",", ":"),
)
def _decode_session(raw: str) -> Optional[Tuple[str, dt.datetime]]:
try:
data = json.loads(raw)
user_id = str(data["user_id"])
value = str(data["expires_at"])
if value.endswith("Z"):
value = value[:-1] + "+00:00"
expires_at = dt.datetime.fromisoformat(value)
return user_id, expires_at
except (ValueError, KeyError, TypeError):
return None
def _cache_ttl(remaining: float) -> int:
return max(1, int(min(remaining, settings.session_cache_ttl_seconds)))
def create(conn, user_id: str) -> Tuple[str, dt.datetime]:
token = security.new_token()
hashed = security.token_hash(token)
expires_at = repo.utcnow() + dt.timedelta(seconds=settings.session_ttl_seconds)
repo.insert_session(conn, hashed, user_id, expires_at)
# The cache is populated by the first successful resolve() (read-through),
# so it can only ever contain sessions already committed to PostgreSQL.
return token, expires_at
def resolve(conn, token: str) -> Optional[str]:
"""Return the session's user id, or None if the token is not valid.
A cache hit is accepted only while the stored expiry is in the future and
only for the bounded cache TTL. A miss or any cache failure falls back to
the authoritative PostgreSQL row.
"""
hashed = security.token_hash(token)
cached = _cache_get(_session_key(hashed))
if cached is not None:
decoded = _decode_session(cached)
if decoded is not None and decoded[1] > repo.utcnow():
return decoded[0]
row = repo.get_valid_session(conn, hashed)
if row is None:
# Remove any legacy/stale entry; revocation is already authoritative.
_cache_delete(_session_key(hashed))
return None
user_id = str(row["user_id"])
remaining = (row["expires_at"] - repo.utcnow()).total_seconds()
if remaining > 0:
_cache_set(
_session_key(hashed),
_encode_session(user_id, row["expires_at"]),
_cache_ttl(remaining),
)
return user_id
def revoke(conn, token: str) -> None:
hashed = security.token_hash(token)
repo.delete_session(conn, hashed)
if settings.cache_enabled:
# Durable obligation, committed together with the session delete.
repo.enqueue_cache_invalidation(conn, hashed)
# Best effort: the drainer retries if this fails (e.g. Valkey is down).
_cache_delete(_session_key(hashed))
def invalidate_session_key(token_hash: str) -> bool:
"""Delete one cache key for the drainer; True means it is safe to dequeue.
Deliberately bypasses the circuit breaker: a transient cache outage must not
cause pending invalidations to be dropped. Socket timeouts still bound the
call so the worker cannot block forever.
"""
client = _cache()
if client is None:
# Cache deliberately disabled -> nothing to invalidate. A client that
# failed to initialise keeps its rows so a restart can retry.
return not settings.cache_enabled
try:
client.delete(_session_key(token_hash))
return True
except (redis.RedisError, OSError):
return False
+19
View File
@@ -0,0 +1,19 @@
"""Process-wide lifecycle flags.
``shutting_down`` is raised from the SIGTERM/SIGINT handler before Uvicorn
stops accepting connections, so ``/health/ready`` reports ``503`` and the
balancer drains this replica instead of sending it new work.
"""
from __future__ import annotations
import threading
_shutting_down = threading.Event()
def begin_shutdown() -> None:
_shutting_down.set()
def is_shutting_down() -> bool:
return _shutting_down.is_set()
+67
View File
@@ -0,0 +1,67 @@
"""Student tests run against an already-running compose stand.
Start the stand first (secrets + `docker compose up -d --build`), then:
.venv\\Scripts\\python -m pytest student-tests -v
# or: make test-student PYTHON=.venv/bin/python
Override the target with BASE_URL (default http://localhost:8080).
"""
from __future__ import annotations
import os
import sys
import pytest
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080")
@pytest.fixture(scope="session")
def base_url() -> str:
return BASE_URL.rstrip("/")
@pytest.fixture(scope="session")
def client(base_url):
from http_client import Client
return Client(base_url)
def _register_and_login(client, label: str) -> dict:
suffix = os.urandom(4).hex()
username = f"s_{label}_{suffix}"
password = "T3st-" + os.urandom(8).hex()
registered = client.register(username, password, "Студент " + label)
assert registered.status == 201, registered.body
user = registered.json
session = client.login(username, password)
assert session.status == 201, session.body
payload = session.json
return {
"id": user["id"],
"username": username,
"password": password,
"user": user,
"token": payload["token"],
}
@pytest.fixture(scope="session")
def alice(client):
return _register_and_login(client, "alice")
@pytest.fixture(scope="session")
def bob(client):
return _register_and_login(client, "bob")
@pytest.fixture(scope="session")
def chat(client, alice, bob):
response = client.create_chat(alice["token"], [alice["id"], bob["id"]])
assert response.status == 201, response.body
return response.json
+125
View File
@@ -0,0 +1,125 @@
"""Minimal stdlib HTTP client for student black-box tests (no extra deps)."""
from __future__ import annotations
import base64
import json
import os
import urllib.error
import urllib.request
from dataclasses import dataclass
from typing import Optional
@dataclass
class Response:
status: int
headers: object
body: bytes
@property
def json(self):
if not self.body:
return None
return json.loads(self.body.decode("utf-8"))
@property
def content_type(self) -> str:
return self.headers.get_content_type()
@property
def request_id(self) -> Optional[str]:
return self.headers.get("X-Request-Id")
@property
def instance_id(self) -> Optional[str]:
return self.headers.get("X-Instance-Id")
class Client:
def __init__(self, base_url: str):
self.base = base_url.rstrip("/")
def request(
self,
method: str,
path: str,
body=None,
raw: Optional[bytes] = None,
token: Optional[str] = None,
basic: Optional[str] = None,
headers: Optional[dict] = None,
) -> Response:
data = raw
request_headers = {"Accept": "application/json"}
if body is not None:
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request_headers["Content-Type"] = "application/json"
if raw is not None:
request_headers.setdefault("Content-Type", "application/json")
if token is not None:
request_headers["Authorization"] = "Bearer " + token
if basic is not None:
request_headers["Authorization"] = "Basic " + basic
if headers:
request_headers.update(headers)
request = urllib.request.Request(
self.base + path, data=data, headers=request_headers, method=method
)
try:
with urllib.request.urlopen(request, timeout=15) as response:
return Response(response.status, response.headers, response.read())
except urllib.error.HTTPError as error:
return Response(error.code, error.headers, error.read())
# -- convenience --------------------------------------------------------
def register(self, username: str, password: str, display_name: str = "Студент") -> Response:
return self.request(
"POST",
"/api/v1/users",
body={"username": username, "display_name": display_name, "password": password},
)
def login(self, username: str, password: str) -> Response:
credential = base64.b64encode(f"{username}:{password}".encode("utf-8")).decode()
return self.request("POST", "/api/v1/auth/sessions", basic=credential)
def me(self, token: str) -> Response:
return self.request("GET", "/api/v1/users/me", token=token)
def create_chat(self, token: str, member_ids, title: str = "Чат") -> Response:
return self.request(
"POST",
"/api/v1/chats",
body={"title": title, "member_ids": list(member_ids)},
token=token,
)
def send(
self,
token: str,
chat_id: str,
text: str,
key: Optional[str] = None,
headers: Optional[dict] = None,
) -> Response:
# lab3 requires an Idempotency-Key on every message POST.
request_headers = dict(headers or {})
request_headers.setdefault("Idempotency-Key", key or os.urandom(16).hex())
return self.request(
"POST",
f"/api/v1/chats/{chat_id}/messages",
body={"text": text},
token=token,
headers=request_headers,
)
def list_messages(self, token: str, chat_id: str, limit: int = 50, cursor=None) -> Response:
path = f"/api/v1/chats/{chat_id}/messages?limit={limit}"
if cursor is not None:
from urllib.parse import quote
path += "&cursor=" + quote(cursor, safe="")
return self.request("GET", path, token=token)
def logout(self, token: str) -> Response:
return self.request("DELETE", "/api/v1/auth/sessions/current", token=token)
+122
View File
@@ -0,0 +1,122 @@
"""Authentication and registration tests (lab2 auth, unchanged in lab3)."""
from __future__ import annotations
import base64
import os
def _assert_error(response, status, code, challenge_prefix=None):
assert response.status == status, (response.status, response.body)
assert response.content_type == "application/json"
payload = response.json
assert payload["error"]["code"] == code
assert response.request_id, "missing X-Request-Id"
assert payload["error"]["request_id"] == response.request_id
if challenge_prefix:
header = response.headers.get("WWW-Authenticate", "")
assert header.lower().startswith(challenge_prefix.lower()), header
def test_registration_requires_password(client):
response = client.request(
"POST", "/api/v1/users", body={"username": "no_pw_" + os.urandom(3).hex(), "display_name": "X"}
)
_assert_error(response, 400, "invalid_request")
def test_short_password_is_400(client):
response = client.register("shortpw_" + os.urandom(3).hex(), "too-short")
_assert_error(response, 400, "invalid_request")
def test_extra_field_is_400(client):
response = client.request(
"POST",
"/api/v1/users",
body={
"username": "extra_" + os.urandom(3).hex(),
"display_name": "X",
"password": "T3st-" + os.urandom(8).hex(),
"role": "admin",
},
)
_assert_error(response, 400, "invalid_request")
def test_malformed_json_is_400(client):
response = client.request("POST", "/api/v1/users", raw=b"{not json")
_assert_error(response, 400, "invalid_request")
def test_duplicate_username_is_409(client):
username = "dup_" + os.urandom(4).hex()
password = "T3st-" + os.urandom(8).hex()
assert client.register(username, password).status == 201
_assert_error(client.register(username, password), 409, "conflict")
def test_registration_never_returns_password(client):
response = client.register("pw_hidden_" + os.urandom(3).hex(), "T3st-" + os.urandom(8).hex())
assert response.status == 201, response.body
assert "password" not in response.json
def test_wrong_password_is_401_basic(client, alice):
_assert_error(
client.login(alice["username"], "definitely-wrong-password"),
401,
"unauthorized",
challenge_prefix="Basic",
)
def test_unknown_user_is_401_basic(client):
_assert_error(
client.login("ghost_" + os.urandom(4).hex(), "T3st-" + os.urandom(8).hex()),
401,
"unauthorized",
challenge_prefix="Basic",
)
def test_basic_on_business_endpoint_is_401_bearer(client, alice):
credential = base64.b64encode(f"{alice['username']}:{alice['password']}".encode()).decode()
response = client.request("GET", "/api/v1/users/me", basic=credential)
_assert_error(response, 401, "unauthorized", challenge_prefix="Bearer")
def test_missing_auth_is_401_bearer(client):
_assert_error(client.request("GET", "/api/v1/users/me"), 401, "unauthorized", challenge_prefix="Bearer")
def test_unknown_bearer_is_401(client):
_assert_error(
client.me("not-a-real-token-" + os.urandom(8).hex()),
401,
"unauthorized",
challenge_prefix="Bearer",
)
def test_x_user_id_is_ignored(client, alice, bob):
only_header = client.request("GET", "/api/v1/users/me", headers={"X-User-Id": alice["id"]})
_assert_error(only_header, 401, "unauthorized", challenge_prefix="Bearer")
response = client.request(
"GET", "/api/v1/users/me", token=alice["token"], headers={"X-User-Id": bob["id"]}
)
assert response.status == 200, response.body
assert response.json["id"] == alice["id"]
def test_logout_revokes_session(client):
suffix = os.urandom(4).hex()
username = f"s_out_{suffix}"
password = "T3st-" + os.urandom(8).hex()
assert client.register(username, password).status == 201
token = client.login(username, password).json["token"]
assert client.me(token).status == 200
logout = client.logout(token)
assert logout.status == 204, logout.body
assert not logout.body
_assert_error(client.me(token), 401, "unauthorized", challenge_prefix="Bearer")
_assert_error(client.logout(token), 401, "unauthorized", challenge_prefix="Bearer")
+37
View File
@@ -0,0 +1,37 @@
"""Concurrency: 100 parallel unique messages survive without loss."""
from __future__ import annotations
import concurrent.futures
import os
def _register(client, label):
username = f"s_race_{label}_{os.urandom(4).hex()}"
password = "T3st-" + os.urandom(8).hex()
assert client.register(username, password).status == 201
token = client.login(username, password).json["token"]
return {"id": client.me(token).json["id"], "token": token}
def test_100_concurrent_messages_are_not_lost(client, alice):
senders = [_register(client, str(i)) for i in range(10)]
members = [alice["id"]] + [sender["id"] for sender in senders]
chat = client.create_chat(alice["token"], members).json
def worker(task):
sender, index = task
response = client.send(sender["token"], chat["id"], f"race-{index}")
assert response.status == 201, response.body
return response.json["id"]
tasks = [(senders[index // 10], index) for index in range(100)]
with concurrent.futures.ThreadPoolExecutor(max_workers=25) as pool:
created = list(pool.map(worker, tasks))
assert len(created) == 100
assert len(set(created)) == 100, "duplicate message ids"
history = client.list_messages(alice["token"], chat["id"], limit=100).json
stored = [item["id"] for item in history["items"]]
assert len(stored) == 100, f"stored {len(stored)} of 100"
assert len(set(stored)) == 100
assert set(stored) == set(created)
+65
View File
@@ -0,0 +1,65 @@
"""Lab3 shared idempotency: replay, conflict and cross-replica concurrency."""
from __future__ import annotations
import concurrent.futures
import json
import uuid
def test_replay_same_key_returns_same_message(client, alice, chat):
key = uuid.uuid4().hex
first = client.send(alice["token"], chat["id"], "идемпотентно", key=key)
assert first.status == 201, first.body
replay = client.send(alice["token"], chat["id"], "идемпотентно", key=key)
assert replay.status == 201, replay.body
assert replay.json == first.json, "replay must return the same Message"
def test_same_key_different_body_is_409(client, alice, chat):
key = uuid.uuid4().hex
assert client.send(alice["token"], chat["id"], "первый", key=key).status == 201
conflict = client.send(alice["token"], chat["id"], "второй", key=key)
assert conflict.status == 409, conflict.body
assert conflict.json["error"]["code"] == "conflict"
def test_missing_key_is_400(client, alice, chat):
response = client.request(
"POST",
f"/api/v1/chats/{chat['id']}/messages",
body={"text": "без ключа"},
token=alice["token"],
)
assert response.status == 400, response.body
assert response.json["error"]["code"] == "invalid_request"
def test_invalid_key_is_400(client, alice, chat):
for bad in ("bad key", "has/slash", "x" * 129, "with$sign"):
response = client.request(
"POST",
f"/api/v1/chats/{chat['id']}/messages",
body={"text": "плохой ключ"},
token=alice["token"],
headers={"Idempotency-Key": bad},
)
assert response.status == 400, (bad, response.status, response.body)
def test_concurrent_same_key_creates_exactly_one_message(client, alice, chat):
key = uuid.uuid4().hex
text = "конкурентный повтор " + uuid.uuid4().hex
def send(_):
return client.send(alice["token"], chat["id"], text, key=key)
with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
responses = list(pool.map(send, range(8)))
assert all(r.status == 201 for r in responses), [r.status for r in responses]
bodies = {json.dumps(r.json, sort_keys=True) for r in responses}
assert len(bodies) == 1, "parallel replays returned different messages"
history = client.list_messages(alice["token"], chat["id"], limit=100).json["items"]
matching = [m for m in history if m["text"] == text]
assert len(matching) == 1, f"expected exactly one stored message, got {len(matching)}"
+23
View File
@@ -0,0 +1,23 @@
"""Lab3 balancing: X-Instance-Id is present and more than one replica serves."""
from __future__ import annotations
def test_instance_header_present_on_success(client, alice):
response = client.me(alice["token"])
assert response.status == 200, response.body
assert response.instance_id, "missing X-Instance-Id"
def test_instance_header_present_on_error(client):
response = client.request("GET", "/api/v1/users/me")
assert response.status == 401, response.body
assert response.instance_id, "error response missing X-Instance-Id"
def test_at_least_two_instances_seen_through_lb(client, alice):
seen = set()
for _ in range(60):
instance = client.me(alice["token"]).instance_id
if instance:
seen.add(instance)
assert len(seen) >= 2, f"expected >=2 API replicas behind the LB, saw {sorted(seen)}"
+65
View File
@@ -0,0 +1,65 @@
"""Negative and access-control tests (carried over, lab3 keeps them)."""
from __future__ import annotations
import os
def _assert_error(response, status, code):
assert response.status == status, (response.status, response.body)
payload = response.json
assert payload["error"]["code"] == code
assert payload["error"]["request_id"] == response.request_id
def _fresh_actor(client, label="peer"):
suffix = os.urandom(4).hex()
username = f"s_{label}_{suffix}"
password = "T3st-" + os.urandom(8).hex()
assert client.register(username, password).status == 201
token = client.login(username, password).json["token"]
return {"id": client.me(token).json["id"], "token": token}
def test_foreign_chat_is_404(client, alice, chat):
stranger = _fresh_actor(client, "stranger")
assert client.request("GET", f"/api/v1/chats/{chat['id']}", token=stranger["token"]).status == 404
_assert_error(client.send(stranger["token"], chat["id"], "чужое"), 404, "not_found")
_assert_error(client.list_messages(stranger["token"], chat["id"]), 404, "not_found")
def test_empty_message_is_400(client, alice, chat):
for text in ("", " ", "\t\n"):
_assert_error(client.send(alice["token"], chat["id"], text), 400, "invalid_request")
def test_oversized_message_is_400(client, alice, chat):
_assert_error(client.send(alice["token"], chat["id"], "x" * 4001), 400, "invalid_request")
def test_limit_out_of_range_is_400(client, alice, chat):
_assert_error(client.list_messages(alice["token"], chat["id"], limit=0), 400, "invalid_request")
_assert_error(client.list_messages(alice["token"], chat["id"], limit=101), 400, "invalid_request")
def test_sender_id_in_body_is_rejected(client, alice, bob, chat):
response = client.request(
"POST",
f"/api/v1/chats/{chat['id']}/messages",
body={"text": "привет", "sender_id": bob["id"]},
token=alice["token"],
headers={"Idempotency-Key": os.urandom(12).hex()},
)
_assert_error(response, 400, "invalid_request")
def test_chat_without_caller_is_400(client, bob, alice):
_assert_error(client.create_chat(bob["token"], [alice["id"]]), 400, "invalid_request")
def test_chat_with_unknown_member_is_400(client, alice):
unknown = "00000000-0000-4000-8000-000000000000"
_assert_error(client.create_chat(alice["token"], [alice["id"], unknown]), 400, "invalid_request")
def test_chat_with_duplicate_members_is_400(client, alice):
_assert_error(client.create_chat(alice["token"], [alice["id"], alice["id"]]), 400, "invalid_request")
+79
View File
@@ -0,0 +1,79 @@
"""Keyset pagination tests (carried over from lab2)."""
from __future__ import annotations
import base64
import json
import os
def _fake_cursor(payload) -> str:
raw = json.dumps(payload, separators=(",", ":")).encode("utf-8")
return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
def _fresh_chat(client, alice):
suffix = os.urandom(4).hex()
username = f"s_page_{suffix}"
password = "T3st-" + os.urandom(8).hex()
assert client.register(username, password).status == 201
peer_token = client.login(username, password).json["token"]
peer_id = client.me(peer_token).json["id"]
response = client.create_chat(alice["token"], [alice["id"], peer_id])
assert response.status == 201, response.body
return response.json
def test_full_traversal_without_duplicates(client, alice):
chat = _fresh_chat(client, alice)
expected = []
for index in range(5):
response = client.send(alice["token"], chat["id"], f"msg-{index}")
assert response.status == 201, response.body
expected.append(response.json["id"])
seen = []
cursor = None
while True:
page = client.list_messages(alice["token"], chat["id"], limit=2, cursor=cursor).json
assert len(page["items"]) <= 2
seen.extend(item["id"] for item in page["items"])
cursor = page["next_cursor"]
if cursor is None:
break
assert len(seen) == 5
assert len(set(seen)) == 5, "duplicate across pages"
assert seen == expected, "pagination reordered history"
def test_cursor_from_other_chat_is_400(client, alice):
first = _fresh_chat(client, alice)
second = _fresh_chat(client, alice)
for index in range(3):
client.send(alice["token"], first["id"], f"a{index}")
client.send(alice["token"], second["id"], f"b{index}")
cursor = client.list_messages(alice["token"], first["id"], limit=1).json["next_cursor"]
assert cursor
foreign = client.list_messages(alice["token"], second["id"], limit=1, cursor=cursor)
assert foreign.status == 400, foreign.body
assert foreign.json["error"]["code"] == "invalid_request"
def test_garbage_cursor_is_400(client, alice):
chat = _fresh_chat(client, alice)
client.send(alice["token"], chat["id"], "hello")
response = client.list_messages(alice["token"], chat["id"], cursor="!!!not-a-cursor!!!")
assert response.status == 400, response.body
def test_well_formed_cursor_with_wrong_types_is_400(client, alice):
bad_payloads = [
{"r": "chats", "t": "2026-01-01T00:00:00.000000Z", "i": 1},
{"r": "chats", "t": "2026-01-01T00:00:00.000000Z", "i": []},
{"r": "chats", "t": "2026-01-01T00:00:00.000000Z", "i": True},
{"r": "chats", "t": "not-a-time", "i": "11111111-1111-4111-8111-111111111111"},
]
for payload in bad_payloads:
response = client.request(
"GET", "/api/v1/chats?cursor=" + _fake_cursor(payload), token=alice["token"]
)
assert response.status == 400, (payload, response.status, response.body)
+34
View File
@@ -0,0 +1,34 @@
"""Grade-4 integrity checks: registration race and composite-op rollback."""
from __future__ import annotations
import concurrent.futures
import os
def test_concurrent_duplicate_username_single_winner(client):
username = "race_dup_" + os.urandom(4).hex()
password = "T3st-" + os.urandom(8).hex()
def register(_):
return client.register(username, password).status
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as pool:
statuses = list(pool.map(register, range(5)))
assert statuses.count(201) == 1, statuses
assert statuses.count(409) == 4, statuses
def test_failed_chat_creation_rolls_back(client, alice):
def chats_count():
return len(client.request("GET", "/api/v1/chats?limit=100", token=alice["token"]).json["items"])
before = chats_count()
unknown = "00000000-0000-4000-8000-000000000000"
response = client.create_chat(alice["token"], [alice["id"], unknown], title="should-rollback")
assert response.status == 400, response.body
after = chats_count()
assert after == before, "failed composite operation left a partial chat"
listed = client.request("GET", "/api/v1/chats?limit=100", token=alice["token"]).json["items"]
assert all(item["title"] != "should-rollback" for item in listed)
+34
View File
@@ -0,0 +1,34 @@
"""Lab3 revocation: logout takes effect immediately on every replica.
Session validity is decided only by PostgreSQL, so a revoked token must be
rejected regardless of which replica answers and regardless of the cache state.
The heavier Valkey-outage reproduction lives in scripts/check-revocation.py.
"""
from __future__ import annotations
import os
def _actor(client, label="revoke"):
suffix = os.urandom(4).hex()
username = f"s_{label}_{suffix}"
password = "T3st-" + os.urandom(8).hex()
assert client.register(username, password).status == 201
token = client.login(username, password).json["token"]
return {"id": client.me(token).json["id"], "token": token}
def test_logout_invalidates_across_replicas(client):
actor = _actor(client)
seen = set()
for _ in range(20):
response = client.me(actor["token"])
assert response.status == 200, response.body
seen.add(response.instance_id)
assert len(seen) >= 2, f"expected the LB to spread requests, saw {sorted(seen)}"
logout = client.logout(actor["token"])
assert logout.status == 204, logout.body
for _ in range(20):
assert client.me(actor["token"]).status == 401