90 KiB
Отчёт — лабораторная 2
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
- Целевая оценка 5; выбранный трек 5: 2 (план запроса и восстановление)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта
Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change
postgres-storage), пароли, вход по Basic и Bearer-сессии
(session-auth), кэш карточки чата в Valkey (membership-cache),
автоматические проверки отказов уровня 4 (failure-checks),
нагрузочный стенд на PostgreSQL и обоснование индекса истории планами
EXPLAIN (ANALYZE, BUFFERS) (bench-postgres), трек 2 часть 1 —
индексы и запросы истории на чатах разного размера и стоимость записи
(track2-query-plans). Впереди: трек 2 часть 2 — backup и
восстановление (track2-backup-restore).
Запуск из чистого clone
Версии. Образ API: python:3.12.14-slim-trixie и uv 0.12.17,
Postgres: postgres:18.6-trixie, Valkey: valkey/valkey:9.1.2-trixie;
все закреплены тегом и digest индекса (amd64 + arm64) в Dockerfile и
docker-compose.yml. Приложение: Python 3.12, FastAPI 0.141.1,
SQLAlchemy 2.1.1 (async), asyncpg 0.31.0, alembic 1.20.0, argon2-cffi
25.1.0, redis-py 8.1.0 и остальное строго по uv.lock. Проверено на
Docker Desktop 29.8.1 (VM linux/arm64), Compose v5.5.1, macOS на Apple
M3 Pro.
Нужно на машине: Docker с BuildKit, make, python3 (3.9+) для
публичных проверок и make test_isolated, свободные порты
127.0.0.1:8080 (API), 127.0.0.1:5433 (Postgres) и 127.0.0.1:6380
(Valkey). uv на хосте нужен для make run_dev (сервис без контейнера)
и для собственных тестов: make student_test, make test_isolated и
make failure_checks запускают uv run pytest. Публичные make test и
make test-persistence обходятся python3.
Подготовка и секреты. make env_setup создаёт .env из
.env.example и config.toml из config_example.toml; существующие
файлы не трогает. В шаблоне пароли Postgres и Valkey пустые, в новый
.env подставляются случайные (openssl rand -hex 16), так что общего
пароля стенда в git нет. Отдельно запускать env_setup не нужно: его
вызывают make run_docker, make run_dev и make test_isolated. Пароль
задаётся Postgres только при создании volume: после смены
POSTGRES_PASSWORD нужен make wipe_data. Пароль Valkey действует со
следующего пересоздания контейнера (make run_docker), volume у Valkey
нет.
.env, созданный до membership-cache. make env_setup его не
меняет, а без VALKEY_PASSWORD любая команда compose останавливается с
VALKEY_PASSWORD is empty, copy Valkey lines from .env.example.
Перенести из .env.example блок Valkey (VALKEY_* и мосты CACHE__*)
и вписать пароль, например openssl rand -hex 16.
git clone <fork> && cd <каталог clone>
git checkout solution/bvt2301-safronov
Способ 1. Всё в compose: make run_docker
make run_docker
# make env_setup (только недостающие .env и config.toml)
# DOCKER_BUILDKIT=1 docker compose build
# docker compose up -d postgres, valkey -> migrate (alembic upgrade head) -> api
Порядок задают depends_on: migrate стартует после healthcheck
Postgres (pg_isready по TCP), API — после healthcheck Valkey и после
того, как migrate завершился с кодом 0. Готовность —
GET http://127.0.0.1:8080/health/ready → 200 (несколько секунд после
команды). Журнал API — make logs, миграций — docker compose logs migrate.
Способ 2. Сервис на хосте: make run_dev
make run_dev
# docker compose up -d --wait postgres
# uv run alembic upgrade head -> 127.0.0.1:5433
# docker compose up -d --wait valkey
# APP__RUN_MODE=console uv run python -m src
Сервис слушает 127.0.0.1:8080 с reload по src/, Postgres и Valkey —
те же контейнеры (и тот же volume Postgres), что у способа 1.
Переключение между способами не требует правки файлов (раздел
«Конфигурация»).
Проверки
make check # структура skeleton
make validate PYTHON=.venv/bin/python # OpenAPI 3.1 (после uv sync --all-extras)
make test_isolated # образ на временной базе: smoke + student-tests, уборка
make failure_checks # проверки отказов на отдельном стенде, ~45 с
make student_test # собственные тесты против запущенного стенда (BASE_URL)
make test # публичный smoke против запущенного стенда
make test-persistence ACTION_SCRIPT=scripts/restart.sh # данные и прежний токен после рестарта
Ожидаемо: make test и make test-persistence — PASS,
make test_isolated — код 0 и 103 passed, 12 deselected
(evidence/tests/test-isolated.md), make failure_checks — код 0 и
12 passed (evidence/tests/failure-checks.md).
make failure_checks поднимает свой проект compose
mtusi-lab2-failures: свои Postgres и Valkey со своим volume, без
публикации их портов, обычный API и API со сроком сессии 2 с и пулом из
одного соединения. Тесты с маркером fault останавливают и замораживают
хранилища этого стенда через hook student-tests/fault_hook.py, после
прогона стенд удаляется вместе с volume. Рабочий стенд не трогается. Два
прогона одновременно не запускать.
Сценарий защиты
echo yes | make wipe_data && make run_docker # миграции на пустом volume
# регистрация, вход, сообщение — тем же сценарием, что в tests/smoke.py:
make test # PASS
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт API, Postgres и Valkey, тот же токен
# logout и повтор прежним токеном: test_logout, test_logout_twice в make test_isolated
# короткий срок сессии, отказ БД и Valkey, откат создания чата — одной командой:
make failure_checks # 12 passed, рабочий стенд не трогается
# или срок сессии вручную — отдельным экземпляром в консоли:
AUTH__SESSION_TTL_SECONDS=2 python3 .claude/skills/run-mtusi-messenger/driver.py --port 18080 start
# роль Valkey: ключи карточек, срок, отказ кэша
docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" --scan --pattern "messenger:*" | head -3'
docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" INFO stats' | grep keyspace_
docker compose stop valkey # чат, сообщения и /health/ready — те же ответы; make logs: warning
docker compose start valkey # через 5 с кэш снова работает; make logs: info
valkey-cli в контейнере берёт пароль из переменной VALKEYCLI_AUTH, в
командной строке его нет.
Вручную вход и запрос выглядят так (пароль и токен — свои):
curl -s -X POST localhost:8080/api/v1/users -H 'Content-Type: application/json' \
-d '{"username":"alice_demo","display_name":"Алиса","password":"<пароль 12–128>"}'
curl -s -X POST localhost:8080/api/v1/auth/sessions -u 'alice_demo:<пароль>' # 201 Session
curl -s localhost:8080/api/v1/users/me -H 'Authorization: Bearer <token>' # 200
curl -s -X DELETE localhost:8080/api/v1/auth/sessions/current -H 'Authorization: Bearer <token>' # 204
Миграция 42bc3b9be38f удаляет данные лабы 1. У пользователей,
созданных до session-auth, нет пароля, войти они не смогут, а хэш
теперь обязателен. Поэтому при первом make run_docker или
make run_dev на старом volume миграция удаляет таких пользователей
вместе с чатами, участниками и сообщениями и пишет их число в журнал
migrate (warning). Данные стенда синтетические
(evidence/migrations/drop-lab1-data.md).
Остановка и удаление данных
make stop— остановить контейнеры;make down— удалить контейнеры, volumepostgres_dataс данными остаётся, кэш Valkey теряется (он без volume, данные от этого не страдают);make wipe_data— удалить контейнеры и volume, только после вводаyes; следующийmake run_dockerподнимает пустую базу со схемой и пустой кэш.
Архитектура и решения
клиент --HTTP--> api (FastAPI, 1 процесс) --asyncpg, пул--> postgres (volume postgres_data)
| ^
| migrate (тот же образ, alembic upgrade head, до старта api)
+--redis-py, пул--> valkey (кэш карточек чатов, без volume)
Источник истины — PostgreSQL. Пользователи, чаты, участники, сообщения и сессии хранятся только в нём; память процесса, файлы и SQLite не используются. Valkey держит только копию неизменяемых карточек чатов (раздел «Кэш Valkey»). Подтверждённая запись (201, 204) зафиксирована commit до ответа.
Сервисы стенда (docker-compose.yml, infra/README.md):
| Роль | Сервис | Версия / digest | Healthcheck / готовность | Volume | Сеть и порт | Credentials |
|---|---|---|---|---|---|---|
| api | api (образ mtusi-messenger:lab2 из Dockerfile) |
python:3.12.14-slim-trixie@sha256:f77ac9e4… |
HEALTHCHECK образа: GET /health/ready на APP__PORT |
нет | внутри APP__PORT (8080), публикация 127.0.0.1:${APP_OUT_PORT} |
DATABASE__PASSWORD, CACHE__PASSWORD из environment compose (.env); config.toml монтируется read-only |
| миграции | migrate (тот же образ) |
тот же | одноразовый, api ждёт service_completed_successfully |
нет | только сеть compose | как у api |
| postgres | postgres |
postgres:18.6-trixie@sha256:5a5a84b1… |
pg_isready -h 127.0.0.1 по TCP |
postgres_data → /var/lib/postgresql |
POSTGRES_PORT (5432), алиас POSTGRES_HOST, публикация 127.0.0.1:${POSTGRES_OUT_PORT} (5433) |
POSTGRES_USER / POSTGRES_PASSWORD из .env |
| redis_or_valkey | valkey |
valkey/valkey:9.1.2-trixie@sha256:418652cf… |
valkey-cli ping = PONG (после AUTH из VALKEYCLI_AUTH) |
нет: persistence выключен, кэш | VALKEY_PORT (6379), алиас VALKEY_HOST, публикация 127.0.0.1:${VALKEY_OUT_PORT} (6380) |
VALKEY_PASSWORD из .env → --requirepass через переменную контейнера; конфиг infra/valkey/valkey.conf read-only |
Bootstrap у Valkey нет: пустой кэш — штатное состояние, он заполняется
при чтении. Схему Postgres создаёт migrate; повтор безопасен
(«Доказательства критериев»).
Схема (миграции migrations/versions/…_added_messenger_tables.py и
…_added_sessions_and_password_hashes.py):
| Таблица | Ключи и ограничения | Индексы |
|---|---|---|
users |
PK id; UNIQUE username; CHECK шаблона username и длины display_name; password_hash NOT NULL, CHECK LIKE '$argon2id$%' — открытый пароль или быстрый хэш не запишется |
uq_users_username |
sessions |
PK id; FK user_id → users; UNIQUE token_hash (SHA-256 токена, bytea, CHECK 32 байта); CHECK expires_at > created_at |
uq_sessions_token_hash — проверка токена |
chats |
PK id; CHECK длины title |
— |
chat_members |
PK (chat_id, user_id); FK на chats и users; UNIQUE (chat_id, position); position хранит порядок member_ids |
(user_id, created_at, chat_id) — keyset списка чатов |
messages |
PK id; составной FK (chat_id, sender_id) → chat_members: отправитель обязан быть участником; CHECK длины text |
(chat_id, created_at, id) — keyset истории |
id и created_at назначает сервис (uuid4(), utcnow()), а не БД.
chat_members.created_at — копия времени чата, по ней список чатов идёт
keyset-ом по индексу без сортировки всех чатов пользователя. CHECK
дублируют контракт: первым отвечает API (400), сработавший CHECK —
дефект валидации.
Транзакционные границы. Одна AsyncSession на запрос, commit делает
сервис, изоляция READ COMMITTED:
| Операция | Шаги в одной транзакции |
|---|---|
| регистрация | хэш пароля (до БД) → INSERT … ON CONFLICT (username) DO NOTHING RETURNING; конфликт → 409 |
| вход | транзакция 1: SELECT учётных данных → commit (соединение возвращается в пул); проверка пароля вне БД; транзакция 2: INSERT sessions → commit |
| запрос с токеном | один SELECT sessions JOIN users WHERE token_hash = … AND expires_at > now |
| выход | DELETE FROM sessions WHERE id = … → commit |
| создание чата | проверка существования участников → INSERT chats → INSERT chat_members (одна вставка) → commit; ошибка до commit — откат, не остаётся ни чата, ни участников. После commit карточка пишется в Valkey |
| сообщение | проверка членства по карточке чата (Valkey, при промахе — SELECT) → INSERT messages → commit |
| чтения | карточка чата — из Valkey или одним SELECT; история и список чатов — один SELECT |
Явные блокировки не нужны: пользователи и участники не меняются и не
удаляются, гонку регистрации закрывает уникальный индекс (тест
test_same_username_at_once: из 10 одновременных регистраций одна 201,
девять 409).
Пагинация. Курсор — ключ (created_at, id) последнего элемента;
запрос — сравнение кортежей по индексу, без OFFSET. Повторов при обходе
нет. Сообщение, которое закоммитилось позже, но с created_at меньше уже
пройденного курсора, текущий обход пропустит, а новый обход с начала
увидит. Время ставит один процесс API с часами хоста; при нескольких
репликах лабы 3 часы общие (один Docker-host).
Индекс истории. Страница истории — один запрос repo
get_chat_messages_page. Текст — из журнала Postgres, как его выполнило
приложение:
SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at
FROM messages
WHERE messages.chat_id = $1::UUID
AND (messages.created_at, messages.id) > ($2::TIMESTAMP WITH TIME ZONE, $3::UUID)
ORDER BY messages.created_at, messages.id
LIMIT $4::INTEGER -- limit + 1 = 51
Первая страница — тот же запрос без условия по курсору. Индекс
ix_messages_chat_id_created_at_id (chat_id, created_at, id)
повторяет условие и порядок:
- равенство по
chat_id; - диапазон по ключу курсора в порядке
ORDER BY.
Postgres спускается по B-дереву к курсору и читает следующие 51 запись,
без сортировки и OFFSET.
Как сняты планы. EXPLAIN (ANALYZE, BUFFERS) из метки baseline
(commit e61a0e5):
- данные — один чат из N сообщений после
VACUUM (ANALYZE); - план с индексом — запрос самого приложения, снятый
auto_explain; - «без индекса» — тот же текст с теми же параметрами в psql, после
DROP INDEXвнутри транзакции, которая откатывается.
Буферы — shared hit верхнего узла плана (страницы по 8 КБ). Чтений с
диска нет (read=0).
| Сообщений | Страница (после скольких сообщений) | Узел | Буферы | Время, мс |
|---|---|---|---|---|
| 10 000 | первая (0) | Index Scan using ix_messages_chat_id_created_at_id |
3 | 0,034 |
| средняя (5 000) | Index Scan, тот же индекс |
54 | 0,049 | |
| последняя (9 900) | Index Scan, тот же индекс |
54 | 0,046 | |
| средняя без индекса | Seq Scan + Sort |
209 | 0,848 | |
| 100 000 | первая (0) | Index Scan, тот же индекс |
4 | 0,031 |
| средняя (50 000) | Index Scan, тот же индекс |
50 | 0,042 | |
| последняя (99 900) | Index Scan, тот же индекс |
54 | 0,050 | |
| средняя без индекса | Parallel Seq Scan + Sort |
1 948 | 6,933 | |
| 500 000 | первая (0) | Index Scan, тот же индекс |
4 | 0,038 |
| средняя (250 000) | Index Scan, тот же индекс |
47 | 0,048 | |
| последняя (499 500) | Index Scan, тот же индекс |
55 | 0,049 | |
| средняя без индекса | Parallel Seq Scan + Sort |
9 678 | 20,124 |
Что видно в таблице:
- С индексом страница стоит одинаково на любой глубине истории и при любом её размере. Первая страница — 3–4 буфера, остальные — 47–55, время около 0,05 мс. Пагинация не просматривает историю до курсора.
- Без индекса тот же запрос читает всю таблицу (9 678 буферов по 8 КБ на 500k — это вся таблица, 75 МиБ) и сортирует найденное. Стоимость растёт с таблицей: при данных ×50 буферы выросли ×46, время — ×24 (с 100k Postgres сканирует в три процесса).
- На строку страницы приходится около одной страницы таблицы (47–55
буферов на 51 строку). Вероятная причина, отдельно не проверенная:
соседние сообщения чата лежат на разных страницах, потому что их
вставляли 32 клиента наполнения через разные соединения.
Покрывающий индекс (
Index Only Scan) убрал бы чтения таблицы. Трек 2 его сравнил: 5 буферов вместо ~50, но сообщение из 4000 символов в строку такого индекса не влезает, и индекс оставлен прежним (раздел «Трек 2, часть 1»).
Файлы: evidence/bench/baseline/explain-{10k,100k,500k}.txt — планы
целиком. Сводка — раздел «Планы запроса истории» в
evidence/bench/baseline/summary.md. Как устроен замер — раздел
«Нагрузочный стенд на PostgreSQL» ниже.
Недоступность БД. Критичная зависимость /health/ready — PostgreSQL
(SELECT 1 с таймаутом 2 с). Valkey /health/ready не проверяет: без
кэша обязательные запросы обслуживаются из Postgres (раздел «Кэш
Valkey»). Ошибки соединения и таймауты на
бизнес-запросе дают 503 unavailable без деталей, причина пишется в
журнал (warning), после возврата Postgres запросы обслуживаются без
рестарта API. Таймауты: подключение 3 с, ожидание соединения пула 5 с,
серверный statement_timeout 5 с, срок всей работы запроса с БД 6 с;
пул 10 + 5 соединений. При замёрзшем сервере ответ приходит через 6 + 2 с:
2 с — ограниченное мягкое закрытие прерванного соединения. Без этого
ограничения asyncpg и SQLAlchemy ждали разморозки сервера (169 с в
замере); подробности — design change postgres-storage, решение 6.
Пароли и сессии.
- Пароль — Argon2id (argon2-cffi), профиль RFC 9106 low-memory назван в коде явно: t = 3, m = 64 MiB, p = 4, соль 16 байт, хэш 32 байта. Около 30 мс на хэш или проверку. Пароль хэшируется целиком как UTF-8, без обрезки: 128 кириллических символов (256 байт) сравниваются полностью, поэтому не bcrypt (72 байта). Lab7 требует Argon2id.
- KDF не в event loop: в потоке через
anyio.to_thread.run_syncсо своим лимитом[auth] kdf_concurrency= 4. Пик памяти 4 × 64 MiB, а не 40 × 64 MiB при общем пуле потоков anyio. Пока считается пароль, соединение БД отпущено. - Неизвестный username проверяется против фиктивного хэша: время
ответа то же, что у неверного пароля (26,0 и 26,4 мс в медиане,
evidence/auth/passwords-and-tokens.md). Ответ одинаковый: 401 сWWW-Authenticate: Basic realm="messenger", charset="UTF-8". - Вход — только
Authorization: BasicнаPOST /auth/sessions. Разбор свой: FastAPIHTTPBasicдекодирует ASCII и на пароле не из ASCII сам отвечает 401 мимо формата контракта. Схема объявлена черезHTTPBase, base64 строго, UTF-8, первое двоеточие. Username не по шаблону и пароль вне 12–128 отсекаются до БД и KDF тем же 401. Ответа 400 у входа нет: любой сбой Basic — 401. - Токен —
secrets.token_urlsafe(32): 256 бит, 43 символа, ничего не кодирует. В БД — только его SHA-256: быстрого хэша достаточно, перебирать 256 бит нечего. - Сессия — строка
sessionsсexpires_at, фиксированным при входе. Срок не продлевают ни запросы, ни рестарт. Каждый запрос — одинSELECTпоtoken_hash, поэтому отзыв мгновенный:DELETEстроки, кэша нет. Истёкший, отозванный или неизвестный токен, Basic на бизнес-ручке — 401 сWWW-Authenticate: Bearer realm="messenger".X-User-Idигнорируется. - Недоступность Postgres при запросе с токеном — 503
unavailable, не 401 и не анонимный доступ (evidence/auth/expiry.md). - Журнал не содержит паролей, токенов, их хэшей,
Authorizationи username. Вход, неудачный вход и выход пишутся сuser_idиidсессии. Параметры SQL в ошибках драйвера скрыты (hide_parameters).
Кэш Valkey (change membership-cache, спек chat-cache). Из пары
Redis / Valkey выбран Valkey 9.1, клиент — redis-py (redis.asyncio):
протокол тот же, а асинхронный клиент redis-py зрелее valkey-py.
- Роль — кэш карточки чата:
id,title,member_idsв порядке создания,created_at. Её читают три самых частых запроса:GET /chats/{id},POST …/messages(проверка членства) иGET …/messages. Сессии в Valkey не хранятся: они в Postgres ради мгновенного отзыва. История и список чатов не кэшируются: они меняются с каждой записью. - Источник истины — PostgreSQL. Чтение: Valkey → при промахе
SELECTи запись в кэш (cache-aside). Новый чат пишется в кэш после commit: откат создания не оставит в кэше чата, которого нет в БД. Отсутствующий чат не кэшируется. - Ключ —
messenger:v1:{имя базы}:chat:{chat_id}, значение — JSON. Имя базы разделяет рабочий стенд иmake test_isolated(базаtest_<db>) на одном Valkey;v1— версия формата значения. - Expiry и вытеснение. Срок записи —
[cache] chat_ttl_seconds(3600 с), чтения его не продлевают. Память ограниченаmaxmemory 64mb, при нехватке —allkeys-lru(infra/valkey/valkey.conf). Срок здесь ограничивает память, а не свежесть. - Инвалидация не нужна. По контракту чат и его участники после
создания не меняются и не удаляются, поэтому устаревшей карточки через
API получить нельзя. Граница этого допущения — правка базы в обход API.
Восстановление из backup (трек 2) откатывает базу, и в кэше остаются
карточки чатов, созданных после снятия backup. Поэтому процедура
восстановления заканчивается
FLUSHALL(changetrack2-backup-restore). - Отказ Valkey — обход, а не ошибка. Вся команда кэша — ожидание
пула, соединение и ответ — ограничена 0,2 с (
asyncio.timeout). redis-py по умолчанию повторяет команду с backoff, и замороженный Valkey держал бы запрос 6,27 с, а остановленный — 3,98 с (замер перед выбором). Поэтому повтор один и только на обрыв соединения (ConnectionError), без паузы; таймаут не повторяется. При ошибкеCacheвозвращает промах, запрос идёт в Postgres с тем же ответом, а кэш пропускается 5 с ([cache] retry_after_seconds). В журнал — одинwarning«Cache is unavailable» на отказ иinfo«Cache is available again» при возврате. Аутентификация от кэша не зависит, поэтому анонимного доступа отказ не открывает. Пул соединений —BlockingConnectionPoolна 10: при всплеске запрос ждёт свободное соединение, а не считает здоровый Valkey отказавшим. - Flush и рестарт. Persistence выключен (
save "",appendonly no), volume нет: послеFLUSHALLили рестарта кэш пуст и заполняется при чтении, данные и сессии в Postgres не страдают.scripts/restart.shперезапускает и Valkey. Рестарт одного Valkey при работающем API отказом не считается: соединение пула, закрытое сервером, повтор открывает заново. - Эффект (
evidence/cache/hits.md): из 50 чтений одной карточки Postgres читает таблицуchatsодин раз, без кэша — 50 раз. Время ответа на этом стенде почти то же (1,6 против 1,7 мс в медиане): таблица маленькая. Замер под нагрузкой — changebench-postgres.
Конфигурация. Адреса, порты и учётные данные — из .env, пул,
таймауты, срок сессии и срок записей кэша — из config.toml
([database], [auth], [cache]). Переключение консоль ↔ docker — без
правки файлов. Консольный сервис читает .env с мостами DATABASE__* и
CACHE__*; в контейнер .env не попадает, адреса и порты Postgres и
Valkey приходят из environment compose. В compose нет литералов
адресов и портов Postgres и Valkey, литерал — только адрес публикации
127.0.0.1 (evidence/storage/postgres-port.md,
evidence/cache/config.md).
Переменная skeleton (.env.example) |
В этом проекте |
|---|---|
APP_HOST |
режим APP__RUN_MODE: console — 127.0.0.1, docker — 0.0.0.0 |
APP_PORT |
APP__PORT (внутри), APP_OUT_PORT (публикация на 127.0.0.1) |
APP_ENV |
не используется: окружение одно — учебный стенд |
SESSION_TTL_SECONDS |
[auth] session_ttl_seconds в config.toml, по умолчанию 3600; разовая подмена — окружением AUTH__SESSION_TTL_SECONDS (так короткий срок 2 с для проверки истечения). Мостом из .env не заводится: его читает только приложение, а окружение мост по исходному имени не перекрывает |
DATABASE_URL_FILE |
не используется: URL собирает приложение из [database], пароль — мостом из POSTGRES_PASSWORD |
SESSION_STORE |
postgres: таблица sessions, без кэша — отзыв мгновенный. Отдельной настройки нет |
CACHE_URL_FILE |
не используется: адрес и порт Valkey — VALKEY_HOST, VALKEY_PORT (в сети compose) и VALKEY_OUT_PORT (консоль) в .env, пароль — мостом из VALKEY_PASSWORD в [cache] password; таймаут, окно пропуска, срок записей и пул — [cache] в config.toml |
Что перенесено из лабы 1 и что изменено. Хранилище MemoryStore
заменено PostgreSQL, repo и сервисы переписаны на AsyncSession, цель
make run_no_compose удалена: API без Postgres не обслуживает запросы.
Переход API 1 → 2 (COURSE.md): X-User-Id заменён Bearer-сессией,
регистрация требует пароль, student-tests идентифицируются токеном.
Данные лабы 1 без паролей удаляет миграция (см. «Сценарий защиты»).
Согласования с преподавателем из лабы 1 действуют: FastAPI с его
расхождениями и конфиг через config.toml (AGENTS.md).
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test_isolated (внутри — make test против образа) |
PASS: lab2 public API scenario |
evidence/tests/test-isolated.md |
PostgreSQL содержит пользователей, чаты, участников и сообщения; PK/FK, уникальный username |
\d в psql, alembic check после миграций |
4 таблицы, ограничения и индексы по таблице выше; модели совпадают со схемой | evidence/migrations/from-zero-and-rerun.md, migrations/versions/ |
| Миграции с нуля и повторно без дублирования | make wipe_data, make run_docker, docker compose run --rm migrate |
migrate завершился с кодом 0 до старта API; повтор — no-op, число строк не изменилось |
evidence/migrations/from-zero-and-rerun.md |
| API не стартует при ошибке миграции | migrate с несуществующей базой через override-файл compose |
up — код 1, migrate Exited (1), api создан, но не запущен; ошибка в журнале migrate |
evidence/migrations/migration-error.md |
| Запуск из чистого clone: консоль, затем docker | git clone, make env_setup, make run_dev, make run_docker, make down + make run_docker |
консоль с нуля: Postgres, миграции и ready 200 одной командой; docker видит данные из консоли без правки файлов; после make down данные на месте |
evidence/storage/fresh-clone.md |
| Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: прежний токен читает те же данные; у API, Postgres и Valkey новые StartedAt; кэш после рестарта пуст и заполняется заново |
evidence/cache/flush-restart.md; до Valkey — evidence/storage/test-persistence.md; порядок участников и истории — evidence/storage/restart.md (снят до session-auth, с X-User-Id) |
| Миграция к паролям на старой базе | make run_docker на volume с данными лабы 1, затем docker compose run --rm migrate |
warning «Deleted lab 1 data without passwords: 225 users…», password_hash NOT NULL, таблица sessions; повтор — no-op |
evidence/migrations/drop-lab1-data.md |
| Составная операция создания чата атомарна (уровень 4: rollback составной операции) | test_members_failure_rolls_back_chat в make failure_checks: триггер в базе стенда отказов роняет вставку участников |
POST /chats — 500 internal_error; чата нет в списках обоих участников, count(*) по его названию — 0: вставка строки чата откатилась вместе с участниками |
evidence/tests/failure-checks.md |
Basic только на POST /auth/sessions, остальное — Bearer; X-User-Id не даёт доступ |
smoke и test_identification.py, test_sessions.py в make test_isolated |
Basic на /users/me — 401 с вызовом Bearer; только X-User-Id — 401; Bearer alice с X-User-Id eve — alice; битый Basic — 401 с вызовом Basic |
evidence/tests/test-isolated.md |
Схемы bearerAuth и basicAuth в документации API |
test_security_schemes_in_openapi; вручную в /docs |
/openapi.json совпадает с контрактом, devUser нет; в /docs вход через Authorize (Basic, пароль из ASCII) и запрос с Bearer работают — проверено автором 2026-10-01 |
evidence/tests/test-isolated.md |
| Срок жизни сессии | сервис с AUTH__SESSION_TTL_SECONDS=2 |
200 сразу, 401 через 2,1 с; запросы каждые 0,5 с срок не продлевают | evidence/auth/expiry.md (вручную); автоматически — строка «Уровень 4: автоматическая проверка expiry» |
Срок сессии — настройка (SESSION_TTL_SECONDS контракта) |
сервис с разными config.toml и окружением |
без [auth] — 3600 с, session_ttl_seconds = 600 — 600 с, окружение AUTH__SESSION_TTL_SECONDS=2 поверх файла — 2 с; abc и 0 — запуск останавливается |
evidence/auth/ttl-config.md |
| Отзыв сессии | DELETE /auth/sessions/current: test_logout, test_logout_twice, test_other_session_survives_logout |
204 без тела, дальше этот токен — 401 везде; вторая сессия работает | evidence/tests/test-isolated.md |
| Пароли — password KDF | psql, pg_dump --data-only, журнал API |
$argon2id$v=19$m=65536,t=3,p=4$…, у одинаковых паролей разные хэши; пароля и токена нет ни в БД, ни в журнале; в sessions — SHA-256 токена |
evidence/auth/passwords-and-tokens.md |
| Secrets и volumes не в git | .gitignore, make env_setup |
.env, config.toml игнорируются; пароли Postgres и Valkey генерируются локально |
.gitignore |
| Собственные тесты против контейнера | make test_isolated и make failure_checks |
test_isolated — код 0: smoke PASS, 103 passed (12 проверок отказов deselected); failure_checks — 12 passed; 108 сценариев спеков: 98 тестами (13 — проверками отказов), 10 исключениями; стенды убираются при любом исходе |
evidence/tests/test-isolated.md, evidence/tests/failure-checks.md, evidence/tests/test-isolated-mechanics.md |
Конфигурация из .env, без литералов адреса и порта Postgres в compose |
POSTGRES_PORT и POSTGRES_OUT_PORT изменены в .env, make run_docker, make run_dev |
оба способа запуска подключились к новому порту, compose не правился | evidence/storage/postgres-port.md |
Порты и пароль Valkey из .env |
VALKEY_PORT, VALKEY_OUT_PORT и VALKEY_PASSWORD изменены в .env, make run_docker, driver.py start |
сервер слушает новый порт, публикация только на 127.0.0.1; docker и консоль пишут карточки в кэш; прежний пароль — WRONGPASS, без пароля — NOAUTH; compose не правился |
evidence/cache/config.md |
| Уровень 4: Redis/Valkey с ролью, источником истины, expiry и инвалидацией | 50 чтений одной карточки; TTL ключа; INFO stats |
новый чат в кэше сразу после commit, TTL 3600 с; 50 чтений — одно чтение таблицы chats и 49 попаданий, без кэша — 50 чтений таблицы; ключи make test_isolated под своим префиксом |
evidence/cache/hits.md; роль и политика — раздел «Кэш Valkey» |
| Уровень 4: недоступность Redis/Valkey — корректный обход кэша | docker compose stop / pause / start / unpause valkey |
ответы 200 / 201 / 200 с теми же телами, /health/ready 200; отказ добавляет к одному запросу не больше 0,2 с (остановленный — 97 мс, зависший — 207 мс; 30 одновременных — до 201 мс), дальше 5 с без обращений; после возврата кэш работает без рестарта API; один warning и одно info на отказ, пароля в журнале нет |
evidence/cache/outage.md |
| Flush и рестарт кэша | FLUSHALL, docker compose restart valkey, scripts/restart.sh |
ответы те же, кэш заполняется при чтении; рестарт одного Valkey при работающем API — без отказа: старое соединение пула переоткрыто повтором | evidence/cache/flush-restart.md |
| Уровень 4: ограниченный пул и таймауты | пул из одного соединения, Postgres на паузе | второй запрос — 503 через 1 с (pool_timeout), первый — 503 через 6 + 2 с |
evidence/storage/pool-timeout.md |
| Уровень 4: таймаут запроса и логи без содержимого сообщений | messages под ACCESS EXCLUSIVE, POST сообщения |
503 через 5 с по statement_timeout; в журнале SQL и причина, параметры скрыты (hide_parameters), текста сообщения нет; до исправления он там был |
evidence/storage/statement-timeout.md |
| Уровень 4: недоступность БД | docker compose stop и pause postgres |
503 unavailable без деталей, /health/live 200, после возврата — без рестарта API |
evidence/storage/db-unavailable.md |
| Уровень 4: недоступность БД при запросе с токеном | docker compose stop postgres, GET /users/me и вход |
503 unavailable, не 401 и не анонимный доступ; после start тот же токен — 200 |
evidence/auth/expiry.md |
| Уровень 4: автоматические проверки logout и неверного пароля | test_logout, test_wrong_password (test_rubric.py) в make test_isolated |
выход — 204, повтор — 401 Bearer; неверный пароль — 401 Basic без токена | evidence/tests/test-isolated.md |
Уровень 4: автоматическая проверка expiry при коротком SESSION_TTL_SECONDS |
test_expired_token, test_use_does_not_extend_session в make failure_checks (API со сроком 2 с) |
200 сразу, 401 с вызовом Bearer через 3 с; запросы каждые 0,5 с срок не продлевают | evidence/tests/failure-checks.md |
| Уровень 4: автоматическая проверка недоступности БД | 5 тестов make failure_checks: stop / pause postgres на стенде отказов |
сообщение, запрос с токеном и readiness — 503 без деталей и без WWW-Authenticate, /health/live 200; исчерпанный пул — 503 быстрее 1,5 с; после возврата — тот же токен 200 и запись проходит, неподтверждённая запись не появилась |
evidence/tests/failure-checks.md |
| Уровень 4: автоматическая проверка недоступности Valkey | 5 тестов make failure_checks: stop / pause / start valkey, FLUSHALL |
ответы 200 / 201 / 200 с теми же телами, каждый быстрее 0,5 с; зависший Valkey — не больше медианы + 0,2 + 0,3 с, дальше окно пропуска; /health/ready 200; после возврата и FLUSHALL кэш снова пишется и читается |
evidence/tests/failure-checks.md |
Уровень 4: гонка регистрации одного username |
test_same_username_at_once в make test_isolated |
10 клиентов, в полёте одновременно 10: одна 201, девять 409 | evidence/tests/test-isolated.md |
| Уровень 4: параметризованные запросы | код repo | SQLAlchemy Core/ORM с параметрами, SQL из строк нет | src/core/repos/ |
| Уровень 4: индекс истории обоснован запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация без полного scan | make bench BENCH_LABEL=baseline: auto_explain запроса приложения на 10k / 100k / 500k; тот же запрос без индекса в откатываемой транзакции |
Index Scan по (chat_id, created_at, id): 3–4 буфера на первую страницу, 47–55 на среднюю и последнюю на любом размере, около 0,05 мс. Без индекса — скан всей таблицы: 9 678 буферов и 20 мс на 500k. p50 чтения на 500k выше, чем на 10k, на 1–4% |
evidence/bench/baseline/explain-*.txt, summary.md; раздел «Индекс истории» |
| Трек 5 №2, часть 1: ≥100 000 сообщений в чатах разного размера, ≥2 индекса и запроса, стоимость записи | make bench BENCH_LABEL=track2: 110 000 / 200 000 / 600 000 сообщений в 1 111 чатах от 10 до 500 000; планы приложения по уровням чатов, 6 вариантов страницы сравнения в откатываемой транзакции, пробы записи по 4 вариантам индекса |
индекс приложения — 5–55 буферов на любой странице любого чата; or-cursor — 252 338 буферов и 44 мс на середине чата 500k; chat_only — до 11 590; covering — 5 буферов, но +100 байт индекса и +17–34% WAL на сообщение, а сообщение из 4000 символов не вставляется. Индекс и запрос приложения оставлены по правилу выбора, записанному до замера |
evidence/bench/track2/summary.md, explain-*.txt; раздел «Трек 2, часть 1» |
| Трек 5 №2, часть 2: backup → восстановление в новое хранилище → сверка | — | TODO (change track2-backup-restore) |
TODO |
Эксперименты и отказы
Стенд: Docker Desktop 29.8.1 на macOS (Apple M3 Pro), ВМ Docker 12 CPU и
7 GiB RAM, лимиты контейнерам не задавались; таймауты — по умолчанию из
config_example.toml.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker compose stop postgres |
503 вместо 500, ready 503, live 200 | 503 через 0,01 с; ready 503, live 200 | после start — сразу, без рестарта API; подтверждённые данные на месте |
docker compose pause postgres (сервер завис) |
503 не позже срока запроса и закрытия соединения (6 + 2 с) | 503 через 8,0 с, ready 503 через 2 с | после unpause — сразу |
| пул исчерпан (1 соединение, сервер завис) | ожидание не дольше pool_timeout |
503 через 1,0 с | после unpause — сразу |
messages под ACCESS EXCLUSIVE 8 с |
503 по statement_timeout, в журнале нет параметров SQL |
503 через 5,0 с, параметры скрыты | после снятия блокировки — сразу |
migrate завершился ошибкой |
API не стартует | api в состоянии Created, up — код 1 |
make run_docker с верной базой — сразу |
scripts/restart.sh (API и Postgres) |
данные и порядок на месте | hook 3,5 с, готовность через 1 с после него | потерь нет |
make test-persistence с тем же hook |
прежний токен работает | PASS, вся проверка 4,9 с |
сессии и данные на месте |
scripts/restart.sh (API, Postgres и Valkey) |
данные и сессии на месте, кэш пуст | hook 3,6 с, готовность через 1 с; DBSIZE Valkey 0, первое чтение снова пишет карточку |
потерь нет; кэш теряется штатно |
docker compose stop valkey |
те же ответы из Postgres, ready 200, не больше 0,2 с добавки | первый запрос 97 мс (повтор на обрыв и неразрешимое имя valkey), следующие 2–7 мс; ready 200; один warning |
после start — через окно пропуска 5 с, без рестарта API |
docker compose pause valkey (кэш завис) |
+срок команды 0,2 с к одному запросу | первый запрос 207 мс, следующие 3–10 мс; 30 одновременных команд — 200–201 мс; ready 200 | после unpause — через 5 с |
FLUSHALL |
тот же ответ, кэш заполняется | 200, ключ снова есть | — |
docker compose restart valkey при работающем API |
тот же ответ, без отказа | 200 за 6 мс, ключ сразу записан; warning нет — повтор переоткрыл соединение, закрытое сервером. До правки клиента (cae4b09): warning и 5 с без кэша |
сразу |
срок сессии 2 с (AUTH__SESSION_TTL_SECONDS=2) |
401 после срока, запросы не продлевают | первый 401 через 2,1 с при запросах каждые 0,5 с | — |
| Postgres остановлен, токен действующий | 503, не 401 | 503 unavailable на /users/me и на вход |
после start тот же токен — 200 |
| миграция к паролям на базе лабы 1 | данные без паролей удалены, это видно в журнале | warning с числом 225, password_hash NOT NULL |
данные лабы 1 удалены намеренно (синтетические) |
make failure_checks: 12 автоматических проверок отказов на отдельном стенде |
истечение, отказы БД и Valkey, пул, откат — как в строках выше, без ручных шагов | 12 passed, весь прогон 45 с; рабочий стенд — те же StartedAt и число строк |
стенд отказов удалён вместе с volume; рабочие данные не тронуты |
| сбой вставки участников (триггер на стенде отказов) | откат всей транзакции создания чата | 500 internal_error, строки чата нет |
частичная запись не осталась |
Нагрузочный стенд на PostgreSQL: базовый замер
Зачем: план запроса истории на ≥10 000 сообщениях (уровень 4) и
базовая метка для сравнений трека 2. Команда — make bench BENCH_LABEL=baseline, методика — .claude/rules/bench.md и design
change bench-postgres.
Стенд. Свой проект compose mtusi-bench: те же образы Postgres и
Valkey, что у рабочего стенда, без портов хоста и без .env и
config.toml рабочего стенда. Лимиты без swap:
| Контейнер | CPU | Память |
|---|---|---|
| API | 1 | 2 ГБ |
| PostgreSQL | 4 | 3 ГБ |
| Valkey | 2 | 512 МБ |
Генератор k6 работает в той же сети без лимита. Postgres — настройки
образа (shared_buffers 128 МБ) плюс auto_explain, выключенный вне
этапа плана.
Профиль.
- Матрица:
- размеры истории читаемого чата 10 000 / 100 000 / 500 000 (не 1M, как на лабе 1: прогон ~30 мин вместо ~45, а ×50 по длине истории достаточно, чтобы увидеть рост);
- 1 / 10 / 50 клиентов;
- сценарии
read(страницаlimit=50со случайным курсором) иwrite(сообщение в соседний чат); - по 3 повтора с прогревом.
- На каждый размер:
- свежий стенд и миграции;
- наполнение через HTTP API порциями по 25 000;
VACUUM (ANALYZE)иCHECKPOINT;EXPLAIN (ANALYZE, BUFFERS)запроса страницы, которую выполнило приложение: первая, средняя и последняя страница, плюс средняя без индекса в откатываемой транзакции.
- Вход в сценариях — как в контракте: регистрация с паролем, Basic, затем Bearer.
Гипотезы. Записаны до полной матрицы, по самопроверке make bench_quick (1k–10k, от батареи). Там API на 4–16 клиентах занимал
1,0 ядра, Postgres — 0,15–0,25, а средняя страница читала около 54
буферов на любом размере. Опровержение — при условии в последнем
столбце.
| Гипотеза | Опровергнута, если | |
|---|---|---|
| H1 | Время страницы истории не зависит от длины истории: keyset по индексу (chat_id, created_at, id) читает ограниченное число страниц, а не всю историю до курсора |
p50 read на 500k больше, чем на 10k, более чем на 20% при той же конкуренции, или буферы средней и последней страницы в плане приложения на 500k больше, чем на 10k, более чем вдвое |
| H2 | Без индекса тот же запрос — Seq Scan всей таблицы и сортировка: буферы — порядка числа страниц таблицы, время растёт примерно пропорционально N |
план без индекса читает ограниченное число страниц или его время на 500k меньше чем в 10 раз больше, чем на 10k (при пропорциональном росте — ×50) |
| H3 | На 10 и 50 клиентах read и write упираются в CPU API (1 ядро), а не в Postgres |
app_cpu_cores меньше 0,9 при db_cpu_cores больше 2 в этих ячейках |
| H4 | Стоимость записи растёт с размером индекса слабо (глубина B-дерева — логарифм N) | RPS последней порции наполнения 500k меньше 80% RPS первой порции |
Результаты. Метка evidence/bench/baseline/, commit e61a0e5,
2026-10-02, 26,5 минуты:
- хост в начале и в конце прогона — от сети, swap 0, свободно 77–78% памяти;
- посторонних контейнеров нет;
- 54 прогона без пометок и ошибок.
Значения — медиана (min–max) трёх повторов из summary.md.
| Размер | Клиенты | read: RPS | read: p50 / p99, мс | write: RPS | write: p50 / p99, мс | CPU API / БД, ядер (read; write) |
|---|---|---|---|---|---|---|
| 10k | 1 | 617 (617–624) | 1,49 / 2,34 | 748 (736–753) | 1,26 / 1,90 | 0,83 / 0,13; 0,78 / 0,13 |
| 10k | 10 | 777 (772–779) | 12,20 / 31,23 | 999 (989–1000) | 9,79 / 19,39 | 1,00 / 0,17; 1,00 / 0,20 |
| 10k | 50 | 742 (742–744) | 63,56 / 175,80 | 903 (896–909) | 53,38 / 109,98 | 1,00 / 0,17; 1,00 / 0,21 |
| 100k | 1 | 581 (574–584) | 1,62 / 2,40 | 752 (738–763) | 1,25 / 1,85 | 0,83 / 0,13; 0,78 / 0,13 |
| 100k | 10 | 755 (754–759) | 12,47 / 31,20 | 1003 (1002–1006) | 9,65 / 19,71 | 1,00 / 0,17; 1,00 / 0,20 |
| 100k | 50 | 726 (722–730) | 65,11 / 170,76 | 922 (922–926) | 51,66 / 114,36 | 1,00 / 0,17; 1,00 / 0,21 |
| 500k | 1 | 608 (605–611) | 1,55 / 2,32 | 738 (736–744) | 1,26 / 2,17 | 0,83 / 0,13; 0,78 / 0,13 |
| 500k | 10 | 770 (768–770) | 12,44 / 30,25 | 1014 (1005–1015) | 9,66 / 19,75 | 1,00 / 0,18; 1,00 / 0,20 |
| 500k | 50 | 737 (734–741) | 64,15 / 170,35 | 911 (907–924) | 52,72 / 111,86 | 1,00 / 0,18; 1,00 / 0,21 |
| Размер | Таблица messages, МиБ |
Индексы, МиБ | Байт в БД на сообщение | Наполнение, сообщ/с (32 клиента) |
|---|---|---|---|---|
| 10k | 1,6 | 1,0 | 274 | 908 |
| 100k | 15,1 | 9,9 | 263 | 926 |
| 500k | 75,4 | 46,8 | 256 | 926 (порции 902–940) |
Итог по гипотезам:
| Итог | Числа | |
|---|---|---|
| H1 | подтверждена | p50 чтения на 500k против 10k: 1,49 → 1,55 мс (+4%) при 1 клиенте, 12,20 → 12,44 (+2%) при 10, 63,56 → 64,15 (+1%) при 50; порог +20%. Буферы средней и последней страницы — 47 и 55 против 54 и 54 (раздел «Индекс истории») |
| H2 | подтверждена | без индекса 209 → 9 678 буферов (×46 при данных ×50), 0,848 → 20,124 мс (×24, порог ×10); Seq Scan, с 100k — параллельный |
| H3 | подтверждена | с 10 клиентов API занимает 1,00 ядра в каждой ячейке, Postgres — 0,17–0,21 из 4 |
| H4 | подтверждена | 20 порций наполнения 500k — 902–940 сообщ/с без тренда: первая 919, последняя 931; p95 — 51–55 мс |
Что ещё видно:
- Пропускную способность ограничивает процесс API, а не база. С 10 клиентов RPS больше не растёт, растёт очередь: p50 при 50 клиентах — 64 мс, близко к 50 / RPS = 67 мс. Запрос в Postgres занимает около 0,05 мс из ~1,3 мс CPU API на чтение. Поэтому разницу индексов в треке 2 сравнивать по планам, буферам и стоимости записи в БД, а не только по RPS этого стенда.
- Различие между запусками стенда — около 5%. Чтение одним клиентом
на 100k (581 RPS) медленнее, чем на 10k и 500k (617 и 608). Порядок
не монотонен по N, значит, это разброс между запусками стенда (каждый
размер — свежий стенд), а не длина истории. A/A-метки, которая
оценила бы этот шум, у
baselineнет. - Метрика лабы 1 «байт RSS на сообщение» (431 / 63 / 11) на лабе 2 смысла не имеет: API данных не хранит, его RSS растёт на постоянные ~5 МБ. Объём на сообщение — байты в БД: 256–274.
Ограничения замера:
- Один чат со всей историей: селективность
chat_idоколо 100%. Чаты разного размера — в треке 2, часть 1: план индекса приложения тот же. - Настройки Postgres — по умолчанию образа (
shared_buffers128 МБ). Таблица с индексами на 500k (122 МБ) целиком в памяти, чтения с диска не измерялись. - Все планы приложения в этой метке — custom: параметры подставлены в
условия. Generic plan проверен в треке 2, часть 1: на 10k и 100k с
чатами разного размера приложение получило его само, и это тот же
Index Scanс теми же буферами. - Docker Desktop на ноутбуке (macOS, Apple M3 Pro): числа сравнимы только между метками этой методики, а не с другими машинами.
Трек 2, часть 1: индексы и запросы истории на чатах разного размера
Зачем: трек «5» №2 — ≥100 000 сообщений с неравномерными размерами
чатов, сравнение ≥2 индексов или запросов и стоимости записи. Команда
— make bench BENCH_LABEL=track2. Методика — design change
track2-query-plans и .claude/rules/bench.md. Стенд, лимиты и
матрица — как у baseline, плюс фоновые чаты. Поэтому track2 и
baseline — разные методики, и make bench_compare их не сравнивает.
Набор данных. На каждом размере, кроме читаемого чата (10 000 / 100 000 / 500 000) и чата записи, есть 1 110 фоновых чатов: 10 × 5 000, 100 × 400 и 1 000 × 10. Это 100 000 сообщений, а всего в таблице 110 000 / 200 000 / 600 000. Все сообщения отправляются через HTTP API вперемешку, по детерминированному расписанию: сообщения каждого чата равномерно распределены по наполнению. После наполнения распределение по чатам проверяется.
Что сравниваем. Страница истории limit=50 — тот же запрос и те же
параметры, что выполнило приложение. Для читаемого чата и первого чата
каждого уровня страница из середины, у чата из 10 сообщений — первая.
Варианты в psql, в транзакции, которая откатывается:
| Вариант | Что это |
|---|---|
app / psql |
индекс приложения (chat_id, created_at, id), сравнение кортежей (created_at, id) > (…); app — план самого приложения из auto_explain |
generic |
то же с plan_cache_mode = force_generic_plan |
or-cursor |
условие курсора через created_at > … OR (created_at = … AND id > …) |
chat_only |
индекс (chat_id) вместо индекса приложения |
covering |
индекс (chat_id, created_at, id) INCLUDE (sender_id, text) вместо индекса приложения |
no-index |
без индекса истории |
Стоимость записи — для app, chat_only, covering и none (без
индекса истории), в конце каждого размера:
- индекс строится заново;
- 20 000 сообщений вставляются во все чаты в пропорции наполнения, в транзакции, которая откатывается;
- после
CHECKPOINTснимаетсяEXPLAIN (ANALYZE, WAL); - три повтора со сдвигом порядка вариантов;
- отдельно проверяется, вставляется ли сообщение из 4000 символов, максимум контракта.
Гипотезы. Записаны 2026-10-02 до полной матрицы, на commit
d2656ab. Основа — проба на Postgres 18.6 и make bench_quick (1k–10k
и 3 500 фоновых сообщений). В пробе:
covering— 160 байт индекса на сообщение против 60 у индекса приложения;- WAL на вставку у
coveringв 1,4 раза больше; - сообщение из 4000 символов при
coveringне вставляется; or-cursorна середине чата из 10 000 читает 5 010 буферов против 53;- план приложения для страниц с курсором — уже generic.
Опровержение — при условии в последнем столбце.
| Гипотеза | Опровергнута, если | |
|---|---|---|
| P1 | Индекс приложения со сравнением кортежей: страница любого чата на любой глубине стоит ограниченно — до ~60 буферов и меньше 0,2 мс, независимо от размера чата и таблицы | план приложения хоть одной страницы читает больше 100 буферов, или буферы средней и последней страницы читаемого чата на 500k больше, чем на 10k, более чем вдвое |
| P2 | chat_only: маленькие чаты (10 и 400) стоят как с индексом приложения (сортировка ≤400 строк), а огромный читаемый чат читается и сортируется целиком |
на середине читаемого чата 500k буферов меньше чем в 20 раз больше, чем у psql, или время от 10k к 500k растёт меньше чем в 10 раз |
| P3 | or-cursor: индекс приложения используется только по chat_id, условие курсора становится фильтром, и буферы растут с числом сообщений до курсора |
на середине читаемого чата 500k буферов меньше чем в 100 раз больше, чем у psql |
| P4 | covering: Index Only Scan без чтения кучи, буферов на странице сравнения в ≥5 раз меньше; но индекс в ≥2 раза больше, WAL на сообщение в ≥1,3 раза больше, и сообщение из 4000 символов не вставляется |
узел не Index Only Scan, или буферов больше 1/5 от psql на странице с курсором, или сообщение из 4000 символов вставляется |
| P5 | Приложение после прогрева получает generic plan, и это тот же Index Scan по индексу приложения на всех уровнях: неравномерность чатов план не портит |
на каком-то уровне у generic другой узел или буферов больше чем в 1,5 раза больше, чем у psql |
| P6 | Стоимость записи (WAL и время на сообщение) растёт в порядке none < chat_only < app < covering; разница между вариантами — единицы микросекунд на сообщение, меньше 1% от ~1,3 мс CPU API на HTTP-запись |
порядок медиан нарушен, или covering дороже app больше чем на 13 мкс на сообщение (1% от 1,3 мс) |
Правило выбора записано вместе с гипотезами. Вариант индекса заменяет индекс приложения, только если выполнены все три условия:
- сообщение из 4000 символов вставляется;
- буферы страницы сравнения на каждом уровне не больше половины от
psql; - время вставки и WAL на сообщение не больше ×1,5 от
app.
Форма запроса меняется, только если or-cursor читает меньше буферов на
всех уровнях. Иначе приложение не меняется.
Результаты. Метка evidence/bench/track2/: commit 67be41e (код
стенда d2656ab и гипотезы), 2026-10-02, 32 минуты.
- Хост в начале и в конце — от сети, swap 0, свободно 76% и 67% памяти; посторонних контейнеров нет.
- 54 прогона без пометок и ошибок.
- Распределение по чатам совпало на всех размерах: 1 111 чатов от 10 до N сообщений.
Планы страниц сравнения. Ячейка — буферы shared hit верхнего узла /
время, мс; чтений с диска нет. Узел — индекс приложения (Index Scan),
если не сказано иначе. Файлы — explain-{10k,100k,500k}.txt, сводка —
раздел «Планы запроса истории» в summary.md.
| Таблица | Чат, страница (после скольких) | psql |
generic |
or-cursor |
chat_only |
covering |
no-index |
|---|---|---|---|---|---|---|---|
| 600 000 | 500 000, средняя (250 000) | 49 / 0,023 | 49 / 0,029 | 252 338 / 44,023 | Parallel Seq Scan 11 590 / 18,405 |
Index Only Scan 5 / 0,020 |
Parallel Seq Scan 11 590 / 20,463 |
| 5 000, средняя (2 500) | 52 / 0,024 | 52 / 0,038 | 2 441 / 0,557 | 4 176 / 1,328 | Index Only Scan 5 / 0,013 |
Parallel Seq Scan 11 590 / 11,077 |
|
| 400, средняя (200) | 55 / 0,030 | 55 / 0,030 | Bitmap Heap Scan 208 / 0,135 |
403 / 0,129 | Index Only Scan 5 / 0,020 |
Parallel Seq Scan 11 560 / 10,731 |
|
| 10, первая | 13 / 0,011 | 13 / 0,012 | — | 13 / 0,013 | Index Only Scan 5 / 0,006 |
Parallel Seq Scan 11 650 / 9,996 |
|
| 110 000 | 10 000, средняя (5 000) | 53 / 0,027 | 53 / 0,026 | 4 979 / 0,847 | Bitmap Heap Scan 2 036 / 2,017 |
Index Only Scan 5 / 0,016 |
Seq Scan 2 129 / 4,023 |
| 5 000, средняя (2 500) | 51 / 0,025 | 51 / 0,027 | 2 427 / 0,359 | Bitmap Heap Scan 1 876 / 1,092 |
Index Only Scan 5 / 0,017 |
Seq Scan 2 129 / 3,167 |
|
| 400, средняя (200) | 51 / 0,021 | 51 / 0,024 | 249 / 0,065 | Bitmap Heap Scan 378 / 0,151 |
Index Only Scan 5 / 0,015 |
Seq Scan 2 129 / 2,835 |
|
| 10, первая | Bitmap Heap Scan 13 / 0,022 |
13 / 0,009 | — | Bitmap Heap Scan 12 / 0,020 |
Index Only Scan 4 / 0,011 |
Seq Scan 2 129 / 2,526 |
Планы самого приложения (auto_explain), все 30 страниц на трёх
размерах:
Index Scanпо индексу приложения, кроме первой страницы чата из 10 на 10k (Bitmap Heap Scan);- 5–55 буферов и 0,029–0,149 мс.
Страницы с курсором на 10k и 100k приложение выполнило generic-планом, на 500k — custom. Выбор зависит от истории выполнений на соединении пула, а узел и буферы в обоих случаях те же.
Стоимость записи — медиана трёх повторов, вставка 20 000 сообщений
(раздел «Стоимость записи по вариантам индекса» в summary.md):
| Вариант | Индекс, байт на сообщение | мкс на сообщение (10k / 100k / 500k) | WAL байт на сообщение (10k / 100k / 500k) | Сообщение из 4000 символов |
|---|---|---|---|---|
none |
0 | 5,09 / 4,93 / 5,28 | 495 / 621 / 1 185 | вставляется |
chat_only |
7,4 / 7,3 / 7,2 | 5,46 / 5,55 / 5,93 | 601 / 720 / 1 284 | вставляется |
app |
59,1 / 59,0 / 58,9 | 5,90 / 6,03 / 6,48 | 740 / 865 / 1 375 | вставляется |
covering |
158,7 / 158,7 / 158,6 | 6,46 / 6,37 / 6,79 | 991 / 1 080 / 1 604 | не вставляется: index row requires 12072 bytes, maximum size is 8191 |
На 500k индекс covering занимает 98,2 МиБ — больше самой таблицы
(90,4 МиБ). Индекс приложения — 36,5 МиБ, chat_only — 4,4 МиБ.
WAL на сообщение растёт с таблицей у всех вариантов. После CHECKPOINT
каждая впервые изменённая страница пишет полный образ (FPI):
- у
app— 65 FPI на 1 000 сообщений на 10k и 180 на 500k; - добавка
coveringкappв абсолютных числах почти постоянна: +251 / +215 / +229 байт.
HTTP-матрица (summary.md, сценарии read и write):
read595–620 RPS при одном клиенте и 757–789 при 10;write998–1 056 RPS при 10 клиентах;- API занимает 1,00 ядра с 10 клиентов, Postgres — 0,12–0,23;
- наполнение — 934–959 сообщений в секунду без тренда до 600 000.
Это тот же порядок, что у baseline. Сравнивать их таблицей нельзя:
методика другая, make bench_compare откажет по profile.background.
Итог по гипотезам:
| Итог | Числа | |
|---|---|---|
| P1 | подтверждена | планы приложения — 5–55 буферов и до 0,149 мс на всех уровнях и размерах; середина и конец чата 500k — 49 и 54 буфера против 53 и 53 на 10k |
| P2 | опровергнута | середина чата 500k — 11 590 буферов против 49 (×237, порог ×20), но время от 10k к 500k выросло в 9,1 раза (2,017 → 18,405 мс) при пороге ×10. Причина: chat_only читает все сообщения чата, а они перемешаны с другими чатами и лежат почти каждое на своей странице. Поэтому стоимость близка к числу страниц с сообщениями чата: чат из 5 000 на 500k — 4 176 буферов, а чат из 10 000 на 10k читает почти всю таблицу (2 036 буферов при 2 129 страницах таблицы). Неверна и первая часть: чат из 400 читает 378–403 буфера против 51–55 у индекса приложения, так же дёшево только чат из 10 |
| P3 | подтверждена | середина чата 500k — 252 338 буферов и 44 мс против 49 и 0,023 мс (×5 150, порог ×100). Это хуже полного скана (11 590 буферов): Postgres идёт по индексу чата с начала и отбрасывает фильтром все 250 000 сообщений до курсора. На маленьких чатах вреда почти нет (400: 208–253 буфера) |
| P4 | подтверждена по условию опровержения, часть про WAL — только на 10k | Index Only Scan, 4–5 буферов против 13–55 (в 10 раз меньше на страницах с курсором); индекс в 2,7 раза больше (158,6 против 58,9 байт на сообщение); сообщение из 4000 символов не вставляется. WAL — ×1,34 на 10k, но ×1,25 на 100k и ×1,17 на 500k: при росте таблицы FPI становится больше, и добавка покрывающего индекса в доле меньше |
| P5 | формально опровергнута в одной точке | у generic везде Index Scan по индексу приложения и те же буферы, что у psql. Но на 10k у чата из 10 custom-план — Bitmap Heap Scan, а generic — Index Scan при тех же 13 буферах (generic даже быстрее: 0,009 против 0,022 мс). Неравномерные чаты generic-план не портят. Часть «приложение после прогрева получает generic» верна на 10k и 100k, на 500k приложение осталось на custom |
| P6 | подтверждена | на каждом размере медианы времени и WAL идут по порядку none < chat_only < app < covering; covering дороже app на 0,31–0,56 мкс на сообщение (порог 13 мкс) |
Решение по правилу выбора — индекс и запрос приложения не меняются.
coveringне проходит условие 1: контракт разрешает текст до 4000 символов, а такой несжимаемый текст в строку индекса не влезает, иPOSTсообщения получил бы 500. Выигрыш — около 0,01 мс БД на страницу, меньше 1% от ~1,3 мс CPU API на запрос, а платить пришлось бы +100 байт индекса на сообщение и +17–34% WAL.chat_onlyне проходит условие 2: на всех уровнях, кроме чата из 10, буферов в 7–237 раз больше.or-cursorдороже на всех страницах с курсором, на большом чате — на три порядка.
Что ещё видно:
- Индекс приложения читает примерно одну страницу таблицы на строку
страницы (47–55 буферов на 51 строку) на любом уровне. Сообщения
чата лежат на разных страницах кучи: их вставляли вперемешку с
сообщениями других чатов. В
baseline, с одним чатом, было так же: там сообщения перемешивали 32 клиента наполнения. Прогон с одним клиентом наполнения, который проверил бы это напрямую, не делался. - Форма запроса важнее выбора между близкими индексами. Условие
через
ORдаёт верный результат, но превращает keyset-пагинацию в скан всего, что до курсора. Сравнение кортежей — не стилистика, а граница диапазона для индекса.
Ограничения:
- Вся таблица и индексы в памяти (
read= 0, кроме одной страницы). При холодном кэше выигрышcoveringпо вводу-выводу был бы больше: 5 случайных чтений против ~50. Не измерялось. - Стоимость записи по вариантам — одна вставка
INSERT … SELECTв транзакции, безfsyncкоммита на каждое сообщение. HTTP-запись меряет сценарийwrite, и только для индекса приложения. - Варианты в psql — custom-планы с литералами, а приложение выполняет
prepared statement. Generic-план проверен через
force_generic_plan; какой план выберетautoна другой истории выполнений, зависит от соединения. - Данные синтетические: три уровня размеров, равномерное перемешивание,
тексты по 64 символа. Длинные реальные тексты увеличили бы
coveringещё сильнее. - В планах варианты индекса построены заново и компактны, а индекс приложения — живой, после наполнения. Это сравнение в пользу вариантов. В пробах записи индекс приложения тоже строится заново, там условия равные.
- Один прогон без A/A. Варианты сравниваются на одних данных в одном состоянии стенда, а буферы детерминированы. Шум между прогонами влияет только на время.
Ограничения и следующие шаги
- Сервер, замёрзший при открытом соединении, держит запрос 8 с, а не 6: 2 с уходят на ограниченное закрытие соединения.
- Время сообщений ставит процесс API: порядок истории зависит от часов хоста; конкурентные вставки могут быть пропущены текущим обходом (раздел «Пагинация»).
- Срок запроса может истечь на самом
commit. Тогда сервер мог уже зафиксировать запись, а клиент получит 503: это не частичная запись, но исход для клиента неизвестен, и повтор создаст дубль. Безопасный повтор появится сIdempotency-Keyв лабе 3. - Один Docker-host: потерю хоста стенд не переживает, Postgres без реплик.
- Прогоны
make student_testиmake testпротив рабочего стенда оставляют данные в рабочей базе; обычный прогон —make test_isolated. - Истёкшие сессии остаются в таблице: их не читает ни один запрос, рост — одна строка на вход. Чистка — фоновая задача с лабы 5.
- Вход ограничен лимитом KDF (4 хэша одновременно), но частота входа не ограничена (429 не реализован). Очередь из сотен входов дольше 6 с дала бы 503 с записью «Database is unavailable», хотя БД в порядке.
- Защита от перебора имён по времени касается только входа: регистрация
по контракту отвечает 409 на занятый
username. - Swagger UI кодирует Basic через
btoa: войти из/docsможно только с паролем из ASCII. API принимает любой UTF-8, это проверяют тесты. - Кэш держится на неизменяемости карточки чата. Если контракт позволит
менять участников или удалять чаты, понадобится удаление ключа в той
же операции. Правка базы в обход API (восстановление из backup)
требует
FLUSHALL. - После отказа Valkey кэш пропускается 5 с, даже если Valkey вернулся
раньше: запросы этого окна идут в Postgres. Срок — настройка
[cache] retry_after_seconds. - Valkey один, без реплик: его потеря не теряет данных, но снимает разгрузку Postgres до возврата.
- Проверки отказов идут только через
make failure_checks(~45 с, свой стенд), а не в каждомmake student_test. Два прогона одновременно не поддерживаются: второй удаляет стенд первого. Границы времени в них — с запасом 0,3–0,5 с; на сильно загруженном хосте возможны ложные падения, в выводе — фактические длительности. - Откат создания чата проверен сбоем, вызванным триггером на стенде отказов, а не настоящей ошибкой БД: проверяется свойство транзакции, а не причина сбоя.
- Пропускную способность стенда ограничивает CPU единственного процесса API (на стенде замеров — 1 ядро), Postgres загружен на 0,2 ядра. Это ожидаемо для одного worker; масштабирование репликами — лаба 3.
- Планы и нагрузка сняты с настройками Postgres по умолчанию, вся таблица в памяти: выигрыш покрывающего индекса при холодном кэше не измерялся (раздел «Трек 2, часть 1», ограничения).
- Не реализовано: трек 2, часть 2 — backup с восстановлением (change
track2-backup-restore).
Источники, библиотеки и использование ИИ
- Документация: PostgreSQL 18 (транзакции,
statement_timeout,pg_isready), SQLAlchemy 2.1 (asyncio, пул, обработка разрывов), alembic (async-шаблонenv.py), asyncpg (параметры подключения,connection_class), Docker Compose (depends_on,--wait, сети). - Документация по аутентификации: RFC 7617 (Basic), RFC 9106 (Argon2) и
argon2-cffi (профили параметров), anyio (
to_thread.run_sync,CapacityLimiter), FastAPI security (HTTPBase,HTTPBearer). - Документация по кэшу: Valkey (persistence,
maxmemory-policy,requirepass, образvalkey/valkeyи егоdocker-entrypoint.sh), redis-py (redis.asyncio,Retry,BlockingConnectionPool), PostgreSQL (pg_stat_user_tables, задержка статистики). - Документация по планам и записи: PostgreSQL 18 (
EXPLAINсBUFFERSиWAL,auto_explain,plan_cache_mode, индексы сINCLUDEиIndex Only Scan, предел размера строки B-дерева, сравнение кортежей в условиях), k6 (SharedArray,shared-iterations). - Библиотеки: FastAPI, pydantic, pydantic-settings, structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn; в тестах — pytest и httpx; в нагрузочном стенде — k6.
- ИИ: Claude (Claude Code) помогал проектировать changes
postgres-storage,session-auth,membership-cache,failure-checks,bench-postgresиtrack2-query-plans(OpenSpec), писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки просмотрены автором; поведение подтверждено командами, выводы которых лежат вevidence/.