29 KiB
Отчёт — лабораторная 2
- Автор, группа: Мусаев Абдул-Хамид Рамзанович, БВТ-2303
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не заявлен
- Commit/PR: mtusi2026/mtusi2026lab2#27
- Использованные источники, библиотеки и помощь ИИ:
- библиотеки: 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; - помощь ИИ: ИИ-ассистент использовался во вспомогательных целях.
- библиотеки: 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 (полный список с версиями в
Запуск из чистого clone
Нужны Docker с Compose v2 (проверено на Docker 29.3.0, Compose 5.1.0), make, openssl, curl и Python 3.9+ на хосте для тестов. Сервер, PostgreSQL и Redis работают только в контейнерах.
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:
./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:<sha256 от токена>, значение — id пользователя. Сам токен в Redis не хранится, поэтому по дампу нельзя получить рабочий токен. - Expiry: ключ записывается командой
SET ... EX SESSION_TTL_SECONDS, срок отсчитывается от входа и запросами не продлевается. Истёкший ключ Redis удаляет сам. - Инвалидация: logout — это
DELключа текущей сессии. Другие сессии того же пользователя остаются. - Persistence: включён AOF с
appendfsync always, данные лежат в volumeredisdata. Сессия переживает перезапуск Redis, а оставшийся TTL при этом не увеличивается (evidence/04-redis-sessions.txt: 3591 с до перезапуска, 3583 с после). - Политика вытеснения —
noeviction: при нехватке памяти Redis откажет в записи новой сессии, но не удалит действующие. - После
FLUSHALLили удаления volumeredisdataвсе сессии пропадают: каждый токен получит 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 до её появления.
Пагинация и порядок
Запрос истории:
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] последней выданной записи; область привязывает его к конкретному чату или к списку чатов конкретного пользователя. Разбор строгий: посторонние символы в base64 не пропускаются, внутри должен быть список ровно из трёх строк, время — в формате сервера, id — UUID в каноническом виде; затем cursor кодируется заново и сравнивается с присланным. Любое отклонение даёт 400 invalid_request. Запрашивается 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), собственные тесты.
Исправлено по замечанию к lab1: некорректный cursor мог вернуть 200 (посторонние символы в base64, неканоничные время и UUID); теперь он всегда даёт 400, проверка — тест test_cursor_format_is_checked.
Изменено: хранилище в памяти заменено на 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. Файл evidence/02-student-tests.txt получен заново на commit 31530fc после ужесточения проверки cursor.
| Критерий 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 не запускалось.