# Отчёт — лабораторная 2 - Автор, группа: Мусаев Абдул-Хамид Рамзанович, БВТ-2303 - Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не заявлен - Commit/PR: TODO после публикации - Использованные источники, библиотеки и помощь ИИ: - библиотеки: FastAPI 0.143.0, Uvicorn 0.54.0, psycopg 3.3.6 и psycopg-pool 3.3.3, redis-py 8.1.0, argon2-cffi 25.1.0 (полный список с версиями в `requirements.txt`); - источники: документация PostgreSQL (транзакции, EXPLAIN), Redis persistence, psycopg, Docker Compose, RFC 7617, `contracts/README.md`; - помощь ИИ: ИИ-ассистент использовался во вспомогательных целях. ## Запуск из чистого clone Нужны Docker с Compose v2 (проверено на Docker 29.3.0, Compose 5.1.0), `make`, `openssl`, `curl` и Python 3.9+ на хосте для тестов. Сервер, PostgreSQL и Redis работают только в контейнерах. ```sh make up # создаёт .env с паролями, собирает образ, поднимает стенд и ждёт /health/ready make check # структура skeleton make test # публичный smoke make test-persistence ACTION_SCRIPT=scripts/restart.sh make student-test # собственные тесты API make test-failures # истечение сессии, остановка Redis и PostgreSQL, откат транзакции make explain # 60 000 синтетических сообщений и планы запросов python3 scripts/sigterm_check.py make down # остановить и удалить контейнеры, данные остаются в volumes make clean # то же и удалить volumes: намеренное удаление учебных данных ``` То же без `make`: ```sh ./scripts/init-env.sh docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build ./scripts/wait-ready.sh ``` `scripts/init-env.sh` копирует `.env.example` в `.env` и дописывает в него случайные пароли PostgreSQL и Redis (`openssl rand`). Файл `.env` исключён из Git. Повторный запуск скрипта пароли не меняет: пароль PostgreSQL задаётся один раз при создании volume, поэтому после `make clean` нужно либо оставить старый `.env`, либо удалить его и создать заново. Миграции отдельной команды не требуют: при `up` одноразовый контейнер `migrate` применяет их до старта API. Повторить вручную можно командой `docker compose --env-file .env run --rm migrate`. `make test-failures` сам останавливает и запускает `redis` и `postgres` и поднимает второй экземпляр API на порту 8081, поэтому запускать его нужно только на учебном стенде. ## Архитектура и решения ``` клиент ──HTTP──> api (uvicorn + FastAPI) ──┬──> postgres: пользователи, чаты, участники, сообщения └──> redis: сессии с TTL ``` ### Роли и сервисы | Роль | Сервис compose | Образ | Готовность | Volume | Сеть и порт | Как получает секреты | | --- | --- | --- | --- | --- | --- | --- | | api | `api` | собирается из `Dockerfile` на `python:3.13.16-slim-bookworm` | HEALTHCHECK → `/health/ready` | нет, состояния не хранит | опубликован `127.0.0.1:8080` | файлы `/run/secrets/database_url`, `/run/secrets/cache_url` | | миграции | `migrate` | тот же образ, команда `python migrate.py` | одноразовый, код выхода 0 | нет | только внутренняя сеть | файл `/run/secrets/database_url` | | postgres | `postgres` | `postgres:17.11-alpine` | `pg_isready` | `pgdata` | только внутренняя сеть, 5432 | `POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password` | | redis | `redis` | `redis:7.4.11-alpine` | `redis-cli ping` | `redisdata` | только внутренняя сеть, 6379 | `--requirepass` из `/run/secrets/redis_password` | Секреты описаны в `compose.yaml` как `secrets` с источником из переменных `.env`. Compose кладёт их в контейнеры файлами, в окружении контейнеров паролей нет (проверка в `evidence/07-containers.txt`). Наружу опубликован только порт API. ### Файлы | Файл | Что в нём | | --- | --- | | `migrations/0001_init.sql` | таблицы, ключи, ограничения, индексы | | `src/migrate.py` | применяет миграции по порядку, ведёт таблицу `schema_migrations` | | `src/store.py` | все SQL-запросы и пул соединений | | `src/sessions.py` | сессии в Redis | | `src/security.py` | hash пароля (Argon2id), разбор заголовков Basic и Bearer | | `src/main.py` | endpoint, middleware, обработка ошибок | | `src/schemas.py`, `src/errors.py`, `src/config.py` | валидация JSON, формат ошибки, настройки | ### Схема данных - `users`: `id` (PK), `username` (UNIQUE и CHECK по шаблону), `display_name`, `password_hash`, `created_at`. - `chats`: `id` (PK), `title`, `created_at`. - `chat_members`: PK `(chat_id, user_id)`, внешние ключи на `chats` и `users`, `position` — порядок участника в запросе. Индекс `(user_id, chat_id)` для списка чатов пользователя. - `messages`: `id` (PK), внешние ключи `chat_id` и `sender_id`, `text` (CHECK 1–4000 символов), `created_at`. Индекс `(chat_id, created_at, id)` для истории. `id` и `created_at` назначает PostgreSQL (`gen_random_uuid()`, `now()`). Ограничения длины продублированы в CHECK, чтобы неверные данные не попали в БД даже в обход приложения. ### Транзакционные границы Каждый метод `Store` берёт одно соединение из пула и выполняется в одной транзакции: `with pool.connection()` делает COMMIT при выходе и ROLLBACK при исключении. - **Регистрация** — один `INSERT`. Уникальность username проверяет сама БД; нарушение ограничения превращается в 409. Поэтому два одновременных запроса не создадут двух пользователей. - **Создание чата** — составная операция: `INSERT` в `chats`, затем `INSERT` всех участников в `chat_members`. Если участника нет, срабатывает внешний ключ, транзакция откатывается вместе с уже вставленным чатом, клиент получает 400. - **Отправка сообщения** — проверка членства и `INSERT` в одной транзакции. - Ответ 201 отправляется только после COMMIT. PostgreSQL работает с настройками по умолчанию (`fsync=on`, `synchronous_commit=on`), то есть подтверждённая запись уже на диске. Все значения попадают в запросы только параметрами `%s`, строки SQL из пользовательских данных не собираются. ### Аутентификация - Пароль хешируется Argon2id (`argon2-cffi`, 19 МиБ памяти, 2 прохода, 1 поток — минимальные параметры из рекомендаций OWASP). В БД хранится только hash. - `POST /api/v1/auth/sessions` принимает только `Authorization: Basic`. Неизвестный username и неверный пароль дают одинаковый 401 с `WWW-Authenticate: Basic`. Если пользователя нет, пароль всё равно сверяется с заранее посчитанным hash, чтобы время ответа не выдавало существование username. - Токен — `secrets.token_urlsafe(32)`, 256 бит случайности. Остальные endpoint принимают только `Authorization: Bearer`; `X-User-Id` не читается, Basic на бизнес-запросах даёт 401. - Проверка токена выполняется до валидации параметров и тела и до обращения к чату: сначала аутентификация, потом доступ к конкретному ресурсу. ### Роль Redis Redis — **единственное хранилище сессий**. PostgreSQL о сессиях ничего не знает; источник истины для пользователей, чатов и сообщений — PostgreSQL, для сессий — Redis. - Ключ `session:`, значение — id пользователя. Сам токен в Redis не хранится, поэтому по дампу нельзя получить рабочий токен. - **Expiry**: ключ записывается командой `SET ... EX SESSION_TTL_SECONDS`, срок отсчитывается от входа и запросами не продлевается. Истёкший ключ Redis удаляет сам. - **Инвалидация**: logout — это `DEL` ключа текущей сессии. Другие сессии того же пользователя остаются. - **Persistence**: включён AOF с `appendfsync always`, данные лежат в volume `redisdata`. Сессия переживает перезапуск Redis, а оставшийся TTL при этом не увеличивается (`evidence/04-redis-sessions.txt`: 3591 с до перезапуска, 3583 с после). - Политика вытеснения — `noeviction`: при нехватке памяти Redis откажет в записи новой сессии, но не удалит действующие. - После `FLUSHALL` или удаления volume `redisdata` все сессии пропадают: каждый токен получит 401, пользователям нужно войти заново. Данные в PostgreSQL при этом не страдают. ### Пул соединений и таймауты | Что | Значение | Где задаётся | | --- | --- | --- | | соединений с PostgreSQL | от 2 до 10 | `DB_POOL_MIN_SIZE`, `DB_POOL_MAX_SIZE` | | ожидание свободного соединения | 3 с | `DB_POOL_TIMEOUT` | | установка соединения с PostgreSQL | 3 с | `DB_CONNECT_TIMEOUT` | | выполнение одного запроса | 5 с (`statement_timeout`) | `DB_STATEMENT_TIMEOUT` | | соединений с Redis | до 20 | `CACHE_POOL_MAX_SIZE` | | операция с Redis и ожидание соединения | 2 с | `CACHE_TIMEOUT` | Перед выдачей из пула соединение с PostgreSQL проверяется, поэтому после перезапуска БД запросы не получают мёртвые соединения. ### Поведение при отказе зависимостей - **Redis недоступен**: проверить токен нечем, поэтому любой запрос с токеном получает 503 `unavailable`. Запрос не выполняется ни от имени владельца токена, ни как анонимный. Запрос без токена по-прежнему получает 401. - **PostgreSQL недоступен**: запросы, которым нужны данные, получают 503 не позже чем через 3 секунды (ожидание соединения из пула). - `/health/ready` проверяет обе зависимости (`SELECT 1` и `PING`) и отвечает 503 в общем формате ошибки, если хотя бы одна недоступна. `/health/live` от них не зависит. - API стартует, даже если БД ещё не поднялась, и отвечает 503 до её появления. ### Пагинация и порядок Запрос истории: ```sql SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4 ``` Cursor — base64 от JSON `[область, created_at, id]` последней выданной записи; область привязывает его к конкретному чату или к списку чатов конкретного пользователя. Запрашивается `limit + 1` строк: лишняя строка показывает, есть ли следующая страница. **Семантика при конкурентных вставках.** `created_at` — это `now()` PostgreSQL, то есть время начала транзакции. Две параллельные транзакции могут зафиксироваться не в порядке своих `created_at`. Поэтому сообщение с чуть более ранним временем может появиться в истории уже после того, как клиент прошёл это место по cursor, и при обходе вперёд он его не увидит (окно — миллисекунды, длительность транзакции вставки). Повторов при обходе нет. Чтение после записи выполняется: ответ 201 приходит после COMMIT, следующий `GET` это сообщение видит. ### Соответствие переменных окружения | Переменная в `.env` | По умолчанию | Что делает | | --- | --- | --- | | `APP_HOST`, `APP_PORT` | `0.0.0.0`, `8080` | адрес сервера; в compose заданы жёстко, из `.env` не читаются | | `APP_ENV` | `lab` | выводится в лог при старте | | `SESSION_TTL_SECONDS` | `3600` | срок жизни сессии | | `SESSION_STORE` | `redis` | поддерживается только `redis`, с другим значением сервер не стартует | | `DATABASE_URL_FILE`, `CACHE_URL_FILE` | `/run/secrets/...` | пути к файлам со строками подключения; в compose заданы жёстко | | `LOG_LEVEL`, `SHUTDOWN_TIMEOUT` | `info`, `8` | как в lab1 | | `DB_POOL_*`, `DB_*_TIMEOUT`, `CACHE_*` | см. таблицу выше | пул и таймауты | | `POSTGRES_PASSWORD`, `REDIS_PASSWORD`, `DATABASE_URL`, `CACHE_URL` | создаёт `init-env.sh` | источник compose-секретов; в контейнер `api` попадают только файлами | ### Что перенесено из lab1 и что изменено Перенесены: структура `src/`, формат ошибок и `X-Request-Id`, валидация JSON, cursor-пагинация, логирование без содержимого, Dockerfile (непривилегированный пользователь, healthcheck, корректная остановка по SIGTERM), собственные тесты. Изменено: хранилище в памяти заменено на PostgreSQL; `X-User-Id` заменён на пароль, Basic и Bearer; добавлены миграции, Redis, compose, проверка зависимостей в `/health/ready` и ответ 503. Строки теперь проверяются ещё и на символ NUL, который PostgreSQL не хранит. Контракт и публичные тесты не менялись. ## Доказательства критериев Стенд: Apple M3 Pro, 11 CPU, 18 ГБ RAM, macOS 26.1, Docker 29.3.0, Compose 5.1.0, без ограничений CPU/RAM для контейнеров. Все файлы получены из чистого clone на пустых volumes, commit `6473fd0`. | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Публичный smoke | `make test` | `PASS: lab2 public API scenario` | `evidence/01-up-and-smoke.txt` | | 3: данные и сессии переживают рестарт API и хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS`; у контейнеров `postgres`, `redis`, `api` новое время старта, volumes те же | `evidence/03-persistence.txt` | | 3: таблицы, ключи, уникальность username, миграции с нуля | `make up` на пустом volume | `применена: 0001_init.sql`, smoke проходит | `evidence/01-up-and-smoke.txt`, `migrations/0001_init.sql` | | 3: создание чата атомарно | `make test-failures` (`test_transactions.py`) | после неудачного создания в `chats` 0 строк, после удачного — чат и 2 участника | `evidence/05-failures.txt` | | 3: Basic только на входе, Bearer на остальном, срок жизни, отзыв, `X-User-Id` не даёт доступ | `make student-test` (`test_auth.py`) | 15 тестов `ok` | `evidence/02-student-tests.txt` | | 3: пароли хешируются KDF | `test_password_is_stored_as_argon2id_hash` | hash в БД начинается с `$argon2id$` | `evidence/05-failures.txt` | | 3: миграции повторяются без дублирования | `docker compose run --rm migrate` | `уже применена: 0001_init.sql`, в `schema_migrations` одна строка, число строк в таблицах не изменилось | `evidence/03-persistence.txt`, `evidence/05-failures.txt` | | 3: secrets и volumes не в Git | `git ls-files \| grep -E "^\.env$\|secrets"` | пусто | `evidence/07-containers.txt` | | 4: Redis реально используется для сессий с TTL и persistence | `redis-cli CONFIG GET`, `TTL`, `docker compose restart redis` | `appendonly yes`, `appendfsync always`; ключ пережил перезапуск, TTL 3591 → 3583 | `evidence/04-redis-sessions.txt` | | 4: параметризованные запросы, ограниченный пул, таймауты | `src/store.py`, `src/sessions.py`; остановка зависимостей | 503 через 0,01 с без Redis и через 3,0 с без PostgreSQL | `evidence/05-failures.txt` | | 4: гонка регистрации одного username | `test_username_race_creates_one_row`, `test_same_username_registered_once` | один ответ 201 и девять 409, в `users` одна строка | `evidence/05-failures.txt`, `evidence/02-student-tests.txt` | | 4: rollback составной операции | `test_chat_with_unknown_member_is_rolled_back` | 400, в `chats` 0 строк с этим названием, участников без чата нет | `evidence/05-failures.txt` | | 4: индекс истории обоснован EXPLAIN на ≥10 000 сообщений | `make explain` | Index Scan, 8 буферов на страницу в любом месте истории | `evidence/06-explain.txt` | | 4: автоматическая проверка expiry при коротком TTL | `test_expiry.py`, API с `SESSION_TTL_SECONDS=2` | через 3 с токен получает 401, запросы срок не продлевают | `evidence/05-failures.txt` | | 4: автоматическая проверка logout и неверного пароля | `test_auth.py` | после logout 401, вторая сессия работает; неверный пароль — 401 | `evidence/02-student-tests.txt` | | 4: недоступность Redis и БД | `test_dependencies.py` | 503 `unavailable` за ограниченное время, аноним получает 401, после восстановления прежний токен и данные на месте | `evidence/05-failures.txt` | | Возможности lab1: непривилегированный пользователь, закреплённые версии, SIGTERM | `docker compose exec api id`, `scripts/sigterm_check.py` | `uid=10001(app)`; начатый запрос получил 201, выход за 1,45 с с кодом 0 | `evidence/07-containers.txt`, `evidence/08-sigterm.txt` | ## Эксперименты и отказы Нагрузочное исследование (трек 5) не проводилось. ### Индекс истории Гипотеза: индекс `(chat_id, created_at, id)` позволяет читать любую страницу истории за число обращений к диску, не зависящее от длины истории и от положения страницы. Методика: `scripts/seed_history.sql` создаёт 21 чат и 60 000 сообщений, из них 10 000 в исследуемом чате, остальные 50 000 поровну в 20 других; затем `ANALYZE`. `scripts/explain_history.sql` выполняет `EXPLAIN (ANALYZE, BUFFERS)` для четырёх запросов с `LIMIT 51` (страница 50 плюс одна строка). Данные небольшие и целиком в кэше, поэтому сравнивать нужно число буферов, а не миллисекунды. | Запрос | План | Буферов | Время выполнения | | --- | --- | --- | --- | | первая страница | Index Scan по `messages_chat_history_idx` | 8 | 0,025 мс | | страница после 5000-го сообщения, keyset | Index Scan, условие на `(created_at, id)` внутри Index Cond | 8 | 0,034 мс | | та же страница через `OFFSET 5000` | Index Scan, прочитано 5051 строка | 491 | 0,469 мс | | keyset без индекса | Seq Scan всей таблицы (отброшено 55 140 строк) и сортировка | 862 | 2,266 мс | Вывод: с индексом и keyset страница из середины стоит столько же, сколько первая, сортировка не нужна. OFFSET читает все пропущенные строки, и стоимость растёт с номером страницы. Без индекса каждая страница читает всю таблицу, включая чужие чаты. Ограничение измерения: одна таблица на 60 000 строк, один запуск, всё в памяти. Для вывода о реальной нагрузке этого мало. Четвёртый запрос выполняет `DROP INDEX` внутри транзакции с `ROLLBACK`: на это время таблица `messages` заблокирована, поэтому скрипт годится только для учебного стенда. ### Отказы | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | `docker compose restart postgres redis api` | данные и сессия на месте | прежний токен читает прежние сообщения | готов через несколько секунд, потерь нет | | `docker compose stop redis` | запросы с токеном не выполняются | 503 за 0,01 с; без токена 401; `/health/ready` 503, `/health/live` 200 | после `start redis` прежний токен работает, сообщение, отправленное во время отказа, не записано | | `docker compose stop postgres` | запросы к данным не выполняются | 503 за 3,0 с; без токена 401 | после `start postgres` данные на месте, запись снова работает | | сессия с TTL 2 с | через 2 с токен недействителен | через 3 с 401, logout с ним тоже 401, новый вход работает | — | | чат с несуществующим участником | ничего не создаётся | 400, в `chats` и `chat_members` следов нет | — | | 10 одновременных регистраций одного username | один пользователь | один 201, девять 409, одна строка | — | | SIGTERM процессу API | начатый запрос завершится | 201, новые соединения не принимаются, выход за 1,45 с | — | ## Ограничения и следующие шаги - Один экземпляр API, один PostgreSQL, один Redis на одном хосте. Отказ хоста, диска или любого из хранилищ не переживается, резервных копий нет. - При недоступном Redis не работает ни один запрос с токеном: запасного пути проверки сессии нет. Это осознанный выбор в пользу простоты и того, что отозванная сессия не может «ожить» из другого хранилища. - `appendfsync always` делает каждую запись сессии синхронной записью на диск. Для учебного стенда это незаметно, под нагрузкой вход станет узким местом. - Нет ограничения числа попыток входа и числа сессий на пользователя, код 429 не используется. - Порядок истории при параллельных вставках описан выше: возможен пропуск сообщения при обходе вперёд в окне длительности транзакции. - Если JSON синтаксически сломан, FastAPI отвечает 400 раньше, чем проверяется токен. На доступ к данным это не влияет. - При недоступной БД ответ 503 приходит через 3 секунды, а не сразу: столько запрос ждёт соединение из пула. - Пароли в `.env` лежат открытым текстом на диске разработчика (права 600). Для локального стенда с синтетическими данными это допустимо. - `make explain` оставляет в БД синтетические чаты и 60 000 сообщений; убрать их можно только `make clean`. - Проверено на одном стенде (macOS, Docker Desktop). На Linux не запускалось.