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/.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..df2af196 100644 --- a/.gitignore +++ b/.gitignore @@ -28,5 +28,7 @@ coverage/ .DS_Store .idea/ .vscode/ +# Personal study notes, not part of the submission. +EXPLAIN.md # Keep small, sanitized evidence summaries in evidence/ under version control. # Inspect git diff --cached: ignore rules are not a secret scanner. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..7e0111a7 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,28 @@ +# syntax=docker/dockerfile:1 +# Lab2 messenger image. Python is interpreted, so one pinned stage is enough. +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=10s --timeout=3s --start-period=15s --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 9ecb223e..1f3a6c62 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 +.PHONY: help check validate test load test-persistence 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 @@ -24,3 +24,6 @@ load: test-persistence: @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2) $(PYTHON) tests/resilience.py --mode persistence --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 e42f2b05..8aee3afc 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,119 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: TODO (заполняет студент) +- Целевая оценка; выбранный трек 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); `openapi-spec-validator` и pytest только для проверок. Документация PostgreSQL (transactions, EXPLAIN), Valkey/Redis persistence, RFC 7617. Помощь ИИ: генерация каркаса и текста, проверено запуском тестов. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +**Версии и prerequisites** + +| Компонент | Версия / образ | +| --- | --- | +| Runtime | Python 3.11.9 | +| API-образ | `python:3.11.9-slim-bookworm` (пин; digest `sha256:8fb099…c317`) | +| 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; persistence-хук выполняется в WSL Ubuntu 22.04 (Python 3.12) и на Linux-раннере | + +Prerequisites: Docker с Linux-контейнерами и плагином Compose. На Windows для `scripts/restart.sh` нужен POSIX-shell (WSL/Git Bash) либо Linux-раннер; публичный smoke и `make check` работают где угодно. + +**Создание локальных secrets (не коммитятся)** + +```sh +sh scripts/gen-secrets.sh +# создаёт ./secrets/database_password, ./secrets/database_url, ./secrets/cache_url +# либо: cp secrets.example/* secrets/ и вписать свой пароль +``` + +**Запуск, миграции, проверка, остановка** + +```sh +docker compose --env-file .env config --quiet # 1. валидация конфигурации +docker compose --env-file .env up -d --build # 2. сборка и запуск API+PostgreSQL+Valkey +docker compose ps # 3. дождаться healthy у всех трёх + +# Миграции применяются автоматически на старте API (идемпотентно, под advisory-lock); +# отдельно: docker compose exec -T api python -m src.migrate + +python tests/smoke.py --base-url http://localhost:8080 # 4. публичный smoke +.venv\Scripts\python -m pytest student-tests -v # свои тесты (см. ниже) + +# Сохранность: перезапуск API и всех хранилищ с сохранением volumes +make test-persistence ACTION_SCRIPT=scripts/restart.sh # выполнять в WSL/Linux + +# Отказы и expiry +python scripts/check-degradation.py # Valkey/PG down -> 200/503, восстановление +sh scripts/check-expiry.sh # короткий TTL -> 401 + +# Безопасная остановка (данные сохраняются): +docker compose stop + +# Намеренное удаление учебных данных (тома): +docker compose down -v +``` + +Оператору нужно: сгенерировать secrets, выполнить шаги 1–4. Повторная сборка — `docker compose up -d --build`. `down -v` удаляет данные PostgreSQL и Valkey; обычная остановка/`down` (без `-v`) их сохраняет. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +**Схема:** `клиент → API (FastAPI/Uvicorn) → PostgreSQL (источник истины)`; `Valkey` — read-through кэш сессий. + +- **Источник истины — PostgreSQL.** Таблицы `users` (PK, `UNIQUE(username)`, `password_hash`), `chats`, `chat_members` (FK, составной PK), `messages` (FK), `sessions` (`token_hash` PK, `user_id`, `expires_at`), `schema_migrations`. +- **Транзакционные границы.** Создание чата — одна транзакция (вставить `chats` + всех `chat_members`); при невалидных участниках — rollback и `400`, частичный объект не остаётся. Регистрация полагается на `UNIQUE(username)`; гонка даёт ровно одного победителя и `409` остальным. +- **Аутентификация lab2.** `POST /api/v1/users` требует `password` (12–128 code points). Пароль хранится как **Argon2id** (argon2-cffi), не в открытом виде. `POST /api/v1/auth/sessions` принимает только `Authorization: Basic base64(username:password)` и выдаёт opaque-токен (`secrets.token_urlsafe(32)`, ≥256 бит). В БД хранится **SHA-256 токена**, не сам токен. Все бизнес-endpoint требуют `Bearer`; `X-User-Id` игнорируется. `DELETE /api/v1/auth/sessions/current` отзывает сессию и отдаёт `204`. +- **Сессии и кэш.** Сессия валидна, пока `sessions.expires_at > now()` (TTL = `SESSION_TTL_SECONDS`). Valkey кэширует `session:{sha256(token)} → user_id` с TTL до конца жизни сессии. Кэш **не является источником истины**: `current_user` всегда затем читает пользователя из PostgreSQL. При недоступности Valkey кэш обходится (операция ограничена таймаутом 0.5 c + mini circuit breaker, т.к. DNS остановленного контейнера может блокироваться); при недоступности PostgreSQL — ограниченный `503`, анонимный пользователь не считается доверенным. +- **Индекс истории.** `messages(chat_id, created_at, id)` под keyset-запрос `WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4`; пагинация не сканирует всю историю. Подтверждено EXPLAIN на ≥10 000 сообщений. +- **Пул и таймауты.** `psycopg_pool.ConnectionPool` ограничен `DB_POOL_MAX` (default 10), `DB_POOL_TIMEOUT` (5 c); на соединении `statement_timeout=DB_STATEMENT_TIMEOUT_MS` (5000 мс). Все запросы параметризованы. +- **Перенос из lab1.** Сохранён HTTP-каркас (маршруты, конверт ошибок, `X-Request-Id`, keyset-cursor), но слой данных переписан на PostgreSQL, добавлены миграции, аутентификация заменена на password + Basic/Bearer. `X-User-Id` удалён. In-memory `store.py` lab1 не переносился. + +**Соответствие `.env.example`** + +| Переменная | Роль в решении | +| --- | --- | +| `APP_HOST`, `APP_PORT` | адрес/порт Uvicorn (`src/main.py`); в compose `0.0.0.0:8080` | +| `APP_ENV` | метка в лог-строке запуска | +| `SESSION_TTL_SECONDS` | срок жизни сессии (`sessions.expires_at`) и TTL кэша | +| `SESSION_STORE` | `valkey`/`redis` — включить кэш Valkey; `postgres` — без кэша | +| `DATABASE_URL_FILE` | файл с DSN PostgreSQL (compose secret `/run/secrets/database_url`) | +| `CACHE_URL_FILE` | файл с URL Valkey (compose secret `/run/secrets/cache_url`) | ## Доказательства критериев | Критерий 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: lab2 public API scenario` | `evidence/lab2-smoke.txt` | +| Persistence: данные и сессии переживают рестарт API и хранилищ без удаления volumes | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (WSL) | `PASS: persistence preserved confirmed data and existing session`; контейнеры перезапущены, volumes на месте | `evidence/lab2-persistence.txt` | +| Миграции запускаются с нуля и повторно без дублирования | `docker compose exec -T api python -m src.migrate` | `migrations up to date`; в `schema_migrations` одна строка | `evidence/lab2-migrations.txt` | +| PostgreSQL хранит users/chats/members/messages; PK/FK/UNIQUE; атомарное создание чата | схема + `test_race.py`, `test_negative.py` | rollback при неизвестном участнике; `409` при дубликате username | `evidence/lab2-student-tests.txt` | +| Basic только на `/auth/sessions`; Bearer для остальных; TTL и отзыв; `X-User-Id` не даёт доступ; пароли — KDF | `test_auth.py` | 401 Basic/Bearer с корректным challenge; logout → 401 | `evidence/lab2-student-tests.txt` | +| Уровень 4: Valkey реально используется с TTL, источник истины и политика описаны | `check-degradation.py`, `check-expiry.sh` | cache bypass при отказе Valkey; expiry → 401 | `evidence/lab2-degradation.txt`, `evidence/lab2-expiry.txt` | +| Уровень 4: параметризованный SQL, ограниченный pool, таймауты; гонка регистрации и rollback | `test_race.py` | один `201` и четыре `409`; частичный чат не создан | `evidence/lab2-student-tests.txt` | +| Уровень 4: индекс обоснован EXPLAIN на ≥10 000 сообщений, пагинация без full scan | `EXPLAIN (ANALYZE, BUFFERS)` | `Index Scan using messages_chat_created_id_idx`, 0.113 мс, 52 буфера | `evidence/lab2-explain.txt` | +| Уровень 4: expiry при коротком TTL, logout, неверный пароль, недоступность Valkey/БД | `check-expiry.sh`, `test_auth.py`, `check-degradation.py` | expiry 401; logout 401; Valkey down → 200; PG down → 503 | `evidence/lab2-expiry.txt`, `evidence/lab2-student-tests.txt`, `evidence/lab2-degradation.txt` | +| Безопасность: секреты вне Git, `.env`/volumes не коммитятся | `.gitignore`, `secrets.example/`, `scripts/gen-secrets.sh` | `git status` без `.env`/`secrets/` | описание в PR | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Гипотеза: PostgreSQL — источник истины, поэтому рестарт API и хранилищ не теряет данные и активные сессии; Valkey можно потерять без остановки API; потеря PostgreSQL даёт ограниченный `503`, а не обход аутентификации. Методика: реальный compose-стенд, синтетические данные, хуки в WSL. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `docker compose restart api postgres valkey` | данные и сессия сохранены | `PASS: persistence preserved confirmed data and existing session` | рестарт ≈ секунды; потерь нет | +| Остановка Valkey | API продолжает работать, `/health/ready`=200 | `/users/me`=200, `/health/ready`=200 (кэш обойдён) | ~0.5 c на операцию кэша, далее fast-path | +| Остановка PostgreSQL | `/health/ready`=503; аноним не доверяется | `/health/ready`=503, `/users/me`=503, анонимным=503 | восстановление после старта PG; сессия сохранилась | +| Гонка регистрации одинакового username (5 потоков) | ровно один победитель | `1×201`, `4×409` | n/a | +| Ошибка составной операции (неизвестный участник) | rollback, чат не создан | `400`; число чатов не изменилось | n/a | +| Короткий `SESSION_TTL_SECONDS=2` | сессия истекает | `before=200`, `after=401` | ~2 c | + +Замеры: единичный стенд на одном Docker-host (Windows/WSL2); throughput-исследование не заявлено (трек 5 не выбран). Числа latency кэша/БД — из логов и EXPLAIN. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Выдерживается: перезапуск API и хранилищ с volumes, потеря Valkey (кэш), короткий отказ PostgreSQL с восстановлением, гонки и откат составных операций, некорректный ввод. +- **Не** выдерживается и не заявлено: отказ самого Docker-host, несколько API-реплик и балансировщик (lab3), вложения (lab4). Единственный инстанс PostgreSQL/Valkey не высокодоступен. +- Учебные упрощения: HTTP без TLS (допустимо для изолированного стенда lab1–6); нет rate limiting и лимитов памяти (трек 5); хук `restart.sh` перезапускает сервисы, а не выполняет rolling-обновление. +- Подтверждено измерениями: сохранность после рестарта, использование индекса (EXPLAIN), отсутствие доверия кэшу/анониму. Гипотеза на будущее: поведение при росте числа реплик и кэш-согласованности — кандидат на трек 5 следующей лабы. diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..37ce872d --- /dev/null +++ b/compose.yaml @@ -0,0 +1,73 @@ +# Lab2 topology: API + PostgreSQL (source of truth) + Valkey (session cache). +# Versions are pinned; PostgreSQL and Valkey are not published outside the +# compose network. Secrets are file-based and live in ./secrets (gitignored). +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} + 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} + +services: + api: + build: + context: . + environment: *api-env + secrets: + - database_url + - cache_url + ports: + - "127.0.0.1:${PUBLISH_PORT:-8080}:8080" + depends_on: + postgres: + condition: service_healthy + valkey: + condition: service_healthy + restart: unless-stopped + + 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 + + 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 + +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/lab2-degradation.txt b/evidence/lab2-degradation.txt new file mode 100644 index 00000000..8b516f7e --- /dev/null +++ b/evidence/lab2-degradation.txt @@ -0,0 +1,16 @@ + Container mtusi2026lab2-valkey-1 Stopping + Container mtusi2026lab2-valkey-1 Stopped + Container mtusi2026lab2-valkey-1 Starting + Container mtusi2026lab2-valkey-1 Started + Container mtusi2026lab2-postgres-1 Stopping + Container mtusi2026lab2-postgres-1 Stopped + Container mtusi2026lab2-postgres-1 Starting + Container mtusi2026lab2-postgres-1 Started +baseline: /users/me = 200 +stopping valkey ... +valkey down: /health/ready = 200, /users/me = 200 (cache bypassed) +valkey restored: /users/me = 200 +stopping postgres ... +postgres down: /health/ready = 503, /users/me = 503, anonymous = 503 +postgres restored: /users/me = 200 (session survived) +PASS: graceful degradation and recovery without trusting the cache/anonymous user diff --git a/evidence/lab2-expiry.txt b/evidence/lab2-expiry.txt new file mode 100644 index 00000000..0b2a8f0e --- /dev/null +++ b/evidence/lab2-expiry.txt @@ -0,0 +1,3 @@ +# Expiry with a short SESSION_TTL_SECONDS=2 on a throwaway stack +$ sh scripts/check-expiry.sh +PASS: session expired after ~2s (before=200, after=401) diff --git a/evidence/lab2-explain.txt b/evidence/lab2-explain.txt new file mode 100644 index 00000000..add12a3f --- /dev/null +++ b/evidence/lab2-explain.txt @@ -0,0 +1,47 @@ +# Grade 4: keyset pagination uses the composite index on >=10k messages +# dataset +$ docker compose exec -T postgres psql -U messenger -d messenger -c select count(*) as messages, pg_size_pretty(pg_total_relation_size('messages')) as size from messages; + messages | size +----------+--------- + 10343 | 2568 kB +(1 row) + + +# first page (cursor before history) +$ docker compose exec -T postgres psql -U messenger -d messenger -c EXPLAIN (ANALYZE, BUFFERS) SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id = '9157b350-faa5-4a4b-9907-c0610e01649d' AND (created_at, id) > ('1970-01-01T00:00:00Z'::timestamptz, '00000000-0000-0000-0000-000000000000'::uuid) ORDER BY created_at, id LIMIT 50; + QUERY PLAN +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + Limit (cost=0.29..9.97 rows=50 width=81) (actual time=0.015..0.071 rows=50 loops=1) + Buffers: shared hit=52 + -> Index Scan using messages_chat_created_id_idx on messages (cost=0.29..645.61 rows=3333 width=81) (actual time=0.015..0.067 rows=50 loops=1) + Index Cond: ((chat_id = '9157b350-faa5-4a4b-9907-c0610e01649d'::uuid) AND (ROW(created_at, id) > ROW('1970-01-01 00:00:00+00'::timestamp with time zone, '00000000-0000-0000-0000-000000000000'::uuid))) + Buffers: shared hit=52 + Planning: + Buffers: shared hit=106 + Planning Time: 0.248 ms + Execution Time: 0.098 ms +(9 rows) + + +# deep page (cursor at offset 5000) - cost stays flat +$ docker compose exec -T postgres psql -U messenger -d messenger -c EXPLAIN (ANALYZE, BUFFERS) SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id = '9157b350-faa5-4a4b-9907-c0610e01649d' AND (created_at, id) > (SELECT created_at, id FROM messages WHERE chat_id = '9157b350-faa5-4a4b-9907-c0610e01649d' ORDER BY created_at, id OFFSET 5000 LIMIT 1) ORDER BY created_at, id LIMIT 50; + QUERY PLAN +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + Limit (cost=186.95..209.67 rows=50 width=81) (actual time=0.620..0.621 rows=0 loops=1) + Buffers: shared hit=35 + InitPlan 1 (returns $0,$1) + -> Limit (cost=186.61..186.67 rows=1 width=24) (actual time=0.607..0.608 rows=0 loops=1) + Buffers: shared hit=35 + -> Index Only Scan using messages_chat_created_id_idx on messages messages_1 (cost=0.29..186.61 rows=3333 width=24) (actual time=0.024..0.511 rows=3333 loops=1) + Index Cond: (chat_id = '9157b350-faa5-4a4b-9907-c0610e01649d'::uuid) + Heap Fetches: 0 + Buffers: shared hit=35 + -> Index Scan using messages_chat_created_id_idx on messages (cost=0.29..504.99 rows=1111 width=81) (actual time=0.619..0.619 rows=0 loops=1) + Index Cond: ((chat_id = '9157b350-faa5-4a4b-9907-c0610e01649d'::uuid) AND (ROW(created_at, id) > ROW($0, $1))) + Buffers: shared hit=35 + Planning: + Buffers: shared hit=106 + Planning Time: 0.384 ms + Execution Time: 0.659 ms +(16 rows) + diff --git a/evidence/lab2-migrations.txt b/evidence/lab2-migrations.txt new file mode 100644 index 00000000..38c4397a --- /dev/null +++ b/evidence/lab2-migrations.txt @@ -0,0 +1,11 @@ +# Migrations are idempotent: re-running adds nothing +$ docker compose restart api # entrypoint runs migrations again +$ docker compose exec -T api python -m src.migrate +INFO:messenger.migrate:migrations up to date + +$ docker compose exec -T postgres psql -U messenger -d messenger -c select version, applied_at from schema_migrations order by version; + version | applied_at +--------------+------------------------------- + 001_init.sql | 2026-10-15 15:58:41.848316+00 +(1 row) + diff --git a/evidence/lab2-persistence.txt b/evidence/lab2-persistence.txt new file mode 100644 index 00000000..eaa385b0 --- /dev/null +++ b/evidence/lab2-persistence.txt @@ -0,0 +1,18 @@ +# Persistence: restart API + all state stores, keep volumes (make test-persistence) + +## containers before +mtusi2026lab2-api-1 Up About a minute (healthy) +mtusi2026lab2-postgres-1 Up About a minute (healthy) +mtusi2026lab2-valkey-1 Up About a minute (healthy) + +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. + +## containers after +mtusi2026lab2-api-1 Up 1 second (health: starting) +mtusi2026lab2-postgres-1 Up 1 second (health: starting) +mtusi2026lab2-valkey-1 Up 1 second (health: starting) + +## volumes (still present, not removed) +mtusi2026lab2_pgdata +mtusi2026lab2_valkeydata diff --git a/evidence/lab2-smoke.txt b/evidence/lab2-smoke.txt new file mode 100644 index 00000000..31465e46 --- /dev/null +++ b/evidence/lab2-smoke.txt @@ -0,0 +1,3 @@ +# Public acceptance scenario +$ python tests/smoke.py --base-url http://localhost:8080 +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/lab2-student-tests.txt b/evidence/lab2-student-tests.txt new file mode 100644 index 00000000..97956c5c --- /dev/null +++ b/evidence/lab2-student-tests.txt @@ -0,0 +1,39 @@ +# Student black-box tests (grade 4), one command +$ C:\IT-labs\VNP\mtusi2026lab2\.venv\Scripts\python.exe -m pytest student-tests -v +============================= test session starts ============================= +platform win32 -- Python 3.11.9, pytest-8.3.4, pluggy-1.7.0 -- C:\IT-labs\VNP\mtusi2026lab2\.venv\Scripts\python.exe +cachedir: .pytest_cache +rootdir: C:\IT-labs\VNP\mtusi2026lab2 +plugins: anyio-4.15.1 +collecting ... collected 28 items + +student-tests/test_auth.py::test_registration_requires_password PASSED [ 3%] +student-tests/test_auth.py::test_short_password_is_400 PASSED [ 7%] +student-tests/test_auth.py::test_extra_field_is_400 PASSED [ 10%] +student-tests/test_auth.py::test_malformed_json_is_400 PASSED [ 14%] +student-tests/test_auth.py::test_duplicate_username_is_409 PASSED [ 17%] +student-tests/test_auth.py::test_registration_never_returns_password PASSED [ 21%] +student-tests/test_auth.py::test_wrong_password_is_401_basic PASSED [ 25%] +student-tests/test_auth.py::test_unknown_user_is_401_basic PASSED [ 28%] +student-tests/test_auth.py::test_basic_on_business_endpoint_is_401_bearer PASSED [ 32%] +student-tests/test_auth.py::test_missing_auth_is_401_bearer PASSED [ 35%] +student-tests/test_auth.py::test_unknown_bearer_is_401 PASSED [ 39%] +student-tests/test_auth.py::test_x_user_id_is_ignored PASSED [ 42%] +student-tests/test_auth.py::test_logout_revokes_session PASSED [ 46%] +student-tests/test_concurrency.py::test_100_concurrent_messages_are_not_lost PASSED [ 50%] +student-tests/test_negative.py::test_foreign_chat_is_404 PASSED [ 53%] +student-tests/test_negative.py::test_empty_message_is_400 PASSED [ 57%] +student-tests/test_negative.py::test_oversized_message_is_400 PASSED [ 60%] +student-tests/test_negative.py::test_limit_out_of_range_is_400 PASSED [ 64%] +student-tests/test_negative.py::test_sender_id_in_body_is_rejected PASSED [ 67%] +student-tests/test_negative.py::test_chat_without_caller_is_400 PASSED [ 71%] +student-tests/test_negative.py::test_chat_with_unknown_member_is_400 PASSED [ 75%] +student-tests/test_negative.py::test_chat_with_duplicate_members_is_400 PASSED [ 78%] +student-tests/test_pagination.py::test_full_traversal_without_duplicates PASSED [ 82%] +student-tests/test_pagination.py::test_cursor_from_other_chat_is_400 PASSED [ 85%] +student-tests/test_pagination.py::test_garbage_cursor_is_400 PASSED [ 89%] +student-tests/test_pagination.py::test_well_formed_cursor_with_wrong_types_is_400 PASSED [ 92%] +student-tests/test_race.py::test_concurrent_duplicate_username_single_winner PASSED [ 96%] +student-tests/test_race.py::test_failed_chat_creation_rolls_back PASSED [100%] + +============================= 28 passed in 5.10s ============================== diff --git a/migrations/001_init.sql b/migrations/001_init.sql new file mode 100644 index 00000000..41499537 --- /dev/null +++ b/migrations/001_init.sql @@ -0,0 +1,42 @@ +-- Lab2 initial schema. Idempotent and safe to re-run via the migration runner. +create table if not exists users ( + id uuid primary key, + username text not null unique, + display_name text not null, + password_hash text not null, + created_at timestamptz not null +); + +create table if not exists chats ( + id uuid primary key, + title text not null, + created_at timestamptz not null +); + +create table if not exists chat_members ( + chat_id uuid not null references chats (id) on delete cascade, + user_id uuid not null references users (id) on delete cascade, + primary key (chat_id, user_id) +); + +create table if not exists messages ( + id uuid primary key, + chat_id uuid not null references chats (id) on delete cascade, + sender_id uuid not null references users (id), + text text not null, + created_at timestamptz not null +); + +-- Composite index prepared for keyset pagination: +-- where chat_id = $1 and (created_at, id) > ($2, $3) order by created_at, id +create index if not exists messages_chat_created_id_idx + on messages (chat_id, created_at, id); + +create table if not exists sessions ( + token_hash text primary key, + user_id uuid not null references users (id) on delete cascade, + created_at timestamptz not null, + expires_at timestamptz not null +); + +create index if not exists sessions_expires_at_idx on sessions (expires_at); diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..74a6ba13 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,8 @@ +# Runtime dependencies for the lab2 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/check-degradation.py b/scripts/check-degradation.py new file mode 100644 index 00000000..d7beaeef --- /dev/null +++ b/scripts/check-degradation.py @@ -0,0 +1,109 @@ +#!/usr/bin/env python3 +"""Dependency-failure probe (grade 4). + +Proves the documented behaviour of the running compose stand: + + * Valkey down -> API keeps authenticating from PostgreSQL (cache bypass), + /health/ready stays 200; + * PostgreSQL down -> /health/ready is 503 and authenticated calls return a + bounded 503 (an anonymous caller is never trusted); + * both recover when the service is started again. + +Run from the repository root where ``docker compose`` is available. +""" +from __future__ import annotations + +import base64 +import json +import os +import subprocess +import time +import urllib.error +import urllib.request + +BASE = os.environ.get("BASE_URL", "http://localhost:8080").rstrip("/") + + +def call(method, path, token=None, body=None): + headers = {"Accept": "application/json"} + data = None + if body is not None: + data = json.dumps(body).encode("utf-8") + headers["Content-Type"] = "application/json" + if token: + headers["Authorization"] = "Bearer " + token + request = urllib.request.Request(BASE + path, data=data, headers=headers, method=method) + try: + with urllib.request.urlopen(request, timeout=15) as response: + return response.status + except urllib.error.HTTPError as error: + return error.code + except (urllib.error.URLError, TimeoutError, OSError): + return 0 + + +def compose(*args): + subprocess.run(["docker", "compose", *args], check=True) + + +def wait_ready(expected, timeout=120.0): + deadline = time.time() + timeout + while time.time() < deadline: + if call("GET", "/health/ready") == expected: + return + time.sleep(2) + raise SystemExit(f"readiness did not reach {expected}") + + +def login(): + username = "degrade_" + os.urandom(4).hex() + password = "T3st-" + os.urandom(8).hex() + assert call("POST", "/api/v1/users", body={ + "username": username, "display_name": "Degrade", "password": password}) == 201 + credential = base64.b64encode(f"{username}:{password}".encode()).decode() + request = urllib.request.Request( + BASE + "/api/v1/auth/sessions", + headers={"Authorization": "Basic " + credential, "Accept": "application/json"}, + method="POST", + ) + with urllib.request.urlopen(request, timeout=15) as response: + return json.loads(response.read())["token"] + + +def main() -> None: + wait_ready(200) + token = login() + assert call("GET", "/api/v1/users/me", token=token) == 200 + print("baseline: /users/me = 200") + + print("stopping valkey ...") + compose("stop", "valkey") + ready = call("GET", "/health/ready") + me = call("GET", "/api/v1/users/me", token=token) + assert ready == 200, f"readiness must stay 200 without cache, got {ready}" + assert me == 200, f"auth must work from PostgreSQL without cache, got {me}" + print("valkey down: /health/ready = 200, /users/me = 200 (cache bypassed)") + compose("start", "valkey") + wait_ready(200) + assert call("GET", "/api/v1/users/me", token=token) == 200 + print("valkey restored: /users/me = 200") + + print("stopping postgres ...") + compose("stop", "postgres") + time.sleep(2) + ready = call("GET", "/health/ready") + me = call("GET", "/api/v1/users/me", token=token) + anon = call("GET", "/api/v1/users/me") + assert ready == 503, f"readiness must be 503 without PostgreSQL, got {ready}" + assert me == 503, f"authenticated call must be a bounded 503, got {me}" + assert anon == 503, f"anonymous call must not be trusted, got {anon}" + print("postgres down: /health/ready = 503, /users/me = 503, anonymous = 503") + compose("start", "postgres") + wait_ready(200, timeout=180) + assert call("GET", "/api/v1/users/me", token=token) == 200 + print("postgres restored: /users/me = 200 (session survived)") + print("PASS: graceful degradation and recovery without trusting the cache/anonymous user") + + +if __name__ == "__main__": + main() diff --git a/scripts/check-expiry.sh b/scripts/check-expiry.sh new file mode 100755 index 00000000..df4aec12 --- /dev/null +++ b/scripts/check-expiry.sh @@ -0,0 +1,12 @@ +#!/bin/sh +set -eu +# Prove session expiry with a SHORT SESSION_TTL_SECONDS on a throwaway stack. +# The main stand can stay up; this uses a second compose project on port 8081. +cd "$(dirname "$0")/.." +export SESSION_TTL_SECONDS=2 +export PUBLISH_PORT=8081 +PROJECT=mtusi2expiry +cleanup() { docker compose -p "$PROJECT" down -v >/dev/null 2>&1 || true; } +trap cleanup EXIT +docker compose -p "$PROJECT" up -d --build +python3 scripts/expiry_probe.py --base-url http://localhost:8081 --ttl 2 diff --git a/scripts/expiry_probe.py b/scripts/expiry_probe.py new file mode 100644 index 00000000..a263e935 --- /dev/null +++ b/scripts/expiry_probe.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +"""Wait for a stand, then prove that a short-TTL session expires. + +Run against a stand started with SESSION_TTL_SECONDS=2 (see check-expiry.sh). +""" +from __future__ import annotations + +import argparse +import base64 +import json +import os +import time +import urllib.error +import urllib.request + + +def _call(base, method, path, token=None, body=None): + headers = {"Accept": "application/json"} + data = None + if body is not None: + data = json.dumps(body).encode("utf-8") + headers["Content-Type"] = "application/json" + if token: + headers["Authorization"] = "Bearer " + token + request = urllib.request.Request(base + path, data=data, headers=headers, method=method) + try: + with urllib.request.urlopen(request, timeout=10) as response: + return response.status, json.loads(response.read() or b"null") + except urllib.error.HTTPError as error: + return error.code, json.loads(error.read() or b"null") + + +def wait_ready(base, timeout=180.0): + deadline = time.time() + timeout + while time.time() < deadline: + try: + with urllib.request.urlopen(base + "/health/ready", timeout=3) as response: + if response.status == 200: + return + except (urllib.error.URLError, TimeoutError, OSError): + pass + time.sleep(2) + raise SystemExit("stand did not become ready") + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--base-url", default="http://localhost:8081") + parser.add_argument("--ttl", type=int, default=2) + args = parser.parse_args() + base = args.base_url.rstrip("/") + wait_ready(base) + + username = "expiry_" + os.urandom(4).hex() + password = "T3st-" + os.urandom(8).hex() + status, _ = _call(base, "POST", "/api/v1/users", + body={"username": username, "display_name": "Expiry", "password": password}) + assert status == 201, status + credential = base64.b64encode(f"{username}:{password}".encode()).decode() + request = urllib.request.Request( + base + "/api/v1/auth/sessions", + headers={"Authorization": "Basic " + credential, "Accept": "application/json"}, + method="POST", + ) + with urllib.request.urlopen(request, timeout=10) as response: + session = json.loads(response.read()) + token = session["token"] + + me_before, _ = _call(base, "GET", "/api/v1/users/me", token=token) + assert me_before == 200, me_before + time.sleep(args.ttl + 1) + me_after, _ = _call(base, "GET", "/api/v1/users/me", token=token) + assert me_after == 401, f"expired token still accepted: {me_after}" + print(f"PASS: session expired after ~{args.ttl}s (before=200, after=401)") + + +if __name__ == "__main__": + main() 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..ff7830bd --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,8 @@ +#!/bin/sh +set -eu +# Restart the API 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 postgres valkey +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/secrets.example/cache_url b/secrets.example/cache_url new file mode 100644 index 00000000..075714da --- /dev/null +++ b/secrets.example/cache_url @@ -0,0 +1 @@ +redis://valkey:6379/0 diff --git a/secrets.example/database_password b/secrets.example/database_password new file mode 100644 index 00000000..1bf660c6 --- /dev/null +++ b/secrets.example/database_password @@ -0,0 +1 @@ +Example-Local-Password-Change-Me-123 diff --git a/secrets.example/database_url b/secrets.example/database_url new file mode 100644 index 00000000..fa7bbeda --- /dev/null +++ b/secrets.example/database_url @@ -0,0 +1 @@ +postgresql://messenger:Example-Local-Password-Change-Me-123@postgres:5432/messenger diff --git a/src/__init__.py b/src/__init__.py new file mode 100644 index 00000000..1c5bcfee --- /dev/null +++ b/src/__init__.py @@ -0,0 +1 @@ +"""MTUSI Messenger lab2 application package.""" diff --git a/src/app.py b/src/app.py new file mode 100644 index 00000000..ed5450b3 --- /dev/null +++ b/src/app.py @@ -0,0 +1,348 @@ +"""FastAPI application implementing the lab2 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``. +""" +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 +from .db import pool +from .errors import ApiError +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) + +_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 — лабораторная 2", + version="1.2.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} + 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 + 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 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: + 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, + user: Dict = Depends(current_user), + conn=Depends(get_conn), +) -> dict: + canonical = _require_chat(conn, chat_id, str(user["id"])) + row = repo.insert_message(conn, canonical, str(user["id"]), payload.text) + return repo.message_json(row) + + +@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..1968c38d --- /dev/null +++ b/src/config.py @@ -0,0 +1,59 @@ +"""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 + 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(), + 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/main.py b/src/main.py new file mode 100644 index 00000000..5b517f5c --- /dev/null +++ b/src/main.py @@ -0,0 +1,38 @@ +"""Container entrypoint: migrate, then run the HTTP server as PID 1.""" +from __future__ import annotations + +import logging +import os + +import uvicorn + +from .config import settings +from .migrate import apply_migrations + + +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 env=%s host=%s port=%s sessions=%s cache=%s", + settings.app_env, + settings.app_host, + settings.app_port, + settings.session_store, + "on" if settings.cache_enabled else "off", + ) + apply_migrations() + uvicorn.run( + "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, + ) + + +if __name__ == "__main__": + main() diff --git a/src/migrate.py b/src/migrate.py new file mode 100644 index 00000000..eed4f6ad --- /dev/null +++ b/src/migrate.py @@ -0,0 +1,66 @@ +"""Versioned, idempotent migration runner. + +Applied versions are recorded in ``schema_migrations``; a transaction-scoped +advisory lock serializes concurrent API replicas, so re-running never +duplicates schema or data. +""" +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..37662117 --- /dev/null +++ b/src/repositories.py @@ -0,0 +1,240 @@ +"""Parameterized SQL for users, chats, members, messages and sessions. + +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 uuid +from typing import Dict, List, Optional, Sequence + +from psycopg.errors import UniqueViolation + +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() + + +# --------------------------------------------------------------------------- # +# 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/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..8c7bc3f7 --- /dev/null +++ b/student-tests/http_client.py @@ -0,0 +1,109 @@ +"""Minimal stdlib HTTP client for student black-box tests (no extra deps).""" +from __future__ import annotations + +import base64 +import json +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") + + +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) -> Response: + return self.request( + "POST", + f"/api/v1/chats/{chat_id}/messages", + body={"text": text}, + token=token, + ) + + 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..77cf5425 --- /dev/null +++ b/student-tests/test_auth.py @@ -0,0 +1,124 @@ +"""Authentication and registration tests for lab2 (password + Basic/Bearer).""" +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): + # X-User-Id alone must not authenticate. + only_header = client.request("GET", "/api/v1/users/me", headers={"X-User-Id": alice["id"]}) + _assert_error(only_header, 401, "unauthorized", challenge_prefix="Bearer") + # With a valid token, X-User-Id must not override the session identity. + 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..9d6ef21f --- /dev/null +++ b/student-tests/test_concurrency.py @@ -0,0 +1,37 @@ +"""Race protection: 10 clients x 10 messages in parallel = 100 unique.""" +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_negative.py b/student-tests/test_negative.py new file mode 100644 index 00000000..d5cc4687 --- /dev/null +++ b/student-tests/test_negative.py @@ -0,0 +1,64 @@ +"""Negative and access-control tests carried over from lab1 onto lab2 auth.""" +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"], + ) + _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..d63d1f8c --- /dev/null +++ b/student-tests/test_pagination.py @@ -0,0 +1,79 @@ +"""Keyset pagination tests (carried over from lab1).""" +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..a95ccf8c --- /dev/null +++ b/student-tests/test_race.py @@ -0,0 +1,35 @@ +"""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" + + # And nothing titled like the failed attempt is visible. + listed = client.request("GET", "/api/v1/chats?limit=100", token=alice["token"]).json["items"] + assert all(item["title"] != "should-rollback" for item in listed)