From 78709bb7e05748d8e1480dc7b3cacc2b817b5bb0 Mon Sep 17 00:00:00 2001 From: Ejur22 Date: Thu, 15 Oct 2026 19:19:30 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9B=D0=A02:=20=D0=BD=D0=B5=20=D0=BF=D1=83?= =?UTF-8?q?=D0=B1=D0=BB=D0=B8=D0=BA=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20EXPLAI?= =?UTF-8?q?N.md=20(=D0=BB=D0=B8=D1=87=D0=BD=D1=8B=D0=B5=20=D0=B7=D0=B0?= =?UTF-8?q?=D0=BC=D0=B5=D1=82=D0=BA=D0=B8)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 2 ++ EXPLAIN.md | 81 ------------------------------------------------------ 2 files changed, 2 insertions(+), 81 deletions(-) delete mode 100644 EXPLAIN.md diff --git a/.gitignore b/.gitignore index b5a7189..df2af19 100644 --- a/.gitignore +++ b/.gitignore @@ -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. diff --git a/EXPLAIN.md b/EXPLAIN.md deleted file mode 100644 index 750a50d..0000000 --- a/EXPLAIN.md +++ /dev/null @@ -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.