forked from mtusi2026/mtusi2026lab2
ЛР2: не публиковать EXPLAIN.md (личные заметки)
This commit is contained in:
@@ -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
@@ -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.
|
||||
Reference in New Issue
Block a user