ЛР 2 — БВТ2304 — Запорожец Михаил — на 4 #117

Closed
Rainak wants to merge 2 commits from Rainak/lab2-zaporozhets-mikhail-bvt2304-na4:solution/bvt2304-zaporozhets into master
31 changed files with 1881 additions and 16 deletions
+14 -1
View File
@@ -7,5 +7,18 @@ SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
# postgres - sessions only in PostgreSQL
# postgres+valkey - PostgreSQL is the source of truth, Valkey is a read-through session cache with TTL
SESSION_STORE=postgres+valkey
CACHE_URL_FILE=/run/secrets/cache_url
# Max lifetime of a cached session copy (also the cache-distrust window after a Valkey error)
SESSION_CACHE_TTL_SECONDS=60
# Bounded pool and timeouts
DB_POOL_MAX=10
DB_STATEMENT_TIMEOUT_MS=5000
DB_ACQUIRE_TIMEOUT_MS=2000
CACHE_TIMEOUT_MS=300
# Parallel Argon2id computations (each uses 64 MiB)
PASSWORD_HASH_WORKERS=4
# Host port bound to 127.0.0.1
API_PUBLISHED_PORT=8080
+6
View File
@@ -0,0 +1,6 @@
# Shell-скрипты выполняются в Linux-контейнерах: всегда LF, даже при checkout на Windows.
*.sh text eol=lf
*.sql text eol=lf
*.conf text eol=lf
Dockerfile text eol=lf
*.Dockerfile text eol=lf
+26
View File
@@ -0,0 +1,26 @@
# API мессенджера lab2. Образ собирается из исходников этого репозитория.
FROM python:3.12.12-slim-bookworm
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /srv
# Сначала зависимости (кэшируемый слой), потом код.
COPY requirements.txt .
RUN pip install --no-deps -r requirements.txt
COPY app ./app
COPY migrations ./migrations
RUN useradd --system --uid 10001 --no-create-home appuser
USER appuser
EXPOSE 8080
HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=3 \
CMD ["python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).status == 200 else 1)"]
# exec-форма: uvicorn — PID 1 и получает SIGTERM от docker stop напрямую.
CMD ["python", "-m", "app"]
+118 -15
View File
@@ -1,37 +1,140 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Запорожец Михаил, БВТ2304
- Целевая оценка: **4** (трек 5 не заявлен)
- Commit/PR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/117 (ветка solution/bvt2304-zaporozhets, коммит 0c58461)
- Использованные источники, библиотеки и помощь ИИ: документация PostgreSQL (transactions, EXPLAIN, row comparison), Valkey persistence, RFC 7617, RFC 9106 (Argon2); библиотеки FastAPI 0.115, asyncpg 0.30, argon2-cffi 23.1, redis-py 5.2. Код, схема и тесты написаны с помощью ИИ-ассистента (Claude); решения разобраны и проверены автором.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
**Нужно:** Docker Engine/Desktop с Compose v2.20+ (проверено: Docker 29.8.2, Compose 5.6.0, Windows 11 + Docker Desktop) и POSIX-shell (Linux/macOS или Git Bash на Windows). Python и make на хосте **не нужны**: проверки запускаются в сервисе `tester` (Python 3.12 + GNU make + docker CLI).
| Роль | Сервис | Образ | Health/readiness | Volume | Порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| API | `api` | сборка `Dockerfile` (python:3.12.12-slim-bookworm) | `GET /health/ready` (HEALTHCHECK) | нет (stateless) | `127.0.0.1:8080` | secrets `database_url`, `cache_url` |
| Миграции | `migrate` (one-shot) | тот же образ | exit 0 | — | — | secret `database_url` |
| PostgreSQL | `postgres` | postgres:17.7-bookworm | `pg_isready` | `pgdata` (named) | только внутренняя сеть | `POSTGRES_PASSWORD_FILE` |
| Кэш сессий | `valkey` | valkey/valkey:8.1.4 | `valkey-cli ping` | нет (persistence выключена намеренно) | только внутренняя сеть | `requirepass` в secret `valkey_conf` |
| API с TTL=2 с | `api-ttl` (profile `test`) | тот же образ | как у api | — | `127.0.0.1:8081` | как у api |
| Тестовый стенд | `tester` (profile `tools`) | python:3.12.12-alpine3.22 + make + docker-cli | — | bind `.` | — | docker.sock |
```sh
git clone <repo> && cd <repo>
sh scripts/init-secrets.sh # создаёт ./secrets/* со случайными паролями и .env из .env.example; значения не печатает
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait # postgres+valkey -> migrate (применяет миграции) -> api healthy
# Публичные проверки (внутри Linux-контейнера tester; на Linux-хосте можно и просто `make ...` с BASE_URL=http://localhost:8080)
docker compose --env-file .env --profile tools run --rm tester make check
docker compose --env-file .env --profile tools run --rm tester make test
docker compose --env-file .env --profile tools run --rm tester make test-persistence ACTION_SCRIPT=scripts/restart.sh
# Собственные проверки уровня 4 и EXPLAIN
sh scripts/test-grade4.sh # поднимает api-ttl, гоняет student-tests/test_grade4.py, гасит api-ttl
sh scripts/explain.sh # seed 50 000 синтетических сообщений (один раз) -> evidence/explain.txt
```
- Миграции: `python -m app.migrate` (сервис `migrate`) применяет `migrations/NNNN_*.sql` по порядку, каждую в отдельной транзакции, под `pg_advisory_lock`; версия и SHA-256 файла пишутся в `schema_migrations`. Повторный запуск печатает `skip` и ничего не дублирует (`evidence/migrations.txt`); изменённый задним числом файл останавливает запуск.
- Действий оператора, кроме `init-secrets.sh`, не требуется.
- Безопасная остановка (данные сохраняются): `docker compose --env-file .env stop` или `docker compose --env-file .env down`.
- **Намеренное удаление учебных данных:** `docker compose --env-file .env down -v` (удаляет volume `mtusi-lab2_pgdata`). Секреты: удалить каталог `secrets/`.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```
клиент ──HTTP──> api (FastAPI/uvicorn, 1 процесс)
├─ asyncpg pool (≤10 соединений) ──> PostgreSQL 17 ← источник истины: users, chats, chat_members, messages, sessions
└─ redis-py (timeout 300 мс) ──────> Valkey 8.1 ← только кэш сессий с TTL, без persistence
```
**Что перенесено из lab1 и что изменено.** Контракт ресурсов lab1 (пользователи, чаты, сообщения, keyset-пагинация, единый формат ошибок, X-Request-Id) сохранён, но хранение перенесено из памяти в PostgreSQL. Объявленные переходы lab2: `password` при регистрации (Argon2id), `POST /auth/sessions` только с Basic, все бизнес-endpoint только с `Bearer`, `X-User-Id` игнорируется, `DELETE /auth/sessions/current`.
**Схема** (`migrations/0001_init.sql`):
| Таблица | Ключи и ограничения | Индексы и зачем |
| --- | --- | --- |
| `users` | PK `id`; `UNIQUE(username)`; CHECK формата username и длины display_name | unique-индекс username (вход и защита от дублей) |
| `sessions` | PK `token_hash` (SHA-256 токена, 32 байта); FK `user_id`; `expires_at`, `revoked_at` | `user_id`; `expires_at` (фоновая очистка) |
| `chats` | PK `id`; FK `created_by`; CHECK длины title | `(created_at, id)` — порядок списка |
| `chat_members` | PK `(chat_id, user_id)`; FK на chats и users | `(user_id, chat_id)` — «чаты пользователя» |
| `messages` | PK `id`; **составной FK `(chat_id, sender_id) → chat_members`**: писать может только участник; CHECK длины text | `(chat_id, created_at, id)` — keyset-пагинация |
**Транзакционные границы.**
- `POST /chats`: одна транзакция `INSERT chats` + `INSERT chat_members SELECT … FROM users WHERE id = ANY($2)`. Если вставлено меньше участников, чем передано (неизвестный UUID), бросается исключение → `ROLLBACK`, строки `chats` не остаётся (тест `test_chat_rollback`).
- `POST /messages`: один оператор `INSERT … SELECT … WHERE EXISTS (участник)` — проверка доступа и запись без окна гонки; дополнительно составной FK.
- `POST /users`: гонку одинаковых username решает `UNIQUE` → `UniqueViolation` → 409 (тест `test_username_race`: 16 параллельных запросов → ровно один 201 и 15×409).
- Все остальные запросы — одиночные операторы в autocommit.
**Аутентификация и сессии.**
- Пароль: Argon2id (argon2-cffi, профиль RFC 9106 low-memory: m=64 MiB, t=3, p=4), считается в отдельном пуле из `PASSWORD_HASH_WORKERS=4` потоков, чтобы не блокировать event loop и ограничить память. Для несуществующего username выполняется verify по фиктивному хешу — время и текст ответа одинаковые.
- Токен: `secrets.token_urlsafe(32)` = 256 бит CSPRNG. В БД и в ключе кэша — только SHA-256 токена.
- Срок: `expires_at = clock_timestamp() + SESSION_TTL_SECONDS` вычисляется в БД при входе; рестарт его не продлевает.
- **Источник истины сессий — PostgreSQL.** Valkey — read-through кэш: ключ `session:<sha256>`, значение `{user_id, expires_at}`, TTL = `min(остаток жизни, SESSION_CACHE_TTL_SECONDS=60)`. При промахе — запрос в PostgreSQL и заполнение кэша.
- **Инвалидация:** logout = `UPDATE sessions SET revoked_at` (COMMIT) → затем `DEL` в Valkey. Если любая операция с Valkey упала, API 60 с (= максимальный TTL записи) не читает кэш, а ходит в PostgreSQL. Так копия отозванной сессии, которую не удалось стереть при разрыве, не может быть использована (тест `test_revoke_during_cache_partition`).
- **Почему Valkey без persistence:** он не единственное хранилище сессий. Flush или рестарт Valkey = пустой кэш, сессии восстанавливаются из PostgreSQL (`test_valkey_cache_role`: после `FLUSHALL` тот же токен работает, ключ создаётся заново).
**Критичность зависимостей (`/health/ready`).** Критична только PostgreSQL: `SELECT 1` с таймаутом 1 с, иначе 503. Valkey не критичен: без него API корректно работает через PostgreSQL. `/health/live` не трогает зависимости.
**Ограничения пула и таймауты:** `DB_POOL_MAX=10`, ожидание соединения из пула 2 с, `statement_timeout=5 с`, `idle_in_transaction_session_timeout=10 с`, connect timeout 3 с; Valkey connect/read timeout 300 мс. Исчерпание пула или недоступность БД → `503 unavailable`, без деталей.
**Пагинация.** Ключ `(created_at, id)` по возрастанию, `LIMIT limit+1` (лишняя строка = есть следующая страница). Курсор — base64url от `{scope, created_at, id}`; scope = `messages:<chat_id>` или `chats`, курсор другого чата/списка → 400. Подделка курсора не даёт доступа: членство проверяется отдельно. `created_at` отдаётся с микросекундами — та же точность, что в `timestamptz`, поэтому клиентская сортировка совпадает с серверной. **Семантика при конкурентных вставках:** `created_at = clock_timestamp()` в момент INSERT; транзакция с меньшим `created_at` может закоммититься позже, чем читатель прошёл эту позицию, и тогда её сообщение не попадёт в уже пройденные страницы (видно при новом обходе). Повторов не бывает. Часы — одни (сервер PostgreSQL), поэтому рассинхронизации реплик API нет.
**Соответствие `.env.example` реальной конфигурации:** `APP_HOST`, `APP_PORT` (внутри контейнера всегда 8080; на хосте `API_PUBLISHED_PORT`), `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE=postgres+valkey` (`postgres` — без кэша), `CACHE_URL_FILE`, `SESSION_CACHE_TTL_SECONDS`, `DB_POOL_MAX`, `DB_STATEMENT_TIMEOUT_MS`, `DB_ACQUIRE_TIMEOUT_MS`, `CACHE_TIMEOUT_MS`, `PASSWORD_HASH_WORKERS` — читаются в `app/config.py`. `APP_ENV` только информационный. Секреты передаются файлами через Compose secrets (`/run/secrets/*`), не через переменные окружения и не через образ.
## Доказательства критериев
Все проверки выполнены 2026-10-29 на Windows 11 + Docker Desktop (8 vCPU, 4 GB RAM для VM).
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Публичный smoke | `tester make check`, `tester make test` | `PASS: offline skeleton…`, `PASS: lab2 public API scenario` | `evidence/public-tests.txt` |
| 3: данные и сессии переживают рестарт API и хранилищ | `tester make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session` | `evidence/public-tests.txt` |
| 3: hook реально перезапускает api, postgres, valkey без удаления volume | `sh scripts/restart.sh` + `docker inspect StartedAt`, `docker volume inspect` | StartedAt всех трёх изменился; volume `created 15:27:24Z` до и после; 50 029 сообщений до и после; в логе PG `shut down` → `ready to accept` | `evidence/restart-hook.txt` |
| 3: PK/FK, UNIQUE username, миграции с нуля | `\d messages`; свежий проект с пустым volume | составной FK и индексы видны; на пустом volume `apply 0001_init` и smoke PASS | `evidence/migrations.txt`, `evidence/fresh-start.txt` |
| 3: повтор миграций без дублей | `docker compose run --rm migrate` | `skip 0001_init`, в `schema_migrations` одна строка | `evidence/migrations.txt` |
| 3: атомарное создание чата / 4: rollback составной операции | `test_chat_rollback` | счётчики `chats`/`chat_members` до и после ошибочного POST равны | `evidence/grade4-tests.txt` |
| 3: Basic только на входе, Bearer на остальном, X-User-Id игнорируется | smoke + `test_wrong_password` | Basic на `/users/me` → 401 Bearer; Bearer на входе → 401 Basic; X-User-Id не меняет пользователя | `evidence/public-tests.txt`, `evidence/grade4-tests.txt` |
| 3: KDF паролей | код `app/security.py`, строка в `users.password_hash` начинается с `$argon2id$` | — | исходники |
| 3: секреты и volumes вне Git | `git check-ignore -v .env secrets/…`; поиск значений секретов по репозиторию | игнорируются `.gitignore`; значений вне `secrets/` нет | — |
| 4: Valkey реально используется для сессий с TTL, flush не теряет сессии | `test_valkey_cache_role` | ключ `session:<sha256>` с TTL ∈ (0, 60]; после `FLUSHALL` токен валиден, ключ создан заново | `evidence/grade4-tests.txt` |
| 4: инвалидация при сбое кэша | `test_revoke_during_cache_partition` (`docker network disconnect` valkey во время logout + возврат устаревшей записи) | после восстановления связи отозванный токен → 401 | `evidence/grade4-tests.txt` |
| 4: гонка регистрации одинакового username | `test_username_race` (16 потоков, Barrier) | ровно `[201, 409×15]`, в БД одна строка | `evidence/grade4-tests.txt` |
| 4: параметризованные запросы, ограниченный пул, таймауты | код `app/main.py`, `app/db.py` | только `$1..$n` asyncpg, `max_size=10`, acquire 2 с, statement_timeout 5 с | исходники |
| 4: индекс истории обоснован EXPLAIN на ≥10 000 сообщений | `sh scripts/explain.sh` | 50 029 сообщений (20 000 в одном чате). Keyset-страница 301: Index Scan, 51 строка, **5 буферов, 0.09 мс**; OFFSET 15000: 15 051 строка, 313 буферов, 4.0 мс; без индекса: Seq Scan 50 029 строк + Sort, 637 буферов, 6.3 мс | `evidence/explain.txt` |
| 4: expiry при коротком TTL | `test_short_ttl` (api-ttl, SESSION_TTL_SECONDS=2) | `/users/me` 200 сразу, 401 через 3 с | `evidence/grade4-tests.txt` |
| 4: logout | `test_logout` | 204 → 401 (Bearer challenge) → повтор logout 401; в БД `revoked_at` установлен | `evidence/grade4-tests.txt` |
| 4: неверный пароль | `test_wrong_password` | 401 с `Basic realm="messenger", charset="UTF-8"`; текст для неверного пароля и несуществующего пользователя одинаковый | `evidence/grade4-tests.txt` |
| 4: недоступность Valkey | `test_valkey_down` (`docker compose stop valkey`) | действующий токен 200 (обход кэша), неизвестный и пустой — 401, вход/logout работают, ready 200 | `evidence/grade4-tests.txt` |
| 4: недоступность БД | `test_postgres_down` (`docker compose stop postgres`) | live 200, ready 503; `/users/me` с токеном и с неизвестным токеном → **503 unavailable** (не 200 и не 500); без токена 401; после `start` тот же токен снова 200 | `evidence/grade4-tests.txt` |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
**Нагрузка (только для наблюдения, не оценка ёмкости).** `python tests/load.py --duration 20 --concurrency 4` из контейнера tester; стенд на том же ноутбуке (Docker Desktop VM 8 vCPU / 4 GB), ~50 000 сообщений в БД, без прогрева, один прогон. 4 920 успешных POST, 0 ошибок, **244 successful RPS, p50 15.2 мс, p95 24.3 мс, p99 29.0 мс**. Ограничения: closed-loop (coordinated omission), клиент и сервер делят CPU, один запуск — не статистика. Raw: `evidence/load.json`.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| `scripts/restart.sh`: stop api → restart postgres, valkey → start api | данные и сессия сохраняются | persistence PASS, тот же токен читает те же сообщения | API ready через ~5 с после hook; потерь нет (PostgreSQL завершился штатно с checkpoint) |
| `FLUSHALL` в Valkey | сессии не теряются | токен валиден, кэш заполнен при первом запросе | мгновенно; потерь нет |
| `docker compose stop valkey` | работа через PostgreSQL, аноним не пропускается | 200 для действующего токена, 401 для остальных; ready 200 | после `start` кэш снова используется через ≤60 с (окно недоверия) |
| Разрыв сети API↔Valkey во время logout | отозванный токен не воскресает из кэша | 401 после восстановления связи | — |
| `docker compose stop postgres` | ограниченная ошибка, без пропуска | 503 `unavailable` на защищённых запросах, ready 503, live 200 | после `start` ready ≈ 2–5 с; первый запрос на «мёртвом» соединении пула может получить 503, следующие успешны; подтверждённые данные сохранены |
## Ответы на вопросы защиты
**Что подтверждает COMMIT и какие гарантии зависят от настройки durability?** COMMIT означает, что все изменения транзакции стали видимы другим сессиям атомарно (все или ни одного) и, при `synchronous_commit=on` и `fsync=on` (у нас значения по умолчанию), запись WAL сброшена на диск до ответа клиенту. Поэтому подтверждённое сообщение переживает падение процесса или контейнера. Если включить `synchronous_commit=off`, COMMIT вернётся раньше сброса WAL, и при падении ОС можно потерять последние ~3×`wal_writer_delay` транзакций (БД при этом остаётся консистентной). `fsync=off` грозит уже повреждением данных. От потери диска или хоста COMMIT на одном узле не защищает: для этого нужны реплика или бэкап. В Docker Desktop диск — виртуальный диск VM, и честность fsync зависит и от него.
**Где хранятся сессии и что будет после flush/restart Redis?** Источник истины — таблица `sessions` в PostgreSQL (хеш токена, user_id, expires_at, revoked_at). Valkey хранит только копии с TTL ≤ 60 с. После `FLUSHALL` или рестарта Valkey кэш пуст: первый запрос с токеном идёт в PostgreSQL и снова кладёт копию в кэш, пользователь ничего не замечает. Если бы сессии хранились только в Redis, понадобилась бы AOF (`appendfsync everysec`/`always`), и всё равно было бы окно потери, а TTL сам по себе ничего не сохраняет.
**Чем аутентификация отличается от доступа к конкретному чату?** Аутентификация отвечает на вопрос «кто это» по действующему Bearer-токену: если токена нет или он неверный, ответ 401. Доступ (авторизация) отвечает на вопрос «можно ли этому пользователю этот чат»: проверяется членство в `chat_members` для каждого запроса. Посторонний получает 404, как и для несуществующего чата, чтобы не раскрывать, что чат существует. Порядок всегда такой: сначала аутентификация, потом доступ.
**Почему hash пароля и быстрый checksum решают разные задачи?** Checksum (SHA-256, CRC) нужен для целостности и должен быть быстрым: GPU считает миллиарды SHA-256 в секунду. Пароли людей имеют низкую энтропию, поэтому украденную базу быстрых хешей перебирают по словарю за минуты. Password KDF (Argon2id) специально медленный и требует много памяти (64 MiB на одну попытку), а уникальная соль делает бесполезными заранее посчитанные таблицы. Перебор дорожает на много порядков, а один честный вход стоит десятки миллисекунд. Обратный пример есть в самой работе: токен сессии мы храним как SHA-256, потому что у него 256 бит случайности и перебор невозможен, так что медленный KDF там не нужен.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Окно недоверия к кэшу хранится в памяти процесса. С одной репликой API (lab2) это закрывает дыру инвалидации полностью. С несколькими репликами (lab3) другая реплика не узнает о сбое, и отозванный токен может приниматься ею до 60 с. Варианты: версия сессии в кэше плюс проверка `revoked_at` при записи, pub/sub-инвалидация или короткий TTL кэша.
- Отказоустойчивость только на уровне процесса и контейнера: один узел PostgreSQL без реплики и бэкапов; потеря volume или диска означает потерю данных.
- Семантика пагинации при конкурентных вставках описана выше: пропуск позднего коммита с ранним `created_at` возможен, повторов нет.
- Rate limiting входа не реализован (необязателен). Argon2 ограничен пулом из 4 потоков, но перебор паролей ничем не тормозится.
- Истёкшие сессии удаляются фоновой задачей раз в час (старше суток), это гигиена, а не корректность: проверка `expires_at` выполняется на каждом запросе.
- Тест «Valkey недоступен во время logout» моделирует потерю `DEL` явной перезаписью устаревшей копии, потому что при `docker network disconnect` или `pause` ядро всё равно доставляет `DEL` повторной передачей TCP после восстановления связи.
- HTTP без TLS — только локальный стенд (порты привязаны к 127.0.0.1); Basic не шифрует пароль.
View File
+16
View File
@@ -0,0 +1,16 @@
"""Запуск: python -m app (HTTP-процесс — PID 1 в контейнере)."""
import logging
import os
import uvicorn
def main() -> None:
logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(name)s %(message)s')
uvicorn.run('app.main:app', host=os.environ.get('APP_HOST', '0.0.0.0'),
port=int(os.environ.get('APP_PORT', '8080')), proxy_headers=False,
server_header=False, timeout_graceful_shutdown=10)
if __name__ == '__main__':
main()
+59
View File
@@ -0,0 +1,59 @@
"""Настройки из переменных окружения. Секреты читаются только из файлов (*_FILE)."""
import os
from dataclasses import dataclass
from pathlib import Path
def _int(name: str, default: int, low: int, high: int) -> int:
value = int(os.environ.get(name, default))
if not low <= value <= high:
raise ValueError(f'{name} must be in [{low}, {high}]')
return value
def _secret(name: str) -> str | None:
"""Значение из файла, путь к которому лежит в переменной NAME_FILE."""
path = os.environ.get(name + '_FILE')
if not path:
return None
return Path(path).read_text(encoding='utf-8').strip()
@dataclass(frozen=True)
class Settings:
host: str
port: int
session_ttl: int
session_store: str
session_cache_ttl: int
database_url: str
cache_url: str | None
db_pool_max: int
db_statement_timeout_ms: int
db_acquire_timeout: float
cache_timeout: float
hash_workers: int
def load() -> Settings:
database_url = _secret('DATABASE_URL') or os.environ.get('DATABASE_URL')
if not database_url:
raise RuntimeError('DATABASE_URL_FILE is not configured')
store = os.environ.get('SESSION_STORE', 'postgres')
if store not in ('postgres', 'postgres+valkey'):
raise ValueError('SESSION_STORE must be postgres or postgres+valkey')
cache_url = _secret('CACHE_URL') if store == 'postgres+valkey' else None
return Settings(
host=os.environ.get('APP_HOST', '0.0.0.0'),
port=_int('APP_PORT', 8080, 1, 65535),
session_ttl=_int('SESSION_TTL_SECONDS', 3600, 1, 30 * 24 * 3600),
session_store=store,
session_cache_ttl=_int('SESSION_CACHE_TTL_SECONDS', 60, 1, 3600),
database_url=database_url,
cache_url=cache_url,
db_pool_max=_int('DB_POOL_MAX', 10, 1, 100),
db_statement_timeout_ms=_int('DB_STATEMENT_TIMEOUT_MS', 5000, 100, 600000),
db_acquire_timeout=_int('DB_ACQUIRE_TIMEOUT_MS', 2000, 100, 60000) / 1000,
cache_timeout=_int('CACHE_TIMEOUT_MS', 300, 10, 10000) / 1000,
hash_workers=_int('PASSWORD_HASH_WORKERS', 4, 1, 32),
)
+65
View File
@@ -0,0 +1,65 @@
"""Ограниченный пул соединений asyncpg и перевод сбоев БД в 503."""
import asyncio
from contextlib import asynccontextmanager
import asyncpg
from .config import Settings
from .errors import unavailable
# Ошибки "БД недоступна/перегружена" -> 503, а не 500 и тем более не пропуск запроса.
DB_UNAVAILABLE = (
OSError,
asyncio.TimeoutError,
asyncpg.PostgresConnectionError,
asyncpg.InterfaceError,
asyncpg.CannotConnectNowError,
asyncpg.TooManyConnectionsError,
asyncpg.QueryCanceledError, # statement_timeout
asyncpg.AdminShutdownError,
)
class Database:
def __init__(self, settings: Settings):
self.settings = settings
self.pool: asyncpg.Pool | None = None
async def start(self) -> None:
s = self.settings
# min_size соединений создаётся лениво (connect при первом acquire), поэтому API стартует
# даже при недоступной БД и честно отвечает 503 в /health/ready.
self.pool = asyncpg.create_pool(
s.database_url,
min_size=0,
max_size=s.db_pool_max,
timeout=3, # таймаут установления соединения
command_timeout=s.db_statement_timeout_ms / 1000 + 1,
max_inactive_connection_lifetime=300,
server_settings={
'application_name': 'messenger-api',
'statement_timeout': str(s.db_statement_timeout_ms),
'idle_in_transaction_session_timeout': '10000',
'timezone': 'UTC',
},
)
await self.pool
async def close(self) -> None:
if self.pool is not None:
await self.pool.close()
@asynccontextmanager
async def connection(self):
try:
async with self.pool.acquire(timeout=self.settings.db_acquire_timeout) as conn:
yield conn
except DB_UNAVAILABLE:
raise unavailable() from None
async def ping(self) -> bool:
try:
async with self.pool.acquire(timeout=1) as conn:
return await conn.fetchval('SELECT 1', timeout=1) == 1
except DB_UNAVAILABLE:
return False
+48
View File
@@ -0,0 +1,48 @@
"""Единый формат ошибок {"error":{"code","message","request_id"}}."""
from contextvars import ContextVar
from fastapi.responses import JSONResponse
request_id_var: ContextVar[str] = ContextVar('request_id', default='-')
BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"'
BEARER_CHALLENGE = 'Bearer realm="messenger"'
class ApiError(Exception):
def __init__(self, status: int, code: str, message: str, headers: dict | None = None):
super().__init__(message)
self.status = status
self.code = code
self.message = message
self.headers = headers or {}
def invalid(message: str = 'Некорректный запрос') -> ApiError:
return ApiError(400, 'invalid_request', message)
def not_found() -> ApiError:
# Одинаковый ответ для "нет такого" и "чужое": существование чужого чата не раскрывается.
return ApiError(404, 'not_found', 'Объект не найден')
def unauthorized_bearer() -> ApiError:
return ApiError(401, 'unauthorized', 'Требуется действительная сессия', {'WWW-Authenticate': BEARER_CHALLENGE})
def unauthorized_basic() -> ApiError:
return ApiError(401, 'unauthorized', 'Неверные учётные данные', {'WWW-Authenticate': BASIC_CHALLENGE})
def unavailable() -> ApiError:
return ApiError(503, 'unavailable', 'Сервис временно недоступен')
def error_response(status: int, code: str, message: str, headers: dict | None = None) -> JSONResponse:
rid = request_id_var.get()
return JSONResponse(
status_code=status,
content={'error': {'code': code, 'message': message, 'request_id': rid}},
headers=headers,
)
+355
View File
@@ -0,0 +1,355 @@
"""HTTP API мессенджера lab2 по contracts/openapi.json."""
import asyncio
import base64
import binascii
import logging
import re
import uuid
from contextlib import asynccontextmanager
from datetime import datetime, timezone
from uuid import UUID
import asyncpg
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, Response
from starlette.exceptions import HTTPException as StarletteHTTPException
from . import config, validation as v
from .db import DB_UNAVAILABLE, Database
from .errors import (ApiError, error_response, invalid, not_found, request_id_var,
unauthorized_basic, unauthorized_bearer, unavailable)
from .security import PasswordService, new_token
from .sessions import SessionStore
log = logging.getLogger('messenger')
settings = config.load()
db = Database(settings)
sessions = SessionStore(settings, db)
passwords = PasswordService(settings.hash_workers)
async def purge_loop() -> None:
while True:
await asyncio.sleep(3600)
try:
removed = await sessions.purge_expired()
log.info('purged %d expired sessions', removed)
except Exception: # очистка — фоновая гигиена, её сбой не должен ронять процесс
log.warning('session purge failed', exc_info=True)
@asynccontextmanager
async def lifespan(_app: FastAPI):
await db.start()
task = asyncio.create_task(purge_loop())
yield
task.cancel()
await sessions.cache.close()
await db.close()
passwords.close()
app = FastAPI(lifespan=lifespan, openapi_url=None, docs_url=None, redoc_url=None)
# ---------- request id, ошибки ----------
REQUEST_ID_RE = re.compile(r'[A-Za-z0-9._:-]{1,128}')
@app.middleware('http')
async def request_id_middleware(request: Request, call_next):
incoming = request.headers.get('x-request-id', '')
rid = incoming if REQUEST_ID_RE.fullmatch(incoming) else uuid.uuid4().hex
request_id_var.set(rid)
try:
response = await call_next(request)
except Exception:
log.exception('unhandled error, request_id=%s', rid)
response = error_response(500, 'internal_error', 'Внутренняя ошибка сервера')
response.headers['X-Request-Id'] = rid
return response
@app.exception_handler(ApiError)
async def api_error_handler(_request: Request, exc: ApiError):
return error_response(exc.status, exc.code, exc.message, exc.headers)
@app.exception_handler(StarletteHTTPException)
async def http_error_handler(_request: Request, exc: StarletteHTTPException):
if exc.status_code == 404:
return error_response(404, 'not_found', 'Объект не найден')
if exc.status_code == 405:
return error_response(405, 'invalid_request', 'Метод не поддерживается', dict(exc.headers or {}))
return error_response(exc.status_code, 'invalid_request', 'Некорректный запрос')
@app.exception_handler(RequestValidationError)
async def validation_error_handler(_request: Request, _exc: RequestValidationError):
return error_response(400, 'invalid_request', 'Некорректный запрос')
async def db_unavailable_handler(_request: Request, _exc: Exception):
# Страховка: сбой связи с БД вне db.connection() тоже даёт ограниченный 503, а не 500.
return error_response(503, 'unavailable', 'Сервис временно недоступен')
for _exc_type in DB_UNAVAILABLE:
app.add_exception_handler(_exc_type, db_unavailable_handler)
# ---------- представление ----------
def ts(value: datetime) -> str:
# RFC 3339 UTC с микросекундами: точность совпадает с timestamptz и с ключом пагинации.
return value.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.%fZ')
def user_json(row) -> dict:
return {'id': str(row['id']), 'username': row['username'],
'display_name': row['display_name'], 'created_at': ts(row['created_at'])}
def chat_json(row) -> dict:
return {'id': str(row['id']), 'title': row['title'],
'member_ids': [str(m) for m in row['member_ids']], 'created_at': ts(row['created_at'])}
def message_json(row) -> dict:
return {'id': str(row['id']), 'chat_id': str(row['chat_id']), 'sender_id': str(row['sender_id']),
'text': row['text'], 'created_at': ts(row['created_at'])}
USER_COLUMNS = 'id, username, display_name, created_at'
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) AS member_ids')
MESSAGE_COLUMNS = 'id, chat_id, sender_id, text, created_at'
# ---------- аутентификация ----------
TOKEN_RE = re.compile(r'[A-Za-z0-9_-]{32,128}')
def bearer_token(request: Request) -> str:
"""Только Authorization: Bearer. X-User-Id и Basic здесь игнорируются/отклоняются."""
scheme, _, token = request.headers.get('authorization', '').partition(' ')
token = token.strip()
if scheme.lower() != 'bearer' or not TOKEN_RE.fullmatch(token):
raise unauthorized_bearer()
return token
async def current_user(request: Request) -> UUID:
session = await sessions.resolve(bearer_token(request))
if session is None:
raise unauthorized_bearer()
return session.user_id
def basic_credentials(request: Request) -> tuple[str, str]:
scheme, _, encoded = request.headers.get('authorization', '').partition(' ')
if scheme.lower() != 'basic':
raise unauthorized_basic()
try:
decoded = base64.b64decode(encoded.strip(), validate=True)
username, sep, password = decoded.partition(b':') # двоеточие допустимо внутри пароля
if not sep:
raise ValueError
return username.decode('ascii'), password.decode('utf-8')
except (ValueError, binascii.Error, UnicodeDecodeError):
raise unauthorized_basic() from None
# ---------- health ----------
@app.get('/health/live')
async def live():
return {'status': 'ok'}
@app.get('/health/ready')
async def ready():
# Критична только PostgreSQL (источник истины). Valkey — кэш: без него API работает медленнее, но корректно.
if not await db.ping():
raise unavailable()
return {'status': 'ok'}
# ---------- пользователи и сессии ----------
@app.post('/api/v1/users', status_code=201)
async def create_user(request: Request):
data = await v.read_json(request)
v.fields(data, {'username', 'display_name', 'password'})
username = v.username(data)
display_name = v.text_field(data, 'display_name', 1, 100)
password = v.text_field(data, 'password', 12, 128)
password_hash = await passwords.hash(password)
try:
async with db.connection() as conn:
row = await conn.fetchrow(
f'INSERT INTO users (username, display_name, password_hash) VALUES ($1, $2, $3) RETURNING {USER_COLUMNS}',
username, display_name, password_hash)
except asyncpg.UniqueViolationError:
# Гонка двух одинаковых регистраций решается UNIQUE-индексом: COMMIT пройдёт только у одной.
raise ApiError(409, 'conflict', 'username уже занят') from None
return JSONResponse(user_json(row), status_code=201)
@app.post('/api/v1/auth/sessions', status_code=201)
async def create_session(request: Request):
if await request.body():
raise invalid('Тело запроса не допускается; используйте Authorization: Basic')
username, password = basic_credentials(request)
row = None
if v.USERNAME_RE.fullmatch(username) and 12 <= len(password) <= 128:
async with db.connection() as conn:
row = await conn.fetchrow(
f'SELECT {USER_COLUMNS}, password_hash FROM users WHERE username = $1', username)
# verify выполняется всегда (и для несуществующего пользователя) — одинаковое время ответа.
if not await passwords.verify(row['password_hash'] if row else None, password):
raise unauthorized_basic()
token = new_token()
session = await sessions.create(row['id'], token)
return JSONResponse({'token': token, 'token_type': 'Bearer', 'expires_at': ts(session.expires_at),
'user': user_json(row)}, status_code=201, headers={'Cache-Control': 'no-store'})
@app.delete('/api/v1/auth/sessions/current', status_code=204)
async def delete_session(request: Request):
token = bearer_token(request)
if not await sessions.revoke(token):
raise unauthorized_bearer()
return Response(status_code=204)
@app.get('/api/v1/users/me')
async def me(request: Request):
user_id = await current_user(request)
async with db.connection() as conn:
row = await conn.fetchrow(f'SELECT {USER_COLUMNS} FROM users WHERE id = $1', user_id)
if row is None:
raise not_found()
return user_json(row)
# ---------- чаты ----------
@app.post('/api/v1/chats', status_code=201)
async def create_chat(request: Request):
user_id = await current_user(request)
data = await v.read_json(request)
v.fields(data, {'title', 'member_ids'})
title = v.text_field(data, 'title', 1, 100)
raw_members = data['member_ids']
if not isinstance(raw_members, list) or not 1 <= len(raw_members) <= 100:
raise invalid('member_ids должен быть массивом из 1..100 UUID')
members = [v.uuid_value(m, 'member_id') for m in raw_members]
if len(set(members)) != len(members):
raise invalid('member_ids содержит дубликаты')
if user_id not in members:
raise invalid('Создатель должен входить в member_ids')
async with db.connection() as conn:
# Одна транзакция: чат и все участники появляются вместе или не появляются вовсе.
async with conn.transaction():
chat = await conn.fetchrow(
'INSERT INTO chats (title, created_by) VALUES ($1, $2) RETURNING id, created_at', title, user_id)
added = await conn.fetch(
'INSERT INTO chat_members (chat_id, user_id) '
'SELECT $1, u.id FROM users u WHERE u.id = ANY($2::uuid[]) RETURNING user_id',
chat['id'], members)
if len(added) != len(members):
# Исключение внутри conn.transaction() -> ROLLBACK, строка chats тоже откатывается.
raise invalid('member_ids содержит неизвестных пользователей')
return JSONResponse({'id': str(chat['id']), 'title': title,
'member_ids': sorted(str(m) for m in members),
'created_at': ts(chat['created_at'])}, status_code=201)
@app.get('/api/v1/chats')
async def list_chats(request: Request):
user_id = await current_user(request)
limit = v.limit_param(request)
after = v.decode_cursor(request, 'chats')
query = (f'SELECT {CHAT_COLUMNS} FROM chats c '
'JOIN chat_members m ON m.chat_id = c.id AND m.user_id = $1 ')
params = [user_id, limit + 1]
if after:
query += 'WHERE (c.created_at, c.id) > ($3, $4) '
params += after
query += 'ORDER BY c.created_at, c.id LIMIT $2'
async with db.connection() as conn:
rows = await conn.fetch(query, *params)
return page(rows, limit, 'chats', chat_json)
def page(rows, limit: int, scope: str, render) -> dict:
# Читаем limit+1 строку: если лишняя есть — следующая страница существует.
items = rows[:limit]
cursor = (v.encode_cursor(scope, items[-1]['created_at'], items[-1]['id'])
if len(rows) > limit else None)
return {'items': [render(r) for r in items], 'next_cursor': cursor}
async def chat_for_member(conn, chat_id: UUID, user_id: UUID):
return await conn.fetchrow(
f'SELECT {CHAT_COLUMNS} FROM chats c '
'WHERE c.id = $1 AND EXISTS (SELECT 1 FROM chat_members m WHERE m.chat_id = c.id AND m.user_id = $2)',
chat_id, user_id)
@app.get('/api/v1/chats/{chat_id}')
async def get_chat(chat_id: str, request: Request):
user_id = await current_user(request)
cid = v.uuid_value(chat_id, 'chat_id')
async with db.connection() as conn:
row = await chat_for_member(conn, cid, user_id)
if row is None:
raise not_found()
return chat_json(row)
# ---------- сообщения ----------
@app.post('/api/v1/chats/{chat_id}/messages', status_code=201)
async def create_message(chat_id: str, request: Request):
user_id = await current_user(request)
cid = v.uuid_value(chat_id, 'chat_id')
data = await v.read_json(request)
v.fields(data, {'text'}) # sender_id в запросе не принимается — отправитель берётся из сессии
text = v.text_field(data, 'text', 1, 4000)
async with db.connection() as conn:
# Проверка членства и вставка — один атомарный оператор, без окна гонки между ними.
row = await conn.fetchrow(
f'INSERT INTO messages (chat_id, sender_id, text) '
f'SELECT $1, $2, $3 WHERE EXISTS '
f'(SELECT 1 FROM chat_members WHERE chat_id = $1 AND user_id = $2) RETURNING {MESSAGE_COLUMNS}',
cid, user_id, text)
if row is None:
raise not_found()
return JSONResponse(message_json(row), status_code=201)
@app.get('/api/v1/chats/{chat_id}/messages')
async def list_messages(chat_id: str, request: Request):
user_id = await current_user(request)
cid = v.uuid_value(chat_id, 'chat_id')
limit = v.limit_param(request)
after = v.decode_cursor(request, 'messages:' + str(cid))
async with db.connection() as conn:
member = await conn.fetchval(
'SELECT 1 FROM chat_members WHERE chat_id = $1 AND user_id = $2', cid, user_id)
if member is None:
raise not_found()
if after:
# Keyset: продолжаем строго после последнего элемента прошлой страницы (без OFFSET).
rows = await conn.fetch(
f'SELECT {MESSAGE_COLUMNS} FROM messages WHERE chat_id = $1 AND (created_at, id) > ($3, $4) '
'ORDER BY created_at, id LIMIT $2', cid, limit + 1, *after)
else:
rows = await conn.fetch(
f'SELECT {MESSAGE_COLUMNS} FROM messages WHERE chat_id = $1 '
'ORDER BY created_at, id LIMIT $2', cid, limit + 1)
return page(rows, limit, 'messages:' + str(cid), message_json)
+57
View File
@@ -0,0 +1,57 @@
"""Версионированные миграции: migrations/NNNN_name.sql применяются по порядку, каждая в своей транзакции.
Повторный запуск безопасен: применённые версии записаны в schema_migrations и пропускаются,
изменённый задним числом файл (другая контрольная сумма) останавливает запуск.
Advisory lock не даёт двум параллельным запускам применить одну миграцию дважды.
"""
import asyncio
import hashlib
from pathlib import Path
import asyncpg
from . import config
MIGRATIONS = Path(__file__).resolve().parent.parent / 'migrations'
LOCK_ID = 2026_0002
async def connect(url: str, attempts: int = 30) -> asyncpg.Connection:
for attempt in range(attempts):
try:
return await asyncpg.connect(url, timeout=3)
except (OSError, asyncpg.CannotConnectNowError, asyncpg.PostgresConnectionError):
if attempt == attempts - 1:
raise
await asyncio.sleep(1)
async def migrate() -> None:
settings = config.load()
conn = await connect(settings.database_url)
try:
await conn.execute('SELECT pg_advisory_lock($1)', LOCK_ID)
await conn.execute(
'CREATE TABLE IF NOT EXISTS schema_migrations ('
' version text PRIMARY KEY, checksum text NOT NULL,'
' applied_at timestamptz NOT NULL DEFAULT clock_timestamp())')
applied = {r['version']: r['checksum'] for r in await conn.fetch('SELECT version, checksum FROM schema_migrations')}
for path in sorted(MIGRATIONS.glob('[0-9][0-9][0-9][0-9]_*.sql')):
version = path.stem
sql = path.read_text(encoding='utf-8')
checksum = hashlib.sha256(sql.encode()).hexdigest()
if version in applied:
if applied[version] != checksum:
raise SystemExit(f'migration {version} was modified after being applied')
print(f'skip {version}')
continue
async with conn.transaction():
await conn.execute(sql)
await conn.execute('INSERT INTO schema_migrations (version, checksum) VALUES ($1, $2)', version, checksum)
print(f'apply {version}')
finally:
await conn.close()
if __name__ == '__main__':
asyncio.run(migrate())
+47
View File
@@ -0,0 +1,47 @@
"""Пароли (Argon2id) и непрозрачные токены сессий."""
import asyncio
import hashlib
import secrets
from concurrent.futures import ThreadPoolExecutor
from argon2 import PasswordHasher
from argon2.exceptions import InvalidHashError, VerificationError
# Параметры по умолчанию argon2-cffi = профиль RFC 9106 "low memory": Argon2id, m=64 MiB, t=3, p=4.
_hasher = PasswordHasher()
# Хеш для несуществующего пользователя: вход выполняет ту же работу и не выдаёт по времени,
# что такого username нет.
_DUMMY_HASH = _hasher.hash('dummy-password-for-timing')
class PasswordService:
"""KDF дорогой по CPU и памяти: считаем в отдельном ограниченном пуле потоков,
чтобы не блокировать event loop и не съесть всю память параллельными входами."""
def __init__(self, workers: int):
self._pool = ThreadPoolExecutor(max_workers=workers, thread_name_prefix='argon2')
async def hash(self, password: str) -> str:
return await asyncio.get_running_loop().run_in_executor(self._pool, _hasher.hash, password)
async def verify(self, password_hash: str | None, password: str) -> bool:
def check() -> bool:
try:
return _hasher.verify(password_hash or _DUMMY_HASH, password) and password_hash is not None
except (VerificationError, InvalidHashError):
return False
return await asyncio.get_running_loop().run_in_executor(self._pool, check)
def close(self) -> None:
self._pool.shutdown(wait=False)
def new_token() -> str:
# 32 случайных байта = 256 бит энтропии из CSPRNG ОС; base64url -> 43 символа.
return secrets.token_urlsafe(32)
def token_hash(token: str) -> bytes:
# Для токена с 256 битами энтропии быстрый SHA-256 достаточен: перебор невозможен.
# Для паролей (низкая энтропия) так нельзя — там нужен медленный KDF.
return hashlib.sha256(token.encode('ascii')).digest()
+148
View File
@@ -0,0 +1,148 @@
"""Сессии: PostgreSQL — источник истины, Valkey — read-through кэш с TTL.
Политика:
- создание: INSERT в PostgreSQL (COMMIT), затем SET в кэш с TTL = min(остаток жизни, SESSION_CACHE_TTL_SECONDS);
- проверка: кэш -> при промахе PostgreSQL -> заполнить кэш;
- logout: UPDATE revoked_at в PostgreSQL (COMMIT), затем DEL из кэша;
- любой сбой Valkey: работаем только с PostgreSQL и SESSION_CACHE_TTL_SECONDS не доверяем кэшу
(все записи, сделанные до сбоя, за это время гарантированно истекут — например, не удалённая
при logout копия отозванной сессии). Flush/рестарт Valkey = пустой кэш, сессии не теряются.
"""
import json
import logging
import time
from dataclasses import dataclass
from datetime import datetime, timezone
from uuid import UUID
import redis.asyncio as redis
from redis.exceptions import RedisError
from .config import Settings
from .db import Database
from .security import token_hash
log = logging.getLogger('messenger.sessions')
@dataclass(frozen=True)
class Session:
user_id: UUID
expires_at: datetime
class SessionCache:
def __init__(self, url: str | None, ttl: int, timeout: float):
self.ttl = ttl
self.client = redis.Redis.from_url(
url, socket_timeout=timeout, socket_connect_timeout=timeout,
retry_on_timeout=False, health_check_interval=30,
) if url else None
self._distrust_until = 0.0
@staticmethod
def key(digest: bytes) -> str:
return 'session:' + digest.hex()
def usable(self) -> bool:
return self.client is not None and time.monotonic() >= self._distrust_until
def _failed(self, op: str) -> None:
# Не знаем, что успело/не успело записаться: перестаём читать кэш на один максимальный TTL.
self._distrust_until = time.monotonic() + self.ttl
log.warning('valkey %s failed; bypassing cache for %ss', op, self.ttl)
async def get(self, digest: bytes) -> Session | None:
if not self.usable():
return None
try:
raw = await self.client.get(self.key(digest))
except (RedisError, OSError):
self._failed('get')
return None
if raw is None:
return None
data = json.loads(raw)
return Session(UUID(data['u']), datetime.fromtimestamp(data['e'], timezone.utc))
async def put(self, digest: bytes, session: Session) -> None:
if not self.usable():
return
remaining = int((session.expires_at - datetime.now(timezone.utc)).total_seconds())
ttl = min(self.ttl, remaining)
if ttl <= 0:
return
value = json.dumps({'u': str(session.user_id), 'e': session.expires_at.timestamp()})
try:
await self.client.set(self.key(digest), value, ex=ttl)
except (RedisError, OSError):
self._failed('set')
async def delete(self, digest: bytes) -> None:
if self.client is None:
return
try:
await self.client.delete(self.key(digest))
except (RedisError, OSError):
self._failed('delete')
async def close(self) -> None:
if self.client is not None:
await self.client.aclose()
class SessionStore:
def __init__(self, settings: Settings, db: Database):
self.ttl = settings.session_ttl
self.db = db
self.cache = SessionCache(settings.cache_url, settings.session_cache_ttl, settings.cache_timeout)
async def create(self, user_id: UUID, token: str) -> Session:
digest = token_hash(token)
async with self.db.connection() as conn:
# Время берём из БД, чтобы срок не зависел от часов конкретной реплики API.
expires_at = await conn.fetchval(
'INSERT INTO sessions (token_hash, user_id, expires_at) '
'VALUES ($1, $2, clock_timestamp() + make_interval(secs => $3)) RETURNING expires_at',
digest, user_id, self.ttl,
)
session = Session(user_id, expires_at)
await self.cache.put(digest, session)
return session
async def resolve(self, token: str) -> Session | None:
digest = token_hash(token)
now = datetime.now(timezone.utc)
cached = await self.cache.get(digest)
if cached is not None and cached.expires_at > now:
return cached
async with self.db.connection() as conn:
row = await conn.fetchrow(
'SELECT user_id, expires_at FROM sessions '
'WHERE token_hash = $1 AND revoked_at IS NULL AND expires_at > clock_timestamp()',
digest,
)
if row is None:
return None
session = Session(row['user_id'], row['expires_at'])
await self.cache.put(digest, session)
return session
async def revoke(self, token: str) -> bool:
digest = token_hash(token)
async with self.db.connection() as conn:
status = await conn.execute(
'UPDATE sessions SET revoked_at = clock_timestamp() '
'WHERE token_hash = $1 AND revoked_at IS NULL AND expires_at > clock_timestamp()',
digest,
)
# Инвалидация кэша строго после COMMIT в источнике истины.
await self.cache.delete(digest)
return status == 'UPDATE 1'
async def purge_expired(self) -> int:
async with self.db.connection() as conn:
status = await conn.execute(
"DELETE FROM sessions WHERE expires_at < clock_timestamp() - interval '1 day'")
return int(status.split()[-1])
+108
View File
@@ -0,0 +1,108 @@
"""Строгий разбор JSON и параметров: лишние поля, неверные типы, malformed JSON -> 400."""
import base64
import json
import re
from datetime import datetime
from uuid import UUID
from fastapi import Request
from .errors import ApiError, invalid
MAX_BODY_BYTES = 64 * 1024
USERNAME_RE = re.compile(r'[a-z0-9_]{3,32}')
async def read_json(request: Request) -> dict:
media_type = request.headers.get('content-type', '').split(';')[0].strip().lower()
if media_type != 'application/json':
raise ApiError(415, 'unsupported_media_type', 'Ожидается Content-Type: application/json')
body = await request.body()
if len(body) > MAX_BODY_BYTES:
raise ApiError(413, 'payload_too_large', 'Слишком большое тело запроса')
try:
data = json.loads(body.decode('utf-8'))
except (UnicodeDecodeError, ValueError):
raise invalid('Некорректный JSON') from None
if not isinstance(data, dict):
raise invalid('Ожидается JSON-объект')
return data
def fields(data: dict, required: set[str], optional: set[str] = frozenset()) -> None:
extra = set(data) - required - optional
if extra:
raise invalid('Неизвестные поля: ' + ', '.join(sorted(extra)))
missing = required - set(data)
if missing:
raise invalid('Отсутствуют поля: ' + ', '.join(sorted(missing)))
def text_field(data: dict, name: str, min_len: int, max_len: int, *, allow_blank: bool = False) -> str:
value = data[name]
if not isinstance(value, str):
raise invalid(f'Поле {name} должно быть строкой')
try:
value.encode('utf-8') # отсекает одиночные суррогаты из \uD800-экранирования
except UnicodeEncodeError:
raise invalid(f'Поле {name} содержит некорректный Unicode') from None
if not min_len <= len(value) <= max_len: # len(str) в Python = число code points
raise invalid(f'Длина поля {name} должна быть {min_len}..{max_len} символов')
if not allow_blank and not value.strip():
raise invalid(f'Поле {name} не может состоять из пробелов')
return value
def username(data: dict) -> str:
value = data['username']
if not isinstance(value, str) or not USERNAME_RE.fullmatch(value):
raise invalid('username должен соответствовать [a-z0-9_]{3,32}')
return value
def uuid_value(value, what: str = 'идентификатор') -> UUID:
if not isinstance(value, str):
raise invalid(f'Некорректный {what}')
try:
parsed = UUID(value)
except ValueError:
raise invalid(f'Некорректный {what}') from None
if str(parsed) != value.lower(): # только каноническая форма 8-4-4-4-12
raise invalid(f'Некорректный {what}')
return parsed
def limit_param(request: Request) -> int:
raw = request.query_params.get('limit')
if raw is None:
return 50
if not re.fullmatch(r'[0-9]{1,3}', raw) or not 1 <= int(raw) <= 100:
raise invalid('limit должен быть целым 1..100')
return int(raw)
# Курсор: base64url(JSON {"s": область, "t": created_at, "i": id}). Для клиента это непрозрачная строка.
# Подделка курсора ничего не даёт: доступ к чату проверяется отдельно, а область привязывает
# курсор к конкретному чату/списку — курсор другого чата отклоняется с 400.
def encode_cursor(scope: str, created_at: datetime, item_id: UUID) -> str:
raw = json.dumps({'s': scope, 't': created_at.isoformat(), 'i': str(item_id)}, separators=(',', ':'))
return base64.urlsafe_b64encode(raw.encode()).decode().rstrip('=')
def decode_cursor(request: Request, scope: str) -> tuple[datetime, UUID] | None:
raw = request.query_params.get('cursor')
if raw is None:
return None
try:
if len(raw) > 512:
raise ValueError
data = json.loads(base64.urlsafe_b64decode(raw + '=' * (-len(raw) % 4)))
if not isinstance(data, dict) or set(data) != {'s', 't', 'i'} or data['s'] != scope:
raise ValueError
created_at = datetime.fromisoformat(data['t'])
if created_at.tzinfo is None:
raise ValueError
return created_at, UUID(data['i'])
except (ValueError, TypeError, UnicodeDecodeError):
raise invalid('Некорректный cursor') from None
+122
View File
@@ -0,0 +1,122 @@
# Стенд lab2: api + postgres + valkey (+ служебные профили test/tools).
# Подготовка: sh scripts/init-secrets.sh && cp .env.example .env
# Запуск: docker compose --env-file .env up -d --build --wait
name: mtusi-lab2
x-api-env: &api-env
APP_HOST: ${APP_HOST:-0.0.0.0}
APP_PORT: "8080"
APP_ENV: ${APP_ENV:-lab}
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
SESSION_STORE: ${SESSION_STORE:-postgres+valkey}
SESSION_CACHE_TTL_SECONDS: ${SESSION_CACHE_TTL_SECONDS:-60}
DATABASE_URL_FILE: ${DATABASE_URL_FILE:-/run/secrets/database_url}
CACHE_URL_FILE: ${CACHE_URL_FILE:-/run/secrets/cache_url}
DB_POOL_MAX: ${DB_POOL_MAX:-10}
DB_STATEMENT_TIMEOUT_MS: ${DB_STATEMENT_TIMEOUT_MS:-5000}
DB_ACQUIRE_TIMEOUT_MS: ${DB_ACQUIRE_TIMEOUT_MS:-2000}
CACHE_TIMEOUT_MS: ${CACHE_TIMEOUT_MS:-300}
PASSWORD_HASH_WORKERS: ${PASSWORD_HASH_WORKERS:-4}
x-api-depends: &api-depends
postgres:
condition: service_healthy
migrate:
condition: service_completed_successfully
valkey:
# Valkey — кэш, не источник истины: API должен стартовать и без него.
condition: service_started
required: false
services:
postgres:
image: postgres:17.7-bookworm
environment:
POSTGRES_USER: app
POSTGRES_DB: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets: [postgres_password]
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD", "pg_isready", "-U", "app", "-d", "messenger"]
interval: 2s
timeout: 3s
retries: 30
stop_grace_period: 30s # даём PostgreSQL завершиться с checkpoint, без recovery при старте
restart: unless-stopped
valkey:
image: valkey/valkey:8.1.4
command: ["valkey-server", "/run/secrets/valkey_conf"]
secrets: [valkey_conf]
healthcheck:
test: ["CMD-SHELL", "valkey-cli --no-auth-warning -a \"$$(sed -n 's/^requirepass //p' /run/secrets/valkey_conf)\" ping | grep -q PONG"]
interval: 2s
timeout: 3s
retries: 30
restart: unless-stopped
migrate:
build: .
image: mtusi-lab2-api:local
command: ["python", "-m", "app.migrate"]
environment:
DATABASE_URL_FILE: /run/secrets/database_url
SESSION_STORE: postgres
secrets: [database_url]
depends_on:
postgres:
condition: service_healthy
restart: "no"
api:
image: mtusi-lab2-api:local
build: .
environment: *api-env
secrets: [database_url, cache_url]
ports:
- "127.0.0.1:${API_PUBLISHED_PORT:-8080}:8080"
depends_on: *api-depends
restart: unless-stopped
# Отдельная реплика с коротким TTL только для автотеста истечения сессии.
api-ttl:
profiles: [test]
image: mtusi-lab2-api:local
environment:
<<: *api-env
SESSION_TTL_SECONDS: "2"
secrets: [database_url, cache_url]
ports:
- "127.0.0.1:8081:8080"
depends_on: *api-depends
# Linux-окружение для make/тестов/restart.sh (нужно на Windows без make и WSL).
tester:
profiles: [tools]
build:
context: .
dockerfile: tools/tester.Dockerfile
working_dir: /work
environment:
BASE_URL: http://api:8080
TTL_BASE_URL: http://api-ttl:8080
PYTHONUTF8: "1"
PYTHONDONTWRITEBYTECODE: "1"
volumes:
- .:/work
- /var/run/docker.sock:/var/run/docker.sock
volumes:
pgdata:
secrets:
postgres_password:
file: ./secrets/postgres_password
database_url:
file: ./secrets/database_url
cache_url:
file: ./secrets/cache_url
valkey_conf:
file: ./secrets/valkey.conf
+102
View File
@@ -0,0 +1,102 @@
# EXPLAIN evidence, 2026-10-29T15:35:04Z, commit 65003b6
== Объём данных
total_messages | big_chat_messages | table_size | index_size
----------------+-------------------+------------+------------
50029 | 20000 | 5096 kB | 4112 kB
(1 row)
== 1. Первая страница (запрос API без cursor, limit=50 -> LIMIT 51)
QUERY PLAN
------------------------------------------------------------------------------------------------------------
Limit (actual time=0.017..0.046 rows=51 loops=1)
Buffers: shared hit=6
-> Index Scan using messages_chat_created_id_idx on messages (actual time=0.016..0.037 rows=51 loops=1)
Index Cond: (chat_id = 'ad832a44-34ce-416b-a5f8-f8e528316fd6'::uuid)
Buffers: shared hit=6
Planning:
Buffers: shared hit=6
Planning Time: 0.156 ms
Execution Time: 0.072 ms
(9 rows)
== 2. Страница 301 через keyset cursor (запрос API с cursor)
QUERY PLAN
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Limit (actual time=0.015..0.036 rows=51 loops=1)
Buffers: shared hit=5
-> Index Scan using messages_chat_created_id_idx on messages (actual time=0.015..0.029 rows=51 loops=1)
Index Cond: ((chat_id = 'ad832a44-34ce-416b-a5f8-f8e528316fd6'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 04:10:00+00'::timestamp with time zone, '1e3006cf-e446-47db-80e3-a34c031790a8'::uuid)))
Buffers: shared hit=5
Planning Time: 0.232 ms
Execution Time: 0.086 ms
(7 rows)
== 3. Для сравнения: та же страница через OFFSET (НЕ используется в API)
QUERY PLAN
---------------------------------------------------------------------------------------------------------------
Limit (actual time=4.002..4.015 rows=51 loops=1)
Buffers: shared hit=313
-> Index Scan using messages_chat_created_id_idx on messages (actual time=0.017..3.277 rows=15051 loops=1)
Index Cond: (chat_id = 'ad832a44-34ce-416b-a5f8-f8e528316fd6'::uuid)
Buffers: shared hit=313
Planning Time: 0.088 ms
Execution Time: 4.035 ms
(7 rows)
== 4. Для сравнения: keyset-запрос без индекса (DROP INDEX внутри транзакции, затем ROLLBACK)
QUERY PLAN
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Limit (actual time=6.187..6.193 rows=51 loops=1)
Buffers: shared hit=637
-> Sort (actual time=6.185..6.188 rows=51 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 31kB
Buffers: shared hit=637
-> Seq Scan on messages (actual time=1.966..5.520 rows=5000 loops=1)
Filter: ((chat_id = 'ad832a44-34ce-416b-a5f8-f8e528316fd6'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 04:10:00+00'::timestamp with time zone, '1e3006cf-e446-47db-80e3-a34c031790a8'::uuid)))
Rows Removed by Filter: 45029
Buffers: shared hit=637
Planning:
Buffers: shared hit=5
Planning Time: 0.096 ms
Execution Time: 6.267 ms
(14 rows)
== 5. Список чатов пользователя (запрос API GET /chats, limit=50)
QUERY PLAN
-----------------------------------------------------------------------------------------------------
Limit (actual time=0.230..0.420 rows=31 loops=1)
Buffers: shared hit=33
-> Result (actual time=0.229..0.415 rows=31 loops=1)
Buffers: shared hit=33
-> Sort (actual time=0.145..0.148 rows=31 loops=1)
Sort Key: c.created_at, c.id
Sort Method: quicksort Memory: 27kB
Buffers: shared hit=2
-> Hash Join (actual time=0.088..0.097 rows=31 loops=1)
Hash Cond: (c.id = m.chat_id)
Buffers: shared hit=2
-> Seq Scan on chats c (actual time=0.005..0.008 rows=42 loops=1)
Buffers: shared hit=1
-> Hash (actual time=0.015..0.016 rows=31 loops=1)
Buckets: 1024 Batches: 1 Memory Usage: 10kB
Buffers: shared hit=1
-> Seq Scan on chat_members m (actual time=0.006..0.010 rows=31 loops=1)
Filter: (user_id = '264c4b72-36e7-41e2-895d-18a04eb55baf'::uuid)
Rows Removed by Filter: 19
Buffers: shared hit=1
SubPlan 1
-> Sort (actual time=0.006..0.006 rows=1 loops=31)
Sort Key: cm.user_id
Sort Method: quicksort Memory: 25kB
Buffers: shared hit=31
-> Seq Scan on chat_members cm (actual time=0.003..0.004 rows=1 loops=31)
Filter: (chat_id = c.id)
Rows Removed by Filter: 49
Buffers: shared hit=31
Planning:
Buffers: shared hit=51
Planning Time: 0.700 ms
Execution Time: 0.495 ms
(33 rows)
+4
View File
@@ -0,0 +1,4 @@
# Fresh empty volume check, 2026-10-29T15:38:02Z (separate throwaway project mtusi-lab2-fresh)
migrate-1 | apply 0001_init
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
removed objects: 6
+13
View File
@@ -0,0 +1,13 @@
# Grade-4 student tests, 2026-10-29T15:36:49Z
$ sh scripts/test-grade4.sh
PASS test_wrong_password (0.4s)
PASS test_logout (0.6s)
PASS test_short_ttl (3.2s)
PASS test_username_race (1.6s)
PASS test_chat_rollback (1.0s)
PASS test_cursor_rules (0.8s)
PASS test_valkey_cache_role (1.5s)
PASS test_revoke_during_cache_partition (1.9s)
PASS test_valkey_down (4.2s)
PASS test_postgres_down (9.0s)
10/10 passed
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 20.0,
"elapsed_seconds": 20.134,
"concurrency": 4,
"successful_requests": 4920,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 244.368,
"successful_latency_ms": {
"p50": 15.203,
"p95": 24.258,
"p99": 28.968
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+26
View File
@@ -0,0 +1,26 @@
# Migrations re-run evidence, 2026-10-29T15:36:22Z
$ docker compose run --rm migrate
skip 0001_init
$ select version, checksum, applied_at from schema_migrations
version | checksum | applied_at
-----------+------------------+-------------------------------
0001_init | b0f6ac0177a064da | 2026-10-29 15:27:31.980855+00
(1 row)
$ \d messages
Table "public.messages"
Column | Type | Collation | Nullable | Default
------------+--------------------------+-----------+----------+-------------------
id | uuid | | not null | gen_random_uuid()
chat_id | uuid | | not null |
sender_id | uuid | | not null |
text | text | | not null |
created_at | timestamp with time zone | | not null | clock_timestamp()
Indexes:
"messages_pkey" PRIMARY KEY, btree (id)
"messages_chat_created_id_idx" btree (chat_id, created_at, id)
Check constraints:
"messages_text_check" CHECK (char_length(text) >= 1 AND char_length(text) <= 4000)
Foreign-key constraints:
"messages_sender_is_member" FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members(chat_id, user_id)
+8
View File
@@ -0,0 +1,8 @@
# Public checks, 2026-10-29T15:36:27Z (run inside tester container: python 3.12 + GNU make)
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
python3 tests/smoke.py --base-url "http://api:8080"
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://api: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.
+35
View File
@@ -0,0 +1,35 @@
# Restart hook evidence, 2026-10-29T15:35:55Z
$ docker compose ps (before)
SERVICE STATUS
api Up 23 seconds (healthy)
postgres Up 26 seconds (healthy)
valkey Up 27 seconds (healthy)
$ docker volume inspect mtusi-lab2_pgdata (before)
mtusi-lab2_pgdata created 2026-10-29T15:27:24Z
$ messages count (before)
50029
$ sh scripts/restart.sh
before:
/mtusi-lab2-api-1 2026-10-29T15:35:32.425887132Z
/mtusi-lab2-postgres-1 2026-10-29T15:35:28.694054577Z
/mtusi-lab2-valkey-1 2026-10-29T15:35:28.598642747Z
after:
/mtusi-lab2-api-1 2026-10-29T15:36:04.421672285Z
/mtusi-lab2-postgres-1 2026-10-29T15:36:00.44755603Z
/mtusi-lab2-valkey-1 2026-10-29T15:36:00.560733883Z
$ docker compose ps (after)
SERVICE STATUS
api Up 1 second (health: starting)
postgres Up 5 seconds (healthy)
valkey Up 5 seconds (healthy)
$ docker volume inspect mtusi-lab2_pgdata (after)
mtusi-lab2_pgdata created 2026-10-29T15:27:24Z
$ messages count (after)
50029
$ docker compose logs postgres --since 1m | grep -E "shut down|ready to accept"
postgres-1 | 2026-10-29 15:35:28.065 UTC [1] LOG: database system is shut down
postgres-1 | 2026-10-29 15:35:29.149 UTC [29] LOG: database system was shut down at 2026-10-29 15:35:28 UTC
postgres-1 | 2026-10-29 15:35:29.158 UTC [1] LOG: database system is ready to accept connections
postgres-1 | 2026-10-29 15:35:59.971 UTC [1] LOG: database system is shut down
postgres-1 | 2026-10-29 15:36:00.824 UTC [31] LOG: database system was shut down at 2026-10-29 15:35:59 UTC
postgres-1 | 2026-10-29 15:36:00.835 UTC [1] LOG: database system is ready to accept connections
+59
View File
@@ -0,0 +1,59 @@
-- 0001: базовая схема мессенджера lab2.
-- Применяется раннером app/migrate.py внутри одной транзакции; версия пишется в schema_migrations.
CREATE TABLE users (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
username text NOT NULL,
display_name text NOT NULL,
password_hash text NOT NULL, -- строка Argon2id ($argon2id$v=19$m=...,t=...,p=...$salt$hash)
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
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)
);
-- Серверные сессии. Источник истины; Valkey хранит только копию с TTL.
-- В БД лежит SHA-256 от токена, а не сам токен: утечка дампа не даёт войти.
CREATE TABLE sessions (
token_hash bytea PRIMARY KEY CHECK (octet_length(token_hash) = 32),
user_id uuid NOT NULL REFERENCES users (id) ON DELETE CASCADE,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
expires_at timestamptz NOT NULL,
revoked_at timestamptz,
CONSTRAINT sessions_expiry_after_create CHECK (expires_at > created_at)
);
CREATE INDEX sessions_user_id_idx ON sessions (user_id);
CREATE INDEX sessions_expires_at_idx ON sessions (expires_at); -- для периодической очистки истёкших
CREATE TABLE chats (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
title text NOT NULL CHECK (char_length(title) BETWEEN 1 AND 100),
created_by uuid NOT NULL REFERENCES users (id),
created_at timestamptz NOT NULL DEFAULT clock_timestamp()
);
-- Список чатов сортируется по (created_at, id).
CREATE INDEX chats_created_at_id_idx ON chats (created_at, id);
CREATE TABLE chat_members (
chat_id uuid NOT NULL REFERENCES chats (id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES users (id),
joined_at timestamptz NOT NULL DEFAULT clock_timestamp(),
PRIMARY KEY (chat_id, user_id) -- один пользователь входит в чат один раз
);
-- "Чаты пользователя": поиск по user_id (PK начинается с chat_id и тут не помогает).
CREATE INDEX chat_members_user_id_idx ON chat_members (user_id, chat_id);
CREATE TABLE messages (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
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 clock_timestamp(),
-- Отправитель обязан быть участником этого чата: гарантирует сама БД.
CONSTRAINT messages_sender_is_member FOREIGN KEY (chat_id, sender_id)
REFERENCES chat_members (chat_id, user_id)
);
-- Индекс под keyset-пагинацию истории:
-- WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT n
-- Равенство по chat_id + диапазон по (created_at, id) читаются одним проходом индекса без сортировки.
CREATE INDEX messages_chat_created_id_idx ON messages (chat_id, created_at, id);
+20
View File
@@ -0,0 +1,20 @@
# Полный lock (pip freeze в python:3.12.12-slim-bookworm); устанавливается с --no-deps.
# Прямые зависимости: fastapi, uvicorn, asyncpg, argon2-cffi, redis (клиент совместим с Valkey).
annotated-types==0.8.0
anyio==4.15.1
argon2-cffi==23.1.0
argon2-cffi-bindings==26.1.0
asyncpg==0.30.0
cffi==2.1.1
click==8.5.0
fastapi==0.115.12
h11==0.16.0
idna==3.20
pycparser==3.12
pydantic==2.14.1
pydantic_core==2.50.1
redis==5.2.1
starlette==0.46.2
typing-inspection==0.4.4
typing_extensions==4.16.0
uvicorn==0.34.2
+10
View File
@@ -0,0 +1,10 @@
#!/bin/sh
# Заполняет БД синтетическими сообщениями (один раз) и сохраняет планы в evidence/explain.txt.
set -eu
cd "$(dirname "$0")/.."
mkdir -p evidence
{
echo "# EXPLAIN evidence, $(date -u +%Y-%m-%dT%H:%M:%SZ), commit $(git rev-parse --short HEAD 2>/dev/null || echo uncommitted)"
docker compose --env-file .env exec -T postgres psql -U app -d messenger -X -q -v ON_ERROR_STOP=1 -f - < scripts/explain.sql
} > evidence/explain.txt
echo 'saved evidence/explain.txt'
+78
View File
@@ -0,0 +1,78 @@
-- Обоснование индекса истории: синтетические данные + EXPLAIN (ANALYZE, BUFFERS) реальных запросов API.
-- Seed идемпотентен (маркер — пользователь bench_owner). Пароль бенч-пользователей невалиден: войти нельзя.
\set ON_ERROR_STOP 1
\pset pager off
DO $$
DECLARE
owner uuid; peer uuid; big uuid; small uuid;
BEGIN
IF EXISTS (SELECT 1 FROM users WHERE username = 'bench_owner') THEN
RETURN;
END IF;
INSERT INTO users (username, display_name, password_hash) VALUES ('bench_owner', 'Bench', '!') RETURNING id INTO owner;
INSERT INTO users (username, display_name, password_hash) VALUES ('bench_peer', 'Bench', '!') RETURNING id INTO peer;
-- Один большой чат: 20 000 сообщений.
INSERT INTO chats (title, created_by) VALUES ('bench big', owner) RETURNING id INTO big;
INSERT INTO chat_members (chat_id, user_id) VALUES (big, owner), (big, peer);
INSERT INTO messages (chat_id, sender_id, text, created_at)
SELECT big, CASE WHEN n % 2 = 0 THEN owner ELSE peer END, 'bench message ' || n,
timestamptz '2026-01-01 00:00:00+00' + n * interval '1 second'
FROM generate_series(1, 20000) AS n;
-- 30 чатов по 1 000 сообщений — "шум" других чатов в той же таблице.
FOR i IN 1..30 LOOP
INSERT INTO chats (title, created_by) VALUES ('bench small ' || i, owner) RETURNING id INTO small;
INSERT INTO chat_members (chat_id, user_id) VALUES (small, owner);
INSERT INTO messages (chat_id, sender_id, text, created_at)
SELECT small, owner, 'noise ' || n, timestamptz '2026-01-01 00:00:00+00' + n * interval '1 second'
FROM generate_series(1, 1000) AS n;
END LOOP;
END $$;
ANALYZE users, chats, chat_members, messages;
SELECT id AS big_chat FROM chats WHERE title = 'bench big' \gset
\echo '== Объём данных'
SELECT (SELECT count(*) FROM messages) AS total_messages,
(SELECT count(*) FROM messages WHERE chat_id = :'big_chat') AS big_chat_messages,
pg_size_pretty(pg_relation_size('messages')) AS table_size,
pg_size_pretty(pg_relation_size('messages_chat_created_id_idx')) AS index_size;
-- Курсор "из середины": последняя строка 300-й страницы по 50.
SELECT created_at AS cur_t, id AS cur_i FROM messages WHERE chat_id = :'big_chat'
ORDER BY created_at, id OFFSET 14999 LIMIT 1 \gset
\echo '== 1. Первая страница (запрос API без cursor, limit=50 -> LIMIT 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 '== 2. Страница 301 через keyset cursor (запрос API с cursor)'
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_t'::timestamptz, :'cur_i'::uuid)
ORDER BY created_at, id LIMIT 51;
\echo '== 3. Для сравнения: та же страница через OFFSET (НЕ используется в API)'
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 15000 LIMIT 51;
\echo '== 4. Для сравнения: keyset-запрос без индекса (DROP INDEX внутри транзакции, затем ROLLBACK)'
BEGIN;
DROP INDEX messages_chat_created_id_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_t'::timestamptz, :'cur_i'::uuid)
ORDER BY created_at, id LIMIT 51;
ROLLBACK;
\echo '== 5. Список чатов пользователя (запрос API GET /chats, limit=50)'
SELECT id AS owner_id FROM users WHERE username = 'bench_owner' \gset
EXPLAIN (ANALYZE, BUFFERS, COSTS OFF)
SELECT 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) AS member_ids
FROM chats c JOIN chat_members m ON m.chat_id = c.id AND m.user_id = :'owner_id'
ORDER BY c.created_at, c.id LIMIT 51;
+36
View File
@@ -0,0 +1,36 @@
#!/bin/sh
# Создаёт локальные секреты в ./secrets (каталог в .gitignore). Повторный запуск ничего не перезаписывает.
set -eu
cd "$(dirname "$0")/.."
# Каталог закрыт для других пользователей хоста; сами файлы 0644, т.к. compose монтирует их
# в контейнеры с правами хоста, а процессы там работают под непривилегированными uid.
umask 022
mkdir -p secrets
chmod 700 secrets
random_hex() { od -An -tx1 -N24 /dev/urandom | tr -d ' \n'; }
if [ ! -f secrets/postgres_password ]; then
pg=$(random_hex)
printf '%s' "$pg" > secrets/postgres_password
printf 'postgresql://app:%s@postgres:5432/messenger' "$pg" > secrets/database_url
echo 'created secrets/postgres_password, secrets/database_url'
fi
if [ ! -f secrets/valkey.conf ]; then
vk=$(random_hex)
# Valkey — только кэш сессий: persistence выключена намеренно, источник истины — PostgreSQL.
cat > secrets/valkey.conf <<EOF
requirepass $vk
save ""
appendonly no
maxmemory 64mb
maxmemory-policy volatile-lru
EOF
printf 'redis://:%s@valkey:6379/0' "$vk" > secrets/cache_url
echo 'created secrets/valkey.conf, secrets/cache_url'
fi
if [ ! -f .env ]; then
cp .env.example .env
echo 'created .env from .env.example'
fi
echo 'secrets ready (values are not printed)'
+14
View File
@@ -0,0 +1,14 @@
#!/bin/sh
# Перезапуск API и ВСЕХ используемых хранилищ (PostgreSQL, Valkey) с сохранением volumes.
# Не выполняет down -v, FLUSHALL и повторный seed. Готовность API ожидает сам тест.
set -eu
cd "$(dirname "$0")/.."
compose() { docker compose --env-file .env "$@"; }
started_at() { docker inspect -f '{{.Name}} {{.State.StartedAt}}' $(compose ps -q api postgres valkey); }
echo 'before:'; started_at
compose stop api # сначала останавливаем клиента хранилищ
compose restart postgres valkey # обычный restart контейнеров: volume pgdata остаётся
compose start api
echo 'after:'; started_at
+11
View File
@@ -0,0 +1,11 @@
#!/bin/sh
# Собственные проверки уровня 4. Запускать на хосте (Linux/macOS/Git Bash) из корня репозитория.
# Поднимает api-ttl (SESSION_TTL_SECONDS=2), запускает student-tests в контейнере tester, гасит api-ttl.
set -eu
cd "$(dirname "$0")/.."
compose() { docker compose --env-file .env "$@"; }
compose --profile test up -d --wait api-ttl
status=0
MSYS_NO_PATHCONV=1 compose --profile tools run --rm tester python student-tests/test_grade4.py || status=$?
compose --profile test stop api-ttl
exit $status
+255
View File
@@ -0,0 +1,255 @@
#!/usr/bin/env python3
"""Собственные проверки уровня 4. Запуск: sh scripts/test-grade4.sh (внутри сервиса tester).
Требуют запущенный стенд и доступ к docker (останавливают/ставят на паузу valkey и postgres,
затем возвращают их). Используют только синтетические данные.
"""
import base64
import hashlib
import os
import subprocess
import sys
import threading
import time
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'tests'))
from client import Client, Failure, check # noqa: E402
BASE_URL = os.environ.get('BASE_URL', 'http://localhost:8080')
TTL_BASE_URL = os.environ.get('TTL_BASE_URL', 'http://localhost:8081')
VALKEY_CLI = 'valkey-cli --no-auth-warning -a "$(sed -n "s/^requirepass //p" /run/secrets/valkey_conf)" '
def compose(*args: str, capture: bool = False) -> str:
result = subprocess.run(['docker', 'compose', '--env-file', str(ROOT / '.env'), *args],
cwd=ROOT, check=True, text=True,
stdout=subprocess.PIPE if capture else subprocess.DEVNULL,
stderr=subprocess.DEVNULL)
return (result.stdout or '').strip()
def sql(query: str) -> str:
return compose('exec', '-T', 'postgres', 'psql', '-U', 'app', '-d', 'messenger', '-tAc', query, capture=True)
def valkey(command: str) -> str:
return compose('exec', '-T', 'valkey', 'sh', '-c', VALKEY_CLI + command, capture=True)
def basic(username: str, password: str) -> dict:
return {'Authorization': 'Basic ' + base64.b64encode(f'{username}:{password}'.encode()).decode()}
def wait_ready(c: Client, seconds: float = 60) -> None:
deadline = time.monotonic() + seconds
while True:
try:
c.call('GET', '/health/ready', schema='Health')
return
except Failure:
check(time.monotonic() < deadline, 'API did not become ready')
time.sleep(0.5)
def wait_healthy(service: str, seconds: float = 60) -> None:
deadline = time.monotonic() + seconds
container = compose('ps', '-q', service, capture=True)
while subprocess.run(['docker', 'inspect', '-f', '{{.State.Health.Status}}', container],
text=True, capture_output=True).stdout.strip() != 'healthy':
check(time.monotonic() < deadline, service + ' did not become healthy')
time.sleep(0.5)
def cache_key(actor: dict) -> str:
return 'session:' + hashlib.sha256(actor['token'].encode()).hexdigest()
def wait_cache_used(c: Client, actor: dict, seconds: float = 75) -> None:
"""После недавнего сбоя Valkey API законно не доверяет кэшу SESSION_CACHE_TTL_SECONDS — ждём конца окна."""
deadline = time.monotonic() + seconds
while True:
c.call('GET', '/api/v1/users/me', actor=actor, schema='User')
if valkey('EXISTS ' + cache_key(actor)) == '1':
return
check(time.monotonic() < deadline, 'session was never cached in Valkey')
time.sleep(2)
def bearer(token: str) -> dict:
return {'Authorization': 'Bearer ' + token}
# ---------------------------------------------------------------- тесты
def test_wrong_password(c: Client):
alice = c.user('wrongpw')
username = alice['registration']['username']
wrong = c.call('POST', '/api/v1/auth/sessions', 401, headers=basic(username, 'definitely-wrong-password'))
unknown = c.call('POST', '/api/v1/auth/sessions', 401, headers=basic('no_such_' + uuid.uuid4().hex[:8], 'whatever-password-123'))
# Одинаковый ответ: по нему нельзя узнать, существует ли username.
check(wrong['json']['error']['message'] == unknown['json']['error']['message'], 'different 401 for unknown user')
check(wrong['headers']['WWW-Authenticate'] == 'Basic realm="messenger", charset="UTF-8"', 'wrong Basic challenge')
c.call('POST', '/api/v1/auth/sessions', 401, headers={'Authorization': 'Basic !!!not-base64'})
c.call('POST', '/api/v1/auth/sessions', 401, headers=bearer(alice['token'])) # Bearer на входе не принимается
def test_logout(c: Client):
alice = c.user('logout')
c.call('GET', '/api/v1/users/me', actor=alice, schema='User')
c.call('DELETE', '/api/v1/auth/sessions/current', 204, actor=alice)
r = c.call('GET', '/api/v1/users/me', 401, actor=alice)
check(r['headers']['WWW-Authenticate'] == 'Bearer realm="messenger"', 'wrong Bearer challenge')
c.call('DELETE', '/api/v1/auth/sessions/current', 401, actor=alice)
revoked = sql("SELECT count(*) FROM sessions s JOIN users u ON u.id = s.user_id "
f"WHERE u.username = '{alice['registration']['username']}' AND s.revoked_at IS NOT NULL")
check(revoked == '1', 'revocation not recorded in PostgreSQL')
def test_short_ttl(_c: Client):
# Отдельная реплика api-ttl с SESSION_TTL_SECONDS=2, общая БД и кэш.
c = Client(TTL_BASE_URL)
wait_ready(c)
alice = c.user('ttl')
c.call('GET', '/api/v1/users/me', actor=alice, schema='User')
time.sleep(3)
c.call('GET', '/api/v1/users/me', 401, actor=alice)
def test_username_race(c: Client):
username = 'race_' + uuid.uuid4().hex[:12]
body = {'username': username, 'display_name': 'Гонка', 'password': 'Race-password-' + uuid.uuid4().hex}
statuses, barrier = [], threading.Barrier(16)
def register():
barrier.wait()
statuses.append(Client(BASE_URL, timeout=30).call('POST', '/api/v1/users', [201, 409], body=body)['status'])
threads = [threading.Thread(target=register) for _ in range(16)]
for t in threads:
t.start()
for t in threads:
t.join()
check(sorted(statuses) == [201] + [409] * 15, f'race result {sorted(statuses)}')
check(sql(f"SELECT count(*) FROM users WHERE username = '{username}'") == '1', 'duplicate username row')
def test_chat_rollback(c: Client):
alice = c.user('rollback')
before = sql('SELECT (SELECT count(*) FROM chats) || \' \' || (SELECT count(*) FROM chat_members)')
# Второй участник не существует: INSERT chats уже выполнен, INSERT chat_members вставит 1 из 2 -> ROLLBACK.
c.call('POST', '/api/v1/chats', 400, actor=alice,
body={'title': 'Откат', 'member_ids': [alice['id'], str(uuid.uuid4())]})
after = sql('SELECT (SELECT count(*) FROM chats) || \' \' || (SELECT count(*) FROM chat_members)')
check(before == after, f'partial chat left after failure: {before} -> {after}')
listed = c.call('GET', '/api/v1/chats', actor=alice, schema='ChatPage')['json']
check(listed['items'] == [], 'failed chat is visible')
def test_cursor_rules(c: Client):
alice, bob, _eve, chat = c.bootstrap()
other = c.call('POST', '/api/v1/chats', 201, actor=alice, body={'title': 'Другой', 'member_ids': [alice['id']]},
schema='Chat')['json']
for i in range(3):
c.message(alice, chat, f'm{i}')
c.message(alice, other, f'o{i}')
page = c.call('GET', f'/api/v1/chats/{chat["id"]}/messages?limit=1', actor=alice, schema='MessagePage')['json']
from urllib.parse import quote
cursor = quote(page['next_cursor'], safe='')
c.call('GET', f'/api/v1/chats/{other["id"]}/messages?cursor={cursor}', 400, actor=alice) # курсор чужого чата
c.call('GET', f'/api/v1/chats/{chat["id"]}/messages?cursor=garbage', 400, actor=alice)
c.call('GET', f'/api/v1/chats/{chat["id"]}/messages?limit=101', 400, actor=alice)
c.call('POST', '/api/v1/chats', 400, actor=alice, body={'title': 'x', 'member_ids': [alice['id']], 'extra': 1})
c.call('POST', f'/api/v1/chats/{chat["id"]}/messages', 400, actor=bob, body={'text': 'x', 'sender_id': alice['id']})
def test_valkey_cache_role(c: Client):
alice = c.user('cache')
wait_cache_used(c, alice)
ttl = int(valkey('TTL ' + cache_key(alice)))
check(0 < ttl <= 60, f'unexpected cache TTL {ttl}')
valkey('FLUSHALL') # потеря всего кэша
c.call('GET', '/api/v1/users/me', actor=alice, schema='User') # источник истины — PostgreSQL
check(valkey('EXISTS ' + cache_key(alice)) == '1', 'cache was not refilled on miss')
def test_valkey_down(c: Client):
alice = c.user('vkdown')
try:
compose('stop', 'valkey')
c.call('GET', '/api/v1/users/me', actor=alice, schema='User') # обход кэша через PostgreSQL
c.call('GET', '/api/v1/users/me', 401, headers=bearer('A' * 43)) # неизвестный токен — не доверяем
c.call('GET', '/api/v1/users/me', 401) # аноним — 401
bob = c.user('vkdown_login') # вход работает без кэша
c.call('GET', '/health/ready', schema='Health') # Valkey не критичен
c.call('DELETE', '/api/v1/auth/sessions/current', 204, actor=bob)
c.call('GET', '/api/v1/users/me', 401, actor=bob)
finally:
compose('start', 'valkey')
wait_healthy('valkey')
def test_revoke_during_cache_partition(c: Client):
# Худший случай инвалидации: logout во время разрыва API <-> Valkey, DEL потерян, а копия отозванной
# сессии в Valkey пережила разрыв. Окно недоверия к кэшу (SESSION_CACHE_TTL_SECONDS после ошибки)
# не даёт её использовать. TCP может доставить DEL повторной передачей после восстановления сети,
# поэтому потерю DEL моделируем явно: возвращаем сохранённую до разрыва копию записи.
alice = c.user('partition')
wait_cache_used(c, alice)
key = cache_key(alice)
stale_value = valkey('GET ' + key)
container = compose('ps', '-q', 'valkey', capture=True)
network = 'mtusi-lab2_default'
subprocess.run(['docker', 'network', 'disconnect', network, container], check=True)
try:
c.call('DELETE', '/api/v1/auth/sessions/current', 204, actor=alice) # COMMIT в PostgreSQL прошёл
finally:
subprocess.run(['docker', 'network', 'connect', '--alias', 'valkey', network, container], check=True)
valkey(f"SET {key} '{stale_value}' EX 60")
c.call('GET', '/api/v1/users/me', 401, actor=alice)
def test_postgres_down(c: Client):
alice = c.user('pgdown')
c.call('GET', '/api/v1/users/me', actor=alice, schema='User')
try:
compose('stop', 'postgres')
c.call('GET', '/health/live', schema='Health')
c.call('GET', '/health/ready', 503)
r = c.call('GET', '/api/v1/users/me', 503, actor=alice) # ограниченная ошибка, не 500/200
check(r['json']['error']['code'] == 'unavailable', 'expected unavailable')
c.call('GET', '/api/v1/users/me', 503, headers=bearer('B' * 43)) # неизвестный токен не проходит
c.call('GET', '/api/v1/chats', 401) # аноним не пропускается
c.call('POST', '/api/v1/users', 503, body={'username': 'pg_' + uuid.uuid4().hex[:8],
'display_name': 'x', 'password': 'Password-123456'})
finally:
compose('start', 'postgres')
wait_ready(c)
c.call('GET', '/api/v1/users/me', actor=alice, schema='User') # та же сессия жива после рестарта БД
TESTS = [test_wrong_password, test_logout, test_short_ttl, test_username_race, test_chat_rollback,
test_cursor_rules, test_valkey_cache_role, test_revoke_during_cache_partition, test_valkey_down,
test_postgres_down]
def main() -> int:
c = Client(BASE_URL)
wait_ready(c)
failed = 0
for test in TESTS:
started = time.monotonic()
try:
test(c)
print(f'PASS {test.__name__} ({time.monotonic() - started:.1f}s)')
except (Failure, subprocess.CalledProcessError, OSError) as exc:
failed += 1
print(f'FAIL {test.__name__}: {exc}')
print(f'{len(TESTS) - failed}/{len(TESTS)} passed')
return 1 if failed else 0
if __name__ == '__main__':
sys.exit(main())
+4
View File
@@ -0,0 +1,4 @@
# Служебный образ для запуска make check / make test / restart.sh из Linux на любой ОС хоста.
FROM python:3.12.12-alpine3.22
RUN apk add --no-cache make docker-cli docker-cli-compose
WORKDIR /work