Files
mtusi2026lab2/REPORT.md
T

10 KiB
Raw Blame History

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

  • Автор, группа: Васюкова Наталья, БВТ2303
  • Целевая оценка: 3
  • 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, pydantic (из fastapi)
    • ИИ: DeepSeek — помощь в структурировании кода и отчёта. Весь код проверен, отредактирован и запущен разработчиком.

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

Версии runtime/образов и Prerequisites (предварительные требования):

  • Python: 3.12 (базовый образ python:3.12-slim)
  • FastAPI 0.115.0, uvicorn[standard] 0.32.0, psycopg[binary] 3.2.3
  • PostgreSQL 18.6
  • Docker Desktop (Windows), образ mtusi-messenger:lab2

Подготовка PostgreSQL

  1. Установить PostgreSQL 18.6, открыть pgAdmin, подключиться к серверу localhost:5432 под пользователем postgres.
  2. Создать БД:
    • Database: high_load_messenger
    • Owner: postgres
  3. В Query Tool для базы high_load_messenger создать роль приложения:
    CREATE ROLE messenger WITH LOGIN PASSWORD 'messenger';
    GRANT ALL PRIVILEGES ON DATABASE high_load_messenger TO messenger;
    GRANT ALL ON SCHEMA public TO messenger;
    
  4. Схему таблиц автоматически создает приложение на старте.

Запуск API

  1. Клонировать репозиторий:

    git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab2.git && cd mtusi2026lab2
    
  2. Переключиться на ветку решения:

    git checkout solution/BVT2303-Vasyukova
    
  3. Создать локальный .env из шаблона:

    copy .env.example .env
    

    Отредактировать .env, указав DATABASE_URL.

  4. Сборка образа:

    docker build -t mtusi-messenger:lab2 .
    
  5. Запуск:

    docker run --rm --name mtuci-messenger-lab2 -p 127.0.0.1:8080:8080 --env-file .env --add-host=host.docker.internal:host-gateway mtuci-messenger:lab2
    

    Флаг --add-host=host.docker.internal:host-gateway обязателен, если PostgreSQL работает на хосте, а не в контейнере.

  6. Проверка готовности:

    curl.exe -s http://localhost:8080/health/ready
    

    Ожидается: {"status":"ok"}.

  7. Публичный smoke (в другом терминале): python tests/smoke.py --base-url http://localhost:8080

Альтернативный локальный запуск без Docker: python -m uvicorn src.app.main:app --host 0.0.0.0 --port 8080 --reload

Проверки

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

Примечание про 2 action-скрипта:

  • scripts/restart.sh — обязательный артефакт по методичке, для Linux/CI (shebang #!/bin/sh, chmod +x).
  • scripts/restart.bat — Windows-эквивалент restart.sh: tests/resilience.py запускает action-script напрямую через subprocess.Popen, и на Windows .sh не исполняется (WinError 193).

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

Ctrl+C в терминале контейнера
или
docker stop mtusi-messenger-lab2

Данные в PostgreSQL сохраняются (источник истины). Контейнер запускается с флагом --rm и удаляется автоматически.

Альтернативный локальный запуск без 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)

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

Актуальная архитектура на момент лаб 1:

Схема процессов/хранилищ: HTTP-клиент → FastAPI (uvicorn, 0.0.0.0:8080) → in-memory storage (dict + RLock)

Источник истины: Память процесса. Persistence - сохранение данных при перезапуске процесса - отсутствует. Транзакционные границы: операции над storage выполняются под RLock атомарно.

Ограничения: Одно-процессное хранение, нет репликации, нет HA.

Дерево папок:

mtusi2026lab1/
├── src/app/                  # исходники приложения
│   ├── main.py               # точка входа uvicorn, создание FastAPI, подключение роутеров, middleware для X-Request-Id, структурное логирование, обработчик SIGTERM, обработчики ошибок
│   ├── api/                  # HTTP-роутеры (по ресурсам)
│   │   ├── health.py
│   │   ├── users.py
│   │   ├── chats.py
│   │   └── messages.py
│   ├── models/
│   │   └── schemas.py        # Pydantic-схемы
│   └── storage/
│       └── memory.py         # in-memory хранилище (RLock)
├── contracts/                # OpenAPI + семантика (без изменений)
├── tests/                    # публичные проверки (без изменений)
├── scripts/                  # check_contract.py, validate_openapi.py (без изменений)
├── student-tests/            # собственные тесты уровня 4
│   ├── run_all.py            # единая команда запуска
│   ├── test_negative.py      # негативные сценарии
│   └── test_concurrency.py   # защита от гонок (100 сообщений / 10 клиентов)
├── Dockerfile                # сборка образа
├── Makefile                  # + test-student
├── README.md, ...            # скелет (без изменений)
└── REPORT.md                 # отчет

Примечание:

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

  • APP_HOST, APP_PORT — используется uvicorn/CMD в Dockerfile.
  • APP_ENV — используется в стартовом логе (event=startup app_env=...), в остальном в lab1 не влияет на логику.

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

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства Уровень
OpenAPI 3.1 и JSON Schema python scripts/validate_openapi.py PASS: full OpenAPI 3.1 and JSON Schema validation evidence/lab1_checks.txt 3
Публичный smoke (endpoint lab1, форматы ошибок, членство, пагинация) python tests/smoke.py --base-url http://localhost:8080 PASS: lab1 public API scenario evidence/lab1_checks.txt 3
Dockerfile собирает приложение, слушает 0.0.0.0:8080 docker build -t mtusi-messenger:lab1 . ; docker run ... образ собран, /health/ready = {"status":"ok"} evidence/lab1_checks.txt 3
Остальные пункты уровня 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: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.