Files
mtusi2026lab2/REPORT.md
T

683 lines
68 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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
(`track2-query-plans`, `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`.
```sh
git clone <fork> && cd <каталог clone>
git checkout solution/bvt2301-safronov
```
### Способ 1. Всё в compose: `make run_docker`
```sh
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`
```sh
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.
Переключение между способами не требует правки файлов (раздел
«Конфигурация»).
### Проверки
```sh
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. Рабочий стенд не трогается. Два
прогона одновременно не запускать.
### Сценарий защиты
```sh
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`, в
командной строке его нет.
Вручную вход и запрос выглядят так (пароль и токен — свои):
```sh
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, как его выполнило
приложение:
```sql
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.
Файлы: `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 | — | TODO | 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.
- Настройки Postgres — по умолчанию образа (`shared_buffers` 128 МБ).
Таблица с индексами на 500k (122 МБ) целиком в памяти, чтения с диска
не измерялись.
- Все планы приложения — custom: параметры подставлены в условия. Какой
generic plan Postgres выбрал бы для prepared statement asyncpg после
многих выполнений, не проверялось.
- Docker Desktop на ноутбуке (macOS, Apple M3 Pro): числа сравнимы
только между метками этой методики, а не с другими машинами.
## Ограничения и следующие шаги
- Сервер, замёрзший при открытом соединении, держит запрос 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
по умолчанию, вся таблица в памяти (раздел «Нагрузочный стенд на
PostgreSQL», ограничения замера).
- Не реализовано: трек 2 — сравнение индексов на чатах разного размера
и backup с восстановлением (changes `track2-query-plans` и
`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`, задержка статистики).
- Библиотеки: FastAPI, pydantic, pydantic-settings, structlog,
SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn; в тестах —
pytest и httpx.
- ИИ: Claude (Claude Code) помогал проектировать changes
`postgres-storage`, `session-auth`, `membership-cache` и
`failure-checks` (OpenSpec),
писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки
просмотрены автором; поведение подтверждено командами, выводы которых
лежат в `evidence/`.