diff --git a/REPORT.md b/REPORT.md index bb3d7dec..635a9d30 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,77 +1,64 @@ # Отчёт — лабораторная 2 - Автор, группа: Васюкова Наталья, БВТ2303 -- Целевая оценка: 3 +- Целевая оценка: 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, pydantic (из fastapi) + - Библиотеки: 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/образов и 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 +Версии 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 (на хосте), Redis 7.4.1-alpine (в Compose) +- Docker Desktop (Windows) ### Подготовка PostgreSQL -1. Установить PostgreSQL 18.6, открыть pgAdmin, подключиться к серверу localhost:5432 под пользователем postgres. -2. Создать БД: - - Database: `high_load_messenger` - - Owner: `postgres` -3. В Query Tool для базы high_load_messenger создать роль приложения: +1. Установить PostgreSQL 18.6, открыть pgAdmin, подключиться к серверу `localhost:5432` под пользователем `postgres`. +2. Создать БД `high_load_messenger`, owner `postgres`. +3. В Query Tool создать роль приложения: ```sql 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. Схему таблиц автоматически создает приложение на старте. +4. Разрешить подключения из docker-сети: в `postgresql.conf` — `listen_addresses = '*'`, в `pg_hba.conf` — строка для `172.16.0.0/12`/`host.docker.internal`. Перезапустить службу PostgreSQL. +5. Схему таблиц автоматически создаёт приложение на старте (`init_schema()`). -### Запуск API +### Запуск стека -1. Клонировать репозиторий: +1. Клонировать репозиторий и переключиться на ветку решения: ``` git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab2.git && cd mtusi2026lab2 - ``` -2. Переключиться на ветку решения: - ``` git checkout solution/BVT2303-Vasyukova ``` -3. Создать локальный `.env` из шаблона: +2. Создать `.env` из шаблона и при необходимости поправить `DATABASE_URL`: ``` copy .env.example .env ``` - Отредактировать `.env`, указав DATABASE_URL. -4. Сборка образа: +3. Собрать и поднять: ``` - docker build -t mtusi-messenger:lab2 . + docker compose --env-file .env up -d --build ``` -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. Проверка готовности: +4. Проверить готовность: ``` 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 - +(в `.env` при этом `DATABASE_URL=postgresql://user:password@localhost:5432/high_load_messenger`) + ### Проверки `make` в среде автора недоступен (Windows без GNU Make), поэтому использованы эквивалентные прямые вызовы скриптов. Для Linux/CI рядом указаны команды `make`. -| Makefile-команда | Прямой эквивалент | +| Makefile-команда | Прямой вызов | | --- | --- | | `make check` | `python scripts/check_contract.py` | | `make validate` | `python scripts/validate_openapi.py` | @@ -80,132 +67,128 @@ | `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). +`scripts/restart.sh` — обязательный артефакт для Linux/CI; `scripts/restart.bat` — Windows-эквивалент (`tests/resilience.py` запускает action-script напрямую через `subprocess.Popen` не исполняет `.sh` на Windows). ### Остановка и удаление учебных данных +docker compose stop # данные Redis и PostgreSQL (источник истины) сохраняются +docker compose down # volumes Redis сохраняются +docker compose down -v # ТОЛЬКО если осознанно стираем данные Redis ``` -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`) ## Архитектура и решения -Актуальная архитектура на момент lab2: +Схема процессов и хранилищ: -Схема процессов/хранилищ: ``` -HTTP-клиент → FastAPI (uvicorn, 0.0.0.0:8080) → PostgreSQL 18.6 (localhost:5432) - ↓ - БД high_load_messenger +HTTP-клиент → FastAPI (uvicorn, 0.0.0.0:8080) → PostgreSQL 18.6 (host.docker.internal:5432) + ↘ Redis 7.4.1 (redis:6379, AOF everysec) ``` Источник истины: -PostgreSQL. Все данные хранятся в БД. Память процесса используется только как кэш объектов Python в рамках одного запроса. +- PostgreSQL — пользователи, чаты, членство, сообщения. +- Redis — серверные сессии (TTL, инвалидация через logout). -Транзакционные границы: -- `create_user` — SELECT-проверка username и INSERT выполняются в одной транзакции; конкурентный дубликат отсекается уникальным индексом `users.username` (ловим `UniqueViolation` → 409). -- `create_chat` — INSERT в `chats` и `chat_members` выполняются в одной транзакции, фиксируются или откатываются целиком. Составная операция создания чата атомарна. -- `add_message` — один INSERT, фиксируется отдельно. -- `create_session`/`revoke_session` — одна транзакция на операцию. +Роль Redis на уровне 4: +- Хранилище серверных сессий с TTL (`SETEX sess: SESSION_TTL_SECONDS ...`). +- Persistence: AOF `appendonly yes`, `appendfsync everysec`, RDB `save 60 1` — сессии переживают рестарт Redis. +- Политика expiry: TTL задаёт сам Redis, продления нет. Инвалидация: `DEL sess:` при `DELETE /auth/sessions/current`. +- Источник истины для сессий — Redis. Если Redis недоступен, `/health/ready` → 503, бизнес-запросы не обслуживаются молча как анонимные. Схема БД (подробнее - `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 UUID FK→chats, user_id UUID FK→users, PK(chat_id,user_id)) -messages(id UUID PK, chat_id UUID FK→chats, sender_id UUID FK→users, text 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 UUID FK→users, expires_at TIMESTAMPTZ) +sessions(token TEXT PK, user_id FK→users, expires_at TIMESTAMPTZ) -- fallback SESSION_STORE=postgres +``` +Применяется идемпотентно через `init_schema()` на старте. Все временные метки — `TIMESTAMPTZ`. -Применяется идемпотентно через `init_schema()` при старте (CREATE ... IF NOT EXISTS). +Транзакционные границы: +- `create_user` — SELECT-проверка username и INSERT в одной транзакции; при гонке `UniqueViolation` ловится и превращается в 409. +- `create_chat` — INSERT `chats` + INSERT `chat_members` в одной транзакции, откат целиком. +- `add_message` — один INSERT, отдельная транзакция. +- Создание/отзыв сессии — одна операция. -Все временные метки — `TIMESTAMPTZ`. +Пул соединений и таймауты (уровень 4): +- `psycopg_pool.ConnectionPool(min_size=2, max_size=10, timeout=5.0)`, `statement_timeout=5000 ms` через `options`. Пул инициализируется в `lifespan` и закрывается на shutdown. + +Keyset-пагинация (уровень 4): +- `list_messages_page(chat_id, limit, after)`: `WHERE chat_id = %s AND (created_at, id) > (%s, %s) ORDER BY created_at, id LIMIT %s`. Берётся `limit + 1`, чтобы определить наличие следующей страницы. Полного scan всей истории на страницу нет. Аутентификация (lab1 → lab2): -- Регистрация (`POST /api/v1/users`) требует поле `password` (12–128 code points). Пароль хешируется стандартным `hashlib.scrypt` с уникальной солью на пользователя, формат хранения `scrypt$N$r$p$salt$dk`. Проверка через `hmac.compare_digest`. -- `POST /api/v1/auth/sessions` принимает только `Authorization: Basic `, без JSON body. Неверные креды → 401 с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. -- Успешный вход → 201 с `{token, token_type="Bearer", expires_at, user}`. Токен — `secrets.token_urlsafe(32)`, хранится серверной сессией в таблице `sessions` с TTL из `SESSION_TTL_SECONDS` (по умолчанию 3600). -- Все защищённые endpoint принимают только `Authorization: Bearer `. Истёкший/отозванный/неизвестный токен → 401 с `WWW-Authenticate: Bearer realm="messenger"`. -- `DELETE /api/v1/auth/sessions/current` — отзыв текущей сессии, 204. +- Регистрация `POST /api/v1/users` требует поле `password` (12–128 code points). Пароль хешируется стандартным `hashlib.scrypt` с уникальной солью на пользователя, формат хранения `scrypt$N$r$p$salt$dk`. Проверка через `hmac.compare_digest`. +- `POST /api/v1/auth/sessions` принимает только Basic `Authorization: Basic `, без JSON body. Неверные креды → 401 с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. +- Успешный вход → 201 `{token, token_type="Bearer", expires_at, user}`. Токен — `secrets.token_urlsafe(32)`, хранится серверной сессией в таблице `sessions` с TTL из `SESSION_TTL_SECONDS` (по умолчанию 3600). +- Защищённые endpoint принимают только `Authorization: Bearer `. Истёкший/отозванный/неизвестный токен → 401 с `WWW-Authenticate: Bearer realm="messenger"`. +- `DELETE /api/v1/auth/sessions/current` → отзыв текущей сессии. 204, повтор → 401. - `X-User-Id` (lab1) с lab2 игнорируется и доступа не даёт: смоук проверяет, что с валидным Bearer и чужим `X-User-Id: ` возвращается владелец токена (Alice), а не Eve. - Согласно `contracts/README.md`, Basic на бизнес-endpoint → 401. -Ограничения: -- Сессии хранятся в PostgreSQL. На уровне 4 потребуется либо перенести сессии в Redis/Valkey, либо использовать Redis для осмысленного кэша и обосновать это. -- Одна инстанция API, одна БД. Горизонтального масштабирования и HA нет (это lab3+). -- Пул соединений отсутствует: сейчас на каждый запрос создаётся `psycopg.connect()`. Для уровня 4 требуется ограниченный connection pool и таймауты. -- Keyset-пагинация в текущей версии реализована фильтрацией в Python после выборки всех сообщений чата. Для уровня 4 требуется вынести пагинацию в SQL и подкрепить EXPLAIN. -- Нагрузочных измерений для lab2 не проводилось (не требуется на 3). +Обработка недоступности зависимостей: +- `psycopg.OperationalError` → 503 `{"error":{"code":"unavailable",...}}` (обработчик в `main.py`). +- Redis-ошибки в `sessions.py` обёрнуты в `RuntimeError("redis_unavailable: ...")`, `main.py` превращает в 503 `unavailable`. +- `/health/ready` пингует PostgreSQL и, в режиме `redis`, Redis; при ошибке исключение вылетает наверх и превращается в 503 с телом `Error`. -Дерево папок: +Дерево проекта (изменения относительно lab1 отмечены `*`): ``` mtusi2026lab2/ -├── src/app/ # исходники приложения -│ ├── main.py # точка входа uvicorn, init_schema, роутеры, middleware X-Request-Id, структурное логирование, SIGTERM, обработчики ошибок (Basic/Bearer challenge) +├── compose.yaml * # API + Redis, PostgreSQL на хосте +├── 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 +│ │ ├── health.py * # readiness пингует PostgreSQL + Redis │ │ ├── auth.py # Авторизация -│ │ ├── security.py # current_user: извлечение Bearer, поиск сессии в PostgreSQL +│ │ ├── security.py │ │ ├── users.py │ │ ├── chats.py -│ │ └── messages.py -│ ├── models/ -│ │ └── schemas.py # Pydantic-схемы +│ │ └── messages.py * # keyset-пагинация в SQL +│ ├── models/schemas.py # Pydantic-схемы │ └── storage/ -│ ├── db.py # connection(), SCHEMA_SQL, init_schema() -│ ├── postgres.py # PostgresStorage — источник истины lab2 -│ └── memory.py # MemoryStorage оставлен как референс lab1 -├── contracts/ # OpenAPI + семантика (без изменений) -├── tests/ # публичные проверки (без изменений) +│ ├── db.py * # ConnectionPool, SCHEMA_SQL, statement_timeout +│ ├── postgres.py * # PostgresStorage, делегаты сессий, list_messages_page +│ ├── sessions.py * # Redis-сессии, RuntimeError +│ └── memory.py # референс lab1, не используется ├── scripts/ -│ ├── check_contract.py -│ ├── validate_openapi.py -│ ├── restart.example.sh -│ ├── restart.sh # Linux/CI: перезапуск API-контейнера -│ └── restart.bat # Windows-эквивалент для локального прогона -├── student-tests/ # собственные тесты из lab1 -│ ├── run_all.py # единая команда запуска -│ ├── test_negative.py # негативные сценарии -│ └── test_concurrency.py # защита от гонок (100 сообщений / 10 клиентов) -├── Dockerfile # сборка образа -├── Makefile -├── README.md, ... # скелет (без изменений) -├── requirements.txt -├── .env.example -└── REPORT.md # отчёт +│ ├── restart.sh * # Linux/CI: перезапуск API и Redis через compose +│ └── restart.bat * # Windows-эквивалент для локального прогона +├── student-tests/ +│ ├── run_all.py +│ ├── test_negative.py +│ ├── test_concurrency.py +│ └── test_lab2_level4.py * # конкурентная регистрация, expiry, EXPLAIN, Redis down +└── tests/ # публичные проверки, без изменений ``` -Примечание: - -Что перенесено из lab1: -- Исходники FastAPI, роутеры, Pydantic-схемы, обработчик SIGTERM, middleware X-Request-Id, формат ошибок, структурное логирование. -- Dockerfile, healthcheck, непривилегированный пользователь `appuser`, `.dockerignore`. -- `student-tests/` (негативные и конкурентные тесты lab1 продолжают работать). +Что перенесено из 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]==3.2.3`. -- `.env.example`: добавлена `DATABASE_URL`. -- `src/app/storage/db.py` — новый файл. -- `src/app/storage/postgres.py` — новый файл, реализует тот же интерфейс, что `MemoryStorage`. -- Роутеры `users/chats/messages/security/auth` переведены на `from ..storage.postgres import storage`. -- `src/app/models/schemas.py`: добавлен `field_serializer` для `created_at` и `expires_at`, чтобы Pydantic выдавал `Z`, а не `+00:00` (требование `contracts/README.md`). -- `src/app/main.py`: в `lifespan` вызывается `init_schema()`; `_error_response` выбирает `WWW-Authenticate` (Basic для `POST /auth/sessions`, Bearer для остальных 401). -- Добавлен `scripts/restart.sh` (Linux/CI) и `scripts/restart.bat` (Windows). +- `requirements.txt`: добавлены `psycopg[binary]`, `psycopg_pool`, `redis`. +- `.env.example`: добавлены `REDIS_URL`, `SESSION_STORE`. +- `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 и Redis. +- `student-tests/test_lab2_level4.py`: тесты уровня 4. Соответствие `.env.example` реальной конфигурации: - `APP_HOST`, `APP_PORT` — используются uvicorn/CMD в Dockerfile. - `APP_ENV` — пишется в стартовый лог `event=startup app_env=...`, в остальном на логику не влияет. - `SESSION_TTL_SECONDS` — TTL серверных сессий в таблице `sessions`, по умолчанию 3600. -- `DATABASE_URL` — строка подключения к PostgreSQL; в Docker используется `host.docker.internal` (PostgreSQL на хосте), при запуске без Docker — `localhost`. Пароль — секрет, реальное значение только в локальном `.env` (в `.gitignore`/`.dockerignore`); в `.env.example` — placeholder. +- `DATABASE_URL` — строка подключения к PostgreSQL. В Docker используется `host.docker.internal` (PostgreSQL на хосте); пароль — в локальном `.env`, в `.env.example` — placeholder. +- `REDIS_URL` — адрес Redis в compose-сети (`redis://redis:6379/0`), не секрет. +- `SESSION_STORE` — `redis` (уровень 4) или `postgres` (fallback). +- `CACHE_URL_FILE` — резервная переменная из скелета, не используется. ## Доказательства критериев @@ -213,84 +196,70 @@ mtusi2026lab2/ | --- | --- | --- | --- | --- | | OpenAPI 3.1 и JSON Schema | `python scripts/validate_openapi.py` | `PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.` | evidence/lab2/lab2_checks.txt | **3** | | Структура и локальные ссылки | `python scripts/check_contract.py` | `PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.` | evidence/lab2/lab2_checks.txt | **3** | -| Публичный smoke (endpoint lab2, ошибки, членство, пагинация, авторизация) | `python tests/smoke.py --base-url http://localhost:8080` | `PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.` | evidence/lab2/lab2_checks.txt | **3** | -| Собственные тесты | `python student-tests/run_all.py --base-url http://localhost:8080` | `PASS: all student tests (level 4) passed` | evidence/lab2/lab2_checks.txt | **3** | -| Dockerfile собирает приложение, слушает 0.0.0.0:8080 | `docker build -t mtusi-messenger:lab2 .`; `docker run ...` | образ собран, `/health/ready` → `{"status":"ok"}` | evidence/lab2/lab2_checks.txt | **3** | -| PostgreSQL как источник истины (пользователи, чаты, участники, сообщения) | таблицы созданы `init_schema()`, схема в `src/app/storage/db.py`; `\dt` в pgAdmin | таблицы `users`, `chats`, `chat_members`, `messages`, `sessions` присутствуют | evidence/lab2/lab2_checks.txt | **3** | -| PK/FK, уникальность username, миграции с нуля | `SCHEMA_SQL` в `db.py`; прогон `init_schema()` на пустой БД | таблицы создаются идемпотентно; повторный запуск не дублирует | evidence/lab2/lab2_checks.txt | **3** | -| Составная операция создания чата атомарна | `create_chat` в `postgres.py`: INSERT chats + INSERT chat_members в одной транзакции | при ошибке INSERT в `chat_members` чат не появляется | src/app/storage/postgres.py | **3** | -| Basic применяется только на `POST /auth/sessions`, остальные — Bearer | смоук-проверки: Basic на `/users/me` → 401; X-User-Id игнорируется | `PASS: lab2 public API scenario` | evidence/lab2/lab2_checks.txt | **3** | -| Срок жизни сессии и отзыв | `SESSION_TTL_SECONDS` в `.env`; `DELETE /auth/sessions/current` → 204; повторный запрос с отозванным токеном → 401 | 204, затем 401 | evidence/lab2/lab2_checks.txt | **3** | -| X-User-Id не даёт доступ на lab2 | `GET /users/me` с `Authorization: Bearer ` и `X-User-Id: ` → возвращает Alice | возвращает Alice | evidence/lab2/lab2_checks.txt | **3** | -| Пароли хешируются password KDF | `hashlib.scrypt` в `memory.py`/`postgres.py`, формат `scrypt$N$r$p$salt$dk` | plaintext/hash в ответах API не фигурируют | src/app/storage/postgres.py | **3** | -| Persistence: данные и токен переживают рестарт API | `python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080` | `PASS: persistence preserved confirmed data and existing session.` | evidence/lab2/lab2_persistence.txt | **3** | -| Hook реально перезапустил API (operator evidence) | `docker inspect -f "{{.State.StartedAt}}" mtusi-messenger-lab2` до/после hook | `StartedAt` изменился, данные в БД сохранены | evidence/lab2/lab2_persistence.txt | **3** | -| Миграции повторно запускаются без дублирования | повторный `docker run` → `init_schema()` | количество строк в таблицах не растёт | evidence/lab2/lab2_checks.txt | **3** | -| Secrets/volumes не попадают в Git | `.dockerignore`, `.gitignore` (при наличии), `.env` локально | `DATABASE_URL` в `.env.example` — placeholder | .env.example | **3** | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. - -### Примечание про hook scope (operator evidence) - -`tests/resilience.py` после прогона выводит: «Hook scope needs operator evidence» — это значит, что тест не доказывает, что hook реально перезапустил контейнер. В `evidence/lab2/lab2_persistence.txt` приложены: -- `docker ps` до и после (контейнер `mtusi-messenger-lab2` присутствует и там, и там); -- `docker inspect -f "{{.State.StartedAt}}" mtusi-messenger-lab2` до и после — время старта отличается; -- фрагмент `docker logs mtusi-messenger-lab2` с новой строкой `event=startup app_env=lab` после рестарта; -- PostgreSQL не перезапускался, volumes не удалялись — данные остались (это и есть суть проверки persistence на lab2 при БД на хосте). +| Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | `PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.` | evidence/lab2/lab2_checks.txt | **3** | +| Собственные тесты lab1 | `python student-tests/run_all.py --base-url http://localhost:8080` | `PASS: all student tests (level 4) passed` | evidence/lab2/lab2_checks.txt | **3** | +| Dockerfile собирает приложение, слушает 0.0.0.0:8080 | `docker compose --env-file .env up -d --build` | `/health/ready` → `{"status":"ok"}` | evidence/lab2/lab2_checks.txt | **3** | +| PostgreSQL как источник истины | `init_schema()`; таблицы в pgAdmin | `users`, `chats`, `chat_members`, `messages`, `sessions` присутствуют | evidence/lab2/lab2_checks.txt | **3** | +| PK/FK, уникальность username, миграции с нуля | `SCHEMA_SQL` в `db.py`; прогон на пустой БД | таблицы создаются идемпотентно, повторный запуск не дублирует | evidence/lab2/lab2_checks.txt | **3** | +| Составная операция создания чата атомарна | `create_chat`: INSERT chats + INSERT chat_members в одной транзакции | при ошибке INSERT в `chat_members` чат не появляется | src/app/storage/postgres.py | **3** | +| Basic только на `POST /auth/sessions` | смоук: Basic на `/users/me` → 401; `X-User-Id` игнорируется | `PASS: lab2 public API scenario` | evidence/lab2/lab2_checks.txt | **3** | +| Срок жизни сессии и отзыв | `DELETE /auth/sessions/current` → 204; повтор → 401 | 204, затем 401 | evidence/lab2/lab2_checks.txt | **3** | +| X-User-Id не даёт доступ | `GET /users/me` с `Authorization: Bearer Alice` и `X-User-Id: ` | возвращает Alice | evidence/lab2/lab2_checks.txt | **3** | +| Пароли хешируются password KDF | `hashlib.scrypt`, формат `scrypt$N$r$p$salt$dk` | plaintext/hash в ответах API не фигурируют | src/app/storage/postgres.py | **3** | +| Persistence: данные и сессия переживают рестарт API и Redis | `python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080` | `PASS: persistence preserved confirmed data and existing session.` | evidence/lab2/lab2_persistence.txt | **3** | +| Hook реально перезапустил API и Redis | `docker inspect -f "{{.State.StartedAt}}"` до/после | время старта изменилось, данные сохранены | evidence/lab2/lab2_persistence.txt | **3** | +| Secrets/volumes не попадают в Git | `.dockerignore`, `.env` локально | `DATABASE_URL`/`REDIS_URL` в `.env.example` — плейсхолдеры | .env.example | **3** | +| Redis реально используется для сессий с TTL | `docker exec mtusi-redis redis-cli KEYS "sess:*"`, `TTL sess:` | ключи `sess:*`, TTL ≈ `SESSION_TTL_SECONDS` | evidence/lab2/lab2_level4.txt | **4** | +| Redis persistence, выдерживающее рестарт | `docker exec mtusi-redis redis-cli INFO persistence`; рестарт Redis | `aof_enabled:1`; сессии живы после рестарта | evidence/lab2/lab2_level4.txt | **4** | +| Параметризованные запросы, ограниченный пул, таймауты | `psycopg_pool.ConnectionPool(2..10, timeout=5)`, `statement_timeout=5000` | нет `psycopg.connect()` на запрос | src/app/storage/db.py | **4** | +| Гонка регистрации одинакового username | `python student-tests/test_lab2_level4.py` (блок `test_concurrent_registration`) | ровно одна 201, остальные 409 | evidence/lab2/lab2_level4.txt | **4** | +| Индекс истории обоснован EXPLAIN на ≥10 000 сообщениях | тот же скрипт, `test_explain` | `Index Scan using idx_messages_chat_created` | evidence/lab2/lab2_level4.txt | **4** | +| Keyset-пагинация без полного scan на страницу | `list_messages_page` в `postgres.py` | `WHERE (created_at, id) > (…, …)` + `LIMIT` | src/app/storage/postgres.py | **4** | +| Автопроверка expiry при коротком TTL | `SESSION_TTL_SECONDS=5`, `test_short_ttl_expiry` | до TTL — 200, после — 401; повторный вход работает | evidence/lab2/lab2_level4.txt | **4** | +| Logout и неверный пароль | `DELETE /auth/sessions/current`; неверный Basic | 204 → 401; неверный Basic → 401 с Basic-challenge | evidence/lab2/lab2_checks.txt | **3** | +| Недоступность Redis не даёт анонимный доступ | `test_redis_unavailable` (stop redis → ready 503) | `/health/ready` → 503 `unavailable`, Bearer не проходит | evidence/lab2/lab2_level4.txt | **4** | +| Недоступность PostgreSQL → 503 | обработчик `psycopg.OperationalError` в `main.py` | 503 `unavailable`, без внутренних деталей | src/app/main.py | **4** | +| Выбранный трек 5 | не заявлен | — | — | — | ## Эксперименты и отказы -Обязательный сценарий уровня 3 — persistence через рестарт API и всех используемых хранилищ — выполнен и подтверждён. Нагрузочные эксперименты и отказоустойчивость (failover, Redis/Valkey, недоступность БД) относятся к уровням 4/5 и на этом этапе не выполнялись. - Hardware и версии: -- Windows 11, Docker Desktop (WSL2 backend), без ограничений CPU/RAM на контейнер. -- Образ `mtusi-messenger:lab2` на базе `python:3.12-slim`. -- PostgreSQL 18.6 на хосте, БД `high_load_messenger`. -- FastAPI 0.115.0, uvicorn[standard] 0.32.0, psycopg[binary] 3.2.3. +- Windows 11, Docker Desktop (WSL2 backend), без лимитов CPU/RAM на контейнер; +- Образ `mtusi-messenger:lab2` на `python:3.12-slim`; +- PostgreSQL 18.6 на хосте +- Redis 7.4.1-alpine в Compose. - -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. - -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потери | | --- | --- | --- | --- | -| `docker restart mtusi-messenger-lab2` (hook `scripts/restart.bat`) | API перезапускается, PostgreSQL и volume не трогаются; тот же Bearer-токен читает то же сообщение | `PASS: persistence preserved confirmed data and existing session` | downtime ≈ 2–3 с; потеря данных 0 | -| Повторный `init_schema()` при новом старте | Таблицы уже существуют, миграция идемпотентна | нет ошибок, нет дублирования строк | — | -| SIGTERM (`docker stop -t 10`) | Процесс завершается ≤ 10 с | как в lab1: завершение за <1 с, `event=shutdown_complete` в логе | — | +| `docker compose restart api redis` (`scripts/restart.bat`) | API и Redis перезапускаются, PostgreSQL и volumes не трогаются; прежний Bearer читает прежние данные | `PASS: persistence preserved confirmed data and existing session`; `event=startup` в логах, `StartedAt` изменился | downtime ≈ 2–3 с; потери 0 | +| `docker compose stop redis`, затем запрос `/health/ready` | 503 `unavailable`, анонимный доступ не открывается | `PASS: readiness 503 без Redis`; после `start redis` — 200 | downtime ≈ 3 с; потери сессий 0 (AOF) | +| Повторный `init_schema()` | Идемпотентно, без дублирования, таблицы уже существуют | ошибок нет, нет дублирования строк | — | +| SIGTERM (`docker stop -t 10`) | завершение ≤ 10 с | как в lab1: <1 с, `event=shutdown_complete` | — | -Профиль нагрузки на lab2 не снимался: по методичке нагрузочные измерения требуются на уровнях 4/5 (EXPLAIN на ≥10 000 сообщений, Redis-эксперимент в Треке 1). Для уровня 3 достаточен публичный smoke и persistence-тест. +Профиль нагрузки на lab2 не снимался: на уровне 3/4 нагрузочные измерения не требуются, EXPLAIN на ≥10 000 сообщениях подтверждает индекс запроса истории. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. - -Что выдерживает текущая реализация: -- Штатную работу одной инстанции API с PostgreSQL как источником истины. -- Регистрацию с password KDF (scrypt), вход Basic → Bearer, TTL сессии, отзыв. -- Сохранение пользователей, чатов, членства, сообщений и действующих сессий между рестартами API (данные в PostgreSQL на хосте). -- Атомарность создания чата (INSERT chats + INSERT chat_members в одной транзакции). -- Идемпотентную миграцию схемы. -- Контрактные форматы ответов, коды ошибок, `X-Request-Id`, `WWW-Authenticate` (Basic на `/auth/sessions`, Bearer на остальных). - -Что пока не реализовано (за скоупом «3», задел на 4/5): -- Redis/Valkey не подключён. Сессии хранятся в PostgreSQL. Для уровня 4 нужно либо перенести сессии в Redis/Valkey с TTL и persistence, либо использовать Redis как осмысленный кэш (cache-aside) и обосновать это. -- Connection pool не используется: на каждый запрос создаётся новое `psycopg.connect()`. Для уровня 4 нужен `psycopg_pool.ConnectionPool` с ограничением `min_size/max_size`, `timeout` и `statement_timeout`. -- Keyset-пагинация выполняется фильтрацией в Python после выборки всех сообщений чата. Для уровня 4 нужно вынести фильтр в SQL (`WHERE (created_at, id) > (%s, %s) ORDER BY created_at, id LIMIT n`) и обосновать индекс `idx_messages_chat_created` через `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях. -- Гонка регистрации одинакового username обрабатывается через SELECT-then-INSERT и уникальный индекс `users.username`; ловится `UniqueViolation`. Нужен отдельный тест конкурентной регистрации, чтобы подтвердить это для уровня 4. -- Тест expiry при коротком `SESSION_TTL_SECONDS` (например, 2 с) не выделен в отдельный сценарий. -- Обработка недоступности БД/Redis (503 `unavailable`) — сейчас ошибка соединения с БД приведёт к 500. Для уровня 4 нужно маппить `psycopg.OperationalError` на 503. -- Одна инстанция API, одна БД. Горизонтального масштабирования и HA нет (lab3+). -- Нагрузочные эксперименты и failover-сценарии не выполнялись. +Что выдерживает реализация: +- Штатную работу API с PostgreSQL (источник истины) и Redis (сессии с TTL и AOF). +- Регистрацию (scrypt), Basic → Bearer, TTL, отзыв, повторный вход. +- Сохранение пользователей, чатов, членства, сообщений и действующих сессий при рестарте API и Redis без удаления volumes. +- Атомарность создания чата (INSERT chats + INSERT chat_members в одной транзакции); идемпотентную миграцию. +- Keyset-пагинацию в SQL с индексом `idx_messages_chat_created`. +- Контрактные ответы, `X-Request-Id`, `WWW-Authenticate`, 503 при недоступности Redis/PostgreSQL. +- Конкурентную регистрацию одинакового username без дублей. Учебные упрощения: -- PostgreSQL на хосте, не в Compose. Методичка (уровень 3) «рекомендует» Compose, но не требует; инструкция по чистому клонированию зафиксирована в этом отчёте. Для уровня 4/5 при необходимости можно перенести БД в Compose без изменения кода (только DSN). -- `memory.py` оставлен в репозитории как референс lab1, но в приложении не используется. +- PostgreSQL запущен на хосте (не в Compose); в коде это только DSN, перенос в Compose не требует правок. +- `storage/memory.py` оставлен как референс lab1 и в приложении не используется. +- `SESSION_STORE=postgres` — fallback, оставлен для сравнения; в рабочем режиме — `redis`. -Следующие шаги (для заявленных 4/5): -1. Подключить `psycopg_pool.ConnectionPool` и `statement_timeout`. -2. Вынести keyset-пагинацию в SQL; снять `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщений; приложить план. -3. Добавить Redis/Valkey: либо перенос сессий (TTL + persistence), либо осмысленный кэш. Обосновать выбор. -4. Добавить тесты: конкурентная регистрация, expiry при коротком TTL, недоступность Redis/БД (503). -5. Реализовать один трек 5 (Трек 1 «Согласованность кэша» проще всего ложится на cache-aside Redis поверх PostgreSQL; Трек 2 «План запроса и восстановление» — backup/restore и сравнение индексов). +Что не входит в уровень 4: +- Горизонтальное масштабирование, балансировщик, HA (lab3+). +- Вложения и S3 (lab4+), фоновая обработка (lab5+), OTel/Grafana (lab6+), TLS/mTLS/OpenBao/Argon2id (lab7). +- Трек 5 не заявлен. + +Следующие шаги (при заявке на 5): +1. Трек 1 «Согласованность кэша»: cache-aside поверх PostgreSQL с измерением SQL-запросов/latency до и после, защита от stampede, read-after-write. +2. Либо Трек 2 «План запроса и восстановление»: ≥100 000 сообщений, сравнение ≥2 индексов, backup → restore → сверка. ```