Files
mtusi2026lab2/REPORT.md
T

28 KiB
Raw Blame History

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

  • Автор, группа: Мусаев Абдул-Хамид Рамзанович, БВТ-2303
  • Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не заявлен
  • Commit/PR: mtusi2026/mtusi2026lab2#27
  • Использованные источники, библиотеки и помощь ИИ:
    • библиотеки: FastAPI 0.143.0, Uvicorn 0.54.0, psycopg 3.3.6 и psycopg-pool 3.3.3, redis-py 8.1.0, argon2-cffi 25.1.0 (полный список с версиями в requirements.txt);
    • источники: документация PostgreSQL (транзакции, EXPLAIN), Redis persistence, psycopg, Docker Compose, RFC 7617, contracts/README.md;
    • помощь ИИ: ИИ-ассистент использовался во вспомогательных целях.

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

Нужны Docker с Compose v2 (проверено на Docker 29.3.0, Compose 5.1.0), make, openssl, curl и Python 3.9+ на хосте для тестов. Сервер, PostgreSQL и Redis работают только в контейнерах.

make up             # создаёт .env с паролями, собирает образ, поднимает стенд и ждёт /health/ready

make check          # структура skeleton
make test           # публичный smoke
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make student-test   # собственные тесты API
make test-failures  # истечение сессии, остановка Redis и PostgreSQL, откат транзакции
make explain        # 60 000 синтетических сообщений и планы запросов
python3 scripts/sigterm_check.py

make down           # остановить и удалить контейнеры, данные остаются в volumes
make clean          # то же и удалить volumes: намеренное удаление учебных данных

То же без make:

./scripts/init-env.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
./scripts/wait-ready.sh

scripts/init-env.sh копирует .env.example в .env и дописывает в него случайные пароли PostgreSQL и Redis (openssl rand). Файл .env исключён из Git. Повторный запуск скрипта пароли не меняет: пароль PostgreSQL задаётся один раз при создании volume, поэтому после make clean нужно либо оставить старый .env, либо удалить его и создать заново.

Миграции отдельной команды не требуют: при up одноразовый контейнер migrate применяет их до старта API. Повторить вручную можно командой docker compose --env-file .env run --rm migrate.

make test-failures сам останавливает и запускает redis и postgres и поднимает второй экземпляр API на порту 8081, поэтому запускать его нужно только на учебном стенде.

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

клиент ──HTTP──> api (uvicorn + FastAPI) ──┬──> postgres: пользователи, чаты, участники, сообщения
                                           └──> redis:    сессии с TTL

Роли и сервисы

Роль Сервис compose Образ Готовность Volume Сеть и порт Как получает секреты
api api собирается из Dockerfile на python:3.13.16-slim-bookworm HEALTHCHECK → /health/ready нет, состояния не хранит опубликован 127.0.0.1:8080 файлы /run/secrets/database_url, /run/secrets/cache_url
миграции migrate тот же образ, команда python migrate.py одноразовый, код выхода 0 нет только внутренняя сеть файл /run/secrets/database_url
postgres postgres postgres:17.11-alpine pg_isready pgdata только внутренняя сеть, 5432 POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password
redis redis redis:7.4.11-alpine redis-cli ping redisdata только внутренняя сеть, 6379 --requirepass из /run/secrets/redis_password

Секреты описаны в compose.yaml как secrets с источником из переменных .env. Compose кладёт их в контейнеры файлами, в окружении контейнеров паролей нет (проверка в evidence/07-containers.txt). Наружу опубликован только порт API.

Файлы

Файл Что в нём
migrations/0001_init.sql таблицы, ключи, ограничения, индексы
src/migrate.py применяет миграции по порядку, ведёт таблицу schema_migrations
src/store.py все SQL-запросы и пул соединений
src/sessions.py сессии в Redis
src/security.py hash пароля (Argon2id), разбор заголовков Basic и Bearer
src/main.py endpoint, middleware, обработка ошибок
src/schemas.py, src/errors.py, src/config.py валидация JSON, формат ошибки, настройки

Схема данных

  • users: id (PK), username (UNIQUE и CHECK по шаблону), display_name, password_hash, created_at.
  • chats: id (PK), title, created_at.
  • chat_members: PK (chat_id, user_id), внешние ключи на chats и users, position — порядок участника в запросе. Индекс (user_id, chat_id) для списка чатов пользователя.
  • messages: id (PK), внешние ключи chat_id и sender_id, text (CHECK 1–4000 символов), created_at. Индекс (chat_id, created_at, id) для истории.

id и created_at назначает PostgreSQL (gen_random_uuid(), now()). Ограничения длины продублированы в CHECK, чтобы неверные данные не попали в БД даже в обход приложения.

Транзакционные границы

Каждый метод Store берёт одно соединение из пула и выполняется в одной транзакции: with pool.connection() делает COMMIT при выходе и ROLLBACK при исключении.

  • Регистрация — один INSERT. Уникальность username проверяет сама БД; нарушение ограничения превращается в 409. Поэтому два одновременных запроса не создадут двух пользователей.
  • Создание чата — составная операция: INSERT в chats, затем INSERT всех участников в chat_members. Если участника нет, срабатывает внешний ключ, транзакция откатывается вместе с уже вставленным чатом, клиент получает 400.
  • Отправка сообщения — проверка членства и INSERT в одной транзакции.
  • Ответ 201 отправляется только после COMMIT. PostgreSQL работает с настройками по умолчанию (fsync=on, synchronous_commit=on), то есть подтверждённая запись уже на диске.

Все значения попадают в запросы только параметрами %s, строки SQL из пользовательских данных не собираются.

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

  • Пароль хешируется Argon2id (argon2-cffi, 19 МиБ памяти, 2 прохода, 1 поток — минимальные параметры из рекомендаций OWASP). В БД хранится только hash.
  • POST /api/v1/auth/sessions принимает только Authorization: Basic. Неизвестный username и неверный пароль дают одинаковый 401 с WWW-Authenticate: Basic. Если пользователя нет, пароль всё равно сверяется с заранее посчитанным hash, чтобы время ответа не выдавало существование username.
  • Токен — secrets.token_urlsafe(32), 256 бит случайности. Остальные endpoint принимают только Authorization: Bearer; X-User-Id не читается, Basic на бизнес-запросах даёт 401.
  • Проверка токена выполняется до валидации параметров и тела и до обращения к чату: сначала аутентификация, потом доступ к конкретному ресурсу.

Роль Redis

Redis — единственное хранилище сессий. PostgreSQL о сессиях ничего не знает; источник истины для пользователей, чатов и сообщений — PostgreSQL, для сессий — Redis.

  • Ключ session:<sha256 от токена>, значение — id пользователя. Сам токен в Redis не хранится, поэтому по дампу нельзя получить рабочий токен.
  • Expiry: ключ записывается командой SET ... EX SESSION_TTL_SECONDS, срок отсчитывается от входа и запросами не продлевается. Истёкший ключ Redis удаляет сам.
  • Инвалидация: logout — это DEL ключа текущей сессии. Другие сессии того же пользователя остаются.
  • Persistence: включён AOF с appendfsync always, данные лежат в volume redisdata. Сессия переживает перезапуск Redis, а оставшийся TTL при этом не увеличивается (evidence/04-redis-sessions.txt: 3591 с до перезапуска, 3583 с после).
  • Политика вытеснения — noeviction: при нехватке памяти Redis откажет в записи новой сессии, но не удалит действующие.
  • После FLUSHALL или удаления volume redisdata все сессии пропадают: каждый токен получит 401, пользователям нужно войти заново. Данные в PostgreSQL при этом не страдают.

Пул соединений и таймауты

Что Значение Где задаётся
соединений с PostgreSQL от 2 до 10 DB_POOL_MIN_SIZE, DB_POOL_MAX_SIZE
ожидание свободного соединения 3 с DB_POOL_TIMEOUT
установка соединения с PostgreSQL 3 с DB_CONNECT_TIMEOUT
выполнение одного запроса 5 с (statement_timeout) DB_STATEMENT_TIMEOUT
соединений с Redis до 20 CACHE_POOL_MAX_SIZE
операция с Redis и ожидание соединения 2 с CACHE_TIMEOUT

Перед выдачей из пула соединение с PostgreSQL проверяется, поэтому после перезапуска БД запросы не получают мёртвые соединения.

Поведение при отказе зависимостей

  • Redis недоступен: проверить токен нечем, поэтому любой запрос с токеном получает 503 unavailable. Запрос не выполняется ни от имени владельца токена, ни как анонимный. Запрос без токена по-прежнему получает 401.
  • PostgreSQL недоступен: запросы, которым нужны данные, получают 503 не позже чем через 3 секунды (ожидание соединения из пула).
  • /health/ready проверяет обе зависимости (SELECT 1 и PING) и отвечает 503 в общем формате ошибки, если хотя бы одна недоступна. /health/live от них не зависит.
  • API стартует, даже если БД ещё не поднялась, и отвечает 503 до её появления.

Пагинация и порядок

Запрос истории:

SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
ORDER BY created_at, id LIMIT $4

Cursor — base64 от JSON [область, created_at, id] последней выданной записи; область привязывает его к конкретному чату или к списку чатов конкретного пользователя. Запрашивается limit + 1 строк: лишняя строка показывает, есть ли следующая страница.

Семантика при конкурентных вставках. created_at — это now() PostgreSQL, то есть время начала транзакции. Две параллельные транзакции могут зафиксироваться не в порядке своих created_at. Поэтому сообщение с чуть более ранним временем может появиться в истории уже после того, как клиент прошёл это место по cursor, и при обходе вперёд он его не увидит (окно — миллисекунды, длительность транзакции вставки). Повторов при обходе нет. Чтение после записи выполняется: ответ 201 приходит после COMMIT, следующий GET это сообщение видит.

Соответствие переменных окружения

Переменная в .env По умолчанию Что делает
APP_HOST, APP_PORT 0.0.0.0, 8080 адрес сервера; в compose заданы жёстко, из .env не читаются
APP_ENV lab выводится в лог при старте
SESSION_TTL_SECONDS 3600 срок жизни сессии
SESSION_STORE redis поддерживается только redis, с другим значением сервер не стартует
DATABASE_URL_FILE, CACHE_URL_FILE /run/secrets/... пути к файлам со строками подключения; в compose заданы жёстко
LOG_LEVEL, SHUTDOWN_TIMEOUT info, 8 как в lab1
DB_POOL_*, DB_*_TIMEOUT, CACHE_* см. таблицу выше пул и таймауты
POSTGRES_PASSWORD, REDIS_PASSWORD, DATABASE_URL, CACHE_URL создаёт init-env.sh источник compose-секретов; в контейнер api попадают только файлами

Что перенесено из lab1 и что изменено

Перенесены: структура src/, формат ошибок и X-Request-Id, валидация JSON, cursor-пагинация, логирование без содержимого, Dockerfile (непривилегированный пользователь, healthcheck, корректная остановка по SIGTERM), собственные тесты.

Изменено: хранилище в памяти заменено на PostgreSQL; X-User-Id заменён на пароль, Basic и Bearer; добавлены миграции, Redis, compose, проверка зависимостей в /health/ready и ответ 503. Строки теперь проверяются ещё и на символ NUL, который PostgreSQL не хранит. Контракт и публичные тесты не менялись.

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

Стенд: Apple M3 Pro, 11 CPU, 18 ГБ RAM, macOS 26.1, Docker 29.3.0, Compose 5.1.0, без ограничений CPU/RAM для контейнеров. Все файлы получены из чистого clone на пустых volumes, commit 6473fd0.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS: lab2 public API scenario evidence/01-up-and-smoke.txt
3: данные и сессии переживают рестарт API и хранилищ make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; у контейнеров postgres, redis, api новое время старта, volumes те же evidence/03-persistence.txt
3: таблицы, ключи, уникальность username, миграции с нуля make up на пустом volume применена: 0001_init.sql, smoke проходит evidence/01-up-and-smoke.txt, migrations/0001_init.sql
3: создание чата атомарно make test-failures (test_transactions.py) после неудачного создания в chats 0 строк, после удачного — чат и 2 участника evidence/05-failures.txt
3: Basic только на входе, Bearer на остальном, срок жизни, отзыв, X-User-Id не даёт доступ make student-test (test_auth.py) 15 тестов ok evidence/02-student-tests.txt
3: пароли хешируются KDF test_password_is_stored_as_argon2id_hash hash в БД начинается с $argon2id$ evidence/05-failures.txt
3: миграции повторяются без дублирования docker compose run --rm migrate уже применена: 0001_init.sql, в schema_migrations одна строка, число строк в таблицах не изменилось evidence/03-persistence.txt, evidence/05-failures.txt
3: secrets и volumes не в Git git ls-files | grep -E "^\.env$|secrets" пусто evidence/07-containers.txt
4: Redis реально используется для сессий с TTL и persistence redis-cli CONFIG GET, TTL, docker compose restart redis appendonly yes, appendfsync always; ключ пережил перезапуск, TTL 3591 → 3583 evidence/04-redis-sessions.txt
4: параметризованные запросы, ограниченный пул, таймауты src/store.py, src/sessions.py; остановка зависимостей 503 через 0,01 с без Redis и через 3,0 с без PostgreSQL evidence/05-failures.txt
4: гонка регистрации одного username test_username_race_creates_one_row, test_same_username_registered_once один ответ 201 и девять 409, в users одна строка evidence/05-failures.txt, evidence/02-student-tests.txt
4: rollback составной операции test_chat_with_unknown_member_is_rolled_back 400, в chats 0 строк с этим названием, участников без чата нет evidence/05-failures.txt
4: индекс истории обоснован EXPLAIN на ≥10 000 сообщений make explain Index Scan, 8 буферов на страницу в любом месте истории evidence/06-explain.txt
4: автоматическая проверка expiry при коротком TTL test_expiry.py, API с SESSION_TTL_SECONDS=2 через 3 с токен получает 401, запросы срок не продлевают evidence/05-failures.txt
4: автоматическая проверка logout и неверного пароля test_auth.py после logout 401, вторая сессия работает; неверный пароль — 401 evidence/02-student-tests.txt
4: недоступность Redis и БД test_dependencies.py 503 unavailable за ограниченное время, аноним получает 401, после восстановления прежний токен и данные на месте evidence/05-failures.txt
Возможности lab1: непривилегированный пользователь, закреплённые версии, SIGTERM docker compose exec api id, scripts/sigterm_check.py uid=10001(app); начатый запрос получил 201, выход за 1,45 с с кодом 0 evidence/07-containers.txt, evidence/08-sigterm.txt

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

Нагрузочное исследование (трек 5) не проводилось.

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

Гипотеза: индекс (chat_id, created_at, id) позволяет читать любую страницу истории за число обращений к диску, не зависящее от длины истории и от положения страницы.

Методика: scripts/seed_history.sql создаёт 21 чат и 60 000 сообщений, из них 10 000 в исследуемом чате, остальные 50 000 поровну в 20 других; затем ANALYZE. scripts/explain_history.sql выполняет EXPLAIN (ANALYZE, BUFFERS) для четырёх запросов с LIMIT 51 (страница 50 плюс одна строка). Данные небольшие и целиком в кэше, поэтому сравнивать нужно число буферов, а не миллисекунды.

Запрос План Буферов Время выполнения
первая страница Index Scan по messages_chat_history_idx 8 0,025 мс
страница после 5000-го сообщения, keyset Index Scan, условие на (created_at, id) внутри Index Cond 8 0,034 мс
та же страница через OFFSET 5000 Index Scan, прочитано 5051 строка 491 0,469 мс
keyset без индекса Seq Scan всей таблицы (отброшено 55 140 строк) и сортировка 862 2,266 мс

Вывод: с индексом и keyset страница из середины стоит столько же, сколько первая, сортировка не нужна. OFFSET читает все пропущенные строки, и стоимость растёт с номером страницы. Без индекса каждая страница читает всю таблицу, включая чужие чаты.

Ограничение измерения: одна таблица на 60 000 строк, один запуск, всё в памяти. Для вывода о реальной нагрузке этого мало. Четвёртый запрос выполняет DROP INDEX внутри транзакции с ROLLBACK: на это время таблица messages заблокирована, поэтому скрипт годится только для учебного стенда.

Отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose restart postgres redis api данные и сессия на месте прежний токен читает прежние сообщения готов через несколько секунд, потерь нет
docker compose stop redis запросы с токеном не выполняются 503 за 0,01 с; без токена 401; /health/ready 503, /health/live 200 после start redis прежний токен работает, сообщение, отправленное во время отказа, не записано
docker compose stop postgres запросы к данным не выполняются 503 за 3,0 с; без токена 401 после start postgres данные на месте, запись снова работает
сессия с TTL 2 с через 2 с токен недействителен через 3 с 401, logout с ним тоже 401, новый вход работает —
чат с несуществующим участником ничего не создаётся 400, в chats и chat_members следов нет —
10 одновременных регистраций одного username один пользователь один 201, девять 409, одна строка —
SIGTERM процессу API начатый запрос завершится 201, новые соединения не принимаются, выход за 1,45 с —

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

  • Один экземпляр API, один PostgreSQL, один Redis на одном хосте. Отказ хоста, диска или любого из хранилищ не переживается, резервных копий нет.
  • При недоступном Redis не работает ни один запрос с токеном: запасного пути проверки сессии нет. Это осознанный выбор в пользу простоты и того, что отозванная сессия не может «ожить» из другого хранилища.
  • appendfsync always делает каждую запись сессии синхронной записью на диск. Для учебного стенда это незаметно, под нагрузкой вход станет узким местом.
  • Нет ограничения числа попыток входа и числа сессий на пользователя, код 429 не используется.
  • Порядок истории при параллельных вставках описан выше: возможен пропуск сообщения при обходе вперёд в окне длительности транзакции.
  • Если JSON синтаксически сломан, FastAPI отвечает 400 раньше, чем проверяется токен. На доступ к данным это не влияет.
  • При недоступной БД ответ 503 приходит через 3 секунды, а не сразу: столько запрос ждёт соединение из пула.
  • Пароли в .env лежат открытым текстом на диске разработчика (права 600). Для локального стенда с синтетическими данными это допустимо.
  • make explain оставляет в БД синтетические чаты и 60 000 сообщений; убрать их можно только make clean.
  • Проверено на одном стенде (macOS, Docker Desktop). На Linux не запускалось.