Обновила отчет: перенесла основную информацию из лаб 2
This commit is contained in:
@@ -1,18 +1,165 @@
|
||||
# Отчёт — лабораторная 3
|
||||
|
||||
- Автор, группа: 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 (в 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 | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
|
||||
Reference in New Issue
Block a user