Files
mtusi2026lab2/REPORT.md
T

23 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Авзалов Артур Марсович, БПИ2301
  • Целевая оценка: 4 (трек 5 не заявлен)
  • Commit/MR: TODO после публикации
  • Дата локальной проверки: 23 октября 2026 года, Windows PowerShell + Docker Desktop
  • Источники: FastAPI, Pydantic, PostgreSQL/psycopg, Argon2id (argon2-cffi), Redis, Docker Compose. ChatGPT использовался для разработки начальной реализации, тестовых скриптов и документации; студент должен воспроизвести проверки и понимать решения.

Статус доказательств (23.10.2026). На машине студента подтверждены успешная сборка и healthy-статусы API, PostgreSQL, Redis, public smoke после миграции 002, дополнительные негативные тесты, защита от повреждённой Redis-сессии, persistence при фактическом перезапуске всех трёх сервисов, rollback, SQL EXPLAIN на 10 000 сообщений, TTL=2 и отказ Redis/PostgreSQL. После отказов все три сервиса вновь healthy. Все результаты ниже записаны по предоставленному выводу студента, а не по запуску в среде подготовки отчёта. Повторная идемпотентная миграция, non-root runtime и последний smoke после fault injection отдельно ещё не подтверждены.

Запуск из чистого clone

Предпосылки: Docker Desktop с Compose v2, Python 3.9+ (для запуска тестов), make (либо прямые вызовы python tests/...). Все порты внутренних сервисов закрыты с хоста; только API слушает 127.0.0.1:8080. Синтетические credentials предназначены для изолированного локального стенда, HTTP Basic по сети вне localhost недопустим без TLS.

Windows 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:

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.

Архитектура и решения

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)

Критерий Как проверяли Наблюдение
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 Миграция 002 применена, затем Migrations up to date; повторный отдельный запуск для идемпотентности — TODO
Non-root непосредственно в контейнере docker compose --env-file .env exec -T api id TODO (Dockerfile задаёт USER app, но фактический вывод команды ещё не приложен)
Последний smoke после имитации отказов python tests/smoke.py TODO (все контейнеры уже наблюдались healthy)

Примечание к негативному тесту на 101 участника. Схема CreateChat.member_ids содержит max_length=100, поэтому API отклоняет массив длины 101. Текущий extra.py использует 100 случайных несуществующих UUID плюс вызывающего, поэтому один этот HTTP-тест не изолирует причину 400: такое же значение могло бы возникнуть из-за неизвестных пользователей. Это отдельно проверено ревизией схемы; при необходимости добавляется тест со 101 заранее созданным реальным пользователем.

Короткий TTL (отдельный запуск)

Windows PowerShell после обычных smoke/persistence:

$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-условием:

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 после инъекций отказов.