ЛР 2 — БВТ2302 — Ким — на 3 #87

Closed
ddientee wants to merge 1 commits from ddientee/mtusi2026lab2:solution into master
First-time contributor

Отчёт — лабораторная 2

  • Автор, группа: Ким Владимир, БВТ2302
  • Целевая оценка; 3
    (Redis/Valkey как кэш сессий, параметризованные запросы и пул, индекс истории с EXPLAIN на 10 000
    сообщениях, автоматические проверки expiry/logout/гонки/отказа).
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки: FastAPI 0.115.6, Uvicorn 0.34.0,
    psycopg2-binary 2.9.10, redis 5.2.1, argon2-cffi 23.1.0; PostgreSQL 16.4, Valkey 7.2.6.
    Все решения проверены запуском стенда. Первичные материалы: см. README курса.

Запуск из чистого clone

Prerequisites: Docker Engine/Desktop с Compose v2 и доступом к сети для сборки образа.
Версии зафиксированы: Python 3.12.7-slim (образ python:3.12.7-slim), postgres:16.4,
valkey/valkey:7.2.6. Никаких хостовых БД/Redis не требуется.

# 1. Локальные синтетические секреты (файл в .gitignore, в Git не попадает)
cp .env.example .env
#   заполните как минимум POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB,
#   APP_HOST/APP_PORT/APP_ENV/SESSION_TTL_SECONDS/SESSION_STORE, DB_POOL_MIN/DB_POOL_MAX

# 2. Проверка конфигурации и сборка
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build

# 3. Дождаться готовности (миграции применяются автоматически при старте API)
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done

# 4. Проверки
python scripts/check_contract.py                 # = make check
python tests/smoke.py --base-url http://localhost:8080   # = make test
python tests/resilience.py --mode persistence --action-script scripts/restart.sh \
    --base-url http://localhost:8080             # = make test-persistence
python tests/load.py --duration 30 --concurrency 4 --output evidence/load.json

# 5. Безопасная остановка (volumes сохраняются)
docker compose --env-file .env stop

# 6. Намеренное удаление только учебных данных
docker compose --env-file .env down -v

На Windows хук scripts/restart.sh (POSIX) запускается через scripts/restart.cmd
(та же команда docker compose restart); проверка сохранности при этом эквивалентна.
make в среде разработки отсутствовал, поэтому в отчёте приведены эквивалентные python-команды.

Архитектура и решения

Клиент --HTTP--> API (FastAPI/Uvicorn, python:3.12.7-slim, non-root)
                     |  psycopg2 pool (bounded, statement_timeout)
                     v
             PostgreSQL 16.4  <-- источник истины: users, chats, chat_members,
             (named volume pgdata)   messages, sessions, schema_migrations
                     ^
                     |  cache-aside (TTL = остаток жизни сессии)
             Valkey 7.2.6 (named volume valkeydata, AOF)  <-- кэш сессий
  • Источник истины — PostgreSQL. Пользователи, чаты, членство, сообщения и сессии
    хранятся в БД, поэтому данные и действующие сессии переживают рестарт API и хранилищ.
  • Сессии: opaque-токен (secrets.token_urlsafe(32), ≥256 бит). В БД пишется только
    SHA-256-фингерпринт токена (сам токен не хранится). Срок жизни задаёт SESSION_TTL_SECONDS
    (по умолчанию 3600). Отзыв — revoked_at + удаление ключа из кэша.
  • Пароли: Argon2id (argon2-cffi). Пароль никогда не возвращается в User.
  • Valkey/Redis — кэш, а не источник истины. При каждом аутентифицированном запросе сначала
    проверяется кэш (sess:<sha256>); промах или недоступность кэша → запрос к PostgreSQL.
    TTL кэша равен остатку жизни сессии, инвалидация — при logout/отзыве. Так как истина в БД,
    потеря кэша не приводит к потере данных, а анонимный запрос не принимается доверенным.
  • Транзакционные границы: регистрация пользователя и создание сессии — одиночные INSERT;
    создание чата — одна транзакция (проверка существования участников + INSERT чата +
    INSERT участников); отправка сообщения — проверка членства и INSERT в одной транзакции.
    Гонка регистрации одинакового username разрешается уникальным ограничением users.username,
    нарушение перехватывается и превращается в 409 conflict.
  • Ограничения и валидация: длина и формат полей проверяются приложением (код-поинты) и
    дублируются CHECK-ограничениями БД; лишние поля и неверные типы → 400; additionalProperties:false
    соблюдается для всех ответов.
  • Пагинация истории — keyset по (created_at, id) по возрастанию, курсор непрозрачный и
    привязан к ресурсу (chat_id/user_id); выборка LIMIT n+1 определяет next_cursor без
    полного сканирования истории.

Соответствие .env.example реальной конфигурации

.env.example Реальная переменная Смысл
APP_HOST / APP_PORT то же bind-адрес/порт Uvicorn
APP_ENV то же метка окружения (лог)
SESSION_TTL_SECONDS то же TTL сессии, по умолчанию 3600
SESSION_STORE то же postgres или postgres+redis
DATABASE_URL_FILE DATABASE_URL или DATABASE_URL_FILE DSN PostgreSQL (поддержаны оба способа)
CACHE_URL_FILE CACHE_URL или CACHE_URL_FILE DSN Valkey/Redis (кэш)
— DB_POOL_MIN / DB_POOL_MAX границы пула соединений

Приложение читает значение напрямую из переменной, а при её отсутствии — из файла,
указанного в *_FILE (совместимо с Docker secrets). Секретов в Git нет: .env в .gitignore.

Роли инфраструктуры

Роль service Образ (пиннинг) healthcheck volume сеть credentials
api api сборка из Dockerfile (python:3.12.7-slim) HEALTHCHECK + /health/live — backend env из .env
postgres postgres postgres:16.4 pg_isready pgdata backend POSTGRES_* из .env
cache valkey valkey/valkey:7.2.6 valkey-cli ping valkeydata (AOF) backend CACHE_URL из .env

Bootstrap: миграции migrations/*.sql применяются самим API при старте (таблица
schema_migrations, advisory lock). Повторный запуск не дублирует данные.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Структура skeleton python scripts/check_contract.py PASS: offline skeleton structure... evidence/check.txt
Публичный smoke python tests/smoke.py --base-url http://localhost:8080 PASS: lab2 public API scenario evidence/smoke.txt
Данные и сессия переживают рестарт python tests/resilience.py --mode persistence --action-script scripts/restart.sh ... PASS: persistence preserved confirmed data and existing session; StartedAt всех контейнеров изменился, volumes сохранены evidence/persistence.txt
PostgreSQL = источник истины, ключи, уникальность, миграции с нуля миграция migrations/0001_init.sql + лог старта API applied migration 0001_init; таблицы/индексы создаются на пустом volume evidence/persistence.txt
Атомарное создание чата код store.create_chat + одна транзакция rollback при неизвестном участнике; гонка username → 409 student-tests/test_lab2.py
Basic только на POST /auth/sessions, остальное — Bearer, expiry и отзыв student-tests/test_lab2.py wrong password 401 (Basic), X-User-Id не работает, logout 204→401 (Bearer) evidence/cache_outage.txt
Истечение сессии при коротком TTL --expiry c SESSION_TTL_SECONDS=2 PASS: session expired after 2s TTL evidence/expiry_check.txt
Параметризованные запросы, пул, таймауты (уровень 4) код db.py/store.py пул ThreadedConnectionPool, statement_timeout, все SQL параметризованы код
Индекс истории обоснован EXPLAIN на ≥10 000 сообщений (уровень 4) student-tests/perf_explain.sql Index Scan using messages_chat_created_id_idx, 5 буферов, 0.028 ms против Seq Scan 361 буфер, 2.550 ms evidence/explain.txt, evidence/explain_no_index.txt
Отказ Redis/БД (уровень 4) --cache-check и stop postgres аутентификация живёт без кэша; /health/ready и аутентифицированные запросы → 503 unavailable при недоступной БД, /health/live → 200 evidence/cache_outage.txt, evidence/dependency_outage.txt

Эксперименты и отказы

Оборудование: один Docker-host (Windows, Docker Desktop 29.4.3, Linux engine), образы без
явных CPU/RAM-лимитов. Прогрев не выделялся; данные синтетические.

Нагрузка (closed-loop POST сообщений, tests/load.py, см. evidence/load.json):

Профиль Длительность Concurrency Успешные RPS Ошибки p50 p95 p99
4 воркера 15 с 4 236.6 0 (0.0) 16.0 ms 32.0 ms 47.0 ms

Ограничения измерения: генератор закрытого контура ограничен клиентом и подвержен coordinated
omission; latency только по успешным запросам; это пропускная способность HTTP-подтверждений, а
не счётчик COMMIT.

План запроса (10 000 сообщений в чате, keyset-страница):

Вариант План Buffers Execution
С индексом Index Scan using messages_chat_created_id_idx shared hit=5 0.028 ms
Без индекса (indexscan off) Seq Scan + Sort shared hit=361 2.550 ms

Отказы:

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose restart (api+postgres+valkey, volumes сохранены) данные и прежний токен доступны те же чат/сообщение по прежнему токену рестарт всех контейнеров; потерь нет
Остановка Valkey (кэш) аутентификация продолжает работать через БД /users/me по прежнему токену → 200 кэш пересоберётся сам; потерь нет
Остановка PostgreSQL /health/ready деградирует /health/ready → 503 unavailable, аутентифицированный запрос → 503 unavailable, /health/live → 200 200 после старта БД; потерь нет

Ограничения и следующие шаги

  • Учебное упрощение: один Docker-host; эксперимент не даёт отказоустойчивости к потере
    самого host, а единственная БД и отсутствие LB/реплик не делают стенд HA. Redis выбран как
    кэш, а не единственное хранилище сессий, поэтому его потеря безопасна.
  • Durability PostgreSQL определяется настройками по умолчанию образа; отдельно проверялось
    сохранение при рестарте контейнеров с сохранением volume, а не при потере диска.
  • Не реализовано (вне минимума этой лабы): изменение участников/удаление сообщений, rate limiting,
    идемпотентность отправки (Idempotency-Key) и X-Instance-Id — это переходы lab3+.
  • Уровень 4 подтверждён частично: кэш сессий, пул/таймауты, индекс и отказы проверены; отдельный
    «трек 5» (согласованность кэша или backup/restore) не заявлен и не измерялся.

git remote add origin https://gitea.privcloud.tech/ddientee/mtusi2026lab2.git
git push -u origin solution

# Отчёт — лабораторная 2 - Автор, группа: Ким Владимир, БВТ2302 - Целевая оценка; 3 (Redis/Valkey как кэш сессий, параметризованные запросы и пул, индекс истории с EXPLAIN на 10 000 сообщениях, автоматические проверки expiry/logout/гонки/отказа). - Commit/PR: TODO после публикации - Использованные источники, библиотеки: FastAPI 0.115.6, Uvicorn 0.34.0, psycopg2-binary 2.9.10, redis 5.2.1, argon2-cffi 23.1.0; PostgreSQL 16.4, Valkey 7.2.6. Все решения проверены запуском стенда. Первичные материалы: см. README курса. ## Запуск из чистого clone Prerequisites: Docker Engine/Desktop с Compose v2 и доступом к сети для сборки образа. Версии зафиксированы: Python 3.12.7-slim (образ `python:3.12.7-slim`), `postgres:16.4`, `valkey/valkey:7.2.6`. Никаких хостовых БД/Redis не требуется. ```sh # 1. Локальные синтетические секреты (файл в .gitignore, в Git не попадает) cp .env.example .env # заполните как минимум POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB, # APP_HOST/APP_PORT/APP_ENV/SESSION_TTL_SECONDS/SESSION_STORE, DB_POOL_MIN/DB_POOL_MAX # 2. Проверка конфигурации и сборка docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build # 3. Дождаться готовности (миграции применяются автоматически при старте API) until curl -fsS http://localhost:8080/health/ready; do sleep 1; done # 4. Проверки python scripts/check_contract.py # = make check python tests/smoke.py --base-url http://localhost:8080 # = make test python tests/resilience.py --mode persistence --action-script scripts/restart.sh \ --base-url http://localhost:8080 # = make test-persistence python tests/load.py --duration 30 --concurrency 4 --output evidence/load.json # 5. Безопасная остановка (volumes сохраняются) docker compose --env-file .env stop # 6. Намеренное удаление только учебных данных docker compose --env-file .env down -v ``` На Windows хук `scripts/restart.sh` (POSIX) запускается через `scripts/restart.cmd` (та же команда `docker compose restart`); проверка сохранности при этом эквивалентна. `make` в среде разработки отсутствовал, поэтому в отчёте приведены эквивалентные python-команды. ## Архитектура и решения ``` Клиент --HTTP--> API (FastAPI/Uvicorn, python:3.12.7-slim, non-root) | psycopg2 pool (bounded, statement_timeout) v PostgreSQL 16.4 <-- источник истины: users, chats, chat_members, (named volume pgdata) messages, sessions, schema_migrations ^ | cache-aside (TTL = остаток жизни сессии) Valkey 7.2.6 (named volume valkeydata, AOF) <-- кэш сессий ``` - **Источник истины** — PostgreSQL. Пользователи, чаты, членство, сообщения и **сессии** хранятся в БД, поэтому данные и действующие сессии переживают рестарт API и хранилищ. - **Сессии**: opaque-токен (`secrets.token_urlsafe(32)`, ≥256 бит). В БД пишется только SHA-256-фингерпринт токена (сам токен не хранится). Срок жизни задаёт `SESSION_TTL_SECONDS` (по умолчанию 3600). Отзыв — `revoked_at` + удаление ключа из кэша. - **Пароли**: Argon2id (`argon2-cffi`). Пароль никогда не возвращается в `User`. - **Valkey/Redis — кэш, а не источник истины.** При каждом аутентифицированном запросе сначала проверяется кэш (`sess:<sha256>`); промах или недоступность кэша → запрос к PostgreSQL. TTL кэша равен остатку жизни сессии, инвалидация — при logout/отзыве. Так как истина в БД, потеря кэша не приводит к потере данных, а анонимный запрос не принимается доверенным. - **Транзакционные границы**: регистрация пользователя и создание сессии — одиночные INSERT; создание чата — одна транзакция (проверка существования участников + INSERT чата + INSERT участников); отправка сообщения — проверка членства и INSERT в одной транзакции. Гонка регистрации одинакового username разрешается уникальным ограничением `users.username`, нарушение перехватывается и превращается в `409 conflict`. - **Ограничения и валидация**: длина и формат полей проверяются приложением (код-поинты) и дублируются CHECK-ограничениями БД; лишние поля и неверные типы → `400`; `additionalProperties:false` соблюдается для всех ответов. - **Пагинация истории** — keyset по `(created_at, id)` по возрастанию, курсор непрозрачный и привязан к ресурсу (`chat_id`/`user_id`); выборка `LIMIT n+1` определяет `next_cursor` без полного сканирования истории. ### Соответствие `.env.example` реальной конфигурации | `.env.example` | Реальная переменная | Смысл | | --- | --- | --- | | `APP_HOST` / `APP_PORT` | то же | bind-адрес/порт Uvicorn | | `APP_ENV` | то же | метка окружения (лог) | | `SESSION_TTL_SECONDS` | то же | TTL сессии, по умолчанию 3600 | | `SESSION_STORE` | то же | `postgres` или `postgres+redis` | | `DATABASE_URL_FILE` | `DATABASE_URL` **или** `DATABASE_URL_FILE` | DSN PostgreSQL (поддержаны оба способа) | | `CACHE_URL_FILE` | `CACHE_URL` **или** `CACHE_URL_FILE` | DSN Valkey/Redis (кэш) | | — | `DB_POOL_MIN` / `DB_POOL_MAX` | границы пула соединений | Приложение читает значение напрямую из переменной, а при её отсутствии — из файла, указанного в `*_FILE` (совместимо с Docker secrets). Секретов в Git нет: `.env` в `.gitignore`. ### Роли инфраструктуры | Роль | service | Образ (пиннинг) | healthcheck | volume | сеть | credentials | | --- | --- | --- | --- | --- | --- | --- | | api | `api` | сборка из `Dockerfile` (python:3.12.7-slim) | `HEALTHCHECK` + `/health/live` | — | `backend` | env из `.env` | | postgres | `postgres` | `postgres:16.4` | `pg_isready` | `pgdata` | `backend` | `POSTGRES_*` из `.env` | | cache | `valkey` | `valkey/valkey:7.2.6` | `valkey-cli ping` | `valkeydata` (AOF) | `backend` | `CACHE_URL` из `.env` | Bootstrap: миграции `migrations/*.sql` применяются самим API при старте (таблица `schema_migrations`, advisory lock). Повторный запуск не дублирует данные. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Структура skeleton | `python scripts/check_contract.py` | `PASS: offline skeleton structure...` | `evidence/check.txt` | | Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | `PASS: lab2 public API scenario` | `evidence/smoke.txt` | | Данные и сессия переживают рестарт | `python tests/resilience.py --mode persistence --action-script scripts/restart.sh ...` | `PASS: persistence preserved confirmed data and existing session`; StartedAt всех контейнеров изменился, volumes сохранены | `evidence/persistence.txt` | | PostgreSQL = источник истины, ключи, уникальность, миграции с нуля | миграция `migrations/0001_init.sql` + лог старта API | `applied migration 0001_init`; таблицы/индексы создаются на пустом volume | `evidence/persistence.txt` | | Атомарное создание чата | код `store.create_chat` + одна транзакция | rollback при неизвестном участнике; гонка username → `409` | `student-tests/test_lab2.py` | | Basic только на `POST /auth/sessions`, остальное — Bearer, expiry и отзыв | `student-tests/test_lab2.py` | wrong password `401` (Basic), `X-User-Id` не работает, logout `204`→`401` (Bearer) | `evidence/cache_outage.txt` | | Истечение сессии при коротком TTL | `--expiry` c `SESSION_TTL_SECONDS=2` | `PASS: session expired after 2s TTL` | `evidence/expiry_check.txt` | | Параметризованные запросы, пул, таймауты (уровень 4) | код `db.py`/`store.py` | пул `ThreadedConnectionPool`, `statement_timeout`, все SQL параметризованы | код | | Индекс истории обоснован EXPLAIN на ≥10 000 сообщений (уровень 4) | `student-tests/perf_explain.sql` | `Index Scan using messages_chat_created_id_idx`, 5 буферов, 0.028 ms против Seq Scan 361 буфер, 2.550 ms | `evidence/explain.txt`, `evidence/explain_no_index.txt` | | Отказ Redis/БД (уровень 4) | `--cache-check` и `stop postgres` | аутентификация живёт без кэша; `/health/ready` и аутентифицированные запросы → `503 unavailable` при недоступной БД, `/health/live` → `200` | `evidence/cache_outage.txt`, `evidence/dependency_outage.txt` | ## Эксперименты и отказы Оборудование: один Docker-host (Windows, Docker Desktop 29.4.3, Linux engine), образы без явных CPU/RAM-лимитов. Прогрев не выделялся; данные синтетические. Нагрузка (closed-loop POST сообщений, `tests/load.py`, см. `evidence/load.json`): | Профиль | Длительность | Concurrency | Успешные RPS | Ошибки | p50 | p95 | p99 | | --- | --- | --- | --- | --- | --- | --- | --- | | 4 воркера | 15 с | 4 | 236.6 | 0 (0.0) | 16.0 ms | 32.0 ms | 47.0 ms | Ограничения измерения: генератор закрытого контура ограничен клиентом и подвержен coordinated omission; latency только по успешным запросам; это пропускная способность HTTP-подтверждений, а не счётчик COMMIT. План запроса (10 000 сообщений в чате, keyset-страница): | Вариант | План | Buffers | Execution | | --- | --- | --- | --- | | С индексом | `Index Scan using messages_chat_created_id_idx` | shared hit=5 | 0.028 ms | | Без индекса (indexscan off) | `Seq Scan` + `Sort` | shared hit=361 | 2.550 ms | Отказы: | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | `docker compose restart` (api+postgres+valkey, volumes сохранены) | данные и прежний токен доступны | те же чат/сообщение по прежнему токену | рестарт всех контейнеров; потерь нет | | Остановка Valkey (кэш) | аутентификация продолжает работать через БД | `/users/me` по прежнему токену → `200` | кэш пересоберётся сам; потерь нет | | Остановка PostgreSQL | `/health/ready` деградирует | `/health/ready` → `503 unavailable`, аутентифицированный запрос → `503 unavailable`, `/health/live` → `200` | `200` после старта БД; потерь нет | ## Ограничения и следующие шаги - Учебное упрощение: один Docker-host; эксперимент **не** даёт отказоустойчивости к потере самого host, а единственная БД и отсутствие LB/реплик не делают стенд HA. Redis выбран как кэш, а не единственное хранилище сессий, поэтому его потеря безопасна. - Durability PostgreSQL определяется настройками по умолчанию образа; отдельно проверялось сохранение при рестарте контейнеров с сохранением volume, а не при потере диска. - Не реализовано (вне минимума этой лабы): изменение участников/удаление сообщений, rate limiting, идемпотентность отправки (`Idempotency-Key`) и `X-Instance-Id` — это переходы lab3+. - Уровень 4 подтверждён частично: кэш сессий, пул/таймауты, индекс и отказы проверены; отдельный «трек 5» (согласованность кэша или backup/restore) не заявлен и не измерялся. git remote add origin https://gitea.privcloud.tech/ddientee/mtusi2026lab2.git git push -u origin solution
ddientee added 1 commit 2026-10-23 12:22:18 +03:00
FastAPI-сервис с opaque-сессиями (Argon2id, SHA-256 фингерпринт), PostgreSQL как источником истины, Valkey как кэшем сессий, keyset-пагинацией, пулом соединений и таймаутами. Добавлены миграции, compose-стенд, скрипт рестарта, студенческие проверки и evidence.
andrey.derbenev closed this pull request 2026-11-12 15:11:04 +03:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mtusi2026/mtusi2026lab2#87