22 KiB
Отчёт — лабораторная 2
- Автор, группа: Соколова Полина БВТ2304
- Целевая оценка: 4
- Трек уровня 5: не выполняется
- Commit/PR: добавить после публикации Проверки выполнены на локальном стенде; результаты сохранены в каталоге evidence/.
Запуск из чистого clone
Требования и версии
Стенд разрабатывался и проверялся в Debian 12 под WSL 2.
Использованные версии:
- Docker Engine: 20.10.24+dfsg1.
- Docker Compose: v2.27.0.
- Базовый образ приложения: python:3.12.10-slim-bookworm.
- PostgreSQL: postgres:16.4-bookworm.
- Redis: redis:7.2.5-bookworm.
- Прямые зависимости Python закреплены в requirements.txt.
- Для публичных и собственных тестов на стороне хоста нужен Python 3.9+.
Внешний адрес API: http://localhost:18081. Внутри контейнера приложение слушает 0.0.0.0:8080.
Порт 18081 выбран из-за занятых портов 8080 и 8081 в локальном окружении.
Подготовка и запуск
Команды выполняются из корня репозитория:
cp .env.example .env
В новом локальном .env необходимо заменить POSTGRES_PASSWORD=CHANGE_ME_LOCAL_ONLY отдельным учебным паролем. Файл .env не добавляется в Git.
После настройки:
docker compose --env-file .env config --quiet
docker compose --env-file .env build api
docker compose --env-file .env up -d --wait api redis
docker compose ps -a
curl -i http://localhost:18081/health/live
curl -i http://localhost:18081/health/ready
Compose запускает PostgreSQL, одноразовый сервис migrate и API. API зависит от готовности PostgreSQL и успешного завершения migrate. Redis запускается явно в приведённой команде.
Миграции находятся в migrations/. Программа app/migrate.py хранит применённые версии и контрольные суммы в schema_migrations.
Повторный запуск:
docker compose --env-file .env run --rm migrate
Для уже применённого файла выводится:
Already applied: 001_initial.sql
Migrations committed successfully
Повторная миграция не создаёт дубликаты таблиц и данных. Изменение применённого SQL-файла обнаруживается по контрольной сумме. Изменения схемы следует добавлять новой миграцией.
Проверки
make check
make test BASE_URL=http://localhost:18081
make test-persistence \
BASE_URL=http://localhost:18081 \
ACTION_SCRIPT=scripts/restart.sh
make test-lab2 BASE_URL=http://localhost:18081
make test-lab2 последовательно запускает:
- make test-extra — шесть собственных проверок;
- make test-faults — отказы зависимостей и короткий TTL.
Сценарий test-faults управляет локальным Compose-стендом. Его нельзя запускать параллельно с другими проверками или направлять на произвольный удалённый сервер.
Проверка индекса:
docker compose exec -T postgres \
psql -X -U messenger -d messenger -v ON_ERROR_STOP=1 \
< scripts/explain_history.sql
Перед этим должен пройти smoke или собственные тесты: SQL-сценарий использует одного существующего пользователя.
Каждый запуск SQL-сценария создаёт новый чат и 10 000 сообщений.
Остановка и удаление данных
Остановка без удаления данных:
docker compose --env-file .env stop
Удаление контейнеров и сети с сохранением именованных volumes:
docker compose --env-file .env down
Только для намеренного полного сброса учебных данных:
docker compose --env-file .env down --volumes
Последняя команда удаляет volumes PostgreSQL и Redis. Она не применяется в persistence-проверках.
Инструкция запуска подготовлена для нового окружения. Отдельный эксперимент запуска из чистого clone с новыми volumes на момент заполнения отчёта не выполнен.
Архитектура и решения
Компоненты
Клиент
|
| HTTP, localhost:18081
v
FastAPI
|-- PostgreSQL: источник истины
|-- Redis: кэш публичных данных пользователя
В PostgreSQL находятся:
- users — пользователи и хеши паролей;
- chats — чаты;
- chat_members — участники;
- messages — сообщения;
- sessions — хеши токенов и сроки действия сессий;
- schema_migrations — история применения миграций.
Приложение не хранит обязательное состояние в локальных словарях. Для PostgreSQL и Redis настроены отдельные именованные volumes.
Порты хранилищ не публикуются на хосте. API опубликован только на 127.0.0.1.
Изменения относительно лабораторной 1
Сохранены операции пользователей, чатов, сообщений и история.
Изменено:
- in-memory хранилище заменено PostgreSQL;
- при регистрации требуется password;
- вход выполняется через Basic;
- бизнес-запросы используют Bearer вместо X-User-Id;
- добавлены expiry и logout;
- добавлены Redis, миграции и проверки отказов;
- пагинация выполняется SQL-запросом, без загрузки всей истории.
Аутентификация и сессии
Пароли хешируются библиотекой argon2-cffi с Argon2id. PasswordHasher использует параметры:
- time_cost=3;
- memory_cost=65536 KiB;
- parallelism=4;
- hash_len=32;
- salt_len=16.
Basic credentials декодируются как UTF-8. Разделение username:password выполняется по первому двоеточию, поэтому двоеточия внутри пароля сохраняются.
Токен сессии генерируется secrets.token_urlsafe(32): используется 32 случайных байта. Клиент получает исходный токен, в PostgreSQL сохраняется SHA-256 токена.
SHA-256 применяется к случайным токенам и файлам миграций, но не заменяет password KDF.
Срок действия проверяется по времени PostgreSQL. Истёкшая строка sessions не даёт доступ, даже если физически ещё не удалена. Logout удаляет текущую сессию.
X-User-Id не используется для аутентификации. Сессии сохраняются в PostgreSQL и переживают проверенный рестарт.
Роль Redis
Redis содержит только публичные поля пользователя: id, username, display_name, created_at.
Политика:
- источник истины — PostgreSQL;
- TTL кэша по умолчанию — 60 секунд;
- пароли, хеши паролей и токены не кэшируются;
- действительность сессии проверяется в PostgreSQL до чтения кэша;
- при отказе Redis профиль читается из PostgreSQL;
- при отказе PostgreSQL кэш не заменяет проверку сессии;
- изменение и удаление профиля отсутствуют в обязательном API, поэтому в текущем контракте используется истечение по TTL.
Для Redis включён AOF с appendfsync everysec. Сохранность сессий не зависит от Redis: они находятся в PostgreSQL.
Транзакции и ограничения
В БД определены первичные и внешние ключи, уникальность username и ограничения длины полей.
Составной внешний ключ messages(chat_id, sender_id) ссылается на chat_members(chat_id, user_id).
Создание чата и добавление всех участников выполняются в одной транзакции. Ошибка участника откатывает всю операцию.
При регистрации конкурентная уникальность обеспечивается ограничением users_username_unique. Конфликт username возвращается как HTTP 409.
Ответ об успешной записи формируется после выхода из транзакционного блока с успешным COMMIT.
Соединения и таймауты
Используется AsyncConnectionPool:
- min_size=1;
- max_size=5 на процесс API;
- ожидание соединения — 3 секунды;
- max_waiting=20;
- connect_timeout=3 секунды;
- statement_timeout=3000 ms;
- lock_timeout=2000 ms;
- idle_in_transaction_session_timeout=10000 ms.
Значения SQL передаются параметрами, а не конкатенацией пользовательского ввода.
Redis:
- socket_connect_timeout=0.2 секунды;
- socket_timeout=0.2 секунды;
- max_connections=10.
Эти настройки не являются единой жёсткой границей времени любого HTTP-запроса. В сценарии отказов отдельно проверяется локальный бюджет запроса менее 10 секунд.
Пагинация и конкурентные вставки
История сортируется по (created_at, id). Курсор содержит эту пару и область запроса. Курсор другого чата отклоняется.
Запрашивается limit + 1 строка для определения next_cursor. Для неизменной истории продолжение использует строгое сравнение >, поэтому последняя строка предыдущей страницы не повторяется.
Между HTTP-запросами общий snapshot не поддерживается. При конкурентных вставках новая запись с ключом больше текущего курсора может попасть в последующие страницы. Запись с ключом не больше уже пройденного курсора может быть пропущена текущим обходом.
Время назначается сервером БД через clock_timestamp(). Часы не являются уникальным идентификатором или гарантией порядка COMMIT; для разрешения одинакового времени используется id.
Конфигурация
.env.example соответствует реализации:
| Переменная | Назначение |
|---|---|
| POSTGRES_PASSWORD | Пароль PostgreSQL; передаётся приложению как PGPASSWORD |
| SESSION_TTL_SECONDS | Срок действия новых сессий, по умолчанию 3600 |
| USER_CACHE_TTL_SECONDS | TTL кэша пользователя, по умолчанию 60 |
Адреса и имена сервисов заданы в compose.yaml. Реальные credentials и .env не включаются в репозиторий.
Доказательства критериев
| Критерий | Команда / сценарий | Наблюдаемый результат | Доказательство |
|---|---|---|---|
| Структура и синтаксис | make check | PASS; приложение этой проверкой не тестируется | Вывод команды |
| Публичный API | make test BASE_URL=http://localhost:18081 | PASS: lab2 public API scenario | evidence/smoke-final.txt |
| Миграции | Повторный запуск migrate | Already applied; в schema_migrations одна версия 001_initial.sql | Вывод миграции и SELECT |
| Сохранность данных и сессии | make test-persistence с scripts/restart.sh | PASS: confirmed data and existing session preserved | Результат теста; evidence/persistence-before.txt и persistence-after.txt |
| Реальный рестарт API и хранилищ | Сравнение StartedAt | Время запуска изменилось у API, PostgreSQL и Redis | evidence/persistence-before.txt; evidence/persistence-after.txt |
| Гонка username | Четыре конкурентные регистрации | Один 201 и три 409; вход созданного пользователя успешен | evidence/lab2-final.txt |
| Атомарность чата | Создание с неизвестным участником | 400; количество чатов и участников не изменилось; следующая валидная операция успешна | evidence/lab2-final.txt |
| Logout | Отзыв и повторное использование токена | 204 без тела; последующее чтение и повторный logout дают 401 | evidence/lab2-final.txt |
| Неверный пароль | Вход с неправильным паролем и неизвестным username | Одинаковый 401 и сообщение | evidence/lab2-final.txt |
| Unicode и двоеточия | Регистрация и вход с таким паролем | Успешный вход | evidence/lab2-final.txt |
| X-User-Id | Запрос без Bearer и попытка смены пользователя | Без токена 401; с токеном владелец не меняется | evidence/lab2-final.txt |
| Короткий expiry | SESSION_TTL_SECONDS=2 | Сначала 200, затем 401 | evidence/lab2-final.txt |
| Отказ Redis | Остановка Redis | Действующий токен работает через PostgreSQL; анонимный доступ запрещён | evidence/lab2-final.txt |
| Отказ PostgreSQL | Остановка БД при заполненном кэше | Защищённый запрос 503; live 200; ready 503; без токена 401 | evidence/lab2-final.txt |
| Возврат PostgreSQL | Запуск БД после отказа | Прежняя сессия снова работает | evidence/lab2-final.txt |
| Индекс истории | EXPLAIN на 10 000 сообщениях | Index Scan для первой и средней страницы | evidence/explain-history.txt |
| Pool и безопасные SQL-запросы | Проверка реализации | Ограниченный пул, таймауты, параметры SQL | app/db.py; app/store.py |
Эксперименты и отказы
Persistence
Тест завершился:
PASS: persistence preserved confirmed data and existing session.
Зафиксированные времена запуска до и после:
| Сервис | До, UTC | После, UTC |
|---|---|---|
| API | 14:33:23 | 14:38:37 |
| PostgreSQL | 11:25:08 | 14:38:30 |
| Redis | 11:25:08 | 14:38:30 |
Дата эксперимента: 2026-10-16. Полные временные метки находятся в evidence/.
Скрипт перезапускает API и оба используемых хранилища, не удаляя volumes и не подменяя тестовые данные.
Отказы и expiry: финальный запуск
| Воздействие | Наблюдение |
|---|---|
| Остановка Redis | Fallback успешен; защищённый запрос 0.140 s |
| Остановка PostgreSQL | Защищённый запрос получил 503 за 3.006 s |
| Возврат PostgreSQL | Прежняя сессия восстановила доступ |
| TTL=2 | Отказ по expiry наблюдался через 2.067 s после начала наблюдения |
| Завершение теста | PostgreSQL и Redis запущены, API healthy, TTL=3600 |
Это одиночный локальный сценарий, не статистическое измерение задержек и не production SLA. Полное время восстановления от момента запуска зависимости отдельно не измерялось.
Шесть собственных проверок в финальном запуске: Ran 6 tests in 1.384s; OK.
Индекс истории
Набор: 10 000 сообщений в одном чате, 1 000 различных created_at, по десять сообщений на временную метку.
Индекс:
CREATE INDEX messages_chat_created_id_idx
ON messages (chat_id, created_at, id);
Перед измерением выполнено ANALYZE messages.
| Запрос | План | Строки | Shared hit | Execution Time |
|---|---|---|---|---|
| Первая страница | Index Scan | 51 | 3 | 0.025 ms |
| Страница после курсора около середины | Index Scan | 51 | 9 | 0.052 ms |
У второй страницы условие по (created_at, id) входит в Index Cond. Отдельного Sort нет.
OFFSET используется только для подготовки контрольного курсора в эксперименте, но не в запросах страниц приложения.
Показанные времена относятся к SQL-запросам на данном наборе, а не к HTTP API. В плане указаны shared hits; холодный кэш отдельно не исследовался.
Нагрузочное исследование RPS, p50/p95/p99 и потребления CPU/RAM не проводилось. Лимиты CPU/RAM сервисов в Compose не заданы. Исследовательские треки уровня 5 не заявляются.
Ограничения и следующие шаги
- По одному экземпляру API, PostgreSQL и Redis. Высокая доступность не реализована.
- При отказе PostgreSQL обязательный путь недоступен; API возвращает контролируемую ошибку.
- Redis является необязательным для корректности кэшем.
- Проверен штатный рестарт с сохранением volumes, не потеря диска, авария питания или повреждение данных.
- HTTP применяется только для локального изолированного стенда с синтетическими данными.
- Постраничный обход не является snapshot всей истории.
- Устаревшие строки sessions автоматически не очищаются, но не проходят проверку expiry.
- Нет rate limiting, вложений и фоновых workers: они не входят в обязательную реализацию этой лабораторной.
- Теги образов и прямые зависимости закреплены; digest образов и полный lock транзитивных зависимостей не добавлены.
- Проверки не являются полным security/fuzz/load suite.
- Нельзя заявлять запуск из чистого clone как выполненный эксперимент без отдельной проверки.
Использованные материалы и библиотеки
- Задание README.md и contracts/README.md.
- contracts/openapi.json и публичные tests/.
- Документация Docker Compose.
- Документация PostgreSQL: ограничения, транзакции, индексы и EXPLAIN.
- Документация Psycopg 3 и psycopg-pool.
- Документация redis-py.
- Документация argon2-cffi.
- FastAPI, Uvicorn и стандартная библиотека Python.