From 5a745e6434b417d7ccb32f01f3c1ed4b183dcdf1 Mon Sep 17 00:00:00 2001 From: Sona Date: Tue, 3 Nov 2026 12:13:58 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9B=D0=A0=202:=20=D0=BE=D1=82=D1=87=D1=91?= =?UTF-8?q?=D1=82=20=D0=B8=20=D0=B8=D1=82=D0=BE=D0=B3=D0=BE=D0=B2=D1=8B?= =?UTF-8?q?=D0=B5=20=D0=B4=D0=BE=D0=BA=D0=B0=D0=B7=D0=B0=D1=82=D0=B5=D0=BB?= =?UTF-8?q?=D1=8C=D1=81=D1=82=D0=B2=D0=B0=20(=D1=83=D1=80=D0=BE=D0=B2?= =?UTF-8?q?=D0=B5=D0=BD=D1=8C=204)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 139 +++++++++++++++++++++++++++--- evidence/restart-after.txt | 7 +- evidence/restart-before.txt | 7 +- evidence/student-tests-level4.txt | 3 +- student_tests/test_level4.py | 16 ++++ 5 files changed, 151 insertions(+), 21 deletions(-) diff --git a/REPORT.md b/REPORT.md index e42f2b0..34bc7b9 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,148 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Саргсян Сона, БВТ2302 +- Целевая оценка: 4 +- Commit/PR: +- Использованные источники, библиотеки и помощь ИИ: Claude Code. Библиотеки: FastAPI, Pydantic, Uvicorn, asyncpg, argon2-cffi, redis-py (клиент для Valkey). ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Нужны Git, Docker с запущенным daemon (Compose v2), Make, Python 3.9+ (для публичных проверок, только стандартная библиотека) и `openssl`. Порты 8080 (API), 18080 (только SIGTERM-тест) должны быть свободны. При первой сборке нужен доступ к Docker Hub и PyPI. + +Версии: Python 3.12.7 (образ `python:3.12.7-slim`, закреплён digest), FastAPI 0.115.2, Pydantic 2.14.1, Uvicorn 0.32.0, asyncpg 0.30.0, argon2-cffi 23.1.0, redis-py 5.2.1, PostgreSQL 16.6 (`postgres:16.6-alpine`), Valkey 8.0.1 (`valkey/valkey:8.0.1-alpine`). Все runtime-зависимости закреплены в `requirements.txt`. + +Действия оператора (один раз). Секреты создаются локально и в Git не попадают (`secrets/` и `.env` в `.gitignore` и `.dockerignore`): + +```sh +mkdir -p secrets +PW=$(openssl rand -hex 24) +printf '%s' "$PW" > secrets/postgres_password +printf 'postgresql://messenger:%s@postgres:5432/messenger' "$PW" > secrets/database_url +chmod 644 secrets/* +cp .env.example .env +chmod +x scripts/restart.sh +``` + +Права 644 нужны, чтобы непривилегированный пользователь `app` в контейнере прочитал секрет; допустимо только для локального стенда с синтетическими данными. + +Сборка, миграции и запуск. Миграции применяет само приложение при старте (`src/db.py`), отдельного шага нет: + +```sh +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build +curl --fail --retry 20 --retry-connrefused --retry-delay 1 http://localhost:8080/health/ready +``` + +Проверки: + +```sh +make check +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +python3 student_tests/test_lab2.py +python3 student_tests/test_lifecycle.py +python3 student_tests/test_sigterm.py +python3 -m unittest discover -s student_tests -p "test_level4.py" -v +docker compose --env-file .env exec -T postgres psql -U messenger -d messenger < scripts/explain.sql +``` + +`test_level4.py` останавливает и запускает контейнеры valkey/postgres/api; volumes не удаляются. `test_sigterm.py` запускает отдельный контейнер API в сети compose (имя сети по умолчанию `mtusi-lab2_default`, переопределяется `COMPOSE_NETWORK`). + +Остановка с сохранением данных: `docker compose --env-file .env down`. Намеренное удаление учебных данных (БД и Valkey): `docker compose --env-file .env down -v`. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +Клиент ──HTTP──> API (FastAPI) ──> PostgreSQL 16 (volume pgdata) - источник истины + └────────> Valkey 8 (без persistence) — кэш сессий с TTL +``` + +**Источник истины.** PostgreSQL хранит пользователей, чаты, участников, сообщения и сессии (`migrations/001_init.sql`). Сессия — строка в `sessions`: SHA-256 токена (сам токен не хранится), `user_id`, `expires_at`, `revoked_at`. Токен - 256 бит случайности (`secrets.token_urlsafe(32)`). + +**Роль Valkey.** Кэш проверенных сессий: ключ `sess:`, значение - данные пользователя. Valkey запущен без persistence (`--save "" --appendonly no`), с лимитом памяти 64 МБ и политикой `allkeys-lru`. Потеря кэша (рестарт, `FLUSHALL`) ничего не теряет: следующий запрос получает данные из PostgreSQL и наполняет кэш заново. + +**Политика expiry и инвалидации кэша.** +- TTL записи = `min(остаток жизни сессии, CACHE_TTL_SECONDS=60)`, то есть кэш никогда не живёт дольше сессии. +- Logout: сначала `UPDATE sessions SET revoked_at` в PostgreSQL, затем `DEL` ключа в Valkey. +- Данные пользователя в кэше неизменяемы (в API нет редактирования), поэтому других причин инвалидации нет. +- Если Valkey недоступен, кэш обходится (любой сбой - промах); после сбоя обращения к кэшу приостанавливаются на 5 секунд, чтобы не ждать таймаут на каждом запросе. Readiness зависит только от PostgreSQL: Valkey - оптимизация, а не критичная зависимость. + +**Аутентификация.** `POST /auth/sessions` принимает только `Authorization: Basic`; остальные endpoint - только Bearer (зависимость `current_user`). `X-User-Id` не читается. Пароли хешируются Argon2id (argon2-cffi, параметры по умолчанию библиотеки), вычисление выполняется в thread pool. Для несуществующего пользователя проверка идёт по хешу-заглушке, ответ одинаковый 401. Это отличает password KDF (медленный, с солью, защищает слабые пароли от перебора) от быстрого checksum: токен имеет 256 бит случайности, поэтому для него достаточно SHA-256. + +**Транзакционные границы.** +- Создание чата: `INSERT chats` + `INSERT chat_members` в одной транзакции; неизвестный участник нарушает FK и откатывает всё. +- Отправка сообщения: проверка членства и `INSERT` - один оператор (`INSERT ... SELECT ... WHERE EXISTS`). +- Регистрация: гонку одинаковых username решает `UNIQUE`, приложение ловит `UniqueViolationError` и отвечает 409. +- Миграции: каждая в транзакции вместе с записью в `schema_migrations`, под `pg_advisory_lock`. + +**Что перенесено из lab1.** Структура приложения (middleware с `X-Request-Id`, формат ошибок, строгая валидация Pydantic, обработка SIGTERM), Dockerfile, собственные тесты (адаптированы под пароль/Bearer). **Что изменено.** In-memory словари заменены PostgreSQL; `X-User-Id` заменён Bearer; добавлены password KDF, сессии, Valkey, миграции, compose. Курсор пагинации теперь keyset `(created_at, id)`, непрозрачный и привязанный к ресурсу (раньше был ID записи). + +**Соответствие переменных `.env.example`.** + +| Переменная | Реализация | +| --- | --- | +| `APP_HOST`, `APP_PORT` | задаются в Dockerfile (0.0.0.0 / 8080) | +| `APP_ENV` | передаётся в контейнер, поведение не меняет | +| `SESSION_TTL_SECONDS` | срок жизни сессии (по умолчанию 3600) | +| `DATABASE_URL_FILE` | путь к секрету с адресом PostgreSQL | +| `SESSION_STORE` | не используется: сессии всегда в PostgreSQL, Valkey - кэш | +| `CACHE_URL_FILE` | поддерживается; в compose адрес Valkey передаётся через `CACHE_URL` (в нём нет секретов) | + +Дополнительно: `DB_POOL_MIN=2`, `DB_POOL_MAX=10`, `DB_CONNECT_TIMEOUT=5`, `DB_COMMAND_TIMEOUT=5`, `CACHE_TTL_SECONDS=60`, `CACHE_TIMEOUT=0.5`, `MIGRATIONS_DIR`. ## Доказательства критериев +Дата проверок: 03.11.2026; стенд: . + | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Публичный smoke | `make test` | PASS: lab2 public API scenario | `evidence/smoke.txt` | +| Данные и сессии переживают рестарт API и хранилищ без удаления volumes | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS; контейнеры postgres/valkey `Up 5 seconds`, api `Up Less than a second` после hook | `evidence/persistence.txt`, `evidence/restart-before.txt`, `evidence/restart-after.txt` | +| Полный жизненный цикл: тот же токен читает те же данные после рестарта, logout → 401 | `python3 student_tests/test_lifecycle.py` | PASS (7 проверок) | `evidence/lifecycle.txt` | +| Таблицы, PK/FK, UNIQUE username, миграции с нуля | `migrations/001_init.sql`, запуск с пустым volume | миграция применена | `evidence/migrations.txt` | +| Миграции повторно запускаются без дублирования | перезапуск стенда, `logs api \| grep migration` | одна строка `Applied migration 001_init.sql` за все рестарты | `evidence/migrations.txt` | +| Атомарность создания чата | `test_chat_creation_rolls_back` | чат с неизвестным участником → 400, `count(*)` в БД = 0 | `evidence/student-tests-level4.txt` | +| Basic только на `POST /auth/sessions`, Bearer на остальных, `X-User-Id` без доступа, срок жизни, отзыв | `test_lab2.py` (`test_validation_and_unicode`), `test_x_user_id_gives_no_access`, `test_logout_...`, `test_zz_session_expiry` | PASS | `evidence/student-tests.txt`, `evidence/student-tests-level4.txt` | +| Пароли хешируются KDF | `src/auth.py` (Argon2id), в БД только `password_hash` | см. код | `src/auth.py` | +| Secrets/volumes не в Git | `.gitignore`, `.dockerignore`, `git status` перед коммитом | `.env`, `secrets/` не отслеживаются | — | +| **4:** Valkey реально используется (сессии с TTL) | `valkey-cli keys 'sess:*'` после запросов; `test_valkey_flush_keeps_sessions` | ключи `sess:...` есть, после `FLUSHALL` сессия работает и кэш наполняется снова | `evidence/student-tests-level4.txt` | +| **4:** параметризованные запросы, ограниченный пул, таймауты | `src/db.py`, `src/chats.py` (все запросы с `$n`) | пул 2–10, таймауты соединения и команд 5 с | `src/db.py` | +| **4:** гонка регистрации | `test_register_race_same_username` | 10 параллельных POST: ровно один 201, девять 409 | `evidence/student-tests-level4.txt` | +| **4:** индекс истории + EXPLAIN на ≥10 000 сообщений | `scripts/explain.sql` | с индексом `messages_history_idx`: Index Scan, 3 страницы буфера и для первой страницы, и для страницы из середины истории (0.03 мс); без индекса: Seq Scan + сортировка, 123 страницы (0.9 мс) | `evidence/explain.txt` | +| **4:** expiry при коротком TTL, logout, неверный пароль | `test_zz_session_expiry` (TTL=2), `test_logout_...`, `test_wrong_password` | PASS | `evidence/student-tests-level4.txt` | +| **4:** недоступность Valkey и PostgreSQL | `test_valkey_down_falls_back_to_postgres`, `test_postgres_down_returns_bounded_error` | Valkey остановлен: запросы работают через PostgreSQL; PostgreSQL остановлен: `/health/ready` 503, неизвестный токен 503, запрос без токена 401, регистрация 503 | `evidence/student-tests-level4.txt` | +| Собственные тесты | `python3 student_tests/test_lab2.py` | PASS: 12 сценариев | `evidence/student-tests.txt` | +| Корректная остановка | `python3 student_tests/test_sigterm.py` | PASS: exit code 0, idle 0.34 с, с незавершённым POST 8.4 с | `evidence/sigterm.txt` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Трек 5 не заявлен. ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Объём данных EXPLAIN: 10 000 сообщений в одном чате, синтетика (`scripts/explain.sql`), PostgreSQL 16.6, все чтения из shared buffers (`shared hit`), диска нет. Замер единичный, прогрев не выполнялся, поэтому важно соотношение (3 страницы против 123), а не абсолютные миллисекунды. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Полный рестарт api + postgres + valkey (volumes сохранены) | токен и данные сохраняются | тот же токен читает ту же историю | сервисы `Up` через ~5 с; потери данных нет | +| `FLUSHALL` в Valkey | сессии работают, кэш наполняется заново | ответ 200 из PostgreSQL, ключи `sess:*` появляются снова | без прерывания; потери данных нет | +| Остановка Valkey | чтение и вход работают через PostgreSQL | 200 для действующего токена, 401 для неизвестного и анонимного | после `start` кэш снова используется не позднее чем через 5 с; потери данных нет | +| Остановка PostgreSQL | ограниченная ошибка, аноним не доверенный | `/health/ready` 503 (код `unavailable`), неизвестный токен 503, запрос без токена 401, регистрация 503 | API снова готов после старта PostgreSQL в пределах 90 с ожидания теста (точное время не измерялось) | +| `SESSION_TTL_SECONDS=2` | токен истекает | через 3.5 с запрос с тем же токеном → 401 (в том числе из-за TTL кэша ≤ остатка сессии) | не применимо | + +Ограничения измерения: нагрузочный профиль не снимался (трек 5 не заявлен), время восстановления PostgreSQL точно не измерялось. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- **Устаревание кэша при сбое инвалидации.** Если logout выполнился, а `DEL` в Valkey не прошёл (кратковременный сбой), запись может остаться в кэше не дольше `CACHE_TTL_SECONDS` (60 с). Это сознательный компромисс; снизить окно можно, уменьшив TTL кэша. +- **Порядок истории при конкурентной записи.** `created_at` задаётся через `clock_timestamp()` в момент вставки, а видимость строки определяется моментом COMMIT. При конкурентных записях возможно, что сообщение с чуть более ранним `created_at` станет видимым после того, как читатель уже получил курсор за ним; такая запись не повторится и не пропадёт при следующем чтении с начала, но может быть пропущена при продолжении по старому курсору. Гарантируется отсутствие повторов при обходе неизменной истории. +- **Просроченные сессии не удаляются** из таблицы `sessions` (нет фоновой очистки); они не принимаются, но занимают место. Следующий шаг - периодическая очистка по индексу `sessions_expires_idx`. +- **Один экземпляр PostgreSQL и Valkey**, без репликации и бэкапов; отказ диска PostgreSQL приведёт к потере данных (backup/restore - трек 2 уровня 5, не реализован). +- **HTTP и Basic без TLS** - допустимо только для локального изолированного стенда с синтетическими данными. Права `644` у секретов - учебное упрощение для локального запуска. +- **Argon2id** использует параметры по умолчанию библиотеки; подбор параметров под целевое железо не выполнялся. +- Удалённый CI для сборки приложения не добавлен: `.github/workflows/contracts.yml` проверяет только контракт. + +## Ответы на вопросы защиты + +- **Что подтверждает COMMIT?** Транзакция записана в WAL и (при `synchronous_commit=on`, значение по умолчанию) сброшена на диск до ответа клиенту; гарантия зависит от настроек `fsync`/`synchronous_commit` и от надёжности диска и Docker volume. +- **Где хранятся сессии и что будет после flush/restart Redis/Valkey?** Источник истины - таблица `sessions` в PostgreSQL; Valkey лишь кэш без persistence. После flush или рестарта кэш пуст, сессии не теряются и наполняют кэш заново (`test_valkey_flush_keeps_sessions`). +- **Чем аутентификация отличается от доступа к чату?** Аутентификация отвечает «кто вы» (Bearer-сессия), доступ - «можно ли этому пользователю в этот чат» (проверка членства в `chat_members`); постороннему возвращается 404, чтобы не раскрывать существование чата. +- **Почему hash пароля и быстрый checksum - разные задачи?** Пароль имеет низкую энтропию и должен защищаться от перебора, поэтому нужен медленный salted KDF (Argon2id); токен сессии - 256 бит случайности, перебор невозможен, и достаточно быстрого SHA-256. \ No newline at end of file diff --git a/evidence/restart-after.txt b/evidence/restart-after.txt index f64ea13..65b72e7 100644 --- a/evidence/restart-after.txt +++ b/evidence/restart-after.txt @@ -1,3 +1,4 @@ -NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS -mtusi-lab2-api-1 mtusi-messenger:lab2 "sh -c 'exec uvicorn…" api 38 minutes ago Up Less than a second (health: starting) 127.0.0.1:8080->8080/tcp -mtusi-lab2-postgres-1 postgres:16.6-alpine "docker-entrypoint.s…" postgres 38 minutes ago Up 5 seconds (healthy) 5432/tcp +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab2-api-1 mtusi-messenger:lab2 "sh -c 'exec uvicorn…" api 7 hours ago Up Less than a second (health: starting) 127.0.0.1:8080->8080/tcp +mtusi-lab2-postgres-1 postgres:16.6-alpine "docker-entrypoint.s…" postgres 10 hours ago Up 5 seconds (healthy) 5432/tcp +mtusi-lab2-valkey-1 valkey/valkey:8.0.1-alpine "docker-entrypoint.s…" valkey 8 hours ago Up 5 seconds (healthy) 6379/tcp diff --git a/evidence/restart-before.txt b/evidence/restart-before.txt index 5a2da7e..6e32f5c 100644 --- a/evidence/restart-before.txt +++ b/evidence/restart-before.txt @@ -1,3 +1,4 @@ -NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS -mtusi-lab2-api-1 mtusi-messenger:lab2 "sh -c 'exec uvicorn…" api 38 minutes ago Up 39 seconds (healthy) 127.0.0.1:8080->8080/tcp -mtusi-lab2-postgres-1 postgres:16.6-alpine "docker-entrypoint.s…" postgres 38 minutes ago Up 44 seconds (healthy) 5432/tcp +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab2-api-1 mtusi-messenger:lab2 "sh -c 'exec uvicorn…" api 7 hours ago Up 3 minutes (healthy) 127.0.0.1:8080->8080/tcp +mtusi-lab2-postgres-1 postgres:16.6-alpine "docker-entrypoint.s…" postgres 10 hours ago Up 3 minutes (healthy) 5432/tcp +mtusi-lab2-valkey-1 valkey/valkey:8.0.1-alpine "docker-entrypoint.s…" valkey 8 hours ago Up 3 minutes (healthy) 6379/tcp diff --git a/evidence/student-tests-level4.txt b/evidence/student-tests-level4.txt index 6c8df7f..7e736ad 100644 --- a/evidence/student-tests-level4.txt +++ b/evidence/student-tests-level4.txt @@ -17,6 +17,7 @@ ok test_valkey_down_falls_back_to_postgres (test_level4.Level4.test_valkey_down_falls_back_to_postgres) ... /opt/homebrew/Cellar/python@3.14/3.14.0_1/Frameworks/Python.framework/Versions/3.14/lib/python3.14/tempfile.py:484: ResourceWarning: Implicitly cleaning up _warnings.warn(self.warn_message, ResourceWarning) ok +test_valkey_flush_keeps_sessions (test_level4.Level4.test_valkey_flush_keeps_sessions) ... ok test_wrong_password (test_level4.Level4.test_wrong_password) ... /opt/homebrew/Cellar/python@3.14/3.14.0_1/Frameworks/Python.framework/Versions/3.14/lib/python3.14/tempfile.py:484: ResourceWarning: Implicitly cleaning up _warnings.warn(self.warn_message, ResourceWarning) ok @@ -26,6 +27,6 @@ test_zz_session_expiry (test_level4.Level4.test_zz_session_expiry) ... /opt/home ok ---------------------------------------------------------------------- -Ran 8 tests in 12.946s +Ran 9 tests in 16.447s OK diff --git a/student_tests/test_level4.py b/student_tests/test_level4.py index c8d1fde..d523e36 100644 --- a/student_tests/test_level4.py +++ b/student_tests/test_level4.py @@ -145,6 +145,22 @@ class Level4(unittest.TestCase): self.assertEqual(call("GET", "/api/v1/users/me", headers=bearer("x" * 43))[0], 401) finally: compose("start", "valkey") + + def test_valkey_flush_keeps_sessions(self): + _, token = new_session() + self.assertEqual(call("GET", "/api/v1/users/me", headers=bearer(token))[0], 200) + compose("exec", "-T", "valkey", "valkey-cli", "FLUSHALL") + # кэш пуст, но сессия живёт в PostgreSQL; ответ не зависит от состояния кэша + deadline = time.time() + 10 + refilled = False + while time.time() < deadline: + self.assertEqual(call("GET", "/api/v1/users/me", headers=bearer(token))[0], 200) + keys = compose("exec", "-T", "valkey", "valkey-cli", "keys", "sess:*") + if keys.strip(): + refilled = True + break + time.sleep(1) + self.assertTrue(refilled, "cache should be refilled after a miss") def test_postgres_down_returns_bounded_error(self): compose("stop", "postgres")