Files
mtusi2026lab2/REPORT.md
T

146 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 2
- Автор, группа: Авзалов Артур Марсович, БПИ2301
- Целевая оценка: **4** (трек 5 не заявлен)
- Коммит и MR: идентификатор коммита и ссылка доступны в истории соответствующего merge request в Gitea
- Дата локальной проверки: **23 октября 2026 года**, Windows PowerShell + Docker Desktop
- Источники: FastAPI, Pydantic, PostgreSQL/psycopg, Argon2id (argon2-cffi), Redis, Docker Compose. ChatGPT использовался для помощи в реализации приложения, тестовых скриптов и документации; проверки ниже выполнены локально студентом.
> **Статус доказательств (23.10.2026).** На Windows PowerShell + Docker Desktop подтверждены успешная сборка и `healthy` для API, PostgreSQL и Redis; `make check` и `make test`; public smoke после миграции `002`; дополнительные негативные тесты; защита от повреждённой Redis-сессии; persistence после перезапуска всех трёх сервисов; rollback; SQL EXPLAIN на 10 000 сообщений; TTL=2 с последующим возвратом к 3600; отказы Redis/PostgreSQL с восстановлением. Повторный запуск миграций показал `Migrations up to date`; контейнер API работает от `app` (UID 999); финальный smoke после отказов повторно прошёл. Результаты приведены по реальным выводам, полученным на машине студента. Linux/WSL persistence и чистый запуск на другой машине отдельно не проверялись.
## Запуск из чистого clone
Предпосылки: Docker Desktop с Compose v2, Python 3.9+ (для запуска тестов), `make` (либо прямые вызовы `python tests/...`). Все порты внутренних сервисов закрыты с хоста; только API слушает `127.0.0.1:8080`. Синтетические credentials предназначены для изолированного локального стенда, HTTP Basic по сети вне localhost недопустим без TLS.
Windows PowerShell:
```powershell
Copy-Item .env.example .env
# Открой .env локально и поставь случайный пароль без URI-спецсимволов.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
python tests/smoke.py
python tests/extra.py
python tests/redis_corruption.py
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd
python tests/dependency.py
# дополнительно:
python scripts/check_contract.py
docker compose --env-file .env run --rm migrate
docker compose --env-file .env exec -T api id
```
Linux/WSL:
```sh
cp .env.example .env
# Установить локальный пароль в .env (не коммитить)
docker compose --env-file .env up -d --build
make check
make test
make test-own
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-dependencies
```
Применение миграций происходит однократным Compose-сервисом `migrate` **до запуска API**. Для отдельной проверки повторного запуска: `docker compose --env-file .env run --rm migrate` (второй запуск не должен ничего изменять). Проверить логи миграций: `docker compose --env-file .env logs migrate`.
Остановка без потери данных: `docker compose --env-file .env down` (без `-v`). Намеренно **полностью удалить** учебные данные: `docker compose --env-file .env down -v` (не запускать при persistence-проверке!). В Git не попадут `.env` и named volumes.
## Архитектура и решения
```text
Client (localhost:8080) -> FastAPI (1 worker, no mutable business state)
|-> PostgreSQL 16: users, chats, chat_members, messages
`-> Redis 7.4: session:<SHA256(token)> -> user UUID (TTL + AOF)
```
Образ API: `python:3.12.12-slim-bookworm`, запуск от `app` (non-root); версии зависимостей зафиксированы в `requirements.txt`. PostgreSQL хранит **истину по бизнес-данным**; Redis — **единственное хранилище действующих серверных сессий** (нет локальной памяти процесса). Токен генерируется `secrets.token_urlsafe(32)` (256 бит энтропии); ключ Redis использует SHA-256 от токена, клиенту возвращается только исходное случайное значение. `EX` устанавливает TTL, `DEL` отзывает сессию. AOF с `appendfsync always` сохраняет записи на диск; named volume хранит их при рестарте. TTL при рестарте не продлевается. `FLUSHDB` сотрёт сессии — прежние токены станут недействительными; данные чатов в PostgreSQL сохранятся.
Пароли хранятся только как Argon2id hash с солью в PostgreSQL (`time_cost=2`, `memory_cost=19456` KiB, `parallelism=1`; библиотека `argon2-cffi`). POST `/api/v1/auth/sessions` принимает только Basic и не использует JSON body; остальные endpoint принимают только `Authorization: Bearer`. Заголовок `X-User-Id` больше не аутентифицирует. Доступ к конкретному чату дополнительно проверяется по `chat_members`; посторонний получает 404. HTTP вне локальной сети не используется.
В `db/migrations/001_initial.sql`: PK/FK, UNIQUE(username), UNIQUE(chat_id, user_id), позиция участников и B-tree индекс `idx_messages_chat_history(chat_id, created_at, id)`. Создание чата + участников выполняется в одной транзакции. При ошибке вставок все изменения откатываются; гонка по username отсекается ограничением UNIQUE в PostgreSQL, а не проверкой в памяти Python.
В `db/migrations/002_utf8_binary_strings.sql` пользовательские `display_name`, `chats.title` и `messages.text` конвертируются без потери данных из varchar в `bytea` (сырые UTF-8 байты): PostgreSQL text/varchar не принимает U+0000, хотя семантика API допускает этот символ. Приложение проверяет максимальную длину в **Unicode code points** и UTF-8 валидность до `.encode('utf-8')`; при чтении декодирует bytes. В БД есть ограничение на длину в байтах, а проверка непустого/непробельного значения выполняется на уровне API. Это позволяет хранить `A\u0000B` без 503 и сохранить все существующие записи при миграции.
Чтение сообщений — keyset по `(created_at,id)`, без загрузки всей истории в Python, с `LIMIT limit+1`. Последняя запись страницы превращается в cursor; при продолжении проверяется, что запись существует и принадлежит текущему чату. При изменении истории в ходе обхода snapshot между HTTP-запросами не гарантирован. Для составного ключа времени и UUID `id` обеспечивает определённый порядок даже при совпавших метках времени.
Пул: psycopg_pool, `max_size=DB_POOL_MAX` (по умолчанию 8), ожидание получения соединения — 3 с, время установки БД соединения — 5 с, `statement_timeout` — 5 с, Redis socket/connect timeout — 2 с. При отказе критической БД/Redis — 503, `/health/live` остаётся 200, `/health/ready` становится 503. Неизвестная/отозванная/истёкшая сессия — 401; нельзя обходить недоступный Redis по X-User-Id. API не логирует тела сообщений, токены или пароли.
## Доказательства критериев (фактические прогоны на Windows)
| Критерий | Как проверяли | Наблюдение |
|----------------------------------------|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `make check` | `make check` | **PASS**: offline skeleton structure, local refs and Python syntax; application NOT tested |
| `make test` | `make test` | **PASS**: lab2 public API scenario; infrastructure and grading evidence remain separate |
| Compose / готовность | `docker compose --env-file .env up -d --build`, `docker compose --env-file .env ps` | API, PostgreSQL и Redis работают и `healthy`; API доступен только на `127.0.0.1:8080` |
| Public smoke после миграции `002` | `python tests/smoke.py` | **PASS**: `lab2 public API scenario; infrastructure and grading evidence remain separate.` |
| Дополнительные негативные тесты | `python tests/extra.py` | **PASS**: login body, пароль из пробелов, проверки JSON, U+0000, лимит входного массива, гонка username и др. |
| Повреждённое значение сессии | `python tests/redis_corruption.py` | **PASS**: испорченная запись отвергается `401` и удаляется |
| Persistence API + PostgreSQL + Redis | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd` | **PASS**: тот же Bearer-токен, подтверждённые сообщения и данные доступны после restart; hook завершился кодом 0. В отдельном запуске hook показал последовательную остановку API, Redis, PostgreSQL и их запуск без удаления volumes |
| Rollback | `docker compose --env-file .env exec -T api python scripts/rollback_check.py` | **PASS**: вставка чата и участников откатилась целиком после FK-ошибки |
| История 10 000 записей | `docker compose --env-file .env exec -T api python scripts/explain_history.py` | **PASS**: `Index Scan using idx_messages_chat_history`, `rows=50`, `Buffers: shared hit=5`, `Execution Time: 0.377 ms` |
| Session TTL | Временный `SESSION_TTL_SECONDS=2`, `python tests/expiry.py`, затем возвращено `3600` | **PASS**: токен после истечения получает `401`; `printenv` показал `2`, затем `3600` |
| Redis outage | `python tests/dependency.py` | **PASS**: защищённый API и readiness вернули `503`; после восстановления Redis сессия сохранилась |
| PostgreSQL outage | `python tests/dependency.py` | **PASS**: защищённый API и readiness вернули `503`; после восстановления PostgreSQL сессия сохранилась |
| Повторный запуск миграций | `docker compose --env-file .env run --rm migrate` | **PASS**: после применения `002` повторный отдельный запуск вывел `Migrations up to date`; повторных изменений нет |
| Non-root непосредственно в контейнере | `docker compose --env-file .env exec -T api id` | **PASS**: `uid=999(app) gid=999(app) groups=999(app)` |
| Последний smoke после имитации отказов | `python tests/smoke.py` | **PASS**: `lab2 public API scenario; infrastructure and grading evidence remain separate.` |
**Примечание к негативному тесту на 101 участника.** Схема `CreateChat.member_ids` содержит `max_length=100`, поэтому API отклоняет массив длины 101. Текущий `extra.py` использует 100 случайных несуществующих UUID плюс вызывающего, поэтому один этот HTTP-тест не изолирует причину `400`: такое же значение могло бы возникнуть из-за неизвестных пользователей. Это отдельно проверено ревизией схемы; при необходимости добавляется тест со 101 заранее созданным реальным пользователем.
### Короткий TTL (отдельный запуск)
Windows PowerShell **после обычных smoke/persistence**:
```powershell
$env:SESSION_TTL_SECONDS = '2'
docker compose --env-file .env up -d --no-deps --force-recreate api
python tests/expiry.py
Remove-Item Env:SESSION_TTL_SECONDS
docker compose --env-file .env up -d --no-deps --force-recreate api
```
Обоснование: переcоздание только API не удаляет PostgreSQL и Redis volumes. Тест создаёт нового пользователя, токен, спит 3.1 секунды и убеждается, что токен получил 401. После восстановления TTL=3600 повторить smoke. Для PowerShell используйте `python` (в старом skeleton `Makefile` был `python3`).
### SQL EXPLAIN (фактический вывод 23.10.2026)
Отдельная тестовая история: **10 000 сообщений**, chat_id `d94197ba-c1a1-4aa8-af1a-fd67c9138c1e`. `EXPLAIN (ANALYZE, BUFFERS)` для страницы `LIMIT 50` с keyset-условием:
```text
Limit (cost=0.29..5.30 rows=50 width=70) (actual time=0.032..0.067 rows=50 loops=1)
Buffers: shared hit=5
-> Index Scan using idx_messages_chat_history on messages (cost=0.29..501.83 rows=4999 width=70) (actual time=0.030..0.056 rows=50 loops=1)
Index Cond: ((chat_id = 'd94197ba-c1a1-4aa8-af1a-fd67c9138c1e'::uuid) AND (ROW(created_at, id) > ROW('2026-10-23 14:58:41.99321+00'::timestamp with time zone, '8da12be9-184e-42fb-b175-469e45109f3e'::uuid)))
Buffers: shared hit=5
Planning:
Buffers: shared hit=12
Planning Time: 2.458 ms
Execution Time: 0.377 ms
```
Индекс `idx_messages_chat_history(chat_id, created_at, id)` выбран планировщиком. Для конкретного чата применяется условие `(created_at, id) > (cursor_created_at, cursor_id)`; PostgreSQL читает следующую порцию истории по индексу без полного прохода с `OFFSET`. `shared hit=5` означает обращения к страницам, оказавшимся в буферном кэше. `0.377 ms` — время **серверного SQL**, а не end-to-end HTTP latency; не является гарантией под конкурентной нагрузкой или холодным кэшем. Версия PostgreSQL: образ `postgres:16.10-bookworm`; CPU/RAM-профиль хоста в ходе измерения не зафиксирован. Тестовый fixture не очищен автоматически.
## Эксперименты и отказы (23.10.2026)
| Воздействие | Ожидаем | Наблюдали |
|-------------------------------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------|
| Restart API+PG+Redis без удаления volumes | Сохранены пользователи, чаты, сообщения и действующий токен | **PASS**; hook `Exit code: 0`, persistence client подтвердил прежний Bearer |
| Logout | Старый токен далее получает 401 | **PASS** в `tests/extra.py` |
| TTL=2 | Токен после 3.1 с получает 401 | **PASS**, переменная окружения затем восстановлена до 3600 |
| Stop Redis | Readiness и защищённый API 503, после запуска токен работает | **PASS** |
| Stop PostgreSQL | Readiness и защищённый API 503, после запуска токен работает | **PASS** |
| Конкурентная регистрация одного username | 1×201, 9×409 | **PASS** в `tests/extra.py` (assertion на точные количества) |
| Ошибка FK посреди транзакции | Частично созданного чата в БД нет | **PASS**, `rollback_check.py` |
| Повреждение своей записи сессии в Redis | 401, испорченный ключ удалён | **PASS**, `redis_corruption.py` |
## Ограничения и следующие шаги
- Один API процесс (нет LB/реплик, это lab3). PostgreSQL и Redis — single points of failure, HA не заявлен.
- Redis недоступен — защищённые запросы возвращают 503; это корректный fail-closed выбор для сессий. `logout` при отказе Redis **не возвращает 204**: отозвать токен нельзя, API возвращает 503. Положительного кэша поверх PostgreSQL-сессий нет; Redis — единственный источник сессий. Некорректная строка вместо UUID сессии отклоняется 401 с удалением испорченного ключа.
- Нет TLS во внешней сети: тестовый стенд предназначен только для localhost и синтетических паролей.
- Хранение данных гарантируется корректным завершением/рестартом volumes; против отказа диска, утраты volumes или разрушения FS этот стенд не защищает. PostgreSQL durability зависит от fsync/WAL, Redis — от AOF.
- Автоматические сценарии и инъекция отказов не доказывают все эксплуатационные свойства. Подтверждены non-root, повторная идемпотентная миграция и финальный smoke после отказов; Linux/WSL persistence и запуск из чистого clone в другой среде отдельно не проверялись.