diff --git a/REPORT.md b/REPORT.md index e42f2b05..a008c8d6 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,173 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- **Автор, группа:** Травкин С.А., БВТ2304. +- **Целевая оценка; выбранный трек 5, если нужен:** 4. Трек 5 пока не заявлен. +- **Commit/PR:** указать после публикации. +- **Использованные источники, библиотеки и помощь ИИ:** README и API-контракт лабораторной; документация PostgreSQL, Redis, SQLAlchemy, Alembic, FastAPI и Docker Compose. Использованы Python, FastAPI, SQLAlchemy, asyncpg, Alembic, PostgreSQL 17.6, Redis 8.2.2, Argon2id. ChatGPT использовался для разбора задания, разработки и проверки реализации, тестов и оформления отчёта. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Необходимы Docker Engine, Docker Compose, Git и Python 3.9+ для публичных тестов. Приложение запускается в контейнерах; локально использовался Python 3.13. + +После клонирования репозитория перейти в его каталог и создать локальную конфигурацию: + +```bash +cp .env.example .env +mkdir -p secrets +chmod 700 secrets +``` + +Создать согласованные файлы секретов: + +```bash +python3 - <<'PY' +from pathlib import Path +import secrets + +directory = Path("secrets") +password = secrets.token_hex(24) + +values = { + "postgres_password": password, + "database_url": f"postgresql+asyncpg://lab2:{password}@postgres:5432/messenger", + "cache_url": "redis://redis:6379/0", +} + +for name, value in values.items(): + path = directory / name + path.write_text(value, encoding="utf-8") + path.chmod(0o600) + +print("Local secrets created.") +PY +``` + +Секреты создаются только при первоначальной настройке пустой базы. Пароли и строки подключения не выводятся в терминал и не добавляются в Git. + +Сборка и запуск: + +```bash +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build +``` + +Используются образы PostgreSQL 17.6 и Redis 8.2.2. API собирается из локального `Dockerfile`. Сервис `migrate` автоматически выполняет `alembic upgrade head` после готовности PostgreSQL. API запускается после успешного завершения миграций и готовности Redis. + +Проверка: + +```bash +docker compose ps -a +curl -i http://localhost:8080/health/ready +make check +make test +``` + +Ожидаемый ответ `/health/ready` — HTTP 200, `{"status":"ok"}`. + +Дополнительные проверки: + +```bash +python3 -m venv .venv +.venv/bin/python -m pip install -r requirements-dev.txt +make validate PYTHON=.venv/bin/python +make test-persistence ACTION_SCRIPT=scripts/restart.sh +``` + +Собственные тесты: + +```bash +python tests_student/test_auth.py +python tests_student/test_race.py +./scripts/test_short_ttl.sh +./scripts/test_failures.sh +``` + +Откат транзакции проверяется внутри контейнера: + +```bash +docker compose run --rm --no-deps \ + -e PYTHONPATH=/app \ + -v "$PWD/tests_student:/app/tests_student:ro" \ + api python tests_student/test_rollback.py +``` + +Безопасная остановка с сохранением данных: + +```bash +docker compose down +``` + +Намеренное удаление учебных данных вместе с volumes: + +```bash +docker compose down -v +``` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Схема: **клиент → FastAPI → PostgreSQL / Redis**. + +PostgreSQL — источник истины для пользователей, чатов, участников и сообщений. Redis используется для хранения сессий с TTL. + +В PostgreSQL созданы таблицы `users`, `chats`, `chat_members`, `messages`. Используются UUID, первичные и внешние ключи, уникальность `username`. Для истории сообщений создан индекс `(chat_id, created_at, id)`. + +Создание чата и добавление участников выполняются в одной транзакции. При ошибке изменения откатываются. Это проверено тестом `test_rollback.py`. + +Из лабораторной № 1 сохранены основные операции мессенджера. Вместо хранения данных в памяти используется PostgreSQL. Добавлены пароли с Argon2id, вход через Basic, случайные Bearer-токены, TTL и logout. Заголовок `X-User-Id` больше не предоставляет доступ. + +Redis хранит ключи `session:` с UUID пользователя. При logout ключ удаляется, при истечении TTL становится недействительным. Включены AOF (`appendonly yes`, `appendfsync everysec`) и named volume `redis_data`. PostgreSQL использует named volume `postgres_data`. + +SQL-запросы параметризованы. Пул SQLAlchemy: `pool_size=5`, `max_overflow=5`, `pool_timeout=5` секунд, таймаут подключения — 5 секунд. Для Redis установлены таймауты подключения и операций по 5 секунд. + +Соответствие `.env.example` конфигурации: `APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE` передаются сервису API через Compose. URL подключений читаются из файлов `/run/secrets/database_url` и `/run/secrets/cache_url`. Пароль PostgreSQL читается из `/run/secrets/postgres_password`. Значение `SESSION_STORE=redis` соответствует используемому хранилищу сессий. + +Миграции Alembic запускаются отдельным сервисом `migrate`. Проверен запуск на пустых volumes и создание схемы с нуля. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Публичный smoke | `make test` | PASS, публичный API-сценарий выполнен | `evidence/grade4_checks.txt` | +| Проверка структуры и контракта | `make check`, `make validate` | Обе проверки PASS | `evidence/grade4_checks.txt` | +| Постоянное хранение данных и сессий | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Данные и прежний токен сохранились | `evidence/grade4_resilience.txt` | +| Перезапуск всех сервисов | `scripts/restart.sh` | `docker compose down` и `up -d` без удаления volumes; ожидание готовности PostgreSQL, Redis и API | `scripts/restart.sh` | +| PostgreSQL, ключи и ограничения | `alembic upgrade head`, запуск с пустыми volumes | Схема создана, таблицы и ограничения применены | `migrations/versions/f7c51e1e945b_initial_schema.py` | +| Атомарность создания чата | `test_rollback.py` | PASS, частичные изменения отсутствуют | `evidence/grade4_checks.txt` | +| Basic, Bearer, неверный пароль и logout | `test_auth.py`, `make test` | Неверный пароль — 401; logout — 204; отозванный токен — 401 | `evidence/grade4_checks.txt` | +| Redis для сессий с TTL и persistence | Перезапуск Redis в `test_failures.sh` | Прежний действующий токен работает после восстановления | `evidence/grade4_resilience.txt` | +| Ограниченный пул и таймауты | Конфигурация SQLAlchemy и Redis | Пул 5+5, таймауты заданы | `src/database.py`, `src/sessions.py` | +| Конкурентная регистрация | `test_race.py` | Одна регистрация — 201, вторая — 409 | `evidence/grade4_checks.txt` | +| Индекс истории и пагинация | `EXPLAIN (ANALYZE, BUFFERS)` на 20 000 сообщениях | Keyset: 100 строк Index Scan против 15 100 у OFFSET | `evidence/explain_history.txt` | +| Короткий TTL | `test_short_ttl.sh` | Токен истёк, получен 401 | `evidence/grade4_resilience.txt` | +| Отказ Redis | `test_failures.sh` | Readiness — 503, защищённый запрос — 503, после восстановления — 200 | `evidence/failure_timings.txt` | +| Отказ PostgreSQL | `test_failures.sh` | Readiness — 503, защищённый запрос — 503, после восстановления — 200 | `evidence/failure_timings.txt` | +| Секреты вне Git | Проверка `.gitignore` | `.env`, `secrets/`, volumes и backups исключены | `.gitignore` | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +**Эксперимент с индексом.** Гипотеза: keyset-пагинация с составным индексом эффективнее OFFSET при чтении глубокой страницы истории. Подготовлено 20 000 синтетических сообщений одного чата. После `ANALYZE` выполнены два запроса с `EXPLAIN (ANALYZE, BUFFERS)` для получения 100 сообщений после первых 15 000. + +Результаты: OFFSET — 1,908 мс, 435 shared buffer hits, 15 100 строк Index Scan; keyset — 0,053 мс, 7 shared buffer hits, 100 строк Index Scan. В данном прогоне keyset оказался примерно в 36 раз быстрее. Полный результат — `evidence/explain_history.txt`. + +**Проверки отказов.** Использован локальный стенд Docker Compose в WSL. PostgreSQL 17.6, Redis 8.2.2, один API-контейнер. Создавался тестовый пользователь и действующая сессия. Зависимости останавливались по очереди, HTTP-ответы измерялись через `curl %{time_total}`. Выполнено два прогона сценария отказов. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Штатный перезапуск API, PostgreSQL и Redis | Сохранение данных и действующей сессии | `make test-persistence` — PASS | Потеря подтверждённых данных не обнаружена; время не измерялось | +| Остановка Redis | 503 без анонимного доступа | `/health/ready` и `/users/me` — 503; `/health/live` — 200 | Ответ `/users/me`: 4,006 и 8,000 с; после восстановления прежний токен работает; точное время восстановления не измерялось | +| Остановка PostgreSQL | 503 без необработанной ошибки | `/health/ready` и `/users/me` — 503; `/health/live` — 200 | Ответ `/users/me`: 4,006 и 4,008 с; после восстановления — 200; точное время восстановления не измерялось | +| Истечение TTL | Отказ в доступе | После TTL=2 секунды получен 401 | Сессия становится недействительной | +| Конкурентная регистрация | Уникальность username | Один 201, один 409 | Дублирования username нет | +| Ошибка составной операции | Полный rollback | Частично созданных записей нет | Частичные изменения откатились | + +Время обработки отказных запросов оказалось ограниченным в проведённых тестах, но строгая максимальная задержка на уровне сервера не доказана. Отдельный нагрузочный эксперимент с RPS, p50/p95/p99, CPU/RAM, заданной интенсивностью запросов и прогревом не проводился. Поэтому такие метрики не приводятся. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Приложение сохраняет данные и действующие сессии после проверенного штатного перезапуска с сохранением volumes. При недоступности PostgreSQL или Redis возвращается 503, после восстановления работа продолжается. Автоматического переключения на резервные экземпляры нет. + +Redis AOF с `appendfsync everysec` не гарантирует отсутствие потери последних изменений при аварийном сбое. Удаление volumes приводит к потере локальных данных. Резервное копирование и восстановление в новое хранилище пока не реализованы. + +Эффективность keyset-пагинации подтверждена одним экспериментом на 20 000 сообщениях. Результаты не следует переносить на любую нагрузку без дополнительных измерений. Стоимость записи при разных индексах не исследовалась. + +В дальнейшем планируется выполнить трек 2 для оценки 5: эксперимент на 100 000+ сообщениях с неравномерным распределением по чатам, сравнение индексов и стоимости вставки, backup и восстановление в новое хранилище с проверкой данных. \ No newline at end of file diff --git a/evidence/failure_timings.txt b/evidence/failure_timings.txt new file mode 100644 index 00000000..387b0b50 --- /dev/null +++ b/evidence/failure_timings.txt @@ -0,0 +1,39 @@ +Waiting for API readiness before testing... +Creating a test user and session... +Test session created. + +Checking baseline... +PASS: /health/live returned 200 in 0.001683s +PASS: /health/ready returned 200 in 0.003160s +PASS: /api/v1/users/me returned 200 in 0.002653s + +=== Redis failure === + Container mtusi2026lab2-redis-1 Stopping + Container mtusi2026lab2-redis-1 Stopped +PASS: /health/live returned 200 in 0.001606s +PASS: /health/ready returned 503 in 4.006407s +PASS: /api/v1/users/me returned 503 in 4.006094s +Restarting Redis... + Container mtusi2026lab2-redis-1 Starting + Container mtusi2026lab2-redis-1 Started +PASS: /health/ready returned 200 in 0.002260s +PASS: /api/v1/users/me returned 200 in 0.002382s + +=== PostgreSQL failure === + Container mtusi2026lab2-postgres-1 Stopping + Container mtusi2026lab2-postgres-1 Stopped +PASS: /health/live returned 200 in 0.001882s +PASS: /health/ready returned 503 in 4.007958s +PASS: /api/v1/users/me returned 503 in 4.006373s +Restarting PostgreSQL... + Container mtusi2026lab2-postgres-1 Starting + Container mtusi2026lab2-postgres-1 Started +PASS: /health/ready returned 200 in 0.002324s +PASS: /api/v1/users/me returned 200 in 0.012524s + +PASS: dependency failure and recovery tests completed. +Restoring PostgreSQL and Redis... + Container mtusi2026lab2-postgres-1 Running + Container mtusi2026lab2-redis-1 Running +Waiting for API readiness... +Services restored. diff --git a/evidence/grade4_checks.txt b/evidence/grade4_checks.txt new file mode 100644 index 00000000..691be8f7 --- /dev/null +++ b/evidence/grade4_checks.txt @@ -0,0 +1,22 @@ +=== make check === +python3 scripts/check_contract.py +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. + +=== make validate === +.venv/bin/python scripts/validate_openapi.py +PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested. + +=== make test === +python3 tests/smoke.py --base-url "http://localhost:8080" +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. + +=== test_auth === +PASS: wrong password returned 401; valid session worked; logout revoked the token. + +=== test_race === +PASS: concurrent registration produced exactly one 201 and one 409. + +=== test_rollback === + Container mtusi2026lab2-api-run-8eb3c54add45 Creating + Container mtusi2026lab2-api-run-8eb3c54add45 Created +PASS: failed compound transaction rolled back chat and membership inserts. diff --git a/evidence/grade4_resilience.txt b/evidence/grade4_resilience.txt new file mode 100644 index 00000000..5653d85c --- /dev/null +++ b/evidence/grade4_resilience.txt @@ -0,0 +1,66 @@ +=== persistence === +python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8080" +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. + +=== short TTL === +Starting API with SESSION_TTL_SECONDS=2... + Container mtusi2026lab2-api-1 Recreate + Container mtusi2026lab2-api-1 Recreated + Container mtusi2026lab2-api-1 Starting + Container mtusi2026lab2-api-1 Started +Checking API configuration... +Waiting for API readiness... +Running short TTL test... +PASS: token works immediately after login. +PASS: expired token returned 401. +PASS: short session TTL test completed. +Restoring API with SESSION_TTL_SECONDS=3600... + Container mtusi2026lab2-api-1 Recreate + Container mtusi2026lab2-api-1 Recreated + Container mtusi2026lab2-api-1 Starting + Container mtusi2026lab2-api-1 Started + +=== dependency failures === +Waiting for API readiness before testing... +Creating a test user and session... +Test session created. + +Checking baseline... +PASS: /health/live returned 200 in 0.002339s +PASS: /health/ready returned 200 in 0.003825s +PASS: /api/v1/users/me returned 200 in 0.004731s + +=== Redis failure === + Container mtusi2026lab2-redis-1 Stopping + Container mtusi2026lab2-redis-1 Stopped +PASS: /health/live returned 200 in 0.002183s +PASS: /health/ready returned 503 in 4.007097s +PASS: /api/v1/users/me returned 503 in 8.000377s +Restarting Redis... + Container mtusi2026lab2-redis-1 Starting + Container mtusi2026lab2-redis-1 Started +PASS: /health/ready returned 200 in 0.002200s +PASS: /api/v1/users/me returned 200 in 0.003519s + +=== PostgreSQL failure === + Container mtusi2026lab2-postgres-1 Stopping + Container mtusi2026lab2-postgres-1 Stopped +PASS: /health/live returned 200 in 0.002847s +PASS: /health/ready returned 503 in 4.006891s +PASS: /api/v1/users/me returned 503 in 4.008468s +Restarting PostgreSQL... + Container mtusi2026lab2-postgres-1 Starting + Container mtusi2026lab2-postgres-1 Started +PASS: /health/ready returned 200 in 0.003164s +PASS: /api/v1/users/me returned 200 in 0.006318s + +PASS: dependency failure and recovery tests completed. +Restoring PostgreSQL and Redis... + Container mtusi2026lab2-postgres-1 Running + Container mtusi2026lab2-redis-1 Running +Waiting for API readiness... +Services restored. + +=== final readiness === +{"status":"ok"} diff --git a/scripts/test_failures.sh b/scripts/test_failures.sh index 4b1a1be0..47fd5b38 100755 --- a/scripts/test_failures.sh +++ b/scripts/test_failures.sh @@ -26,32 +26,53 @@ restore_services() { trap restore_services EXIT +echo "Waiting for API readiness before testing..." + +api_ready=false + +for attempt in $(seq 1 60); do + if curl --silent --fail --max-time 3 \ + "$BASE_URL/health/ready" > /dev/null; then + api_ready=true + break + fi + + sleep 1 +done + +if [[ "$api_ready" != "true" ]]; then + echo "FAIL: API did not become ready before testing." >&2 + exit 1 +fi + check_status() { local expected="$1" local path="$2" local authorization="${3:-}" - local status + local result actual_status elapsed if [[ -n "$authorization" ]]; then - status=$(curl --silent --output /dev/null \ + result=$(curl --silent --output /dev/null \ --max-time 12 \ - --write-out "%{http_code}" \ + --write-out "%{http_code} %{time_total}" \ -H "Authorization: Bearer $authorization" \ "$BASE_URL$path") else - status=$(curl --silent --output /dev/null \ + result=$(curl --silent --output /dev/null \ --max-time 12 \ - --write-out "%{http_code}" \ + --write-out "%{http_code} %{time_total}" \ "$BASE_URL$path") fi - if [[ "$status" != "$expected" ]]; then - echo "FAIL: $path expected $expected, got $status" >&2 + read -r actual_status elapsed <<< "$result" + + if [[ "$actual_status" != "$expected" ]]; then + echo "FAIL: $path expected $expected, got $actual_status" >&2 exit 1 fi - echo "PASS: $path returned $status" + echo "PASS: $path returned $actual_status in ${elapsed}s" } echo "Creating a test user and session..."