683 lines
68 KiB
Markdown
683 lines
68 KiB
Markdown
# Отчёт — лабораторная 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/`.
|