Files
2026-10-03 11:14:52 +03:00

59 KiB
Raw Permalink Blame History

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

PostgreSQL, серверные сессии и Valkey

  • Автор, группа: Максимова Мария, БВТ2303
  • Целевая оценка: 4
  • Commit / PR: e78c103
  • Использованные средства: Python 3.12.7 (в Docker), FastAPI, SQLAlchemy 2 (async) + asyncpg, argon2-cffi, redis-py 5 (клиент Valkey), PostgreSQL 16.4, Valkey 8.0.1, Docker Desktop + WSL2.
  • Источники: документация PostgreSQL (EXPLAIN, сравнение строк/row comparison, транзакции, WAL), документация Valkey (persistence, SET NX, EX), RFC 7617 (HTTP Basic), документация FastAPI и SQLAlchemy.
  • Помощь ИИ: Claude Code и Perplexity использовались для части реализации кэша, тестов уровня 4, диагностики окружения и оформления отчёта. Все команды, тесты и измерения я запускала локально сама, результаты сохранены в evidence/.

1. Краткий итог

В lab1 всё состояние хранилось в словарях Python и пропадало при перезапуске, а пользователя определял заголовок X-User-Id, который мог подставить кто угодно. В lab2:

  1. Пользователи, чаты, участники, сообщения и сессии хранятся в PostgreSQL на именованном volume postgres_data.
  2. Структура базы создаётся версионируемыми миграциями. Их можно запустить повторно, и данные не продублируются.
  3. Регистрация принимает password. Пароль хранится только в виде хеша Argon2id.
  4. Вход: POST /api/v1/auth/sessions с Basic. Сервер выдаёт opaque Bearer-токен, у сессии есть срок жизни, её можно отозвать через logout.
  5. Все остальные бизнес-endpoint принимают только Bearer. X-User-Id игнорируется.
  6. Данные и ещё действующие сессии переживают перезапуск API и всех хранилищ без удаления volumes.
  7. На «4» добавлен Valkey с одной ролью: cache-aside кэш проверки Bearer-сессий. Источник истины остаётся в PostgreSQL. Отказы Valkey и PostgreSQL проверены экспериментально.

Контракт lab1 (users/chats/messages, keyset-пагинация с непрозрачным cursor, единый формат ошибок, X-Request-Id) сохранён. Изменена только аутентификация, как требует контракт lab2.

2. Соответствие критериям

2.1. Оценка «3»

Критерий Где реализовано Чем доказано
Минимум lab1 сохранён, объявлен переход на новую аутентификацию app/main.py, contracts/openapi.json make test → PASS: lab2 public API scenario (evidence/smoke.txt)
Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes scripts/restart.sh, volume postgres_data, таблица sessions make test-persistence ACTION_SCRIPT=scripts/restart.sh → PASS со старым токеном (evidence/persistence.txt)
PostgreSQL содержит users, chats, участников и messages migrations/001_initial_schema.sql \dt в psql; smoke-тест работает через БД
PK, FK, UNIQUE username migrations/001_initial_schema.sql раздел 5; проверка FK вручную (раздел 5.2)
Миграции с нуля scripts/migrate.py, migrations/*.sql на пустом volume: APPLY 001…, APPLY 002…, PASS
Миграции повторно запускаются без дублирования таблица schema_migrations docker compose run --rm migrate → SKIP 001…, SKIP 002… (evidence/migrations_repeat.txt)
Создание чата атомарно app/repositories.py::create_chat_with_members make db-checks: откат строки chats вместе с участниками (evidence/explain.txt)
Basic только на POST /auth/sessions app/services.py::create_user_session, app/deps.py::require_user smoke: Basic на /users/me → 401
Остальные endpoint требуют Bearer Depends(require_user) на каждом защищённом маршруте smoke + evidence/level4.txt
Срок жизни и отзыв сессии sessions.expires_at, sessions.revoked_at logout → 204, затем 401; тест истечения TTL = 3 s (evidence/level4.txt)
X-User-Id не даёт доступа app/deps.py вообще не читает этот заголовок smoke: только X-User-Id → 401; Bearer + чужой X-User-Id → остаётся владелец токена
Пароли хешируются password KDF app/security.py (Argon2id) SELECT password_hash FROM users → $argon2id$…
make test и make test-persistence проходят Makefile evidence/smoke.txt, evidence/persistence.txt
Secrets и volumes не попадают в Git .gitignore, .dockerignore git check-ignore -v infra/secrets/*.txt (раздел 12)

2.2. Оценка «4»

Критерий Чем доказано
Valkey с конкретной ролью (кэш сессий), источник истины — PostgreSQL EXISTS messenger:session:<sha256> = 1 после первого запроса (evidence/level4.txt)
Корректный expiry кэша TTL записи = min(60 s, остаток жизни сессии); тест api_short_ttl
Инвалидация при logout без гонки tombstone revoked + заполнение через SET NX
Поведение при отказе Valkey (stop и pause) задержка ≤ 0.26–0.30 s, токен, отозванный во время отказа, остаётся 401, в том числе после рестарта API
Поведение при отказе PostgreSQL 503 unavailable за ~3 s, ready 503, live 200, анонимный запрос 401
Пул соединений и таймауты app/db.py, app/cache.py
Индекс истории обоснован EXPLAIN keyset: 5 buffers против 208 (OFFSET) и 783 (без индекса)
Гонка регистрации 20 параллельных запросов → {201: 1, 409: 19}
Эксперимент отказа повторён с Valkey persistence-тест перезапускает db, valkey, api

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

3.1. Требования

  • Docker Engine или Docker Desktop с Compose v2.
  • Linux-shell: Linux/macOS — обычный терминал; Windows — WSL2 (подробности в 3.3).
  • Python 3.9+ для публичных тестов. Они используют только стандартную библиотеку.
  • Для make validate: виртуальное окружение с requirements-dev.txt (см. 3.3).

Версии образов закреплены: python:3.12.7-slim, postgres:16.4-alpine, valkey/valkey:8.0.1-alpine.

3.2. Порядок команд

Все команды выполняются из корня репозитория.

cd /mnt/c/Users/masha/WebstormProjects/mtusi2026lab2

# 1. Сгенерировать локальные secrets (случайные пароли; в Git не попадают)
sh scripts/init-secrets.sh

# 2. Собрать и запустить стенд:
#    db → (healthy) → migrate → api :8080 и api_short_ttl :8081
docker compose --profile tests up -d --build api api_short_ttl

# 3. Дождаться готовности (ожидается {"status":"ok"})

# 4. Проверки
make check                                              # структура репозитория, OpenAPI refs, синтаксис
make validate                                           # полная OpenAPI 3.1 / JSON Schema
make test                                               # публичный smoke
make test-persistence ACTION_SCRIPT=scripts/restart.sh  # рестарт db, valkey, api
make test-level4                                        # ~1 мин; сам останавливает/запускает valkey и db
make db-checks                                          # rollback и EXPLAIN внутри сети compose

# 5. Всё сразу с сохранением результатов в evidence/
sh scripts/run_evidence.sh

.env необязателен. cp .env.example .env нужен, только curl -fsS http://localhost:8080/health/ready если требуется изменить SESSION_TTL_SECONDS. Для persistence-теста значение должно быть не меньше 300.

Безопасная остановка (volume postgres_data сохраняется):

docker compose --profile tests down

Намеренное удаление всех учебных данных. Эта команда уничтожает volume, поэтому в тесте рестарта её использовать нельзя:

docker compose --profile tests down -v

3.3. Windows

В PowerShell команды не заработают: там нет sh и make, python3 — заглушка Microsoft Store, curl — псевдоним Invoke-WebRequest. К тому же официальный тест запускает restart.sh как исполняемый файл, а Windows не умеет выполнять shell-скрипты напрямую (WinError 193).

Порядок работы:

  1. В Docker Desktop включить Settings → Resources → WSL Integration для своего дистрибутива.
  2. В PowerShell перейти в папку проекта и выполнить wsl. WSL откроется в той же папке (путь вида /mnt/c/.../mtusi2026lab2).
  3. Один раз добавить пользователя в группу docker: sudo usermod -aG docker $USER, затем в PowerShell выполнить wsl --shutdown и снова войти в WSL.
  4. Один раз установить make: sudo apt install -y make.
  5. Выдать hook право на исполнение: chmod +x scripts/restart.sh. Если файл редактировался в Windows, убрать CRLF: sed -i 's/\r$//' scripts/*.sh.
  6. Для make validate:
    python3 -m venv .venv-wsl && . .venv-wsl/bin/activate
    pip install openapi-spec-validator==0.7.2 jsonschema referencing
    
    Полный requirements-dev.txt на хостовом Python 3.13/3.14 не установится: закреплённые pydantic и asyncpg рассчитаны на Python 3.12 и начнут собираться из исходников. Самому приложению это не мешает, оно работает в образе python:3.12.7-slim. Для валидатора достаточно трёх библиотек выше.

Если make выдаёт getcwd: No such file or directory, WSL потерял текущую папку, потому что её изменили со стороны Windows. Нужно заново войти в неё командой cd.

4. Архитектура

                    HTTP, Authorization: Basic (только вход) / Bearer
Клиент ───────────────────────────────────────────────> api (FastAPI/Uvicorn, 1 процесс)
                                                          │
                          SQL, пул ≤ 15, таймауты 3/5 s   │   RESP, пул ≤ 20, таймаут 0.25 s
                         ┌────────────────────────────────┴───────────────────────┐
                         ▼                                                        ▼
            db — PostgreSQL 16.4                                    valkey — Valkey 8.0.1
            источник истины:                                        только копия сессий
            users, chats, chat_members,                             (cache-aside),
            messages, sessions                                      persistence выключена
            volume: postgres_data

4.1. Сервисы Compose

Роль из contracts/infrastructure.json Service Версия / источник Health / readiness Volume Сеть / порт Передача credentials
API api собирается из исходников, база python:3.12.7-slim /health/live (процесс жив), /health/ready (PostgreSQL отвечает) нет, состояния в процессе нет messenger_net; host 8080:8080 DATABASE_URL_FILE, CACHE_URL_FILE → Docker secrets
API с коротким TTL (только для тестов) api_short_ttl (profile tests) тот же образ, SESSION_TTL_SECONDS=3 те же endpoint нет host 8081:8080 те же secrets
Реляционное хранилище / сессии db postgres:16.4-alpine pg_isready -U messenger -d messenger postgres_data → /var/lib/postgresql/data только messenger_net, db:5432, на хост не опубликован POSTGRES_PASSWORD_FILE → Docker secret
Кэш сессий valkey valkey/valkey:8.0.1-alpine, --save "" --appendonly no valkey-cli PING нет, сознательно только messenger_net, valkey:6379 пароль из Docker secret valkey_password
Bootstrap схемы migrate тот же образ, python scripts/migrate.py завершается с кодом 0 нет messenger_net DATABASE_URL_FILE

Порядок старта задан через depends_on: db (service_healthy) → migrate (service_completed_successfully) → api.

4.2. Почему один процесс API

Состояние в процессе API не хранится: всё лежит в PostgreSQL, а кэш — в Valkey. Поэтому ограничение lab1 «только один worker» больше не связано с согласованностью данных. Сейчас процесс один, потому что для lab2 этого достаточно.

4.3. Критичные зависимости readiness

  • PostgreSQL — критичен. Без него нельзя проверить сессию, если её нет в кэше, и нельзя выполнить ни одну запись. /health/ready при недоступной БД возвращает 503.
  • Valkey — не критичен. Его отказ снижает только производительность: проверка сессий идёт напрямую в PostgreSQL. /health/ready от Valkey не зависит.
  • Grafana и мониторинг в lab2 не используются. В будущем их отказ тоже не должен останавливать API.

5. Схема базы данных

Схема описана до написания запросов, в файлах migrations/001_initial_schema.sql (таблицы и ограничения) и migrations/002_indexes.sql (индексы).

5.1. Таблицы и ограничения

Таблица Столбцы Ограничения Назначение
users id UUID, username VARCHAR(32), display_name VARCHAR(100), password_hash TEXT, created_at TIMESTAMPTZ PK id; UNIQUE(username); CHECK (username ~ '^[a-z0-9_]{3,32}$'); CHECK непустого display_name пользователи; пароль хранится только как Argon2id-хеш
chats id UUID, title VARCHAR(255), created_at PK id; CHECK непустого title чаты
chat_members chat_id UUID, user_id UUID PK (chat_id, user_id); FK chat_id → chats(id) ON DELETE CASCADE; FK user_id → users(id) ON DELETE RESTRICT связь «многие ко многим»; дважды добавить одного участника невозможно
messages id UUID, chat_id, sender_id, text VARCHAR(4000), created_at PK id; FK chat_id → chats(id); FK sender_id → users(id); CHECK непустого текста сообщения
sessions id UUID, user_id, token_hash CHAR(64), expires_at, revoked_at, created_at PK id; FK user_id → users(id) ON DELETE CASCADE; UNIQUE(token_hash) серверные сессии; хранится только SHA-256 токена
schema_migrations version TEXT, applied_at PK version учёт применённых миграций

Все временные столбцы имеют тип TIMESTAMPTZ и назначаются сервером (DEFAULT now()). API отдаёт их в RFC 3339 UTC с суффиксом Z.

5.2. Почему правила записаны в базе, а не только в коде

Ограничение в базе нельзя обойти ошибкой в приложении. Например, попытка вставить сообщение в несуществующий чат отклоняется самой PostgreSQL:

docker compose exec db psql -U messenger -d messenger -c \
  "INSERT INTO messages (id, chat_id, sender_id, text)
   VALUES (gen_random_uuid(), gen_random_uuid(), gen_random_uuid(), 'x');"
# ERROR: ... violates foreign key constraint ...

Точно так же UNIQUE(username) гарантирует уникальность логина даже при одновременных запросах (раздел 7.4).

5.3. Индексы

Индекс Для какого запроса
messages_keyset_idx (chat_id, created_at, id) страница истории чата по keyset-cursor; обоснован EXPLAIN
chats_keyset_idx (created_at, id) сортировка списка чатов по (created_at, id)
chat_members_user_chat_idx (user_id, chat_id) «чаты пользователя» и проверка «является ли пользователь участником»
sessions_active_token_idx (token_hash, expires_at) WHERE revoked_at IS NULL поиск действующей сессии при промахе кэша
неявные индексы PK и UNIQUE поиск по id, username, token_hash

Лишних индексов нет: каждый обслуживает конкретный запрос из app/repositories.py.

6. Миграции

scripts/migrate.py выполняется в отдельном контейнере migrate до старта API:

  1. создаёт служебную таблицу schema_migrations, если её ещё нет;
  2. перебирает файлы migrations/*.sql в порядке номеров (001_…, 002_…);
  3. если версия уже есть в schema_migrations, печатает SKIP <файл>;
  4. иначе выполняет SQL файла и записывает версию в одной транзакции. Если миграция упадёт, в schema_migrations она не попадёт, а частично созданные объекты будут откачены.

Сами SQL-файлы тоже идемпотентны (CREATE … IF NOT EXISTS). Даже при ручном повторе они ничего не сломают.

Миграции выполняются через «сырое» соединение asyncpg, а не через session.execute(text(...)) из SQLAlchemy. Причина: prepared statement в asyncpg не принимает несколько SQL-команд сразу. Первая версия скрипта падала с ошибкой cannot insert multiple commands into a prepared statement.

Seed-данных миграции не содержат. Это только bootstrap схемы. Тестовые пользователи создаются тестами через API.

Проверка:

docker compose run --rm migrate
# SKIP 001_initial_schema.sql
# SKIP 002_indexes.sql
# PASS: migrations applied

docker compose exec db psql -U messenger -d messenger -c 'SELECT * FROM schema_migrations'

7. Транзакционные границы

Операция Граница транзакции Что гарантируется
Регистрация один INSERT INTO users + COMMIT дубль username отсекает UNIQUE → IntegrityError → 409 conflict; предварительного SELECT нет, поэтому нет гонки «проверил → вставил»
Создание чата INSERT chats + INSERT chat_members (все участники) в одной транзакции при любой ошибке ROLLBACK: чата без участников не бывает
Отправка сообщения проверка членства + INSERT messages + COMMIT 201 Created возвращается только после COMMIT
Создание сессии INSERT sessions + COMMIT токен отдаётся клиенту только после записи сессии
Logout UPDATE sessions SET revoked_at = now() WHERE token_hash = … AND revoked_at IS NULL AND expires_at > now() + COMMIT повторный logout затрагивает 0 строк → 401
Миграция один файл + запись версии файл применяется целиком или не применяется совсем

7.1. Проверки перед созданием чата (в app/services.py)

  1. В member_ids нет дубликатов → иначе 400.
  2. Вызывающий пользователь есть в member_ids → иначе 400.
  3. Все участники существуют (один SELECT … WHERE id = ANY(...)) → иначе 400.
  4. Только после этого выполняется транзакция create_chat_with_members.

Даже если между шагом 3 и транзакцией пользователя удалят (в обязательном API удаления нет), FK chat_members.user_id не даст сохранить участника. Вся транзакция откатится.

7.2. Проверка атомарности (make db-checks)

Скрипт намеренно передаёт в транзакцию второго, несуществующего участника:

expected failure: IntegrityError
PASS: chat row was rolled back together with members
PASS: no chats without members exist in the database

7.3. Что гарантирует COMMIT

После COMMIT PostgreSQL записывает изменения в журнал WAL на диск. Настройки fsync=on и synchronous_commit=on оставлены по умолчанию. Проверен штатный рестарт, но не аварийное убийство контейнера. API отвечает 201 только после COMMIT: если клиент получил 201, запись точно сохранена.

7.4. Гонка регистрации

20 одновременных POST /api/v1/users с одинаковым username:

statuses: {201: 1, 409: 19}

Ровно один запрос успешен, остальные получают 409. Ответов 500 нет.

8. Аутентификация и сессии

8.1. Хеширование пароля

app/security.py::hash_password использует argon2.PasswordHasher (Argon2id, параметры библиотеки по умолчанию). В базе лежит строка вида:

$argon2id$v=19$m=65536,t=3,p=4$<соль>$<хеш>
  • m=65536 — 64 МБ памяти на одну проверку, t=3 — три прохода, p=4 — степень параллелизма.
  • Соль у каждого пользователя своя, поэтому одинаковые пароли дают разные хеши.

Почему не SHA-256 для паролей. SHA-256 рассчитан на скорость: на видеокарте его считают миллиардами в секунду, а придуманные людьми пароли короткие. Argon2id специально медленный и требует много памяти, поэтому перебор становится дорогим. bcrypt не выбран, потому что он обрезает пароль до 72 байт, а контракт допускает до 128 символов UTF-8.

Пароль, его хеш и данные сессии никогда не попадают в ответ User.

8.2. Вход через Basic

POST /api/v1/auth/sessions принимает только заголовок Authorization: Basic base64(username:password), без JSON-тела.

  • Строка разбивается по первому двоеточию, поэтому двоеточие в пароле допустимо.
  • Username проверяется на ASCII, пароль декодируется как UTF-8.
  • Неизвестный пользователь и неверный пароль дают одинаковый ответ 401 с WWW-Authenticate: Basic realm="messenger", charset="UTF-8". По ответу нельзя узнать, существует ли логин.

Basic — это кодирование, а не шифрование. Поэтому он используется ровно один раз, при входе. Работа по HTTP допустима только на локальном стенде с синтетическими данными.

8.3. Токен

  • Генерация: secrets.token_urlsafe(32) — 256 бит случайности.
  • Токен opaque: внутри нет ни username, ни UUID, ни подписанных данных. Это не JWT, а просто случайная строка, как номер гардеробного жетона.
  • Клиент получает токен один раз, в ответе 201:
    {"token":"…","token_type":"Bearer","expires_at":"…Z","user":{…}}
    
  • В sessions.token_hash хранится SHA-256 токена, сам токен не хранится. При утечке базы хеши нельзя использовать как токены.
  • Для токена SHA-256 допустим, в отличие от пароля: у токена 256 бит энтропии, перебрать его невозможно даже быстрым хешем.

8.4. Срок жизни и отзыв

  • expires_at = now() + SESSION_TTL_SECONDS (по умолчанию 3600 s). Срок фиксируется при входе и не продлевается после рестарта.
  • Сессия действует, если revoked_at IS NULL AND expires_at > now() (repositories.get_active_session_user).
  • DELETE /api/v1/auth/sessions/current → 204 без тела; повтор с тем же токеном → 401.
  • Истечение проверено на api_short_ttl с TTL 3 s: токен работает, а через 4.5 s получает 401, хотя до этого был в кэше.

8.5. Bearer на всех бизнес-endpoint

app/deps.py::require_user подключается к каждому защищённому маршруту через Depends(require_user):

Запрос Ответ
без Authorization 401, WWW-Authenticate: Bearer realm="messenger"
Authorization: Basic … на бизнес-endpoint 401, Bearer challenge
неизвестный, истёкший или отозванный токен 401, Bearer challenge
только X-User-Id 401: код этот заголовок не читает
Bearer Алисы + X-User-Id Евы 200, пользователь — Алиса

8.6. Аутентификация и авторизация

Аутентификация отвечает на вопрос «кто ты» (токен → пользователь). Авторизация — «можно ли тебе это». repositories.get_accessible_chat делает JOIN chat_members … AND user_id = <текущий пользователь>. Если пользователь не участник чата, ответ 404, а не 403: так API не раскрывает, что чат существует. Списки чатов содержат только доступные чаты.

9. Valkey: роль, expiry, инвалидация, отказы (уровень «4»)

9.1. Роль

Valkey выполняет одну роль: кэширует результат проверки Bearer-сессии, чтобы не ходить в PostgreSQL на каждый защищённый запрос.

Источник истины — таблица sessions в PostgreSQL. В Valkey лежит только копия, поэтому его persistence выключена сознательно (--save "" --appendonly no). Потеря кэша ничего не теряет: действующие сессии переживают рестарт благодаря PostgreSQL, а не Valkey.

9.2. Алгоритм (cache-aside, services.current_user_from_bearer_token)

h = sha256(token)
GET messenger:session:<h>
 ├─ "revoked"               → 401
 ├─ данные пользователя     → проверить expires_at → пустить (cache hit, без SQL)
 └─ ключа нет / ошибка      → запрос в PostgreSQL (cache miss)
       ├─ сессии нет        → 401
       └─ сессия действует  → пустить + SET NX с TTL

Посмотреть ключи:

docker compose exec valkey sh -c \
  'valkey-cli -a "$(cat /run/secrets/valkey_password)" --no-auth-warning --scan --pattern "messenger:session:*"'

Тест уровня 4 проверяет, что до запроса ключа нет, а после него EXISTS = 1.

9.3. Expiry кэша

TTL записи = min(SESSION_CACHE_TTL_SECONDS = 60, секунд до expires_at). Кроме того, expires_at ещё раз сверяется при чтении из кэша. Поэтому истёкшая сессия не может «застрять» в Valkey.

9.4. Инвалидация при logout без гонки

  1. Сначала UPDATE sessions SET revoked_at = now() + COMMIT в PostgreSQL.
  2. Затем по тому же ключу записывается tombstone revoked (SET … EX 60, с перезаписью).

Удалять ключ вместо tombstone нельзя из-за гонки:

Запрос A: прочитал из БД «сессия действует»…
Запрос B: logout → отозвал в БД → удалил ключ
Запрос A: …положил в кэш «сессия действует»   ← отозванная сессия ожила

Поэтому кэш заполняется командой SET NX («записать, только если ключа нет»). После logout по ключу уже лежит revoked, и запись запроса A не проходит.

9.5. Отказ Valkey (app/cache.py::_run)

  • Таймаут любой операции — 0.25 s. Ошибка или таймаут считаются cache miss, запрос идёт в PostgreSQL.
  • После ошибки кэш не используется 5 s (circuit breaker), чтобы не ждать таймаут на каждом запросе.
  • При первой успешной операции после сбоя и после каждого старта процесса API выполняется FLUSHDB. Пока Valkey был недоступен, logout не мог записать tombstone. После возвращения в кэше могла остаться запись «сессия действует», и очистка её убирает. Потерять при этом нечего: в кэше только копии.
  • Флаг «очистить перед использованием» живёт в памяти процесса, поэтому новый процесс стартует с ним включённым: он не знает, какие инвалидации потерял предыдущий. Без этого сценарий «logout при недоступном Valkey → рестарт API → Valkey вернулся» давал отозванному токену 200 и 201 на отправку сообщения, пока не истечёт TTL записи (≤ 60 s). Дефект воспроизведён и закрыт регрессионным тестом test_logout_during_outage_then_api_restart в student-tests/level4.py.
  • Пул клиента Valkey — не больше 20 соединений.

9.6. После restart или flush Valkey

Ничего не теряется. Первый запрос не найдёт ключ, проверит сессию в PostgreSQL и снова заполнит кэш.

10. Надёжность работы с PostgreSQL

10.1. Пул и таймауты (app/db.py)

Параметр Значение Зачем
pool_size 10 постоянные соединения
max_overflow 5 временные соединения при пике; всего ≤ 15, API не исчерпает max_connections
pool_timeout 3 s ожидание свободного соединения, потом 503
connect timeout 3 s недоступная БД не держит запрос бесконечно
statement_timeout 5000 ms зависший запрос прерывает сама база
idle_in_transaction_session_timeout 10 s «забытая» открытая транзакция закрывается
pool_pre_ping вкл. разорванное соединение не выдаётся запросу

10.2. Отказ БД → 503

app/main.py (is_dependency_failure, dependency_error_handler) превращает ошибки соединения, таймауты и исчерпание пула в ответ:

{"error":{"code":"unavailable","message":"Service is unavailable.","request_id":"…"}}

Это ответ 503 за ограниченное время: не 500, не зависание, без SQL-текста, stack trace и credentials.

10.3. Единый формат ошибок

Каждый ответ, включая ошибки и health, содержит непустой X-Request-Id, который совпадает с error.request_id. Ошибки валидации FastAPI (по умолчанию 422) переведены в 400 invalid_request, как требует контракт. Неожиданное исключение даёт 500 internal_error без внутренних деталей.

10.4. SQL-инъекции

Все запросы параметризованы: text("… WHERE username = :username"), {"username": …}. Значение передаётся отдельно от текста запроса. Строка '; DROP TABLE users; -- будет воспринята как обычный текст.

11. Индекс и EXPLAIN

11.1. Keyset-пагинация

next_cursor — это непрозрачное base64-представление (created_at, id) последнего элемента страницы и идентификатора ресурса. Cursor от другого чата даёт 400. id нужен как второй ключ, потому что у двух сообщений может совпасть время.

Запрос страницы:

SELECT … FROM messages
WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
ORDER BY created_at, id
LIMIT 51;            -- limit + 1, чтобы понять, есть ли следующая страница

Условие записано сравнением кортежей (created_at, id) > (…). Тогда PostgreSQL применяет его как Index Cond прямо в индексе, а не как Filter после чтения строк.

11.2. Замер (make db-checks, evidence/explain.txt)

Данные: один чат с 10 000 сообщений (всего в таблице ~59 000). Запрашивается страница после 9000-го сообщения.

Вариант План Buffers Время
keyset + messages_keyset_idx Index Scan using messages_keyset_idx, cursor в Index Cond 5 (hit=4 read=1) ~0.1 ms
OFFSET 9000 Sort 9051 строк, 9000 из них отбрасываются 208 ~3.7 ms
без индекса (удалён внутри транзакции, затем ROLLBACK) Seq Scan on messages, ~58 000 строк отброшено фильтром 783 ~2.2 ms

Главная метрика — Buffers (прочитанные страницы по 8 КБ). Время на маленьких данных скачет, а число буферов стабильно. Keyset читает только нужную страницу независимо от глубины; OFFSET и Seq Scan читают тем больше, чем дальше страница.

Время у всех вариантов единицы миллисекунд, потому что таблица целиком в кэше PostgreSQL. Различие видно по buffers: оно растёт вместе с объёмом таблицы (в прогоне на ~84 000 сообщений без индекса было 1106 buffers, у keyset по-прежнему 5).

12. Secrets и Git

  • Реальные secrets генерирует scripts/init-secrets.sh в infra/secrets/*.txt. В контейнеры они передаются как Docker secrets (*_FILE), а не через переменные окружения или compose.yaml.
  • В Git нет ни одного файла с secrets: их создаёт scripts/init-secrets.sh на каждой машине, в репозитории лежит только .env.example без значений.
  • .gitignore исключает infra/secrets/*.txt, .env, .venv/, .venv-wsl/, __pycache__/. .dockerignore дополнительно исключает infra/secrets и .git из build context.
  • Volume postgres_data — объект Docker, он не лежит в дереве репозитория и в Git попасть не может.
  • В evidence/ нет токенов, паролей, DATABASE_URL, заголовков Authorization и реальных сообщений. Официальные тесты не печатают credentials, а restart-hook запускается с подавленным выводом.

Проверка:

git check-ignore -v infra/secrets/postgres_password.txt infra/secrets/database_url.txt .venv-wsl
git status --short     # secrets и venv в списке отсутствуют

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

Стенд: Windows 11, Docker Desktop 29.3 (WSL2 backend), лимиты CPU/RAM для контейнеров не задавались. Клиенты запускались из WSL на том же хосте. Все данные синтетические.

13.1. Нагрузка

tests/load.py: closed-loop, 4 клиента, 15 s, без прогрева и без автоматических повторов, POST /api/v1/chats/{id}/messages, сессии кэшируются в Valkey.

Метрика Значение
Успешных запросов 4 071
Ошибок 0
Successful RPS ≈ 271
p50 / p95 / p99 13.4 / 22.9 / 31.9 ms

Это один прогон, генератор нагрузки работает на той же машине, у closed-loop есть coordinated omission, CPU/RAM не измерялись. Это не оценка максимальной пропускной способности, а подтверждение, что API стабильно пишет под параллельной нагрузкой без ошибок. Для сравнения: ранний прогон без Valkey дал 4 803 запроса / 319.89 RPS / p95 15.8 ms. Разница в пределах разброса одиночных прогонов на Docker Desktop, выводов о влиянии кэша на запись отсюда не делается.

13.2. Отказы

Воздействие Ожидание Наблюдение Восстановление / потеря данных
scripts/restart.sh (docker compose restart db valkey api) данные и сессия сохранены persistence PASS со старым токеном, без повторного входа; CreatedAt volume не изменился готовность за несколько секунд / потерь нет
docker compose stop valkey обход кэша через PostgreSQL вход, чтение и запись успешны, задержка ≤ 0.30 s; поддельный и анонимный запросы → 401 сразу; после старта кэш пуст и заполняется заново
docker compose pause valkey (зависание) таймаут 0.25 s, затем обход 5 s задержка ≤ 0.26 s; токен, отозванный во время отказа, после unpause остаётся 401 благодаря FLUSHDB ~5 s до возврата к кэшу / потерь нет
pause valkey → logout → restart api → unpause valkey отозванный токен не оживает /users/me и отправка сообщения → 401: новый процесс API очищает кэш перед первым использованием сразу после готовности API / потерь нет
docker compose stop db ограниченный 503, анонимным не доверяем запись и вход → 503 unavailable с request_id за ~3 s; ready 503, live 200; анонимный 401; непроверяемый токен 503, никогда 2xx после start db API снова ready, токен не из кэша получает 503, закэшированный может быть опознан на /users/me (раздел 15)
20 параллельных регистраций одного username один 201, остальные 409 {201: 1, 409: 19}, ни одного 500 —

14. Доказательства

Файл Команда Результат
evidence/check_contract.txt make check PASS: offline skeleton structure, local refs and Python syntax
evidence/validate_openapi.txt make validate PASS: full OpenAPI 3.1 and JSON Schema validation
evidence/smoke.txt make test PASS: lab2 public API scenario
evidence/persistence.txt make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: persistence preserved confirmed data and existing session
evidence/migrations_repeat.txt docker compose run --rm migrate SKIP 001…, SKIP 002…, PASS
evidence/level4.txt make test-level4 PASS: level 4 checks
evidence/explain.txt make db-checks rollback PASS, планы EXPLAIN
evidence/load.txt, evidence/load.json python3 tests/load.py --duration 15 --concurrency 4 агрегаты раздела 13.1
evidence/README.md — контекст, commit, стенд, профиль нагрузки

scripts/check_contract.py и scripts/validate_openapi.py проверяют только репозиторий и контракт, приложение они не запускают. Поведение API доказывают smoke, persistence, level4 и db-checks.

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

  • Кэшированная сессия при отказе PostgreSQL. Пока БД недоступна, закэшированная действующая сессия до 60 s продолжает опознавать пользователя на GET /users/me. Отозвать её в это время нельзя, потому что logout тоже требует БД. Все бизнес-операции при этом возвращают 503. Можно уменьшить SESSION_CACHE_TTL_SECONDS или запретить ответы из кэша при недоступной БД.
  • Одна реплика API. Балансировка, X-Instance-Id, idempotency и failover относятся к lab3. Очистка кэша после сбоя рассчитана на один экземпляр: реплика, которая не получала запросов во время отказа Valkey и не перезапускалась, не узнает о потерянной инвалидации. Для нескольких реплик нужна общая эпоха кэша или запись отложенных инвалидаций в PostgreSQL.
  • HTTP без TLS. Допустим только на локальном стенде с синтетическими данными. HTTPS обязателен в lab7.
  • Нагрузка измерена один раз. Для статистических выводов нужны 3–5 повторов, медианы и разброс, а также open-loop генератор на отдельной машине.
  • Хостовое окружение Windows. Официальные тесты и restart.sh требуют POSIX-shell, поэтому на Windows всё запускается через WSL. Полный requirements-dev.txt устанавливается на Python 3.12; runtime в Docker от этого не зависит.
  • Очистка сессий. Истёкшие и отозванные строки sessions пока не удаляются. Нужна периодическая очистка (DELETE … WHERE expires_at < now() - interval '1 day').