Files
mtusi2026lab2/REPORT.md
T
kokorindenis c4ffc8dcf3
Skeleton contracts / contracts (pull_request) Canceled after 0s
fix comments
2026-10-23 22:32:15 +03:00

50 KiB
Raw Blame History

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

  • Автор, группа: Кокорин Денис, БВТ2301
  • Целевая оценка: 4 — уровень 3 целиком и все пункты уровня 4; трек 5 не заявляем
  • Commit/PR: решение лежит в ветке solution/bvt2301-kokorin; коммиты делает автор, поэтому ссылки на PR здесь нет
  • Использованные источники, библиотеки и помощь ИИ: см. раздел «Источники и ИИ»

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

Версии и предпосылки

Компонент Версия Примечание
Python 3.11.9 локально и в образе
Docker Engine 28.0.1 Docker Desktop, Windows 10 Pro 19045, AMD64
Docker Compose 2.33.1-desktop.1
Базовый образ python:3.11.9-slim-bookworm digest sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317, тот же в builder и runtime
PostgreSQL postgres:16.15-bookworm digest sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4
Valkey valkey/valkey:8.0.11-trixie digest sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab
Образ приложения mtusi-messenger-lab2:2.0.0 сборка с нуля 1 м 35 с, 74 408 022 байта (~71 МиБ)

Все 24 зависимости закреплены точными версиями в requirements.txt — это полное замыкание pip freeze на Python 3.11.9, включая транзитивные.

Обязательных действий оператора два: скопировать .env.example в .env (там только несекретные значения) и создать локальные секреты — make secrets, он же sh scripts/bootstrap-secrets.sh. Первый запуск занимает минуты из-за сборки образа, последующие — секунды.

git clone <URL своего fork> && cd mtusi2026lab2
git checkout solution/bvt2301-kokorin

cp .env.example .env                # порт и TTL; секретов здесь нет
make secrets                        # то же, что sh scripts/bootstrap-secrets.sh: режим 600,
                                    # повторный запуск существующие файлы не перезаписывает

docker compose --env-file .env config --quiet    # конфигурация валидна (пустой вывод)
docker compose --env-file .env up -d --build     # migrate → api, публикация 127.0.0.1:8080

# готовность: обычно 1–2 с после старта api
curl -s http://127.0.0.1:8080/health/ready        # {"status":"ok"}

# в другом терминале
make check
python3 -m venv .venv && .venv/Scripts/python.exe -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/Scripts/python.exe
make test BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.cmd BASE_URL=http://127.0.0.1:8080
make student-test BASE_URL=http://127.0.0.1:8080 PYTHON="python3 -X utf8"

Инструкция проверена целиком на копии репозитория без игнорируемых Git файлов: сборка --no-cache 1 м 35 с в первом прогоне и 2 м 49 с в повторном, up -d 8–19 с, готовность через 1 с, make check и make validate — PASS, make test — PASS, make test-persistence — PASS, make student-test — 82 теста OK за 30.9 с. Транскрипт — evidence/12-clean-clone.txt (первый прогон и повторный на итоговом дереве).

Три оговорки для Windows, все проверены на практике:

  • Хук перезапуска вызывается тестом через Popen([script]) без оболочки, а Windows исполняет так только .exe/.cmd/.bat: .sh падает с WinError 193. Поэтому в комплекте есть scripts/restart.cmd — двойник POSIX-версии с тем же поведением; оба запускаются в доказательстве 02.
  • make в этом окружении (MSYS/Git Bash) не передаёт рецептам переменные окружения — работают только переопределения в командной строке, отсюда PYTHON="python3 -X utf8".
  • Адрес стенда в примерах — 127.0.0.1, а не localhost: на Windows localhost сначала разрешается в ::1, и каждый запрос платит около 2 с за откат на IPv4 (это измерение есть и в отчёте по лабораторной 1). Публичные тесты по умолчанию ходят на localhost — это их право, время в них не измеряется.

Безопасная остановка и удаление учебных данных

docker compose stop          # остановить, сохранив тома: данные на месте
docker compose start         # вернуть стенд
docker compose down          # убрать контейнеры и сеть; тома pgdata и valkeydata остаются
docker compose down -v       # намеренно удалить учебные данные вместе с томами

Порядок именно такой, и -v стоит последним, потому что после него данные не вернуть. Хуки перезапуска в репозитории удаление не делают вовсе: scripts/restart.sh и его .cmd-двойник вызывают только docker compose restart --timeout 10 api postgres valkey и проверяют, что все три сервиса снова running (доказательство 02).

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

Схема

Клиент (curl, tests/smoke.py, tests/load.py, student-tests)
  │  HTTP/1.1 + JSON; Basic — только на POST /api/v1/auth/sessions, дальше Bearer
  ▼
RequestContextMiddleware — X-Request-Id и access-лог
  ▼
FastAPI + Pydantic — валидация на границе, зависимости, единый конверт ошибок
  ▼
repository (SQL, только bind-параметры)         sessions (SessionStore)
  ▼                                               ▼
PostgreSQL — источник истины                  Valkey — только сессии
users, chats, chat_members, messages          messenger:session:<sha256(token)>, TTL

Модули: domain (сущности и правила) ← repository, sessions, security; access и deps связывают их с routers; сборка — в app, конфигурация — в config, схема — в schema, миграции — в migrations/. Транспорт не знает ни об SQL, ни о ключах Valkey: замена хранилища не трогает обработчики, а замена формата ответа не трогает запросы.

Сопоставление ролей из contracts/infrastructure.json с фактическими сервисами, версиями, digest'ами, healthcheck'ами, томами, сетями и способом передачи credentials (как требует infra/README.md) — в evidence/10-infra-mapping.txt.

Таблицы, ограничения, индексы

Таблица Ключи и ограничения
users id uuid pk, uq_users_username (уникальный индекс), ck_users_username_format, ck_users_display_name_length, created_at timestamptz
chats id uuid pk, ck_chats_title_length, created_at
chat_members pk(chat_id, user_id), FK на chats с on delete cascade, FK на users с on delete restrict
messages id uuid pk, FK на chats, FK на users, ck_messages_text_length, created_at

Индексов ровно три, и каждый появился под конкретный запрос, а не «на всякий случай»:

  • ix_messages_chat_id_created_at_id (chat_id, created_at, id) — равенство по чату, порядок истории и позиция keyset-курсора (обоснование — доказательство 07).
  • ix_chat_members_user_id_chat_id (user_id, chat_id) — «мои чаты» (доказательство 08).
  • uq_users_username (username) — уникальность имени, она же закрывает гонку регистрации.

Время назначает база (now() + RETURNING), а не процесс: часы приложения и часы БД разъезжаются, и порядок истории должен зависеть от одного источника. Ничья по created_at разрешается id — контракт этого и требует, а публичный smoke сравнивает выдачу с сортировкой по (created_at, id).

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

  • Регистрация — предпроверка SELECT (избавляет от argon2 на заведомо занятом имени) плюс один оператор INSERT ... ON CONFLICT (username) DO NOTHING RETURNING id. Пустой RETURNING означает, что имя занято: 409 без аборченной транзакции. Гонку закрывает уникальный индекс, а не предварительная проверка, которая между SELECT и INSERT ничего не гарантирует: при одновременной регистрации проигравший зря хэширует пароль, но теряет только время. Проверка: 12 одновременных регистраций одного имени дают ровно один 201.
  • Создание чата — одна транзакция: INSERT chats RETURNING плюс INSERT chat_members по всем участникам. Неизвестный участник даёт ошибку внешнего ключа 23503, транзакция откатывается целиком, клиент получает 400, и чата не остаётся. Именно это и есть проверяемый откат составной операции.
  • Между страницами истории нет snapshot-изоляции: каждый запрос — своя транзакция. Строка, вставленная во время обхода, может появиться на следующей странице, если её ключ больше курсора, и не появиться, если меньше. Уже отданные строки не дублируются — это свойство keyset-позиции. Транзакция, начатая до чтения страницы, но зафиксированная после, теоретически может добавить строку «позади» курсора: тогда её не увидит этот обход. Для мессенджера это приемлемо (история не перечитывается ради точности), но это ограничение, а не гарантия.

Источник истины, сессии, expiry и инвалидация

Источник истины ровно один — PostgreSQL: пользователи, чаты, членство, сообщения. Valkey хранит только сессии. Разделение выбрано так, чтобы у каждого хранилища была одна роль: если Valkey потеряет всё, никто не потеряет данные, но все разлогинятся; если бы сессии лежали ещё и в PostgreSQL, появилось бы два источника истины и вопрос «чья запись главнее», который в лабораторной негде проверить.

  • Ключ — messenger:session:<sha256(token)>. Сам токен (256 бит из secrets.token_urlsafe) в хранилище не попадает, поэтому дамп Valkey, MONITOR и логи не выдают действующих токенов.
  • Значение — JSON с user_id, created_at, expires_at, но сроком владеет хранилище: TTL ставится на ключ (SET ... EX). Приложение не хранит свой счётчик времени, поэтому перезапуск процесса не продлевает сессию: в доказательстве 04 у токена, выданного при TTL 3600, после переключения на TTL 3 осталось 3596 с.
  • Инвалидация — GETDEL при logout: удаление атомарно, повторный logout получает 401, а не 204 и не 404. Истечение и отзыв — независимые механизмы; приложение не подчищает просроченные ключи, это делает Valkey (в 04 видно, что ключ исчез сам между двумя запросами).
  • Долговечность — AOF (appendonly yes, appendfsync everysec), RDB выключен, чтобы механизм был ровно один и его было видно в evidence. Цена честная: при гибели процесса теряется примерно последняя секунда записей — это измерено в 05.
  • SESSION_STORE принимает только redis и падает при старте на любом другом значении, включая postgres из .env.example. Молча проигнорировать переменную было бы хуже: человек решил бы, что сессии лежат в PostgreSQL, а они лежали бы в Valkey.

Пагинация и курсор

История и список чатов листаются по ключу: WHERE chat_id = $1 AND ($2::timestamptz IS NULL OR (created_at, id) > ($2, $3)) ORDER BY created_at, id LIMIT $4. В выборке запрашивается limit + 1 строка: лишняя означает has_more, а её ключ становится next_cursor — без второго запроса и без «сколько там всего». UUID сравнивается в PostgreSQL нативно (порядок байтов совпадает с порядком uuid.UUID(x).int, которым публичный smoke сортирует выдачу), поэтому курсор и сортировка не расходятся.

Курсор подписан HMAC-SHA256 (CURSOR_SECRET), привязан к ресурсу и не содержит limit: обход можно продолжить с другим размером страницы, а чужой курсор даёт 400. Альтернатива с OFFSET измерена в 07: 4.078 мс против 0.267 мс на десятой тысяче строк, и она читает 10 000 строк там, где keyset читает 199.

Ошибки

Единый конверт {"error":{"code","message","request_id"}}; request_id совпадает с заголовком X-Request-Id. Штатный 422 FastAPI перехвачен и приведён к контрактному 400 invalid_request. 403 не используется нигде: чужой чат неотличим от несуществующего — 404; сначала аутентификация (401), затем доступ к ресурсу. WWW-Authenticate соответствует маршруту: Basic предлагается только на POST /api/v1/auth/sessions, на бизнес-маршрутах челлендж — Bearer, иначе клиент с Basic-креденшелами получил бы приглашение повторить то, что и привело к отказу. Неверный пароль и несуществующий пользователь отвечают одинаково, и время ответа выравнивается проверочным хешем, чтобы отказ не выдавал существование имени.

Валидация на границе отвергает две категории строк, которые не должны доходить до базы: пароль из одних пробельных символов (это пустое значение обязательного поля, а не секрет) и U+0000 в сохраняемых строках — PostgreSQL text его не хранит. Обе дают 400 invalid_request. 503 unavailable закреплён только за отказами соединения и пула (OperationalError, InterfaceError, DisconnectionError, таймаут пула, ошибки Valkey): DataError — ошибка данных клиента — в это семейство не входит, поэтому сбой значения не маскируется под аварию зависимости.

Таймауты и поведение при отказе зависимостей

Параметр Значение Зачем именно столько
DB_POOL_SIZE / DB_MAX_OVERFLOW 5 / 5 Верхняя граница одновременных соединений задана на процесс; при workers>1 её пришлось бы делить, поэтому процесс один
DB_POOL_TIMEOUT_SECONDS 2 Ожидание свободного соединения в пуле — последняя линия, а не первая
DB_CONNECT_TIMEOUT_SECONDS 1.5 Отдельный таймаут подключения: разрешение имени остановленного контейнера занимает ~3.3 с (доказательство 06), и общий бюджет запроса его не покрывает
DB_COMMAND_TIMEOUT_SECONDS 2.5 Клиентский потолок на запрос
DB_STATEMENT_TIMEOUT_MS 2000 Серверный statement_timeout строже клиентского: запрос обрывает PostgreSQL, а не только клиент, и соединение возвращается в пул живьём
CACHE_TIMEOUT_SECONDS 1 Сессия — одна операция в Valkey; секунды хватает с запасом

При недоступной зависимости бизнес-маршруты и /health/ready отвечают 503 unavailable, а не 401 и не «доверяем анониму»: клиент, реагирующий на 401 повторным входом, выбросил бы рабочую сессию из-за чужой аварии. /health/live при этом остаётся 200 — супервизор не должен перезапускать здоровый процесс.

Логи и X-Request-Id

RequestContextMiddleware стоит снаружи стека Starlette, поэтому заголовок есть и на ответе 500. Лог — JSON-строка на событие: request_id, метод, шаблон маршрута, статус, длительность, user_id. Тел запросов, текстов сообщений и query-строки с курсором в логе нет, access-лог uvicorn отключён. verify_stack.py отдельно проверяет по всему логу контейнера (11 512 строк), что в нём не встречаются ни пароль, ни токен, ни ключ сессии.

Живость, готовность, остановка

  • /health/live — «процесс жив», зависимости не трогает; его опрашивает Docker.
  • /health/ready — «можно принимать трафик»: проверяет PostgreSQL и Valkey. На старте неудачный ping не фатален: при одновременном подъёме api, PostgreSQL и Valkey приложение стартовало бы в петлю перезапусков, а готовность — это как раз то, что должно быть красным, пока зависимости недоступны.
  • CMD в exec-форме, приложение — PID 1, STOPSIGNAL SIGTERM. Бюджет остановки — GRACEFUL_SHUTDOWN_SECONDS (5) плюс SHUTDOWN_DRAIN_SECONDS (0 в стенде; значение больше 10 отвергается при старте с кодом 2).

Соответствие переменных .env.example

.env.example Где используется По умолчанию Замечание
APP_HOST Config.host → адрес bind 0.0.0.0 в compose задано явно
APP_PORT Config.port → порт bind и healthcheck 8080 проверяется диапазон 1..65535
APP_ENV Config.env → метка в логах lab
SESSION_TTL_SECONDS Config.session_ttl_seconds 3600 допустимо 1..86400; короткое значение включает проверки истечения
SESSION_STORE Config.session_store redis допускается только redis; postgres из примера отвергается при старте
DATABASE_URL_FILE Config.database_url — обязательна; DATABASE_URL и *_FILE одновременно — ошибка
CACHE_URL_FILE Config.cache_url — обязательна; тот же принцип «значение или файл»

Дополнительно поддерживаются LOG_LEVEL, DB_POOL_SIZE, DB_MAX_OVERFLOW, DB_POOL_TIMEOUT_SECONDS, DB_CONNECT_TIMEOUT_SECONDS, DB_COMMAND_TIMEOUT_SECONDS, DB_STATEMENT_TIMEOUT_MS, CACHE_TIMEOUT_SECONDS, GRACEFUL_SHUTDOWN_SECONDS, SHUTDOWN_DRAIN_SECONDS, CURSOR_SECRET(_FILE). Некорректное значение — отказ старта с понятным сообщением и кодом выхода 2, а не тихая подстановка умолчания. Значения секретов в текст ошибок не попадают.

Что перенесено из лабораторной 1 и что изменено в файлах skeleton

Перенесены: context, middleware, logging_setup, healthcheck, errors, errorhandlers, domain, models, schema, cursor, pagination, config, deps, access, routers, app и __main__ — то есть структура и дисциплина (конверт ошибок, X-Request-Id, JSON-логи без содержимого, русские docstring'и, полные type hints, docs_url=None). Изменено по существу: хранилище (память → SQL), идентификация (X-User-Id → Basic-вход и opaque Bearer-сессия с TTL и отзывом), появились repository, db, security, sessions, migrations/, Dockerfile, compose.yaml. Строка X-User-Id не читается нигде. X-Instance-Id и Idempotency-Key не добавлялись — это возможности лабораторной 3.

В файлах skeleton изменены только три: Makefile (добавлена цель student-test и строка в help), .dockerignore (дополнен — в образ не входят tests/, student-tests/, contracts/, examples/, infra/, Makefile, *.md) и этот REPORT.md. Контракт, публичные тесты, README.md, COURSE.md, lab.json, scripts/check_contract.py, scripts/validate_openapi.py и .github/** не изменялись.

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

Все измерения сделаны на стенде: Windows 10 Pro 19045, x64, Python 3.11.9, Docker 28.0.1 (WSL2), контейнеры ограничены 2 CPU и 512 МБ (api, postgres), 1 CPU и 256 МБ (valkey).

Уровень 3

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Минимум lab1 сохранён с переходом на новую аутентификацию make test PASS: lab2 public API scenario evidence/01-check-and-smoke.txt
Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes make test-persistence ACTION_SCRIPT=scripts/restart.cmd PASS: persistence preserved confirmed data and existing session; StartedAt сменился у всех трёх контейнеров evidence/02-persistence-restart.txt
PostgreSQL содержит пользователей, чаты, участников и сообщения; PK/FK, уникальность username python student-tests/verify_stack.py, разд. 6 таблицы, uq_users_username, CHECK-ограничения и индексы на месте evidence/11-container-security.txt
Миграции с нуля docker compose up -d на пустом томе в чистом клоне migrate применяет схему и выходит с кодом 0 evidence/12-clean-clone.txt
Миграции повторяются без дублирования alembic upgrade head второй раз, verify_stack.py разд. 6 «нет Running upgrade» — повторный прогон ничего не меняет; alembic check совпадает с моделями evidence/11-container-security.txt
Составная операция создания чата атомарна make student-test (test_chat_atomicity) 6 тестов: неизвестный участник, дубликат и отсутствие создателя дают 400, чата не остаётся evidence/03-student-tests.txt
Basic только на POST /auth/sessions, остальное Bearer make student-test (test_auth) 14 тестов: Basic на бизнес-маршруте → 401 с челленджем Bearer evidence/03-student-tests.txt
Есть срок жизни сессии и отзыв test_sessions, test_expiry 10 + 4 теста: несколько независимых сессий, logout → 204, повтор → 401, истечение по TTL evidence/03-student-tests.txt, evidence/04-expiry-short-ttl.txt
X-User-Id не даёт доступа test_auth, публичный smoke заголовок лабораторной 1 не даёт доступа и не подменяет сессию evidence/03-student-tests.txt
Пароли хешируются KDF test_auth 128 кириллических кодовых точек (256 байт) и пароль длиннее 72 байт не усекаются evidence/03-student-tests.txt
Secrets/volumes не попадают в Git verify_stack.py разд. 4 (git check-ignore) secrets/ и .env игнорируются, в индексе Git нет файлов secrets/ evidence/11-container-security.txt

Уровень 4

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Valkey реально используется для сессий с TTL verify_stack.py разд. 5 и 7 ключ — sha256 токена, а не сам токен; TTL ключа положителен; сырой токен не встречается ни в одном имени ключа evidence/11-container-security.txt
Источник истины, политика expiry и инвалидации описаны раздел «Архитектура и решения» + test_expiry TTL принадлежит хранилищу: expires_at в ответе и TTL ключа совпадают (3.00 с против 3 с); logout — атомарный GETDEL evidence/04-expiry-short-ttl.txt
Persistence, выдерживающее проверяемый рестарт make test-persistence; test_dependency_outage::test_valkey_outage; valkey_crash.py сессия возвращается вместе с TTL 3595 с после stop и после kill -9 процесса evidence/02-persistence-restart.txt, evidence/05-valkey-outage.txt
Параметризованные запросы, ограниченный pool, таймауты src/messenger/repository.py (только bind-параметры, без f-строк), compose.yaml, verify_stack.py разд. 9 пул 5+5, лимиты CPU/памяти и политика restart заданы; бюджет таймаутов измерен на живом отказе evidence/06-postgres-outage.txt
Гонка регистрации одинакового username проверена test_registration_race 12 одновременных регистраций → ровно один 201, остальные 409, в базе одна строка evidence/03-student-tests.txt
Rollback составной операции проверен test_chat_atomicity 400 на неизвестном участнике и ни одного созданного чата evidence/03-student-tests.txt
Индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях student-tests/seed_messages.py (20 116 сообщений, 3 071 чат) + student-tests/explain_queries.py используется ix_messages_chat_id_created_at_id, Rows Removed by Filter: 0, 199 прочитанных строк; без индекса — Seq Scan + Sort, 20 116 строк и в 6 раз медленнее evidence/07-explain-messages.txt
Индекс «моих чатов» обоснован explain_queries.py --only chats Index Only Scan — 1 001 строка из 3 105; без индекса Seq Scan по той же таблице; отдельно показана граница применимости evidence/08-explain-chats.txt
Пагинация не сканирует всю историю explain_queries.py, разд. 4 keyset 0.267 мс и 199 строк против OFFSET 9999 — 4.078 мс и 10 000 строк; обе страницы возвращают один и тот же набор evidence/07-explain-messages.txt
Автоматическая проверка expiry при коротком SESSION_TTL_SECONDS test_expiry при SHORT_TTL_SECONDS=3 токен, выданный до переключения, продолжает работать (3596 с из 3600); через 4 с отвергается обоими маршрутами, ключ исчезает сам evidence/04-expiry-short-ttl.txt
Автоматическая проверка logout test_sessions 204 без тела, повтор → 401, отзыв одной сессии не трогает остальные evidence/03-student-tests.txt
Автоматическая проверка неверного пароля test_auth одинаковый 401 для неверного пароля и неизвестного пользователя evidence/03-student-tests.txt
Автоматическая проверка недоступности Redis/БД ALLOW_OUTAGE=1 … -p test_dependency_outage.py все маршруты: 503 unavailable за 1.0–1.5 с, ни одного 401 и ни одного 200; /health/live остаётся 200 evidence/05-valkey-outage.txt, evidence/06-postgres-outage.txt
Приложение не принимает запрос анонимного пользователя как доверенный те же прогоны при недоступной зависимости доступа нет ни у кого: 503, а не «пустим как анонима» evidence/05-valkey-outage.txt, evidence/06-postgres-outage.txt
PR собирается из чистого clone копия без игнорируемых файлов → up -d --build → make check/validate/test/test-persistence/student-test сборка с нуля 1 м 35 с и 2 м 49 с в двух прогонах, миграции на пустом томе, все проверки PASS, 82 теста OK evidence/12-clean-clone.txt

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

Измерение 1. Индекс истории: 20 116 сообщений, ключ (created_at, id)

Гипотеза: индекс (chat_id, created_at, id) отдаёт страницу истории по порядку, без сортировки всей выборки и без чтения чужих сообщений. Данные — засев через generate_series, включая пары с одинаковым created_at, затем ANALYZE; чат для эксперимента содержит 10 000 сообщений.

Планы: страница середины истории — Limit → Sort → Bitmap Heap Scan → Bitmap Index Scan (сортируется выборка чата, а не вся таблица), страница с курсором у конца истории — Limit → Index Scan вообще без узла Sort, потому что порядок задаёт индекс. Rows Removed by Filter: 0 — курсор отсекает строки индексом, а не фильтром после чтения; прочитано 199 строк, то есть две страницы по 100 и одна лишняя для has_more.

Контрпример получен честно: BEGIN; DROP INDEX ...; EXPLAIN; ROLLBACK. Сравнение на странице с курсором (нижняя граница диапазона ключей): 199 строк и 0.267 мс с индексом против 20 116 строк, Seq Scan и 1.601 мс без него, то есть в 6 раз медленнее и в 101 раз больше прочитанных строк. ROLLBACK вернул индекс на место (проверено отдельным запросом к каталогу).

OFFSET против курсора на десятой тысяче строк: 4.078 мс против 0.267 мс, и OFFSET читает 10 000 строк, которые всё равно выбрасывает. Это и есть ответ на «пагинация не просматривает всю историю».

Измерение 2. Граница применимости второго индекса

Список чатов читается по ix_chat_members_user_id_chat_id: Index Only Scan, 1 001 строка из 3 105 — вместо перебора всей таблицы членства.

Здесь же измерена граница, а не только успех. Для пользователя, который состоит в 2 000 чатах из 3 105 (64 % таблицы), планировщик отказывается от индекса и делает Seq Scan с Rows Removed by Filter: 1105 — и это правильное решение: поднимать две тысячи строк по индексу дороже, чем прочитать три тысячи подряд. Индекс рассчитан на обычного пользователя, у которого чатов мало, и в этом сценарии он полезен; случай «64 % таблицы» вынесен в отчёт как зафиксированная граница, а не спрятан. Если такие пользователи станут нормой, лечится не индексом, а денормализацией (дублированием created_at в chat_members, чтобы убрать Sort) — но это уже другая схема, и менять её без данных о реальном распределении значило бы гадать.

Измерение 3. Нагрузка: closed loop, 30 с, 4 и 16 потоков

Профиль: tests/load.py пишет сообщения в один чат; каждый поток ждёт ответа, прежде чем отправить следующий (closed loop, без retry); длительность 30 с; прогрева нет; повторов нет — числа одного прогона, а не среднее.

Потоков Успешных Ошибок RPS p50 p95 p99
4 6 282 0 208.9 16 мс 32 мс 47 мс
16 4 933 0 162.5 93 мс 172 мс 234 мс

CPU и память (сэмплы docker stats во время второго прогона): api 56 % → 93–102 %, postgres 20–23 %, valkey меньше 2 %. Датасет после двух прогонов: 31 454 сообщения в 3 136 чатах, 349 пользователей, таблица messages 7 472 кБ.

Сырые числа и оговорки стенда — evidence/09-load.txt; JSON второго прогона, который принимает tests/load.py --output, — evidence/09-load-c16.json (сессионных токенов в нём нет).

Что из этого следует. Потоков стало вчетверо больше, а пропускная способность упала на 22 %, задержка p99 выросла в 5 раз — стенд упёрся не в базу и не в квоту CPU: у контейнера api лимит 2.0 ядра, а он занят примерно одним. Причина видна в коде: приложение запущено одним процессом uvicorn (workers=1; там же объяснено, почему — границы пула соединений заданы на процесс). Один процесс — один event loop — одно ядро; семнадцатый одновременный запрос не получает параллелизма, он ждёт в очереди. Что именно ест это ядро — сериализация SQLAlchemy, JSON или проверка сессии, — эти замеры не показывают: нужен профиль, и это записано следующим шагом, а не выводом.

Ограничения измерения: клиент живёт на той же машине и вне контейнеров, поэтому его собственные затраты в docker stats не видны, а время запроса включает и его; closed loop занижает перцентили при насыщении (coordinated omission) и связывает RPS с задержкой; датасет учебный, при десятках миллионов строк и запись, и индексы будут вестись иначе.

Таблица отказов

Воздействие Что ожидали Что наблюдали Время восстановления / потеря данных
docker compose stop valkey 503 unavailable < 2 с, /health/live 200, сессия возвращается 1.016 / 1.000 / 1.031 / 1.000 с, все unavailable; ключ вернулся с TTL 3595 с, прежний токен принимается поднят за 0.31 с; потерь нет (SIGTERM + AOF)
docker compose stop postgres 503 < 2 с, данные целы 1.500–1.516 с на всех маршрутах, включая вход; запись, сделанная до отказа, читается после поднят за 0.83 с; потерь нет
kill -9 процессу valkey-server внутри контейнера контейнер поднимается сам, сессия возвращается RestartCount 0 → 1, готов через 5.56 с; ключ EXISTS 1, TTL 3591 с 5.56 с (из них около 5 с — период healthcheck); теоретическая потеря ≤1 с записей everysec на этом прогоне не выстрелила
docker compose kill valkey — (проверяли, поднимется ли) контейнер остался exited: политика restart не поднимает контейнер, убитый снаружи, — Docker считает это ручным действием поднят оператором за 5.22 с; сессия на месте
docker compose restart api postgres valkey (scripts/restart.sh) тот же токен читает те же данные PASS: persistence preserved confirmed data and existing session; StartedAt сменился у всех трёх контейнеров ~30 с вместе с проверкой; потерь нет
Повторный alembic upgrade head ничего не меняет «нет Running upgrade»; alembic check совпадает с моделями —

Отдельно про время ответа при отказе Valkey: в одном прогоне запрос получил 503 за 0.000 с (соединение к мёртвому процессу отвергается сразу), в другом — за 1.000 с (клиент дождался таймаута сокета на уже установленном соединении). Оба значения внутри бюджета, и оба означают одно: CACHE_TIMEOUT_SECONDS=1 ограничивает ожидание сверху, а не задаёт его. При остановленной PostgreSQL ответ занимает 1.5 с и упирается в DB_CONNECT_TIMEOUT_SECONDS: за это время успевает истечь только подключение, но не запрос. Стоит помнить, что 3.3 с внутри этого времени — вклад DNS Docker, а не базы: имя остановленного контейнера перестаёт разрешаться, и запрос уходит вышестоящему резолверу (измерено изнутри контейнера, доказательство 06).

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

Что решение выдерживает (подтверждено измерением): остановку и падение Valkey, остановку PostgreSQL, полный перезапуск всех трёх сервисов без удаления томов, конкурентную регистрацию одного имени, откат неудачного создания чата, истечение и отзыв сессий, обход истории в 10 000 сообщений с корректным курсором.

Чего решение не выдерживает или не делает:

  • Rate limiting отсутствует. Пароль проверяется argon2id, и каждый вход стоит процессорного времени; поток входов с одного адреса никем не ограничен. Для учебного стенда на loopback это допустимо, для публичного — первое, что нужно добавить.
  • Кэша истории нет, и это осознанно: кэш создал бы второй источник истины и вопрос о read-after-write, который нечем проверить в этой лабораторной. Трек 5 как раз про это, и мы его не заявляем.
  • Один процесс uvicorn. Горизонтального масштабирования нет: вторая реплика — это второй набор пулов и второй набор курсоров (курсоры, впрочем, не привязаны к процессу, так как подписаны общим секретом). Масштабирование — задача лабораторной 3.
  • Потеря до ~1 секунды сессий при гибели процесса с appendfsync everysec. Вариант always убрал бы окно ценой заметно более медленной записи; для сессий это плохой размен, и он не сделан осознанно. Что именно теряется — только что выданные сессии; данные в PostgreSQL не затронуты.
  • Нет snapshot-изоляции между страницами истории: строка, зафиксированная позади курсора во время обхода, может не попасть в этот обход. Дубликатов при этом не возникает. Полноценное решение — материализованный снимок или версионирование.
  • GETDEL не защищает от гонки logout с параллельным запросом: запрос, начатый до отзыва, успеет завершиться. Для мессенджера это нормальное поведение (отзыв не мгновенный), но его стоит назвать.
  • Курсоры не имеют срока жизни: подписанный курсор остаётся валидным, пока жив секрет. Протухший курсор просто вернёт пустую страницу — это безопасно, но неинформативно.
  • Идентификатор пользователя не секрет: user_id виден в ответах, а UUID — не средство авторизации. Доступ проверяется членством в чате, а не знанием идентификатора.

Подтверждено измерением: индекс истории и его ценность, граница применимости второго индекса, бюджет таймаутов и поведение при отказах, долговечность AOF при остановке и падении, потолок пропускной способности одного процесса. Гипотеза, требующая отдельного замера: что именно ограничивает пропускную способность (профиль процессора) и где предел при горизонтальном масштабировании — это предмет следующих работ, а не вывод этой.

Источники и ИИ

  • Контракт и семантика: contracts/openapi.json, contracts/README.md, contracts/infrastructure.json, COURSE.md, README.md — единственный источник требований. Контракт и публичные проверки не изменялись и не подгонялись под решение.
  • Библиотеки: FastAPI 0.141.1, uvicorn 0.53.0, SQLAlchemy 2.0.44 (async), asyncpg 0.30.0, Alembic 1.16.5, redis-py 6.4.0 (клиент Valkey), argon2-cffi 25.1.0; полный список с точными версиями — в requirements.txt, отдельно requirements-dev.txt для полной проверки OpenAPI. Стандартная библиотека: asyncio, hmac, hashlib, secrets, logging, dataclasses, uuid, datetime, unittest.
  • Первичные материалы: PostgreSQL: EXPLAIN, PostgreSQL: transactions, Valkey: persistence, Basic authentication, Dockerfile reference.
  • Помощь ИИ: реализация написана с использованием Claude Code (Anthropic): генерация кода по моей постановке, разбор контракта, подготовка проверок и этого отчёта. Измерения выполнены на моём стенде и воспроизводимы командами из отчёта; там, где эксперимент дал неожиданный результат (например, docker compose kill не поднимается политикой restart), в отчёте осталось наблюдение, а не ожидание.