ЛР 2: отчёт и итоговые доказательства (уровень 4)

This commit is contained in:
2026-11-03 12:13:58 +03:00
parent 3feb4a9da3
commit 5a745e6434
5 changed files with 151 additions and 21 deletions
+125 -14
View File
@@ -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:<sha256 токена>`, значение - данные пользователя. 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; стенд: <macOS / Docker Desktop, число CPU и RAM>.
| Критерий 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.
+4 -3
View File
@@ -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
+4 -3
View File
@@ -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
+2 -1
View File
@@ -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 <HTTPError 401: 'Unauthorized'>
_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 <HTTPError 401: 'Unauthorized'>
_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
+16
View File
@@ -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")