50 KiB
Отчёт — лабораторная 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: на Windowslocalhostсначала разрешается в::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), в отчёте осталось наблюдение, а не ожидание.