diff --git a/REPORT.md b/REPORT.md index 9ad2b84f..cc1090b5 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,28 +1,161 @@ # Отчёт — лабораторная 4 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Васюкова Наталья, БВТ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 -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Версии 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, Redis 7.4.1-alpine, nginx 1.27.3-alpine (в Compose) +- Docker Desktop (Windows) + +### Запуск стека + +1. Клонировать репозиторий и переключиться на ветку решения: + ``` + git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab3.git + git checkout solution/BVT2303-Vasyukova + ``` +2. Создать `.env` из шаблона: + ``` + copy .env.example .env + ``` +3. Собрать и поднять (LB + 2 реплики API + PostgreSQL + Redis): + ``` + docker compose --env-file .env up -d --build + ``` +4. Проверить готовность: + ``` + curl.exe -s http://localhost:8080/health/ready + ``` + Ожидается: `{"status":"ok"}`. + +Все проверки ниже выполнялись с `PYTHONUTF8=1` (Windows по умолчанию использует cp1251 и падает на чтении UTF-8 JSON): +``` +$env:PYTHONUTF8="1" +``` + +### Проверки + +`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/lab3_test_level4.py --base-url http://localhost:8080` | + +### Остановка и удаление учебных данных + +``` +docker compose stop # данные PostgreSQL и Redis сохраняются (volumes) +docker compose down # volumes сохраняются +docker compose down -v # ТОЛЬКО если осознанно стираем данные БД и Redis +``` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Схема процессов и хранилищ: + +``` + ┌─ api-1 (uvicorn:8080, INSTANCE_ID=…) +HTTP-клиент → lb:80 ──┤ ↘ + (nginx) └─ api-2 (uvicorn:8080, INSTANCE_ID=…) PostgreSQL 18.6 (postgres:5432) + Redis 7.4.1 (redis:6379) +``` + +Все сервисы — в одной compose-сети `mtuci2026lab3_default`. Публично опубликован только порт LB `127.0.0.1:8080:80`. Реплики `api` **не имеют `ports`** — трафик к ним идёт исключительно через LB. PostgreSQL и Redis доступны только по внутренним именам `postgres` и `redis`. + +Источники истины: +- 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 +idempotency_keys(user_id FK→users, method TEXT, path TEXT, key TEXT, + body_hash TEXT, response_status INT, response_body JSONB, created_at TIMESTAMPTZ, + PRIMARY KEY (user_id, method, path, key)) + + INDEX idx_idempotency_created(created_at) +``` + +Применяется идемпотентно через `init_schema()` на старте. Все временные метки — `TIMESTAMPTZ`. + +Транзакционные границы: +- `create_user` — SELECT-проверка username и INSERT в одной транзакции; при гонке `UniqueViolation` → 409. +- `create_chat` — INSERT `chats` + INSERT `chat_members` в одной транзакции, откат целиком. +- `add_message` — один INSERT, отдельная транзакция. +- Создание/отзыв сессии — одна операция. + +### Дерево проекта (изменения относительно lab2 отмечены `*`) + +``` +mtuci2026lab3/ +├── compose.yaml * # + lb, api без container_name/ports, deploy.replicas +├── Dockerfile * # убран ARG INSTANCE_ID, добавлен docker-entrypoint.sh +├── docker-entrypoint.sh * # генерирует INSTANCE_ID, пишет /tmp/instance_id +├── infra/nginx.conf * # vhost LB +├── Makefile +├── src/app/ +│ ├── main.py * # X-Instance-Id в middleware +│ ├── api/ +│ │ └── messages.py * # обязательный Idempotency-Key, атомарный reserve/complete +│ └── storage/ +│ ├── db.py * # + таблица idempotency_keys +│ └── postgres.py * # + reserve_idempotency / complete_idempotency +├── scripts/ +│ ├── restart.sh / .bat * # + lb, обе реплики api +│ └── stop-one.sh / .bat * # останавливает ту реплику, чей INSTANCE_ID == TARGET_INSTANCE_ID +└── student-tests/ + └── lab3_test_level4.py * # два X-Instance-Id, идемпотентность через реплики, отказ реплики +``` + +### Что нового в lab4 относительно lab3 + +... + +Соответствие `.env.example` реальной конфигурации (без изменений с lab2): +- `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 | +| Публичный smoke | make test | TODO | 3 | | Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Все пункты уровня 4 | TODO | TODO | TODO | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +### Выводы тестов + +``` +(venv) PS ...> python scripts/check_contract.py +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. + +(venv) PS ...> python scripts/validate_openapi.py +PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested. + +(venv) PS ...> python tests/smoke.py --base-url http://localhost:8080 +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. ## Эксперименты и отказы @@ -35,3 +168,10 @@ TODO: гипотеза, hardware/лимиты, версии, объём данн ## Ограничения и следующие шаги TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. + +- **Один Docker-host.** Отказ узла не проверялся; LB, PostgreSQL и Redis — единичные экземпляры (SPOF). HA БД/LB не заявляется. +- **Обнаружение отказа — реактивное.** LB узнаёт о мёртвой реплике по первой ошибке (`max_fails=1 fail_timeout=5s`), поэтому возможна короткая задержка ~5 с до исключения из ротации. Это допустимо по методичке (восстановление ≤10 с). +- **Идемпотентность только на POST сообщения.** `POST /users` и `POST /chats` без `Idempotency-Key` — повтор создаёт новый объект/409, что соответствует контракту. +- **Часы.** Порядок `(created_at, id)` требует монотонности `created_at` в пределах сервера; для учебного стенда с одной БД это выполняется. +- **Миграции.** `init_schema()` идемпотентен, но запускается на старте каждой реплики. Гонки нет благодаря `CREATE TABLE IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS`. Отдельный миграционный job не выделен — это упрощение учебного уровня. +- **Нагрузка.** Полноценных замеров RPS/p50/p95/p99 при фиксированных ресурсах не проводилось — для целевой оценки 4 это не требуется. Трек 5 (цена масштабирования) не заявлен. \ No newline at end of file