ЛР2: не публиковать EXPLAIN.md (личные заметки)

This commit is contained in:
2026-10-15 19:19:30 +03:00
parent 6808ed8c98
commit 78709bb7e0
2 changed files with 2 additions and 81 deletions
+2
View File
@@ -28,5 +28,7 @@ coverage/
.DS_Store
.idea/
.vscode/
# Personal study notes, not part of the submission.
EXPLAIN.md
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
-81
View File
@@ -1,81 +0,0 @@
# EXPLAIN — лабораторная 2: что сделано и как объяснять преподавателю
Шпаргалка к защите: что перенесено, как устроено решение, чем закрыт уровень 4 и что отвечать на вопросы.
## 1. Что требовалось и что сделано
Lab2 переносит состояние из памяти в постоянное хранилище и меняет аутентификацию: `password` при регистрации, `Basic` для входа, `Bearer` для бизнес-запросов, `X-User-Id` больше не действует. PostgreSQL — источник истины; на оценку 4 добавляется Valkey как кэш сессий.
Стек: **Python 3.11 + FastAPI + psycopg3 + PostgreSQL 16 + Valkey 8 + Docker Compose**.
Реализовано:
- `POST /api/v1/users` (+ `password`, Argon2id), `POST /api/v1/auth/sessions` (Basic → opaque token), `DELETE /api/v1/auth/sessions/current` (204);
- `Bearer`-зависимость для всех бизнес-endpoint; `X-User-Id` игнорируется;
- чаты и сообщения в PostgreSQL, атомарное создание чата, keyset-пагинация;
- версионируемые идемпотентные миграции, пул соединений с таймаутами;
- Valkey — read-through кэш сессий с TTL и корректным обходом при отказе;
- `/health/live` (процесс) и `/health/ready` (критичен только PostgreSQL).
## 2. Что перенесено из lab1
Перенесены исходники HTTP-слоя, `Dockerfile`, `student-tests/`, `requirements` — и переработаны. Не переносились: `.git`, `.env`, `.venv`, `README.md`, `COURSE.md`, публичные `tests/`, `contracts/`, `REPORT.md` lab1, in-memory `store.py`.
## 3. Ключевые решения (что говорить)
- **Источник истины — PostgreSQL, а не кэш.** Валидность сессии определяется строкой `sessions` (`expires_at > now()`). `current_user` после проверки токена **всегда** читает пользователя из PostgreSQL, поэтому кэш не может «оживить» удалённого пользователя.
- **Токен не хранится в открытом виде.** В БД — SHA-256 токена; сам токен знает только клиент. Токен — `secrets.token_urlsafe(32)` (≥256 бит), не JWT.
- **Пароль — Argon2id**, медленный memory-hard KDF. В ответах API пароль/хеш не появляются.
- **Valkey — кэш, а не авторитет.** Кэшируется `session:{sha256(token)} → user_id` с TTL до конца сессии. Отказ Valkey → обход кэша, API работает дальше.
- **Устойчивость к «зависанию» DNS.** Остановленный контейнер Valkey приводит к тому, что внутренний Docker-DNS может блокироваться на секунды. Поэтому каждая операция кэша ограничена жёстким таймаутом 0.5 c и маленьким circuit breaker (на 5 c кэш пропускается). Это делает деградацию предсказуемой.
- **Границы транзакций.** Создание чата — одна транзакция; при ошибке rollback. Регистрация опирается на `UNIQUE(username)`: гонка даёт одного победителя и `409` остальным.
- **Индекс под пагинацию.** `messages(chat_id, created_at, id)`; запрос `(created_at, id) > (...) ORDER BY created_at, id LIMIT n` использует Index Scan, а не скан всей истории.
- **Пул и таймауты.** `psycopg_pool` ограничен, `statement_timeout` задан; все запросы параметризованы.
## 4. Как воспроизвести
```sh
sh scripts/gen-secrets.sh
docker compose --env-file .env up -d --build
docker compose ps # все healthy
python tests/smoke.py --base-url http://localhost:8080
.venv\Scripts\python -m pytest student-tests -v # 28 passed
make test-persistence ACTION_SCRIPT=scripts/restart.sh # в WSL/Linux
python scripts/check-degradation.py
sh scripts/check-expiry.sh
```
## 5. Демонстрация по сценарию защиты (README)
1. Применить миграции к пустому volume, создать пользователей, войти, отправить сообщение.
2. Запустить persistence-сценарий: токен живёт только в памяти теста, action script перезапускает API и хранилища с сохранением volumes.
3. Тот же токен читает те же данные; после logout — 401; короткий TTL — expiry.
4. Для оценки 4: показать роль Valkey (доказать, что он используется и корректно обходится), план SQL (`EXPLAIN`) и ошибку зависимости (`/health/ready`=503 при остановленном PostgreSQL).
## 6. Ответы на вопросы на защите
**Что подтверждает COMMIT и какие гарантии зависят от настройки durability?**
`COMMIT` подтверждает, что транзакция завершена и её изменения видны другим транзакциям. В PostgreSQL по умолчанию `synchronous_commit=on`: COMMIT возвращается после записи WAL и его синхронизации на диск (fsync), поэтому подтверждённые данные переживают падение процесса и обычно — ОС. Если `synchronous_commit=off`, ответ приходит раньше реального fsync (быстрее, но окно потери при падении). `fsync=off` ещё быстрее и опаснее — можно повредить БД. Наша durable-гарантия опирается на дефолт PostgreSQL и named volume.
**Где хранятся сессии и что будет после flush/restart Redis?**
Сессии хранятся в PostgreSQL (`sessions`), а Valkey — только кэш. После `FLUSHALL` или рестарта Valkey кэш пуст, но обращения продолжают разрешаться из PostgreSQL (cache miss → авторитетный ответ → повторное наполнение кэша). Истечение определяется `expires_at` в БД, поэтому «оживить» сессию кэшем нельзя. Это и делает потерю Valkey безопасной.
**Чем аутентификация отличается от доступа к конкретному чату?**
Аутентификация устанавливает, кто ты (валидный Bearer-токен → пользователь), и при её провале — `401`. Доступ к чату — авторизация: участник ли ты этого ресурса. Чужой чат не раскрывается: посторонний получает `404` (не `403`), списки содержат только доступные объекты. Сначала аутентификация, затем доступ.
**Почему hash пароля и быстрый checksum имеют разные задачи?**
Пароль хешируют медленно и с солью (Argon2id), чтобы перебор был дорогим: это защита секрета. Checksum (например SHA-256 файла) — быстро и детерминированно проверить целостность/совпадение данных; он не защищает от перебора и не годится для паролей. Поэтому SHA-256 недопустим для пароля, но уместен для контроля целостности (в lab4 — для содержимого файла, у нас — для хранения токена, который и так случаен и не перебирается по словарю).
## 7. Честные границы
- Один экземпляр PostgreSQL и Valkey, один Docker-host — нет отказоустойчивости к потере host (lab3).
- HTTP без TLS — допустимо только для локального стенда lab1–6 (lab7 — HTTPS).
- Нет rate limiting и лимитов памяти — это трек 5, не заявлен.
- `SESSION_STORE=postgres` выключает кэш Valkey (режим для сравнения).
## 8. Вероятные дополнительные вопросы
- **Почему токен в БД хеширован?** Утечка дампа не даёт готовых bearer-токенов; сравнение идёт по SHA-256 токена.
- **Зачем circuit breaker для кэша?** Не позволить проблемному кэшу (или DNS остановленного контейнера) тормозить запросы; после серии сбоев кэш временно пропускается.
- **Почему keyset, а не offset?** При росте истории offset пересчитывает пропущенные строки и «сдвигается» при вставках; keyset по `(created_at, id)` использует индекс и стабилен.
- **Что будет при двух API-процессах?** Оба ходят в одну БД и один кэш; сессии и данные общие. Но балансировщик и идемпотентность — задача lab3.