forked from mtusi2026/mtusi2026lab2
146 lines
23 KiB
Markdown
146 lines
23 KiB
Markdown
# Отчёт — лабораторная 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 в другой среде отдельно не проверялись.
|