From eeee24d3d745c0b94b9484f4c9bebd23d29163d1 Mon Sep 17 00:00:00 2001 From: Ejur22 Date: Fri, 23 Oct 2026 15:06:43 +0300 Subject: [PATCH 1/3] =?UTF-8?q?=D0=BB=D0=B0=D0=B1=D0=BE=D1=80=D0=B0=D1=82?= =?UTF-8?q?=D0=BE=D1=80=D0=BD=D0=B0=D1=8F=20=D1=80=D0=B0=D0=B1=D0=BE=D1=82?= =?UTF-8?q?=D0=B0=203?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .dockerignore | 36 ++- .env.example | 15 +- .gitattributes | 2 + .gitignore | 3 + Dockerfile | 29 +++ Makefile | 7 +- REPORT.md | 119 ++++++++-- compose.yaml | 137 +++++++++++ evidence/lab3-compose-ps.txt | Bin 0 -> 944 bytes evidence/lab3-explain.txt | Bin 0 -> 4020 bytes evidence/lab3-failover.txt | Bin 0 -> 1413 bytes evidence/lab3-instances.txt | Bin 0 -> 592 bytes evidence/lab3-load.json | 17 ++ evidence/lab3-load.txt | Bin 0 -> 1060 bytes evidence/lab3-migrations.txt | Bin 0 -> 1150 bytes evidence/lab3-persistence.txt | Bin 0 -> 997 bytes evidence/lab3-rolling.txt | Bin 0 -> 812 bytes evidence/lab3-smoke.txt | Bin 0 -> 174 bytes evidence/lab3-stats.txt | Bin 0 -> 684 bytes evidence/lab3-student-tests.txt | Bin 0 -> 204 bytes infra/nginx.conf | 59 +++++ migrations/001_init.sql | 42 ++++ migrations/002_idempotency.sql | 19 ++ requirements.txt | 8 + scripts/gen-secrets.sh | 11 + scripts/restart.sh | 8 + scripts/restore-api.sh | 7 + scripts/rolling-update.sh | 38 +++ scripts/stop-one.sh | 26 +++ secrets.example/README.md | 9 + src/__init__.py | 1 + src/app.py | 372 ++++++++++++++++++++++++++++++ src/config.py | 61 +++++ src/db.py | 42 ++++ src/errors.py | 20 ++ src/instance.py | 21 ++ src/main.py | 60 +++++ src/migrate.py | 67 ++++++ src/pagination.py | 53 +++++ src/repositories.py | 321 ++++++++++++++++++++++++++ src/security.py | 33 +++ src/seed.py | 87 +++++++ src/sessions.py | 131 +++++++++++ src/state.py | 19 ++ student-tests/conftest.py | 67 ++++++ student-tests/http_client.py | 125 ++++++++++ student-tests/test_auth.py | 122 ++++++++++ student-tests/test_concurrency.py | 37 +++ student-tests/test_idempotency.py | 65 ++++++ student-tests/test_instances.py | 23 ++ student-tests/test_negative.py | 65 ++++++ student-tests/test_pagination.py | 79 +++++++ student-tests/test_race.py | 34 +++ 53 files changed, 2476 insertions(+), 21 deletions(-) create mode 100644 .gitattributes create mode 100644 Dockerfile create mode 100644 compose.yaml create mode 100644 evidence/lab3-compose-ps.txt create mode 100644 evidence/lab3-explain.txt create mode 100644 evidence/lab3-failover.txt create mode 100644 evidence/lab3-instances.txt create mode 100644 evidence/lab3-load.json create mode 100644 evidence/lab3-load.txt create mode 100644 evidence/lab3-migrations.txt create mode 100644 evidence/lab3-persistence.txt create mode 100644 evidence/lab3-rolling.txt create mode 100644 evidence/lab3-smoke.txt create mode 100644 evidence/lab3-stats.txt create mode 100644 evidence/lab3-student-tests.txt create mode 100644 infra/nginx.conf create mode 100644 migrations/001_init.sql create mode 100644 migrations/002_idempotency.sql create mode 100644 requirements.txt create mode 100755 scripts/gen-secrets.sh create mode 100755 scripts/restart.sh create mode 100755 scripts/restore-api.sh create mode 100755 scripts/rolling-update.sh create mode 100755 scripts/stop-one.sh create mode 100644 secrets.example/README.md create mode 100644 src/__init__.py create mode 100644 src/app.py create mode 100644 src/config.py create mode 100644 src/db.py create mode 100644 src/errors.py create mode 100644 src/instance.py create mode 100644 src/main.py create mode 100644 src/migrate.py create mode 100644 src/pagination.py create mode 100644 src/repositories.py create mode 100644 src/security.py create mode 100644 src/seed.py create mode 100644 src/sessions.py create mode 100644 src/state.py create mode 100644 student-tests/conftest.py create mode 100644 student-tests/http_client.py create mode 100644 student-tests/test_auth.py create mode 100644 student-tests/test_concurrency.py create mode 100644 student-tests/test_idempotency.py create mode 100644 student-tests/test_instances.py create mode 100644 student-tests/test_negative.py create mode 100644 student-tests/test_pagination.py create mode 100644 student-tests/test_race.py diff --git a/.dockerignore b/.dockerignore index bc16e556..81048714 100644 --- a/.dockerignore +++ b/.dockerignore @@ -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 diff --git a/.env.example b/.env.example index d32b9be0..4531fc78 100644 --- a/.env.example +++ b/.env.example @@ -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,17 @@ 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 + +# 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 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..cf6c9216 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# Keep shell hooks LF so they stay executable on Linux/CI. +*.sh text eol=lf diff --git a/.gitignore b/.gitignore index b5a71896..ce0a75af 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..c8f60042 --- /dev/null +++ b/Dockerfile @@ -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"] diff --git a/Makefile b/Makefile index 5d86d171..26cfe223 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/REPORT.md b/REPORT.md index c2679005..764a8f97 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,126 @@ # Отчёт — лабораторная 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 # поочерёдная замена под нагрузкой + +# Безопасная остановка (данные сохраняются): +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 — read-through кэш с TTL и обходом при отказе. Sticky session не используются: пользователь свободно попадает на любую реплику без повторного входа. +- **Одноразовые миграции.** Отдельный сервис `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` — без кэша | +| `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 | чередование `4141f552b001`/`5ac0582fa5e1` (2 реплики), один токен | `evidence/lab3-instances.txt` | +| Уровень 3: остановка одной реплики, запись/чтение продолжаются ≤10 с | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 138 успешных записей, 0 ошибок, восстановление **0.898 с**; `api-6 Exited` при живом `api-5` | `evidence/lab3-failover.txt` | +| Общая идемпотентность, в т.ч. конкурентная и через разные реплики | `test_idempotency.py` | повтор = тот же Message; другой body → 409; 8 параллельных запросов с одним ключом → ровно одно сообщение | `evidence/lab3-student-tests.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` 2 строки | `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` | 133 RPS, 0 ошибок, p50/p95/p99 = 47/141/203 мс | `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-6 Exited` | **0.898 с**; потерь нет | +| То же для второй реплики (после восстановления первой) | то же | 138 записей, 0 ошибок, `api-2 Exited` | **1.02 с** | +| `docker compose restart api lb postgres valkey` | данные и сессия сохранены | `PASS: persistence preserved……` | рестарт ≈ секунды; потерь нет | +| Rolling update (`rolling-update.sh`) под непрерывным опросом | замена реплик без недоступности | 400/400 `200` при поочерёдной замене | простоя нет | +| Нагрузка 133 RPS на 2 реплики | стабильная пропускная способность | 0 ошибок, p99 203 мс | n/a | + +Ограничения измерения: closed-loop генератор страдает coordinated omission и ограничен клиентом; числа — throughput HTTP-подтверждений, не точный счётчик COMMIT; единичный Docker-host не проверяет отказ узла. `docker stats` показывает ~74 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. +- Подтверждено измерениями: смена обслуживающей реплики при отказе, конкуренто-безопасная идемпотентность, сохранность после рестарта, использование индекса (EXPLAIN), отсутствие публикации портов API. +- Возможное улучшение (гипотеза): при большем числе реплик и `proxy_next_upstream_tries` можно снизить долю ошибок при «жёстком» (без ожидания healthy) rolling-обновлении; в этой работе замена ожидает healthy, поэтому ошибок нет. diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..e0c4b507 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,137 @@ +# 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} + 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 diff --git a/evidence/lab3-compose-ps.txt b/evidence/lab3-compose-ps.txt new file mode 100644 index 0000000000000000000000000000000000000000..74b954fe1ac5c41b033ae4687cf373da7938ee48 GIT binary patch literal 944 zcmcJNT}uK%6o#Mc!2d9p32LoYY8OFB7hP!4uHLU7sN@%^fq%Yyk1OuxM{Gh2Gjo`k z^YWZ`&i7Y?N9sJ`{y2Q)ywT#BS|ZygkX}F&KegT~FH#DWk>P?dJ?0ucCiJy_kY_|l zo06iC8AI*ffqHbaUqw^z9k<+QHO&rF>2?)6E*a<~l=?!^itJXi!ZkLpbly>ZdaB}9 zA*T3^%A@+PR3mwI%qgde+Xtjhe`a1;4P$vcVX6Aux)W1b IJ(8qa19)11xBvhE literal 0 HcmV?d00001 diff --git a/evidence/lab3-explain.txt b/evidence/lab3-explain.txt new file mode 100644 index 0000000000000000000000000000000000000000..47fe1c70384bba5e76c42aa26a6b53ef824a9d68 GIT binary patch literal 4020 zcmeH~ZBG+H5Xa}WiQnPEn?kgtrB9TkCR9lzq9SV47(=e56@sNmO9YKyUH$!Md)&35 z&>)&X$fkR;9H5gYc0z&$NXwg zW!}fufzrIpD$ni;bPEX`s4~wQR2@kVU0#pXfDzkgr@}cpBaE;s(Pc2wwgY{{t@yMncCzPF)w(7nJ;>0Dt?Vp-k!yLhUN6#1gd4spm+OQUx& zZ#qcGvkpV&lsKi%t`fgF`(!`uzTKM=nFid~6BC`$@DbUXy|+!^}u^tHZw_$tMJc_8|zI|g?1FVUlg!V(QMmz;L7F?2WYDm?`_J#G(&*`wI zfV5>0OV7o#Rb@eBYW=&beBwvYIAwYkE|B*mj7PPe+<5p1MUG z@UHLkiWNd0k;OUN0rSYFw1tSm+BQsX0x?|5MRro6T@r36*z3!#Ga}B2Fpg2^0$=;m% zM*hk3D~{#}y1+T<{J`mOdV(Rsr>76^TmyD7p%_T4?x@%v)V`IEb$o;oj#i>YK+ z@|^U*!WbfDBbBAoENwcTDRu#|I(C8;!bsuh@|5by%9_2BiZe(%zpB=$Al{>DO*C<+@xyNTMo$O1O9QYWGZV`X+@+}r^t)!4U*Nd)OnS=CD2eEq6ba{9oDEu eq5d&gu{Y{*lU#LpYZ5gg6r6J)|6%dTfyzyq^cx*|DD+q;JquZqZDH9G+O--}`pbIgPwHRj%v&oc zrG%ywVeRVeyqS4#pMQS;k*2BJ<=e`I%7lfsT&Zlx+#r4u~OchVx{@a zd8)n$r5mly*|f*HliKnZ#C+gRH>!IRYsW0d{K{B8_c7KRyZS5MfeaPIe8m)PM%lRW90d-Q)-J+R)!X7qScoJJn6_6vO3{vZGV literal 0 HcmV?d00001 diff --git a/evidence/lab3-instances.txt b/evidence/lab3-instances.txt new file mode 100644 index 0000000000000000000000000000000000000000..597a7b4f3e243db47aab570dc5c46524a1c053a3 GIT binary patch literal 592 zcmeH^!3x4K5Jca(;6LQni$Ys0h(~XNA0UW_)~4EvrET={)oB8HZ?CdsH#@VFgv|SO zWW}C41CB!Vg7rv+5oYOlCJK0OUab`@5HDdgg9pF literal 0 HcmV?d00001 diff --git a/evidence/lab3-load.json b/evidence/lab3-load.json new file mode 100644 index 00000000..ebdbd77f --- /dev/null +++ b/evidence/lab3-load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 20.0, + "elapsed_seconds": 20.375, + "concurrency": 8, + "successful_requests": 2712, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 133.104, + "successful_latency_ms": { + "p50": 47.0, + "p95": 141.0, + "p99": 203.0 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/lab3-load.txt b/evidence/lab3-load.txt new file mode 100644 index 0000000000000000000000000000000000000000..a68bd5d11a3f81c2907dd1cf80dee8414c58abc2 GIT binary patch literal 1060 zcmZ{k(N4lZ5Jl(N#D8e|tXKqt=r5RPBJTug5hAomi^dp!T|IZVMOJAV>U8JMotZnc zet&)1shwEF6Wh`z_Qc;CzIt|c;CZ*gHueId0F&03*rx8Jw2ZTJXBW06`oZq)(MDJ+ zd?nAso}G2eSq@9Y$<`{Y6;@>nxFT|7*c-kS6$drQ_ezXB74Ou>{I;Ndd;#wmUj~!x z)G?@+OG~W7@35oHb-Q+WF}26_Y+zSGtmmJ)+^Q-k<43K@b$~3vOnJNpGrpGO3OiAs zzRH1hsr9hR8NDrt@!cMe``gzBeoaex8fAQj|0=ZACtZ9@mrdxQUKjoPL2bulwL_YY z*JR9e8>Zh)^V_yY)uhhSN8@lp4Q2?csiaR8ZK&a1#l+Q{?6-FpRIS}peV#M6yP)2P z?ak0l6U)JQ?Mrq@Gki}Ys@Xmm(|u{XWpi*%ZJKyW-n@<#pYGNIM9Et>LYZ|hJfrTIdKAugHs?gQyMsFV Iuds9PAC6R`v;Y7A literal 0 HcmV?d00001 diff --git a/evidence/lab3-migrations.txt b/evidence/lab3-migrations.txt new file mode 100644 index 0000000000000000000000000000000000000000..b14ab1f51411505b44493d0b88e1cb7dc747af1f GIT binary patch literal 1150 zcmchXTT8=05QWb}o&^6xo(I3gS;!znL^di?6x*!0B#(kKq|OdsqA1ZNhv+ZizR0t^@k&8k^_{ zFUG62?t?$}^R`hQy7tbrd+tHqBR0TdG^B7<*(HaK)$7Yq(RW?3F23k*V|t(?-@l}~ zrsf&vn2hoyA7jS0`fDo{Hr1pTFT92s6>5NeO9kp^%cH3)w|@(J=|j#k`H;KF8w!1oDJFSa4}DU<&>1O#^iW73 z2uZ8;?(FQWf4;tpqA=@nxH1K99gx;M+0I@-$eY<62>HWE*;f)~C}jV?(=VzM~y@R*a5} zGAJ?du9K(Xmy%cq7K*efD>7@2F-Ca7BVM^4nEM~6LnSdD_SGz_wD=&l$9nIpSS@mk zMVlC?@7&=r2XU@b{+zMTwA8Ws5~^4j=DUO%XlI{K=pE}x&w&UP@2p$yrGS>9za!F$ zUll9NHBq~yl)4mVN$%2J5m`qu_w<>BQY3ZMSyotcRP>BfEb)#TS|zb+-nYzoqit}< zomG}PRjM@MOf`pw*h}m%Jp);Imql*KeTM5ZaP?>CAI<9IIiAu(Ry-Jh;b$NvR5b-0EA literal 0 HcmV?d00001 diff --git a/evidence/lab3-rolling.txt b/evidence/lab3-rolling.txt new file mode 100644 index 0000000000000000000000000000000000000000..89d2a53eecb571213a53d620ca64497997813458 GIT binary patch literal 812 zcmb7?O>V+K428X})H~z^g+LO1dVwyhiVI|BLW`7A8b~EB-}ZZkpt3=#MzI|~`;9&J z&-cCE*^BkI`3Gmzao3=-u8G$_6AecimE8=HyPPPrN0JYuGAIa<%|_ z1dG%)_nHD&Nvx2Z+t3fyIq*M3{XG}oT*T$`=K$Q+XesV+OweD?s$x!6*{Q|o^ BfnWdt literal 0 HcmV?d00001 diff --git a/evidence/lab3-smoke.txt b/evidence/lab3-smoke.txt new file mode 100644 index 0000000000000000000000000000000000000000..9155c94f2bba3373ba257ce54467ccbf29946ffc GIT binary patch literal 174 zcmW-bF%H5o5Co@2;tzfS4INY|(?#M12Ae2S5>QBZK4ffJ^6lP@_U`}dXt?<<1V$ov z&Z;+?YGmM{Yv^dLA6;gaTAaMN+8gvweRR57H<{IckqmZclC`fys&ucP0frMlw7C|pxozWymH%1IN&SmcT?m6>% zt}#V`1qMH^IW`E{GpzMVoq*>MTdFP#)e+At_^kWbp^qL;h;ikLamIn)92!zY*kjDU z2pJOYc1^dO&4UgBLm@htuxi1feu5c$B+ueK`%~#o6fL4bZIe^gJyt~V2Qj5rjmquJ zCDCYjH0eg?6e`iAOSiMf3>PMTW8Qg@{+C{QbQO<+%F=nIU#2Qpu{sm)e906?(jE=3 Qk| ($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); diff --git a/migrations/002_idempotency.sql b/migrations/002_idempotency.sql new file mode 100644 index 00000000..2fba4094 --- /dev/null +++ b/migrations/002_idempotency.sql @@ -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); diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..12a69401 --- /dev/null +++ b/requirements.txt @@ -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 diff --git a/scripts/gen-secrets.sh b/scripts/gen-secrets.sh new file mode 100755 index 00000000..2a5c8f18 --- /dev/null +++ b/scripts/gen-secrets.sh @@ -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)." diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..252a031c --- /dev/null +++ b/scripts/restart.sh @@ -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 diff --git a/scripts/restore-api.sh b/scripts/restore-api.sh new file mode 100755 index 00000000..42b6544e --- /dev/null +++ b/scripts/restore-api.sh @@ -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 diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh new file mode 100755 index 00000000..9bbfc91b --- /dev/null +++ b/scripts/rolling-update.sh @@ -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." diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..2547395a --- /dev/null +++ b/scripts/stop-one.sh @@ -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 diff --git a/secrets.example/README.md b/secrets.example/README.md new file mode 100644 index 00000000..108b27f9 --- /dev/null +++ b/secrets.example/README.md @@ -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 diff --git a/src/__init__.py b/src/__init__.py new file mode 100644 index 00000000..19d86e09 --- /dev/null +++ b/src/__init__.py @@ -0,0 +1 @@ +"""MTUSI Messenger lab3 application package.""" diff --git a/src/app.py b/src/app.py new file mode 100644 index 00000000..a8da8af5 --- /dev/null +++ b/src/app.py @@ -0,0 +1,372 @@ +"""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 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 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", +} + +app = FastAPI( + title="MTUSI Messenger — лабораторная 3", + version="1.3.0", + docs_url=None, + redoc_url=None, + openapi_url=None, +) + + +# --------------------------------------------------------------------------- # +# 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} diff --git a/src/config.py b/src/config.py new file mode 100644 index 00000000..eadb4574 --- /dev/null +++ b/src/config.py @@ -0,0 +1,61 @@ +"""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 + 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(), + 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() diff --git a/src/db.py b/src/db.py new file mode 100644 index 00000000..5353efc5 --- /dev/null +++ b/src/db.py @@ -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 diff --git a/src/errors.py b/src/errors.py new file mode 100644 index 00000000..48f9a0f0 --- /dev/null +++ b/src/errors.py @@ -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 diff --git a/src/instance.py b/src/instance.py new file mode 100644 index 00000000..8411c30e --- /dev/null +++ b/src/instance.py @@ -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() diff --git a/src/main.py b/src/main.py new file mode 100644 index 00000000..502c57ff --- /dev/null +++ b/src/main.py @@ -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() diff --git a/src/migrate.py b/src/migrate.py new file mode 100644 index 00000000..76f17bb9 --- /dev/null +++ b/src/migrate.py @@ -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() diff --git a/src/pagination.py b/src/pagination.py new file mode 100644 index 00000000..c832d2ff --- /dev/null +++ b/src/pagination.py @@ -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 diff --git a/src/repositories.py b/src/repositories.py new file mode 100644 index 00000000..5a1ba105 --- /dev/null +++ b/src/repositories.py @@ -0,0 +1,321 @@ +"""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) diff --git a/src/security.py b/src/security.py new file mode 100644 index 00000000..79aaa92d --- /dev/null +++ b/src/security.py @@ -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() diff --git a/src/seed.py b/src/seed.py new file mode 100644 index 00000000..c59e338c --- /dev/null +++ b/src/seed.py @@ -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() diff --git a/src/sessions.py b/src/sessions.py new file mode 100644 index 00000000..f1eee158 --- /dev/null +++ b/src/sessions.py @@ -0,0 +1,131 @@ +"""Sessions: PostgreSQL is the source of truth, Valkey is a read-through cache. + +Design: + * ``sessions`` rows in PostgreSQL decide validity (``expires_at > now()``). + * Valkey caches ``session:{token_hash} -> user_id`` with a TTL equal to the + remaining session lifetime. + * If Valkey is unreachable the cache is bypassed transparently and the API + keeps authenticating from PostgreSQL (Valkey is never trusted as authority). + +Every cache operation is bounded by a hard timeout and guarded by a tiny +circuit breaker. A stopped Valkey container can make Docker DNS itself block +for several seconds; without this guard a cache outage would stall request +handling. On any failure the breaker skips the cache for a few seconds. +""" +from __future__ import annotations + +import concurrent.futures +import datetime as dt +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 cache operation with a hard 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 _key(token_hash: str) -> str: + return f"session:{token_hash}" + + +def _cache_get(token_hash: str) -> Optional[str]: + client = _cache() + if client is None: + return None + value = _guard(lambda: client.get(_key(token_hash))) + if value is None: + return None + return value.decode("utf-8") if isinstance(value, bytes) else str(value) + + +def _cache_set(token_hash: str, user_id: str, ttl_seconds: float) -> None: + client = _cache() + if client is None: + return + _guard(lambda: client.set(_key(token_hash), user_id, ex=max(1, int(ttl_seconds)))) + + +def _cache_delete(token_hash: str) -> None: + client = _cache() + if client is None: + return + _guard(lambda: client.delete(_key(token_hash))) + + +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) + _cache_set(hashed, user_id, settings.session_ttl_seconds) + return token, expires_at + + +def resolve(conn, token: str) -> Optional[str]: + hashed = security.token_hash(token) + cached = _cache_get(hashed) + if cached is not None: + return cached + row = repo.get_valid_session(conn, hashed) + if row is None: + return None + user_id = str(row["user_id"]) + remaining = (row["expires_at"] - repo.utcnow()).total_seconds() + if remaining > 0: + _cache_set(hashed, user_id, remaining) + return user_id + + +def revoke(conn, token: str) -> None: + hashed = security.token_hash(token) + repo.delete_session(conn, hashed) + _cache_delete(hashed) diff --git a/src/state.py b/src/state.py new file mode 100644 index 00000000..276a5d95 --- /dev/null +++ b/src/state.py @@ -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() diff --git a/student-tests/conftest.py b/student-tests/conftest.py new file mode 100644 index 00000000..17447d63 --- /dev/null +++ b/student-tests/conftest.py @@ -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 diff --git a/student-tests/http_client.py b/student-tests/http_client.py new file mode 100644 index 00000000..762114ce --- /dev/null +++ b/student-tests/http_client.py @@ -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) diff --git a/student-tests/test_auth.py b/student-tests/test_auth.py new file mode 100644 index 00000000..646db383 --- /dev/null +++ b/student-tests/test_auth.py @@ -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") diff --git a/student-tests/test_concurrency.py b/student-tests/test_concurrency.py new file mode 100644 index 00000000..a6506194 --- /dev/null +++ b/student-tests/test_concurrency.py @@ -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) diff --git a/student-tests/test_idempotency.py b/student-tests/test_idempotency.py new file mode 100644 index 00000000..9e667e5e --- /dev/null +++ b/student-tests/test_idempotency.py @@ -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)}" diff --git a/student-tests/test_instances.py b/student-tests/test_instances.py new file mode 100644 index 00000000..d8cf51ef --- /dev/null +++ b/student-tests/test_instances.py @@ -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)}" diff --git a/student-tests/test_negative.py b/student-tests/test_negative.py new file mode 100644 index 00000000..a5af2237 --- /dev/null +++ b/student-tests/test_negative.py @@ -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") diff --git a/student-tests/test_pagination.py b/student-tests/test_pagination.py new file mode 100644 index 00000000..18e7188b --- /dev/null +++ b/student-tests/test_pagination.py @@ -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) diff --git a/student-tests/test_race.py b/student-tests/test_race.py new file mode 100644 index 00000000..a095feb0 --- /dev/null +++ b/student-tests/test_race.py @@ -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) -- 2.54.0 From c60c78b51e2bcb1cddb657d0aa328d6444dd9261 Mon Sep 17 00:00:00 2001 From: Ejur22 Date: Fri, 23 Oct 2026 19:46:34 +0300 Subject: [PATCH 2/3] =?UTF-8?q?=D0=98=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D0=BE=D0=B1=D1=85=D0=BE=D0=B4=20=D0=BE=D1=82?= =?UTF-8?q?=D0=B7=D1=8B=D0=B2=D0=B0=20=D1=81=D0=B5=D1=81=D1=81=D0=B8=D0=B8?= =?UTF-8?q?=20=D0=BF=D1=80=D0=B8=20=D1=81=D0=B1=D0=BE=D0=B5=20Valkey?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit resolve() больше не доверяет кэшу: валидность сессии всегда проверяется в PostgreSQL, поэтому неудавшаяся инвалидация при недоступном Valkey не воскрешает отозванный токен. Valkey остаётся read-through кэшем неизменяемого профиля. Добавлены scripts/check-revocation.py и student-tests/test_session_revocation.py. --- REPORT.md | 12 ++- evidence/lab3-compose-ps.txt | Bin 944 -> 465 bytes evidence/lab3-explain.txt | Bin 4020 -> 1985 bytes evidence/lab3-failover.txt | Bin 1413 -> 1390 bytes evidence/lab3-instances.txt | Bin 592 -> 292 bytes evidence/lab3-load.txt | Bin 1060 -> 512 bytes evidence/lab3-migrations.txt | Bin 1150 -> 569 bytes evidence/lab3-persistence.txt | Bin 997 -> 994 bytes evidence/lab3-revocation-fix.txt | 4 + evidence/lab3-rolling.txt | Bin 812 -> 395 bytes evidence/lab3-smoke.txt | Bin 174 -> 85 bytes evidence/lab3-stats.txt | Bin 684 -> 335 bytes evidence/lab3-student-tests.txt | Bin 204 -> 100 bytes evidence/lab3-valkey-degradation.txt | 6 ++ scripts/check-revocation.py | 79 ++++++++++++++++++++ src/app.py | 10 ++- src/sessions.py | 89 ++++++++++++++++------- student-tests/test_session_revocation.py | 34 +++++++++ 18 files changed, 198 insertions(+), 36 deletions(-) create mode 100644 evidence/lab3-revocation-fix.txt create mode 100644 evidence/lab3-valkey-degradation.txt create mode 100644 scripts/check-revocation.py create mode 100644 student-tests/test_session_revocation.py diff --git a/REPORT.md b/REPORT.md index 764a8f97..6d20dadb 100644 --- a/REPORT.md +++ b/REPORT.md @@ -46,6 +46,7 @@ make test-persistence ACTION_SCRIPT=scripts/restart.sh # выполня 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 @@ -63,7 +64,7 @@ docker compose down -v - **Динамический 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 — read-through кэш с TTL и обходом при отказе. Sticky session не используются: пользователь свободно попадает на любую реплику без повторного входа. +- **Сессии общие, отзыв немедленный.** Источник истины — PostgreSQL: каждый запрос проверяет строку сессии (`sessions.expires_at > now()`), поэтому отозванный токен даёт `401` на любой реплике немедленно. Valkey — read-through кэш **неизменяемого профиля пользователя** (`user:{id}`, TTL 300 c), он никогда не используется для решения о доступе. Поэтому сбой инвалидации при лежащем Valkey не может «воскресить» отозванную сессию (регрессионная проверка — `scripts/check-revocation.py`). Sticky session не используются: пользователь свободно попадает на любую реплику без повторного входа. - **Одноразовые миграции.** Отдельный сервис `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 работает. @@ -90,8 +91,10 @@ docker compose down -v | Публичный 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 | чередование `4141f552b001`/`5ac0582fa5e1` (2 реплики), один токен | `evidence/lab3-instances.txt` | -| Уровень 3: остановка одной реплики, запись/чтение продолжаются ≤10 с | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 138 успешных записей, 0 ошибок, восстановление **0.898 с**; `api-6 Exited` при живом `api-5` | `evidence/lab3-failover.txt` | +| Уровень 3: остановка одной реплики, запись/чтение продолжаются ≤10 с | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 122 успешных записи, 0 ошибок, восстановление **1.083 с**; `api-6 Exited` при живом `api-5` | `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` | +| Деградация кэша без остановки 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` 2 строки | `evidence/lab3-migrations.txt` | | Уровень 4: health/readiness, SIGTERM, LB исключает backend | `scripts/stop-one.sh` + `/health/ready` | остановленная реплика исчезает из ответов; readiness→503 при SIGTERM; пассивные проверки nginx | `evidence/lab3-failover.txt` | @@ -109,10 +112,11 @@ docker compose down -v | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| Остановка одной API-реплики (`stop-one.sh`, TARGET = обслужившая реплика) | записи/чтения продолжаются, без дублей, токен жив | 138 записей за 15 с, 0 ошибок, цель не в последних ответах; `api-6 Exited` | **0.898 с**; потерь нет | -| То же для второй реплики (после восстановления первой) | то же | 138 записей, 0 ошибок, `api-2 Exited` | **1.02 с** | +| Остановка одной API-реплики (`stop-one.sh`, TARGET = обслужившая реплика) | записи/чтения продолжаются, без дублей, токен жив | 122 записи за 15 с, 0 ошибок, цель не в последних ответах; `api-6 Exited` | **1.083 с**; потерь нет | +| То же для второй реплики (после восстановления первой) | то же | ≈120–140 записей, 0 ошибок; `api-2 Exited` | **≈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 → 6 c → 401 через обе реплики, POST отклонён | потерь нет; сессия отозвана в PostgreSQL | | Нагрузка 133 RPS на 2 реплики | стабильная пропускная способность | 0 ошибок, p99 203 мс | n/a | Ограничения измерения: closed-loop генератор страдает coordinated omission и ограничен клиентом; числа — throughput HTTP-подтверждений, не точный счётчик COMMIT; единичный Docker-host не проверяет отказ узла. `docker stats` показывает ~74 MB RSS на реплику при лимите 256 MB. diff --git a/evidence/lab3-compose-ps.txt b/evidence/lab3-compose-ps.txt index 74b954fe1ac5c41b033ae4687cf373da7938ee48..9dc0b6ef7a8db9d37db56f0b154c61232bbe85a8 100644 GIT binary patch literal 465 zcmeZs^mSFh0fJqF!aSY9(!n8)A)&$8)CKqlg#>furWO~c=B1|=>EP?dJ?0ucCiJy_kY_|l zo06iC8AI*ffqHbaUqw^z9k<+QHO&rF>2?)6E*a<~l=?!^itJXi!ZkLpbly>ZdaB}9 zA*T3^%A@+PR3mwI%qgde+Xtjhe`a1;4P$vcVX6Aux)W1b IJ(8qa19)11xBvhE diff --git a/evidence/lab3-explain.txt b/evidence/lab3-explain.txt index 47fe1c70384bba5e76c42aa26a6b53ef824a9d68..e8f438b7654903a1806352ff717bcdfae6bd17c9 100644 GIT binary patch literal 1985 zcmds1ZBN@U5dNNDaq5?*8jkEZXUmah9U*r2$5R zJs6bOw&D_7eTGpjddu8m{(n6ClCdXe9+Mu4{F!#f-GGQtyOoj5QbB!2{lGYjB0uAD zCP_wRMm$%435kNtw73BeBaeH7pMR`7xg^g?#7dF`4!@lq9~@0#j@K3 zE3p7ol$cN_45;In#qVu>3X8g4wh0>Yph&lL?JQ1E<#if^s+VL6If`Z5#dU&Z-RQ%7JfCcj zJf2bS)Z{fOR4JD5US9?0QdCe^u;~JuGJ6hpyDE=wEB92DU6-45efJg-uH{~xd*A(h zhB8Mvhqra5v$E~mmIVn6pYzg(alBd;=?D&{@4!C$_|?8&y%Fq#*&VvnrGzp)fYP`d zZz$Er4K-RN%BALw$~&gOOu8cx&zZumE!sVPJO4}q+X=D>904~QHN^Q8wBq^5c=SGxU}P`UV6(Xf$QV% z!+Cw+J&q3N7Mw0bRTb4`Y=GJYA>-q%6@1ndi-9_vaVT304%aAGs?hIjqlsu>G&T#m I%8xATFC%~MfB*mh literal 4020 zcmeH~ZBG+H5Xa}WiQnPEn?kgtrB9TkCR9lzq9SV47(=e56@sNmO9YKyUH$!Md)&35 z&>)&X$fkR;9H5gYc0z&$NXwg zW!}fufzrIpD$ni;bPEX`s4~wQR2@kVU0#pXfDzkgr@}cpBaE;s(Pc2wwgY{{t@yMncCzPF)w(7nJ;>0Dt?Vp-k!yLhUN6#1gd4spm+OQUx& zZ#qcGvkpV&lsKi%t`fgF`(!`uzTKM=nFid~6BC`$@DbUXy|+!^}u^tHZw_$tMJc_8|zI|g?1FVUlg!V(QMmz;L7F?2WYDm?`_J#G(&*`wI zfV5>0OV7o#Rb@eBYW=&beBwvYIAwYkE|B*mj7PPe+<5p1MUG z@UHLkiWNd0k;OUN0rSYFw1tSm+BQsX0x?|5MRro6T@r36*z3!#Ga}B2Fpg2^0$=;m% zM*hk3D~{#}y1+T<{J`mOdV(Rsr>76^TmyD7p%_T4?x@%v)V`IEb$o;oj#i>YK+ z@|^U*!WbfDBbBAoENwcTDRu#|I(C8;!bsuh@|5by%9_2BiZe(%zpB=$Al{>DO*C<+@xyNTMo$O1O9QYWGZV`X+@+}r^t)!4U*Nd)OnS=CD2eEq6ba{9oDEu eq5d&gu{Y{*lU#LpYZa>1k~0I0DU!TK5U8B;k881xt{7%UkqHt%H2W|VehNMgumC}k*NP+&*| x;#`JIhCDDob@Fd!^T|2PI*cZhXEFyenooYs+=y3wElVU=mHT8lRy8n769AASAu9j? diff --git a/evidence/lab3-instances.txt b/evidence/lab3-instances.txt index 597a7b4f3e243db47aab570dc5c46524a1c053a3..b8504ad802b44aea2640702a8e7411c57b245ae0 100644 GIT binary patch literal 292 zcma#h^~@_SNz6-5)%8qKC{8UbO$D+Q^2<_-6by|Nia-LzCB+IQ8AbV}=@~#eRl&!} ziYr>(#L&br&D7K=$-ux+T}MIPG%?x0)WRq&(KHpzAJp=(Tq&8wC7F52B~}Uqyb{X= E0B_PuKmY&$ literal 592 zcmeH^!3x4K5Jca(;6LQni$Ys0h(~XNA0UW_)~4EvrET={)oB8HZ?CdsH#@VFgv|SO zWW}C41CB!Vg7rv+5oYOlCJK0OUab`@5HDdgg9pF diff --git a/evidence/lab3-load.txt b/evidence/lab3-load.txt index a68bd5d11a3f81c2907dd1cf80dee8414c58abc2..ebdbd77ffb12f0cc321a6db07045a0c35659f659 100644 GIT binary patch literal 512 zcmZ9J(N4oK3`O7f6;_|2wCkoZ_6tZLvG*z@hE=3-u@lfV?cZ^-Ar;<|d!2J_=d=K* zym_r2pu5TEZ{iP6#;H(QPlE2&6HV~^^sgj%VNKo z!7FZNU2~X;`_hM^e$(f$DRbJctJ`MvKgpYzo9M?}bJF$bf~Iw&m(}JnNEWv1Ojxxu zWvj}v>FP$`oC`HjL=~&Y3lb(|iy>;)0+zmz;o6kmDfnXz`(Z>%QSLC$AYd4^G6h{N r2u?*=)OA4PAfjIYCO9n|G!b&x0gbDx#d+}qIS-)P literal 1060 zcmZ{k(N4lZ5Jl(N#D8e|tXKqt=r5RPBJTug5hAomi^dp!T|IZVMOJAV>U8JMotZnc zet&)1shwEF6Wh`z_Qc;CzIt|c;CZ*gHueId0F&03*rx8Jw2ZTJXBW06`oZq)(MDJ+ zd?nAso}G2eSq@9Y$<`{Y6;@>nxFT|7*c-kS6$drQ_ezXB74Ou>{I;Ndd;#wmUj~!x z)G?@+OG~W7@35oHb-Q+WF}26_Y+zSGtmmJ)+^Q-k<43K@b$~3vOnJNpGrpGO3OiAs zzRH1hsr9hR8NDrt@!cMe``gzBeoaex8fAQj|0=ZACtZ9@mrdxQUKjoPL2bulwL_YY z*JR9e8>Zh)^V_yY)uhhSN8@lp4Q2?csiaR8ZK&a1#l+Q{?6-FpRIS}peV#M6yP)2P z?ak0l6U)JQ?Mrq@Gki}Ys@Xmm(|u{XWpi*%ZJKyW-n@<#pYGNIM9Et>LYZ|hJfrTIdKAugHs?gQyMsFV Iuds9PAC6R`v;Y7A diff --git a/evidence/lab3-migrations.txt b/evidence/lab3-migrations.txt index b14ab1f51411505b44493d0b88e1cb7dc747af1f..f92faf5d2f309c84cb3e0fcaebc0bda74adc7b48 100644 GIT binary patch literal 569 zcmbVK!AiqG5WVkL%t=~mLX+c4yp$Gtsc3r>DPc2B7qh!@cT*b>QNO4+p`hQe{UbLq zq7*OsZZph#^Y+aqNdlQ-x2S(kVa(yBX2)fx}M6F`qrf|Q+8e=<13CCh2Bvb-p5e{ zbZ#}5c^|HCPT>lLvN+x{ESqO{t0q-Z)R$FSw4!6Jm7ZqcSNUu2#EenD4};5QH$4x=TP+=k|^XsUS0GxVRrqGWa3?8VSX_X+s` DX3@Zw literal 1150 zcmchXTT8=05QWb}o&^6xo(I3gS;!znL^di?6x*!0B#(kKq|OdsqA1ZNhv+ZizR0t^@k&8k^_{ zFUG62?t?$}^R`hQy7tbrd+tHqBR0TdG^B7<*(HaK)$7Yq(RW?3F23k*V|t(?-@l}~ zrsf&vn2hoyA7jS0`fDo{Hr1pTFT92s6>5NeO9kp^%cH3)w|@(J=|j#k`H;KF8wEu2p_sP{vLSR-nm{gq1&KxrNDU;IV^-OA$7c)yh*&G1M7ZBJ0 delta 55 zcmaFF{*;~h{qFr6445WIFndgvW8#?Hz{CY&Gv_cQP4;HipUlD>!e~C(kjZ`W0%i#? GOA`PBXbM`^A&~LTS{$wHX&5xa|5!zOCNtpNk7LkG(vw${lr#>8 zq_VRbC)6fbH_m;K#*tNSXIp1>8R^8nru5}|NnH6IFeO;e02`c9pPl%)-9BNfSoZ=# z-0B*s)mSnV+IW3%0D3~bGx!uaR|suAnmCl#KHmiFW2A&$N^vU{k9R+fx4OL@x)9V+K428X})H~z^g+LO1dVwyhiVI|BLW`7A8b~EB-}ZZkpt3=#MzI|~`;9&J z&-cCE*^BkI`3Gmzao3=-u8G$_6AecimE8=HyPPPrN0JYuGAIa<%|_ z1dG%)_nHD&Nvx2Z+t3fyIq*M3{XG}oT*T$`=K$Q+XesV+OweD?s$x!6*{Q|o^ BfnWdt diff --git a/evidence/lab3-smoke.txt b/evidence/lab3-smoke.txt index 9155c94f2bba3373ba257ce54467ccbf29946ffc..fc20f9dd6a1de6ceaeb871ca2769099d4d648c29 100644 GIT binary patch literal 85 zcmV~$F%Ezr3QBZK4ffJ^6lP@_U`}dXt?<<1V$ov z&Z;+?YGmM{Yv^dLA6;gaTAaMN+8gvweRR57H<{IckqmZclC`fys&uc zXMe8AdcM<2lloE~6xontrK{`eW}UP5)=qRVO+wAs(KI|$FyM>JwoGQa+j%A-^+U`- zaGZ(c>)@Xo8Y%)KoN??4UP0frMlw7C|pxozWymH%1IN&SmcT?m6>% zt}#V`1qMH^IW`E{GpzMVoq*>MTdFP#)e+At_^kWbp^qL;h;ikLamIn)92!zY*kjDU z2pJOYc1^dO&4UgBLm@htuxi1feu5c$B+ueK`%~#o6fL4bZIe^gJyt~V2Qj5rjmquJ zCDCYjH0eg?6e`iAOSiMf3>PMTW8Qg@{+C{QbQO<+%F=nIU#2Qpu{sm)e906?(jE=3 Qk| 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() diff --git a/src/app.py b/src/app.py index a8da8af5..45f3a458 100644 --- a/src/app.py +++ b/src/app.py @@ -213,14 +213,16 @@ def _idempotency_key(request: Request) -> str: def current_user(request: Request, conn=Depends(get_conn)) -> Dict: + # Session validity is always checked against PostgreSQL; the cache may only + # serve the immutable user profile, never an access decision. 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: + user = sessions.cached_user(conn, user_id) + if user is None: raise ApiError(401, "unauthorized", "Сессия недействительна", challenge=BEARER_CHALLENGE) - return row + return user def _require_chat(conn, chat_id: str, user_id: str) -> str: @@ -287,7 +289,7 @@ def revoke_session( @app.get("/api/v1/users/me") def current_user_endpoint(user: Dict = Depends(current_user)) -> dict: - return repo.user_json(user) + return user # --------------------------------------------------------------------------- # diff --git a/src/sessions.py b/src/sessions.py index f1eee158..a810d62d 100644 --- a/src/sessions.py +++ b/src/sessions.py @@ -1,11 +1,17 @@ -"""Sessions: PostgreSQL is the source of truth, Valkey is a read-through cache. +"""Sessions and profile cache. -Design: - * ``sessions`` rows in PostgreSQL decide validity (``expires_at > now()``). - * Valkey caches ``session:{token_hash} -> user_id`` with a TTL equal to the - remaining session lifetime. - * If Valkey is unreachable the cache is bypassed transparently and the API - keeps authenticating from PostgreSQL (Valkey is never trusted as authority). +PostgreSQL is the source of truth for **session validity**. Every authenticated +request resolves its bearer token against the ``sessions`` table, so an +expired, revoked or unknown token is rejected immediately - even if Valkey was +unreachable at logout time and the invalidation could not be performed. The +cache is therefore never consulted to decide whether a session is valid, and a +stale or not-invalidated entry cannot resurrect a revoked session. + +Valkey is a best-effort read-through cache for **immutable user profiles** +(``user:{id}``). Profiles do not carry authorization state, so a failed cache +operation only costs one extra SQL query; it can never change an access +decision. This keeps Redis/Valkey genuinely useful without weakening the +contract. Every cache operation is bounded by a hard timeout and guarded by a tiny circuit breaker. A stopped Valkey container can make Docker DNS itself block @@ -16,9 +22,10 @@ from __future__ import annotations import concurrent.futures import datetime as dt +import json import logging import time -from typing import Optional, Tuple +from typing import Dict, Optional, Tuple import redis from redis.backoff import NoBackoff @@ -38,6 +45,10 @@ _OP_TIMEOUT = 0.5 _BREAKER_SECONDS = 5.0 _breaker_until = 0.0 +# User profiles are immutable in the mandatory API, so a short TTL is enough +# and bounds staleness to a value that cannot affect authorization. +_USER_CACHE_TTL = 300 + def _cache() -> Optional[redis.Redis]: global _client, _client_disabled @@ -73,32 +84,36 @@ def _guard(fn, *args): return None -def _key(token_hash: str) -> str: - return f"session:{token_hash}" - - -def _cache_get(token_hash: str) -> Optional[str]: +def _cache_get(key: str) -> Optional[str]: client = _cache() if client is None: return None - value = _guard(lambda: client.get(_key(token_hash))) + 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(token_hash: str, user_id: str, ttl_seconds: float) -> None: +def _cache_set(key: str, value: str, ttl_seconds: float) -> None: client = _cache() if client is None: return - _guard(lambda: client.set(_key(token_hash), user_id, ex=max(1, int(ttl_seconds)))) + _guard(lambda: client.set(key, value, ex=max(1, int(ttl_seconds)))) -def _cache_delete(token_hash: str) -> None: +def _cache_delete(key: str) -> None: client = _cache() if client is None: return - _guard(lambda: client.delete(_key(token_hash))) + _guard(lambda: client.delete(key)) + + +def _session_key(token_hash: str) -> str: + return f"session:{token_hash}" + + +def _user_key(user_id: str) -> str: + return f"user:{user_id}" def create(conn, user_id: str) -> Tuple[str, dt.datetime]: @@ -106,26 +121,44 @@ def create(conn, user_id: str) -> Tuple[str, dt.datetime]: 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) - _cache_set(hashed, user_id, settings.session_ttl_seconds) 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. + + Validity is always decided by PostgreSQL. The cache is *not* consulted here, + so revoking a session (DELETE row) takes effect immediately on every + replica regardless of the state of Valkey. + """ hashed = security.token_hash(token) - cached = _cache_get(hashed) - if cached is not None: - return cached row = repo.get_valid_session(conn, hashed) if row is None: + # Best-effort cleanup of any legacy session entry from older versions; + # never used for a decision. + _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(hashed, user_id, remaining) - return user_id + return str(row["user_id"]) def revoke(conn, token: str) -> None: hashed = security.token_hash(token) repo.delete_session(conn, hashed) - _cache_delete(hashed) + _cache_delete(_session_key(hashed)) + + +def cached_user(conn, user_id: str) -> Optional[Dict]: + """Read-through cache of an immutable user profile (never authorization).""" + key = _user_key(user_id) + raw = _cache_get(key) + if raw is not None: + try: + return json.loads(raw) + except ValueError: + pass + row = repo.get_user_by_id(conn, user_id) + if row is None: + return None + data = repo.user_json(row) + _cache_set(key, json.dumps(data, ensure_ascii=False), _USER_CACHE_TTL) + return data diff --git a/student-tests/test_session_revocation.py b/student-tests/test_session_revocation.py new file mode 100644 index 00000000..e5c56547 --- /dev/null +++ b/student-tests/test_session_revocation.py @@ -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 -- 2.54.0 From 0701e4dcc1aa68848266e0ae94d8fa935a2dd2e1 Mon Sep 17 00:00:00 2001 From: Ejur22 Date: Tue, 27 Oct 2026 20:29:33 +0300 Subject: [PATCH 3/3] =?UTF-8?q?=D0=98=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D0=B5=20=D0=BE=D1=88=D0=B8=D0=B1=D0=BE=D0=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 4 + REPORT.md | 24 +++-- compose.yaml | 2 + evidence/lab3-cache-invalidation.txt | 6 ++ evidence/lab3-compose-ps.txt | 12 +-- evidence/lab3-failover.txt | Bin 1390 -> 713 bytes evidence/lab3-instances.txt | 4 +- evidence/lab3-load.json | 10 +- evidence/lab3-load.txt | 10 +- evidence/lab3-migrations.txt | 9 +- evidence/lab3-persistence.txt | Bin 994 -> 514 bytes evidence/lab3-rolling.txt | 4 +- evidence/lab3-stats.txt | 10 +- evidence/lab3-student-tests.txt | 2 +- migrations/003_cache_invalidations.sql | 15 +++ src/app.py | 22 ++-- src/config.py | 6 ++ src/invalidation.py | 76 ++++++++++++++ src/repositories.py | 36 +++++++ src/sessions.py | 135 ++++++++++++++++--------- 20 files changed, 293 insertions(+), 94 deletions(-) create mode 100644 evidence/lab3-cache-invalidation.txt create mode 100644 migrations/003_cache_invalidations.sql create mode 100644 src/invalidation.py diff --git a/.env.example b/.env.example index 4531fc78..51d1a972 100644 --- a/.env.example +++ b/.env.example @@ -16,6 +16,10 @@ 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 diff --git a/REPORT.md b/REPORT.md index 6d20dadb..710bc898 100644 --- a/REPORT.md +++ b/REPORT.md @@ -64,7 +64,7 @@ docker compose down -v - **Динамический 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()`), поэтому отозванный токен даёт `401` на любой реплике немедленно. Valkey — read-through кэш **неизменяемого профиля пользователя** (`user:{id}`, TTL 300 c), он никогда не используется для решения о доступе. Поэтому сбой инвалидации при лежащем Valkey не может «воскресить» отозванную сессию (регрессионная проверка — `scripts/check-revocation.py`). Sticky session не используются: пользователь свободно попадает на любую реплику без повторного входа. +- **Сессии общие, отзыв корректен при сбое кэша.** Источник истины — 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 работает. @@ -78,6 +78,8 @@ docker compose down -v | `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`) | @@ -90,18 +92,19 @@ docker compose down -v | --- | --- | --- | --- | | Публичный 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 | чередование `4141f552b001`/`5ac0582fa5e1` (2 реплики), один токен | `evidence/lab3-instances.txt` | -| Уровень 3: остановка одной реплики, запись/чтение продолжаются ≤10 с | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 122 успешных записи, 0 ошибок, восстановление **1.083 с**; `api-6 Exited` при живом `api-5` | `evidence/lab3-failover.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` 2 строки | `evidence/lab3-migrations.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` | 133 RPS, 0 ошибок, p50/p95/p99 = 47/141/203 мс | `evidence/lab3-load.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 | ## Эксперименты и отказы @@ -112,19 +115,20 @@ docker compose down -v | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| Остановка одной API-реплики (`stop-one.sh`, TARGET = обслужившая реплика) | записи/чтения продолжаются, без дублей, токен жив | 122 записи за 15 с, 0 ошибок, цель не в последних ответах; `api-6 Exited` | **1.083 с**; потерь нет | -| То же для второй реплики (после восстановления первой) | то же | ≈120–140 записей, 0 ошибок; `api-2 Exited` | **≈1 с**; потерь нет | +| Остановка одной 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 → 6 c → 401 через обе реплики, POST отклонён | потерь нет; сессия отозвана в PostgreSQL | -| Нагрузка 133 RPS на 2 реплики | стабильная пропускная способность | 0 ошибок, p99 203 мс | n/a | +| 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` показывает ~74 MB RSS на реплику при лимите 256 MB. +Ограничения измерения: closed-loop генератор страдает coordinated omission и ограничен клиентом; числа — throughput HTTP-подтверждений, не точный счётчик COMMIT; единичный Docker-host не проверяет отказ узла. `docker stats` показывает ~150 MB RSS на реплику при лимите 256 MB. ## Ограничения и следующие шаги - Выдерживается: отказ **процесса** одной 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, поэтому ошибок нет. diff --git a/compose.yaml b/compose.yaml index e0c4b507..bb590c74 100644 --- a/compose.yaml +++ b/compose.yaml @@ -11,6 +11,8 @@ x-api-env: &api-env 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 diff --git a/evidence/lab3-cache-invalidation.txt b/evidence/lab3-cache-invalidation.txt new file mode 100644 index 00000000..c13a816b --- /dev/null +++ b/evidence/lab3-cache-invalidation.txt @@ -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 diff --git a/evidence/lab3-compose-ps.txt b/evidence/lab3-compose-ps.txt index 9dc0b6ef..65d0bb48 100644 --- a/evidence/lab3-compose-ps.txt +++ b/evidence/lab3-compose-ps.txt @@ -1,6 +1,6 @@ -NAME SERVICE STATUS PORTS -messenger-lab3-api-1 api Up 54 seconds (healthy) 8080/tcp -messenger-lab3-api-2 api Up 19 seconds (healthy) 8080/tcp -messenger-lab3-lb-1 lb Up 2 minutes (healthy) 80/tcp, 127.0.0.1:8080->8080/tcp -messenger-lab3-postgres-1 postgres Up 2 minutes (healthy) 5432/tcp -messenger-lab3-valkey-1 valkey Up 2 minutes (healthy) 6379/tcp +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 diff --git a/evidence/lab3-failover.txt b/evidence/lab3-failover.txt index b986759dfbeb74644d76022e2d8db1453b234521..523306dcd35e5b43a45eed662e7cf35e12b11f07 100644 GIT binary patch literal 713 zcma)&O>5jR5QgvjD~3JoLhZ(zk_{<7^bqK=5PCMUG;0gX8lf4xyOjR-jy7#tN>h3f z!;Bu@kG5@LHWPv%OLa0n(25y$Y_m_oZ&@f+6tU)U4{h6S9?xhO@o@k=r{Jv@c%eq3 z={=MeXpyuC@RCwSW^^C~W+m?+pqUEKXfq1eo3C5y8S{#+^O40wi`?~iqKw-IIJ|)^ zFIIPaT0-|Fd$p?j=JsAMMO!%|g0uS7{Y}~W%+h7FCCsH$C5rBPtnZHBHlIE`Jw5!g zT^wHJLBA$&ItHDx5z2t8cc|{`jWz|2?4(s% zniDZXVyFycKa2wABzln%pUWz}&ZVU|V6KAcZ!430bp(CkbArQNDXT<)-H0a0c-j9A zxW59AXKl#A?q(0oyBE+5^d}Pfs)5iKg{Fbo$3>fcU19cv#zbX)Oz@l1;rK5lEkFis US=pcC|EjJgOn6c7d3Y834u}Q#1ONa4 literal 1390 zcmb`GUyIXF5XI+tVZXzrPc4|bbyY;kgAam_g7{prY1)SVNl0$%7V*3LJ9C?*D=IE5 zVUydrXU@zyGn?mm*cF>9#Hx?kvZ%MsvFgIOFT1*p{mVW!ZPx6oX}_L?JkPJMKH0rh zR@%X$)wZ{l1%BUKYg>Mo{6!*5D>!Yfu_Lz~ku~SWHumA-9Egag^>?tIZ_Cq>)ALle z03AUE_>O#Qk8HUq;2P=+S$b9^YiieaWj|~L{?1uC?_yzd&*)(+=)CkQb1)VCHl9DS z_tbi2FL;m0J%CEM9?StnbNdcbD%E4c&&U{Z2IcB~PMzq;9jeq@!rz?vm+*8%BS>j3 z=_2`cB9c@!bh>!RoT2W<-r24Fbd_K1qkZL3*F)ujBRn{%35Zv2s>U9yD(}v*h4)!- zD_?}tL~HNt(qqk}_WUWB&zv+-%}uN=S%Lh@S$obY);YWU74H#-1>fX z4Y$IIQ@%Cui@D_+EQ2j@U$c2@oKw$B_gFcRn6SgP1!vCPE2&LerL9$sjCmH!|JGSs zI5T_Wj5-JVMon!)pbz<=T@^>LvDYccSH+V}o>1W}`320Xp#P?{OLBe8Y$tqY-o@kj zD`$ll+U@Ns>Q6rYucovG(JN~LN#F0$LF;Q& UKgYz5sNDKKp3W67BTujP3)Ecq>i_@% diff --git a/evidence/lab3-instances.txt b/evidence/lab3-instances.txt index b8504ad8..55a4b214 100644 --- a/evidence/lab3-instances.txt +++ b/evidence/lab3-instances.txt @@ -1,3 +1,3 @@ X-Instance-Id sequence over 12 requests through the LB: -['4141f552b001', '5ac0582fa5e1', '4141f552b001', '5ac0582fa5e1', '4141f552b001', '5ac0582fa5e1', '4141f552b001', '5ac0582fa5e1', '4141f552b001', '5ac0582fa5e1', '4141f552b001', '5ac0582fa5e1'] -distinct: ['4141f552b001', '5ac0582fa5e1'] +['2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901', '2f2d19f8e0e6', 'a17e74060901'] +distinct: ['2f2d19f8e0e6', 'a17e74060901'] diff --git a/evidence/lab3-load.json b/evidence/lab3-load.json index ebdbd77f..1d2ec8bf 100644 --- a/evidence/lab3-load.json +++ b/evidence/lab3-load.json @@ -2,16 +2,16 @@ "lab": 3, "workload": "closed-loop POST messages; no automatic retries", "requested_duration_seconds": 20.0, - "elapsed_seconds": 20.375, + "elapsed_seconds": 20.39, "concurrency": 8, - "successful_requests": 2712, + "successful_requests": 2317, "failed_requests": 0, "error_ratio": 0.0, - "successful_rps": 133.104, + "successful_rps": 113.634, "successful_latency_ms": { "p50": 47.0, - "p95": 141.0, - "p99": 203.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." } diff --git a/evidence/lab3-load.txt b/evidence/lab3-load.txt index ebdbd77f..1d2ec8bf 100644 --- a/evidence/lab3-load.txt +++ b/evidence/lab3-load.txt @@ -2,16 +2,16 @@ "lab": 3, "workload": "closed-loop POST messages; no automatic retries", "requested_duration_seconds": 20.0, - "elapsed_seconds": 20.375, + "elapsed_seconds": 20.39, "concurrency": 8, - "successful_requests": 2712, + "successful_requests": 2317, "failed_requests": 0, "error_ratio": 0.0, - "successful_rps": 133.104, + "successful_rps": 113.634, "successful_latency_ms": { "p50": 47.0, - "p95": 141.0, - "p99": 203.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." } diff --git a/evidence/lab3-migrations.txt b/evidence/lab3-migrations.txt index f92faf5d..f0a19ae0 100644 --- a/evidence/lab3-migrations.txt +++ b/evidence/lab3-migrations.txt @@ -1,15 +1,16 @@ === docker compose exec -T api python -m src.migrate === docker : INFO:messenger.migrate:migrations up to date -строка:1 знак:122 +строка: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 ---------------------- + version +----------------------------- 001_init.sql 002_idempotency.sql -(2 rows) + 003_cache_invalidations.sql +(3 rows) diff --git a/evidence/lab3-persistence.txt b/evidence/lab3-persistence.txt index 9799975a4486f2a2352bc17992d4954cd7a00f5d..b380c4bb0ef29bf66a1c3b5b1634e7a367b52f62 100644 GIT binary patch literal 514 zcma)&L2JV>42AFc6*{(uWQ@T!I&#=yu;ZZY2dK8%m^hZPl+gbB$=wbcZDAK9?Dsys z=f3Y@!jV8pw9Ql`h*EL{D{&=cmAhguShSO24SnA?Z%1;ohI9Zr<``U1`0X2*#}}w4 z@T_@OkU3|A2zgKjTsU}$gkwbrxk4&k^YOafZvKF(hst6u$7vtRWRpilz~pVU<@^SS z1Wp~i*Nx&h6C@%pU{gWm0<;8QD|L;<2hVP#V$3PC5M%+|t6lumJXf4*+H|1OM%+EL zm_z#npBWx&UQPyI4TMpL)4I8$eg3C5?%MmS(hZ!y-1=ScEwmmi>ka2+patVdr`z%` D9HX_W literal 994 zcmb_aL2AP=5S()$f6y^GB&C%0(4s>Qg&qr~4^VBjF>!1oDJJ=SXQTwuLm`16EUi|% zv$M0d)|#!`c$0igi@}H3#N@lmn^~+vGo*MI_~JrZ#`WA-Yp0V}?BP*ihlBbrD! z&Ow};oWEr38!dILzJw|khWS3DM%u*}GJ4N?(sLw2&9mrMda=+l^!G&C@Kv$G+!D3V zN~ud>I&zopiYPjYd7#f^6r0siXGLMnQPB%d(cudZv>dS-o{!A=q;0ZQRF*n*t~BFJ zHHVhiYaB4Y0{Q9Y$St`qaDN4^{tW%2MV&IoOL{1ZC+b%8J+G?1ZlTkdb=9N~f4aIH F{}<9~wio~a diff --git a/evidence/lab3-rolling.txt b/evidence/lab3-rolling.txt index 2d4e2d38..28f7c1cc 100644 --- a/evidence/lab3-rolling.txt +++ b/evidence/lab3-rolling.txt @@ -1,7 +1,7 @@ Running rolling update under continuous /health/live polling... -Replacing replica 72593ccf3b1f861c4d01c81aca3273b8149e00e93a8bad5db4c977a6702b553e ... -Replacing replica 1b3fb45af266d3eb0cbc1800b654b017f168a34d796f2d049b719b4c794a34ab ... +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 diff --git a/evidence/lab3-stats.txt b/evidence/lab3-stats.txt index 44b1a4ee..bbc2baaa 100644 --- a/evidence/lab3-stats.txt +++ b/evidence/lab3-stats.txt @@ -1,6 +1,6 @@ NAME CPU % MEM USAGE / LIMIT -messenger-lab3-api-6 9.50% 74.27MiB / 256MiB -messenger-lab3-api-5 0.13% 74.25MiB / 256MiB -messenger-lab3-lb-1 0.00% 15.35MiB / 128MiB -messenger-lab3-postgres-1 0.18% 58.18MiB / 512MiB -messenger-lab3-valkey-1 0.27% 7.98MiB / 128MiB +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 diff --git a/evidence/lab3-student-tests.txt b/evidence/lab3-student-tests.txt index 6f94e80f..ddfd7e06 100644 --- a/evidence/lab3-student-tests.txt +++ b/evidence/lab3-student-tests.txt @@ -1,2 +1,2 @@ ..................................... [100%] -37 passed in 10.82s +37 passed in 9.10s diff --git a/migrations/003_cache_invalidations.sql b/migrations/003_cache_invalidations.sql new file mode 100644 index 00000000..3b7d274c --- /dev/null +++ b/migrations/003_cache_invalidations.sql @@ -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); diff --git a/src/app.py b/src/app.py index 45f3a458..8ba26acc 100644 --- a/src/app.py +++ b/src/app.py @@ -12,6 +12,7 @@ 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 @@ -22,6 +23,7 @@ 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 @@ -49,12 +51,22 @@ _STATUS_CODES = { 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, ) @@ -213,16 +225,14 @@ def _idempotency_key(request: Request) -> str: def current_user(request: Request, conn=Depends(get_conn)) -> Dict: - # Session validity is always checked against PostgreSQL; the cache may only - # serve the immutable user profile, never an access decision. token = _bearer_token(request) user_id = sessions.resolve(conn, token) if user_id is None: raise ApiError(401, "unauthorized", "Сессия недействительна", challenge=BEARER_CHALLENGE) - user = sessions.cached_user(conn, user_id) - if user is None: + row = repo.get_user_by_id(conn, user_id) + if row is None: raise ApiError(401, "unauthorized", "Сессия недействительна", challenge=BEARER_CHALLENGE) - return user + return row def _require_chat(conn, chat_id: str, user_id: str) -> str: @@ -289,7 +299,7 @@ def revoke_session( @app.get("/api/v1/users/me") def current_user_endpoint(user: Dict = Depends(current_user)) -> dict: - return user + return repo.user_json(user) # --------------------------------------------------------------------------- # diff --git a/src/config.py b/src/config.py index eadb4574..22989c95 100644 --- a/src/config.py +++ b/src/config.py @@ -28,6 +28,8 @@ class Settings: 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 @@ -48,6 +50,10 @@ def load_settings() -> Settings: 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"), diff --git a/src/invalidation.py b/src/invalidation.py new file mode 100644 index 00000000..aa534ac1 --- /dev/null +++ b/src/invalidation.py @@ -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 diff --git a/src/repositories.py b/src/repositories.py index 5a1ba105..d4a40a5d 100644 --- a/src/repositories.py +++ b/src/repositories.py @@ -319,3 +319,39 @@ def purge_expired_sessions(conn) -> int: "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),), + ) diff --git a/src/sessions.py b/src/sessions.py index a810d62d..be6f0376 100644 --- a/src/sessions.py +++ b/src/sessions.py @@ -1,22 +1,23 @@ -"""Sessions and profile cache. +"""Sessions: PostgreSQL is the source of truth, Valkey is a shared session cache. -PostgreSQL is the source of truth for **session validity**. Every authenticated -request resolves its bearer token against the ``sessions`` table, so an -expired, revoked or unknown token is rejected immediately - even if Valkey was -unreachable at logout time and the invalidation could not be performed. The -cache is therefore never consulted to decide whether a session is valid, and a -stale or not-invalidated entry cannot resurrect a revoked session. +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. -Valkey is a best-effort read-through cache for **immutable user profiles** -(``user:{id}``). Profiles do not carry authorization state, so a failed cache -operation only costs one extra SQL query; it can never change an access -decision. This keeps Redis/Valkey genuinely useful without weakening the -contract. - -Every cache operation is bounded by a hard timeout and guarded by a tiny -circuit breaker. A stopped Valkey container can make Docker DNS itself block -for several seconds; without this guard a cache outage would stall request -handling. On any failure the breaker skips the cache for a few seconds. +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 @@ -25,7 +26,7 @@ import datetime as dt import json import logging import time -from typing import Dict, Optional, Tuple +from typing import Optional, Tuple import redis from redis.backoff import NoBackoff @@ -45,10 +46,6 @@ _OP_TIMEOUT = 0.5 _BREAKER_SECONDS = 5.0 _breaker_until = 0.0 -# User profiles are immutable in the mandatory API, so a short TTL is enough -# and bounds staleness to a value that cannot affect authorization. -_USER_CACHE_TTL = 300 - def _cache() -> Optional[redis.Redis]: global _client, _client_disabled @@ -72,7 +69,7 @@ def _cache() -> Optional[redis.Redis]: def _guard(fn, *args): - """Run a cache operation with a hard deadline and a small breaker.""" + """Run a request-path cache operation with a deadline and a small breaker.""" global _breaker_until if time.monotonic() < _breaker_until: return None @@ -84,6 +81,10 @@ def _guard(fn, *args): 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: @@ -108,12 +109,28 @@ def _cache_delete(key: str) -> None: _guard(lambda: client.delete(key)) -def _session_key(token_hash: str) -> str: - return f"session:{token_hash}" +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 _user_key(user_id: str) -> str: - return f"user:{user_id}" +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]: @@ -121,44 +138,66 @@ def create(conn, user_id: str) -> Tuple[str, dt.datetime]: 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. - Validity is always decided by PostgreSQL. The cache is *not* consulted here, - so revoking a session (DELETE row) takes effect immediately on every - replica regardless of the state of Valkey. + 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: - # Best-effort cleanup of any legacy session entry from older versions; - # never used for a decision. + # Remove any legacy/stale entry; revocation is already authoritative. _cache_delete(_session_key(hashed)) return None - return str(row["user_id"]) + + 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 cached_user(conn, user_id: str) -> Optional[Dict]: - """Read-through cache of an immutable user profile (never authorization).""" - key = _user_key(user_id) - raw = _cache_get(key) - if raw is not None: - try: - return json.loads(raw) - except ValueError: - pass - row = repo.get_user_by_id(conn, user_id) - if row is None: - return None - data = repo.user_json(row) - _cache_set(key, json.dumps(data, ensure_ascii=False), _USER_CACHE_TTL) - return data +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 -- 2.54.0