Files
mtusi2026lab2/REPORT.md
T

14 KiB
Raw Blame History

Отчёт по лабораторной работе № 2

Тема: PostgreSQL, сессии и Redis/Valkey
Студент: Кимпаев А.Р.
Группа: БПИ2303 Целевая оценка: 3
Трек уровня 5: не заявлен
Ветка решения: solution/bpi2303-kimpaev

1. Цель и выполненная работа

Цель — перенести серверную часть мессенджера из ЛР № 1 на постоянное хранилище PostgreSQL, реализовать аутентификацию и обеспечить сохранность подтверждённых данных и действующих сессий при перезапуске приложения и БД.

Перенесены функции ЛР № 1: регистрация пользователей, создание и просмотр чатов, управление составом участников при создании чата, отправка сообщений и чтение истории с пагинацией. С учётом перехода контракта ЛР № 2 регистрация требует пароль; POST /api/v1/auth/sessions использует HTTP Basic; остальные защищённые операции — Bearer-токен вместо X-User-Id. Добавлены завершение сеанса (logout) и время действия сессии.

Использованы Python 3.12, FastAPI, Pydantic, psycopg 3, PostgreSQL 16.8, Docker Compose. Redis/Valkey не использованы: на уровне оценки «3» источником истины для данных и сессий является PostgreSQL.

2. Архитектура и схема данных

HTTP-клиент
    |
    v
FastAPI (api, порт localhost:8080)
    |
    v
PostgreSQL (db, порт 5432 внутри сети Compose)
    |
    v
Именованный volume postgres_data

Структура описана миграцией migrations/001_initial.sql:

Таблица Назначение Ключевые ограничения и индексы
users Пользователи и хеши паролей id — PK; username — UNIQUE; ограничение формата username
chats Чаты id — PK
chat_members Участие пользователей в чатах Составной PK (chat_id, user_id); FK на чаты/пользователей; индекс (user_id, chat_id)
messages Сообщения id — PK; FK на чат и отправителя; запрет пустого текста; индекс (chat_id, created_at, id)
sessions Авторизованные сессии PK token_hash, FK user_id, expires_at, индекс по времени истечения
schema_migrations Применённые версии миграций PK version

При запуске FastAPI вызывает migrate(). Скрипты migrations/*.sql применяются по порядку; выполненные версии фиксируются в schema_migrations, повторное применение пропускается. Ограничения IF NOT EXISTS в начальной миграции дополнительно позволяют безопасно создавать отсутствующие объекты.

Транзакционные границы: создание чата (chats + все строки chat_members) производится в одной транзакции psycopg: ошибка отменяет операцию целиком. Вставка сообщения подтверждается завершением транзакции (COMMIT) перед возвращением успешного HTTP-ответа. История сообщений использует keyset-пагинацию по (created_at, id) и составной индекс с первым полем chat_id.

Сохранность: все постоянные данные и сессии находятся в PostgreSQL, которая использует именованный volume postgres_data. Перезапуск контейнеров без удаления volume не уничтожает уже подтверждённые записи. При сбое до COMMIT результат незавершённого запроса не гарантируется.

3. Аутентификация, авторизация и безопасность

  • При регистрации пароль обрабатывается scrypt (password KDF) с индивидуальной случайной солью. В БД хранится производный хеш, а не исходный пароль.
  • Вход выполняется через HTTP Basic только на POST /api/v1/auth/sessions. При успешном входе создаётся случайный opaque Bearer-токен; клиент получает сам токен, PostgreSQL хранит только его SHA-256.
  • Срок действия сессии задаётся SESSION_TTL_SECONDS (по умолчанию 3600 секунд). При обращениях проверяется expires_at > now(); после истечения срока сессия перестаёт действовать.
  • Выход DELETE /api/v1/auth/sessions/current удаляет соответствующую запись из sessions. Повторное использование отозванного токена не допускается.
  • Для защищённых операций X-User-Id не является доказательством входа. Доступ к конкретному чату проверяется по chat_members; постороннему пользователю данные чата не выдаются.
  • SQL-параметры передаются через плейсхолдеры psycopg. Файлы .env и secrets/ исключены из Git через .gitignore.

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

Требования: установленный и запущенный Docker Desktop (Docker Engine + Compose), Python 3.9+ для публичных тестов, make; команды выполнять в корне репозитория ЛР № 2.

Linux / WSL / Git Bash

bash scripts/setup.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl http://localhost:8080/health/ready
make check
make test

setup.sh создаёт локальные файлы secrets/db_password, secrets/database_url и .env, если их ещё нет. При первом запуске PostgreSQL использует пароль из db_password; при сохранённом volume смена файла сама по себе не меняет пароль роли в БД. Не перегенерируйте секреты на уже инициализированном volume без синхронизации учётных данных.

Проверка сохранности с Linux/WSL-скриптом:

chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh

В Windows Git Bash с Windows Python прямой запуск *.sh из subprocess может завершаться WinError 193. Для этого окружения применён эквивалентный scripts/restart.cmd:

@echo off
cd /d "%~dp0.."
docker compose --env-file .env restart db api
exit /b %errorlevel%

Проверка в Git Bash на Windows:

make test-persistence ACTION_SCRIPT=scripts/restart.cmd

Сценарии restart.sh / restart.cmd выполняют docker compose restart db api, не вызывают down -v, не удаляют volumes и не пересоздают тестовые данные. Для доказательства охвата перезапуска преподавателю можно показать текст скрипта и состояние контейнеров перед/после теста:

docker compose ps
docker compose logs --tail=30 api db

Swagger UI: http://localhost:8080/docs. Проверка liveness: http://localhost:8080/health/live; readiness (с подключением к БД): http://localhost:8080/health/ready.

Остановка без потери данных: docker compose down. Команду docker compose down -v не использовать, если данные требуется сохранить.

5. Результаты проверок

Проверки выполнены 03.11.2026, Windows 11 / Git Bash (UCRT64), локальный Docker Compose, http://localhost:8080.

Проверка Команда Фактический результат
Структура проекта и синтаксис make check PASS — offline skeleton structure, local refs and Python syntax; application NOT tested.
Публичный сценарий API make test PASS — lab2 public API scenario; infrastructure and grading evidence remain separate.
Сохранность данных и сессии после перезапуска make test-persistence ACTION_SCRIPT=scripts/restart.cmd PASS — persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
Прямой health-check curl http://localhost:8080/health/live {"status":"ok"}
Контейнеры после запуска docker compose ps api — Up, db — Up (healthy)

Вывод последней проверки persistence:

python3 tests/resilience.py --mode persistence --action-script "scripts/restart.cmd" --base-url "http://localhost:8080"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.

Проверка test-persistence подтвердила сохранение созданных тестом данных и действующего токена. При этом сам тест не доказывает, что hook действительно рестартовал оба контейнера; это подтверждается содержимым scripts/restart.cmd/scripts/restart.sh и демонстрацией Docker Compose. Отдельная проверка короткого TTL и повторного применения миграций на чистом volume в приведённых логах не зафиксирована; их можно продемонстрировать дополнительно на защите.

6. Ограничения и известные особенности

  1. Это локальный учебный стенд, слушающий 127.0.0.1:8080, без HTTPS на внешнем интерфейсе; Basic-аутентификацию нельзя использовать по незашифрованному соединению в публичной сети.
  2. Нет Redis/Valkey, горизонтального масштабирования и отдельного connection pool — это не заявлено для уровня «3».
  3. При недоступности PostgreSQL операции с данными невозможны; приложение обрабатывает psycopg.OperationalError как ошибку зависимости. Не подтверждённые сервером записи после сбоя не считаются сохранёнными.
  4. Для проверки persistence на Windows с Windows Python нужен restart.cmd, а на Linux/WSL — restart.sh.
  5. Публичные smoke/persistence тесты не заменяют полноценные нагрузочные, security и конкурентные испытания. Оценка преподавателем не определяется одним сообщением PASS.

7. Источники и использование ИИ

Реализация выполнена на базе собственного проекта ЛР № 1 и skeleton ЛР № 2. Использованы требования README.md, COURSE.md, contracts/, tests/README.md, CONTRIBUTING.md, а также документация Python/FastAPI, PostgreSQL и Docker Compose. При подготовке и отладке кода, Docker-конфигурации и документации применялась помощь ChatGPT (OpenAI). Запуск контейнеров и публичных тестов произведён локально; фактические результаты приведены выше. Пароли, токены и содержимое secrets/ в отчёт не включены.

8. Контрольный список перед отправкой MR

  • Реализованы основные функции ЛР № 1 с объявленным переходом на Basic/Bearer.
  • PostgreSQL, миграции, ограничения и хранение действующих сессий.
  • Локальный Compose-стенд с именованным volume.
  • make check и make test — PASS.
  • Persistence с scripts/restart.cmd на Windows — PASS.
  • Имеется scripts/restart.sh для Linux/WSL.
  • Перед публикацией проверить git status, git diff --cached и отсутствие .env, secrets/, данных volume.
  • После push вставить ссылку на MR и commit в раздел в начале отчёта.