11 Commits
Author SHA1 Message Date
Mariia_Maksimova ce8749d264 Lab2
Skeleton contracts / contracts (pull_request) Canceled after 0s
2026-10-03 11:14:52 +03:00
Mariia_Maksimova e78c103131 Lab2
Skeleton contracts / contracts (pull_request) Canceled after 0s
2026-10-03 11:03:49 +03:00
Mariia_MaksimovaandClaude Opus 5.5 d77aa1cd74 Обновить evidence и цифры в отчёте по финальному прогону
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-03 11:00:52 +03:00
Mariia_MaksimovaandClaude Opus 5.5 ed012ba09d Не доверять кэшу сессий после рестарта API
Флаг очистки кэша жил только в памяти процесса. Сценарий: logout при
недоступном Valkey (отзыв записан в PostgreSQL, tombstone нет) -> рестарт
API -> Valkey вернулся. Новый процесс читал устаревшую положительную запись,
и отозванный токен получал 200 на /users/me и 201 на отправку сообщения
до истечения TTL записи (до 60 s).

Теперь процесс стартует с включённым флагом и выполняет FLUSHDB перед
первым использованием кэша. Добавлен регрессионный тест
test_logout_during_outage_then_api_restart, evidence и отчёт обновлены.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-03 10:31:12 +03:00
Mariia_Maksimova 8e97518120 Lab2
Skeleton contracts / contracts (pull_request) Canceled after 0s
2026-10-02 10:28:52 +03:00
Mariia_Maksimova b6c3aa1e64 Lab2 2026-10-02 10:21:32 +03:00
Mariia_MaksimovaandClaude Opus 5.5 02dfeccb42 Убрать устаревшие файлы lab1 и неиспользуемый init.sql
Тесты lab1 в student-tests работали через X-User-Id и для lab2 неактуальны.
infra/postgres/init.sql дублировал миграции и нигде не подключался.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-02 10:15:44 +03:00
Mariia_Maksimova c25f19aa81 Lab2 2026-10-02 10:03:35 +03:00
Mariia_Maksimova 920bdf9641 Lab2 2026-10-01 22:08:08 +03:00
Mariia_Maksimova f4198de3c8 Lab2 2026-09-30 12:13:29 +03:00
Mariia_Maksimova 6bc82eaa2a Lab2: starting 2026-09-24 16:27:50 +03:00
44 changed files with 4210 additions and 71 deletions
+5 -1
View File
@@ -3,7 +3,6 @@
.env
.env.*
!.env.example
secrets
certs
volumes
data
@@ -18,3 +17,8 @@ __pycache__
node_modules
evidence
.DS_Store
infra/secrets
output
.pytest_cache
.venv-wsl
student-tests
+14 -4
View File
@@ -1,11 +1,21 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
# compose.yaml sets these values for the api service; only SESSION_TTL_SECONDS
# is read from .env (default 3600, persistence test needs >= 300).
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
# Secrets are files created by scripts/init-secrets.sh; paths contain no values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
# lab2 level 4: Valkey is a session cache, PostgreSQL is the source of truth.
SESSION_STORE=valkey
CACHE_URL_FILE=/run/secrets/cache_url
SESSION_CACHE_TTL_SECONDS=60
CACHE_TIMEOUT_SECONDS=0.25
CACHE_MAX_CONNECTIONS=20
CACHE_RETRY_AFTER_SECONDS=5
DB_POOL_SIZE=10
DB_MAX_OVERFLOW=5
DB_POOL_TIMEOUT_SECONDS=3
DB_CONNECT_TIMEOUT_SECONDS=3
DB_STATEMENT_TIMEOUT_MS=5000
+2
View File
@@ -0,0 +1,2 @@
*.sh text eol=lf
*.sql text eol=lf
+8
View File
@@ -1,4 +1,11 @@
# Local/private state
infra/secrets/*.txt
!infra/secrets/*.example.txt
.env
.venv/
__pycache__/
.pytest_cache/
.env
.env.*
!.env.example
@@ -30,3 +37,4 @@ coverage/
.vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
.venv-wsl/
+20
View File
@@ -0,0 +1,20 @@
FROM python:3.12.7-slim
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app ./app
COPY scripts ./scripts
COPY migrations ./migrations
RUN useradd --create-home --uid 10001 appuser
USER appuser
EXPOSE 8080
CMD ["sh", "-c", "uvicorn app.main:app --host ${APP_HOST:-0.0.0.0} --port ${APP_PORT:-8080}"]
-8
View File
@@ -1,8 +0,0 @@
# Teaching outline, not a runnable Dockerfile. Implement your own Dockerfile.
# 1. Choose a runtime/toolchain version and pin the base image tag/digest.
# 2. Copy dependency manifests first; install from the language lockfile.
# 3. Copy source and build. For compiled languages use a separate runtime stage.
# 4. Run the HTTP process as PID 1; listen on 0.0.0.0:8080.
# 5. Add non-root, signals and healthcheck according to the current rubric.
# 6. Pass runtime config/secrets at startup, never COPY .env or secret files.
# This file deliberately has no FROM/CMD: selecting/implementing them is the task.
+26 -7
View File
@@ -1,13 +1,15 @@
PYTHON ?= python3
# Prefer a local Linux venv (WSL/Linux/macOS) so `make validate` finds requirements-dev.txt.
PYTHON ?= $(firstword $(wildcard .venv/bin/python3 .venv-wsl/bin/python3) python3)
BASE_URL ?= http://localhost:8080
CA_FILE ?=
ACTION_SCRIPT ?=
ACTION_SCRIPT ?= scripts/restart.sh
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 secrets up test-level4 db-checks evidence
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "check: offline structure; validate: full OpenAPI; test: running API; load: synthetic writes"
@echo "secrets, up: local stand; test-level4, db-checks: lab2 level 4; evidence: collect evidence/"
check:
$(PYTHON) scripts/check_contract.py
@@ -16,11 +18,28 @@ validate:
$(PYTHON) scripts/validate_openapi.py
test:
$(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS)
$(PYTHON) tests/smoke.py --base-url $(BASE_URL)
load:
$(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS)
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)
$(PYTHON) tests/resilience.py \
--base-url $(BASE_URL) \
--action-script $(ACTION_SCRIPT) \
--mode persistence
secrets:
sh scripts/init-secrets.sh
up: secrets
docker compose --profile tests up -d --build api api_short_ttl
test-level4:
$(PYTHON) student-tests/level4.py --base-url $(BASE_URL)
db-checks:
docker compose --profile tools run --rm db_checks
evidence:
sh scripts/run_evidence.sh
+529 -24
View File
@@ -1,37 +1,542 @@
# Отчёт — лабораторная 2
# Отчёт — лабораторная работа №2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
PostgreSQL, серверные сессии и Valkey
## Запуск из чистого clone
- Автор, группа: Максимова Мария, БВТ2303
- Целевая оценка: 4
- Commit / PR: e78c103
- Использованные средства: Python 3.12.7 (в Docker), FastAPI, SQLAlchemy 2 (async) + asyncpg, argon2-cffi, redis-py 5 (клиент Valkey), PostgreSQL 16.4, Valkey 8.0.1, Docker Desktop + WSL2.
- Источники: документация PostgreSQL (EXPLAIN, сравнение строк/row comparison, транзакции, WAL), документация Valkey (persistence, `SET NX`, `EX`), RFC 7617 (HTTP Basic), документация FastAPI и SQLAlchemy.
- Помощь ИИ: Claude Code и Perplexity использовались для части реализации кэша, тестов уровня 4, диагностики окружения и оформления отчёта. Все команды, тесты и измерения я запускала локально сама, результаты сохранены в `evidence/`.
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
## 1. Краткий итог
## Архитектура и решения
В lab1 всё состояние хранилось в словарях Python и пропадало при перезапуске, а пользователя определял заголовок `X-User-Id`, который мог подставить кто угодно. В lab2:
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
1. Пользователи, чаты, участники, сообщения и сессии хранятся в PostgreSQL на именованном volume `postgres_data`.
2. Структура базы создаётся версионируемыми миграциями. Их можно запустить повторно, и данные не продублируются.
3. Регистрация принимает `password`. Пароль хранится только в виде хеша Argon2id.
4. Вход: `POST /api/v1/auth/sessions` с Basic. Сервер выдаёт opaque Bearer-токен, у сессии есть срок жизни, её можно отозвать через logout.
5. Все остальные бизнес-endpoint принимают только Bearer. `X-User-Id` игнорируется.
6. Данные и ещё действующие сессии переживают перезапуск API и всех хранилищ без удаления volumes.
7. На «4» добавлен Valkey с одной ролью: cache-aside кэш проверки Bearer-сессий. Источник истины остаётся в PostgreSQL. Отказы Valkey и PostgreSQL проверены экспериментально.
## Доказательства критериев
Контракт lab1 (users/chats/messages, keyset-пагинация с непрозрачным cursor, единый формат ошибок, `X-Request-Id`) сохранён. Изменена только аутентификация, как требует контракт lab2.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
## 2. Соответствие критериям
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
### 2.1. Оценка «3»
## Эксперименты и отказы
| Критерий | Где реализовано | Чем доказано |
|------------------------------------------------------------------------------------|---------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| Минимум lab1 сохранён, объявлен переход на новую аутентификацию | `app/main.py`, `contracts/openapi.json` | `make test` → `PASS: lab2 public API scenario` (`evidence/smoke.txt`) |
| Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes | `scripts/restart.sh`, volume `postgres_data`, таблица `sessions` | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` → PASS со старым токеном (`evidence/persistence.txt`) |
| PostgreSQL содержит users, chats, участников и messages | `migrations/001_initial_schema.sql` | `\dt` в `psql`; smoke-тест работает через БД |
| PK, FK, UNIQUE username | `migrations/001_initial_schema.sql` | раздел 5; проверка FK вручную (раздел 5.2) |
| Миграции с нуля | `scripts/migrate.py`, `migrations/*.sql` | на пустом volume: `APPLY 001…`, `APPLY 002…`, `PASS` |
| Миграции повторно запускаются без дублирования | таблица `schema_migrations` | `docker compose run --rm migrate` → `SKIP 001…`, `SKIP 002…` (`evidence/migrations_repeat.txt`) |
| Создание чата атомарно | `app/repositories.py::create_chat_with_members` | `make db-checks`: откат строки `chats` вместе с участниками (`evidence/explain.txt`) |
| Basic только на `POST /auth/sessions` | `app/services.py::create_user_session`, `app/deps.py::require_user` | smoke: Basic на `/users/me` → 401 |
| Остальные endpoint требуют Bearer | `Depends(require_user)` на каждом защищённом маршруте | smoke + `evidence/level4.txt` |
| Срок жизни и отзыв сессии | `sessions.expires_at`, `sessions.revoked_at` | logout → 204, затем 401; тест истечения TTL = 3 s (`evidence/level4.txt`) |
| `X-User-Id` не даёт доступа | `app/deps.py` вообще не читает этот заголовок | smoke: только `X-User-Id` → 401; Bearer + чужой `X-User-Id` → остаётся владелец токена |
| Пароли хешируются password KDF | `app/security.py` (Argon2id) | `SELECT password_hash FROM users` → `$argon2id$…` |
| `make test` и `make test-persistence` проходят | `Makefile` | `evidence/smoke.txt`, `evidence/persistence.txt` |
| Secrets и volumes не попадают в Git | `.gitignore`, `.dockerignore` | `git check-ignore -v infra/secrets/*.txt` (раздел 12) |
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
### 2.2. Оценка «4»
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Критерий | Чем доказано |
|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| Valkey с конкретной ролью (кэш сессий), источник истины — PostgreSQL | `EXISTS messenger:session:<sha256>` = 1 после первого запроса (`evidence/level4.txt`) |
| Корректный expiry кэша | TTL записи = min(60 s, остаток жизни сессии); тест `api_short_ttl` |
| Инвалидация при logout без гонки | tombstone `revoked` + заполнение через `SET NX` |
| Поведение при отказе Valkey (stop и pause) | задержка ≤ 0.26–0.30 s, токен, отозванный во время отказа, остаётся 401, в том числе после рестарта API |
| Поведение при отказе PostgreSQL | `503 unavailable` за ~3 s, `ready` 503, `live` 200, анонимный запрос 401 |
| Пул соединений и таймауты | `app/db.py`, `app/cache.py` |
| Индекс истории обоснован EXPLAIN | keyset: 5 buffers против 208 (OFFSET) и 783 (без индекса) |
| Гонка регистрации | 20 параллельных запросов → `{201: 1, 409: 19}` |
| Эксперимент отказа повторён с Valkey | persistence-тест перезапускает `db`, `valkey`, `api` |
## Ограничения и следующие шаги
## 3. Запуск из чистого clone
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
### 3.1. Требования
- Docker Engine или Docker Desktop с Compose v2.
- Linux-shell: Linux/macOS — обычный терминал; Windows — WSL2 (подробности в 3.3).
- Python 3.9+ для публичных тестов. Они используют только стандартную библиотеку.
- Для `make validate`: виртуальное окружение с `requirements-dev.txt` (см. 3.3).
Версии образов закреплены: `python:3.12.7-slim`, `postgres:16.4-alpine`, `valkey/valkey:8.0.1-alpine`.
### 3.2. Порядок команд
Все команды выполняются из корня репозитория.
cd /mnt/c/Users/masha/WebstormProjects/mtusi2026lab2
```sh
# 1. Сгенерировать локальные secrets (случайные пароли; в Git не попадают)
sh scripts/init-secrets.sh
# 2. Собрать и запустить стенд:
# db → (healthy) → migrate → api :8080 и api_short_ttl :8081
docker compose --profile tests up -d --build api api_short_ttl
# 3. Дождаться готовности (ожидается {"status":"ok"})
# 4. Проверки
make check # структура репозитория, OpenAPI refs, синтаксис
make validate # полная OpenAPI 3.1 / JSON Schema
make test # публичный smoke
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт db, valkey, api
make test-level4 # ~1 мин; сам останавливает/запускает valkey и db
make db-checks # rollback и EXPLAIN внутри сети compose
# 5. Всё сразу с сохранением результатов в evidence/
sh scripts/run_evidence.sh
```
`.env` необязателен. `cp .env.example .env` нужен, только curl -fsS http://localhost:8080/health/ready
если требуется изменить `SESSION_TTL_SECONDS`. Для persistence-теста значение должно быть не меньше 300.
Безопасная остановка (volume `postgres_data` сохраняется):
```sh
docker compose --profile tests down
```
Намеренное удаление всех учебных данных. Эта команда уничтожает volume, поэтому в тесте рестарта её использовать нельзя:
```sh
docker compose --profile tests down -v
```
### 3.3. Windows
В PowerShell команды не заработают: там нет `sh` и `make`, `python3` — заглушка Microsoft Store, `curl` — псевдоним `Invoke-WebRequest`. К тому же официальный тест запускает `restart.sh` как исполняемый файл, а Windows не умеет выполнять shell-скрипты напрямую (`WinError 193`).
Порядок работы:
1. В Docker Desktop включить Settings → Resources → WSL Integration для своего дистрибутива.
2. В PowerShell перейти в папку проекта и выполнить `wsl`. WSL откроется в той же папке (путь вида `/mnt/c/.../mtusi2026lab2`).
3. Один раз добавить пользователя в группу `docker`: `sudo usermod -aG docker $USER`, затем в PowerShell выполнить `wsl --shutdown` и снова войти в WSL.
4. Один раз установить make: `sudo apt install -y make`.
5. Выдать hook право на исполнение: `chmod +x scripts/restart.sh`. Если файл редактировался в Windows, убрать CRLF: `sed -i 's/\r$//' scripts/*.sh`.
6. Для `make validate`:
```sh
python3 -m venv .venv-wsl && . .venv-wsl/bin/activate
pip install openapi-spec-validator==0.7.2 jsonschema referencing
```
Полный `requirements-dev.txt` на хостовом Python 3.13/3.14 не установится: закреплённые `pydantic` и `asyncpg` рассчитаны на Python 3.12 и начнут собираться из исходников. Самому приложению это не мешает, оно работает в образе `python:3.12.7-slim`. Для валидатора достаточно трёх библиотек выше.
Если `make` выдаёт `getcwd: No such file or directory`, WSL потерял текущую папку, потому что её изменили со стороны Windows. Нужно заново войти в неё командой `cd`.
## 4. Архитектура
```
HTTP, Authorization: Basic (только вход) / Bearer
Клиент ───────────────────────────────────────────────> api (FastAPI/Uvicorn, 1 процесс)
│
SQL, пул ≤ 15, таймауты 3/5 s │ RESP, пул ≤ 20, таймаут 0.25 s
┌────────────────────────────────┴───────────────────────┐
▼ ▼
db — PostgreSQL 16.4 valkey — Valkey 8.0.1
источник истины: только копия сессий
users, chats, chat_members, (cache-aside),
messages, sessions persistence выключена
volume: postgres_data
```
### 4.1. Сервисы Compose
| Роль из `contracts/infrastructure.json` | Service | Версия / источник | Health / readiness | Volume | Сеть / порт | Передача credentials |
|-------------------------------------------|-----------------------------------|-----------------------------------------------------------|---------------------------------------------------------------------|----------------------------------------------|-----------------------------------------------------------|--------------------------------------------------------|
| API | `api` | собирается из исходников, база `python:3.12.7-slim` | `/health/live` (процесс жив), `/health/ready` (PostgreSQL отвечает) | нет, состояния в процессе нет | `messenger_net`; host `8080:8080` | `DATABASE_URL_FILE`, `CACHE_URL_FILE` → Docker secrets |
| API с коротким TTL (только для тестов) | `api_short_ttl` (profile `tests`) | тот же образ, `SESSION_TTL_SECONDS=3` | те же endpoint | нет | host `8081:8080` | те же secrets |
| Реляционное хранилище / сессии | `db` | `postgres:16.4-alpine` | `pg_isready -U messenger -d messenger` | `postgres_data` → `/var/lib/postgresql/data` | только `messenger_net`, `db:5432`, на хост не опубликован | `POSTGRES_PASSWORD_FILE` → Docker secret |
| Кэш сессий | `valkey` | `valkey/valkey:8.0.1-alpine`, `--save "" --appendonly no` | `valkey-cli PING` | нет, сознательно | только `messenger_net`, `valkey:6379` | пароль из Docker secret `valkey_password` |
| Bootstrap схемы | `migrate` | тот же образ, `python scripts/migrate.py` | завершается с кодом 0 | нет | `messenger_net` | `DATABASE_URL_FILE` |
Порядок старта задан через `depends_on`: `db (service_healthy)` → `migrate (service_completed_successfully)` → `api`.
### 4.2. Почему один процесс API
Состояние в процессе API не хранится: всё лежит в PostgreSQL, а кэш — в Valkey. Поэтому ограничение lab1 «только один worker» больше не связано с согласованностью данных. Сейчас процесс один, потому что для lab2 этого достаточно.
### 4.3. Критичные зависимости readiness
- PostgreSQL — критичен. Без него нельзя проверить сессию, если её нет в кэше, и нельзя выполнить ни одну запись. `/health/ready` при недоступной БД возвращает 503.
- Valkey — не критичен. Его отказ снижает только производительность: проверка сессий идёт напрямую в PostgreSQL. `/health/ready` от Valkey не зависит.
- Grafana и мониторинг в lab2 не используются. В будущем их отказ тоже не должен останавливать API.
## 5. Схема базы данных
Схема описана до написания запросов, в файлах `migrations/001_initial_schema.sql` (таблицы и ограничения) и `migrations/002_indexes.sql` (индексы).
### 5.1. Таблицы и ограничения
| Таблица | Столбцы | Ограничения | Назначение |
|---------------------|----------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| `users` | `id UUID`, `username VARCHAR(32)`, `display_name VARCHAR(100)`, `password_hash TEXT`, `created_at TIMESTAMPTZ` | PK `id`; `UNIQUE(username)`; `CHECK (username ~ '^[a-z0-9_]{3,32}$')`; `CHECK` непустого `display_name` | пользователи; пароль хранится только как Argon2id-хеш |
| `chats` | `id UUID`, `title VARCHAR(255)`, `created_at` | PK `id`; `CHECK` непустого `title` | чаты |
| `chat_members` | `chat_id UUID`, `user_id UUID` | PK `(chat_id, user_id)`; FK `chat_id → chats(id) ON DELETE CASCADE`; FK `user_id → users(id) ON DELETE RESTRICT` | связь «многие ко многим»; дважды добавить одного участника невозможно |
| `messages` | `id UUID`, `chat_id`, `sender_id`, `text VARCHAR(4000)`, `created_at` | PK `id`; FK `chat_id → chats(id)`; FK `sender_id → users(id)`; `CHECK` непустого текста | сообщения |
| `sessions` | `id UUID`, `user_id`, `token_hash CHAR(64)`, `expires_at`, `revoked_at`, `created_at` | PK `id`; FK `user_id → users(id) ON DELETE CASCADE`; `UNIQUE(token_hash)` | серверные сессии; хранится только SHA-256 токена |
| `schema_migrations` | `version TEXT`, `applied_at` | PK `version` | учёт применённых миграций |
Все временные столбцы имеют тип `TIMESTAMPTZ` и назначаются сервером (`DEFAULT now()`). API отдаёт их в RFC 3339 UTC с суффиксом `Z`.
### 5.2. Почему правила записаны в базе, а не только в коде
Ограничение в базе нельзя обойти ошибкой в приложении. Например, попытка вставить сообщение в несуществующий чат отклоняется самой PostgreSQL:
```sh
docker compose exec db psql -U messenger -d messenger -c \
"INSERT INTO messages (id, chat_id, sender_id, text)
VALUES (gen_random_uuid(), gen_random_uuid(), gen_random_uuid(), 'x');"
# ERROR: ... violates foreign key constraint ...
```
Точно так же `UNIQUE(username)` гарантирует уникальность логина даже при одновременных запросах (раздел 7.4).
### 5.3. Индексы
| Индекс | Для какого запроса |
|-------------------------------------------------------------------------------|----------------------------------------------------------------------|
| `messages_keyset_idx (chat_id, created_at, id)` | страница истории чата по keyset-cursor; обоснован EXPLAIN |
| `chats_keyset_idx (created_at, id)` | сортировка списка чатов по `(created_at, id)` |
| `chat_members_user_chat_idx (user_id, chat_id)` | «чаты пользователя» и проверка «является ли пользователь участником» |
| `sessions_active_token_idx (token_hash, expires_at) WHERE revoked_at IS NULL` | поиск действующей сессии при промахе кэша |
| неявные индексы PK и UNIQUE | поиск по `id`, `username`, `token_hash` |
Лишних индексов нет: каждый обслуживает конкретный запрос из `app/repositories.py`.
## 6. Миграции
`scripts/migrate.py` выполняется в отдельном контейнере `migrate` до старта API:
1. создаёт служебную таблицу `schema_migrations`, если её ещё нет;
2. перебирает файлы `migrations/*.sql` в порядке номеров (`001_…`, `002_…`);
3. если версия уже есть в `schema_migrations`, печатает `SKIP <файл>`;
4. иначе выполняет SQL файла и записывает версию в одной транзакции. Если миграция упадёт, в `schema_migrations` она не попадёт, а частично созданные объекты будут откачены.
Сами SQL-файлы тоже идемпотентны (`CREATE … IF NOT EXISTS`). Даже при ручном повторе они ничего не сломают.
Миграции выполняются через «сырое» соединение `asyncpg`, а не через `session.execute(text(...))` из SQLAlchemy. Причина: prepared statement в asyncpg не принимает несколько SQL-команд сразу. Первая версия скрипта падала с ошибкой `cannot insert multiple commands into a prepared statement`.
Seed-данных миграции не содержат. Это только bootstrap схемы. Тестовые пользователи создаются тестами через API.
Проверка:
```sh
docker compose run --rm migrate
# SKIP 001_initial_schema.sql
# SKIP 002_indexes.sql
# PASS: migrations applied
docker compose exec db psql -U messenger -d messenger -c 'SELECT * FROM schema_migrations'
```
## 7. Транзакционные границы
| Операция | Граница транзакции | Что гарантируется |
|--------------------|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| Регистрация | один `INSERT INTO users` + `COMMIT` | дубль username отсекает `UNIQUE` → `IntegrityError` → `409 conflict`; предварительного `SELECT` нет, поэтому нет гонки «проверил → вставил» |
| Создание чата | `INSERT chats` + `INSERT chat_members` (все участники) в одной транзакции | при любой ошибке `ROLLBACK`: чата без участников не бывает |
| Отправка сообщения | проверка членства + `INSERT messages` + `COMMIT` | `201 Created` возвращается только после `COMMIT` |
| Создание сессии | `INSERT sessions` + `COMMIT` | токен отдаётся клиенту только после записи сессии |
| Logout | `UPDATE sessions SET revoked_at = now() WHERE token_hash = … AND revoked_at IS NULL AND expires_at > now()` + `COMMIT` | повторный logout затрагивает 0 строк → 401 |
| Миграция | один файл + запись версии | файл применяется целиком или не применяется совсем |
### 7.1. Проверки перед созданием чата (в `app/services.py`)
1. В `member_ids` нет дубликатов → иначе 400.
2. Вызывающий пользователь есть в `member_ids` → иначе 400.
3. Все участники существуют (один `SELECT … WHERE id = ANY(...)`) → иначе 400.
4. Только после этого выполняется транзакция `create_chat_with_members`.
Даже если между шагом 3 и транзакцией пользователя удалят (в обязательном API удаления нет), FK `chat_members.user_id` не даст сохранить участника. Вся транзакция откатится.
### 7.2. Проверка атомарности (`make db-checks`)
Скрипт намеренно передаёт в транзакцию второго, несуществующего участника:
```
expected failure: IntegrityError
PASS: chat row was rolled back together with members
PASS: no chats without members exist in the database
```
### 7.3. Что гарантирует COMMIT
После `COMMIT` PostgreSQL записывает изменения в журнал WAL на диск. Настройки `fsync=on` и `synchronous_commit=on` оставлены по умолчанию. Проверен штатный рестарт, но не аварийное убийство контейнера. API отвечает `201` только после `COMMIT`: если клиент получил 201, запись точно сохранена.
### 7.4. Гонка регистрации
20 одновременных `POST /api/v1/users` с одинаковым `username`:
```
statuses: {201: 1, 409: 19}
```
Ровно один запрос успешен, остальные получают 409. Ответов 500 нет.
## 8. Аутентификация и сессии
### 8.1. Хеширование пароля
`app/security.py::hash_password` использует `argon2.PasswordHasher` (Argon2id, параметры библиотеки по умолчанию). В базе лежит строка вида:
```
$argon2id$v=19$m=65536,t=3,p=4$<соль>$<хеш>
```
- `m=65536` — 64 МБ памяти на одну проверку, `t=3` — три прохода, `p=4` — степень параллелизма.
- Соль у каждого пользователя своя, поэтому одинаковые пароли дают разные хеши.
Почему не SHA-256 для паролей. SHA-256 рассчитан на скорость: на видеокарте его считают миллиардами в секунду, а придуманные людьми пароли короткие. Argon2id специально медленный и требует много памяти, поэтому перебор становится дорогим. bcrypt не выбран, потому что он обрезает пароль до 72 байт, а контракт допускает до 128 символов UTF-8.
Пароль, его хеш и данные сессии никогда не попадают в ответ `User`.
### 8.2. Вход через Basic
`POST /api/v1/auth/sessions` принимает только заголовок `Authorization: Basic base64(username:password)`, без JSON-тела.
- Строка разбивается по первому двоеточию, поэтому двоеточие в пароле допустимо.
- Username проверяется на ASCII, пароль декодируется как UTF-8.
- Неизвестный пользователь и неверный пароль дают одинаковый ответ `401` с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. По ответу нельзя узнать, существует ли логин.
Basic — это кодирование, а не шифрование. Поэтому он используется ровно один раз, при входе. Работа по HTTP допустима только на локальном стенде с синтетическими данными.
### 8.3. Токен
- Генерация: `secrets.token_urlsafe(32)` — 256 бит случайности.
- Токен opaque: внутри нет ни username, ни UUID, ни подписанных данных. Это не JWT, а просто случайная строка, как номер гардеробного жетона.
- Клиент получает токен один раз, в ответе `201`:
```text
{"token":"…","token_type":"Bearer","expires_at":"…Z","user":{…}}
```
- В `sessions.token_hash` хранится SHA-256 токена, сам токен не хранится. При утечке базы хеши нельзя использовать как токены.
- Для токена SHA-256 допустим, в отличие от пароля: у токена 256 бит энтропии, перебрать его невозможно даже быстрым хешем.
### 8.4. Срок жизни и отзыв
- `expires_at = now() + SESSION_TTL_SECONDS` (по умолчанию 3600 s). Срок фиксируется при входе и не продлевается после рестарта.
- Сессия действует, если `revoked_at IS NULL AND expires_at > now()` (`repositories.get_active_session_user`).
- `DELETE /api/v1/auth/sessions/current` → `204` без тела; повтор с тем же токеном → `401`.
- Истечение проверено на `api_short_ttl` с TTL 3 s: токен работает, а через 4.5 s получает 401, хотя до этого был в кэше.
### 8.5. Bearer на всех бизнес-endpoint
`app/deps.py::require_user` подключается к каждому защищённому маршруту через `Depends(require_user)`:
| Запрос | Ответ |
|---------------------------------------------|---------------------------------------------------|
| без `Authorization` | 401, `WWW-Authenticate: Bearer realm="messenger"` |
| `Authorization: Basic …` на бизнес-endpoint | 401, Bearer challenge |
| неизвестный, истёкший или отозванный токен | 401, Bearer challenge |
| только `X-User-Id` | 401: код этот заголовок не читает |
| Bearer Алисы + `X-User-Id` Евы | 200, пользователь — Алиса |
### 8.6. Аутентификация и авторизация
Аутентификация отвечает на вопрос «кто ты» (токен → пользователь). Авторизация — «можно ли тебе это». `repositories.get_accessible_chat` делает `JOIN chat_members … AND user_id = <текущий пользователь>`. Если пользователь не участник чата, ответ 404, а не 403: так API не раскрывает, что чат существует. Списки чатов содержат только доступные чаты.
## 9. Valkey: роль, expiry, инвалидация, отказы (уровень «4»)
### 9.1. Роль
Valkey выполняет одну роль: кэширует результат проверки Bearer-сессии, чтобы не ходить в PostgreSQL на каждый защищённый запрос.
Источник истины — таблица `sessions` в PostgreSQL. В Valkey лежит только копия, поэтому его persistence выключена сознательно (`--save "" --appendonly no`). Потеря кэша ничего не теряет: действующие сессии переживают рестарт благодаря PostgreSQL, а не Valkey.
### 9.2. Алгоритм (cache-aside, `services.current_user_from_bearer_token`)
```
h = sha256(token)
GET messenger:session:<h>
├─ "revoked" → 401
├─ данные пользователя → проверить expires_at → пустить (cache hit, без SQL)
└─ ключа нет / ошибка → запрос в PostgreSQL (cache miss)
├─ сессии нет → 401
└─ сессия действует → пустить + SET NX с TTL
```
Посмотреть ключи:
```sh
docker compose exec valkey sh -c \
'valkey-cli -a "$(cat /run/secrets/valkey_password)" --no-auth-warning --scan --pattern "messenger:session:*"'
```
Тест уровня 4 проверяет, что до запроса ключа нет, а после него `EXISTS` = 1.
### 9.3. Expiry кэша
TTL записи = `min(SESSION_CACHE_TTL_SECONDS = 60, секунд до expires_at)`. Кроме того, `expires_at` ещё раз сверяется при чтении из кэша. Поэтому истёкшая сессия не может «застрять» в Valkey.
### 9.4. Инвалидация при logout без гонки
1. Сначала `UPDATE sessions SET revoked_at = now()` + `COMMIT` в PostgreSQL.
2. Затем по тому же ключу записывается tombstone `revoked` (`SET … EX 60`, с перезаписью).
Удалять ключ вместо tombstone нельзя из-за гонки:
```
Запрос A: прочитал из БД «сессия действует»…
Запрос B: logout → отозвал в БД → удалил ключ
Запрос A: …положил в кэш «сессия действует» ← отозванная сессия ожила
```
Поэтому кэш заполняется командой `SET NX` («записать, только если ключа нет»). После logout по ключу уже лежит `revoked`, и запись запроса A не проходит.
### 9.5. Отказ Valkey (`app/cache.py::_run`)
- Таймаут любой операции — 0.25 s. Ошибка или таймаут считаются cache miss, запрос идёт в PostgreSQL.
- После ошибки кэш не используется 5 s (circuit breaker), чтобы не ждать таймаут на каждом запросе.
- При первой успешной операции после сбоя **и после каждого старта процесса API** выполняется `FLUSHDB`. Пока Valkey был недоступен, logout не мог записать tombstone. После возвращения в кэше могла остаться запись «сессия действует», и очистка её убирает. Потерять при этом нечего: в кэше только копии.
- Флаг «очистить перед использованием» живёт в памяти процесса, поэтому новый процесс стартует с ним включённым: он не знает, какие инвалидации потерял предыдущий. Без этого сценарий «logout при недоступном Valkey → рестарт API → Valkey вернулся» давал отозванному токену 200 и 201 на отправку сообщения, пока не истечёт TTL записи (≤ 60 s). Дефект воспроизведён и закрыт регрессионным тестом `test_logout_during_outage_then_api_restart` в `student-tests/level4.py`.
- Пул клиента Valkey — не больше 20 соединений.
### 9.6. После restart или flush Valkey
Ничего не теряется. Первый запрос не найдёт ключ, проверит сессию в PostgreSQL и снова заполнит кэш.
## 10. Надёжность работы с PostgreSQL
### 10.1. Пул и таймауты (`app/db.py`)
| Параметр | Значение | Зачем |
|---------------------------------------|------------|-------------------------------------------------------------------------------|
| `pool_size` | 10 | постоянные соединения |
| `max_overflow` | 5 | временные соединения при пике; всего ≤ 15, API не исчерпает `max_connections` |
| `pool_timeout` | 3 s | ожидание свободного соединения, потом 503 |
| connect timeout | 3 s | недоступная БД не держит запрос бесконечно |
| `statement_timeout` | 5000 ms | зависший запрос прерывает сама база |
| `idle_in_transaction_session_timeout` | 10 s | «забытая» открытая транзакция закрывается |
| `pool_pre_ping` | вкл. | разорванное соединение не выдаётся запросу |
### 10.2. Отказ БД → 503
`app/main.py` (`is_dependency_failure`, `dependency_error_handler`) превращает ошибки соединения, таймауты и исчерпание пула в ответ:
```json
{"error":{"code":"unavailable","message":"Service is unavailable.","request_id":"…"}}
```
Это ответ 503 за ограниченное время: не 500, не зависание, без SQL-текста, stack trace и credentials.
### 10.3. Единый формат ошибок
Каждый ответ, включая ошибки и health, содержит непустой `X-Request-Id`, который совпадает с `error.request_id`. Ошибки валидации FastAPI (по умолчанию `422`) переведены в `400 invalid_request`, как требует контракт. Неожиданное исключение даёт `500 internal_error` без внутренних деталей.
### 10.4. SQL-инъекции
Все запросы параметризованы: `text("… WHERE username = :username"), {"username": …}`. Значение передаётся отдельно от текста запроса. Строка `'; DROP TABLE users; --` будет воспринята как обычный текст.
## 11. Индекс и EXPLAIN
### 11.1. Keyset-пагинация
`next_cursor` — это непрозрачное base64-представление `(created_at, id)` последнего элемента страницы и идентификатора ресурса. Cursor от другого чата даёт 400. `id` нужен как второй ключ, потому что у двух сообщений может совпасть время.
Запрос страницы:
```text
SELECT … FROM messages
WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
ORDER BY created_at, id
LIMIT 51; -- limit + 1, чтобы понять, есть ли следующая страница
```
Условие записано сравнением кортежей `(created_at, id) > (…)`. Тогда PostgreSQL применяет его как `Index Cond` прямо в индексе, а не как `Filter` после чтения строк.
### 11.2. Замер (`make db-checks`, `evidence/explain.txt`)
Данные: один чат с 10 000 сообщений (всего в таблице ~59 000). Запрашивается страница после 9000-го сообщения.
| Вариант | План | Buffers | Время |
|----------------------------------------------------------|---------------------------------------------------------------|--------------------|---------|
| keyset + `messages_keyset_idx` | `Index Scan using messages_keyset_idx`, cursor в `Index Cond` | 5 (`hit=4 read=1`) | ~0.1 ms |
| `OFFSET 9000` | `Sort` 9051 строк, 9000 из них отбрасываются | 208 | ~3.7 ms |
| без индекса (удалён внутри транзакции, затем `ROLLBACK`) | `Seq Scan on messages`, ~58 000 строк отброшено фильтром | 783 | ~2.2 ms |
Главная метрика — Buffers (прочитанные страницы по 8 КБ). Время на маленьких данных скачет, а число буферов стабильно. Keyset читает только нужную страницу независимо от глубины; OFFSET и Seq Scan читают тем больше, чем дальше страница.
Время у всех вариантов единицы миллисекунд, потому что таблица целиком в кэше PostgreSQL. Различие видно по buffers: оно растёт вместе с объёмом таблицы (в прогоне на ~84 000 сообщений без индекса было 1106 buffers, у keyset по-прежнему 5).
## 12. Secrets и Git
- Реальные secrets генерирует `scripts/init-secrets.sh` в `infra/secrets/*.txt`. В контейнеры они передаются как Docker secrets (`*_FILE`), а не через переменные окружения или `compose.yaml`.
- В Git нет ни одного файла с secrets: их создаёт `scripts/init-secrets.sh` на каждой машине, в репозитории лежит только `.env.example` без значений.
- `.gitignore` исключает `infra/secrets/*.txt`, `.env`, `.venv/`, `.venv-wsl/`, `__pycache__/`. `.dockerignore` дополнительно исключает `infra/secrets` и `.git` из build context.
- Volume `postgres_data` — объект Docker, он не лежит в дереве репозитория и в Git попасть не может.
- В `evidence/` нет токенов, паролей, `DATABASE_URL`, заголовков `Authorization` и реальных сообщений. Официальные тесты не печатают credentials, а restart-hook запускается с подавленным выводом.
Проверка:
```sh
git check-ignore -v infra/secrets/postgres_password.txt infra/secrets/database_url.txt .venv-wsl
git status --short # secrets и venv в списке отсутствуют
```
## 13. Эксперименты и отказы
Стенд: Windows 11, Docker Desktop 29.3 (WSL2 backend), лимиты CPU/RAM для контейнеров не задавались. Клиенты запускались из WSL на том же хосте. Все данные синтетические.
### 13.1. Нагрузка
`tests/load.py`: closed-loop, 4 клиента, 15 s, без прогрева и без автоматических повторов, `POST /api/v1/chats/{id}/messages`, сессии кэшируются в Valkey.
| Метрика | Значение |
|-------------------|-----------------------|
| Успешных запросов | 4 071 |
| Ошибок | 0 |
| Successful RPS | ≈ 271 |
| p50 / p95 / p99 | 13.4 / 22.9 / 31.9 ms |
Это один прогон, генератор нагрузки работает на той же машине, у closed-loop есть coordinated omission, CPU/RAM не измерялись.
Это не оценка максимальной пропускной способности, а подтверждение, что API стабильно пишет под параллельной нагрузкой без ошибок.
Для сравнения: ранний прогон без Valkey дал 4 803 запроса / 319.89 RPS / p95 15.8 ms.
Разница в пределах разброса одиночных прогонов на Docker Desktop, выводов о влиянии кэша на запись отсюда не делается.
### 13.2. Отказы
| Воздействие | Ожидание | Наблюдение | Восстановление / потеря данных |
|---------------------------------------------------------------|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| `scripts/restart.sh` (`docker compose restart db valkey api`) | данные и сессия сохранены | persistence PASS со старым токеном, без повторного входа; `CreatedAt` volume не изменился | готовность за несколько секунд / потерь нет |
| `docker compose stop valkey` | обход кэша через PostgreSQL | вход, чтение и запись успешны, задержка ≤ 0.30 s; поддельный и анонимный запросы → 401 | сразу; после старта кэш пуст и заполняется заново |
| `docker compose pause valkey` (зависание) | таймаут 0.25 s, затем обход 5 s | задержка ≤ 0.26 s; токен, отозванный во время отказа, после `unpause` остаётся 401 благодаря `FLUSHDB` | ~5 s до возврата к кэшу / потерь нет |
| `pause valkey` → logout → `restart api` → `unpause valkey` | отозванный токен не оживает | `/users/me` и отправка сообщения → 401: новый процесс API очищает кэш перед первым использованием | сразу после готовности API / потерь нет |
| `docker compose stop db` | ограниченный 503, анонимным не доверяем | запись и вход → `503 unavailable` с `request_id` за ~3 s; `ready` 503, `live` 200; анонимный 401; непроверяемый токен 503, никогда 2xx | после `start db` API снова ready, токен не из кэша получает 503, закэшированный может быть опознан на /users/me (раздел 15) |
| 20 параллельных регистраций одного username | один 201, остальные 409 | `{201: 1, 409: 19}`, ни одного 500 | — |
## 14. Доказательства
| Файл | Команда | Результат |
|-------------------------------------------|------------------------------------------------------------|-------------------------------------------------------------------|
| `evidence/check_contract.txt` | `make check` | `PASS: offline skeleton structure, local refs and Python syntax` |
| `evidence/validate_openapi.txt` | `make validate` | `PASS: full OpenAPI 3.1 and JSON Schema validation` |
| `evidence/smoke.txt` | `make test` | `PASS: lab2 public API scenario` |
| `evidence/persistence.txt` | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session` |
| `evidence/migrations_repeat.txt` | `docker compose run --rm migrate` | `SKIP 001…`, `SKIP 002…`, `PASS` |
| `evidence/level4.txt` | `make test-level4` | `PASS: level 4 checks` |
| `evidence/explain.txt` | `make db-checks` | rollback PASS, планы EXPLAIN |
| `evidence/load.txt`, `evidence/load.json` | `python3 tests/load.py --duration 15 --concurrency 4` | агрегаты раздела 13.1 |
| `evidence/README.md` | — | контекст, commit, стенд, профиль нагрузки |
`scripts/check_contract.py` и `scripts/validate_openapi.py` проверяют только репозиторий и контракт, приложение они не запускают. Поведение API доказывают smoke, persistence, level4 и db-checks.
## 15. Ограничения и следующие шаги
- Кэшированная сессия при отказе PostgreSQL. Пока БД недоступна, закэшированная действующая сессия до 60 s продолжает опознавать пользователя на `GET /users/me`. Отозвать её в это время нельзя, потому что logout тоже требует БД. Все бизнес-операции при этом возвращают 503. Можно уменьшить `SESSION_CACHE_TTL_SECONDS` или запретить ответы из кэша при недоступной БД.
- Одна реплика API. Балансировка, `X-Instance-Id`, idempotency и failover относятся к lab3. Очистка кэша после сбоя рассчитана на один экземпляр: реплика, которая не получала запросов во время отказа Valkey и не перезапускалась, не узнает о потерянной инвалидации. Для нескольких реплик нужна общая эпоха кэша или запись отложенных инвалидаций в PostgreSQL.
- HTTP без TLS. Допустим только на локальном стенде с синтетическими данными. HTTPS обязателен в lab7.
- Нагрузка измерена один раз. Для статистических выводов нужны 3–5 повторов, медианы и разброс, а также open-loop генератор на отдельной машине.
- Хостовое окружение Windows. Официальные тесты и `restart.sh` требуют POSIX-shell, поэтому на Windows всё запускается через WSL. Полный `requirements-dev.txt` устанавливается на Python 3.12; runtime в Docker от этого не зависит.
- Очистка сессий. Истёкшие и отозванные строки `sessions` пока не удаляются. Нужна периодическая очистка (`DELETE … WHERE expires_at < now() - interval '1 day'`).
+397
View File
@@ -0,0 +1,397 @@
import { useState } from "react";
const API_BASE = "http://localhost:8080/api/v1";
function basicAuthorization(username, password) {
const encoded = btoa(
new TextEncoder()
.encode(`${username}:${password}`)
.reduce((value, byte) => value + String.fromCharCode(byte), "")
);
return `Basic ${encoded}`;
}
async function apiFetch(
path,
{
method = "GET",
token,
basicCredentials,
body,
} = {}
) {
const headers = {
Accept: "application/json",
};
if (body !== undefined) {
headers["Content-Type"] = "application/json";
}
if (token) {
headers.Authorization = `Bearer ${token}`;
}
if (basicCredentials) {
headers.Authorization = basicAuthorization(
basicCredentials.username,
basicCredentials.password
);
}
const response = await fetch(`${API_BASE}${path}`, {
method,
headers,
body: body !== undefined ? JSON.stringify(body) : undefined,
});
const requestId = response.headers.get("X-Request-Id");
const raw = await response.text();
const data = raw ? JSON.parse(raw) : null;
if (!response.ok) {
const message = data?.error?.message || `HTTP ${response.status}`;
throw new Error(`${message} (request_id: ${requestId || "unknown"})`);
}
return data;
}
export default function App() {
const [username, setUsername] = useState("");
const [displayName, setDisplayName] = useState("");
const [password, setPassword] = useState("");
const [session, setSession] = useState(null);
const [chat, setChat] = useState(null);
const [memberIdsInput, setMemberIdsInput] = useState("");
const [chatTitle, setChatTitle] = useState("");
const [text, setText] = useState("");
const [messages, setMessages] = useState([]);
const [error, setError] = useState("");
const [loading, setLoading] = useState(false);
const me = session?.user ?? null;
const token = session?.token ?? null;
async function handleRegister() {
setError("");
setLoading(true);
try {
await apiFetch("/users", {
method: "POST",
body: {
username,
display_name: displayName,
password,
},
});
const createdSession = await apiFetch("/auth/sessions", {
method: "POST",
basicCredentials: {
username,
password,
},
});
setSession(createdSession);
setPassword("");
} catch (requestError) {
setError(requestError.message);
} finally {
setLoading(false);
}
}
async function handleCreateChat() {
if (!me || !token) {
return;
}
setError("");
setLoading(true);
try {
const enteredMemberIds = memberIdsInput
.split(",")
.map((value) => value.trim())
.filter(Boolean);
const uniqueMemberIds = [...new Set([me.id, ...enteredMemberIds])];
const created = await apiFetch("/chats", {
method: "POST",
token,
body: {
title: chatTitle,
member_ids: uniqueMemberIds,
},
});
setChat(created);
setMessages([]);
setText("");
} catch (requestError) {
setError(requestError.message);
} finally {
setLoading(false);
}
}
async function handleSendMessage() {
if (!chat || !token) {
return;
}
setError("");
setLoading(true);
try {
const message = await apiFetch(`/chats/${chat.id}/messages`, {
method: "POST",
token,
body: { text },
});
setMessages((previous) => [...previous, message]);
setText("");
} catch (requestError) {
setError(requestError.message);
} finally {
setLoading(false);
}
}
async function handleLoadHistory() {
if (!chat || !token) {
return;
}
setError("");
setLoading(true);
try {
const page = await apiFetch(`/chats/${chat.id}/messages?limit=100`, {
token,
});
setMessages(page.items);
} catch (requestError) {
setError(requestError.message);
} finally {
setLoading(false);
}
}
async function handleLogout() {
if (!token) {
return;
}
setError("");
setLoading(true);
try {
await apiFetch("/auth/sessions/current", {
method: "DELETE",
token,
});
setSession(null);
setChat(null);
setMessages([]);
setText("");
setMemberIdsInput("");
setChatTitle("");
} catch (requestError) {
setError(requestError.message);
// Если token уже истёк или был отозван, локальная сессия всё равно
// недействительна, поэтому её следует очистить.
if (
requestError.message.includes("Authentication") ||
requestError.message.includes("401")
) {
setSession(null);
setChat(null);
setMessages([]);
}
} finally {
setLoading(false);
}
}
return (
<div
style={{
maxWidth: 560,
margin: "2rem auto",
fontFamily: "sans-serif",
}}
>
<h1>Lab2 Messenger — демо-клиент</h1>
{error && (
<p
role="alert"
style={{
color: "#b00020",
background: "#ffe7eb",
padding: "0.75rem",
borderRadius: "0.25rem",
}}
>
{error}
</p>
)}
{!me && (
<section>
<h2>Регистрация и вход</h2>
<p>
После регистрации клиент автоматически создаст сессию через Basic
authentication и начнёт использовать Bearer-token.
</p>
<input
placeholder="username: a-z, 0-9, _"
value={username}
onChange={(event) => setUsername(event.target.value)}
autoComplete="username"
/>
<input
placeholder="display name"
value={displayName}
onChange={(event) => setDisplayName(event.target.value)}
autoComplete="name"
/>
<input
type="password"
placeholder="пароль: 12–128 символов"
value={password}
onChange={(event) => setPassword(event.target.value)}
autoComplete="new-password"
/>
<button
type="button"
onClick={handleRegister}
disabled={loading}
>
{loading ? "Выполняется…" : "Зарегистрироваться и войти"}
</button>
</section>
)}
{me && !chat && (
<section>
<p>
Вошли как <b>{me.username}</b>
</p>
<p style={{ overflowWrap: "anywhere" }}>
ID пользователя: {me.id}
</p>
<button
type="button"
onClick={handleLogout}
disabled={loading}
>
Выйти
</button>
<h2>Создать чат</h2>
<input
placeholder="название чата"
value={chatTitle}
onChange={(event) => setChatTitle(event.target.value)}
/>
<input
placeholder="UUID других участников через запятую"
value={memberIdsInput}
onChange={(event) => setMemberIdsInput(event.target.value)}
/>
<button
type="button"
onClick={handleCreateChat}
disabled={loading}
>
{loading ? "Создаётся…" : "Создать чат"}
</button>
</section>
)}
{me && chat && (
<section>
<p>
Вошли как <b>{me.username}</b>
</p>
<button
type="button"
onClick={handleLogout}
disabled={loading}
>
Выйти
</button>
<h2>Чат: {chat.title}</h2>
<p>
Участники: {chat.member_ids.length}
</p>
<button
type="button"
onClick={handleLoadHistory}
disabled={loading}
>
{loading ? "Загружается…" : "Обновить историю"}
</button>
<ul>
{messages.map((message) => (
<li key={message.id}>
<b>
{message.sender_id === me.id
? "Я"
: message.sender_id}
:
</b>{" "}
{message.text}
</li>
))}
</ul>
<input
placeholder="текст сообщения"
value={text}
onChange={(event) => setText(event.target.value)}
/>
<button
type="button"
onClick={handleSendMessage}
disabled={loading}
>
{loading ? "Отправляется…" : "Отправить"}
</button>
</section>
)}
</div>
);
}
View File
+179
View File
@@ -0,0 +1,179 @@
"""Valkey session cache.
PostgreSQL is the source of truth for sessions. Valkey only keeps a short
lived copy of "token hash -> user" to avoid a SQL lookup on every request:
- key: messenger:session:<sha256(token)>, the raw token is never stored;
- value TTL: min(SESSION_CACHE_TTL_SECONDS, remaining session lifetime),
and expires_at is checked again on every read;
- logout writes a "revoked" tombstone (SET ... EX, overwrite), while cache
population uses SET ... NX, so a concurrent request cannot resurrect a
revoked session in the cache;
- any Valkey error or timeout is a cache miss: requests go to PostgreSQL and
the cache is skipped for CACHE_RETRY_AFTER_SECONDS. After such an error,
and on every API process start, the cache is flushed before its next use,
because an invalidation may have been lost while Valkey was unreachable
(also by a previous API process).
"""
from __future__ import annotations
import asyncio
import json
import logging
import math
import time
from datetime import datetime, timezone
from typing import Any
from uuid import UUID
from redis.asyncio import ConnectionPool, Redis
from redis.exceptions import RedisError
from app.config import settings
logger = logging.getLogger("messenger.cache")
KEY_PREFIX = "messenger:session:"
REVOKED = "revoked"
class Revoked:
"""Marker returned when the cache knows the session was revoked."""
REVOKED_SESSION = Revoked()
def _key(token_hash: str) -> str:
return KEY_PREFIX + token_hash
def _serialize(user: dict[str, Any], expires_at: datetime) -> str:
return json.dumps(
{
"id": str(user["id"]),
"username": user["username"],
"display_name": user["display_name"],
"created_at": user["created_at"].isoformat(),
"expires_at": expires_at.isoformat(),
},
separators=(",", ":"),
)
def _deserialize(raw: str) -> tuple[dict[str, Any], datetime]:
payload = json.loads(raw)
user = {
"id": UUID(payload["id"]),
"username": payload["username"],
"display_name": payload["display_name"],
"created_at": datetime.fromisoformat(payload["created_at"]),
}
return user, datetime.fromisoformat(payload["expires_at"])
class SessionCache:
def __init__(self, url: str | None) -> None:
self._client: Redis | None = None
self._unavailable_until = 0.0
# A process never trusts a cache it has not flushed itself: an
# earlier process may have lost an invalidation (logout while
# Valkey was unreachable) and that knowledge died with it.
# Cleared only after a successful FLUSHDB.
self._needs_flush = True
if url:
pool = ConnectionPool.from_url(
url,
max_connections=settings.cache_max_connections,
socket_timeout=settings.cache_timeout_seconds,
socket_connect_timeout=settings.cache_timeout_seconds,
decode_responses=True,
)
self._client = Redis(connection_pool=pool)
@property
def enabled(self) -> bool:
return self._client is not None
async def _run(self, operation):
"""Run one cache operation; return (ok, result)."""
if self._client is None:
return False, None
if time.monotonic() < self._unavailable_until:
return False, None
try:
async with asyncio.timeout(settings.cache_timeout_seconds * 2):
if self._needs_flush:
await self._client.flushdb()
self._needs_flush = False
logger.warning("session cache flushed before use")
return True, await operation(self._client)
except (RedisError, OSError, TimeoutError) as exc:
self._unavailable_until = (
time.monotonic() + settings.cache_retry_after_seconds
)
self._needs_flush = True
logger.warning(
"session cache unavailable, falling back to PostgreSQL: %s",
type(exc).__name__,
)
return False, None
async def get(
self,
token_hash: str,
) -> dict[str, Any] | Revoked | None:
ok, raw = await self._run(lambda client: client.get(_key(token_hash)))
if not ok or raw is None:
return None
if raw == REVOKED:
return REVOKED_SESSION
try:
user, expires_at = _deserialize(raw)
except (ValueError, KeyError, TypeError):
return None
if expires_at <= datetime.now(timezone.utc):
return None
return user
async def put(
self,
token_hash: str,
user: dict[str, Any],
expires_at: datetime,
) -> None:
remaining = (expires_at - datetime.now(timezone.utc)).total_seconds()
ttl = min(settings.session_cache_ttl_seconds, math.floor(remaining))
if ttl < 1:
return
value = _serialize(user, expires_at)
await self._run(
lambda client: client.set(_key(token_hash), value, ex=ttl, nx=True)
)
async def revoke(self, token_hash: str) -> None:
await self._run(
lambda client: client.set(
_key(token_hash),
REVOKED,
ex=settings.session_cache_ttl_seconds,
)
)
async def close(self) -> None:
if self._client is not None:
await self._client.aclose()
session_cache = SessionCache(settings.cache_url)
+92
View File
@@ -0,0 +1,92 @@
from dataclasses import dataclass
from pathlib import Path
import os
def read_value(name: str, default: str | None = None) -> str:
file_name = os.getenv(f"{name}_FILE")
if file_name:
return Path(file_name).read_text(encoding="utf-8").strip()
value = os.getenv(name, default)
if value is None:
raise RuntimeError(f"{name} is required.")
return value
def read_positive_int(name: str, default: str) -> int:
value = int(os.getenv(name, default))
if value < 1:
raise RuntimeError(f"{name} must be positive.")
return value
def read_positive_float(name: str, default: str) -> float:
value = float(os.getenv(name, default))
if value <= 0:
raise RuntimeError(f"{name} must be positive.")
return value
@dataclass(frozen=True)
class Settings:
app_host: str
app_port: int
database_url: str
session_ttl_seconds: int
# PostgreSQL connection pool and timeouts.
db_pool_size: int
db_max_overflow: int
db_pool_timeout_seconds: float
db_connect_timeout_seconds: float
db_statement_timeout_ms: int
# Valkey is a session cache; PostgreSQL stays the source of truth.
cache_url: str | None
session_cache_ttl_seconds: int
cache_timeout_seconds: float
cache_max_connections: int
cache_retry_after_seconds: float
def load_settings() -> Settings:
session_store = os.getenv("SESSION_STORE", "postgres").lower()
if session_store not in {"postgres", "valkey", "redis"}:
raise RuntimeError("SESSION_STORE must be postgres, valkey or redis.")
cache_url = None
if session_store != "postgres":
cache_url = read_value("CACHE_URL")
return Settings(
app_host=os.getenv("APP_HOST", "0.0.0.0"),
app_port=int(os.getenv("APP_PORT", "8080")),
database_url=read_value("DATABASE_URL"),
session_ttl_seconds=read_positive_int("SESSION_TTL_SECONDS", "3600"),
db_pool_size=read_positive_int("DB_POOL_SIZE", "10"),
db_max_overflow=int(os.getenv("DB_MAX_OVERFLOW", "5")),
db_pool_timeout_seconds=read_positive_float("DB_POOL_TIMEOUT_SECONDS", "3"),
db_connect_timeout_seconds=read_positive_float(
"DB_CONNECT_TIMEOUT_SECONDS", "3"
),
db_statement_timeout_ms=read_positive_int("DB_STATEMENT_TIMEOUT_MS", "5000"),
cache_url=cache_url,
session_cache_ttl_seconds=read_positive_int(
"SESSION_CACHE_TTL_SECONDS", "60"
),
cache_timeout_seconds=read_positive_float("CACHE_TIMEOUT_SECONDS", "0.25"),
cache_max_connections=read_positive_int("CACHE_MAX_CONNECTIONS", "20"),
cache_retry_after_seconds=read_positive_float(
"CACHE_RETRY_AFTER_SECONDS", "5"
),
)
settings = load_settings()
+57
View File
@@ -0,0 +1,57 @@
from collections.abc import AsyncGenerator
from sqlalchemy.ext.asyncio import (
AsyncSession,
async_sessionmaker,
create_async_engine,
)
from app.config import settings
database_url = settings.database_url.replace(
"postgresql://",
"postgresql+asyncpg://",
1,
)
# Bounded pool: at most db_pool_size + db_max_overflow connections per API
# process. Waiting for a free connection, connecting and every statement are
# limited, so an unavailable database produces a fast 503 instead of a hang.
engine = create_async_engine(
database_url,
pool_pre_ping=True,
pool_size=settings.db_pool_size,
max_overflow=settings.db_max_overflow,
pool_timeout=settings.db_pool_timeout_seconds,
pool_recycle=1800,
connect_args={
"timeout": settings.db_connect_timeout_seconds,
"command_timeout": settings.db_statement_timeout_ms / 1000 + 1,
"server_settings": {
"statement_timeout": str(settings.db_statement_timeout_ms),
"idle_in_transaction_session_timeout": "10000",
"application_name": "messenger-api",
},
},
)
SessionLocal = async_sessionmaker(
bind=engine,
expire_on_commit=False,
autoflush=False,
)
async def get_db() -> AsyncGenerator[AsyncSession, None]:
async with SessionLocal() as session:
yield session
async def check_database_ready() -> bool:
try:
async with engine.connect() as connection:
await connection.exec_driver_sql("SELECT 1")
return True
except Exception:
return False
+61
View File
@@ -0,0 +1,61 @@
"""
FastAPI dependencies for Lab2:
- Bearer authentication;
- pagination query parameters.
"""
from typing import Optional
from fastapi import Depends, Query, Request, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBasic, HTTPBearer
from sqlalchemy.ext.asyncio import AsyncSession
from app.db import get_db
from app.errors import Unauthorized
from app.services import current_user_from_bearer_token
# Security schemes make the "Authorize" button in /docs send real
# Authorization headers. Errors keep the contract format: auto_error=False
# and our own 401 responses.
bearer_scheme = HTTPBearer(
scheme_name="Bearer",
auto_error=False,
description="Opaque session token from POST /api/v1/auth/sessions.",
)
class BasicForDocs(HTTPBasic):
"""Documents Basic auth; the header is parsed by app.security."""
async def __call__(self, request: Request) -> None: # type: ignore[override]
return None
basic_scheme = BasicForDocs(
scheme_name="Basic",
auto_error=False,
description="Only for POST /api/v1/auth/sessions.",
)
async def require_user(
credentials: Optional[HTTPAuthorizationCredentials] = Security(
bearer_scheme
),
db: AsyncSession = Depends(get_db),
) -> dict:
if credentials is None or not credentials.credentials.strip():
raise Unauthorized("Bearer")
return await current_user_from_bearer_token(
db,
credentials.credentials.strip(),
)
def pagination_params(
limit: int = Query(default=50, ge=1, le=100),
cursor: Optional[str] = Query(default=None, min_length=1),
) -> tuple[int, Optional[str]]:
return limit, cursor
+79
View File
@@ -0,0 +1,79 @@
from fastapi import Request
from fastapi.responses import JSONResponse
from uuid import uuid4
class ApiError(Exception):
def __init__(
self,
status_code: int,
code: str,
message: str,
headers: dict[str, str] | None = None,
) -> None:
self.status_code = status_code
self.code = code
self.message = message
self.headers = headers or {}
class InvalidRequest(ApiError):
def __init__(self, message: str = "Invalid request.") -> None:
super().__init__(400, "invalid_request", message)
class Unauthorized(ApiError):
def __init__(self, scheme: str = "Bearer") -> None:
if scheme == "Basic":
challenge = 'Basic realm="messenger", charset="UTF-8"'
else:
challenge = 'Bearer realm="messenger"'
super().__init__(
401,
"unauthorized",
"Authentication is required.",
{"WWW-Authenticate": challenge},
)
class NotFound(ApiError):
def __init__(self, message: str = "Object not found.") -> None:
super().__init__(404, "not_found", message)
class Conflict(ApiError):
def __init__(self, message: str = "Conflict.") -> None:
super().__init__(409, "conflict", message)
class Unavailable(ApiError):
def __init__(self) -> None:
super().__init__(503, "unavailable", "Service is unavailable.")
def request_id(request: Request) -> str:
return getattr(request.state, "request_id", str(uuid4()))
async def api_error_handler(
request: Request,
exc: ApiError,
) -> JSONResponse:
rid = request_id(request)
headers = {
"X-Request-Id": rid,
**exc.headers,
}
return JSONResponse(
status_code=exc.status_code,
content={
"error": {
"code": exc.code,
"message": exc.message,
"request_id": rid,
}
},
headers=headers,
)
+329
View File
@@ -0,0 +1,329 @@
from __future__ import annotations
import logging
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from uuid import UUID, uuid4
from fastapi import Depends, FastAPI, Request, Response, Security
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from sqlalchemy import exc as sa_exc
from sqlalchemy.ext.asyncio import AsyncSession
from app.cache import session_cache
from app.db import check_database_ready, engine, get_db
from app.deps import basic_scheme, pagination_params, require_user
from app.errors import ApiError, Unavailable, api_error_handler
from app.models import (
Chat,
ChatPage,
CreateChat,
CreateMessage,
CreateUser,
Health,
Message,
MessagePage,
Session,
User,
)
from app.services import (
create_chat,
create_message,
create_user_session,
get_chat,
list_chats,
list_messages,
logout_current_session,
register_user,
)
@asynccontextmanager
async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
yield
await session_cache.close()
await engine.dispose()
app = FastAPI(
title="MTUSI Messenger — лабораторная 2",
version="1.2.0",
lifespan=lifespan,
)
@app.middleware("http")
async def add_request_id(request: Request, call_next):
request.state.request_id = (
request.headers.get("X-Request-Id")
or str(uuid4())
)
response = await call_next(request)
response.headers["X-Request-Id"] = request.state.request_id
return response
@app.exception_handler(ApiError)
async def handle_api_error(
request: Request,
exc: Exception,
) -> JSONResponse:
if not isinstance(exc, ApiError):
raise exc
return await api_error_handler(request, exc)
@app.exception_handler(RequestValidationError)
async def validation_error_handler(
request: Request,
_exc: RequestValidationError,
) -> JSONResponse:
request_id = getattr(request.state, "request_id", str(uuid4()))
return JSONResponse(
status_code=400,
content={
"error": {
"code": "invalid_request",
"message": "Invalid request.",
"request_id": request_id,
}
},
headers={
"X-Request-Id": request_id,
},
)
logger = logging.getLogger("messenger.api")
def is_dependency_failure(exc: Exception) -> bool:
"""PostgreSQL is unreachable, restarting, overloaded or timed out."""
if isinstance(
exc,
(
sa_exc.OperationalError,
sa_exc.InterfaceError,
sa_exc.TimeoutError, # connection pool exhausted
OSError,
TimeoutError,
),
):
return True
return isinstance(exc, sa_exc.DBAPIError) and exc.connection_invalidated
async def dependency_error_handler(
request: Request,
exc: Exception,
) -> JSONResponse:
if not is_dependency_failure(exc):
return await unexpected_error_handler(request, exc)
logger.warning("database unavailable: %s", type(exc).__name__)
return await api_error_handler(request, Unavailable())
for _exc_class in (sa_exc.DBAPIError, sa_exc.TimeoutError, OSError, TimeoutError):
app.add_exception_handler(_exc_class, dependency_error_handler)
@app.exception_handler(Exception)
async def unexpected_error_handler(
request: Request,
exc: Exception,
) -> JSONResponse:
request_id = getattr(request.state, "request_id", str(uuid4()))
# Only the type: SQL parameters and headers may contain secrets.
logger.error("unexpected error: %s", type(exc).__name__)
return JSONResponse(
status_code=500,
content={
"error": {
"code": "internal_error",
"message": "Internal server error.",
"request_id": request_id,
}
},
headers={
"X-Request-Id": request_id,
},
)
@app.get(
"/health/live",
response_model=Health,
)
async def liveness() -> dict[str, str]:
return {"status": "ok"}
@app.get(
"/health/ready",
response_model=Health,
)
async def readiness() -> dict[str, str]:
if not await check_database_ready():
raise Unavailable()
return {"status": "ok"}
@app.post(
"/api/v1/users",
status_code=201,
response_model=User,
)
async def register_user_route(
payload: CreateUser,
db: AsyncSession = Depends(get_db),
):
return await register_user(
db,
username=payload.username,
display_name=payload.display_name,
password=payload.password,
)
@app.post(
"/api/v1/auth/sessions",
status_code=201,
response_model=Session,
)
async def login(
request: Request,
db: AsyncSession = Depends(get_db),
_basic: None = Security(basic_scheme),
):
return await create_user_session(
db,
request.headers.get("Authorization"),
)
@app.delete(
"/api/v1/auth/sessions/current",
status_code=204,
)
async def logout(
request: Request,
db: AsyncSession = Depends(get_db),
_current_user: dict = Depends(require_user),
) -> Response:
_, _, token = request.headers["Authorization"].partition(" ")
await logout_current_session(
db,
token.strip(),
)
return Response(status_code=204)
@app.get(
"/api/v1/users/me",
response_model=User,
)
async def current_user_route(
current_user: dict = Depends(require_user),
):
return current_user
@app.post(
"/api/v1/chats",
status_code=201,
response_model=Chat,
)
async def create_chat_route(
payload: CreateChat,
current_user: dict = Depends(require_user),
db: AsyncSession = Depends(get_db),
):
return await create_chat(
db,
title=payload.title,
member_ids=payload.member_ids,
current_user=current_user,
)
@app.get(
"/api/v1/chats",
response_model=ChatPage,
)
async def list_chats_route(
page: tuple[int, str | None] = Depends(pagination_params),
current_user: dict = Depends(require_user),
db: AsyncSession = Depends(get_db),
):
limit, cursor = page
return await list_chats(
db,
limit=limit,
cursor=cursor,
current_user=current_user,
)
@app.get(
"/api/v1/chats/{chat_id}",
response_model=Chat,
)
async def get_chat_route(
chat_id: UUID,
current_user: dict = Depends(require_user),
db: AsyncSession = Depends(get_db),
):
return await get_chat(
db,
chat_id=chat_id,
current_user=current_user,
)
@app.post(
"/api/v1/chats/{chat_id}/messages",
status_code=201,
response_model=Message,
)
async def create_message_route(
chat_id: UUID,
payload: CreateMessage,
current_user: dict = Depends(require_user),
db: AsyncSession = Depends(get_db),
):
return await create_message(
db,
chat_id=chat_id,
text_value=payload.text,
current_user=current_user,
)
@app.get(
"/api/v1/chats/{chat_id}/messages",
response_model=MessagePage,
)
async def list_messages_route(
chat_id: UUID,
page: tuple[int, str | None] = Depends(pagination_params),
current_user: dict = Depends(require_user),
db: AsyncSession = Depends(get_db),
):
limit, cursor = page
return await list_messages(
db,
chat_id=chat_id,
limit=limit,
cursor=cursor,
current_user=current_user,
)
+148
View File
@@ -0,0 +1,148 @@
from __future__ import annotations
from datetime import datetime, timezone
from typing import Literal
from uuid import UUID
from pydantic import BaseModel, ConfigDict, Field, field_validator
class ApiModel(BaseModel):
model_config = ConfigDict(extra="forbid")
class CreateUser(ApiModel):
username: str = Field(
min_length=3,
max_length=32,
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("username")
@classmethod
def username_is_not_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError("username must not contain only spaces.")
return value
@field_validator("display_name")
@classmethod
def display_name_is_not_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError(
"display_name must not contain only spaces."
)
return value
@field_validator("password")
@classmethod
def password_is_not_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError("password must not contain only spaces.")
return value
class User(ApiModel):
id: UUID
username: str
display_name: str
created_at: datetime
@field_validator("created_at")
@classmethod
def user_time_is_utc(cls, value: datetime) -> datetime:
if value.tzinfo is None:
raise ValueError("created_at must include UTC timezone.")
return value.astimezone(timezone.utc)
class CreateChat(ApiModel):
title: str = Field(min_length=1, max_length=255)
member_ids: list[UUID] = Field(min_length=1)
@field_validator("title")
@classmethod
def title_is_not_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError("title must not contain only spaces.")
return value
class Chat(ApiModel):
id: UUID
title: str
member_ids: list[UUID]
created_at: datetime
@field_validator("created_at")
@classmethod
def chat_time_is_utc(cls, value: datetime) -> datetime:
if value.tzinfo is None:
raise ValueError("created_at must include UTC timezone.")
return value.astimezone(timezone.utc)
class ChatPage(ApiModel):
items: list[Chat]
next_cursor: str | None = None
class CreateMessage(ApiModel):
text: str = Field(min_length=1, max_length=4000)
@field_validator("text")
@classmethod
def text_is_not_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError("text must not contain only spaces.")
return value
class Message(ApiModel):
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: datetime
@field_validator("created_at")
@classmethod
def message_time_is_utc(cls, value: datetime) -> datetime:
if value.tzinfo is None:
raise ValueError("created_at must include UTC timezone.")
return value.astimezone(timezone.utc)
class MessagePage(ApiModel):
items: list[Message]
next_cursor: str | None = None
class Session(ApiModel):
token: str = Field(min_length=1)
token_type: Literal["Bearer"]
expires_at: datetime
user: User
@field_validator("expires_at")
@classmethod
def expiry_time_is_utc(cls, value: datetime) -> datetime:
if value.tzinfo is None:
raise ValueError("expires_at must include UTC timezone.")
return value.astimezone(timezone.utc)
class Health(ApiModel):
status: Literal["ok"]
class ErrorInner(ApiModel):
code: str = Field(min_length=1)
message: str = Field(min_length=1)
request_id: str = Field(min_length=1)
class Error(ApiModel):
error: ErrorInner
+358
View File
@@ -0,0 +1,358 @@
"""PostgreSQL repository functions for MTUSI Messenger Lab2."""
from __future__ import annotations
from collections.abc import Iterable
from datetime import datetime
from typing import Any
from uuid import UUID, uuid4
from sqlalchemy import text
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
async def create_user(
db: AsyncSession,
*,
username: str,
display_name: str,
password_hash: str,
) -> dict[str, Any] | None:
user_id = uuid4()
try:
result = await db.execute(
text(
"""
INSERT INTO users (id, username, display_name, password_hash)
VALUES (:id, :username, :display_name, :password_hash)
RETURNING id, username, display_name, created_at
"""
),
{
"id": user_id,
"username": username,
"display_name": display_name,
"password_hash": password_hash,
},
)
await db.commit()
return dict(result.mappings().one())
except IntegrityError:
await db.rollback()
return None
async def get_user_by_username(
db: AsyncSession,
username: str,
) -> dict[str, Any] | None:
result = await db.execute(
text(
"""
SELECT id, username, display_name, password_hash, created_at
FROM users
WHERE username = :username
"""
),
{"username": username},
)
row = result.mappings().first()
return dict(row) if row is not None else None
async def get_user_by_id(
db: AsyncSession,
user_id: UUID,
) -> dict[str, Any] | None:
result = await db.execute(
text(
"""
SELECT id, username, display_name, created_at
FROM users
WHERE id = :user_id
"""
),
{"user_id": user_id},
)
row = result.mappings().first()
return dict(row) if row is not None else None
async def user_ids_that_exist(
db: AsyncSession,
member_ids: Iterable[UUID],
) -> set[UUID]:
values = list(member_ids)
if not values:
return set()
result = await db.execute(
text("SELECT id FROM users WHERE id = ANY(CAST(:member_ids AS uuid[]))"),
{"member_ids": values},
)
return {row.id for row in result}
async def create_session(
db: AsyncSession,
*,
user_id: UUID,
token_hash: str,
expires_at: datetime,
) -> None:
await db.execute(
text(
"""
INSERT INTO sessions (id, user_id, token_hash, expires_at)
VALUES (:id, :user_id, :token_hash, :expires_at)
"""
),
{
"id": uuid4(),
"user_id": user_id,
"token_hash": token_hash,
"expires_at": expires_at,
},
)
await db.commit()
async def get_active_session_user(
db: AsyncSession,
token_hash: str,
) -> dict[str, Any] | None:
result = await db.execute(
text(
"""
SELECT
s.id AS session_id,
s.token_hash,
s.expires_at,
u.id,
u.username,
u.display_name,
u.created_at
FROM sessions AS s
JOIN users AS u ON u.id = s.user_id
WHERE s.token_hash = :token_hash
AND s.revoked_at IS NULL
AND s.expires_at > now()
"""
),
{"token_hash": token_hash},
)
row = result.mappings().first()
return dict(row) if row is not None else None
async def revoke_active_session(
db: AsyncSession,
token_hash: str,
) -> bool:
result = await db.execute(
text(
"""
UPDATE sessions
SET revoked_at = now()
WHERE token_hash = :token_hash
AND revoked_at IS NULL
AND expires_at > now()
"""
),
{"token_hash": token_hash},
)
await db.commit()
return result.rowcount == 1
async def create_chat_with_members(
db: AsyncSession,
*,
title: str,
member_ids: Iterable[UUID],
) -> dict[str, Any]:
chat_id = uuid4()
members = list(member_ids)
try:
result = await db.execute(
text(
"""
INSERT INTO chats (id, title)
VALUES (:id, :title)
RETURNING id, title, created_at
"""
),
{"id": chat_id, "title": title},
)
chat = dict(result.mappings().one())
await db.execute(
text(
"""
INSERT INTO chat_members (chat_id, user_id)
VALUES (:chat_id, :user_id)
"""
),
[{"chat_id": chat_id, "user_id": user_id} for user_id in members],
)
await db.commit()
except Exception:
await db.rollback()
raise
chat["member_ids"] = members
return chat
async def get_accessible_chat(
db: AsyncSession,
*,
chat_id: UUID,
user_id: UUID,
) -> dict[str, Any] | None:
result = await db.execute(
text(
"""
SELECT c.id, c.title, c.created_at
FROM chats AS c
JOIN chat_members AS own_membership
ON own_membership.chat_id = c.id
AND own_membership.user_id = :user_id
WHERE c.id = :chat_id
"""
),
{"chat_id": chat_id, "user_id": user_id},
)
chat_row = result.mappings().first()
if chat_row is None:
return None
members_result = await db.execute(
text(
"""
SELECT user_id
FROM chat_members
WHERE chat_id = :chat_id
ORDER BY user_id ASC
"""
),
{"chat_id": chat_id},
)
chat = dict(chat_row)
chat["member_ids"] = [row.user_id for row in members_result]
return chat
async def list_chats_for_user(
db: AsyncSession,
*,
user_id: UUID,
limit: int,
cursor_created_at: datetime | None,
cursor_id: UUID | None,
) -> list[dict[str, Any]]:
query = """
SELECT c.id, c.title, c.created_at
FROM chats AS c
JOIN chat_members AS own_membership
ON own_membership.chat_id = c.id
AND own_membership.user_id = :user_id \
"""
params: dict[str, Any] = {
"user_id": user_id,
"limit_plus_one": limit + 1,
}
if cursor_created_at is not None and cursor_id is not None:
query += """
WHERE (c.created_at, c.id) > (:cursor_created_at, :cursor_id)
"""
params["cursor_created_at"] = cursor_created_at
params["cursor_id"] = cursor_id
query += " ORDER BY c.created_at ASC, c.id ASC LIMIT :limit_plus_one"
result = await db.execute(text(query), params)
chats = [dict(row) for row in result.mappings().all()]
if not chats:
return []
chat_ids = [chat["id"] for chat in chats]
members_result = await db.execute(
text(
"""
SELECT chat_id, user_id
FROM chat_members
WHERE chat_id = ANY(CAST(:chat_ids AS uuid[]))
ORDER BY chat_id ASC, user_id ASC
"""
),
{"chat_ids": chat_ids},
)
members_by_chat: dict[UUID, list[UUID]] = {chat_id: [] for chat_id in chat_ids}
for row in members_result:
members_by_chat[row.chat_id].append(row.user_id)
for chat in chats:
chat["member_ids"] = members_by_chat[chat["id"]]
return chats
async def create_message(
db: AsyncSession,
*,
chat_id: UUID,
sender_id: UUID,
text_value: str,
) -> dict[str, Any]:
message_id = uuid4()
result = await db.execute(
text(
"""
INSERT INTO messages (id, chat_id, sender_id, text)
VALUES (:id, :chat_id, :sender_id, :text)
RETURNING id, chat_id, sender_id, text, created_at
"""
),
{
"id": message_id,
"chat_id": chat_id,
"sender_id": sender_id,
"text": text_value,
},
)
await db.commit()
return dict(result.mappings().one())
async def list_messages_keyset(
db: AsyncSession,
*,
chat_id: UUID,
limit: int,
cursor_created_at: datetime | None,
cursor_id: UUID | None,
) -> list[dict[str, Any]]:
query = """
SELECT id, chat_id, sender_id, text, created_at
FROM messages
WHERE chat_id = :chat_id \
"""
params: dict[str, Any] = {
"chat_id": chat_id,
"limit_plus_one": limit + 1,
}
if cursor_created_at is not None and cursor_id is not None:
query += """
AND (created_at, id) > (:cursor_created_at, :cursor_id)
"""
params["cursor_created_at"] = cursor_created_at
params["cursor_id"] = cursor_id
query += " ORDER BY created_at ASC, id ASC LIMIT :limit_plus_one"
result = await db.execute(text(query), params)
return [dict(row) for row in result.mappings().all()]
+162
View File
@@ -0,0 +1,162 @@
from __future__ import annotations
import base64
import binascii
import hashlib
import json
import secrets
from datetime import datetime, timezone
from uuid import UUID
from argon2 import PasswordHasher
from argon2.exceptions import InvalidHashError, VerifyMismatchError
password_hasher = PasswordHasher()
def hash_password(password: str) -> str:
return password_hasher.hash(password)
def verify_password(password_hash: str, password: str) -> bool:
try:
return password_hasher.verify(password_hash, password)
except (VerifyMismatchError, InvalidHashError):
return False
def generate_session_token() -> str:
return secrets.token_urlsafe(32)
def hash_session_token(token: str) -> str:
return hashlib.sha256(token.encode("utf-8")).hexdigest()
def parse_basic_authorization(value: str | None) -> tuple[str, str] | None:
if value is None or not value.startswith("Basic "):
return None
try:
encoded_credentials = value[len("Basic "):]
decoded = base64.b64decode(
encoded_credentials,
validate=True,
).decode("utf-8")
username, password = decoded.split(":", 1)
except (
ValueError,
UnicodeDecodeError,
binascii.Error,
):
return None
if not username or not username.isascii():
return None
return username, password
def _encode_cursor_payload(payload: dict[str, str]) -> str:
raw = json.dumps(
payload,
ensure_ascii=False,
separators=(",", ":"),
sort_keys=True,
).encode("utf-8")
return base64.urlsafe_b64encode(raw).decode("ascii")
def _decode_cursor_payload(cursor: str) -> dict[str, str] | None:
try:
raw = base64.urlsafe_b64decode(cursor.encode("ascii"))
payload = json.loads(raw.decode("utf-8"))
if not isinstance(payload, dict):
return None
return payload
except (
ValueError,
TypeError,
UnicodeDecodeError,
binascii.Error,
):
return None
def _utc_timestamp(value: datetime) -> str:
if value.tzinfo is None:
raise ValueError("Cursor datetime must be timezone-aware.")
return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
def encode_chat_cursor(
created_at: datetime,
chat_id: UUID,
) -> str:
return _encode_cursor_payload(
{
"kind": "chat",
"created_at": _utc_timestamp(created_at),
"id": str(chat_id),
}
)
def decode_chat_cursor(
cursor: str,
) -> tuple[datetime, UUID] | None:
payload = _decode_cursor_payload(cursor)
if payload is None or payload.get("kind") != "chat":
return None
try:
created_at = datetime.fromisoformat(
payload["created_at"].replace("Z", "+00:00")
)
chat_id = UUID(payload["id"])
except (KeyError, ValueError, AttributeError):
return None
return created_at, chat_id
def encode_message_cursor(
chat_id: UUID,
created_at: datetime,
message_id: UUID,
) -> str:
return _encode_cursor_payload(
{
"kind": "message",
"chat_id": str(chat_id),
"created_at": _utc_timestamp(created_at),
"id": str(message_id),
}
)
def decode_message_cursor(
cursor: str,
) -> tuple[UUID, datetime, UUID] | None:
payload = _decode_cursor_payload(cursor)
if payload is None or payload.get("kind") != "message":
return None
try:
chat_id = UUID(payload["chat_id"])
created_at = datetime.fromisoformat(
payload["created_at"].replace("Z", "+00:00")
)
message_id = UUID(payload["id"])
except (KeyError, ValueError, AttributeError):
return None
return chat_id, created_at, message_id
+372
View File
@@ -0,0 +1,372 @@
"""Business rules for MTUSI Messenger Lab2."""
from __future__ import annotations
from datetime import datetime, timedelta, timezone
from typing import Any
from uuid import UUID
from sqlalchemy.ext.asyncio import AsyncSession
from app import repositories
from app.cache import REVOKED_SESSION, session_cache
from app.config import settings
from app.errors import ApiError
from app.security import (
decode_chat_cursor,
decode_message_cursor,
encode_chat_cursor,
encode_message_cursor,
generate_session_token,
hash_password,
hash_session_token,
parse_basic_authorization,
verify_password,
)
def _utc_now() -> datetime:
return datetime.now(timezone.utc)
def _to_user(row: dict[str, Any]) -> dict[str, Any]:
return {
"id": row["id"],
"username": row["username"],
"display_name": row["display_name"],
"created_at": row["created_at"],
}
def _to_chat(row: dict[str, Any]) -> dict[str, Any]:
return {
"id": row["id"],
"title": row["title"],
"member_ids": row["member_ids"],
"created_at": row["created_at"],
}
def _to_message(row: dict[str, Any]) -> dict[str, Any]:
return {
"id": row["id"],
"chat_id": row["chat_id"],
"sender_id": row["sender_id"],
"text": row["text"],
"created_at": row["created_at"],
}
def _bearer_unauthorized() -> ApiError:
return ApiError(
401,
"unauthorized",
"Authentication is required.",
headers={
"WWW-Authenticate": 'Bearer realm="messenger"',
},
)
def _basic_unauthorized() -> ApiError:
return ApiError(
401,
"unauthorized",
"Invalid credentials.",
headers={
"WWW-Authenticate": (
'Basic realm="messenger", charset="UTF-8"'
),
},
)
def _invalid_request(message: str) -> ApiError:
return ApiError(400, "invalid_request", message)
def _not_found() -> ApiError:
return ApiError(404, "not_found", "Object not found.")
async def register_user(
db: AsyncSession,
*,
username: str,
display_name: str,
password: str,
) -> dict[str, Any]:
user = await repositories.create_user(
db,
username=username,
display_name=display_name,
password_hash=hash_password(password),
)
if user is None:
raise ApiError(
409,
"conflict",
"Username is already taken.",
)
return _to_user(user)
async def create_user_session(
db: AsyncSession,
authorization: str | None,
) -> dict[str, Any]:
credentials = parse_basic_authorization(authorization)
if credentials is None:
raise _basic_unauthorized()
username, password = credentials
user = await repositories.get_user_by_username(db, username)
if user is None or not verify_password(
user["password_hash"],
password,
):
raise _basic_unauthorized()
token = generate_session_token()
expires_at = _utc_now() + timedelta(
seconds=settings.session_ttl_seconds
)
await repositories.create_session(
db,
user_id=user["id"],
token_hash=hash_session_token(token),
expires_at=expires_at,
)
return {
"token": token,
"token_type": "Bearer",
"expires_at": expires_at,
"user": _to_user(user),
}
async def current_user_from_bearer_token(
db: AsyncSession,
token: str,
) -> dict[str, Any]:
token_hash = hash_session_token(token)
cached = await session_cache.get(token_hash)
if cached is REVOKED_SESSION:
raise _bearer_unauthorized()
if cached is not None:
return cached
# Cache miss or cache unavailable: PostgreSQL decides.
session_user = await repositories.get_active_session_user(db, token_hash)
if session_user is None:
raise _bearer_unauthorized()
user = _to_user(session_user)
await session_cache.put(token_hash, user, session_user["expires_at"])
return user
async def logout_current_session(
db: AsyncSession,
token: str,
) -> None:
token_hash = hash_session_token(token)
revoked = await repositories.revoke_active_session(db, token_hash)
if not revoked:
raise _bearer_unauthorized()
# Invalidate after COMMIT in the source of truth.
await session_cache.revoke(token_hash)
async def create_chat(
db: AsyncSession,
*,
title: str,
member_ids: list[UUID],
current_user: dict[str, Any],
) -> dict[str, Any]:
unique_member_ids = set(member_ids)
if len(unique_member_ids) != len(member_ids):
raise _invalid_request(
"member_ids must not contain duplicates."
)
if current_user["id"] not in unique_member_ids:
raise _invalid_request(
"The current user must be included in member_ids."
)
existing_ids = await repositories.user_ids_that_exist(
db,
unique_member_ids,
)
if existing_ids != unique_member_ids:
raise _invalid_request(
"One or more member_ids do not exist."
)
chat = await repositories.create_chat_with_members(
db,
title=title,
member_ids=member_ids,
)
return _to_chat(chat)
async def get_chat(
db: AsyncSession,
*,
chat_id: UUID,
current_user: dict[str, Any],
) -> dict[str, Any]:
chat = await repositories.get_accessible_chat(
db,
chat_id=chat_id,
user_id=current_user["id"],
)
if chat is None:
raise _not_found()
return _to_chat(chat)
async def list_chats(
db: AsyncSession,
*,
limit: int,
cursor: str | None,
current_user: dict[str, Any],
) -> dict[str, Any]:
cursor_created_at: datetime | None = None
cursor_id: UUID | None = None
if cursor is not None:
decoded = decode_chat_cursor(cursor)
if decoded is None:
raise _invalid_request("Invalid cursor.")
cursor_created_at, cursor_id = decoded
rows = await repositories.list_chats_for_user(
db,
user_id=current_user["id"],
limit=limit,
cursor_created_at=cursor_created_at,
cursor_id=cursor_id,
)
has_more = len(rows) > limit
page = rows[:limit]
next_cursor = None
if has_more and page:
last = page[-1]
next_cursor = encode_chat_cursor(
last["created_at"],
last["id"],
)
return {
"items": [_to_chat(row) for row in page],
"next_cursor": next_cursor,
}
async def create_message(
db: AsyncSession,
*,
chat_id: UUID,
text_value: str,
current_user: dict[str, Any],
) -> dict[str, Any]:
chat = await repositories.get_accessible_chat(
db,
chat_id=chat_id,
user_id=current_user["id"],
)
if chat is None:
raise _not_found()
message = await repositories.create_message(
db,
chat_id=chat_id,
sender_id=current_user["id"],
text_value=text_value,
)
return _to_message(message)
async def list_messages(
db: AsyncSession,
*,
chat_id: UUID,
limit: int,
cursor: str | None,
current_user: dict[str, Any],
) -> dict[str, Any]:
chat = await repositories.get_accessible_chat(
db,
chat_id=chat_id,
user_id=current_user["id"],
)
if chat is None:
raise _not_found()
cursor_created_at: datetime | None = None
cursor_id: UUID | None = None
if cursor is not None:
decoded = decode_message_cursor(cursor)
if decoded is None:
raise _invalid_request("Invalid cursor.")
cursor_chat_id, cursor_created_at, cursor_id = decoded
if cursor_chat_id != chat_id:
raise _invalid_request(
"Cursor belongs to another chat."
)
rows = await repositories.list_messages_keyset(
db,
chat_id=chat_id,
limit=limit,
cursor_created_at=cursor_created_at,
cursor_id=cursor_id,
)
has_more = len(rows) > limit
page = rows[:limit]
next_cursor = None
if has_more and page:
last = page[-1]
next_cursor = encode_message_cursor(
chat_id,
last["created_at"],
last["id"],
)
return {
"items": [_to_message(row) for row in page],
"next_cursor": next_cursor,
}
-10
View File
@@ -1,10 +0,0 @@
# Topology worksheet, deliberately NOT a runnable stack (no application supplied).
# Implement compose.yaml or stack.yaml; do not submit this empty file as deployment.
# Service names below are logical roles, not imposed container names.
x-lab-number: 2
x-required-roles:
- api
- postgres
# TODO: implement real images/builds, network wiring, volumes, healthchecks,
# credentials and bootstrap. Details: contracts/infrastructure.json and README.md.
services: {}
+152
View File
@@ -0,0 +1,152 @@
x-api: &api
build:
context: .
dockerfile: Dockerfile
image: messenger-lab2-api:local
environment: &api-env
APP_HOST: 0.0.0.0
APP_PORT: "8080"
DATABASE_URL_FILE: /run/secrets/database_url
SESSION_TTL_SECONDS: "${SESSION_TTL_SECONDS:-3600}"
SESSION_STORE: valkey
CACHE_URL_FILE: /run/secrets/cache_url
SESSION_CACHE_TTL_SECONDS: "60"
CACHE_TIMEOUT_SECONDS: "0.25"
CACHE_MAX_CONNECTIONS: "20"
CACHE_RETRY_AFTER_SECONDS: "5"
DB_POOL_SIZE: "10"
DB_MAX_OVERFLOW: "5"
DB_POOL_TIMEOUT_SECONDS: "3"
DB_CONNECT_TIMEOUT_SECONDS: "3"
DB_STATEMENT_TIMEOUT_MS: "5000"
LOG_LEVEL: info
secrets:
- database_url
- cache_url
depends_on:
db:
condition: service_healthy
valkey:
condition: service_healthy
migrate:
condition: service_completed_successfully
networks:
- messenger_net
restart: unless-stopped
services:
db:
image: postgres:16.4-alpine
environment:
POSTGRES_DB: messenger
POSTGRES_USER: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets:
- postgres_password
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: [ "CMD-SHELL", "pg_isready -U messenger -d messenger" ]
interval: 5s
timeout: 3s
retries: 20
start_period: 5s
networks:
- messenger_net
restart: unless-stopped
# Session cache only. PostgreSQL is the source of truth, so the cache is
# intentionally not persisted: after restart/flush it is refilled on misses.
valkey:
image: valkey/valkey:8.0.1-alpine
command:
- sh
- -c
- >-
exec valkey-server
--requirepass "$$(cat /run/secrets/valkey_password)"
--save ""
--appendonly no
--maxmemory 64mb
--maxmemory-policy allkeys-lru
secrets:
- valkey_password
healthcheck:
test:
- CMD-SHELL
- valkey-cli -a "$$(cat /run/secrets/valkey_password)" --no-auth-warning ping | grep -q PONG
interval: 5s
timeout: 3s
retries: 20
networks:
- messenger_net
restart: unless-stopped
migrate:
build:
context: .
dockerfile: Dockerfile
image: messenger-lab2-api:local
command:
- python
- scripts/migrate.py
environment:
DATABASE_URL_FILE: /run/secrets/database_url
secrets:
- database_url
depends_on:
db:
condition: service_healthy
networks:
- messenger_net
restart: "no"
api:
<<: *api
ports:
- "8080:8080"
# Second API instance for the automatic expiry test (profile "tests").
api_short_ttl:
<<: *api
profiles: [ "tests" ]
environment:
<<: *api-env
SESSION_TTL_SECONDS: "3"
ports:
- "8081:8080"
# Direct PostgreSQL checks: rollback, EXPLAIN on >=10k messages.
db_checks:
image: messenger-lab2-api:local
profiles: [ "tools" ]
command: [ "python", "student-tests/db_checks.py" ]
environment:
DATABASE_URL_FILE: /run/secrets/database_url
secrets:
- database_url
volumes:
- ./student-tests:/app/student-tests:ro
depends_on:
db:
condition: service_healthy
networks:
- messenger_net
restart: "no"
volumes:
postgres_data:
networks:
messenger_net:
driver: bridge
secrets:
postgres_password:
file: ./infra/secrets/postgres_password.txt
database_url:
file: ./infra/secrets/database_url.txt
valkey_password:
file: ./infra/secrets/valkey_password.txt
cache_url:
file: ./infra/secrets/cache_url.txt
+42 -3
View File
@@ -1,5 +1,44 @@
# Доказательства
# Доказательства Lab2
Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки.
## Контекст
Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно.
- Дата: 2026-09-29.
- Commit: `<COMMIT_HASH>` (заполнить после commit).
- Хост: Windows 11, Docker Desktop 29.3 (WSL2); тесты запускались из WSL Ubuntu, Python 3.14.
- API: FastAPI/Uvicorn в образе `python:3.12.7-slim`.
- Хранилище: PostgreSQL `postgres:16.4-alpine`, named volume `postgres_data`.
- Кэш сессий: Valkey `valkey/valkey:8.0.1-alpine`, без persistence (источник истины — PostgreSQL).
- API URL: `http://localhost:8080`; стенд с коротким TTL: `http://localhost:8081`.
- Session TTL: 3600 s (основной API), 3 s (`api_short_ttl`); TTL записи в кэше ≤ 60 s.
- Restart hook: `scripts/restart.sh` → `docker compose restart db valkey api`, volumes не удаляются.
Все файлы собраны одной командой `sh scripts/run_evidence.sh` на поднятом стенде
(`docker compose --profile tests up -d --build api api_short_ttl`).
## Файлы
| Файл | Команда | Назначение |
|-------------------------|-------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| `check_contract.txt` | `python3 scripts/check_contract.py` | Структура репозитория, OpenAPI refs и Python syntax |
| `validate_openapi.txt` | `python3 scripts/validate_openapi.py` | OpenAPI 3.1 и JSON Schema validation |
| `smoke.txt` | `python3 tests/smoke.py --base-url http://localhost:8080` | Basic/Bearer, users, chats, messages, pagination, logout |
| `persistence.txt` | `python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh` | Restart API, PostgreSQL и Valkey; состояние контейнеров до и после hook |
| `migrations_repeat.txt` | `docker compose run --rm migrate` | Повторный запуск migrations без дублирования |
| `level4.txt` | `python3 student-tests/level4.py` | Неверный пароль, logout, expiry, кэш, гонка регистрации, отказ Valkey/PostgreSQL |
| `explain.txt` | `docker compose --profile tools run --rm db_checks` | Rollback создания чата; `EXPLAIN (ANALYZE, BUFFERS)` на 10 000 сообщений |
| `load.txt`, `load.json` | `python3 tests/load.py --duration 15 --concurrency 4` | Closed-loop нагрузка на создание сообщений |
## Нагрузка
Профиль: 4 concurrent клиента, 15 seconds, closed-loop `POST /api/v1/chats/{chat_id}/messages`, без automatic retries.
Результат: 4071 успешный запрос, 0 ошибок, ≈271 RPS, p50/p95/p99 = 13.4/22.9/31.9 ms.
Это локальное измерение на Docker Desktop/WSL2, а не production SLA.
Latency включает client overhead; closed-loop нагрузка подвержена coordinated omission.
## Безопасность
Evidence содержит только синтетические данные и агрегированные результаты.
В папку не добавляются `.env`, Docker secrets, session tokens, Basic credentials,
cookies, private keys, database dumps, реальные сообщения и raw HTTP headers.
UUID в `explain.txt` относятся к синтетическому чату `explain-bench-0`.
+1
View File
@@ -0,0 +1 @@
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
+68
View File
@@ -0,0 +1,68 @@
== rollback of composite chat creation
expected failure: IntegrityError
PASS: create_chat_with_members fails on a missing member
PASS: chat row was rolled back together with members
PASS: no chats without members exist in the database
== EXPLAIN for message history pagination
messages total: 67882; in explained chat: 10000
PASS: explained chat has >= 10 000 messages
-- first page
Limit (actual time=0.013..0.018 rows=51 loops=1)
Buffers: shared hit=4
-> Index Scan using messages_keyset_idx on messages (actual time=0.012..0.015 rows=51 loops=1)
Index Cond: (chat_id = 'bc6206c8-0e5d-48f3-94ea-a5fe15e0a9e5'::uuid)
Buffers: shared hit=4
Planning:
Buffers: shared hit=6
Planning Time: 0.102 ms
Execution Time: 0.037 ms
-- keyset page after position 9000
Limit (actual time=0.013..0.022 rows=51 loops=1)
Buffers: shared hit=5
-> Index Scan using messages_keyset_idx on messages (actual time=0.012..0.019 rows=51 loops=1)
Index Cond: ((chat_id = 'bc6206c8-0e5d-48f3-94ea-a5fe15e0a9e5'::uuid) AND (ROW(created_at, id) > ROW('2026-10-01 19:08:45.800971+00'::timestamp with time zone, '6f9dad83-2a94-400a-877b-7202790747a3'::uuid)))
Buffers: shared hit=5
Planning Time: 0.050 ms
Execution Time: 0.078 ms
-- OFFSET 9000 (not used by the API)
Limit (actual time=3.380..3.385 rows=51 loops=1)
Buffers: shared hit=208
-> Sort (actual time=2.876..3.174 rows=9051 loops=1)
Sort Key: created_at, id
Sort Method: quicksort Memory: 1713kB
Buffers: shared hit=208
-> Bitmap Heap Scan on messages (actual time=0.226..0.807 rows=10000 loops=1)
Recheck Cond: (chat_id = 'bc6206c8-0e5d-48f3-94ea-a5fe15e0a9e5'::uuid)
Heap Blocks: exact=134
Buffers: shared hit=208
-> Bitmap Index Scan on messages_keyset_idx (actual time=0.212..0.212 rows=10000 loops=1)
Index Cond: (chat_id = 'bc6206c8-0e5d-48f3-94ea-a5fe15e0a9e5'::uuid)
Buffers: shared hit=74
Planning Time: 0.041 ms
Execution Time: 3.564 ms
-- keyset page WITHOUT messages_keyset_idx (rolled back)
Limit (actual time=2.474..2.478 rows=51 loops=1)
Buffers: shared hit=891
-> Sort (actual time=2.472..2.474 rows=51 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 31kB
Buffers: shared hit=891
-> Seq Scan on messages (actual time=0.405..2.402 rows=999 loops=1)
Filter: ((chat_id = 'bc6206c8-0e5d-48f3-94ea-a5fe15e0a9e5'::uuid) AND (ROW(created_at, id) > ROW('2026-10-01 19:08:45.800971+00'::timestamp with time zone, '6f9dad83-2a94-400a-877b-7202790747a3'::uuid)))
Rows Removed by Filter: 66883
Buffers: shared hit=891
Planning:
Buffers: shared hit=4
Planning Time: 0.097 ms
Execution Time: 2.504 ms
PASS: first page reads the index in order, no Sort
PASS: keyset cursor is an Index Cond, not a filter over the history
PASS: keyset deep page touches fewer buffers than OFFSET (5 < 208)
PASS: index reduces buffers for the deep page (5 < 891)
PASS: db checks
+80
View File
@@ -0,0 +1,80 @@
== credentials and anonymous requests
PASS: wrong password -> 401 with Basic challenge
PASS: unknown user -> 401
PASS: no Authorization -> 401 with Bearer challenge
PASS: X-User-Id alone gives no access
PASS: Basic is not accepted on business endpoints
PASS: unknown Bearer token -> 401
== logout and Valkey session cache
PASS: no cache entry before first use
PASS: fresh token works (cache miss -> PostgreSQL)
PASS: session is cached in Valkey under sha256(token)
PASS: second request works (cache hit)
PASS: logout -> 204
PASS: revoked token -> 401 right after logout
PASS: revoked token stays 401 (cache tombstone)
PASS: second logout with same token -> 401
PASS: another session of the user is unaffected
== expiry with SESSION_TTL_SECONDS=3 (api_short_ttl)
PASS: login on short-TTL instance
PASS: token valid before expiry (now cached)
PASS: token rejected after expiry, cache too
PASS: logout of expired token -> 401
== registration race: 20 parallel requests, one username
statuses: {201: 1, 409: 19}
PASS: exactly one registration wins
PASS: all others get 409, no 500
== Valkey stop: cache is bypassed, PostgreSQL decides
PASS: token cached before outage
PASS: login works without Valkey
PASS: Bearer request works without Valkey
PASS: write works without Valkey
PASS: forged token still 401 without Valkey
PASS: anonymous still 401 without Valkey
PASS: logout works without Valkey
PASS: token revoked during outage -> 401
PASS: bounded latency during outage (max 0.26s)
PASS: token revoked during outage stays 401 after Valkey returns (stale cache flushed)
PASS: live session works after recovery
== Valkey pause: cache is bypassed, PostgreSQL decides
PASS: token cached before outage
PASS: login works without Valkey
PASS: Bearer request works without Valkey
PASS: write works without Valkey
PASS: forged token still 401 without Valkey
PASS: anonymous still 401 without Valkey
PASS: logout works without Valkey
PASS: token revoked during outage -> 401
PASS: bounded latency during outage (max 0.26s)
PASS: token revoked during outage stays 401 after Valkey returns (stale cache flushed)
PASS: live session works after recovery
== logout while Valkey hangs, API restart, Valkey returns
PASS: token cached before outage
PASS: positive cache entry exists in Valkey
PASS: logout committed in PostgreSQL, tombstone not written
PASS: API restarted while Valkey is unreachable
PASS: revoked token -> 401 after API restart (got 401)
PASS: revoked token cannot send messages (got 401)
== PostgreSQL stop: limited 503, anonymous is never trusted
PASS: token cached before outage
PASS: write -> 503 unavailable with request id (3.01s)
PASS: 503 is returned within the configured timeouts
PASS: /health/ready -> 503
PASS: /health/live -> 200
PASS: login -> 503
PASS: anonymous -> 401 without touching the DB
PASS: unverifiable token -> 503, never 2xx
PASS: X-User-Id -> 401 during outage
PASS: cached valid session still identifies the user
PASS: API ready again after PostgreSQL start
PASS: writes work again with the old session
PASS: level 4 checks
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 15.0,
"elapsed_seconds": 15.018,
"concurrency": 4,
"successful_requests": 3970,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 264.341,
"successful_latency_ms": {
"p50": 13.83,
"p95": 23.53,
"p99": 32.665
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 15.0,
"elapsed_seconds": 15.018,
"concurrency": 4,
"successful_requests": 3970,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 264.341,
"successful_latency_ms": {
"p50": 13.83,
"p95": 23.53,
"p99": 32.665
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+3
View File
@@ -0,0 +1,3 @@
SKIP 001_initial_schema.sql
SKIP 002_indexes.sql
PASS: migrations applied
+14
View File
@@ -0,0 +1,14 @@
## containers before restart hook
api running Up 7 minutes 2026-10-03 10:50:58 +0300 MSK
api_short_ttl running Up 21 minutes 2026-10-03 10:50:58 +0300 MSK
db running Up 6 minutes (healthy) 2026-10-02 21:00:15 +0300 MSK
migrate exited Exited (0) 21 minutes ago 2026-10-03 10:50:58 +0300 MSK
valkey running Up 7 minutes (healthy) 2026-10-02 21:09:53 +0300 MSK
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 restart hook (Status shows new uptime)
api running Up 1 second 2026-10-03 10:50:58 +0300 MSK
api_short_ttl running Up 21 minutes 2026-10-03 10:50:58 +0300 MSK
db running Up 2 seconds (health: starting) 2026-10-02 21:00:15 +0300 MSK
migrate exited Exited (0) 21 minutes ago 2026-10-03 10:50:58 +0300 MSK
valkey running Up 2 seconds (health: starting) 2026-10-02 21:09:53 +0300 MSK
+1
View File
@@ -0,0 +1 @@
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
+1
View File
@@ -0,0 +1 @@
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
+44 -4
View File
@@ -1,7 +1,47 @@
# Инфраструктура студента
# Инфраструктура
Здесь разместите конфигурации выбранных сервисов; основную топологию — в корневом compose.yaml/stack.yaml. `compose.example.yaml` — только worksheet ролей и намеренно не запускается. `contracts/infrastructure.json` задаёт минимальные роли, не готовые образы/пароли.
## Сервисы
В REPORT.md сопоставьте роль → service name → версия/digest → health/readiness → volume → сеть/порт → способ передачи credentials. Приведите bootstrap (schema, bucket, broker topology, а с lab6 provisioning) и безопасное повторение этих команд.
| Роль | Service | Образ | Назначение |
|-----------|-----------------|------------------------------|-------------------------------------------------------------------|
| API | `api` | `messenger-lab2-api:local` | FastAPI-приложение, порт 8080 |
| Database | `db` | `postgres:16.4-alpine` | Источник истины: пользователи, чаты, участники, сообщения, сессии |
| Cache | `valkey` | `valkey/valkey:8.0.1-alpine` | Кэш сессий `sha256(token) → user`, без persistence |
| Bootstrap | `migrate` | `messenger-lab2-api:local` | Одноразовый прогон `migrations/*.sql`, затем `api` стартует |
| Tests | `api_short_ttl` | `messenger-lab2-api:local` | Профиль `tests`: второй API с `SESSION_TTL_SECONDS=3`, порт 8081 |
| Tools | `db_checks` | `messenger-lab2-api:local` | Профиль `tools`: rollback и EXPLAIN внутри сети compose |
Приложение строится из исходников. Не используйте заранее существующий образ преподавательского сервера вместо своей реализации. Restart hook перезапускает все соответствующие stores с volumes; failover hook останавливает только заданную API-реплику.
Порты `db` и `valkey` наружу не публикуются.
## Healthchecks
- `db`: `pg_isready`; `migrate` и `api` ждут `service_healthy`.
- `valkey`: `valkey-cli ping` с паролем.
- `api`: `/health/live` (процесс жив), `/health/ready` (PostgreSQL отвечает).
Недоступность Valkey не делает API not ready: кэш обходится.
## Запуск
```sh
sh scripts/init-secrets.sh
docker compose up -d --build
# для автоматической проверки expiry:
docker compose --profile tests up -d api_short_ttl
```
## Persistence
- Данные PostgreSQL хранятся в named volume `postgres_data`.
- Valkey намеренно запускается с `--save "" --appendonly no`: это кэш, а не
хранилище. После рестарта/flush сессии читаются из PostgreSQL и снова кэшируются.
- `docker compose restart`, `stop/start` и `down` без `-v` данные не удаляют.
`docker compose down -v` удаляет volume — это осознанный сброс учебных данных,
в restart-сценарии его использовать нельзя.
## Credentials
`scripts/init-secrets.sh` создаёт в `infra/secrets/` случайные
`postgres_password.txt`, `database_url.txt`, `valkey_password.txt`, `cache_url.txt`
(существующие файлы не перезаписываются). В контейнеры они попадают как Docker
secrets (`/run/secrets/*`), приложение читает `*_FILE`. Каталог в `.gitignore`
и `.dockerignore`.
+48
View File
@@ -0,0 +1,48 @@
CREATE TABLE IF NOT EXISTS users (
id UUID PRIMARY KEY,
username VARCHAR(32) NOT NULL UNIQUE,
display_name VARCHAR(100) NOT NULL,
password_hash TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT users_username_format_check
CHECK (username ~ '^[a-z0-9_]{3,32}$'),
CONSTRAINT users_display_name_nonblank_check
CHECK (char_length(btrim(display_name)) >= 1)
);
CREATE TABLE IF NOT EXISTS chats (
id UUID PRIMARY KEY,
title VARCHAR(255) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT chats_title_nonblank_check
CHECK (char_length(btrim(title)) >= 1)
);
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 RESTRICT,
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) ON DELETE RESTRICT,
text VARCHAR(4000) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT messages_text_nonblank_check
CHECK (char_length(btrim(text)) >= 1)
);
CREATE TABLE IF NOT EXISTS sessions (
id UUID PRIMARY KEY,
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
token_hash CHAR(64) NOT NULL UNIQUE,
expires_at TIMESTAMPTZ NOT NULL,
revoked_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
+12
View File
@@ -0,0 +1,12 @@
CREATE INDEX IF NOT EXISTS messages_keyset_idx
ON messages (chat_id, created_at ASC, id ASC);
CREATE INDEX IF NOT EXISTS chats_keyset_idx
ON chats (created_at ASC, id ASC);
CREATE INDEX IF NOT EXISTS chat_members_user_chat_idx
ON chat_members (user_id, chat_id);
CREATE INDEX IF NOT EXISTS sessions_active_token_idx
ON sessions (token_hash, expires_at)
WHERE revoked_at IS NULL;
+5
View File
@@ -1,2 +1,7 @@
-r requirements.txt
# Only for full OpenAPI/JSON Schema validation; HTTP tests use stdlib.
openapi-spec-validator==0.7.2
jsonschema==4.23.0
referencing==0.35.1
httpx==0.27.2
+7
View File
@@ -0,0 +1,7 @@
fastapi==0.115.0
uvicorn[standard]==0.30.6
pydantic==2.9.2
SQLAlchemy==2.0.36
asyncpg==0.30.0
argon2-cffi==23.1.0
redis==5.0.8
+33
View File
@@ -0,0 +1,33 @@
#!/bin/sh
# Creates local Docker secrets for a synthetic lab stand.
# Existing files are never overwritten; values are never printed.
set -eu
dir="$(cd "$(dirname "$0")/.." && pwd)/infra/secrets"
mkdir -p "$dir"
random() {
od -An -tx1 -N24 /dev/urandom | tr -d ' \n'
}
write_new() {
if [ -f "$dir/$1" ]; then
echo "keep infra/secrets/$1"
else
printf '%s' "$2" > "$dir/$1"
chmod 600 "$dir/$1" 2>/dev/null || true
echo "create infra/secrets/$1"
fi
}
if [ ! -f "$dir/postgres_password.txt" ]; then
write_new postgres_password.txt "$(random)"
fi
pg_password="$(cat "$dir/postgres_password.txt")"
write_new database_url.txt "postgresql://messenger:${pg_password}@db:5432/messenger"
if [ ! -f "$dir/valkey_password.txt" ]; then
write_new valkey_password.txt "$(random)"
fi
valkey_password="$(cat "$dir/valkey_password.txt")"
write_new cache_url.txt "redis://:${valkey_password}@valkey:6379/0"
+79
View File
@@ -0,0 +1,79 @@
from __future__ import annotations
import asyncio
import os
from pathlib import Path
import asyncpg
ROOT = Path(__file__).resolve().parents[1]
MIGRATIONS_DIR = ROOT / "migrations"
def read_database_url() -> str:
file_name = os.getenv("DATABASE_URL_FILE")
if file_name:
return Path(file_name).read_text(encoding="utf-8").strip()
value = os.getenv("DATABASE_URL")
if not value:
raise RuntimeError("DATABASE_URL or DATABASE_URL_FILE is required.")
return value
def plain_postgres_url(url: str) -> str:
if url.startswith("postgresql+asyncpg://"):
return url.replace("postgresql+asyncpg://", "postgresql://", 1)
return url
async def migrate() -> None:
connection = await asyncpg.connect(
plain_postgres_url(read_database_url())
)
try:
await connection.execute(
"""
CREATE TABLE IF NOT EXISTS schema_migrations (
version TEXT PRIMARY KEY,
applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
)
"""
)
applied_rows = await connection.fetch(
"SELECT version FROM schema_migrations"
)
applied = {row["version"] for row in applied_rows}
for migration_file in sorted(MIGRATIONS_DIR.glob("*.sql")):
version = migration_file.name
if version in applied:
print(f"SKIP {version}")
continue
sql = migration_file.read_text(encoding="utf-8")
print(f"APPLY {version}")
async with connection.transaction():
await connection.execute(sql)
await connection.execute(
"INSERT INTO schema_migrations (version) VALUES ($1)",
version,
)
print("PASS: migrations applied")
finally:
await connection.close()
if __name__ == "__main__":
asyncio.run(migrate())
-10
View File
@@ -1,10 +0,0 @@
#!/bin/sh
set -eu
# TODO: copy to restart.sh and implement using YOUR compose/stack services.
# Restart API and ALL used state stores (DB, sessions, S3, broker as applicable).
# Preserve persistent volumes and schema/data; never down -v / flush / re-seed.
# Allow operator unseal if required in lab7; do not print credentials.
# Exit 0 only after the intended action; test waits for API readiness separately.
printf '%s
' 'TODO: implement restart.sh for your infrastructure' >&2
exit 2
+6
View File
@@ -0,0 +1,6 @@
#!/bin/sh
# Restarts the API and every storage it uses; volumes are kept.
set -eu
cd "$(dirname "$0")/.."
docker compose restart db valkey api
+51
View File
@@ -0,0 +1,51 @@
#!/bin/sh
# Collects lab2 evidence from a running stand:
# docker compose --profile tests up -d --build api api_short_ttl
# sh scripts/run_evidence.sh
# Output contains only synthetic data and aggregates, never tokens/secrets.
set -eu
cd "$(dirname "$0")/.."
mkdir -p evidence
PYTHON="${PYTHON:-python3}"
if [ -x .venv-wsl/bin/python3 ]; then PYTHON=.venv-wsl/bin/python3; fi
if [ -x .venv/bin/python3 ]; then PYTHON=.venv/bin/python3; fi
# Do not overwrite evidence/ with failures of a stand that is not running.
if ! curl -fsS --max-time 5 http://localhost:8080/health/ready >/dev/null 2>&1 || ! curl -fsS --max-time 5 http://localhost:8081/health/ready >/dev/null 2>&1; then
echo "API is not running. Start it first:" >&2
echo " docker compose --profile tests up -d --build api api_short_ttl" >&2
exit 1
fi
containers() {
docker compose ps -a --format '{{.Service}}\t{{.State}}\t{{.Status}}\t{{.CreatedAt}}'
}
"$PYTHON" scripts/check_contract.py | tee evidence/check_contract.txt
"$PYTHON" scripts/validate_openapi.py | tee evidence/validate_openapi.txt
"$PYTHON" tests/smoke.py --base-url http://localhost:8080 | tee evidence/smoke.txt
{
echo "## containers before restart hook"
containers
"$PYTHON" tests/resilience.py \
--base-url http://localhost:8080 \
--action-script scripts/restart.sh \
--mode persistence
echo "## containers after restart hook (Status shows new uptime)"
containers
} 2>&1 | tee evidence/persistence.txt
docker compose run --rm migrate 2>/dev/null | tee evidence/migrations_repeat.txt
"$PYTHON" student-tests/level4.py | tee evidence/level4.txt
docker compose --profile tools run --rm db_checks 2>/dev/null \
| tee evidence/explain.txt
"$PYTHON" tests/load.py \
--base-url http://localhost:8080 \
--duration 15 \
--concurrency 4 \
--output evidence/load.json | tee evidence/load.txt
+313
View File
@@ -0,0 +1,313 @@
"""Direct PostgreSQL checks for lab2 level 4.
Run inside the compose network (no DB port is published):
docker compose --profile tools run --rm db_checks
1. Rollback of the composite "create chat + members" operation, using the
application's own repository code.
2. EXPLAIN (ANALYZE, BUFFERS) of the message history page on a chat with
>= 10 000 messages: first page, deep keyset page, OFFSET for comparison
and the keyset page with the index dropped inside a rolled back
transaction.
Only synthetic data is created (user "explain_bench").
"""
from __future__ import annotations
import asyncio
import os
import re
import sys
from pathlib import Path
from uuid import uuid4
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
os.environ.setdefault("SESSION_STORE", "postgres")
from sqlalchemy import text # noqa: E402
from app import repositories # noqa: E402
from app.db import SessionLocal, engine # noqa: E402
BENCH_USERNAME = "explain_bench"
BENCH_CHATS = 5
MESSAGES_PER_CHAT = 10_000
PAGE = 50
DEEP_POSITION = 9_000
failures: list[str] = []
def check(condition: bool, message: str) -> None:
print(("PASS: " if condition else "FAIL: ") + message)
if not condition:
failures.append(message)
async def check_chat_rollback() -> None:
print("== rollback of composite chat creation")
title = f"rollback-{uuid4().hex}"
async with SessionLocal() as db:
user_id = (
await db.execute(text("SELECT id FROM users LIMIT 1"))
).scalar_one_or_none()
if user_id is None:
user_id = uuid4()
await db.execute(
text(
"INSERT INTO users (id, username, display_name, password_hash) "
"VALUES (:id, :u, 'Rollback', 'not-a-login-hash')"
),
{"id": user_id, "u": f"rb_{uuid4().hex[:20]}"},
)
await db.commit()
missing_member = uuid4()
failed = False
try:
# Chat INSERT succeeds, the second member violates the FK.
await repositories.create_chat_with_members(
db,
title=title,
member_ids=[user_id, missing_member],
)
except Exception as exc: # noqa: BLE001
failed = True
print(f"expected failure: {type(exc).__name__}")
check(failed, "create_chat_with_members fails on a missing member")
async with SessionLocal() as db:
chats = (
await db.execute(
text("SELECT count(*) FROM chats WHERE title = :title"),
{"title": title},
)
).scalar_one()
orphans = (
await db.execute(
text(
"SELECT count(*) FROM chats c "
"WHERE NOT EXISTS (SELECT 1 FROM chat_members m "
"WHERE m.chat_id = c.id)"
)
)
).scalar_one()
check(chats == 0, "chat row was rolled back together with members")
check(orphans == 0, "no chats without members exist in the database")
async def seed_history() -> str:
async with SessionLocal() as db:
user_id = (
await db.execute(
text("SELECT id FROM users WHERE username = :u"),
{"u": BENCH_USERNAME},
)
).scalar_one_or_none()
if user_id is None:
user_id = uuid4()
await db.execute(
text(
"INSERT INTO users (id, username, display_name, password_hash) "
"VALUES (:id, :u, 'Explain Bench', 'not-a-login-hash')"
),
{"id": user_id, "u": BENCH_USERNAME},
)
chat_ids = list(
(
await db.execute(
text(
"SELECT c.id FROM chats c JOIN chat_members m "
"ON m.chat_id = c.id WHERE m.user_id = :u "
"AND c.title LIKE 'explain-bench-%' ORDER BY c.title"
),
{"u": user_id},
)
).scalars()
)
for index in range(len(chat_ids), BENCH_CHATS):
chat_id = uuid4()
await db.execute(
text("INSERT INTO chats (id, title) VALUES (:id, :t)"),
{"id": chat_id, "t": f"explain-bench-{index}"},
)
await db.execute(
text(
"INSERT INTO chat_members (chat_id, user_id) "
"VALUES (:c, :u)"
),
{"c": chat_id, "u": user_id},
)
chat_ids.append(chat_id)
for chat_id in chat_ids:
existing = (
await db.execute(
text("SELECT count(*) FROM messages WHERE chat_id = :c"),
{"c": chat_id},
)
).scalar_one()
missing = MESSAGES_PER_CHAT - existing
if missing > 0:
# Several messages share one timestamp to exercise the
# (created_at, id) tie-breaker.
await db.execute(
text(
"""
INSERT INTO messages (id, chat_id, sender_id, text, created_at)
SELECT gen_random_uuid(), :c, :u,
'synthetic message ' || g,
now() - interval '1 day' + (g / 3) * interval '1 second'
FROM generate_series(1, :n) AS g
"""
),
{"c": chat_id, "u": user_id, "n": missing},
)
await db.commit()
async with engine.connect() as connection:
await connection.execute(text("ANALYZE messages"))
await connection.commit()
return str(chat_ids[0])
async def explain(connection, title: str, sql: str, params: dict) -> str:
rows = await connection.execute(
text("EXPLAIN (ANALYZE, BUFFERS, COSTS OFF) " + sql),
params,
)
plan = "\n".join(row[0] for row in rows)
print(f"\n-- {title}\n{plan}")
return plan
def shared_buffers(plan: str) -> int:
first = re.search(r"Buffers: shared ([^\n]+)", plan)
if not first:
return 0
return sum(int(value) for value in re.findall(r"=(\d+)", first.group(1)))
async def check_history_plan() -> None:
print("\n== EXPLAIN for message history pagination")
chat_id = await seed_history()
async with engine.connect() as connection:
total = (
await connection.execute(text("SELECT count(*) FROM messages"))
).scalar_one()
in_chat = (
await connection.execute(
text("SELECT count(*) FROM messages WHERE chat_id = :c"),
{"c": chat_id},
)
).scalar_one()
print(f"messages total: {total}; in explained chat: {in_chat}")
check(in_chat >= 10_000, "explained chat has >= 10 000 messages")
cursor = (
await connection.execute(
text(
"SELECT created_at, id FROM messages WHERE chat_id = :c "
"ORDER BY created_at, id OFFSET :o LIMIT 1"
),
{"c": chat_id, "o": DEEP_POSITION},
)
).one()
params = {
"c": chat_id,
"ca": cursor.created_at,
"ci": cursor.id,
"l": PAGE + 1,
}
# Same SQL as repositories.list_messages_keyset.
first_sql = (
"SELECT id, chat_id, sender_id, text, created_at FROM messages "
"WHERE chat_id = :c ORDER BY created_at ASC, id ASC LIMIT :l"
)
keyset_sql = (
"SELECT id, chat_id, sender_id, text, created_at FROM messages "
"WHERE chat_id = :c AND (created_at, id) > (:ca, :ci) "
"ORDER BY created_at ASC, id ASC LIMIT :l"
)
offset_sql = (
"SELECT id, chat_id, sender_id, text, created_at FROM messages "
"WHERE chat_id = :c ORDER BY created_at ASC, id ASC "
f"OFFSET {DEEP_POSITION} LIMIT :l"
)
first = await explain(connection, "first page", first_sql, params)
keyset = await explain(
connection, f"keyset page after position {DEEP_POSITION}",
keyset_sql, params,
)
offset = await explain(
connection, f"OFFSET {DEEP_POSITION} (not used by the API)",
offset_sql, params,
)
# Close the autobegun read transaction, then drop the index only
# inside a transaction that is always rolled back.
await connection.rollback()
transaction = await connection.begin()
await connection.execute(text("SET LOCAL lock_timeout = '2s'"))
await connection.execute(text("DROP INDEX messages_keyset_idx"))
no_index = await explain(
connection, "keyset page WITHOUT messages_keyset_idx (rolled back)",
keyset_sql, params,
)
await transaction.rollback()
check(
"Index Scan using messages_keyset_idx" in first
and "Sort" not in first,
"first page reads the index in order, no Sort",
)
check(
"Index Scan using messages_keyset_idx" in keyset
and re.search(r"Index Cond: .*created_at", keyset) is not None
and "Sort" not in keyset,
"keyset cursor is an Index Cond, not a filter over the history",
)
check(
shared_buffers(keyset) < shared_buffers(offset),
f"keyset deep page touches fewer buffers than OFFSET "
f"({shared_buffers(keyset)} < {shared_buffers(offset)})",
)
check(
shared_buffers(keyset) < shared_buffers(no_index),
f"index reduces buffers for the deep page "
f"({shared_buffers(keyset)} < {shared_buffers(no_index)})",
)
async def main() -> int:
try:
await check_chat_rollback()
await check_history_plan()
finally:
await engine.dispose()
if failures:
print(f"\nFAIL: {len(failures)} check(s) failed")
return 1
print("\nPASS: db checks")
return 0
if __name__ == "__main__":
sys.exit(asyncio.run(main()))
+378
View File
@@ -0,0 +1,378 @@
"""Automatic lab2 level-4 checks against the running compose stand.
docker compose --profile tests up -d --build api_short_ttl
python student-tests/level4.py
Covers: wrong password, Basic/X-User-Id/garbage tokens, logout, session
expiry with a short SESSION_TTL_SECONDS (api_short_ttl on :8081), the Valkey
session cache role, registration race on one username, Valkey stop and hang
(pause), PostgreSQL stop. The script stops/pauses containers itself and
always starts them again; volumes are never removed. Tokens, passwords and
secrets are never printed.
"""
from __future__ import annotations
import argparse
import base64
import hashlib
import json
import subprocess
import sys
import time
import urllib.error
import urllib.request
import uuid
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
PASSWORD = "correct-horse-battery-staple"
failures: list[str] = []
def check(condition: bool, message: str) -> None:
print(("PASS: " if condition else "FAIL: ") + message, flush=True)
if not condition:
failures.append(message)
class Api:
def __init__(self, base_url: str) -> None:
self.base_url = base_url.rstrip("/")
def call(
self,
method: str,
path: str,
*,
body: dict | None = None,
headers: dict[str, str] | None = None,
timeout: float = 15,
) -> tuple[int, dict, dict[str, str], float]:
request_headers = {"Accept": "application/json"}
data = None
if body is not None:
data = json.dumps(body).encode("utf-8")
request_headers["Content-Type"] = "application/json"
request_headers.update(headers or {})
request = urllib.request.Request(
self.base_url + path, data=data, headers=request_headers, method=method
)
started = time.monotonic()
try:
with urllib.request.urlopen(request, timeout=timeout) as response:
raw = response.read().decode("utf-8")
status, response_headers = response.status, response.headers
except urllib.error.HTTPError as exc:
raw = exc.read().decode("utf-8")
status, response_headers = exc.code, exc.headers
elapsed = time.monotonic() - started
return status, json.loads(raw) if raw else {}, response_headers, elapsed
def register(self, username: str | None = None) -> dict:
username = username or f"l4_{uuid.uuid4().hex[:20]}"
status, body, _, _ = self.call(
"POST", "/api/v1/users",
body={"username": username, "display_name": "Level 4",
"password": PASSWORD},
)
assert status == 201, f"register returned {status}"
return body
def login(self, username: str, password: str = PASSWORD):
raw = base64.b64encode(f"{username}:{password}".encode()).decode()
return self.call(
"POST", "/api/v1/auth/sessions",
headers={"Authorization": f"Basic {raw}"},
)
def token(self, username: str) -> str:
status, body, _, _ = self.login(username)
assert status == 201, f"login returned {status}"
return body["token"]
def me(self, token: str, timeout: float = 15):
return self.call(
"GET", "/api/v1/users/me",
headers={"Authorization": f"Bearer {token}"}, timeout=timeout,
)
def create_chat(self, token: str, user_id: str):
return self.call(
"POST", "/api/v1/chats",
body={"title": "Level 4", "member_ids": [user_id]},
headers={"Authorization": f"Bearer {token}"},
)
def logout(self, token: str):
return self.call(
"DELETE", "/api/v1/auth/sessions/current",
headers={"Authorization": f"Bearer {token}"},
)
def wait_ready(self, seconds: float = 90) -> bool:
deadline = time.monotonic() + seconds
while time.monotonic() < deadline:
try:
if self.call("GET", "/health/ready", timeout=3)[0] == 200:
return True
except OSError:
pass
time.sleep(1)
return False
def compose(*args: str) -> str:
result = subprocess.run(
["docker", "compose", *args],
cwd=ROOT, capture_output=True, text=True, check=True,
)
return result.stdout
def valkey_has_session(token: str) -> bool:
"""The cache key is sha256(token); the raw token is never stored."""
key = "messenger:session:" + hashlib.sha256(token.encode()).hexdigest()
output = compose(
"exec", "-T", "valkey", "sh", "-c",
'valkey-cli -a "$(cat /run/secrets/valkey_password)" --no-auth-warning '
f"exists {key}",
)
return output.strip() == "1"
def is_error(body: dict, code: str) -> bool:
error = body.get("error", {})
return error.get("code") == code and bool(error.get("request_id"))
def test_credentials(api: Api) -> None:
print("\n== credentials and anonymous requests")
user = api.register()
status, body, headers, _ = api.login(user["username"], "wrong-password-123")
check(
status == 401 and is_error(body, "unauthorized")
and headers.get("WWW-Authenticate", "").startswith("Basic"),
"wrong password -> 401 with Basic challenge",
)
status, _, _, _ = api.login(f"nobody_{uuid.uuid4().hex[:10]}")
check(status == 401, "unknown user -> 401")
status, _, headers, _ = api.call("GET", "/api/v1/users/me")
check(
status == 401 and headers.get("WWW-Authenticate", "").startswith("Bearer"),
"no Authorization -> 401 with Bearer challenge",
)
status, _, _, _ = api.call(
"GET", "/api/v1/users/me", headers={"X-User-Id": user["id"]}
)
check(status == 401, "X-User-Id alone gives no access")
raw = base64.b64encode(f"{user['username']}:{PASSWORD}".encode()).decode()
status, _, _, _ = api.call(
"GET", "/api/v1/users/me", headers={"Authorization": f"Basic {raw}"}
)
check(status == 401, "Basic is not accepted on business endpoints")
status, _, _, _ = api.me("forged-" + uuid.uuid4().hex)
check(status == 401, "unknown Bearer token -> 401")
def test_logout_and_cache(api: Api) -> None:
print("\n== logout and Valkey session cache")
user = api.register()
token = api.token(user["username"])
check(not valkey_has_session(token), "no cache entry before first use")
check(api.me(token)[0] == 200, "fresh token works (cache miss -> PostgreSQL)")
check(valkey_has_session(token), "session is cached in Valkey under sha256(token)")
check(api.me(token)[0] == 200, "second request works (cache hit)")
check(api.logout(token)[0] == 204, "logout -> 204")
check(api.me(token)[0] == 401, "revoked token -> 401 right after logout")
check(api.me(token)[0] == 401, "revoked token stays 401 (cache tombstone)")
check(api.logout(token)[0] == 401, "second logout with same token -> 401")
other = api.token(user["username"])
check(api.me(other)[0] == 200, "another session of the user is unaffected")
def test_expiry(short_api: Api, ttl: float) -> None:
print(f"\n== expiry with SESSION_TTL_SECONDS={ttl:g} (api_short_ttl)")
if not short_api.wait_ready(30):
check(False, "api_short_ttl is ready (start it with --profile tests)")
return
user = short_api.register()
status, body, _, _ = short_api.login(user["username"])
check(status == 201, "login on short-TTL instance")
token = body["token"]
check(short_api.me(token)[0] == 200, "token valid before expiry (now cached)")
time.sleep(ttl + 1.5)
check(short_api.me(token)[0] == 401, "token rejected after expiry, cache too")
check(short_api.logout(token)[0] == 401, "logout of expired token -> 401")
def test_registration_race(api: Api, parallel: int = 20) -> None:
print(f"\n== registration race: {parallel} parallel requests, one username")
username = f"race_{uuid.uuid4().hex[:20]}"
body = {"username": username, "display_name": "Race", "password": PASSWORD}
def attempt(_):
return api.call("POST", "/api/v1/users", body=body, timeout=30)[0]
with ThreadPoolExecutor(max_workers=parallel) as pool:
statuses = list(pool.map(attempt, range(parallel)))
summary = {code: statuses.count(code) for code in sorted(set(statuses))}
print(f"statuses: {summary}")
check(statuses.count(201) == 1, "exactly one registration wins")
check(statuses.count(409) == parallel - 1, "all others get 409, no 500")
def test_valkey_outage(api: Api, mode: str) -> None:
stop, start = ("stop", "start") if mode == "stop" else ("pause", "unpause")
print(f"\n== Valkey {mode}: cache is bypassed, PostgreSQL decides")
user = api.register()
cached_token = api.token(user["username"])
check(api.me(cached_token)[0] == 200, "token cached before outage")
compose(stop, "valkey")
try:
worst = 0.0
status, body, _, elapsed = api.login(user["username"])
worst = max(worst, elapsed)
check(status == 201, "login works without Valkey")
token = body.get("token", "")
status, _, _, elapsed = api.me(token)
worst = max(worst, elapsed)
check(status == 200, "Bearer request works without Valkey")
status, _, _, elapsed = api.create_chat(token, user["id"])
worst = max(worst, elapsed)
check(status == 201, "write works without Valkey")
status, _, _, elapsed = api.me("forged-" + uuid.uuid4().hex)
worst = max(worst, elapsed)
check(status == 401, "forged token still 401 without Valkey")
check(api.call("GET", "/api/v1/users/me")[0] == 401,
"anonymous still 401 without Valkey")
# Invalidation is lost while Valkey is unreachable.
check(api.logout(cached_token)[0] == 204, "logout works without Valkey")
status, _, _, elapsed = api.me(cached_token)
worst = max(worst, elapsed)
check(status == 401, "token revoked during outage -> 401")
check(worst < 2.0, f"bounded latency during outage (max {worst:.2f}s)")
finally:
compose(start, "valkey")
time.sleep(7) # > CACHE_RETRY_AFTER_SECONDS: API uses Valkey again
check(api.me(cached_token)[0] == 401,
"token revoked during outage stays 401 after Valkey returns "
"(stale cache flushed)")
check(api.me(token)[0] == 200, "live session works after recovery")
def test_logout_during_outage_then_api_restart(api: Api) -> None:
print("\n== logout while Valkey hangs, API restart, Valkey returns")
user = api.register()
token = api.token(user["username"])
check(api.me(token)[0] == 200, "token cached before outage")
check(valkey_has_session(token), "positive cache entry exists in Valkey")
_, chat, _, _ = api.create_chat(token, user["id"])
compose("pause", "valkey")
try:
check(api.logout(token)[0] == 204,
"logout committed in PostgreSQL, tombstone not written")
# A new API process knows nothing about the failed invalidation.
compose("restart", "api")
check(api.wait_ready(60), "API restarted while Valkey is unreachable")
finally:
compose("unpause", "valkey")
# The stale positive entry (TTL <= 60 s) is still in Valkey now.
status, _, _, _ = api.me(token)
check(status == 401, f"revoked token -> 401 after API restart (got {status})")
status, _, _, _ = api.call(
"POST", f"/api/v1/chats/{chat.get('id')}/messages",
body={"text": "must be rejected"},
headers={"Authorization": f"Bearer {token}"},
)
check(status == 401, f"revoked token cannot send messages (got {status})")
def test_database_outage(api: Api) -> None:
print("\n== PostgreSQL stop: limited 503, anonymous is never trusted")
user = api.register()
token = api.token(user["username"])
check(api.me(token)[0] == 200, "token cached before outage")
compose("stop", "db")
try:
status, body, headers, elapsed = api.create_chat(token, user["id"])
check(
status == 503 and is_error(body, "unavailable")
and bool(headers.get("X-Request-Id")),
f"write -> 503 unavailable with request id ({elapsed:.2f}s)",
)
check(elapsed < 10, "503 is returned within the configured timeouts")
status, _, _, _ = api.call("GET", "/health/ready")
check(status == 503, "/health/ready -> 503")
check(api.call("GET", "/health/live")[0] == 200, "/health/live -> 200")
status, body, _, _ = api.login(user["username"])
check(status == 503 and is_error(body, "unavailable"), "login -> 503")
check(api.call("GET", "/api/v1/users/me")[0] == 401,
"anonymous -> 401 without touching the DB")
status, _, _, _ = api.me("forged-" + uuid.uuid4().hex)
check(status == 503, "unverifiable token -> 503, never 2xx")
status, _, _, _ = api.call(
"GET", "/api/v1/chats", headers={"X-User-Id": user["id"]}
)
check(status == 401, "X-User-Id -> 401 during outage")
status, _, _, _ = api.me(token)
check(status == 200, "cached valid session still identifies the user")
finally:
compose("start", "db")
check(api.wait_ready(90), "API ready again after PostgreSQL start")
status, _, _, _ = api.create_chat(token, user["id"])
check(status == 201, "writes work again with the old session")
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--base-url", default="http://localhost:8080")
parser.add_argument("--short-ttl-url", default="http://localhost:8081")
parser.add_argument("--short-ttl", type=float, default=3)
parser.add_argument("--skip-outages", action="store_true")
args = parser.parse_args()
api = Api(args.base_url)
if not api.wait_ready(30):
print("FAIL: API is not ready")
return 1
test_credentials(api)
test_logout_and_cache(api)
test_expiry(Api(args.short_ttl_url), args.short_ttl)
test_registration_race(api)
if not args.skip_outages:
test_valkey_outage(api, "stop")
test_valkey_outage(api, "pause")
test_logout_during_outage_then_api_restart(api)
test_database_outage(api)
if failures:
print(f"\nFAIL: {len(failures)} check(s) failed")
return 1
print("\nPASS: level 4 checks")
return 0
if __name__ == "__main__":
sys.exit(main())