Files
mtusi2026lab3/REPORT.md
T

13 KiB

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

  • Автор, группа: Васюкова Наталья, БВТ2303
  • Целевая оценка: 4
  • Commit/PR: solution/BVT2303-Vasyukova
  • Использованные источники, библиотеки и помощь ИИ:
    • Контракт: contracts/openapi.json, contracts/README.md
    • Инструкции: README.md, COURSE.md, CONTRIBUTING.md
    • Библиотеки: fastapi==0.115.0, uvicorn[standard]==0.32.0, psycopg[binary]==3.2.3, psycopg_pool==3.2.3, redis==5.2.0, pydantic (из fastapi)
    • ИИ: DeepSeek — помощь в структурировании кода и отчёта. Весь код проверен, отредактирован и запущен разработчиком.

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

Версии runtime/образов:

  • Python: 3.12 (образ python:3.12-slim)
  • FastAPI 0.115.0, uvicorn[standard] 0.32.0, psycopg[binary] 3.2.3, psycopg_pool 3.2.3, redis 5.2.0
  • PostgreSQL 18.6-alpine (в Compose), Redis 7.4.1-alpine (в Compose)
  • Docker Desktop (Windows)

Запуск стека

  1. Клонировать репозиторий и переключиться на ветку решения:
    git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab2.git
    git checkout solution/BVT2303-Vasyukova
    
  2. Создать .env из шаблона:
    copy .env.example .env
    
  3. Собрать и поднять:
    docker compose --env-file .env up -d --build
    
  4. Проверить готовность:
    curl.exe -s http://localhost:8080/health/ready
    
    Ожидается: {"status":"ok"}.

Альтернативный локальный запуск без Docker: python -m uvicorn src.app.main:app --host 0.0.0.0 --port 8080 --reload (в .env при этом DATABASE_URL=postgresql://user:password@localhost:5432/high_load_messenger)

Проверки

make в среде автора недоступен (Windows без GNU Make), поэтому использованы эквивалентные прямые вызовы скриптов. Для Linux/CI рядом указаны команды make.

Makefile-команда Прямой вызов
make check python scripts/check_contract.py
make validate python scripts/validate_openapi.py
make test python tests/smoke.py --base-url http://localhost:8080
make test-student python student-tests/run_all.py --base-url http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080
make test-track2 python student-tests/test_track2.py --base-url http://localhost:8080

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

docker compose stop # данные PostgreSQL и Redis сохраняются (volumes) docker compose down # volumes сохраняются docker compose down -v # ТОЛЬКО если осознанно стираем данные БД и Redis

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

TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.

Схема процессов и хранилищ:

HTTP-клиент → FastAPI (uvicorn, 0.0.0.0:8080) → PostgreSQL 18.6 (postgres:5432)
                                              ↘ Redis 7.4.1 (redis:6379)

Все три сервиса — в одной compose-сети mtuci2026lab2_default. PostgreSQL и Redis доступны только по внутренним именам postgres и redis; наружу опубликован лишь порт API 127.0.0.1:8080 (Redis имеет 127.0.0.1:6379 только для отладки, БД порт не публикует).

Источники истины:

  • PostgreSQL — данные (пользователи, чаты, членство, сообщения).
  • Redis — серверные сессии.

Схема БД (подробнее — src/app/storage/db.py, константа SCHEMA_SQL):

users(id UUID PK, username TEXT UNIQUE, display_name TEXT, password_hash TEXT, created_at TIMESTAMPTZ)
chats(id UUID PK, title TEXT, created_at TIMESTAMPTZ)
chat_members(chat_id FK→chats, user_id FK→users, PK(chat_id,user_id))
messages(id UUID PK, chat_id FK→chats, sender_id FK→users, text TEXT, created_at TIMESTAMPTZ)
  + INDEX idx_messages_chat_created(chat_id, created_at, id)
sessions(token TEXT PK, user_id FK→users, expires_at TIMESTAMPTZ)  -- fallback SESSION_STORE=postgres

Применяется идемпотентно через init_schema() на старте. Все временные метки — TIMESTAMPTZ.

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

  • create_user — SELECT-проверка username и INSERT в одной транзакции; при гонке UniqueViolation ловится и превращается в 409.
  • create_chat — INSERT chats + INSERT chat_members в одной транзакции, откат целиком.
  • add_message — один INSERT, отдельная транзакция.
  • Создание/отзыв сессии — одна операция.

Аутентификация (lab1 → lab2)

Дерево проекта (изменения относительно lab1 отмечены *; трек 2 отмечен **):

mtuci2026lab2/
├── compose.yaml *            # API + PostgreSQL + Redis
├── Dockerfile
├── Makefile *
├── README.md, COURSE.md, ...  # скелет без изменений
├── requirements.txt *         # + psycopg_pool, redis
├── .env.example *             # + REDIS_URL, SESSION_STORE
├── src/app/                   # исходники приложения
│   ├── main.py *              # точка входа uvicorn, init_pool/close_pool, 503-обработчики
│   ├── api/
│   │   ├── health.py *        # readiness пингует PostgreSQL + Redis
│   │   ├── auth.py            # Авторизация
│   │   ├── security.py
│   │   ├── users.py
│   │   ├── chats.py
│   │   └── messages.py *      # keyset-пагинация в SQL
│   ├── models/schemas.py      # Pydantic-схемы
│   └── storage/
│       ├── db.py *            # ConnectionPool, SCHEMA_SQL, statement_timeout
│       ├── postgres.py *      # PostgresStorage, делегаты сессий, list_messages_page
│       ├── sessions.py *      # Redis-сессии, RuntimeError
│       └── memory.py          # референс lab1, не используется
├── scripts/
│   ├── restart.sh *           # Linux/CI: перезапуск API, PostgreSQL и Redis через compose
│   └── restart.bat *          # Windows-эквивалент для локального прогона
├── student-tests/
│   ├── run_all.py
│   ├── test_negative.py
│   ├── test_concurrency.py
│   ├── test_lab2_level4.py *  # гонка регистрации (реальные HTTP-коды + строка в БД), rollback составной операции create_chat (docker exec + patch executemany), EXPLAIN, недоступность Redis (с действующим токеном), недоступность PostgreSQL (с восстановлением в finally), expiry; режимы --skip-expiry / --only-expiry
│   ├── track2_seed.sql **     # сидирование >=100 000 сообщений
│   └── test_track2.py **      # Трек 2: EXPLAIN, стоимость записи, backup/restore, RPO
└── tests/                     # публичные проверки, без изменений

Что перенесено из lab1 без изменений: FastAPI-роутеры, Pydantic-схемы, middleware X-Request-Id, структурное логирование, обработчик SIGTERM, формат ошибок, Dockerfile (multi-stage, non-root, healthcheck), .dockerignore, student-tests/test_negative.py, student-tests/test_concurrency.py.

Что изменено:

  • requirements.txt: добавлены psycopg[binary], psycopg_pool, redis.
  • .env.example: добавлены REDIS_URL, SESSION_STORE.
  • compose.yaml: добавлены сервисы postgres и redis; api зависит от обоих через depends_on: condition: service_healthy.
  • storage/db.py: connection() берёт соединение из пула; init_schema() идемпотентен.
  • src/app/storage/postgres.py — реализует тот же интерфейс, что MemoryStorage, плюс делегаты сессий и list_messages_page.
  • storage/sessions.py: новый файл, хранилище сессий — Redis или PostgreSQL.
  • api/messages.py: keyset-пагинация вынесена в SQL.
  • api/health.py: readiness проверяет PostgreSQL и Redis.
  • main.py: init_pool/close_pool, обработчики 503.
  • scripts/restart.sh, scripts/restart.bat: перезапускают API, PostgreSQL и Redis.
  • student-tests/test_lab2_level4.py: тесты уровня 4; добавлены режимы --skip-expiry и --only-expiry.
  • student-tests/track2_seed.sql, student-tests/test_track2.py: трек 2 (уровень 5).
  • Makefile: цель test-track2.

Соответствие .env.example реальной конфигурации:

  • APP_HOST, APP_PORT — используются uvicorn/CMD в Dockerfile.
  • APP_ENV — пишется в стартовый лог event=startup app_env=..., в остальном на логику не влияет.
  • SESSION_TTL_SECONDS — TTL серверных сессий в Redis (или в таблице sessions при SESSION_STORE=postgres), по умолчанию 3600. Для теста expiry временно ставится 5 и возвращается обратно.
  • DATABASE_URL — строка подключения к PostgreSQL. В Docker используется postgresql://user:password@postgres:5432/high_load_messenger.
  • REDIS_URL — адрес Redis в compose-сети (redis://redis:6379/0), не секрет.
  • SESSION_STORE — redis (уровень 4) или postgres (fallback).
  • CACHE_URL_FILE — резервная переменная из скелета, не используется.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test TODO TODO
Остальные пункты уровня 3 TODO TODO TODO
Все пункты уровня 4, если заявлен TODO TODO TODO
Выбранный трек 5, если заявлен TODO TODO TODO

TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.

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

TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
TODO TODO TODO TODO

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

TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.