Files
mtusi2026lab2/REPORT.md
T

22 KiB
Raw Blame History

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

  • Автор, группа: Соколова Полина БВТ2304
  • Целевая оценка: 4
  • Трек уровня 5: не выполняется
  • Commit/PR: добавить после публикации Проверки выполнены на локальном стенде; результаты сохранены в каталоге evidence/.

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

Требования и версии

Стенд разрабатывался и проверялся в Debian 12 под WSL 2.

Использованные версии:

  • Docker Engine: 20.10.24+dfsg1.
  • Docker Compose: v2.27.0.
  • Базовый образ приложения: python:3.12.10-slim-bookworm.
  • PostgreSQL: postgres:16.4-bookworm.
  • Redis: redis:7.2.5-bookworm.
  • Прямые зависимости Python закреплены в requirements.txt.
  • Для публичных и собственных тестов на стороне хоста нужен Python 3.9+.

Внешний адрес API: http://localhost:18081. Внутри контейнера приложение слушает 0.0.0.0:8080.

Порт 18081 выбран из-за занятых портов 8080 и 8081 в локальном окружении.

Подготовка и запуск

Команды выполняются из корня репозитория:

cp .env.example .env

В новом локальном .env необходимо заменить POSTGRES_PASSWORD=CHANGE_ME_LOCAL_ONLY отдельным учебным паролем. Файл .env не добавляется в Git.

После настройки:

docker compose --env-file .env config --quiet
docker compose --env-file .env build api
docker compose --env-file .env up -d --wait api redis
docker compose ps -a

curl -i http://localhost:18081/health/live
curl -i http://localhost:18081/health/ready

Compose запускает PostgreSQL, одноразовый сервис migrate и API. API зависит от готовности PostgreSQL и успешного завершения migrate. Redis запускается явно в приведённой команде.

Миграции находятся в migrations/. Программа app/migrate.py хранит применённые версии и контрольные суммы в schema_migrations.

Повторный запуск:

docker compose --env-file .env run --rm migrate

Для уже применённого файла выводится:

Already applied: 001_initial.sql
Migrations committed successfully

Повторная миграция не создаёт дубликаты таблиц и данных. Изменение применённого SQL-файла обнаруживается по контрольной сумме. Изменения схемы следует добавлять новой миграцией.

Проверки

make check

make test BASE_URL=http://localhost:18081

make test-persistence \
  BASE_URL=http://localhost:18081 \
  ACTION_SCRIPT=scripts/restart.sh

make test-lab2 BASE_URL=http://localhost:18081

make test-lab2 последовательно запускает:

  • make test-extra — шесть собственных проверок;
  • make test-faults — отказы зависимостей и короткий TTL.

Сценарий test-faults управляет локальным Compose-стендом. Его нельзя запускать параллельно с другими проверками или направлять на произвольный удалённый сервер.

Проверка индекса:

docker compose exec -T postgres \
  psql -X -U messenger -d messenger -v ON_ERROR_STOP=1 \
  < scripts/explain_history.sql

Перед этим должен пройти smoke или собственные тесты: SQL-сценарий использует одного существующего пользователя.

Каждый запуск SQL-сценария создаёт новый чат и 10 000 сообщений.

Остановка и удаление данных

Остановка без удаления данных:

docker compose --env-file .env stop

Удаление контейнеров и сети с сохранением именованных volumes:

docker compose --env-file .env down

Только для намеренного полного сброса учебных данных:

docker compose --env-file .env down --volumes

Последняя команда удаляет volumes PostgreSQL и Redis. Она не применяется в persistence-проверках.

Инструкция запуска подготовлена для нового окружения. Отдельный эксперимент запуска из чистого clone с новыми volumes на момент заполнения отчёта не выполнен.

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

Компоненты

Клиент
  |
  | HTTP, localhost:18081
  v
FastAPI
  |-- PostgreSQL: источник истины
  |-- Redis: кэш публичных данных пользователя

В PostgreSQL находятся:

  • users — пользователи и хеши паролей;
  • chats — чаты;
  • chat_members — участники;
  • messages — сообщения;
  • sessions — хеши токенов и сроки действия сессий;
  • schema_migrations — история применения миграций.

Приложение не хранит обязательное состояние в локальных словарях. Для PostgreSQL и Redis настроены отдельные именованные volumes.

Порты хранилищ не публикуются на хосте. API опубликован только на 127.0.0.1.

Изменения относительно лабораторной 1

Сохранены операции пользователей, чатов, сообщений и история.

Изменено:

  • in-memory хранилище заменено PostgreSQL;
  • при регистрации требуется password;
  • вход выполняется через Basic;
  • бизнес-запросы используют Bearer вместо X-User-Id;
  • добавлены expiry и logout;
  • добавлены Redis, миграции и проверки отказов;
  • пагинация выполняется SQL-запросом, без загрузки всей истории.

Аутентификация и сессии

Пароли хешируются библиотекой argon2-cffi с Argon2id. PasswordHasher использует параметры:

  • time_cost=3;
  • memory_cost=65536 KiB;
  • parallelism=4;
  • hash_len=32;
  • salt_len=16.

Basic credentials декодируются как UTF-8. Разделение username:password выполняется по первому двоеточию, поэтому двоеточия внутри пароля сохраняются.

Токен сессии генерируется secrets.token_urlsafe(32): используется 32 случайных байта. Клиент получает исходный токен, в PostgreSQL сохраняется SHA-256 токена.

SHA-256 применяется к случайным токенам и файлам миграций, но не заменяет password KDF.

Срок действия проверяется по времени PostgreSQL. Истёкшая строка sessions не даёт доступ, даже если физически ещё не удалена. Logout удаляет текущую сессию.

X-User-Id не используется для аутентификации. Сессии сохраняются в PostgreSQL и переживают проверенный рестарт.

Роль Redis

Redis содержит только публичные поля пользователя: id, username, display_name, created_at.

Политика:

  • источник истины — PostgreSQL;
  • TTL кэша по умолчанию — 60 секунд;
  • пароли, хеши паролей и токены не кэшируются;
  • действительность сессии проверяется в PostgreSQL до чтения кэша;
  • при отказе Redis профиль читается из PostgreSQL;
  • при отказе PostgreSQL кэш не заменяет проверку сессии;
  • изменение и удаление профиля отсутствуют в обязательном API, поэтому в текущем контракте используется истечение по TTL.

Для Redis включён AOF с appendfsync everysec. Сохранность сессий не зависит от Redis: они находятся в PostgreSQL.

Транзакции и ограничения

В БД определены первичные и внешние ключи, уникальность username и ограничения длины полей.

Составной внешний ключ messages(chat_id, sender_id) ссылается на chat_members(chat_id, user_id).

Создание чата и добавление всех участников выполняются в одной транзакции. Ошибка участника откатывает всю операцию.

При регистрации конкурентная уникальность обеспечивается ограничением users_username_unique. Конфликт username возвращается как HTTP 409.

Ответ об успешной записи формируется после выхода из транзакционного блока с успешным COMMIT.

Соединения и таймауты

Используется AsyncConnectionPool:

  • min_size=1;
  • max_size=5 на процесс API;
  • ожидание соединения — 3 секунды;
  • max_waiting=20;
  • connect_timeout=3 секунды;
  • statement_timeout=3000 ms;
  • lock_timeout=2000 ms;
  • idle_in_transaction_session_timeout=10000 ms.

Значения SQL передаются параметрами, а не конкатенацией пользовательского ввода.

Redis:

  • socket_connect_timeout=0.2 секунды;
  • socket_timeout=0.2 секунды;
  • max_connections=10.

Эти настройки не являются единой жёсткой границей времени любого HTTP-запроса. В сценарии отказов отдельно проверяется локальный бюджет запроса менее 10 секунд.

Пагинация и конкурентные вставки

История сортируется по (created_at, id). Курсор содержит эту пару и область запроса. Курсор другого чата отклоняется.

Запрашивается limit + 1 строка для определения next_cursor. Для неизменной истории продолжение использует строгое сравнение >, поэтому последняя строка предыдущей страницы не повторяется.

Между HTTP-запросами общий snapshot не поддерживается. При конкурентных вставках новая запись с ключом больше текущего курсора может попасть в последующие страницы. Запись с ключом не больше уже пройденного курсора может быть пропущена текущим обходом.

Время назначается сервером БД через clock_timestamp(). Часы не являются уникальным идентификатором или гарантией порядка COMMIT; для разрешения одинакового времени используется id.

Конфигурация

.env.example соответствует реализации:

Переменная Назначение
POSTGRES_PASSWORD Пароль PostgreSQL; передаётся приложению как PGPASSWORD
SESSION_TTL_SECONDS Срок действия новых сессий, по умолчанию 3600
USER_CACHE_TTL_SECONDS TTL кэша пользователя, по умолчанию 60

Адреса и имена сервисов заданы в compose.yaml. Реальные credentials и .env не включаются в репозиторий.

Доказательства критериев

Критерий Команда / сценарий Наблюдаемый результат Доказательство
Структура и синтаксис make check PASS; приложение этой проверкой не тестируется Вывод команды
Публичный API make test BASE_URL=http://localhost:18081 PASS: lab2 public API scenario evidence/smoke-final.txt
Миграции Повторный запуск migrate Already applied; в schema_migrations одна версия 001_initial.sql Вывод миграции и SELECT
Сохранность данных и сессии make test-persistence с scripts/restart.sh PASS: confirmed data and existing session preserved Результат теста; evidence/persistence-before.txt и persistence-after.txt
Реальный рестарт API и хранилищ Сравнение StartedAt Время запуска изменилось у API, PostgreSQL и Redis evidence/persistence-before.txt; evidence/persistence-after.txt
Гонка username Четыре конкурентные регистрации Один 201 и три 409; вход созданного пользователя успешен evidence/lab2-final.txt
Атомарность чата Создание с неизвестным участником 400; количество чатов и участников не изменилось; следующая валидная операция успешна evidence/lab2-final.txt
Logout Отзыв и повторное использование токена 204 без тела; последующее чтение и повторный logout дают 401 evidence/lab2-final.txt
Неверный пароль Вход с неправильным паролем и неизвестным username Одинаковый 401 и сообщение evidence/lab2-final.txt
Unicode и двоеточия Регистрация и вход с таким паролем Успешный вход evidence/lab2-final.txt
X-User-Id Запрос без Bearer и попытка смены пользователя Без токена 401; с токеном владелец не меняется evidence/lab2-final.txt
Короткий expiry SESSION_TTL_SECONDS=2 Сначала 200, затем 401 evidence/lab2-final.txt
Отказ Redis Остановка Redis Действующий токен работает через PostgreSQL; анонимный доступ запрещён evidence/lab2-final.txt
Отказ PostgreSQL Остановка БД при заполненном кэше Защищённый запрос 503; live 200; ready 503; без токена 401 evidence/lab2-final.txt
Возврат PostgreSQL Запуск БД после отказа Прежняя сессия снова работает evidence/lab2-final.txt
Индекс истории EXPLAIN на 10 000 сообщениях Index Scan для первой и средней страницы evidence/explain-history.txt
Pool и безопасные SQL-запросы Проверка реализации Ограниченный пул, таймауты, параметры SQL app/db.py; app/store.py

Эксперименты и отказы

Persistence

Тест завершился:

PASS: persistence preserved confirmed data and existing session.

Зафиксированные времена запуска до и после:

Сервис До, UTC После, UTC
API 14:33:23 14:38:37
PostgreSQL 11:25:08 14:38:30
Redis 11:25:08 14:38:30

Дата эксперимента: 2026-10-16. Полные временные метки находятся в evidence/.

Скрипт перезапускает API и оба используемых хранилища, не удаляя volumes и не подменяя тестовые данные.

Отказы и expiry: финальный запуск

Воздействие Наблюдение
Остановка Redis Fallback успешен; защищённый запрос 0.140 s
Остановка PostgreSQL Защищённый запрос получил 503 за 3.006 s
Возврат PostgreSQL Прежняя сессия восстановила доступ
TTL=2 Отказ по expiry наблюдался через 2.067 s после начала наблюдения
Завершение теста PostgreSQL и Redis запущены, API healthy, TTL=3600

Это одиночный локальный сценарий, не статистическое измерение задержек и не production SLA. Полное время восстановления от момента запуска зависимости отдельно не измерялось.

Шесть собственных проверок в финальном запуске: Ran 6 tests in 1.384s; OK.

Индекс истории

Набор: 10 000 сообщений в одном чате, 1 000 различных created_at, по десять сообщений на временную метку.

Индекс:

CREATE INDEX messages_chat_created_id_idx
ON messages (chat_id, created_at, id);

Перед измерением выполнено ANALYZE messages.

Запрос План Строки Shared hit Execution Time
Первая страница Index Scan 51 3 0.025 ms
Страница после курсора около середины Index Scan 51 9 0.052 ms

У второй страницы условие по (created_at, id) входит в Index Cond. Отдельного Sort нет.

OFFSET используется только для подготовки контрольного курсора в эксперименте, но не в запросах страниц приложения.

Показанные времена относятся к SQL-запросам на данном наборе, а не к HTTP API. В плане указаны shared hits; холодный кэш отдельно не исследовался.

Нагрузочное исследование RPS, p50/p95/p99 и потребления CPU/RAM не проводилось. Лимиты CPU/RAM сервисов в Compose не заданы. Исследовательские треки уровня 5 не заявляются.

Ограничения и следующие шаги

  • По одному экземпляру API, PostgreSQL и Redis. Высокая доступность не реализована.
  • При отказе PostgreSQL обязательный путь недоступен; API возвращает контролируемую ошибку.
  • Redis является необязательным для корректности кэшем.
  • Проверен штатный рестарт с сохранением volumes, не потеря диска, авария питания или повреждение данных.
  • HTTP применяется только для локального изолированного стенда с синтетическими данными.
  • Постраничный обход не является snapshot всей истории.
  • Устаревшие строки sessions автоматически не очищаются, но не проходят проверку expiry.
  • Нет rate limiting, вложений и фоновых workers: они не входят в обязательную реализацию этой лабораторной.
  • Теги образов и прямые зависимости закреплены; digest образов и полный lock транзитивных зависимостей не добавлены.
  • Проверки не являются полным security/fuzz/load suite.
  • Нельзя заявлять запуск из чистого clone как выполненный эксперимент без отдельной проверки.

Использованные материалы и библиотеки

  • Задание README.md и contracts/README.md.
  • contracts/openapi.json и публичные tests/.
  • Документация Docker Compose.
  • Документация PostgreSQL: ограничения, транзакции, индексы и EXPLAIN.
  • Документация Psycopg 3 и psycopg-pool.
  • Документация redis-py.
  • Документация argon2-cffi.
  • FastAPI, Uvicorn и стандартная библиотека Python.