Author SHA1 Message Date
ng14 78db0b567f Обновить REPORT.md 2026-10-10 00:33:03 +03:00
ng14 d0eaaea5b6 исправление замечаний 2026-10-10 00:22:30 +03:00
ng14 1d02ee3f33 исправление - символ не дает 500 2026-10-09 21:09:19 +03:00
ng14 be89a23dfa Обновить REPORT.md 2026-10-09 13:56:22 +03:00
ng14 994c3a9b7a ЛР2 2026-10-09 13:44:23 +03:00
48 changed files with 2693 additions and 37 deletions
+8 -20
View File
@@ -1,20 +1,8 @@
.git
.github
.env
.env.*
!.env.example
secrets
certs
volumes
data
backups
*.key
*.pem
*.p12
*.pfx
*.jks
.venv
__pycache__
node_modules
evidence
.DS_Store
# Белый список: в контекст сборки попадает только то, что явно разрешено ниже.
# Так в образ точно не утекут .env, secrets/, .git, тесты и отчёты.
*
!requirements.txt
!src/
!migrations/
**/__pycache__
**/*.pyc
+13
View File
@@ -9,3 +9,16 @@ DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
# --- Дополнительные настройки этого решения (значения по умолчанию из src/messenger/config.py) ---
# Сколько секунд сессия может лежать в кэше Valkey (не дольше самой сессии).
SESSION_CACHE_TTL_SECONDS=30
# Пул соединений с PostgreSQL и таймауты.
DB_POOL_MIN_SIZE=1
DB_POOL_MAX_SIZE=10
DB_POOL_TIMEOUT_SECONDS=3
DB_CONNECT_TIMEOUT_SECONDS=3
DB_STATEMENT_TIMEOUT_MS=5000
# Valkey: таймаут операции и размер пула соединений.
CACHE_TIMEOUT_MS=300
CACHE_POOL_MAX_SIZE=20
+7
View File
@@ -0,0 +1,7 @@
# Git на Windows (core.autocrlf=true) меняет LF на CRLF при checkout. Для этих файлов это ломает запуск:
# sh-скрипт с \r не выполняется, а конфиг Valkey читается внутри Linux-контейнера.
*.sh text eol=lf
*.sql text eol=lf
*.conf text eol=lf
# cmd.exe ожидает CRLF.
*.cmd text eol=crlf
+35
View File
@@ -0,0 +1,35 @@
# Базовый образ закреплён точной версией (не latest), чтобы сборка была воспроизводимой.
FROM python:3.12.8-slim-bookworm
# Не создавать .pyc, сразу выводить логи (без буфера), не кэшировать скачанные пакеты.
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /srv
# Сначала только список зависимостей: пока он не меняется, Docker берёт этот слой
# из кэша и не переустанавливает пакеты при каждой правке кода.
# --only-binary: только готовые wheel (psycopg-binary, argon2), без компиляции в образе.
COPY requirements.txt .
RUN pip install --only-binary=:all: -r requirements.txt
COPY src/ ./
# SQL-миграции едут в образе вместе с кодом: версия схемы всегда соответствует версии приложения.
COPY migrations/ ./migrations/
# Непривилегированный пользователь: если приложение взломают, у атакующего не будет root.
RUN useradd --system --uid 10001 --no-create-home --shell /usr/sbin/nologin app
USER app
EXPOSE 8080
# Docker сам периодически опрашивает /health/ready и показывает статус healthy/unhealthy.
# С lab2 ready проверяет PostgreSQL, поэтому unhealthy = API жив, но база недоступна.
# curl в slim-образе нет, поэтому проверяем средствами Python.
HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \
CMD ["python", "-c", "import os, urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/health/ready' % os.environ.get('APP_PORT', '8080'), timeout=2)"]
# Exec-форма (JSON-массив): python запускается напрямую как PID 1 и сам получает SIGTERM.
CMD ["python", "-m", "messenger"]
+67 -2
View File
@@ -1,13 +1,21 @@
PYTHON ?= python3
BASE_URL ?= http://localhost:8080
# 127.0.0.1, а не localhost: на части Windows-машин localhost резолвится очень медленно.
BASE_URL ?= http://127.0.0.1:8080
# Второй экземпляр API с SESSION_TTL_SECONDS=2 (сервис api-short-ttl, профиль ttl).
BASE_URL_TTL ?= http://127.0.0.1:8081
CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
# Передаём адреса собственным тестам через окружение (работает и в cmd, и в sh).
export BASE_URL
export BASE_URL_TTL
.PHONY: help check validate test load test-persistence
.PHONY: help check validate test load test-persistence \
secrets up down ps logs student-test race expiry failure-valkey failure-postgres failure-valkey-pause db-test explain demo cache-stats
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "secrets/up/down/ps/logs: stand; student-test, race, expiry, failure-valkey, failure-postgres, failure-valkey-pause, db-test, explain, demo, cache-stats: own checks"
check:
$(PYTHON) scripts/check_contract.py
@@ -24,3 +32,60 @@ load:
test-persistence:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2)
$(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
# ---------- стенд ----------
secrets:
sh scripts/init-secrets.sh
up:
docker compose up -d --build --wait
# Без -v: volumes с данными сохраняются. Удаление данных — только осознанно: docker compose down -v
down:
docker compose --profile ttl --profile tools down
# ID контейнера + время работы: после restart hook ID те же (не пересозданы), а Up сбросился.
ps:
docker compose ps -a --format "table {{.Service}}\t{{.ID}}\t{{.Status}}"
logs:
docker compose logs --tail 50 api
# ---------- собственные проверки ----------
student-test:
$(PYTHON) -m unittest discover -s student-tests -p "test_*.py" -v
race:
$(PYTHON) student-tests/race.py
expiry:
docker compose --profile ttl up -d --wait api-short-ttl
$(PYTHON) student-tests/expiry.py
failure-valkey:
$(PYTHON) student-tests/dependency_failure.py valkey
failure-postgres:
$(PYTHON) student-tests/dependency_failure.py postgres
# Valkey на паузе (данные в нём сохраняются), logout, снова в строю: токен должен остаться отозванным.
failure-valkey-pause:
$(PYTHON) student-tests/cache_revocation.py
db-test:
docker compose --profile tools run --rm db-test
explain:
docker compose exec -T postgres psql -X -q -U messenger -d messenger -v ON_ERROR_STOP=1 < infra/sql/explain_history.sql
demo:
$(PYTHON) student-tests/demo.py
# Роль Valkey: сколько ключей-сессий в кэше и сколько попаданий/промахов; права пользователя health.
VALKEY_HEALTH = docker compose exec -T valkey valkey-cli --user health --pass none --no-auth-warning
cache-stats:
$(VALKEY_HEALTH) dbsize
$(VALKEY_HEALTH) info stats | grep -E "keyspace_(hits|misses)"
-$(VALKEY_HEALTH) get sess:anything
+140 -15
View File
@@ -1,37 +1,162 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Гаджиев Нухбала, БВТ2303
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
- Commit/PR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/29
- Использованные источники, библиотеки и помощь ИИ: FastAPI, uvicorn, pydantic, psycopg 3 + psycopg-pool, argon2-cffi, valkey-py (версии в requirements.txt); образы postgres:17.10-bookworm и valkey/valkey:8.1.9; документация PostgreSQL (транзакции, EXPLAIN), Valkey (ACL, persistence), RFC 7617. ИИ использовался для оценки качества решения, написания комментариев к коду и помощи в составлении отчета.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Проверял на Windows 11 в Git Bash. Версии: Docker 29.6.2 (Docker Desktop), Docker Compose v5.3.1, Python 3.11.5 (нужен только для тестов), GNU Make 4.4.1. В контейнерах: python:3.12.8-slim-bookworm (API), postgres:17.10-bookworm, valkey/valkey:8.1.9.
```sh
git clone https://gitea.privcloud.tech/ng14/mtusi2026lab2.git && cd mtusi2026lab2
git checkout solution/bvt2303-gadzhiev
cp .env.example .env
sed -i 's/\r$//' .env # только Windows: убрать \r из .env
sh scripts/init-secrets.sh # создаёт secrets/ со случайными паролями (каталог в .gitignore)
docker compose up -d --build --wait # сборка API, запуск PostgreSQL и Valkey, ожидание healthy
make ps # api, postgres, valkey: running (healthy)
make check PYTHON=python
make test PYTHON=python
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python # Linux/macOS: scripts/restart.sh
make student-test PYTHON=python
make race PYTHON=python
make db-test
make expiry PYTHON=python
make failure-valkey PYTHON=python
make failure-postgres PYTHON=python
make failure-valkey-pause PYTHON=python
make explain > evidence/explain-history.txt
```
По умолчанию тесты ходят на http://127.0.0.1:8080 (в Makefile BASE_URL заменён с localhost на 127.0.0.1: на Windows localhost резолвится очень медленно).
Миграции применяет само приложение при старте (см. «Архитектура»), отдельной команды не нужно. Оператору нужно только один раз создать секреты (`sh scripts/init-secrets.sh`). Пароли там случайные, на экран не выводятся, в Git не попадают.
Безопасная остановка: `make down` (= `docker compose down`, контейнеры удаляются, volume с данными остаётся; следующий `docker compose up -d --wait` поднимет те же данные). Намеренное удаление учебных данных: `docker compose down -v` (удаляет volume `pgdata`), после этого `rm -rf secrets` и заново `sh scripts/init-secrets.sh`.
В persistence-тесте перезапускаются api, postgres и valkey. Сервис api-short-ttl (второй API с TTL 2 с) нужен только для make expiry и в этом тесте не участвует.
Почему два restart-скрипта: тест вызывает hook напрямую, без shell. Python на Windows не может запустить `.sh` (ошибка WinError 193), поэтому для Windows есть `scripts/restart.cmd` с теми же командами. `scripts/restart.sh` — то же самое для Linux/macOS.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```
клиент ──HTTP──> api (FastAPI, :8080 только на 127.0.0.1)
├──> postgres (источник истины: users, chats, chat_members, messages, sessions; volume pgdata)
└──> valkey (кэш «hash токена -> пользователь», без persistence)
```
PostgreSQL и Valkey наружу не опубликованы, доступны только из сети стенда `backend`.
Что перенесено из lab1 и что изменилось:
- `api.py`, `errors.py`, `cursor.py`, `config.py`, Dockerfile, свои тесты перенесены. Маршруты, проверка входных данных, формат ошибок, X-Request-Id, логи без текстов остались как были.
- `store.py`: вместо словарей в памяти и `threading.Lock` теперь PostgreSQL. Методы те же, поэтому `api.py` почти не изменился. Согласованность теперь держат транзакции и ограничения БД.
- Новое: `db.py` (пул соединений, таймауты, миграции), `security.py` (Argon2id, токены, разбор Basic/Bearer), `sessions.py` (сессии и кэш в Valkey), `migrations/*.sql`, `compose.yaml`, скрипты.
- Аутентификация: регистрация с `password`, вход `POST /auth/sessions` только с Basic, дальше только `Authorization: Bearer`. `X-User-Id` больше ничего не значит. Проверка токена выполняется в middleware до разбора тела запроса, поэтому всегда сначала 401, потом 404/400.
Схема БД (migrations/001_core.sql, 002_sessions.sql, 003_text_as_bytes.sql):
- `users`: PK id, UNIQUE username, CHECK формата username и длины display_name, `password_hash` (Argon2id).
- `chats` и `chat_members`: PK (chat_id, user_id), FK на chats и users, индекс (user_id, chat_id) для списка чатов пользователя.
- `messages`: FK (chat_id, sender_id) -> chat_members, то есть сама база не даст записать сообщение от не-участника. Индекс (chat_id, created_at, id) под историю.
- `sessions`: PK = SHA-256 токена (сам токен не хранится), user_id, expires_at, revoked_at.
- `users.display_name`, `chats.title`, `messages.text` хранятся как байты UTF-8 (`bytea`, миграция `003_text_as_bytes.sql`): тип `text` в PostgreSQL не может хранить символ U+0000, а контракт его разрешает. Точное число символов проверяет API, CHECK в базе ограничивает длину в байтах. Если база отвергнет значение (`DataError`), клиент получит 400, а не 500.
Транзакционные границы:
- регистрация — один INSERT; дубль username ловит уникальный индекс (409), а не проверка «есть ли такой» в коде (она уязвима к гонке);
- создание чата — одна транзакция: проверка участников, INSERT чата, INSERT всех участников. Ошибка на любом шаге = ROLLBACK, чата нет;
- отправка сообщения — один INSERT ... SELECT, вставляет строку только если отправитель состоит в чате;
- вход — одна транзакция: удаление старых истёкших/отозванных сессий пользователя и INSERT новой.
Миграции: файлы `migrations/NNN_*.sql` применяются при старте API по порядку. Каждый файл и запись о нём в `schema_migrations` идут в одной транзакции. Повторный запуск применяет только новые файлы. Если стартуют сразу два API (основной и api-short-ttl), `pg_advisory_lock` пускает к миграциям только один процесс.
Сессии и роль Valkey:
- источник истины — таблица `sessions` в PostgreSQL. Она переживает рестарт, срок `expires_at` абсолютный, рестарт его не продлевает;
- Valkey — кэш, чтобы не делать SQL-запрос при каждой проверке токена. Ключ `sess:<sha256 токена>`, значение — пользователь и expires_at;
- expiry в кэше: TTL ключа = min(30 с, остаток жизни сессии); кроме того, expires_at проверяется при чтении, поэтому кэш никогда не продлевает сессию;
- инвалидация: logout сначала ставит revoked_at в PostgreSQL, затем кладёт в кэш вместо записи о сессии отметку «отозвано» (на 30 с). Запись о сессии кладётся в кэш только если ключа нет (`SET NX`), поэтому запрос, прочитавший сессию из базы за мгновение до logout, не может вернуть её в кэш после logout;
- поколение кэша: каждая запись о сессии помечена поколением процесса (случайное значение при старте). При любой ошибке Valkey процесс начинает новое поколение и записям старого больше не доверяет. Если Valkey был недоступен в момент logout (например, `docker compose pause`), запись о сессии осталась в кэше, но после возвращения Valkey она старого поколения: проверка идёт в PostgreSQL, там сессия отозвана — 401. Отметки «отозвано» действуют в любом поколении: они только запрещают;
- persistence у Valkey выключена: кэш после рестарта пустой, данные снова берутся из PostgreSQL;
- если Valkey недоступен, API его обходит и работает напрямую с PostgreSQL. После первой ошибки запросы перестают обращаться к кэшу, а фоновый поток раз в 5 с делает PING и, когда Valkey вернулся, снова включает кэш. Так ожидание подключения к пропавшему Valkey не попадает в запросы пользователей;
- у Valkey ACL: пользователь `default` выключен, `messenger` (пароль из secrets) может только get/set/del/ping и только по ключам `sess:*`, `health` (без пароля) — только ping/info/dbsize.
Пароли и токены: пароль хешируется Argon2id (m=19 МиБ, t=2, p=1 — минимум по OWASP), это медленная функция с солью против перебора. Токен — 32 случайных байта (256 бит), в БД и кэше лежит только его SHA-256: быстрый hash подходит, потому что токен случайный и перебирать его бессмысленно. Неверный пароль и несуществующий пользователь дают одинаковый 401 за одинаковое время (для несуществующего пользователя тоже выполняется проверка Argon2).
Пул и таймауты: PostgreSQL — пул psycopg от 1 до 10 соединений, ожидание соединения 3 с, connect_timeout 3 с, statement_timeout 5 с, idle_in_transaction_session_timeout 10 с; соединение проверяется перед выдачей (после рестарта БД «мёртвые» соединения заменяются). Valkey — пул до 20 соединений, таймаут 300 мс. Все SQL-запросы параметризованные (`%s`), текст запроса никогда не склеивается с вводом пользователя.
Health: `/health/live` — процесс жив. `/health/ready` — PostgreSQL отвечает (таймаут 1 с). Критична только PostgreSQL; без Valkey API готов (работает медленнее). Docker healthcheck API опрашивает `/health/ready`.
Durability: PostgreSQL с fsync=on, synchronous_commit=on, full_page_writes=on (значения по умолчанию, выписаны явно в compose.yaml). Ответ 201 отдаётся после COMMIT, а COMMIT — после записи WAL на диск, поэтому подтверждённое сообщение переживает рестарт и падение процесса БД. Данные лежат в именованном volume `pgdata`.
Соответствие .env.example:
| Переменная | Что делает в этом решении |
| --- | --- |
| APP_HOST, APP_PORT, APP_ENV | где слушает uvicorn (0.0.0.0:8080), APP_ENV пишется в лог |
| SESSION_TTL_SECONDS | срок жизни сессии (3600; у api-short-ttl в compose.yaml — 2) |
| DATABASE_URL_FILE | путь к секрету с адресом PostgreSQL (/run/secrets/database_url) |
| SESSION_STORE=postgres | источник истины сессий — PostgreSQL (другие значения не поддерживаются) |
| CACHE_URL_FILE | путь к секрету с адресом Valkey; пусто = работать без кэша |
| SESSION_CACHE_TTL_SECONDS, DB_*, CACHE_* | дополнительные: TTL записи в кэше, размер пула и таймауты |
Секреты передаются файлами через `secrets:` в Compose (`/run/secrets/...`), а не значениями переменных, поэтому не видны в `docker inspect`. `.env` и `secrets/` в .gitignore.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Публичный smoke | make test | PASS: lab2 public API scenario | evidence/test.txt |
| Замечание к MR: отозванный токен после возвращения Valkey | make failure-valkey-pause (pause valkey → logout → unpause) | во время паузы logout 204 → 401; после unpause 23 проверки за 12 с, GET и POST — всегда 401; другие токены работают | evidence/failure-valkey-pause.txt |
| Замечание к MR: граничная дата в cursor | make student-test (test_bad_cursor_returns_400) | 0001-01-01T00:00:00+14:00 и 9999-12-31T23:59:59-14:00 в курсоре → 400, не 500 | evidence/student-test.txt |
| Строки с U+0000 сохраняются (нашёл сам по замечанию к похожей работе) | make student-test (test_nul_character_is_stored) | display_name, title и text с U+0000 → 201, читаются без изменений; вход с таким логином → 401, не 500 | evidence/student-test.txt |
| Структура skeleton и контракт не изменены | make check | PASS: offline skeleton structure | evidence/check.txt |
| 3: минимум lab1 сохранён, переход на новую аутентификацию | make test, make student-test (тесты lab1 переведены на пароль и Bearer) | smoke PASS; Ran 22 tests, OK | evidence/test.txt, evidence/student-test.txt |
| 3: данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes | make ps; make test-persistence ACTION_SCRIPT=scripts/restart.cmd; make ps | PASS: persistence preserved confirmed data and existing session; ID контейнеров те же, время Up у api, postgres, valkey сбросилось | evidence/persistence.txt |
| 3: в PostgreSQL пользователи, чаты, участники, сообщения; PK/FK; уникальный username | migrations/001_core.sql; make db-test | FK не даёт записать сообщение от не-участника (ForeignKeyViolation); дубль username — 409 | migrations/, evidence/db-test.txt |
| 3: миграции с нуля | docker compose up на пустом volume, docker compose logs api | «Миграции применены: 001_core, 002_sessions», затем при обновлении 003_text_as_bytes | evidence/stack.txt, evidence/persistence.txt |
| 3: повторный запуск миграций без дублирования | make db-test; логи api после рестарта | повторный migrate() ничего не применил; «Миграции: новых нет» | evidence/db-test.txt, evidence/persistence.txt |
| 3: создание чата атомарно | make db-test (test_create_chat_rolls_back_when_failing_midway) | ошибка посреди транзакции, строк chats/chat_members не осталось | evidence/db-test.txt |
| 3: Basic только на POST /auth/sessions | make student-test (test_bearer_required_on_business_endpoints) | Basic на /users/me -> 401 с WWW-Authenticate: Bearer | evidence/student-test.txt |
| 3: остальные endpoint требуют Bearer, X-User-Id не даёт доступ | make test, make student-test | только X-User-Id -> 401; X-User-Id рядом с Bearer не меняет пользователя | evidence/test.txt, evidence/student-test.txt |
| 3: срок жизни сессии и отзыв | make expiry; make student-test (test_logout_*) | после TTL 2 с -> 401; после logout -> 401, другая сессия работает | evidence/expiry.txt, evidence/student-test.txt |
| 3: пароли хешируются password KDF | docker compose exec postgres psql ... SELECT left(password_hash, 30) | $argon2id$v=19$m=19456,t=2,p=1 | evidence/stack.txt |
| 3: secrets и volumes не попадают в Git | git check-ignore -v .env secrets/database_url | оба файла игнорируются правилами .gitignore | evidence/stack.txt |
| 4: Valkey реально используется для кэша сессий (источник истины, expiry, инвалидация описаны выше) | make test, затем make cache-stats (valkey-cli --user health: dbsize, info stats) | keyspace_hits больше нуля, ключи sess:* есть; доступ к другим ключам — NOPERM | evidence/valkey.txt |
| 4: параметризованные запросы | src/messenger/store.py | все значения передаются через %s, SQL не склеивается | код |
| 4: ограниченный connection pool и таймауты | src/messenger/db.py, config.py | пул PostgreSQL 1–10, таймауты 3 с/3 с/5 с; пул Valkey 20, 300 мс | код |
| 4: гонка регистрации одинакового username | make race; make db-test | 20 параллельных запросов: 201 x1, 409 x19 | evidence/race.txt, evidence/db-test.txt |
| 4: rollback составной операции | make db-test | см. строку «создание чата атомарно» | evidence/db-test.txt |
| 4: индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений | make explain (21 500 сообщений, большой чат 12 000) | первая страница: Index Scan по messages_chat_history_idx, 51 строка, 6 буферов | evidence/explain-history.txt |
| 4: пагинация без полного scan истории | make explain, запросы 2–4 | keyset со страницы из середины: 51 строка, 6 буферов; OFFSET 6000: 6051 строка, 163 буфера; без индекса: Seq Scan по всей таблице, Sort, 289 буферов | evidence/explain-history.txt |
| 4: автопроверка expiry при коротком SESSION_TTL_SECONDS | make expiry (api-short-ttl, TTL=2) | до истечения 200, после — 401 на обоих API | evidence/expiry.txt |
| 4: автопроверка logout | make student-test (test_logout_revokes_only_current_session) | 204, затем 401, повторный logout — 401 | evidence/student-test.txt |
| 4: автопроверка неверного пароля | make student-test (test_wrong_password_and_unknown_user_look_the_same) | одинаковый 401 для неверного пароля и неизвестного пользователя | evidence/student-test.txt |
| 4: недоступность Valkey | make failure-valkey | ready 200, вход, сообщения и logout работают через PostgreSQL | evidence/failure-valkey.txt |
| 4: недоступность БД, аноним не становится доверенным | make failure-postgres | ready 503; бизнес-запросы 503 unavailable; без токена 401; неизвестный токен не принят; после старта БД прежний токен работает | evidence/failure-postgres.txt |
| Выбранный трек 5 | | не выбран | |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Ноутбук: AMD Ryzen 7 4700U (8 ядер), 7,4 ГБ памяти, Windows 11, Docker Desktop без лимитов на CPU и память. Нагрузочных экспериментов нет, так как трек 5 не выбран. Ниже проверки отказов уровня 4.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| restart hook: stop api, restart postgres и valkey, start api (volumes на месте) | данные и токен живы | тот же токен читает то же сообщение; ID контейнеров те же, Up сбросился у api, postgres, valkey; кэш пустой и заполняется из PostgreSQL | весь make test-persistence (создание данных, hook, ожидание готовности, проверка) — 10 с; потерь нет |
| docker compose stop valkey | API работает без кэша | ready 200, вход, сообщения, logout работают; первый запрос после остановки ждал около 4 с (на нём обнаружился сбой: подключение к остановленному контейнеру), дальше запросы десятки мс, в том числе через 6 с | после start valkey кэш включается сам в течение 5 с; потерь нет |
| docker compose pause valkey, logout, unpause (данные в кэше сохранились) | отозванный токен не оживает | во время паузы 401; после unpause кэш снова включился, но запись до сбоя старого поколения — 401 при каждой из 23 проверок | кэш снова работает через ≤5 с; отзыв не теряется |
| docker compose stop postgres | ограниченная ошибка, никого не пускаем без проверки | ready 503 за ~1 с, бизнес-запросы 503, без токена 401 | после start postgres прежний токен и сообщения на месте; запросы во время отказа не сохранены (получили 503) |
| 20 одновременных регистраций одного username | один победитель | 201 x1, 409 x19 | дублей нет |
| 10 клиентов x 10 сообщений одновременно | ровно 100 сообщений | 100, все id уникальны | потерь нет |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- PostgreSQL одна: если упала она или весь Docker-host, API отвечает 503. Отказоустойчивости к потере хоста нет, бэкапов нет.
- Конкурентные вставки: created_at = время начала транзакции. Сообщение, которое закоммитилось позже, может получить более раннее время, и клиент, уже пролиставший дальше по курсору, его не увидит. Повторов нет, но такую запись можно пропустить; это ограничение keyset-пагинации по времени.
- Первый запрос после пропадания Valkey ждёт обнаружения сбоя (на Windows/Docker Desktop около 4 с), следующие идут без кэша сразу.
- Поколение кэша своё у каждого процесса API. Если logout во время сбоя Valkey прошёл через один экземпляр (например, api-short-ttl), а другой экземпляр сбоя не заметил, второй может до 30 с доверять своей старой записи. В lab2 основной API один; для нескольких реплик (lab3) поколение нужно хранить общим.
- Приложение подключается к PostgreSQL пользователем-владельцем базы. Отдельная роль с минимальными правами — в lab7.
- Basic по HTTP передаёт пароль открыто (base64 — это не шифрование). Допустимо только на локальном стенде, TLS — в lab7.
- Старые сессии чистятся только при входе того же пользователя; периодической очистки нет.
- Свободный текст хранится как `bytea`: искать по нему средствами SQL (LIKE, полнотекстовый поиск) напрямую нельзя. Обязательный API такого поиска не требует.
+88
View File
@@ -0,0 +1,88 @@
# Стенд lab2: API + PostgreSQL (источник истины) + Valkey (кэш сессий).
# Запуск: docker compose up -d --build --wait
# Секреты: sh scripts/init-secrets.sh (создаёт каталог secrets/, он в .gitignore)
name: mtusi-lab2
# Общие настройки для всех процессов приложения (обычный API, API с коротким TTL, тесты БД).
x-app: &app
image: mtusi-messenger:lab2
env_file: .env
secrets: [database_url, cache_url]
depends_on:
postgres: {condition: service_healthy}
valkey: {condition: service_healthy}
networks: [backend]
services:
api:
<<: *app
build: .
ports: ["127.0.0.1:8080:8080"] # только на localhost хоста; БД и Valkey наружу не опубликованы
restart: unless-stopped
stop_grace_period: 10s
# Второй экземпляр API с SESSION_TTL_SECONDS=2 — только для проверки истечения сессии.
# Та же база, тот же код; запускается явно: docker compose --profile ttl up -d api-short-ttl
api-short-ttl:
<<: *app
profiles: [ttl]
pull_policy: never # образ собирается сервисом api, а не скачивается
environment:
SESSION_TTL_SECONDS: "2"
ports: ["127.0.0.1:8081:8080"]
restart: unless-stopped
# Интеграционные тесты хранилища (откат транзакции, повтор миграций, гонка регистрации).
# Запуск: docker compose --profile tools run --rm db-test
db-test:
<<: *app
profiles: [tools]
pull_policy: never
volumes: ["./student-tests:/srv/student-tests:ro"]
command: ["python", "-m", "unittest", "discover", "-s", "student-tests/db", "-v"]
postgres:
image: postgres:17.10-bookworm
environment:
POSTGRES_USER: messenger
POSTGRES_DB: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password # пароль из файла, не из переменной
# Значения по умолчанию, выписанные явно: COMMIT возвращается только после записи WAL на диск.
command: ["postgres", "-c", "fsync=on", "-c", "synchronous_commit=on", "-c", "full_page_writes=on"]
secrets: [postgres_password]
volumes: ["pgdata:/var/lib/postgresql/data"] # именованный volume: данные переживают пересоздание контейнера
healthcheck:
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U messenger -d messenger"]
interval: 5s
timeout: 3s
retries: 12
start_period: 10s
restart: unless-stopped
stop_grace_period: 30s # PostgreSQL успевает корректно завершиться (checkpoint)
networks: [backend]
valkey:
image: valkey/valkey:8.1.9
command: ["valkey-server", "/usr/local/etc/valkey/valkey.conf"]
volumes: ["./infra/valkey/valkey.conf:/usr/local/etc/valkey/valkey.conf:ro"]
secrets: [valkey_acl] # пользователи и пароль Valkey (ACL), генерируются init-secrets.sh
healthcheck:
# Пользователь health без пароля может только ping/info/dbsize — данных он не видит.
test: ["CMD-SHELL", "valkey-cli --user health --pass none --no-auth-warning ping | grep -q PONG"]
interval: 5s
timeout: 3s
retries: 12
restart: unless-stopped
networks: [backend]
volumes:
pgdata: {}
secrets:
postgres_password: {file: ./secrets/postgres_password}
database_url: {file: ./secrets/database_url}
cache_url: {file: ./secrets/cache_url}
valkey_acl: {file: ./secrets/valkey_users.acl}
networks:
backend: {}
+2
View File
@@ -0,0 +1,2 @@
python scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
+26
View File
@@ -0,0 +1,26 @@
docker compose --profile tools run --rm db-test
Container mtusi-lab2-postgres-1 Running
Container mtusi-lab2-valkey-1 Running
Container mtusi-lab2-valkey-1 Waiting
Container mtusi-lab2-postgres-1 Waiting
Container mtusi-lab2-valkey-1 Healthy
Container mtusi-lab2-postgres-1 Healthy
Container mtusi-lab2-db-test-run-343a686d3ad8 Creating
Container mtusi-lab2-db-test-run-343a686d3ad8 Created
test_concurrent_registration_has_one_winner (test_store.StoreIntegrationTest.test_concurrent_registration_has_one_winner) ...
20 параллельных create_user: 1 создан, 19 получили Conflict (409)
ok
test_create_chat_rolls_back_when_failing_midway (test_store.StoreIntegrationTest.test_create_chat_rolls_back_when_failing_midway) ...
чат с несуществующим участником: транзакция откатилась, строк chats/chat_members не осталось
ok
test_database_rejects_message_from_non_member (test_store.StoreIntegrationTest.test_database_rejects_message_from_non_member) ... ok
test_migrations_rerun_is_noop (test_store.StoreIntegrationTest.test_migrations_rerun_is_noop) ...
INSERT сообщения от не-участника напрямую в БД: ForeignKeyViolation
ok
schema_migrations: ['001_core', '002_sessions', '003_text_as_bytes']; повторный migrate() ничего не применил
----------------------------------------------------------------------
Ran 4 tests in 0.190s
OK
+22
View File
@@ -0,0 +1,22 @@
docker compose --profile ttl up -d --wait api-short-ttl
Container mtusi-lab2-valkey-1 Running
Container mtusi-lab2-postgres-1 Running
Container mtusi-lab2-api-short-ttl-1 Recreate
Container mtusi-lab2-api-short-ttl-1 Recreated
Container mtusi-lab2-postgres-1 Waiting
Container mtusi-lab2-valkey-1 Waiting
Container mtusi-lab2-valkey-1 Healthy
Container mtusi-lab2-postgres-1 Healthy
Container mtusi-lab2-api-short-ttl-1 Starting
Container mtusi-lab2-api-short-ttl-1 Started
Container mtusi-lab2-valkey-1 Waiting
Container mtusi-lab2-api-short-ttl-1 Waiting
Container mtusi-lab2-postgres-1 Waiting
Container mtusi-lab2-valkey-1 Healthy
Container mtusi-lab2-postgres-1 Healthy
Container mtusi-lab2-api-short-ttl-1 Healthy
python student-tests/expiry.py
session issued by short-TTL API, expires in 1.99s
before expiry: GET /users/me -> 200 (short API twice, main API once)
after expiry: GET /users/me -> 401 on both instances
PASS: session expired after SESSION_TTL_SECONDS; cache did not extend it
+71
View File
@@ -0,0 +1,71 @@
docker compose exec -T postgres psql -X -q -U messenger -d messenger -v ON_ERROR_STOP=1 < infra/sql/explain_history.sql
=== Объём данных
messages_total | messages_in_big_chat
----------------+----------------------
21650 | 12000
=== Индекс истории (migrations/001_core.sql)
indexdef
-------------------------------------------------------------------------------------------------
CREATE INDEX messages_chat_history_idx ON public.messages USING btree (chat_id, created_at, id)
=== 1. Первая страница (limit=50, приложение просит 51 строку, чтобы понять, есть ли следующая)
QUERY PLAN
---------------------------------------------------------------------------------------------------------
Limit (actual time=0.023..0.043 rows=51 loops=1)
Buffers: shared hit=6
-> Index Scan using messages_chat_history_idx on messages (actual time=0.022..0.036 rows=51 loops=1)
Index Cond: (chat_id = 'b0b6cd43-57d9-4deb-99f3-e04443a88e4c'::uuid)
Buffers: shared hit=6
Planning:
Buffers: shared hit=6
Planning Time: 0.160 ms
Execution Time: 0.077 ms
=== 2. Страница из середины истории по keyset-курсору (после 6000-го сообщения)
QUERY PLAN
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Limit (actual time=0.019..0.055 rows=51 loops=1)
Buffers: shared hit=6
-> Index Scan using messages_chat_history_idx on messages (actual time=0.018..0.044 rows=51 loops=1)
Index Cond: ((chat_id = 'b0b6cd43-57d9-4deb-99f3-e04443a88e4c'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 01:40:00+00'::timestamp with time zone, 'bc979085-5d84-44a6-9df2-3b1fff1bdaf1'::uuid)))
Buffers: shared hit=6
Planning Time: 0.157 ms
Execution Time: 0.122 ms
=== 3. Для сравнения: та же страница через OFFSET (так приложение НЕ делает)
QUERY PLAN
-----------------------------------------------------------------------------------------------------------
Limit (actual time=1.586..1.603 rows=51 loops=1)
Buffers: shared hit=163
-> Index Scan using messages_chat_history_idx on messages (actual time=0.020..1.305 rows=6051 loops=1)
Index Cond: (chat_id = 'b0b6cd43-57d9-4deb-99f3-e04443a88e4c'::uuid)
Buffers: shared hit=163
Planning Time: 0.095 ms
Execution Time: 1.625 ms
=== 4. Для сравнения: запрос 2 без индекса (индекс удалён только внутри этой транзакции)
QUERY PLAN
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Limit (actual time=4.238..4.247 rows=51 loops=1)
Buffers: shared hit=289
-> Sort (actual time=4.237..4.241 rows=51 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 31kB
Buffers: shared hit=289
-> Seq Scan on messages (actual time=0.967..3.376 rows=6000 loops=1)
Filter: ((chat_id = 'b0b6cd43-57d9-4deb-99f3-e04443a88e4c'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 01:40:00+00'::timestamp with time zone, 'bc979085-5d84-44a6-9df2-3b1fff1bdaf1'::uuid)))
Rows Removed by Filter: 15650
Buffers: shared hit=289
Planning:
Buffers: shared hit=4
Planning Time: 0.119 ms
Execution Time: 4.268 ms
=== ROLLBACK: синтетические данные удалены, индекс на месте
+12
View File
@@ -0,0 +1,12 @@
python student-tests/dependency_failure.py postgres
stopping postgres (docker compose stop postgres)
/health/live -> 200: процесс жив
/health/ready -> 503 (1000 ms): без PostgreSQL обслуживать нельзя
бизнес-запросы с действующим токеном -> 503 unavailable (без SQL и stack trace в ответе)
без токена -> 401: аноним не становится доверенным
неизвестный токен -> 503: не подтверждается ни кэшем, ни базой
вход -> 503: сессию без базы не выдаём
регистрация -> 503
starting postgres again
after recovery: прежний токен работает, подтверждённые сообщения на месте
PASS: postgres outage handled without trusting anonymous requests
+7
View File
@@ -0,0 +1,7 @@
python student-tests/cache_revocation.py
pausing valkey (docker compose pause valkey): данные в кэше сохраняются
во время паузы: logout -> 204, тот же токен -> 401
unpausing valkey
после unpause: 23 проверок за 12 с, отозванный токен всегда 401 (и GET, и POST)
действующие токены других пользователей работают
PASS: revoked session stays revoked after Valkey comes back with stale data
+12
View File
@@ -0,0 +1,12 @@
python student-tests/dependency_failure.py valkey
stopping valkey (docker compose stop valkey)
/health/ready -> 200 (16 ms): Valkey не критичен, API готов
existing token: GET /users/me -> 200 (4015 ms), сессия проверена по PostgreSQL (этот запрос и обнаружил сбой кэша)
POST message -> 201, история читается
register + login new user -> 201
logout -> 204, затем тот же токен -> 401 (отзыв записан в PostgreSQL)
10 x GET /users/me без кэша: max 32 ms (кэш не ждём на каждом запросе)
через 6 с, ещё 10 x GET /users/me: max 31 ms (повторные попытки — в фоне)
starting valkey again
after recovery: прежний токен работает, подтверждённые сообщения на месте
PASS: valkey outage handled without trusting anonymous requests
+21
View File
@@ -0,0 +1,21 @@
docker compose ps -a --format "table {{.Service}}\t{{.ID}}\t{{.Status}}"
SERVICE CONTAINER ID STATUS
api 5d506a14e681 Up About a minute (healthy)
api-short-ttl 6e433cfb380a Up 9 seconds (healthy)
postgres 094d2f567e2e Up 22 seconds (healthy)
valkey 195f4a7b30f1 Up 44 seconds (healthy)
python tests/resilience.py --mode persistence --action-script "scripts/restart.cmd" --base-url "http://127.0.0.1:8080"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
real 0m10.093s
user 0m0.031s
sys 0m0.000s
docker compose ps -a --format "table {{.Service}}\t{{.ID}}\t{{.Status}}"
SERVICE CONTAINER ID STATUS
api 5d506a14e681 Up 2 seconds (health: starting)
api-short-ttl 6e433cfb380a Up 20 seconds (healthy)
postgres 094d2f567e2e Up 7 seconds (healthy)
valkey 195f4a7b30f1 Up 7 seconds (healthy)
api-1 | 2026-10-09 21:17:33,062 INFO messenger.db: Миграции: новых нет, схема актуальна
api-1 | 2026-10-09 21:19:16,340 INFO messenger.db: Миграции: новых нет, схема актуальна
+6
View File
@@ -0,0 +1,6 @@
python student-tests/race.py
messages: sent 100 from 10 parallel clients in 0.97s
messages: read 100 in 4 pages, unique ids: 100
PASS: 100 concurrent messages stored without loss or duplicates
registration: 20 parallel requests for one username -> 201 x1, 409 x19
PASS: concurrent registration of the same username created exactly one user
+16
View File
@@ -0,0 +1,16 @@
Docker version 29.6.2, build dfc4efb
Docker Compose version v5.3.1
CONTAINER REPOSITORY TAG PLATFORM IMAGE ID SIZE CREATED
mtusi-lab2-api-1 mtusi-messenger lab2 linux/amd64 22006a69bb96 57.7MB 50 seconds ago
mtusi-lab2-postgres-1 postgres 17.10-bookworm linux/amd64 9b18b7839705 156MB 2 months ago
mtusi-lab2-valkey-1 valkey/valkey 8.1.9 linux/amd64 d5e642b89ee0 46MB 5 weeks ago
docker compose ps -a --format "table {{.Service}}\t{{.ID}}\t{{.Status}}"
SERVICE CONTAINER ID STATUS
api 08b92853bbb4 Up 39 seconds (healthy)
postgres 094d2f567e2e Up 46 seconds (healthy)
valkey 195f4a7b30f1 Up 46 seconds (healthy)
api-1 | 2026-10-09 10:18:10,200 INFO messenger.db: Миграции применены: 001_core, 002_sessions
uid=10001(app) gid=999(app) groups=999(app)
$argon2id$v=19$m=19456,t=2,p=1
.gitignore:2:.env .env
.gitignore:5:secrets/ secrets/database_url
+28
View File
@@ -0,0 +1,28 @@
python -m unittest discover -s student-tests -p "test_*.py" -v
test_auth_checked_before_access_and_body (test_api.MessengerApiTest.test_auth_checked_before_access_and_body) ... ok
test_bad_cursor_returns_400 (test_api.MessengerApiTest.test_bad_cursor_returns_400) ... ok
test_chat_list_pagination (test_api.MessengerApiTest.test_chat_list_pagination) ... ok
test_chat_membership_rules (test_api.MessengerApiTest.test_chat_membership_rules) ... ok
test_duplicate_username_returns_409 (test_api.MessengerApiTest.test_duplicate_username_returns_409) ... ok
test_empty_blank_and_too_long_messages_return_400 (test_api.MessengerApiTest.test_empty_blank_and_too_long_messages_return_400) ... ok
test_malformed_json_returns_400 (test_api.MessengerApiTest.test_malformed_json_returns_400) ... ok
test_nul_character_is_stored (test_api.MessengerApiTest.test_nul_character_is_stored) ... ok
test_outsider_gets_404_for_foreign_chat (test_api.MessengerApiTest.test_outsider_gets_404_for_foreign_chat) ... ok
test_pagination_walks_several_pages (test_api.MessengerApiTest.test_pagination_walks_several_pages) ... ok
test_unicode_roundtrip (test_api.MessengerApiTest.test_unicode_roundtrip) ... ok
test_wrong_types_and_extra_fields_return_400 (test_api.MessengerApiTest.test_wrong_types_and_extra_fields_return_400) ... ok
test_bearer_required_on_business_endpoints (test_auth.AuthTest.test_bearer_required_on_business_endpoints) ... ok
test_login_returns_opaque_token_with_expiry (test_auth.AuthTest.test_login_returns_opaque_token_with_expiry) ... ok
test_logout_revokes_only_current_session (test_auth.AuthTest.test_logout_revokes_only_current_session) ... ok
test_malformed_basic_returns_401 (test_auth.AuthTest.test_malformed_basic_returns_401) ... ok
test_password_length_rules (test_auth.AuthTest.test_password_length_rules) ... ok
test_password_with_colon_and_unicode (test_auth.AuthTest.test_password_with_colon_and_unicode) ... ok
test_relogin_after_logout (test_auth.AuthTest.test_relogin_after_logout) ... ok
test_user_never_contains_password (test_auth.AuthTest.test_user_never_contains_password) ... ok
test_wrong_password_and_unknown_user_look_the_same (test_auth.AuthTest.test_wrong_password_and_unknown_user_look_the_same) ... ok
test_x_user_id_does_not_change_identity (test_auth.AuthTest.test_x_user_id_does_not_change_identity) ... ok
----------------------------------------------------------------------
Ran 22 tests in 2.609s
OK
+2
View File
@@ -0,0 +1,2 @@
python tests/smoke.py --base-url "http://127.0.0.1:8080"
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
+8
View File
@@ -0,0 +1,8 @@
docker compose exec -T valkey valkey-cli --user health --pass none --no-auth-warning dbsize
5
docker compose exec -T valkey valkey-cli --user health --pass none --no-auth-warning info stats | grep -E "keyspace_(hits|misses)"
keyspace_hits:16
keyspace_misses:2
docker compose exec -T valkey valkey-cli --user health --pass none --no-auth-warning get sess:anything
NOPERM User health has no permissions to run the 'get' command
+74
View File
@@ -0,0 +1,74 @@
-- Обоснование индекса истории сообщений: EXPLAIN (ANALYZE, BUFFERS) на синтетических данных.
-- Запуск: make explain > evidence/explain-history.txt
-- (= docker compose exec -T postgres psql -U messenger -d messenger < infra/sql/explain_history.sql)
--
-- Всё выполняется в одной транзакции и в конце откатывается (ROLLBACK):
-- синтетические данные не остаются в базе, скрипт можно запускать сколько угодно раз.
-- DROP INDEX внутри транзакции на время скрипта блокирует запись в messages — запускать на учебном стенде.
\pset footer off
BEGIN;
-- 1 «большой» чат на 12 000 сообщений и 19 чатов по 500 (всего 21 500 сообщений):
-- в таблице есть чужие сообщения, как в настоящей базе.
CREATE TEMP TABLE seed_chats AS
SELECT gen_random_uuid() AS chat_id, n, CASE WHEN n = 0 THEN 12000 ELSE 500 END AS size
FROM generate_series(0, 19) AS n;
CREATE TEMP TABLE seed_user AS SELECT gen_random_uuid() AS user_id;
INSERT INTO users (id, username, display_name, password_hash)
SELECT user_id, 'explain_' || substr(md5(random()::text), 1, 12), convert_to('EXPLAIN', 'UTF8'), 'not-a-real-hash' FROM seed_user;
INSERT INTO chats (id, title) SELECT chat_id, convert_to('explain ' || n, 'UTF8') FROM seed_chats;
INSERT INTO chat_members (chat_id, user_id) SELECT chat_id, user_id FROM seed_chats, seed_user;
INSERT INTO messages (id, chat_id, sender_id, text, created_at)
SELECT gen_random_uuid(), c.chat_id, u.user_id, convert_to('synthetic message ' || g, 'UTF8'),
timestamptz '2026-01-01 00:00:00+00' + g * interval '1 second'
FROM seed_chats c, seed_user u, generate_series(1, c.size) AS g;
ANALYZE messages;
SELECT chat_id AS big_chat FROM seed_chats WHERE n = 0 \gset
-- Курсор «середины истории»: ключ (created_at, id) 6000-го сообщения большого чата.
SELECT created_at AS cur_ts, id AS cur_id FROM messages
WHERE chat_id = :'big_chat' ORDER BY created_at, id OFFSET 5999 LIMIT 1 \gset
\echo '=== Объём данных'
SELECT count(*) AS messages_total,
count(*) FILTER (WHERE chat_id = :'big_chat') AS messages_in_big_chat
FROM messages;
\echo ''
\echo '=== Индекс истории (migrations/001_core.sql)'
SELECT indexdef FROM pg_indexes WHERE indexname = 'messages_chat_history_idx';
\echo ''
\echo '=== 1. Первая страница (limit=50, приложение просит 51 строку, чтобы понять, есть ли следующая)'
EXPLAIN (ANALYZE, BUFFERS, COSTS OFF)
SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = :'big_chat'
ORDER BY created_at, id LIMIT 51;
\echo ''
\echo '=== 2. Страница из середины истории по keyset-курсору (после 6000-го сообщения)'
EXPLAIN (ANALYZE, BUFFERS, COSTS OFF)
SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = :'big_chat' AND (created_at, id) > (:'cur_ts'::timestamptz, :'cur_id'::uuid)
ORDER BY created_at, id LIMIT 51;
\echo ''
\echo '=== 3. Для сравнения: та же страница через OFFSET (так приложение НЕ делает)'
EXPLAIN (ANALYZE, BUFFERS, COSTS OFF)
SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = :'big_chat'
ORDER BY created_at, id OFFSET 6000 LIMIT 51;
\echo ''
\echo '=== 4. Для сравнения: запрос 2 без индекса (индекс удалён только внутри этой транзакции)'
DROP INDEX messages_chat_history_idx;
EXPLAIN (ANALYZE, BUFFERS, COSTS OFF)
SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = :'big_chat' AND (created_at, id) > (:'cur_ts'::timestamptz, :'cur_id'::uuid)
ORDER BY created_at, id LIMIT 51;
ROLLBACK;
\echo ''
\echo '=== ROLLBACK: синтетические данные удалены, индекс на месте'
+20
View File
@@ -0,0 +1,20 @@
# Valkey в этой работе — КЭШ сессий. Источник истины — таблица sessions в PostgreSQL.
# Поэтому persistence выключена: после рестарта кэш пустой, данные заново берутся из БД.
bind 0.0.0.0
port 6379
protected-mode yes
# Пользователи и пароли — в секрете (scripts/init-secrets.sh создаёт secrets/valkey_users.acl):
# default — выключен (анонимный доступ запрещён);
# health — без пароля, только ping/info/dbsize (для healthcheck и наблюдения);
# messenger — пароль, только ключи sess:* и только команды get/set/del/ping.
aclfile /run/secrets/valkey_acl
# Без сохранения на диск: ни RDB-снимков, ни AOF.
save ""
appendonly no
# Ограничение памяти. Все ключи с TTL; при нехватке выбрасываются давно не читанные.
maxmemory 64mb
maxmemory-policy allkeys-lru
+45
View File
@@ -0,0 +1,45 @@
-- 001: пользователи, чаты, участники, сообщения.
-- Применяется один раз; номер версии записывается в schema_migrations (см. src/messenger/db.py).
-- Все проверки, которые важны для целостности, продублированы в базе: даже если в коде
-- появится ошибка, PostgreSQL не даст записать некорректные данные.
CREATE TABLE users (
id uuid PRIMARY KEY,
username text NOT NULL,
display_name text NOT NULL,
password_hash text NOT NULL, -- строка Argon2id ($argon2id$...), не сам пароль
created_at timestamptz NOT NULL DEFAULT now(),
CONSTRAINT users_username_key UNIQUE (username), -- защищает от гонки двух регистраций
CONSTRAINT users_username_format CHECK (username ~ '^[a-z0-9_]{3,32}$'),
CONSTRAINT users_display_name_len CHECK (char_length(display_name) BETWEEN 1 AND 100)
);
CREATE TABLE chats (
id uuid PRIMARY KEY,
title text NOT NULL CHECK (char_length(title) BETWEEN 1 AND 100),
created_at timestamptz NOT NULL DEFAULT now()
);
-- Членство: какой пользователь в каком чате. Первичный ключ исключает дубликаты.
CREATE TABLE chat_members (
chat_id uuid NOT NULL REFERENCES chats (id),
user_id uuid NOT NULL REFERENCES users (id),
PRIMARY KEY (chat_id, user_id)
);
-- «Список чатов пользователя»: поиск по user_id (PK начинается с chat_id и тут не помогает).
CREATE INDEX chat_members_user_idx ON chat_members (user_id, chat_id);
CREATE TABLE messages (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL,
sender_id uuid NOT NULL,
text text NOT NULL CHECK (char_length(text) BETWEEN 1 AND 4000),
created_at timestamptz NOT NULL DEFAULT now(),
-- Отправитель обязан быть участником этого чата: внешний ключ на пару (чат, участник).
CONSTRAINT messages_sender_is_member FOREIGN KEY (chat_id, sender_id)
REFERENCES chat_members (chat_id, user_id)
);
-- История чата: WHERE chat_id = ? AND (created_at, id) > (?, ?) ORDER BY created_at, id LIMIT ?
-- Индекс уже отсортирован в нужном порядке, поэтому страница читается без сортировки
-- и без просмотра всей истории. Обоснование и EXPLAIN: evidence/explain-history.txt.
CREATE INDEX messages_chat_history_idx ON messages (chat_id, created_at, id);
+13
View File
@@ -0,0 +1,13 @@
-- 002: серверные сессии (источник истины для Bearer-токенов).
-- Хранится не сам токен, а его SHA-256: утечка таблицы не даёт рабочих токенов.
CREATE TABLE sessions (
token_hash bytea PRIMARY KEY CHECK (octet_length(token_hash) = 32),
user_id uuid NOT NULL REFERENCES users (id),
created_at timestamptz NOT NULL DEFAULT now(),
expires_at timestamptz NOT NULL, -- абсолютное время: рестарт не продлевает сессию
revoked_at timestamptz, -- заполнено = logout
CONSTRAINT sessions_expiry_after_creation CHECK (expires_at > created_at)
);
-- Очистка старых сессий пользователя при входе (DELETE ... WHERE user_id = ?).
CREATE INDEX sessions_user_idx ON sessions (user_id);
+28
View File
@@ -0,0 +1,28 @@
-- 003: свободный текст хранится как байты UTF-8 (bytea), а не как text.
--
-- Причина: тип text в PostgreSQL не может содержать символ U+0000 (байт 0x00), а контракт
-- этот символ в display_name, title и text не запрещает. Строка "hello\u0000world" давала 500.
-- В bytea байт 0x00 допустим, поэтому такие строки теперь сохраняются и возвращаются без изменений.
-- Кодирование/декодирование UTF-8 — в src/messenger/store.py (to_db/from_db).
--
-- Это новая миграция, а не правка 001: 001 уже применена на существующих стендах.
-- Уже сохранённые данные переводятся через convert_to и не теряются.
--
-- Точное число символов (1–100, 1–4000) проверяет API. Функции PostgreSQL, которые считают
-- символы в bytea, отвергают байт 0x00, поэтому CHECK в базе ограничивает длину в байтах:
-- не пусто и не больше 4 байт на символ (максимальный размер символа в UTF-8).
ALTER TABLE users DROP CONSTRAINT users_display_name_len;
ALTER TABLE users ALTER COLUMN display_name TYPE bytea USING convert_to(display_name, 'UTF8');
ALTER TABLE users ADD CONSTRAINT users_display_name_len
CHECK (octet_length(display_name) BETWEEN 1 AND 400);
ALTER TABLE chats DROP CONSTRAINT chats_title_check;
ALTER TABLE chats ALTER COLUMN title TYPE bytea USING convert_to(title, 'UTF8');
ALTER TABLE chats ADD CONSTRAINT chats_title_len
CHECK (octet_length(title) BETWEEN 1 AND 400);
ALTER TABLE messages DROP CONSTRAINT messages_text_check;
ALTER TABLE messages ALTER COLUMN text TYPE bytea USING convert_to(text, 'UTF8');
ALTER TABLE messages ADD CONSTRAINT messages_text_len
CHECK (octet_length(text) BETWEEN 1 AND 16000);
+22
View File
@@ -0,0 +1,22 @@
# Все зависимости закреплены точными версиями (включая транзитивные),
# чтобы сборка образа через месяц дала то же самое, что сегодня.
annotated-types==0.8.0
anyio==4.15.1
argon2-cffi==25.1.0 # Argon2id для паролей
argon2-cffi-bindings==26.1.0
cffi==2.1.1
click==8.5.0
fastapi==0.115.12
h11==0.16.0
idna==3.20
psycopg==3.3.6 # драйвер PostgreSQL
psycopg-binary==3.3.6
psycopg-pool==3.3.3 # пул соединений
pycparser==3.1
pydantic==2.13.5
pydantic_core==2.46.5
starlette==0.46.2
typing-inspection==0.4.4
typing_extensions==4.16.0
uvicorn==0.34.3
valkey==6.1.1 # клиент Valkey (кэш сессий)
+35
View File
@@ -0,0 +1,35 @@
#!/bin/sh
# Создаёт локальные секреты стенда в каталоге secrets/ (он в .gitignore и в Git не попадает).
# Запуск один раз: sh scripts/init-secrets.sh
# Повторный запуск ничего не меняет: у уже созданного volume PostgreSQL пароль сменить так нельзя.
set -eu
cd "$(dirname "$0")/.."
if [ -e secrets/postgres_password ]; then
echo "secrets/ уже существует, оставляю как есть."
echo "Чтобы начать с нуля: docker compose down -v (удалит данные!), затем удалить secrets/ и запустить снова."
exit 0
fi
umask 077 # каталог secrets/ доступен только владельцу
mkdir -p secrets
# 24 случайных байта -> 48 hex-символов. /dev/urandom есть и в Linux/macOS, и в Git Bash.
random_hex() { od -An -tx1 -N24 /dev/urandom | tr -d ' \n'; }
PG_PASSWORD=$(random_hex)
CACHE_PASSWORD=$(random_hex)
# printf без перевода строки в конце: в файле только значение.
printf '%s' "$PG_PASSWORD" > secrets/postgres_password
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$PG_PASSWORD" > secrets/database_url
printf 'valkey://messenger:%s@valkey:6379/0' "$CACHE_PASSWORD" > secrets/cache_url
printf '%s\n' \
'user default off' \
'user health on nopass -@all +ping +info +dbsize' \
"user messenger on >$CACHE_PASSWORD ~sess:* resetchannels -@all +get +set +del +ping" \
> secrets/valkey_users.acl
# Файлы читают процессы в контейнерах под своими пользователями (postgres, valkey, app),
# поэтому сами файлы доступны на чтение; посторонних на хосте не пускает каталог (700).
chmod 644 secrets/*
echo "Готово: secrets/postgres_password, database_url, cache_url, valkey_users.acl (значения не выводятся)."
+9
View File
@@ -0,0 +1,9 @@
@echo off
rem Windows restart hook for "make test-persistence": same steps as scripts/restart.sh.
rem Python on Windows cannot run .sh directly (WinError 193), so this .cmd is used instead.
rem Restarts API and ALL stores (PostgreSQL, Valkey); volumes are kept (no down -v).
cd /d "%~dp0.."
docker compose stop api || exit /b 1
docker compose restart postgres valkey || exit /b 1
docker compose start api || exit /b 1
exit /b 0
+10
View File
@@ -0,0 +1,10 @@
#!/bin/sh
# Restart hook для make test-persistence (Linux/macOS).
# Перезапускает API и ВСЕ используемые хранилища (PostgreSQL, Valkey), сохраняя volumes.
# Ничего не удаляет: нет down -v, flush или повторного seed. Контейнеры те же (restart, не recreate).
set -eu
cd "$(dirname "$0")/.."
docker compose stop api # API останавливается первым: не ловит ошибки БД во время рестарта
docker compose restart postgres valkey # корректная остановка (SIGINT/SIGTERM) и запуск тех же контейнеров
docker compose start api # API ждёт готовности PostgreSQL и проверяет миграции
+1
View File
@@ -0,0 +1 @@
"""Учебный мессенджер МТУСИ: REST API по contracts/openapi.json, данные в PostgreSQL."""
+27
View File
@@ -0,0 +1,27 @@
"""Точка входа: `python -m messenger`.
В контейнере этот процесс — главный (PID 1). uvicorn сам перехватывает SIGTERM:
перестаёт принимать новые соединения, ждёт завершения начатых запросов
(не дольше GRACEFUL_SHUTDOWN_SECONDS) и завершается.
"""
import logging
import uvicorn
from . import config
from .api import app
def main():
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
uvicorn.run(
app,
host=config.APP_HOST,
port=config.APP_PORT,
access_log=False, # строку на каждый запрос пишет наш middleware (без тел и query)
timeout_graceful_shutdown=config.GRACEFUL_SHUTDOWN_SECONDS,
)
if __name__ == "__main__":
main()
+264
View File
@@ -0,0 +1,264 @@
"""HTTP-слой: маршруты из contracts/openapi.json, проверка входных данных, единый формат ошибок.
Здесь нет правил предметной области (кто может писать в чат и т.п.) — они в store.py.
Что изменилось с lab1:
- данные в PostgreSQL (store.py), сессии — sessions.py;
- регистрация принимает password, вход — POST /auth/sessions с Basic, выход — DELETE;
- «кто я» определяется только по Bearer-токену; X-User-Id больше ничего не значит.
"""
import logging
import time
import uuid
from contextlib import asynccontextmanager
from dataclasses import asdict
from typing import Annotated
from fastapi import Depends, FastAPI, Header, Query, Request, Response
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import AfterValidator, BaseModel, ConfigDict, Field
from starlette.concurrency import run_in_threadpool
from starlette.exceptions import HTTPException as StarletteHTTPException
from . import config, db, security
from .cursor import decode_cursor, encode_cursor
from .errors import AppError, Unauthorized
from .sessions import AuthContext, SessionCache, Sessions
from .store import PostgresStore, User, sort_key
log = logging.getLogger("messenger")
# Один набор объектов на процесс. Пул соединений открывается при старте (lifespan).
pool = db.create_pool()
store = PostgresStore(pool)
cache = SessionCache(config.CACHE_URL)
sessions = Sessions(store, cache, config.SESSION_TTL_SECONDS)
@asynccontextmanager
async def lifespan(_app: FastAPI):
config.validate()
await run_in_threadpool(db.migrate_with_retry) # схема БД готова до первого запроса
pool.open()
log.info("Сервер запущен: env=%s, TTL сессии=%s c, кэш сессий: %s",
config.APP_ENV, config.SESSION_TTL_SECONDS, "Valkey" if cache.enabled else "выключен")
yield
pool.close() # аккуратно закрываем соединения с БД при SIGTERM
log.info("Остановка: соединения с PostgreSQL закрыты, данные остаются в базе")
app = FastAPI(title="MTUSI Messenger, lab2", lifespan=lifespan)
# ---------- ошибки и служебная обёртка каждого запроса ----------
def error_response(request: Request, status: int, code: str, message: str,
headers: dict[str, str] | None = None) -> JSONResponse:
body = {"error": {"code": code, "message": message, "request_id": request.state.request_id}}
return JSONResponse(body, status_code=status, headers=headers)
# Эти два адреса доступны без токена. Всё остальное под /api/ требует Bearer.
PUBLIC_ENDPOINTS = {("POST", "/api/v1/users"), ("POST", "/api/v1/auth/sessions")}
def needs_bearer(request: Request) -> bool:
return request.url.path.startswith("/api/") and (request.method, request.url.path) not in PUBLIC_ENDPOINTS
def authenticate(authorization: str | None) -> AuthContext:
"""Bearer-токен -> пользователь. Любая проблема с токеном -> 401 с WWW-Authenticate: Bearer."""
token = security.parse_bearer(authorization)
auth = sessions.authenticate(token) if token else None
if auth is None:
raise Unauthorized("Нужен действующий Bearer-токен сессии")
return auth
@app.middleware("http")
async def request_context(request: Request, call_next):
"""Выполняется вокруг каждого запроса: X-Request-Id, аутентификация, строка лога, перехват ошибок.
Аутентификация стоит здесь, а не в обработчике: она выполняется ДО разбора тела
и поиска чата. Так соблюдается порядок из контракта: сначала «кто ты» (401),
потом «можно ли тебе этот объект» (404) и «правильный ли запрос» (400).
"""
request.state.request_id = uuid.uuid4().hex
started = time.perf_counter()
try:
if needs_bearer(request):
# Проверка токена ходит в Valkey/PostgreSQL (блокирующий код) — выполняем в пуле потоков.
request.state.auth = await run_in_threadpool(authenticate, request.headers.get("Authorization"))
response = await call_next(request)
except AppError as exc: # 401 от аутентификации или 503, если хранилище недоступно
response = error_response(request, exc.status, exc.code, exc.message, exc.headers)
except Exception:
# Подробности (stack trace) — только в лог сервера, клиенту — общий ответ 500.
log.exception("Необработанная ошибка, request_id=%s", request.state.request_id)
response = error_response(request, 500, "internal_error", "Внутренняя ошибка сервера")
response.headers["X-Request-Id"] = request.state.request_id
# В лог не пишем тела, query-параметры и заголовки: там тексты сообщений, пароли и токены.
log.info("%s %s -> %d (%.1f ms) request_id=%s", request.method, request.url.path,
response.status_code, (time.perf_counter() - started) * 1000, request.state.request_id)
return response
@app.exception_handler(AppError)
async def handle_app_error(request: Request, exc: AppError):
return error_response(request, exc.status, exc.code, exc.message, exc.headers)
@app.exception_handler(RequestValidationError)
async def handle_validation_error(request: Request, exc: RequestValidationError):
# FastAPI по умолчанию отвечает 422 со своим форматом; контракт требует 400 и наш формат.
# Детали pydantic клиенту не отдаём: в них может быть эхо входных данных (например, пароль).
first = exc.errors()[0]
if first["type"] == "json_invalid":
message = "Тело запроса не является корректным JSON"
else:
message = "Неверное значение: " + ".".join(str(part) for part in first["loc"])
return error_response(request, 400, "invalid_request", message)
@app.exception_handler(StarletteHTTPException)
async def handle_http_error(request: Request, exc: StarletteHTTPException):
# Ошибки, которые создаёт сам фреймворк: неизвестный путь (404), не тот метод (405) и т.п.
if exc.status_code == 404:
return error_response(request, 404, "not_found", "Ресурс не найден")
return error_response(request, exc.status_code, "invalid_request", "Запрос не может быть обработан")
# ---------- входные данные (схемы из contracts/openapi.json) ----------
def _not_blank(value: str) -> str:
if not value.strip():
raise ValueError("строка состоит только из пробелов")
return value
# Длины в символах Unicode (code points): len("👋") == 1 в Python.
Name = Annotated[str, Field(min_length=1, max_length=100), AfterValidator(_not_blank)]
Text = Annotated[str, Field(min_length=1, max_length=4000), AfterValidator(_not_blank)]
Password = Annotated[str, Field(min_length=security.PASSWORD_MIN, max_length=security.PASSWORD_MAX),
AfterValidator(_not_blank)]
class StrictModel(BaseModel):
model_config = ConfigDict(extra="forbid") # лишние поля в JSON -> 400
class CreateUser(StrictModel):
username: Annotated[str, Field(pattern=r"^[a-z0-9_]{3,32}$")]
display_name: Name
password: Password
class CreateChat(StrictModel):
title: Name
member_ids: Annotated[list[uuid.UUID], Field(min_length=1, max_length=100)]
class CreateMessage(StrictModel):
text: Text # поля sender_id нет: прислать его = лишнее поле = 400
# ---------- текущий пользователь ----------
def current_auth(request: Request) -> AuthContext:
"""Сессия, которую middleware уже проверил для этого запроса."""
auth = getattr(request.state, "auth", None)
if auth is None: # защита от ошибки в PUBLIC_ENDPOINTS: без проверки токена доступа нет
raise Unauthorized("Нужен действующий Bearer-токен сессии")
return auth
def current_user(auth: Annotated[AuthContext, Depends(current_auth)]) -> User:
return auth.user
CurrentAuth = Annotated[AuthContext, Depends(current_auth)]
CurrentUser = Annotated[User, Depends(current_user)]
Limit = Annotated[int, Query(ge=1, le=100)]
Cursor = Annotated[str | None, Query(min_length=1)]
def page_response(scope: str, items: list, has_more: bool) -> dict:
next_cursor = encode_cursor(scope, sort_key(items[-1])) if has_more else None
return {"items": [asdict(item) for item in items], "next_cursor": next_cursor}
# ---------- маршруты ----------
# Обработчики объявлены через def (не async def): FastAPI запускает их в пуле потоков,
# поэтому запросы обрабатываются параллельно. Согласованность данных теперь обеспечивает
# PostgreSQL (транзакции и ограничения), а не замок в памяти процесса.
@app.get("/health/live")
def health_live():
return {"status": "ok"} # процесс жив; от зависимостей не зависит
@app.get("/health/ready")
def health_ready():
# Готовность = можно обслужить обязательный путь. Критична только PostgreSQL:
# без Valkey API работает (медленнее), поэтому его недоступность не делает нас «не готовыми».
store.ping() # если БД недоступна -> Unavailable -> 503 в общем формате ошибки
return {"status": "ok"}
@app.post("/api/v1/users", status_code=201)
def register_user(body: CreateUser):
password_hash = security.hash_password(body.password) # сам пароль нигде не сохраняется
return asdict(store.create_user(body.username, body.display_name, password_hash))
@app.post("/api/v1/auth/sessions", status_code=201)
def create_session(response: Response, authorization: Annotated[str | None, Header()] = None):
credentials = security.parse_basic(authorization)
result = sessions.login(*credentials) if credentials else None
if result is None:
# Один и тот же ответ для «нет такого пользователя», «неверный пароль» и «кривой заголовок».
raise Unauthorized("Неверное имя пользователя или пароль", Unauthorized.BASIC)
token, expires_at, user = result
response.headers["Cache-Control"] = "no-store" # ответ с токеном нельзя кэшировать
return {"token": token, "token_type": "Bearer", "expires_at": expires_at, "user": asdict(user)}
@app.delete("/api/v1/auth/sessions/current", status_code=204)
def revoke_session(auth: CurrentAuth):
sessions.logout(auth)
return Response(status_code=204)
@app.get("/api/v1/users/me")
def get_me(user: CurrentUser):
return asdict(user)
@app.post("/api/v1/chats", status_code=201)
def create_chat(body: CreateChat, user: CurrentUser):
member_ids = [str(member_id) for member_id in body.member_ids]
return asdict(store.create_chat(user.id, body.title, member_ids))
@app.get("/api/v1/chats")
def list_chats(user: CurrentUser, limit: Limit = 50, cursor: Cursor = None):
scope = f"chats:{user.id}"
items, has_more = store.list_chats(user.id, decode_cursor(scope, cursor), limit)
return page_response(scope, items, has_more)
@app.get("/api/v1/chats/{chat_id}")
def get_chat(chat_id: uuid.UUID, user: CurrentUser):
return asdict(store.get_chat(user.id, str(chat_id)))
@app.post("/api/v1/chats/{chat_id}/messages", status_code=201)
def send_message(chat_id: uuid.UUID, body: CreateMessage, user: CurrentUser):
return asdict(store.add_message(user.id, str(chat_id), body.text))
@app.get("/api/v1/chats/{chat_id}/messages")
def list_messages(chat_id: uuid.UUID, user: CurrentUser, limit: Limit = 50, cursor: Cursor = None):
scope = f"messages:{chat_id}"
items, has_more = store.list_messages(user.id, str(chat_id), decode_cursor(scope, cursor), limit)
return page_response(scope, items, has_more)
+85
View File
@@ -0,0 +1,85 @@
"""Настройки из переменных окружения.
Конфигурация не зашита в код и в образ: один и тот же образ запускается
с разными настройками (например, обычный API и API с коротким TTL сессии).
Секреты (адреса БД и Valkey с паролями) передаются не значением переменной,
а путём к файлу: *_FILE=/run/secrets/... Так пароль не виден в `docker inspect`.
"""
import os
from pathlib import Path
def _int(name: str, default: int, minimum: int = 1) -> int:
value = int(os.environ.get(name, str(default)))
if value < minimum:
raise ValueError(f"{name} должен быть не меньше {minimum}")
return value
def _secret(file_var: str, plain_var: str) -> str:
"""Значение секрета: из файла, указанного в *_FILE, иначе из обычной переменной.
strip() убирает перевод строки в конце файла, в том числе \\r из Windows-редакторов:
иначе он попал бы внутрь пароля и подключение к БД не прошло бы.
"""
path = os.environ.get(file_var, "").strip()
if path:
return Path(path).read_text(encoding="utf-8").strip()
return os.environ.get(plain_var, "").strip()
APP_HOST = os.environ.get("APP_HOST", "0.0.0.0") # 0.0.0.0 = слушать на всех интерфейсах контейнера
APP_PORT = _int("APP_PORT", 8080)
APP_ENV = os.environ.get("APP_ENV", "lab")
# Сколько секунд после SIGTERM ждать завершения уже начатых запросов.
# docker stop ждёт 10 секунд, затем убивает процесс через SIGKILL, поэтому берём меньше.
GRACEFUL_SHUTDOWN_SECONDS = 5
# --- сессии ---
SESSION_TTL_SECONDS = _int("SESSION_TTL_SECONDS", 3600)
# Источник истины для сессий. Поддерживается только postgres: Valkey в этой работе — кэш.
SESSION_STORE = os.environ.get("SESSION_STORE", "postgres").strip()
# Сколько секунд запись о сессии может жить в кэше (не дольше самой сессии).
# Это верхняя граница «устаревания»: см. sessions.py и REPORT.md.
SESSION_CACHE_TTL_SECONDS = _int("SESSION_CACHE_TTL_SECONDS", 30)
# --- PostgreSQL ---
DATABASE_URL = _secret("DATABASE_URL_FILE", "DATABASE_URL")
DB_POOL_MIN_SIZE = _int("DB_POOL_MIN_SIZE", 1)
DB_POOL_MAX_SIZE = _int("DB_POOL_MAX_SIZE", 10) # пул ограничен: не больше 10 соединений с БД
DB_POOL_TIMEOUT_SECONDS = _int("DB_POOL_TIMEOUT_SECONDS", 3) # ждать свободное соединение не дольше
DB_CONNECT_TIMEOUT_SECONDS = _int("DB_CONNECT_TIMEOUT_SECONDS", 3)
DB_STATEMENT_TIMEOUT_MS = _int("DB_STATEMENT_TIMEOUT_MS", 5000) # один SQL-запрос не дольше 5 с
DB_STARTUP_WAIT_SECONDS = _int("DB_STARTUP_WAIT_SECONDS", 60) # сколько ждать БД при старте
# --- Valkey (кэш сессий) ---
CACHE_URL = _secret("CACHE_URL_FILE", "CACHE_URL") # пусто = работать без кэша
CACHE_TIMEOUT_MS = _int("CACHE_TIMEOUT_MS", 300) # кэш должен отвечать быстро, иначе обходим его
CACHE_POOL_MAX_SIZE = _int("CACHE_POOL_MAX_SIZE", 20)
CACHE_RETRY_AFTER_SECONDS = _int("CACHE_RETRY_AFTER_SECONDS", 5) # пауза после сбоя кэша
def _migrations_dir() -> Path:
"""Каталог SQL-миграций: в образе /srv/migrations, в репозитории ./migrations."""
explicit = os.environ.get("MIGRATIONS_DIR")
if explicit:
return Path(explicit)
here = Path(__file__).resolve()
for candidate in (here.parents[1] / "migrations", here.parents[2] / "migrations"):
if candidate.is_dir():
return candidate
return here.parents[1] / "migrations"
MIGRATIONS_DIR = _migrations_dir()
def validate() -> None:
"""Проверка при старте: лучше упасть сразу с понятной ошибкой, чем на первом запросе."""
if not DATABASE_URL:
raise RuntimeError("Не задан адрес PostgreSQL: DATABASE_URL_FILE (или DATABASE_URL)")
if SESSION_STORE != "postgres":
raise RuntimeError("SESSION_STORE поддерживает только значение postgres (Valkey здесь — кэш)")
if DB_POOL_MIN_SIZE > DB_POOL_MAX_SIZE:
raise RuntimeError("DB_POOL_MIN_SIZE больше DB_POOL_MAX_SIZE")
+44
View File
@@ -0,0 +1,44 @@
"""Непрозрачный курсор пагинации.
Внутри курсора: «область» (какой именно список листаем) и ключ последнего
элемента страницы (created_at, id). Всё это упаковано в base64, клиент курсор
не разбирает, а просто передаёт обратно. Сервер проверяет, что курсор выдан
для того же списка: курсор от другого чата даёт 400.
С lab2 ключ уходит в SQL-запрос, поэтому перед этим он проверяется:
испорченное время или UUID должны дать 400, а не ошибку базы данных (500).
"""
import base64
import json
import uuid
from datetime import datetime, timezone
from .errors import InvalidRequest
def encode_cursor(scope: str, key: tuple[str, str]) -> str:
raw = json.dumps([scope, *key]).encode()
return base64.urlsafe_b64encode(raw).decode()
def decode_cursor(scope: str, cursor: str | None) -> tuple[datetime, uuid.UUID] | None:
if cursor is None:
return None
try:
data = json.loads(base64.urlsafe_b64decode(cursor.encode("ascii")))
except (ValueError, RecursionError): # не ASCII, не base64, не JSON или слишком глубокая вложенность
raise InvalidRequest("Неверный cursor") from None
well_formed = isinstance(data, list) and len(data) == 3 and all(isinstance(x, str) for x in data)
if not well_formed or data[0] != scope:
raise InvalidRequest("Неверный cursor")
try:
created_at = datetime.fromisoformat(data[1].replace("Z", "+00:00"))
item_id = uuid.UUID(data[2])
if created_at.tzinfo is None:
raise ValueError("время без часового пояса")
# Перевод в UTC может выйти за пределы годов 1–9999 (например, 0001-01-01T00:00+14:00):
# Python бросает OverflowError. Это тоже испорченный курсор -> 400, а не 500.
created_at = created_at.astimezone(timezone.utc)
except (ValueError, OverflowError):
raise InvalidRequest("Неверный cursor") from None
return created_at, item_id
+99
View File
@@ -0,0 +1,99 @@
"""Подключение к PostgreSQL: пул соединений, таймауты и миграции.
Пул — это набор заранее открытых соединений. Запрос берёт соединение из пула,
выполняет SQL и возвращает его обратно. Пул ограничен (DB_POOL_MAX_SIZE), поэтому
даже под нагрузкой API не откроет к базе больше соединений, чем она выдержит.
"""
import logging
import time
import psycopg
from psycopg_pool import ConnectionPool
from . import config
log = logging.getLogger("messenger.db")
# Произвольное постоянное число: «номер замка» для миграций (pg_advisory_lock).
# Если несколько процессов API стартуют одновременно, миграции выполнит только один,
# остальные подождут и увидят, что всё уже применено.
MIGRATION_LOCK_ID = 2026_0002
def connection_kwargs() -> dict:
return {
"connect_timeout": config.DB_CONNECT_TIMEOUT_SECONDS,
"application_name": "messenger-api",
# Таймауты на стороне сервера: зависший запрос или забытая транзакция
# не будут держать соединение и блокировки бесконечно.
"options": (f"-c statement_timeout={config.DB_STATEMENT_TIMEOUT_MS}"
" -c idle_in_transaction_session_timeout=10000"),
}
def create_pool() -> ConnectionPool:
return ConnectionPool(
conninfo=config.DATABASE_URL,
kwargs=connection_kwargs(),
min_size=config.DB_POOL_MIN_SIZE,
max_size=config.DB_POOL_MAX_SIZE,
timeout=config.DB_POOL_TIMEOUT_SECONDS, # сколько ждать свободное соединение из пула
# Перед выдачей соединение проверяется: после рестарта PostgreSQL старые
# соединения «мертвы», и пул заменит их, а не отдаст запросу.
check=ConnectionPool.check_connection,
open=False,
name="messenger",
)
def migrate() -> list[str]:
"""Применяет новые файлы migrations/NNN_*.sql по порядку. Возвращает список применённых.
Каждая миграция и запись о ней выполняются в одной транзакции: либо файл применён
полностью и отмечен, либо ничего не изменилось. Повторный запуск ничего не дублирует.
"""
files = sorted(config.MIGRATIONS_DIR.glob("*.sql"))
if not files:
raise RuntimeError(f"Нет файлов миграций в {config.MIGRATIONS_DIR}")
applied_now = []
# Отдельное соединение без statement_timeout: создание индекса на большой таблице может быть долгим.
with psycopg.connect(config.DATABASE_URL, autocommit=True,
connect_timeout=config.DB_CONNECT_TIMEOUT_SECONDS,
application_name="messenger-migrate") as conn:
conn.execute("SELECT pg_advisory_lock(%s)", (MIGRATION_LOCK_ID,))
try:
conn.execute("""
CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
applied_at timestamptz NOT NULL DEFAULT now()
)""")
done = {row[0] for row in conn.execute("SELECT version FROM schema_migrations")}
for path in files:
if path.stem in done:
continue
with conn.transaction():
# Без параметров psycopg разрешает несколько SQL-команд в одном вызове.
conn.execute(path.read_text(encoding="utf-8"))
conn.execute("INSERT INTO schema_migrations (version) VALUES (%s)", (path.stem,))
applied_now.append(path.stem)
finally:
conn.execute("SELECT pg_advisory_unlock(%s)", (MIGRATION_LOCK_ID,))
return applied_now
def migrate_with_retry() -> None:
"""При старте стенда БД может подниматься дольше API — ждём её, а не падаем сразу."""
deadline = time.monotonic() + config.DB_STARTUP_WAIT_SECONDS
while True:
try:
applied = migrate()
if applied:
log.info("Миграции применены: %s", ", ".join(applied))
else:
log.info("Миграции: новых нет, схема актуальна")
return
except psycopg.OperationalError as exc:
if time.monotonic() > deadline:
raise
log.warning("PostgreSQL пока недоступен (%s), повтор через 1 с", type(exc).__name__)
time.sleep(1)
+43
View File
@@ -0,0 +1,43 @@
"""Ошибки приложения.
Каждый класс знает свой HTTP-статус и код из контракта, поэтому в api.py
достаточно одного обработчика, который превращает любую из них в JSON-ответ.
"""
class AppError(Exception):
status = 500
code = "internal_error"
def __init__(self, message: str, headers: dict[str, str] | None = None):
super().__init__(message)
self.message = message
self.headers = headers or {}
class InvalidRequest(AppError):
status, code = 400, "invalid_request"
class Unauthorized(AppError):
"""401. Контракт требует заголовок WWW-Authenticate: какую схему ждёт сервер."""
status, code = 401, "unauthorized"
BASIC = 'Basic realm="messenger", charset="UTF-8"' # только для POST /auth/sessions
BEARER = 'Bearer realm="messenger"' # для всех остальных защищённых запросов
def __init__(self, message: str, challenge: str = BEARER):
super().__init__(message, {"WWW-Authenticate": challenge})
class NotFound(AppError):
status, code = 404, "not_found"
class Conflict(AppError):
status, code = 409, "conflict"
class Unavailable(AppError):
"""503: нужная зависимость (PostgreSQL) недоступна. Клиент может повторить позже."""
status, code = 503, "unavailable"
+80
View File
@@ -0,0 +1,80 @@
"""Пароли, токены и разбор заголовка Authorization.
Две разные задачи хеширования:
- пароль хешируется МЕДЛЕННОЙ функцией Argon2id с солью: перебор паролей по украденной
базе стоит дорого (каждая попытка — десятки миллисекунд и 19 МиБ памяти);
- токен сессии хешируется БЫСТРЫМ SHA-256: токен — 256 случайных бит, перебирать
его бессмысленно, а проверять его нужно на каждом запросе.
"""
import base64
import binascii
import hashlib
import re
import secrets
from argon2 import PasswordHasher
from argon2.exceptions import InvalidHashError, VerificationError
# Параметры Argon2id — минимальные из рекомендаций OWASP: m=19 МиБ, t=2, p=1.
# Больше памяти — дороже перебор, но и каждый вход дороже для сервера.
_hasher = PasswordHasher(time_cost=2, memory_cost=19 * 1024, parallelism=1)
# Hash заведомо неверного пароля. Если пользователя нет, всё равно выполняем проверку:
# ответ занимает столько же времени, и по задержке нельзя узнать, существует ли username.
_DUMMY_HASH = _hasher.hash("timing-equalizer-not-a-password")
TOKEN_BYTES = 32 # 32 байта = 256 бит энтропии (требование контракта)
PASSWORD_MIN, PASSWORD_MAX = 12, 128
USERNAME_RE = re.compile(r"[a-z0-9_]{3,32}") # то же правило, что при регистрации
MAX_BASIC_HEADER = 1024 # длинный заголовок не проверяем: не тратим CPU на заведомый мусор
def hash_password(password: str) -> str:
return _hasher.hash(password) # строка вида $argon2id$v=19$m=19456,t=2,p=1$<соль>$<hash>
def verify_password(password_hash: str | None, password: str) -> bool:
try:
return _hasher.verify(password_hash or _DUMMY_HASH, password) and password_hash is not None
except (VerificationError, InvalidHashError):
return False
def new_token() -> str:
"""Непрозрачный случайный токен: не username, не UUID и не JWT."""
return secrets.token_urlsafe(TOKEN_BYTES)
def token_hash(token: str) -> bytes:
"""В БД и в кэше хранится только SHA-256 токена — сам токен знает лишь клиент."""
return hashlib.sha256(token.encode("utf-8")).digest()
def _split_scheme(header: str | None) -> tuple[str, str]:
scheme, _, value = (header or "").strip().partition(" ")
return scheme.lower(), value.strip()
def parse_basic(header: str | None) -> tuple[str, str] | None:
"""Authorization: Basic base64(username:password) -> (username, password) или None.
Пароль в UTF-8 и может содержать двоеточие: делим по ПЕРВОМУ двоеточию (RFC 7617).
"""
scheme, value = _split_scheme(header)
if scheme != "basic" or not value or len(value) > MAX_BASIC_HEADER:
return None
try:
decoded = base64.b64decode(value, validate=True).decode("utf-8")
except (binascii.Error, ValueError):
return None
username, sep, password = decoded.partition(":")
if not sep or not username.isascii():
return None
return username, password
def parse_bearer(header: str | None) -> str | None:
scheme, value = _split_scheme(header)
if scheme != "bearer" or not value or len(value) > 512 or " " in value:
return None
return value
+190
View File
@@ -0,0 +1,190 @@
"""Сессии: вход (Basic -> токен), проверка Bearer-токена, выход.
Где что хранится:
- ИСТОЧНИК ИСТИНЫ — таблица sessions в PostgreSQL. Она переживает рестарт и решает,
действует ли сессия (не отозвана и не истекла).
- Valkey — КЭШ «hash токена -> пользователь». Он избавляет от SQL-запроса на каждом
обращении с токеном. Кэш можно в любой момент очистить или потерять: при промахе
данные берутся из PostgreSQL и снова кладутся в кэш.
Политика кэша:
- запись живёт min(SESSION_CACHE_TTL_SECONDS, остаток жизни сессии): кэш никогда
не продлевает сессию, а истёкшая запись к тому же отбрасывается по expires_at;
- logout: сначала отметка revoked_at в PostgreSQL, затем в кэш вместо записи о сессии
кладётся отметка «отозвано» (tombstone). Новая запись о сессии кладётся только если ключа
нет (SET NX), поэтому запрос, который прочитал сессию из базы до logout, не сможет
«воскресить» её в кэше после logout;
- поколение кэша: каждая запись о сессии помечена поколением процесса. При любом сбое
Valkey процесс начинает новое поколение и больше не доверяет записям старого. Пока Valkey
был недоступен, logout не мог убрать запись из кэша; после возвращения Valkey эта старая
запись всё ещё лежит там, но она старого поколения, поэтому проверка идёт в PostgreSQL,
а там сессия отозвана -> 401. Отметки «отозвано» действуют в любом поколении: они только
запрещают, а не разрешают;
- если Valkey недоступен, его обходят: всё работает напрямую через PostgreSQL.
После первого сбоя запросы вообще перестают обращаться к кэшу, а фоновый поток раз в
CACHE_RETRY_AFTER_SECONDS проверяет (PING), вернулся ли Valkey. Так ожидание подключения
(в Docker это ещё и поиск DNS-имени остановленного контейнера, до нескольких секунд)
достаётся фоновому потоку, а не запросам пользователей.
"""
import json
import logging
import secrets
import threading
import time
from dataclasses import asdict, dataclass
from datetime import datetime, timedelta, timezone
import valkey
from . import config, security
from .store import PostgresStore, User, ts
log = logging.getLogger("messenger.sessions")
@dataclass(frozen=True)
class AuthContext:
"""Результат успешной проверки токена: кто пришёл и какой сессией (нужно для logout)."""
user: User
token_hash: bytes
class SessionCache:
PREFIX = "sess:" # пользователю Valkey разрешены только ключи sess:* (ACL: secrets/valkey_users.acl)
def __init__(self, url: str):
self._client = None
self._down = False # True = кэш считается недоступным, запросы его не трогают
self._lock = threading.Lock()
# Поколение: случайное при старте процесса и новое после каждого сбоя Valkey.
self.generation = secrets.token_hex(8)
if url:
timeout = config.CACHE_TIMEOUT_MS / 1000
pool = valkey.BlockingConnectionPool.from_url(
url,
max_connections=config.CACHE_POOL_MAX_SIZE, # ограниченный пул соединений
timeout=timeout, # сколько ждать свободное соединение
socket_timeout=timeout, # сколько ждать ответ
socket_connect_timeout=timeout, # сколько ждать подключение
lib_name=None, lib_version=None,
)
self._client = valkey.Valkey(connection_pool=pool)
@property
def enabled(self) -> bool:
return self._client is not None
def _available(self) -> bool:
return self._client is not None and not self._down
def _failed(self, operation: str, exc: Exception) -> None:
with self._lock:
# Новое поколение при КАЖДОЙ ошибке: всё, что лежит в кэше сейчас, больше не доверенное.
self.generation = secrets.token_hex(8)
if self._down: # уже знаем о сбое, фоновая проверка уже запущена
return
self._down = True
log.warning("Valkey недоступен (%s при %s): работаем напрямую с PostgreSQL",
type(exc).__name__, operation)
threading.Thread(target=self._probe_until_back, name="valkey-probe", daemon=True).start()
def _probe_until_back(self) -> None:
"""Фоновый поток: ждёт возвращения Valkey и снова включает кэш."""
while True:
time.sleep(config.CACHE_RETRY_AFTER_SECONDS)
if self.ping():
with self._lock:
self._down = False
log.info("Valkey снова доступен: кэш сессий включён (записи до сбоя не используются)")
return
def get(self, key: bytes) -> dict | None:
if not self._available():
return None
try:
raw = self._client.get(self.PREFIX + key.hex())
except valkey.ValkeyError as exc:
self._failed("get", exc)
return None
return None if raw is None else json.loads(raw)
def add(self, key: bytes, value: dict, ttl_ms: int) -> None:
"""Положить запись, только если ключа ещё нет (SET NX): отметку «отозвано» не затираем."""
if not self._available() or ttl_ms < 100:
return
try:
self._client.set(self.PREFIX + key.hex(), json.dumps(value), px=ttl_ms, nx=True)
except valkey.ValkeyError as exc:
self._failed("set", exc)
def mark_revoked(self, key: bytes) -> None:
"""Заменить запись о сессии отметкой «отозвано» на SESSION_CACHE_TTL_SECONDS."""
if not self._available():
return # запись в кэше осталась, но после сбоя она старого поколения и не доверенная
try:
self._client.set(self.PREFIX + key.hex(), json.dumps({"revoked": True}),
px=config.SESSION_CACHE_TTL_SECONDS * 1000)
except valkey.ValkeyError as exc:
self._failed("set", exc)
def ping(self) -> bool:
try:
return bool(self._client and self._client.ping())
except valkey.ValkeyError:
return False
class Sessions:
def __init__(self, store: PostgresStore, cache: SessionCache, ttl_seconds: int):
self.store = store
self.cache = cache
self.ttl_seconds = ttl_seconds
def login(self, username: str, password: str) -> tuple[str, str, User] | None:
"""Проверяет пароль и создаёт сессию. None — неверные credentials (без уточнений)."""
if not security.PASSWORD_MIN <= len(password) <= security.PASSWORD_MAX:
return None
if not security.USERNAME_RE.fullmatch(username):
return None # такого username не может существовать — в базу даже не ходим
found = self.store.get_credentials(username)
user, password_hash = found if found else (None, None)
# Проверка выполняется и для несуществующего пользователя (с фиктивным hash):
# одинаковое время ответа и одинаковый 401 не раскрывают, есть ли такой username.
if not security.verify_password(password_hash, password) or user is None:
return None
token = security.new_token()
key = security.token_hash(token)
generation = self.cache.generation
expires_at = self.store.create_session(key, user.id, self.ttl_seconds)
self._remember(key, user, expires_at, generation) # следующий запрос сразу попадёт в кэш
return token, ts(expires_at), user
def authenticate(self, token: str) -> AuthContext | None:
key = security.token_hash(token)
# Поколение запоминаем ДО чтения: если во время запроса случится сбой Valkey,
# то, что мы положим в кэш, окажется старого поколения и доверенным не будет.
generation = self.cache.generation
cached = self.cache.get(key)
if cached is not None:
if cached.get("revoked"):
return None # logout уже был
expires_at = datetime.fromisoformat(cached["expires_at"])
if cached.get("gen") == generation and expires_at > datetime.now(timezone.utc):
return AuthContext(User(**cached["user"]), key)
# запись старого поколения или истёкшая -> проверяем по источнику истины
found = self.store.get_session(key) # промах кэша, недоверенная запись или кэш недоступен
if found is None:
return None
user, expires_at = found
self._remember(key, user, expires_at, generation)
return AuthContext(user, key)
def logout(self, auth: AuthContext) -> None:
self.store.revoke_session(auth.token_hash) # сначала источник истины
self.cache.mark_revoked(auth.token_hash) # затем инвалидация кэша
def _remember(self, key: bytes, user: User, expires_at: datetime, generation: str) -> None:
left = expires_at - datetime.now(timezone.utc)
ttl = min(timedelta(seconds=config.SESSION_CACHE_TTL_SECONDS), left)
self.cache.add(key, {"user": asdict(user), "expires_at": expires_at.isoformat(), "gen": generation},
int(ttl.total_seconds() * 1000))
+270
View File
@@ -0,0 +1,270 @@
"""Хранилище на PostgreSQL.
С lab2 источник истины — база данных, а не память процесса. Методы и их смысл
те же, что у InMemoryStore из lab1, поэтому api.py почти не изменился.
Модуль по-прежнему ничего не знает про HTTP: он хранит данные и соблюдает правила.
Все SQL-запросы параметризованные: значения передаются отдельно от текста запроса
(%s), поэтому ввод пользователя никогда не становится частью SQL (нет SQL-инъекций).
"""
import logging
import uuid
from contextlib import contextmanager
from dataclasses import dataclass
from datetime import datetime, timezone
import psycopg
from psycopg import errors as pg_errors
from psycopg_pool import ConnectionPool, PoolTimeout
from .errors import Conflict, InvalidRequest, NotFound, Unavailable
log = logging.getLogger("messenger.store")
@dataclass(frozen=True)
class User:
id: str
username: str
display_name: str
created_at: str
@dataclass(frozen=True)
class Chat:
id: str
title: str
member_ids: tuple[str, ...]
created_at: str
@dataclass(frozen=True)
class Message:
id: str
chat_id: str
sender_id: str
text: str
created_at: str
def sort_key(item) -> tuple[str, str]:
"""Порядок по контракту: (created_at, id) по возрастанию. Из этой пары строится курсор."""
return item.created_at, item.id
def ts(value: datetime) -> str:
"""Время из БД -> строка RFC 3339 в UTC с Z и микросекундами (как в lab1)."""
return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
# Свободный текст (display_name, title, text) хранится в БД как байты UTF-8 (bytea), а не text:
# тип text в PostgreSQL не может содержать символ U+0000, а контракт его не запрещает.
# См. migrations/003_text_as_bytes.sql. Перед записью кодируем, после чтения декодируем.
def to_db(value: str) -> bytes:
return value.encode("utf-8")
def from_db(value) -> str:
return bytes(value).decode("utf-8")
def _user(row) -> User:
return User(str(row[0]), row[1], from_db(row[2]), ts(row[3]))
def _chat(row) -> Chat:
return Chat(str(row[0]), from_db(row[1]), tuple(str(m) for m in row[3]), ts(row[2]))
def _message(row) -> Message:
return Message(str(row[0]), str(row[1]), str(row[2]), from_db(row[3]), ts(row[4]))
# Участники чата всегда в одном порядке (по UUID), чтобы POST и GET отвечали одинаково.
_CHAT_COLUMNS = """c.id, c.title, c.created_at,
ARRAY(SELECT cm.user_id FROM chat_members cm WHERE cm.chat_id = c.id ORDER BY cm.user_id)"""
class PostgresStore:
def __init__(self, pool: ConnectionPool):
self.pool = pool
@contextmanager
def _conn(self, timeout: float | None = None):
"""Соединение из пула. В конце блока — COMMIT, при исключении — ROLLBACK.
Если база недоступна (нет соединения, истёк таймаут пула или запроса),
клиент получает 503 без подробностей, а не 500 со stack trace.
"""
try:
with self.pool.connection(timeout=timeout) as conn:
yield conn
except (psycopg.OperationalError, PoolTimeout) as exc:
log.warning("PostgreSQL недоступен: %s", type(exc).__name__)
raise Unavailable("Хранилище временно недоступно") from None
except psycopg.DataError as exc:
# База отвергла само значение (например, недопустимый символ): это ошибка входа -> 400,
# а не внутренняя ошибка сервера (500).
log.warning("PostgreSQL отверг значение: %s", type(exc).__name__)
raise InvalidRequest("Недопустимое значение в запросе") from None
def ping(self, timeout: float = 1.0) -> None:
"""Проверка готовности: короткий таймаут, чтобы healthcheck (3 с) успел получить 503."""
with self._conn(timeout) as conn:
conn.execute("SELECT 1")
# --- пользователи ---
def create_user(self, username: str, display_name: str, password_hash: str) -> User:
try:
with self._conn() as conn:
row = conn.execute(
"""INSERT INTO users (id, username, display_name, password_hash)
VALUES (%s, %s, %s, %s)
RETURNING id, username, display_name, created_at""",
(uuid.uuid4(), username, to_db(display_name), password_hash)).fetchone()
except pg_errors.UniqueViolation:
# Не «проверить, потом вставить» (между этими шагами успеет вклиниться другой запрос),
# а сразу вставить: уникальный индекс в БД пропустит ровно одну регистрацию.
raise Conflict("Имя пользователя уже занято") from None
return _user(row)
def get_credentials(self, username: str) -> tuple[User, str] | None:
"""Пользователь и hash его пароля — только для проверки при входе."""
with self._conn() as conn:
row = conn.execute(
"""SELECT id, username, display_name, created_at, password_hash
FROM users WHERE username = %s""", (username,)).fetchone()
return None if row is None else (_user(row), row[4])
# --- чаты ---
def create_chat(self, creator_id: str, title: str, member_ids: list[str]) -> Chat:
if len(set(member_ids)) != len(member_ids):
raise InvalidRequest("Участники чата повторяются")
if creator_id not in member_ids:
raise InvalidRequest("Создатель чата должен входить в member_ids")
members = sorted(uuid.UUID(m) for m in member_ids)
chat_id = uuid.uuid4()
try:
with self._conn() as conn:
# Одна транзакция: чат и все участники записываются вместе или не записываются вовсе.
with conn.transaction():
self._check_members_exist(conn, members)
created_at = conn.execute(
"INSERT INTO chats (id, title) VALUES (%s, %s) RETURNING created_at",
(chat_id, to_db(title))).fetchone()[0]
with conn.cursor() as cur:
cur.executemany("INSERT INTO chat_members (chat_id, user_id) VALUES (%s, %s)",
[(chat_id, m) for m in members])
except pg_errors.ForeignKeyViolation:
# Сюда попадаем, только если проверка выше пропустила несуществующего участника.
# Транзакция уже откатилась: строки чата в базе не осталось.
raise InvalidRequest("Среди участников есть несуществующий пользователь") from None
return Chat(str(chat_id), title, tuple(str(m) for m in members), ts(created_at))
@staticmethod
def _check_members_exist(conn, members: list[uuid.UUID]) -> None:
found = conn.execute("SELECT count(*) FROM users WHERE id = ANY(%s)", (members,)).fetchone()[0]
if found != len(members):
raise InvalidRequest("Среди участников есть несуществующий пользователь")
def get_chat(self, user_id: str, chat_id: str) -> Chat:
with self._conn() as conn:
row = conn.execute(
f"""SELECT {_CHAT_COLUMNS} FROM chats c
WHERE c.id = %s AND EXISTS (
SELECT 1 FROM chat_members cm WHERE cm.chat_id = c.id AND cm.user_id = %s)""",
(uuid.UUID(chat_id), uuid.UUID(user_id))).fetchone()
if row is None:
# Один и тот же ответ для «чата нет» и «чат чужой»:
# посторонний не должен узнать, что такой чат существует.
raise NotFound("Чат не найден")
return _chat(row)
def list_chats(self, user_id: str, after: tuple[datetime, uuid.UUID] | None, limit: int):
query = f"""SELECT {_CHAT_COLUMNS}
FROM chat_members me JOIN chats c ON c.id = me.chat_id
WHERE me.user_id = %s {{after}}
ORDER BY c.created_at, c.id
LIMIT %s"""
params: list = [uuid.UUID(user_id)]
if after is None:
query = query.format(after="")
else:
query = query.format(after="AND (c.created_at, c.id) > (%s, %s)")
params += [after[0], after[1]]
with self._conn() as conn:
rows = conn.execute(query, (*params, limit + 1)).fetchall()
return [_chat(r) for r in rows[:limit]], len(rows) > limit
# --- сообщения ---
def add_message(self, user_id: str, chat_id: str, text: str) -> Message:
with self._conn() as conn:
# Один SQL-оператор: вставка произойдёт, только если отправитель — участник чата.
# Отправитель берётся из сессии, а не из тела запроса.
row = conn.execute(
"""INSERT INTO messages (id, chat_id, sender_id, text)
SELECT %s, cm.chat_id, cm.user_id, %s
FROM chat_members cm WHERE cm.chat_id = %s AND cm.user_id = %s
RETURNING id, chat_id, sender_id, text, created_at""",
(uuid.uuid4(), to_db(text), uuid.UUID(chat_id), uuid.UUID(user_id))).fetchone()
if row is None:
raise NotFound("Чат не найден")
return _message(row)
def list_messages(self, user_id: str, chat_id: str,
after: tuple[datetime, uuid.UUID] | None, limit: int):
chat, user = uuid.UUID(chat_id), uuid.UUID(user_id)
# Keyset-пагинация: «следующие limit записей после ключа», а не OFFSET.
# С индексом (chat_id, created_at, id) база сразу встаёт на нужное место индекса
# и читает только limit+1 строк, сколько бы сообщений ни было в чате.
if after is None:
query = """SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = %s
ORDER BY created_at, id LIMIT %s"""
params = (chat, limit + 1)
else:
query = """SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = %s AND (created_at, id) > (%s, %s)
ORDER BY created_at, id LIMIT %s"""
params = (chat, after[0], after[1], limit + 1)
with self._conn() as conn:
member = conn.execute("SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s",
(chat, user)).fetchone()
if member is None:
raise NotFound("Чат не найден")
rows = conn.execute(query, params).fetchall()
return [_message(r) for r in rows[:limit]], len(rows) > limit
# --- сессии (источник истины; Valkey — только кэш, см. sessions.py) ---
def create_session(self, token_hash: bytes, user_id: str, ttl_seconds: int) -> datetime:
with self._conn() as conn, conn.transaction():
# Заодно убираем у этого пользователя истёкшие и отозванные сессии: они уже не нужны.
conn.execute("""DELETE FROM sessions
WHERE user_id = %s AND (expires_at <= now() OR revoked_at IS NOT NULL)""",
(uuid.UUID(user_id),))
# Срок жизни считает часами PostgreSQL — теми же, по которым он потом проверяется.
return conn.execute(
"""INSERT INTO sessions (token_hash, user_id, expires_at)
VALUES (%s, %s, now() + make_interval(secs => %s))
RETURNING expires_at""",
(token_hash, uuid.UUID(user_id), ttl_seconds)).fetchone()[0]
def get_session(self, token_hash: bytes) -> tuple[User, datetime] | None:
"""Пользователь действующей сессии: не отозвана и не истекла. Иначе None."""
with self._conn() as conn:
row = conn.execute(
"""SELECT u.id, u.username, u.display_name, u.created_at, s.expires_at
FROM sessions s JOIN users u ON u.id = s.user_id
WHERE s.token_hash = %s AND s.revoked_at IS NULL AND s.expires_at > now()""",
(token_hash,)).fetchone()
return None if row is None else (_user(row), row[4])
def revoke_session(self, token_hash: bytes) -> bool:
with self._conn() as conn:
cur = conn.execute("UPDATE sessions SET revoked_at = now() "
"WHERE token_hash = %s AND revoked_at IS NULL", (token_hash,))
return cur.rowcount == 1
+51
View File
@@ -0,0 +1,51 @@
"""Отозванный токен не «воскресает» из кэша после возвращения Valkey (замечание к MR).
Запуск: make failure-valkey-pause
Сценарий преподавателя: Valkey ставится на паузу (docker compose pause) — процесс жив,
данные в его памяти сохраняются, но он не отвечает. В это время делается logout: PostgreSQL
отзывает сессию, а убрать запись из кэша нельзя. После unpause в кэше всё ещё лежит старая
запись «токен -> пользователь». Она не должна снова пропускать этот токен.
"""
import time
from helpers import Client, check, compose, run, wait_ready
def main():
api = Client()
alice, bob, _eve, chat = api.bootstrap()
dave = api.user("dave")
for _ in range(2): # запись о сессии dave точно лежит в кэше
api.call("GET", "/api/v1/users/me", actor=dave, schema="User")
print("pausing valkey (docker compose pause valkey): данные в кэше сохраняются")
compose("pause", "valkey")
try:
api.call("GET", "/api/v1/users/me", actor=dave, schema="User") # этот запрос обнаруживает сбой кэша
api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=dave)
api.call("GET", "/api/v1/users/me", 401, actor=dave)
print("во время паузы: logout -> 204, тот же токен -> 401")
finally:
print("unpausing valkey")
compose("unpause", "valkey")
wait_ready(api)
# Фоновая проверка возвращает кэш в работу в течение 5 с. Смотрим 12 с — дольше, чем она.
deadline = time.monotonic() + 12
checks = 0
while time.monotonic() < deadline:
api.call("GET", "/api/v1/users/me", 401, actor=dave)
api.call("POST", "/api/v1/chats", 401, actor=dave, body={"title": "x", "member_ids": [dave["id"]]})
checks += 1
time.sleep(0.5)
print(f"после unpause: {checks} проверок за 12 с, отозванный токен всегда 401 (и GET, и POST)")
api.call("GET", "/api/v1/users/me", actor=alice, schema="User")
api.message(bob, chat, "после возвращения Valkey")
print("действующие токены других пользователей работают")
print("PASS: revoked session stays revoked after Valkey comes back with stale data")
if __name__ == "__main__":
run(main)
+99
View File
@@ -0,0 +1,99 @@
"""Интеграционные тесты хранилища на настоящей PostgreSQL (уровень 4).
Выполняются ВНУТРИ контейнера приложения (там есть psycopg и доступ к БД по сети стенда):
make db-test == docker compose --profile tools run --rm db-test
Что проверяется:
- повторный запуск миграций ничего не меняет;
- составная операция «создать чат» откатывается целиком, если упала на середине;
- одновременная регистрация одного username даёт ровно одного пользователя;
- сама база не даёт записать сообщение от не-участника (внешний ключ).
"""
import threading
import unittest
import uuid
from unittest import mock
import psycopg
from psycopg import errors as pg_errors
from messenger import config, db
from messenger.errors import Conflict, InvalidRequest
from messenger.store import PostgresStore
class StoreIntegrationTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
config.validate()
db.migrate()
cls.pool = db.create_pool()
cls.pool.open(wait=True)
cls.store = PostgresStore(cls.pool)
@classmethod
def tearDownClass(cls):
cls.pool.close()
def scalar(self, sql, *params):
with self.pool.connection() as conn:
return conn.execute(sql, params).fetchone()[0]
def new_user(self):
return self.store.create_user("db_" + uuid.uuid4().hex[:12], "DB test", "not-a-real-hash")
def test_migrations_rerun_is_noop(self):
versions = self.scalar("SELECT array_agg(version ORDER BY version) FROM schema_migrations")
users = self.scalar("SELECT count(*) FROM users")
self.assertEqual(db.migrate(), []) # второй прогон: применять нечего
self.assertEqual(self.scalar("SELECT array_agg(version ORDER BY version) FROM schema_migrations"), versions)
self.assertEqual(self.scalar("SELECT count(*) FROM users"), users)
print(f"\n schema_migrations: {versions}; повторный migrate() ничего не применил")
def test_create_chat_rolls_back_when_failing_midway(self):
alice = self.new_user()
ghost = str(uuid.uuid4()) # такого пользователя нет
title = "rollback-" + uuid.uuid4().hex[:8]
# Отключаем предварительную проверку участников, чтобы ошибка случилась ВНУТРИ транзакции:
# строка чата уже вставлена, а вставка участника-призрака нарушает внешний ключ.
with mock.patch.object(PostgresStore, "_check_members_exist", staticmethod(lambda conn, members: None)):
with self.assertRaises(InvalidRequest):
self.store.create_chat(alice.id, title, [alice.id, ghost])
self.assertEqual(self.scalar("SELECT count(*) FROM chats WHERE title = %s", title), 0)
self.assertEqual(self.scalar("SELECT count(*) FROM chat_members WHERE user_id = %s", uuid.UUID(alice.id)), 0)
print("\n чат с несуществующим участником: транзакция откатилась, строк chats/chat_members не осталось")
def test_concurrent_registration_has_one_winner(self):
username = "dbrace_" + uuid.uuid4().hex[:10]
threads, barrier, results = 20, threading.Barrier(20), []
def register():
barrier.wait()
try:
self.store.create_user(username, "Race", "not-a-real-hash")
results.append("created")
except Conflict:
results.append("conflict")
workers = [threading.Thread(target=register) for _ in range(threads)]
for w in workers:
w.start()
for w in workers:
w.join()
self.assertEqual(results.count("created"), 1)
self.assertEqual(results.count("conflict"), threads - 1)
self.assertEqual(self.scalar("SELECT count(*) FROM users WHERE username = %s", username), 1)
print(f"\n {threads} параллельных create_user: 1 создан, {threads - 1} получили Conflict (409)")
def test_database_rejects_message_from_non_member(self):
alice, mallory = self.new_user(), self.new_user()
chat = self.store.create_chat(alice.id, "fk", [alice.id])
with self.assertRaises(pg_errors.ForeignKeyViolation):
with psycopg.connect(config.DATABASE_URL) as conn:
conn.execute("INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s, %s, %s, 'x')",
(uuid.uuid4(), uuid.UUID(chat.id), uuid.UUID(mallory.id)))
print("\n INSERT сообщения от не-участника напрямую в БД: ForeignKeyViolation")
if __name__ == "__main__":
unittest.main()
+33
View File
@@ -0,0 +1,33 @@
"""Демонстрация для защиты (шаг 1 сценария): пользователи, вход, чат, сообщения, logout.
Запуск: make demo (печатает шаги; пароли и токены не выводятся)
"""
from helpers import Client, read_history, run
def main():
api = Client()
api.call("GET", "/health/ready", schema="Health")
print("1. /health/ready -> 200: API запущен, PostgreSQL доступна, миграции применены")
alice, bob, eve, chat = api.bootstrap() # регистрация с паролем + вход через Basic у каждого
for name, actor in (("alice", alice), ("bob", bob), ("eve", eve)):
print(f"2. зарегистрирован {name}: {actor['user']['username']}, вход через Basic -> Bearer-токен")
print(f"3. alice создала чат {chat['id']} с bob (eve не участник)")
api.message(alice, chat, "Привет, Боб! Это сообщение лежит в PostgreSQL")
api.message(bob, chat, "Привет, Алиса! Переживёт перезапуск")
history, pages = read_history(api, bob, chat["id"], limit=1)
print(f"4. история чата (по 1 сообщению на страницу, страниц: {pages}):")
names = {alice["id"]: "alice", bob["id"]: "bob"}
for m in history:
print(f" {m['created_at']} {names[m['sender_id']]}: {m['text']}")
api.call("GET", f"/api/v1/chats/{chat['id']}/messages", 404, actor=eve)
print("5. eve читает чужой чат -> 404 (существование чата не раскрывается)")
api.call("GET", "/api/v1/users/me", 401, headers={"X-User-Id": alice["id"]})
print("6. только X-User-Id без токена -> 401 (lab1-способ больше не работает)")
api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=alice)
api.call("GET", "/api/v1/users/me", 401, actor=alice)
print("7. alice logout -> 204, тот же токен -> 401")
if __name__ == "__main__":
run(main)
+100
View File
@@ -0,0 +1,100 @@
"""Отказ зависимости (уровень 4). Запуск: make failure-valkey или make failure-postgres
Тест сам останавливает указанный контейнер (docker compose stop), проверяет поведение API
и запускает контейнер обратно (docker compose start). Volumes не трогаются.
valkey — кэш недоступен: API обходит его и работает через PostgreSQL; logout действует сразу.
postgres — источник истины недоступен: API отвечает ограниченной ошибкой 503 (без деталей),
/health/ready = 503, аноним и неизвестный токен НЕ получают успешный ответ.
После запуска БД прежний токен и данные снова доступны.
"""
import sys
import time
import uuid
from helpers import Client, basic, check, compose, read_history, run, wait_ready
def timed(fn):
started = time.monotonic()
result = fn()
return result, (time.monotonic() - started) * 1000
def valkey_down(api, alice, bob, chat):
ready, ms = timed(lambda: api.call("GET", "/health/ready", schema="Health"))
print(f"/health/ready -> 200 ({ms:.0f} ms): Valkey не критичен, API готов")
_, ms = timed(lambda: api.call("GET", "/api/v1/users/me", actor=alice, schema="User"))
print(f"existing token: GET /users/me -> 200 ({ms:.0f} ms), сессия проверена по PostgreSQL (этот запрос и обнаружил сбой кэша)")
sent = api.message(bob, chat, "во время отказа Valkey")["json"]
history, _ = read_history(api, alice, chat["id"])
check(sent["id"] in [m["id"] for m in history], "message written during Valkey outage is missing")
print("POST message -> 201, история читается")
carol = api.user("carol") # регистрация и вход тоже работают без кэша
print("register + login new user -> 201")
api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=carol)
api.call("GET", "/api/v1/users/me", 401, actor=carol)
print("logout -> 204, затем тот же токен -> 401 (отзыв записан в PostgreSQL)")
latencies = [timed(lambda: api.call("GET", "/api/v1/users/me", actor=alice))[1] for _ in range(10)]
print(f"10 x GET /users/me без кэша: max {max(latencies):.0f} ms (кэш не ждём на каждом запросе)")
check(max(latencies) < 1000, "requests must not wait for the dead cache on every call")
# Фоновая проверка Valkey идёт раз в 5 с. Ждём дольше и убеждаемся, что запросы её не ждут.
time.sleep(6)
latencies = [timed(lambda: api.call("GET", "/api/v1/users/me", actor=alice))[1] for _ in range(10)]
print(f"через 6 с, ещё 10 x GET /users/me: max {max(latencies):.0f} ms (повторные попытки — в фоне)")
check(max(latencies) < 1000, "periodic reconnect attempts must not block user requests")
return carol
def postgres_down(api, alice, chat):
api.call("GET", "/health/live", schema="Health")
print("/health/live -> 200: процесс жив")
_, ms = timed(lambda: api.call("GET", "/health/ready", 503))
print(f"/health/ready -> 503 ({ms:.0f} ms): без PostgreSQL обслуживать нельзя")
for method, path in (("GET", "/api/v1/chats"), ("GET", f"/api/v1/chats/{chat['id']}/messages")):
error = api.call(method, path, 503, actor=alice)["json"]["error"]
check(error["code"] == "unavailable", "expected unavailable error code")
api.call("POST", f"/api/v1/chats/{chat['id']}/messages", 503, actor=alice, body={"text": "не сохранится"})
print("бизнес-запросы с действующим токеном -> 503 unavailable (без SQL и stack trace в ответе)")
api.call("GET", "/api/v1/users/me", 401)
print("без токена -> 401: аноним не становится доверенным")
status = api.call("GET", "/api/v1/users/me", [401, 503], headers={"Authorization": "Bearer " + "x" * 43})["status"]
print(f"неизвестный токен -> {status}: не подтверждается ни кэшем, ни базой")
status = api.call("POST", "/api/v1/auth/sessions", [401, 503],
headers={"Authorization": basic("nobody", "Some-password-1")})["status"]
print(f"вход -> {status}: сессию без базы не выдаём")
api.call("POST", "/api/v1/users", 503,
body={"username": "pg_" + uuid.uuid4().hex[:10], "display_name": "x", "password": "Pg-down-password"})
print("регистрация -> 503")
def main():
target = sys.argv[1] if len(sys.argv) > 1 else ""
check(target in ("valkey", "postgres"), "usage: dependency_failure.py valkey|postgres")
api = Client()
alice, bob, _eve, chat = api.bootstrap()
before = api.message(alice, chat, "до отказа " + target)["json"]
print(f"stopping {target} (docker compose stop {target})")
compose("stop", target)
try:
if target == "valkey":
carol = valkey_down(api, alice, bob, chat)
else:
postgres_down(api, alice, chat)
finally:
print(f"starting {target} again")
compose("start", target)
wait_ready(api)
history, _ = read_history(api, alice, chat["id"])
check(before in history, "message confirmed before the outage is lost or changed")
api.call("GET", "/api/v1/users/me", actor=alice, schema="User")
if target == "valkey":
api.call("GET", "/api/v1/users/me", 401, actor=carol) # отозванный токен не «воскрес» из кэша
print("after recovery: прежний токен работает, подтверждённые сообщения на месте")
print(f"PASS: {target} outage handled without trusting anonymous requests")
if __name__ == "__main__":
run(main)
+42
View File
@@ -0,0 +1,42 @@
"""Проверка истечения сессии при коротком TTL (уровень 4). Запуск: make expiry
Нужен второй экземпляр API с SESSION_TTL_SECONDS=2 (сервис api-short-ttl на порту 8081,
make expiry поднимает его сам). База общая с основным API.
Сценарий: вход -> токен работает (и попадает в кэш Valkey) -> ждём истечения ->
токен отклоняется с 401 и на коротком, и на основном API. Значит, срок жизни — свойство
сессии в PostgreSQL, а кэш не продлевает её.
"""
import datetime as dt
import os
import time
import uuid
from helpers import Client, check, login, run
def main():
short = Client(os.environ.get("BASE_URL_TTL", "http://127.0.0.1:8081"))
main_api = Client()
body = {"username": "ttl_" + uuid.uuid4().hex[:12], "display_name": "TTL", "password": "Ttl-password-123"}
short.call("POST", "/api/v1/users", 201, body=body, schema="User")
session = login(short, body["username"], body["password"])
auth = {"Authorization": "Bearer " + session["token"]}
expires_at = dt.datetime.fromisoformat(session["expires_at"].replace("Z", "+00:00"))
ttl = (expires_at - dt.datetime.now(dt.timezone.utc)).total_seconds()
print(f"session issued by short-TTL API, expires in {ttl:.2f}s")
check(0 < ttl <= 3, "short-TTL instance must issue ~2 second sessions")
for api in (short, short, main_api): # два раза подряд: второй ответ уже из кэша
api.call("GET", "/api/v1/users/me", 200, headers=auth, schema="User")
print("before expiry: GET /users/me -> 200 (short API twice, main API once)")
time.sleep(max(0.0, (expires_at - dt.datetime.now(dt.timezone.utc)).total_seconds()) + 1.0)
for api in (short, main_api):
api.call("GET", "/api/v1/users/me", 401, headers=auth) # клиент проверяет WWW-Authenticate: Bearer
print("after expiry: GET /users/me -> 401 on both instances")
print("PASS: session expired after SESSION_TTL_SECONDS; cache did not extend it")
if __name__ == "__main__":
run(main)
+63
View File
@@ -0,0 +1,63 @@
"""Общие помощники для собственных тестов.
Переиспользуем публичный HTTP-клиент курса (tests/client.py), а не пишем свой:
он уже проверяет X-Request-Id, формат ошибок, WWW-Authenticate и схемы ответов из контракта.
С lab2 клиент сам регистрирует пользователя с паролем, входит через Basic
и подставляет Bearer-токен (токен живёт только в памяти теста и не печатается).
"""
import base64
import subprocess
import sys
import time
from pathlib import Path
from urllib.parse import quote
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "tests"))
from client import Client, Failure, check, run # noqa: E402 (импорт после правки sys.path)
__all__ = ["Client", "Failure", "check", "run", "read_history", "basic", "login", "compose", "wait_ready", "ROOT"]
def read_history(api, actor, chat_id, limit=100):
"""Читает всю историю чата по страницам. Возвращает (сообщения, число_страниц)."""
items, pages, cursor = [], 0, None
while True:
query = f"?limit={limit}" + (f"&cursor={quote(cursor, safe='')}" if cursor else "")
page = api.call("GET", f"/api/v1/chats/{chat_id}/messages{query}",
actor=actor, schema="MessagePage")["json"]
items += page["items"]
pages += 1
cursor = page["next_cursor"]
if cursor is None:
return items, pages
def basic(username, password):
"""Значение заголовка Authorization: Basic base64(username:password), пароль в UTF-8."""
return "Basic " + base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("ascii")
def login(api, username, password, expected=201):
"""POST /auth/sessions; при успехе возвращает тело Session (токен — только в памяти)."""
schema = "Session" if expected == 201 else None
return api.call("POST", "/api/v1/auth/sessions", expected,
headers={"Authorization": basic(username, password)}, schema=schema)["json"]
def compose(*args):
"""docker compose <args> из корня репозитория; вывод скрыт (там могут быть имена/секреты)."""
subprocess.run(["docker", "compose", *args], cwd=ROOT, check=True,
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
def wait_ready(api, seconds=90):
deadline = time.monotonic() + seconds
while True:
try:
api.call("GET", "/health/ready", schema="Health")
return
except Failure:
check(time.monotonic() < deadline, f"API не стал готов за {seconds} с")
time.sleep(0.5)
+74
View File
@@ -0,0 +1,74 @@
"""Проверка гонок (уровень 4). Запуск: make race
1. 10 клиентов одновременно отправляют по 10 сообщений в один чат:
в истории ровно 100 сообщений, все id уникальны, ни один текст не потерян.
2. 20 клиентов одновременно регистрируют ОДИН И ТОТ ЖЕ username:
ровно один получает 201, остальные 409; в базе один такой пользователь.
Защита — уникальный индекс users.username в PostgreSQL, а не проверка в коде.
"""
import threading
import time
import uuid
from concurrent.futures import ThreadPoolExecutor
from helpers import Client, check, read_history, run
CLIENTS = 10
PER_CLIENT = 10
REGISTRATIONS = 20
def concurrent_messages(api):
users = [api.user(f"race{i}") for i in range(CLIENTS)]
chat = api.call("POST", "/api/v1/chats", 201, actor=users[0], schema="Chat",
body={"title": "race", "member_ids": [u["id"] for u in users]})["json"]
path = f"/api/v1/chats/{chat['id']}/messages"
start_together = threading.Barrier(CLIENTS) # все потоки стартуют одновременно
def send_all(index):
client = Client() # у каждого «клиента» свои HTTP-соединения
start_together.wait()
for n in range(PER_CLIENT):
client.call("POST", path, 201, actor=users[index], body={"text": f"client-{index}-msg-{n}"})
started = time.monotonic()
with ThreadPoolExecutor(max_workers=CLIENTS) as pool:
list(pool.map(send_all, range(CLIENTS))) # list() пробрасывает ошибки из потоков
elapsed = time.monotonic() - started
history, pages = read_history(api, users[0], chat["id"], limit=25)
expected = {f"client-{i}-msg-{n}" for i in range(CLIENTS) for n in range(PER_CLIENT)}
print(f"messages: sent {CLIENTS * PER_CLIENT} from {CLIENTS} parallel clients in {elapsed:.2f}s")
print(f"messages: read {len(history)} in {pages} pages, unique ids: {len({m['id'] for m in history})}")
check(len(history) == CLIENTS * PER_CLIENT, "wrong number of messages")
check(len({m["id"] for m in history}) == len(history), "duplicate message ids")
check({m["text"] for m in history} == expected, "lost or corrupted message texts")
print("PASS: 100 concurrent messages stored without loss or duplicates")
def concurrent_registration():
username = "race_" + uuid.uuid4().hex[:12]
start_together = threading.Barrier(REGISTRATIONS)
def register(index):
client = Client()
body = {"username": username, "display_name": f"Участник {index}", "password": f"Race-password-{index:03d}"}
start_together.wait()
return client.call("POST", "/api/v1/users", [201, 409], body=body)["status"]
with ThreadPoolExecutor(max_workers=REGISTRATIONS) as pool:
statuses = list(pool.map(register, range(REGISTRATIONS)))
created, conflicts = statuses.count(201), statuses.count(409)
print(f"registration: {REGISTRATIONS} parallel requests for one username -> 201 x{created}, 409 x{conflicts}")
check(created == 1 and conflicts == REGISTRATIONS - 1, "exactly one registration must win")
print("PASS: concurrent registration of the same username created exactly one user")
def main():
api = Client()
concurrent_messages(api)
concurrent_registration()
if __name__ == "__main__":
run(main)
+163
View File
@@ -0,0 +1,163 @@
"""Собственные тесты API (перенесены из lab1, переведены на пароль и Bearer).
Тесты «чёрного ящика»: шлют настоящие HTTP-запросы на уже запущенный стенд
(BASE_URL, по умолчанию http://127.0.0.1:8080 из Makefile).
Запуск вместе с test_auth.py одной командой: make student-test
"""
import unittest
import uuid
from helpers import Client, basic, read_history
PASSWORD = "Test-password-123"
class MessengerApiTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.api = Client()
cls.alice, cls.bob, cls.eve, cls.chat = cls.api.bootstrap() # eve не состоит в чате
def messages_path(self, chat_id):
return f"/api/v1/chats/{chat_id}/messages"
def send(self, actor, chat_id, text, expected=201):
schema = "Message" if expected == 201 else None # клиент разбирает JSON успешного ответа только со схемой
return self.api.call("POST", self.messages_path(chat_id), expected, actor=actor,
body={"text": text}, schema=schema)
def new_chat(self):
body = {"title": "Тест", "member_ids": [self.alice["id"], self.bob["id"]]}
return self.api.call("POST", "/api/v1/chats", 201, actor=self.alice, body=body, schema="Chat")["json"]
def test_malformed_json_returns_400(self):
json_header = {"Content-Type": "application/json"}
for raw in (b'{"username": "abc",', b"not json", b""):
self.api.call("POST", "/api/v1/users", 400, raw=raw, headers=json_header)
self.api.call("POST", self.messages_path(self.chat["id"]), 400,
actor=self.alice, raw=raw, headers=json_header)
def test_wrong_types_and_extra_fields_return_400(self):
self.api.call("POST", "/api/v1/users", 400,
body={"username": 123, "display_name": "x", "password": PASSWORD})
self.api.call("POST", "/api/v1/users", 400,
body={"username": "valid_name", "display_name": "x", "password": PASSWORD, "is_admin": True})
self.api.call("POST", "/api/v1/users", 400,
body={"username": "Bad Name!", "display_name": "x", "password": PASSWORD})
# Отправителя нельзя подставить: он берётся из сессии.
self.api.call("POST", self.messages_path(self.chat["id"]), 400, actor=self.alice,
body={"text": "hi", "sender_id": self.bob["id"]})
def test_outsider_gets_404_for_foreign_chat(self):
chat_id = self.chat["id"]
self.api.call("GET", f"/api/v1/chats/{chat_id}", 404, actor=self.eve)
self.api.call("GET", self.messages_path(chat_id), 404, actor=self.eve)
self.send(self.eve, chat_id, "чужое", expected=404)
# Несуществующий чат выглядит так же, как чужой: существование не раскрывается.
self.api.call("GET", f"/api/v1/chats/{uuid.uuid4()}", 404, actor=self.eve)
def test_auth_checked_before_access_and_body(self):
# Без токена — всегда 401, даже если тело кривое или чат чужой: сначала «кто ты».
self.api.call("POST", self.messages_path(self.chat["id"]), 401, raw=b"not json",
headers={"Content-Type": "application/json"})
self.api.call("GET", f"/api/v1/chats/{uuid.uuid4()}", 401)
def test_empty_blank_and_too_long_messages_return_400(self):
for text in ("", " ", "\n\t "):
self.send(self.alice, self.chat["id"], text, expected=400)
self.send(self.alice, self.chat["id"], "я" * 4001, expected=400)
self.send(self.alice, self.chat["id"], "я" * 4000) # ровно на границе — можно
def test_duplicate_username_returns_409(self):
body = {"username": "dup_" + uuid.uuid4().hex[:12], "display_name": "Первый", "password": PASSWORD}
self.api.call("POST", "/api/v1/users", 201, body=body)
self.api.call("POST", "/api/v1/users", 409, body=dict(body, display_name="Второй"))
def test_unicode_roundtrip(self):
text = "Привет 👋 你好 ﷽ é"
sent = self.send(self.alice, self.chat["id"], text)["json"]
self.assertEqual(sent["text"], text)
history, _ = read_history(self.api, self.bob, self.chat["id"])
self.assertIn(text, [m["text"] for m in history])
# Длина считается в символах Unicode: 100 эмодзи можно, 101 — нет.
name = "n_" + uuid.uuid4().hex[:12]
self.api.call("POST", "/api/v1/users", 400,
body={"username": name, "display_name": "👋" * 101, "password": PASSWORD})
self.api.call("POST", "/api/v1/users", 201,
body={"username": name, "display_name": "👋" * 100, "password": PASSWORD})
def test_nul_character_is_stored(self):
# Замечание к MR: U+0000 допустим по контракту и должен сохраняться как есть, а не давать 500.
name = "nul_" + uuid.uuid4().hex[:10]
password = "Pass\u0000word-123"
user = self.api.call("POST", "/api/v1/users", 201, schema="User",
body={"username": name, "display_name": "A\u0000B", "password": password})["json"]
self.assertEqual(user["display_name"], "A\u0000B")
session = self.api.call("POST", "/api/v1/auth/sessions", 201, schema="Session",
headers={"Authorization": basic(name, password)})["json"]
self.assertEqual(session["user"]["display_name"], "A\u0000B")
chat = self.api.call("POST", "/api/v1/chats", 201, actor=self.alice, schema="Chat",
body={"title": "T\u0000itle", "member_ids": [self.alice["id"], self.bob["id"]]})["json"]
self.assertEqual(chat["title"], "T\u0000itle")
sent = self.send(self.alice, chat["id"], "hello\u0000world")["json"]
self.assertEqual(sent["text"], "hello\u0000world")
history, _ = read_history(self.api, self.bob, chat["id"])
self.assertEqual([m["text"] for m in history], ["hello\u0000world"])
got = self.api.call("GET", f"/api/v1/chats/{chat['id']}", actor=self.bob, schema="Chat")["json"]
self.assertEqual(got["title"], "T\u0000itle")
# username с U+0000 существовать не может: вход — обычный 401, а не 500.
self.api.call("POST", "/api/v1/auth/sessions", 401, headers={"Authorization": basic("ab\u0000c", password)})
def test_pagination_walks_several_pages(self):
chat = self.new_chat()
sent = [self.send(self.alice, chat["id"], f"msg {i}")["json"] for i in range(7)]
history, pages = read_history(self.api, self.bob, chat["id"], limit=3)
self.assertEqual(pages, 3) # 3 + 3 + 1
self.assertEqual([m["id"] for m in history], [m["id"] for m in sent]) # без потерь, дублей и перестановок
def test_chat_list_pagination(self):
created = [self.new_chat()["id"] for _ in range(3)]
seen, cursor = [], None
while True:
query = "?limit=2" + (f"&cursor={cursor}" if cursor else "")
page = self.api.call("GET", "/api/v1/chats" + query, actor=self.bob, schema="ChatPage")["json"]
seen += [c["id"] for c in page["items"]]
cursor = page["next_cursor"]
if cursor is None:
break
self.assertEqual(len(seen), len(set(seen)))
self.assertEqual(seen[-3:], created) # новые чаты в конце, порядок (created_at, id)
def test_bad_cursor_returns_400(self):
chat_a, chat_b = self.new_chat(), self.new_chat()
for i in range(2):
self.send(self.alice, chat_a["id"], f"a{i}")
first = self.api.call("GET", self.messages_path(chat_a["id"]) + "?limit=1",
actor=self.alice, schema="MessagePage")["json"]
foreign_cursor = first["next_cursor"]
self.api.call("GET", self.messages_path(chat_b["id"]) + "?cursor=" + foreign_cursor, 400, actor=self.alice)
self.api.call("GET", self.messages_path(chat_a["id"]) + "?cursor=garbage", 400, actor=self.alice)
# Курсор правильной формы, но с испорченным временем/UUID: 400, а не ошибка БД (500).
import base64
import json
scope = "messages:" + chat_a["id"]
for bad in ([scope, "not-a-time", str(uuid.uuid4())],
[scope, "2026-01-01T00:00:00.000000Z", "not-a-uuid"],
[scope, "2026-01-01T00:00:00", str(uuid.uuid4())], # без часового пояса
[scope, "0001-01-01T00:00:00+14:00", str(uuid.uuid4())], # в UTC это год 0
[scope, "9999-12-31T23:59:59-14:00", str(uuid.uuid4())]): # в UTC это год 10000
forged = base64.urlsafe_b64encode(json.dumps(bad).encode()).decode()
self.api.call("GET", self.messages_path(chat_a["id"]) + "?cursor=" + forged, 400, actor=self.alice)
for limit in ("0", "101", "abc"):
self.api.call("GET", self.messages_path(chat_a["id"]) + "?limit=" + limit, 400, actor=self.alice)
def test_chat_membership_rules(self):
alice, bob = self.alice["id"], self.bob["id"]
for members in ([bob], [alice, alice], [alice, str(uuid.uuid4())]): # без себя, дубль, неизвестный
self.api.call("POST", "/api/v1/chats", 400, actor=self.alice, body={"title": "x", "member_ids": members})
chats = self.api.call("GET", "/api/v1/chats?limit=100", actor=self.eve, schema="ChatPage")["json"]
self.assertNotIn(self.chat["id"], [c["id"] for c in chats["items"]])
if __name__ == "__main__":
unittest.main()
+118
View File
@@ -0,0 +1,118 @@
"""Собственные тесты аутентификации (уровень 4): пароль, Basic -> Bearer, logout.
Запуск: make student-test (вместе с test_api.py)
"""
import base64
import datetime as dt
import unittest
import uuid
from helpers import Client, basic, login
PASSWORD = "Test-password-123"
def iso(value):
return dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
class AuthTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.api = Client()
def register(self, password=PASSWORD, expected=201):
body = {"username": "a_" + uuid.uuid4().hex[:12], "display_name": "Auth", "password": password}
user = self.api.call("POST", "/api/v1/users", expected, body=body,
schema="User" if expected == 201 else None)["json"]
return body, user
def me(self, token, expected=200):
return self.api.call("GET", "/api/v1/users/me", expected, headers={"Authorization": "Bearer " + token},
schema="User" if expected == 200 else None)
def test_login_returns_opaque_token_with_expiry(self):
body, user = self.register()
session = login(self.api, body["username"], body["password"])
self.assertEqual(session["user"], user)
token = session["token"]
self.assertGreaterEqual(len(token), 43) # 32 случайных байта в base64url
self.assertNotIn(body["username"], token)
self.assertNotIn(user["id"], token)
# Обычный стенд: TTL не меньше 300 с (по умолчанию 3600).
left = iso(session["expires_at"]) - dt.datetime.now(dt.timezone.utc)
self.assertGreater(left.total_seconds(), 290)
self.assertEqual(self.me(token)["json"], user)
def test_user_never_contains_password(self):
body, user = self.register()
self.assertEqual(set(user), {"id", "username", "display_name", "created_at"})
self.assertNotIn(body["password"], str(user))
def test_wrong_password_and_unknown_user_look_the_same(self):
body, _ = self.register()
wrong = login(self.api, body["username"], "Wrong-password-000", expected=401)
unknown = login(self.api, "nobody_" + uuid.uuid4().hex[:8], body["password"], expected=401)
# Одинаковый код и текст: по ответу нельзя узнать, существует ли username.
self.assertEqual(wrong["error"]["code"], unknown["error"]["code"])
self.assertEqual(wrong["error"]["message"], unknown["error"]["message"])
def test_malformed_basic_returns_401(self):
path = "/api/v1/auth/sessions"
no_colon = base64.b64encode(b"just_username").decode()
for header in (None, "Basic", "Basic !!!not-base64!!!", "Basic " + no_colon, "Bearer something"):
headers = {} if header is None else {"Authorization": header}
self.api.call("POST", path, 401, headers=headers) # клиент проверяет WWW-Authenticate: Basic
def test_password_with_colon_and_unicode(self):
password = "пароль:с:двоеточием 👋"
body, user = self.register(password=password)
session = login(self.api, body["username"], password)
self.assertEqual(session["user"], user)
def test_password_length_rules(self):
self.register(password="x" * 11, expected=400)
self.register(password="x" * 129, expected=400)
self.register(password=" " * 12, expected=400) # только пробелы — нельзя
self.register(password="x" * 12)
self.register(password="я" * 128) # 128 символов Unicode — можно
def test_bearer_required_on_business_endpoints(self):
body, user = self.register()
session = login(self.api, body["username"], body["password"])
for headers in ({}, {"Authorization": basic(body["username"], body["password"])},
{"X-User-Id": user["id"]}, {"Authorization": "Bearer " + "A" * 43},
{"Authorization": "Bearer"}, {"Authorization": "Token " + session["token"]}):
self.api.call("GET", "/api/v1/users/me", 401, headers=headers) # WWW-Authenticate: Bearer
# Схема нечувствительна к регистру (RFC 7235).
self.api.call("GET", "/api/v1/users/me", 200, headers={"Authorization": "bearer " + session["token"]})
def test_x_user_id_does_not_change_identity(self):
body, user = self.register()
_, other = self.register()
session = login(self.api, body["username"], body["password"])
me = self.api.call("GET", "/api/v1/users/me", headers={
"Authorization": "Bearer " + session["token"], "X-User-Id": other["id"]}, schema="User")["json"]
self.assertEqual(me["id"], user["id"])
def test_logout_revokes_only_current_session(self):
body, _ = self.register()
first = login(self.api, body["username"], body["password"])["token"]
second = login(self.api, body["username"], body["password"])["token"]
self.me(first) # запись попадает в кэш Valkey
self.api.call("DELETE", "/api/v1/auth/sessions/current", 204, headers={"Authorization": "Bearer " + first})
self.me(first, expected=401) # кэш инвалидирован: отозванный токен не принимается сразу
self.api.call("DELETE", "/api/v1/auth/sessions/current", 401, headers={"Authorization": "Bearer " + first})
self.me(second) # другая сессия того же пользователя продолжает работать
def test_relogin_after_logout(self):
body, _ = self.register()
token = login(self.api, body["username"], body["password"])["token"]
self.api.call("DELETE", "/api/v1/auth/sessions/current", 204, headers={"Authorization": "Bearer " + token})
again = login(self.api, body["username"], body["password"])["token"]
self.assertNotEqual(token, again)
self.me(again)
if __name__ == "__main__":
unittest.main()