Files
mtusi2026lab2/REPORT.md
T
2026-10-02 05:18:06 +03:00

95 KiB
Raw Blame History

Отчёт — лабораторная 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 — удалить контейнеры, volume postgres_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. Разбор свой: FastAPI HTTPBasic декодирует 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 (change track2-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 мс в медиане): таблица маленькая. Замер под нагрузкой — change bench-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_buffers 128 МБ). Таблица с индексами на 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 мс)

Правило выбора записано вместе с гипотезами. Вариант индекса заменяет индекс приложения, только если выполнены все три условия:

  1. сообщение из 4000 символов вставляется;
  2. буферы страницы сравнения на каждом уровне не больше половины от psql;
  3. время вставки и 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):

  • read 595–620 RPS при одном клиенте и 757–789 при 10;
  • write 998–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. Варианты сравниваются на одних данных в одном состоянии стенда, а буферы детерминированы. Шум между прогонами влияет только на время.

Трек 2, часть 2: backup, восстановление в новое хранилище и сверка

Зачем: вторая половина трека «5» №2 — backup → восстановление в новое хранилище → сверка количества и выбранных сообщений, время восстановления и границы потери данных. Команда — make bench_restore (метка restore), самопроверка и сценарий защиты — make bench_restore_quick (~1,5 мин). Методика — design change track2-backup-restore.

Данные и стенд — как в части 1: 110 000 / 200 000 / 600 000 сообщений в 1 111 чатах, те же образы и лимиты. Матрицы прогонов нет.

Процедура на каждом размере:

  1. Запоминаются id и поля всех сообщений и число строк каждой таблицы.
  2. Через HTTP идёт запись 5 000 сообщений, 10 клиентов. Когда число сообщений начало расти, снимается pg_dump -Fc: логический backup, один снимок на старте.
  3. После backup через HTTP: новый пользователь входит (новая сессия), создаёт чат с читателем и пишет в него сообщение. Карточка чата попадает в Valkey.
  4. Новое хранилище: контейнер PostgreSQL того же образа и с теми же лимитами на новом volume, pg_restore -j 4, затем ANALYZE.
  5. Сверка баз:
    • число строк users, chats, chat_members, sessions;
    • md5 всех полей каждого восстановленного сообщения против исходного;
    • все сообщения, бывшие до backup, восстановлены;
    • потерянные — только из чата записи и чата «после backup»;
    • индексы и ревизия схемы совпадают.
  6. API переключается на восстановленную базу. Через HTTP:
    • 30 страниц истории разных чатов совпадают с исходными поэлементно;
    • прежняя сессия действует;
    • сессия «после backup» — 401;
    • ответы на чат «после backup» записываются.
  7. FLUSHALL Valkey. Чат «после backup» — 404, страницы те же.

Любое расхождение в шагах 5–7 — ошибка команды. RTO — время от запуска нового хранилища до готовности API, без сверки.

Гипотезы. Записаны 2026-10-02 до make bench_restore, на commit 8bc4272. Основа — проба (600 000 строк: dump 0,95 с, pg_restore -j 4 1,15 с) и make bench_restore_quick: 4 500–14 500 сообщений, backup 37–41 байт на сообщение, RTO около 3 с, из них 2 с — пересоздание API.

Гипотеза Опровергнута, если
R1 Логический backup не мешает записи: нагрузка во время pg_dump проходит без ошибок хоть один запрос нагрузки неуспешен
R2 Всё, что закоммичено до начала backup, восстанавливается без изменений; теряются только сообщения, закоммиченные после снимка, и активность после backup сверка шага 5 или страницы шага 6 расходятся (команда завершилась бы ошибкой)
R3 Время восстановления базы растёт не быстрее данных, а RTO на 600 000 сообщений меньше 30 с RTO на 500k ≥ 30 с, или время БД (хранилище + копия + pg_restore + ANALYZE) на 600 000 больше чем в 10 раз выше, чем на 110 000 (данных ×5,5)
R4 Backup в формате custom (сжатый, без индексов) — меньше трети от байт в БД на сообщение (~300 в части 1) больше 100 байт на сообщение
R5 Без FLUSHALL чат, созданный после backup, отдаётся из кэша (200), а запись в него — 500; после FLUSHALL — 404 до FLUSHALL не 200 (вред не показан) или после — не 404

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

  • Сервер, замёрзший при открытом соединении, держит запрос 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/.