chore: перенос решения lab2 (src, миграции, student-tests, Dockerfile, compose, lock) без изменений

Исходная точка lab3: код из solution/bvt2302-bodanyuk лабы 2, коммит ef44e48
(PR mtusi2026/mtusi2026lab2#42 принят). README, COURSE, contracts/ и tests/
преподавателя не тронуты; к Makefile дописан студенческий раздел lab2,
.env.example — версия lab2. Исследование трека 2 lab2 (bench/track2) не переносилось.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alexey Bodanyuk
2026-10-16 13:02:13 +03:00
co-authored by Claude Opus 5.5
parent 0ab3a341aa
commit 4f6cfda37a
42 changed files with 3702 additions and 3 deletions
+41
View File
@@ -0,0 +1,41 @@
# Модель данных lab2
Схема: [migrations/0001_init.sql](../migrations/0001_init.sql). Источник истины для пользователей, чатов, участников и сообщений — PostgreSQL 18. Для сессий источник истины — хранилище, выбранное через `SESSION_STORE`. По умолчанию это Valkey с AOF, его можно переключить на таблицу `sessions` в PostgreSQL.
## Таблицы и ограничения
| Таблица | Ключ | Ограничения | Зачем |
| --- | --- | --- | --- |
| `users` | `id uuid` | `UNIQUE (username)`, `CHECK` формата username, длина `display_name` | уникальность имени держит БД, а не код: гонку регистрации разрешает уникальный индекс |
| `chats` | `id uuid` | FK `created_by → users`, длина `title` | `last_message_at` — «часы» чата для упорядочивания сообщений |
| `chat_members` | `(chat_id, user_id)` | FK на `chats` и `users`, `UNIQUE (chat_id, position)` | `position` хранит порядок `member_ids`; `chat_created_at` — копия времени чата для keyset-списка чатов |
| `messages` | `id uuid` | FK `(chat_id, sender_id) → chat_members`, длина `text` | отправитель обязан быть участником — это гарантирует сама БД |
| `sessions` | `token_hash bytea` | FK `user_id → users`, длина хеша 32 байта | хранится SHA-256 токена; сам токен не хранится нигде |
| `schema_migrations` | `version` | checksum файла | какие миграции применены; изменённую задним числом миграцию мигратор не применит |
**Почему `bytea` для текста.** Контракт разрешает символ U+0000, а тип `text` в PostgreSQL не может содержать байт NUL (`DataError`). Поэтому `display_name`, `title` и `text` хранятся как байты UTF-8. Длину в code points проверяет API, а `CHECK` в байтах — страховка (1 code point ≤ 4 байта).
## Индексы и запросы
- `messages_chat_keyset (chat_id, created_at, id)`. Первая страница — `WHERE chat_id=$1 ORDER BY created_at, id LIMIT n`, следующая — `WHERE chat_id=$1 AND (created_at, id) > ($2, $3) ORDER BY ... LIMIT n`. Сравнение строк `(created_at, id) > (...)` попадает в `Index Cond`: поиск начинается прямо с позиции cursor и читает только `n+1` строк. Запросов два, а не один с `($2 IS NULL OR ...)`: иначе при generic plan условие cursor уходит в `Filter`, и поздняя страница сканирует всю историю чата до неё.
- `chat_members_user_keyset (user_id, chat_created_at, chat_id)` — список чатов пользователя тем же keyset-способом.
- `users_username_key` — вход по username и уникальность.
- `sessions_expires_at` — очистка истёкших сессий.
## Транзакционные границы
| Операция | Транзакция | Что гарантирует |
| --- | --- | --- |
| Регистрация | один `INSERT` | `UniqueViolation` → 409; ровно одна строка при гонке |
| Создание чата | `INSERT chats` → `INSERT chat_members` (все участники одним запросом) → `COMMIT` | неизвестный участник вызывает FK-ошибку **после** вставки чата; откат удаляет и чат, и частичное членство |
| Сообщение | проверка членства → `UPDATE chats SET last_message_at = greatest(clock_timestamp(), last_message_at + 1 мкс) RETURNING` → `INSERT messages` → `COMMIT` | строка чата заблокирована до конца транзакции, поэтому писатели одного чата идут по очереди. Время сообщений строго растёт **в порядке коммитов**: страница по cursor не пропустит сообщение, закоммиченное «задним числом» |
| Вход | `SELECT` пользователя, проверка Argon2id, запись сессии | неверный пароль ничего не пишет |
| Logout | `DELETE` сессии (или `DEL` в Valkey) | повтор с тем же токеном — 401 |
Чтение истории не требует snapshot между HTTP-запросами (так в контракте): новое сообщение появится на следующей странице. Список чатов сортируется по `chats.created_at = clock_timestamp()` без блокировки. Два чата, создаваемые одновременно, могут закоммититься не в порядке времени. Тогда у обхода, который уже начался, такой чат может оказаться «до» cursor; новый обход его увидит. Чаты создаются редко, поэтому мы не сериализуем их глобальным замком; это ограничение описано в REPORT.md.
## Сессии
- Токен: `secrets.token_urlsafe(32)` — 256 бит случайности, в ответе 43 символа. В хранилище лежит только SHA-256 токена. Для случайного 256-битного значения быстрого хеша достаточно, медленный KDF нужен только для низкоэнтропийных паролей.
- `SESSION_STORE=valkey` (по умолчанию): ключ `session:<sha256-hex>`, значение `{user_id, expires_at}`. Срок жизни задаётся абсолютным `PXAT expires_at`, поэтому рестарт его не продлевает. Включён `appendonly yes` + `appendfsync always`: подтверждённые вход и logout сохраняются до ответа клиенту. Valkey — **единственное** хранилище сессий, это не кэш над PostgreSQL. Поэтому нет второй копии, которая могла бы «оживить» отозванный токен после отказа. Если Valkey недоступен, проверить сессию нельзя: защищённые запросы и logout получают 503, анонимный доступ не открывается.
- `SESSION_STORE=postgres`: таблица `sessions`, проверка `expires_at > now()` в запросе.
+83
View File
@@ -0,0 +1,83 @@
# Шпаргалка к защите ЛР 2
Отчёт с доказательствами — [REPORT.md](../REPORT.md), модель данных — [DATA_MODEL.md](DATA_MODEL.md).
## Что изменилось по сравнению с lab1
| Было в lab1 | Стало в lab2 | Где |
| --- | --- | --- |
| словари в памяти (`store.py`) | PostgreSQL 18, данные переживают рестарт | [repo.py](../src/messenger/repo.py), [migrations/0001_init.sql](../migrations/0001_init.sql) |
| `X-User-Id` | вход по `Basic` → opaque `Bearer` с expiry, logout | [authhdr.py](../src/messenger/authhdr.py), [sessions.py](../src/messenger/sessions.py), [app.py](../src/messenger/app.py) |
| нет паролей | Argon2id (m=19 MiB, t=2, p=1) в отдельном потоке | [passwords.py](../src/messenger/passwords.py) |
| `threading.Lock` + свой счётчик времени | блокировка строки чата `UPDATE chats … RETURNING` в транзакции | `add_message` в repo.py |
| `bisect` по списку | индекс `(chat_id, created_at, id)` и row-comparison в `Index Cond` | `HISTORY_AFTER` в repo.py |
| один контейнер | `compose.yaml`: postgres, valkey, migrate, api; secrets-файлы; named volumes | [compose.yaml](../compose.yaml) |
Что осталось из lab1: формат ошибок и `X-Request-Id`, строгая валидация, cursor (теперь с проверкой диапазона времени), JSON-логи, graceful SIGTERM, healthcheck, Swagger на `/docs`.
## Путь запроса `GET /chats/{id}/messages?cursor=…` в lab2
1. `parse_bearer`: в заголовке ровно `Bearer <43 символа>`, иначе 401 с `WWW-Authenticate: Bearer`.
2. `sessions.user_id_for`: в Valkey ключ `session:<sha256(token)>`, проверка `expires_at`. Valkey недоступен — 503, нет ключа — 401.
3. `path_uuid` → 400; `ensure_member` (`SELECT 1 FROM chat_members …`) → 404 для чужого чата.
4. `cursor.decode` → `(время в мкс, id)`, привязка к чату → иначе 400.
5. `HISTORY_AFTER`: `WHERE chat_id=$1 AND (created_at, id) > ($2,$3) ORDER BY … LIMIT 51` — индекс начинает чтение прямо с cursor.
6. Каждая работа с БД — `db.run(...)`: отдельная задача, транзакция, дедлайн 3 с. Отказ или зависание БД → 503 ровно через дедлайн.
## Вопросы из README
**Что подтверждает COMMIT и какие гарантии зависят от настройки durability?**
COMMIT возвращается клиенту, когда запись транзакции в WAL сброшена на диск (`fsync=on`, `synchronous_commit=on`, это значения по умолчанию). Транзакция переживёт падение процесса PostgreSQL или ОС: при старте PostgreSQL проиграет WAL. От настроек зависит:
- `synchronous_commit=off` — ответ приходит раньше сброса, и последние ~0,6 с подтверждённых транзакций могут пропасть (база при этом останется целой);
- `fsync=off` — после сбоя возможна порча данных;
- кэш записи диска, который «врёт» о сбросе, ломает и то, и другое.
COMMIT на одном узле не защищает от потери самого диска или хоста: для этого нужны реплики (`synchronous_standby_names`) или резервные копии с архивом WAL (трек 2).
У Valkey свой аналог — `appendfsync`:
- у нас `always`: fsync до ответа, ничего не теряется;
- `everysec`: можно потерять до 1 с записей;
- `no`: когда сбросить на диск, решает ОС.
**Где хранятся сессии и что будет после flush/restart Redis (Valkey)?**
По умолчанию (`SESSION_STORE=valkey`) сессия существует **только** в Valkey: ключ `session:<sha256>`, значение `{user_id, expires_at}` и абсолютный срок `PXAT`.
- **Restart:** Valkey перечитывает AOF с volume, сессии на месте (тест `make test-persistence`). TTL не продлевается.
- **FLUSHALL** или потеря volume: все сессии исчезают, все пользователи получают 401 и входят заново. Отказ безопасный: доступ не выдаётся никому.
- **Valkey недоступен:** 503 на защищённые запросы и на logout. Анонимный доступ не открывается.
Почему не кэш над PostgreSQL: у одной копии нечему расходиться. У студентов с кэшем отозванный токен «оживал» после восстановления Redis, у нас такой ситуации быть не может (тест `test_logout_during_valkey_outage_is_never_lost`). Альтернатива `SESSION_STORE=postgres` хранит сессии в таблице `sessions`.
**Чем аутентификация отличается от доступа к конкретному чату?**
- **Аутентификация** — кто ты: действительная Bearer-сессия → `user_id`. Нет или недействительна → 401.
- **Авторизация доступа** — можно ли этому пользователю этот чат: есть ли строка в `chat_members`. Нет → 404, а не 403, чтобы не раскрывать существование чужого чата.
Сначала всегда аутентификация, потом доступ. Отправитель сообщения берётся из сессии, а БД сама проверяет `FOREIGN KEY (chat_id, sender_id) → chat_members`.
**Почему hash пароля и быстрый checksum имеют разные задачи?**
- **Checksum или быстрый хеш (SHA-256)** — контроль целостности и быстрый поиск. Он должен быть быстрым.
- **Хеш пароля** — защита низкоэнтропийного секрета на случай утечки базы. Он должен быть медленным, с солью и memory-hard (Argon2id), чтобы перебор словаря стоил дорого и не ускорялся на GPU.
Токен сессии — 256 бит случайности, перебрать его невозможно. Поэтому для токена хватает SHA-256: храним хеш, чтобы утечка базы не дала готовых токенов. Для пароля SHA-256 нельзя: миллиарды попыток в секунду на GPU.
## Частые ловушки (на чём преподаватель ловил других) и наш ответ
| Проверка преподавателя | У нас | Тест |
| --- | --- | --- |
| logout при упавшем Redis → после восстановления токен снова 200 | logout при упавшем Valkey = 503 (ничего не отозвано); после восстановления logout → 401, и после рестарта Valkey и API тоже 401 | `test_logout_during_valkey_outage_is_never_lost` |
| истёкшая сессия живёт в кэше | expiry проверяется при каждом чтении, ключ живёт до абсолютного `PXAT` | `test_short_ttl_expires[valkey/postgres]` |
| `docker pause postgres` → запрос висит 8+ с | клиентский дедлайн в отдельной задаче: 503 через 3,0 с | `test_postgres_failure[pause]` |
| БД упала → 401 вместо 503 | 503 `unavailable`, анонимный — 401 | `test_postgres_failure`, `test_postgres_session_store` |
| cursor в `Filter` при generic plan | два запроса без `IS NULL OR`, cursor в `Index Cond` | `test_explain.py`, `evidence/explain-history.txt` |
| `\u0000` → 500 | текст в `bytea`, NUL сохраняется | `test_unicode_limits_are_code_points_and_nul_is_stored` |
| пароль из пробелов, `Basic é` → 500 | 400 и 401 | `test_bad_password_on_registration_is_400`, `test_malformed_basic_is_401_not_500` |
| гонка регистрации считает любые ошибки за 409 | проверяются коды: ровно `[201] + [409]*7`, в БД 1 строка | `test_registration_race_exactly_one_201_and_seven_409` |
| rollback «до первого INSERT» | чат вставляется первым, FK участника падает после; `n_tup_ins` вырос, строк нет | `test_create_chat_rolls_back_after_the_chat_row_was_inserted` |
| `SESSION_TTL_SECONDS` не доходит до контейнера | compose передаёт его из `.env`, тест читает `printenv` внутри контейнера | `test_short_ttl_expires` |
| нет команды создания secrets | `python scripts/init_secrets.py` (идемпотентно) | раздел «Запуск из чистого clone» |
## Трек 2 — коротко
- **Гипотеза.** С индексом `(chat_id, created_at, id)` и keyset-запросом стоимость страницы не зависит от размера чата и позиции. С индексом только по `chat_id` нужна сортировка всего чата, с OFFSET — чтение всего префикса. Каждый индекс удорожает запись.
- **Методика.** Отдельный PostgreSQL (2 CPU / 2 GiB), 121 120 сообщений, чаты 60 000 / 15 000 / 2 000 / 80. pgbench с prepared statements; генератор нагрузки — в своём контейнере. 3 повтора. Плюс EXPLAIN для поздней страницы.
- **Backup.** `pg_dump -Fc` живой БД во время записи через API → новый контейнер и новый volume → `pg_restore` → сверка MD5 по каждому чату и по первым/последним сообщениям → наше же API на восстановленной БД читает чат после нового входа.
- **RPO и RTO.** `pg_dump` — снимок на момент старта. Всё подтверждённое после старта дампа в копию не попадает; это и есть граница потери данных (на практике — время с последнего дампа). RTO — время `pg_restore` с перестройкой индексов плюс переключение приложения. Чтобы уменьшить RPO до секунд, нужен архив WAL и PITR или реплика.
+134
View File
@@ -0,0 +1,134 @@
# Запуск на ноутбуке с Windows и сценарий защиты
Все команды — в **PowerShell**, из папки проекта. Внутри одного окна PowerShell переменные `$env:...` действуют до его закрытия.
## 1. Что установить один раз
| Программа | Зачем | Важно |
| --- | --- | --- |
| [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | ставить в путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\restart.cmd` запускает `restart.sh` |
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, API | backend WSL 2; в BIOS включена виртуализация; после установки перезагрузка |
| [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные тесты, свои тесты | галочка **Add python.exe to PATH**. Если `python` открывает Microsoft Store — отключить «Псевдонимы выполнения приложений» для python в настройках Windows |
Проверка:
```powershell
git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version
```
Docker Desktop должен быть **запущен** (кит в трее не мигает).
## 2. Развернуть проект (дома, заранее — нужен интернет)
```powershell
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab2 mtusi2026lab2
cd mtusi2026lab2
git checkout solution/bvt2302-bodanyuk
python scripts\init_secrets.py
Copy-Item .env.example .env
docker compose --env-file .env up -d --build --wait
```
Первый запуск скачивает образы (~700 МБ) и собирает API — 3–10 минут. Сделайте это **дома**: в аудитории сеть может быть медленной. Последняя команда завершается, когда все сервисы `healthy`.
Проверка в браузере: http://127.0.0.1:8080/health/ready → `{"status":"ok"}`, Swagger — http://127.0.0.1:8080/docs.
Окружение для своих тестов (один раз):
```powershell
python -m venv .venv
.venv\Scripts\python -m pip install --require-hashes --no-deps -r requirements.txt
.venv\Scripts\python -m pip install -r requirements-test.txt -r requirements-dev.txt
```
Активировать venv не нужно: везде вызывается `.venv\Scripts\python` напрямую, поэтому политика выполнения PowerShell не мешает.
## 3. Перед защитой (в аудитории)
```powershell
cd mtusi2026lab2
docker compose up -d --wait # если стенд был остановлен
$env:PYTHONUTF8 = "1" # публичные тесты читают UTF-8 JSON
python tests\smoke.py # PASS: lab2 public API scenario
```
## 4. Сценарий защиты из README — команды по шагам
**Шаг 1. Миграции к пустому volume, пользователи, вход, сообщение.**
```powershell
docker compose down -v # стереть учебные данные (volumes)
docker compose up -d --wait # postgres и valkey пустые -> migrate применяет схему
docker compose logs migrate # "0001_init: applied"
docker compose run --rm migrate # повтор: "already applied, skipped"
```
Дальше в Swagger (http://127.0.0.1:8080/docs):
1. `POST /api/v1/users` — создать двух пользователей (пароль 12+ символов).
2. **Authorize → basicAuth**: логин и пароль первого; `POST /api/v1/auth/sessions` — скопировать `token`.
3. **Authorize → bearerAuth**: вставить токен.
4. `POST /api/v1/chats` (в `member_ids` — оба id) → `POST /api/v1/chats/{chat_id}/messages` → `GET` истории.
**Шаги 2–3. Перезапуск API и хранилищ с сохранением volumes, тот же токен; logout → 401; короткий TTL.**
```powershell
python tests\resilience.py --mode persistence --action-script scripts\restart.cmd # PASS
docker compose ps # у api, postgres, valkey свежее время запуска
```
В Swagger тот же токен по-прежнему работает. `DELETE /api/v1/auth/sessions/current` → 204, затем любой запрос → 401.
Короткий TTL:
```powershell
$env:SESSION_TTL_SECONDS = "2"; docker compose up -d --wait api
docker compose exec api printenv SESSION_TTL_SECONDS # 2
# в Swagger: войти, сразу GET /users/me -> 200, через 3 секунды -> 401
Remove-Item Env:SESSION_TTL_SECONDS; docker compose up -d --wait api # вернуть 3600
```
**Шаг 4. Роль Valkey, план SQL, ошибка зависимости.**
```powershell
# Сессии лежат только в Valkey: ключи session:<sha256 токена>, самих токенов там нет
# (без двойных кавычек внутри: PowerShell 5.1 ломает их при передаче в docker)
docker compose exec valkey sh -c 'REDISCLI_AUTH=$(cat /run/secrets/valkey_password) valkey-cli --scan --pattern ''session:*'''
# План: поздняя страница по индексу (Index Cond) против IS NULL OR и OFFSET, 20 000 сообщений
.venv\Scripts\python scripts\explain_history.py
# Ошибка зависимости: с действующим токеном -> 503, без токена -> 401, после старта всё работает
docker compose stop valkey # или: docker compose pause postgres
# в Swagger: GET /users/me -> 503 unavailable; GET /health/ready -> 503
docker compose start valkey # или: docker compose unpause postgres
```
Всё то же автоматически, с восстановлением в `finally`, около 1 минуты:
```powershell
.venv\Scripts\python -m pytest student-tests\test_failures.py -v
```
**Трек 2 вживую.**
```powershell
.venv\Scripts\python bench\track2\backup_restore.py --repeats 1 # ~1 мин: dump во время записи -> restore в новый контейнер -> сверка
```
Скрипт печатает время дампа и восстановления, `reconciled: true` и сколько сообщений записано после снимка (RPO). Полный замер планов идёт ~25 минут, поэтому на защите показывайте готовые результаты: `evidence\track2\summary.md` и `evidence\track2\plans.png`. При желании можно запустить `.venv\Scripts\python bench\track2\index_sizes.py` (~2 мин).
**Все свои тесты** (~3,5 мин): `.venv\Scripts\python -m pytest student-tests -v`.
## 5. Если что-то пошло не так
| Симптом | Что сделать |
| --- | --- |
| `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту |
| `port is already allocated` на 8080 | в `.env` поставить `APP_PUBLISH_PORT=8081`; дальше тесты с `--base-url http://127.0.0.1:8081` (smoke и resilience), для pytest — `$env:BASE_URL="http://127.0.0.1:8081"` |
| `secrets/... not found` при `up` | не выполнен `python scripts\init_secrets.py` |
| `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` |
| `restart.cmd`: «не удаётся найти путь» | Git установлен не в `C:\Program Files\Git` — поправить путь в `scripts\restart.cmd` |
| api `unhealthy` после сна ноутбука | `docker compose restart` и подождать `docker compose ps` |
| нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные) → `docker compose up -d --wait` |
Остановить стенд после защиты: `docker compose down` (данные сохранятся) или `docker compose down -v` (данные удаляются).