59 KiB
Отчёт — лабораторная работа №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:
- Пользователи, чаты, участники, сообщения и сессии хранятся в PostgreSQL на именованном volume
postgres_data. - Структура базы создаётся версионируемыми миграциями. Их можно запустить повторно, и данные не продублируются.
- Регистрация принимает
password. Пароль хранится только в виде хеша Argon2id. - Вход:
POST /api/v1/auth/sessionsс Basic. Сервер выдаёт opaque Bearer-токен, у сессии есть срок жизни, её можно отозвать через logout. - Все остальные бизнес-endpoint принимают только Bearer.
X-User-Idигнорируется. - Данные и ещё действующие сессии переживают перезапуск API и всех хранилищ без удаления volumes.
- На «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).
Порядок работы:
- В Docker Desktop включить Settings → Resources → WSL Integration для своего дистрибутива.
- В PowerShell перейти в папку проекта и выполнить
wsl. WSL откроется в той же папке (путь вида/mnt/c/.../mtusi2026lab2). - Один раз добавить пользователя в группу
docker:sudo usermod -aG docker $USER, затем в PowerShell выполнитьwsl --shutdownи снова войти в WSL. - Один раз установить make:
sudo apt install -y make. - Выдать hook право на исполнение:
chmod +x scripts/restart.sh. Если файл редактировался в Windows, убрать CRLF:sed -i 's/\r$//' scripts/*.sh. - Для
make validate:Полныйpython3 -m venv .venv-wsl && . .venv-wsl/bin/activate pip install openapi-spec-validator==0.7.2 jsonschema referencingrequirements-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:
- создаёт служебную таблицу
schema_migrations, если её ещё нет; - перебирает файлы
migrations/*.sqlв порядке номеров (001_…,002_…); - если версия уже есть в
schema_migrations, печатаетSKIP <файл>; - иначе выполняет 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)
- В
member_idsнет дубликатов → иначе 400. - Вызывающий пользователь есть в
member_ids→ иначе 400. - Все участники существуют (один
SELECT … WHERE id = ANY(...)) → иначе 400. - Только после этого выполняется транзакция
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 без гонки
- Сначала
UPDATE sessions SET revoked_at = now()+COMMITв PostgreSQL. - Затем по тому же ключу записывается 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').