Files
mtusi2026lab2/REPORT.md
T

213 lines
31 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**, трек 2 «План запроса и восстановление».
- Основа: `mtusi2026/mtusi2026lab2`, commit `65003b61195361aac238f19c9bff0027ca58e09e`.
- Ветка решения: `solution/bvt2301-abdurashidov`. Проверенный commit записывается в `evidence/clean-clone.json`; хеши исходников измерений — в `evidence/research.json`.
- Дата проверок: 30 октября 2026 года.
- Источники и библиотеки: контракт курса, Python stdlib, psycopg 3, redis-py, официальная документация PostgreSQL/Docker/Valkey. matplotlib/NumPy нужны только для рисунка. Собственное Python-решение lab1 использовано как основа HTTP-транспорта; чужие студенческие решения не переносились.
## Что выполнено
1. Изучены новый README, COURSE, OpenAPI, семантика сессий, инфраструктурные роли и публичные проверки. Исходный `make check` прошёл; smoke на ещё отсутствовавшем lab2-сервере ожидаемо получил ошибку соединения.
2. До SQL-запросов описаны [таблицы, ограничения, индексы и транзакции](infra/SCHEMA.md). Добавлена версионируемая миграция `001_initial.sql`; повторный запуск проверяет SHA-256 и не дублирует данные.
3. Из lab1 перенесены строгий HTTP/JSON-транспорт, Unicode-валидация, единый формат ошибок, Request-Id и обработка остановки. Память процесса как источник данных заменена PostgreSQL.
4. Добавлены регистрация с scrypt, Basic-вход без JSON body, непрозрачные 256-битные Bearer-токены, абсолютный expiry и logout. Сессии сохраняются в PostgreSQL; X-User-Id не влияет на идентификацию.
5. Подготовлены Dockerfile и Compose с API, PostgreSQL и Valkey, именованным volume, локальными secret-файлами, healthchecks и закреплёнными версиями/digest.
6. Valkey используется как cache-aside неизменяемого публичного профиля с TTL. История и действительность сессии всегда читаются из PostgreSQL; отказ кэша допускает fallback.
7. Добавлены собственные HTTP-тесты, автоматические проверки отказов/expiry/rollback, публичный hook реального перезапуска всех трёх компонентов и проверка отдельного чистого clone.
8. Проведено исследование на трёх изолированных БД по 100 000 сообщений; сравниваются три индекса, keyset/OFFSET и стоимость committed INSERT. Backup восстановлен в отдельный новый PostgreSQL-контейнер с новым volume; сверена вся история.
## Запуск из чистого clone
Требуются Git, Docker с Compose, Python 3.11+ и make. Внешняя установленная БД не нужна. Исходный README задания, contracts/ и публичные tests/ сохранены.
```sh
# В корне checkout решения:
make up
make check test student-test
make infra-test
# Отдельно публичный persistence:
make test-persistence ACTION_SCRIPT=scripts/restart.sh
# Исследование:
make research
```
`make up` вызывает `scripts/bootstrap.py`: создаются `.env` из примера и случайные локальные credentials только при их отсутствии. Затем `docker compose up -d --build --wait` собирает исходники и ждёт healthcheck. Миграции применяются при старте API до bind HTTP-порта. Оператор не создаёт таблицы вручную и не передаёт пароли в командной строке.
Приложение слушает `0.0.0.0:8080` внутри контейнера, опубликовано только на `127.0.0.1:8082`. Другие сервисы не публикуют host-порты. 8082 выбран для сосуществования с lab1 на 8080; `make` передаёт BASE_URL явно. При смене HOST_PORT изменить также BASE_URL команд тестов.
| Компонент | Закреплённая версия | Назначение |
| --- | --- | --- |
| API | Python 3.13.12 slim-bookworm, digest в Dockerfile | HTTP и драйверы, UID 10001, read-only rootfs |
| PostgreSQL | 17.9-bookworm, digest в compose.yaml | Источник истины; persistent postgres_data |
| Valkey | 8.1.3-alpine, digest в compose.yaml | Только профильный кэш; память 64 MB, allkeys-lru |
| psycopg / psycopg-binary | 3.3.6 | Параметризованный SQL и бинарный libpq |
| psycopg-pool | 3.3.1 | Ограниченный потокобезопасный пул |
| redis-py | 6.4.0 | Valkey protocol client |
| typing_extensions | 4.16.0 | Закреплённая зависимость пула |
Все Python-зависимости приложения закреплены в `requirements.txt`. Dockerfile копирует только исходники и миграции; `.dockerignore` исключает Git, .env, secrets, backups, локальные окружения, тесты, исследования и bytecode. Build/runtime для компилируемого языка здесь неприменимы.
### Конфигурация и секреты
| Переменная | Реальное поведение |
| --- | --- |
| APP_HOST / APP_PORT | В Compose фиксированы 0.0.0.0 / 8080, внутренний HTTP bind |
| HOST_PORT | Host published port; по умолчанию 8082 |
| APP_ENV | Метка лабораторного окружения в .env; не переключает хранилище |
| SESSION_TTL_SECONDS | Абсолютный срок сессии, 3600 с по умолчанию; тест отдельно использует 2 с |
| SESSION_STORE | Поддерживается и проверяется postgres; Valkey не является хранилищем сессий |
| PROFILE_CACHE_TTL_SECONDS | TTL публичного профиля, по умолчанию 300 с |
| DB_POOL_MAX | Максимум 8 соединений по умолчанию; допустимо 1–32 |
| DATABASE_URL_FILE / CACHE_URL_FILE | DSN читаются из явно смонтированных `/run/secrets/...` |
Папка secrets/ имеет режим 0700 на хосте; файлы читаемы сервисными UID только в тех контейнерах, куда явно смонтированы. Compose secrets локального стенда — файловые mounts, не шифрованное secret-хранилище. .env содержит настройки без credentials. Сами пароли/DSN не печатаются и не входят в Git или отчёт.
```sh
# Остановка с сохранением volume и secret-файлов:
docker compose down
# Возобновление:
docker compose up -d --wait
# Намеренное удаление учебных данных только этого проекта:
docker compose down --volumes
```
Удаление volume не удаляет secret-файлы. Удаление/регенерация файлов при сохранённой БД не меняет её пароль автоматически. Секреты следует хранить вместе с инструкцией эксплуатации вне Git.
## Архитектура и транзакции
```text
Клиент → HTTP API (Python, один процесс, потоки)
├→ PostgreSQL: пользователи, чаты, членство, история,
│ хеши сессий/expiry, cursor key, миграции
└→ Valkey: public User по user_id, TTL 300 с
```
Реализация хранит `users`, `chats`, `chat_members`, `messages`, `sessions`, `app_settings`, `schema_migrations`. PK/FK, уникальность username и CHECK обеспечивают базовые инварианты. У сообщения составной FK `(chat_id,sender_id)` на участника чата. Индекс членства `(user_id,chat_id)` поддерживает список доступных чатов. Схема и её обоснование сохранены отдельно до SQL-реализации.
Регистрация атомарно вставляет пользователя, конфликт уникальности возвращает 409. Создание чата и всех участников — одна транзакция; неизвестный участник вызывает FK violation и полный rollback. Отправка сообщения обновляет `last_message_at` чата и вставляет сообщение в одной транзакции. Контекст соединения фиксирует COMMIT до возврата успешного HTTP-ответа; исключения откатывают операцию. SQL-параметры передаются драйверу отдельно от текста запроса.
Пул: минимум 1, максимум 8 соединений, очередь не более 32 ожидающих, ожидание 2 с. Connect timeout 2 с, statement timeout 2 с, lock timeout 1 с, idle-in-transaction 5 с. Исчерпание пула/таймаут/потеря БД дают 503 без внутренних деталей. Потоки HTTP не являются отдельными независимыми источниками состояния.
Миграции инициализируются под транзакционной advisory lock; применённые версии и SHA-256 хранятся в БД. Повторное применение не создаёт бизнес-данные. Изменение уже применённого файла обнаруживается; изменение схемы требует новой миграции. Все pending migrations одного запуска фиксируются вместе с созданием постоянного cursor key.
### Пароли, сессии и доступ
Пароли: scrypt N=16384, r=8, p=1, dklen=32, случайная соль 16 байт; параметры, соль и hash записаны вместе. Длина 12–128 Unicode code points; пароль кодируется в UTF-8 без усечения, двоеточие допускается. Сравнение constant-time. Для неизвестного username выполняется dummy KDF; текст и challenge 401 совпадают с неверным паролем существующего пользователя.
`POST /auth/sessions` принимает Basic только в Authorization, без JSON body. Выдаётся `secrets.token_urlsafe(32)` — 256 бит случайности, не UUID и не username. В БД сохраняется SHA-256 токена, user_id и абсолютное expires_at по часам PostgreSQL. Здесь быстрый SHA-256 уместен для случайного высокоэнтропийного токена; пароль обрабатывается медленным password KDF.
Каждый защищённый запрос проверяет Bearer и expiry в PostgreSQL. Logout удаляет только текущую сессию; другая сессия пользователя остаётся действительной. X-User-Id игнорируется. Сначала аутентификация, затем доступ; чужой/отсутствующий чат одинаково возвращает 404. Пароль, hash и session-данные в User не включаются. HTTP используется только для локального синтетического стенда.
### Кэш и read-after-write
Valkey хранит только четыре поля public User: id, username, display_name, created_at. В текущем контракте профили не изменяются, поэтому TTL 300 с и cache miss безопасны; при добавлении UPDATE/DELETE потребуется явная инвалидация/версионирование ключей. Ключ имеет namespace `profile:v1:<UUID>`.
Сначала PostgreSQL подтверждает сессию, затем разрешается cache hit профиля. Поэтому cache hit никогда не позволяет обойти expiry или logout. При недоступности Valkey timeout 200 мс, автоматических retry нет: профиль читается из PostgreSQL, cache set может быть пропущен. Потеря всего кэша не теряет сессии. Valkey persistence намеренно выключен: это восстанавливаемый кэш, а не единственное хранилище данных или сессий.
Сообщения и история вообще не кэшируются. Следующий GET обращается к primary PostgreSQL после завершённого COMMIT записи. Членство тоже проверяется в БД. Это обеспечивает read-after-write без риска устаревшей страницы из Valkey.
### Пагинация и часы
Cursor подписан HMAC-SHA256 постоянным ключом из app_settings, включает resource scope и `(created_at,id)`. Он переживает рестарт API/БД, привязан к чату либо текущему пользователю для списка чатов. Неверная подпись/scope — 400; limit 1–100 может меняться между страницами.
```sql
SELECT id, chat_id, sender_id, text, created_at
FROM messages
WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
ORDER BY created_at, id
LIMIT $4;
```
Рабочий индекс — `(chat_id,created_at,id)`. API читает limit+1 строку для определения next_cursor, возвращает только limit. OFFSET в API не используется. Timestamp сообщений монотонен внутри чата: row lock и `greatest(clock_timestamp(), last_message_at + interval '1 microsecond')` защищают порядок конкурентных вставок и откат часов. Время может слегка опережать физические часы; это не распределённые часы.
Snapshot isolation между HTTP-страницами не обещается. Подтверждённое между страницами новое сообщение может попасть в последующие страницы. Отсутствие повторов гарантируется для неизменной истории. Для создаваемых конкурентно чатов порядок определяется парой, но страницы не являются снимком всех будущих COMMIT.
### Health и остановка
Live проверяет HTTP-процесс. Ready проверяет PostgreSQL; Valkey некритичен, поскольку есть fallback. SIGTERM прекращает приём новых запросов и дренирует потоки; socket timeout 3 с, общий срок 7,5 с с закрытием оставшихся сокетов, stop_grace_period 10 с. Содержимое сообщений, Authorization и DSN не логируются; лог содержит request_id, метод, статус и длительность.
## Доказательства критериев
| Критерий | Команда / сценарий | Результат | Доказательство |
| --- | --- | --- | --- |
| Целостность контракта и схемы | make check validate PYTHON=.venv/bin/python | PASS | [contracts.txt](evidence/contracts.txt) |
| Обязательный lab2 API | make test | Публичный сценарий PASS | [smoke.txt](evidence/smoke.txt) |
| PostgreSQL, миграции, сессии переживают рестарт | make test-persistence ACTION_SCRIPT=scripts/restart.sh | Тот же токен читает прежние данные | [persistence.txt](evidence/persistence.txt) |
| Все реальные процессы/хранилища перезапущены | make infra-test | StartedAt изменился у API, PostgreSQL и Valkey; volumes не удалены | [infrastructure.json](evidence/infrastructure.json) |
| Valkey используется осмысленно | make infra-test | Есть profile keys с положительным TTL, только public поля; flush/restart восстанавливается | [infrastructure.json](evidence/infrastructure.json) |
| Параметризованные SQL, pool/timeouts | src/store.py; отказ PostgreSQL | 503 примерно за 2,01 с; анонимные запросы не доверены | [store.py](src/store.py), [infrastructure.json](evidence/infrastructure.json) |
| Гонка username | make student-test | 10 одновременных запросов → ровно 1×201 и 9×409 | [student-tests.txt](evidence/student-tests.txt) |
| Rollback составной операции | make student-test; make infra-test | Ошибка неизвестного участника не оставляет чат и членство; количества сверяются в SQL | [student-tests.txt](evidence/student-tests.txt), [clean-clone.json](evidence/clean-clone.json) |
| Конкурентная история | make student-test | 100 сообщений / 10 клиентов, без потерь и дублей | [student-tests.txt](evidence/student-tests.txt) |
| Expiry/logout/неверный пароль | make student-test; make infra-test | 401, отдельный TTL 2 с, другая сессия сохраняется | [student-tests.txt](evidence/student-tests.txt), [infrastructure.json](evidence/infrastructure.json) |
| Отказ Valkey и PostgreSQL | make infra-test | Cache fallback; PG→503; live 200 / ready 503; восстановление с прежней сессией | [infrastructure.json](evidence/infrastructure.json) |
| Индекс и EXPLAIN на ≥10 000 | make research | Измерены 100 000 сообщений; index condition по chat_id и tuple; 50 строк вместо фильтрации 79 900 | [explain-plans.json](evidence/explain-plans.json) |
| Чистый clone / новая БД / воспроизводимость | make clean-clone-test | Отдельные clone, порт, credentials, сеть и volumes; сборка, HTTP и infrastructure проверки | [clean-clone.json](evidence/clean-clone.json), [clean-clone-run.txt](evidence/clean-clone-run.txt) |
| Трек 2: ≥100 000, неравномерные чаты, ≥2 индекса/запроса | make research | 3 индекса × 4 чата × 2 запроса × 30 чтений; 10 write-batch на индекс | [research.json](evidence/research.json), [CSV](evidence/query-measurements.csv) |
| Backup → новое хранилище → сверка | make research | Новый контейнер и volume; 100 000 сообщений, все counts, 7 samples и полный SHA-256 совпали | [research.json](evidence/research.json) |
`make clean-clone-test` проверяет текущий commit, а не незакоммиченные изменения. Он удаляет только свои одноразовые тестовые volumes. CI workflow приложения добавлен отдельно; удалённый запуск GitHub Actions на Gitea не заявляется.
## Исследование и фактические результаты
Гипотеза, полный метод и ограничения: [research/README.md](research/README.md). Аппаратная среда: Apple M4, 16 GiB RAM, Docker Desktop 29.4.3, Linux arm64. PostgreSQL и клиент имеют по 1 CPU / 512 MiB; Valkey — 0,5 CPU / 128 MiB, внутренний cache maxmemory 64 MB.
Исследуются три отдельных БД с одинаковой схемой и 100 000 сообщениями в чатах 80 000 / 15 000 / 4 000 / 1 000. Структурное отличие — только индекс: `chat_id`, составной keyset, либо covering с INCLUDE. После 3 прогревов выполняется по 30 последовательных чтений; сохраняются все времена и nearest-rank p50/p95/p99. Стоимость записи — 10 реальных транзакций по 1000 сообщений, время включает EXPLAIN ANALYZE и COMMIT. Write-строки после измерения удаляются только в исследовательской БД; VACUUM ANALYZE предшествует чтению. Это не нагрузочный HTTP-тест.
| Индекс / запрос, чат 80 000 | p50, мс | p95, мс | p99, мс |
| --- | ---: | ---: | ---: |
| chat_id / keyset | 7,0761 | 7,1933 | 7,1945 |
| составной / keyset | 0,2249 | 0,2545 | 0,3508 |
| covering / keyset | 0,1993 | 0,3393 | 0,4040 |
| составной / OFFSET | 6,9243 | 12,6501 | 15,0282 |
При поздней странице большого чата p95 составного keyset-запроса меньше исходного примерно в **28,26 раза**. EXPLAIN показывает: исходный индекс фильтрует 79 900 строк и сортирует, затрагивает 2017 shared hit blocks; составной — Index Scan с tuple в Index Cond, только 50 строк и 6 shared hit blocks. Covering даёт Index Only Scan, 0 heap fetches, 5 blocks, но это не гарантирует лучший p95 в короткой выборке.
| Индекс | Все индексы messages, MiB | INSERT 1000 + COMMIT p50, мс | p95, мс | Средний WAL bytes |
| --- | ---: | ---: | ---: | ---: |
| chat_id | 5,203 | 9,6394 | 11,5286 | 379 956 |
| составной | 11,156 | 10,2890 | 12,1678 | 453 492 |
| covering | 27,609 | 13,9626 | 64,6203 | 708 616 |
Выбран узкий составной индекс: он устраняет линейный просмотр поздней страницы, а covering увеличивает размер индексов примерно в 2,47 раза относительно составного и медиану write-batch примерно в 1,36 раза. Малые разницы субмиллисекундных чтений не перевешивают этот расход в данном стенде. OFFSET остаётся затратным даже с составным индексом. Планировщик и реальные buffers подтверждают механизм изменения; один факт наличия индекса этого не доказывает.
![Индексы, задержки и стоимость записи](evidence/research.png)
Backup custom-format: **3 004 503 bytes**, создание **0,5288 с**. Подготовка нового PostgreSQL с новым volume — **1,3216 с**, restore — **0,6135 с**, вместе **1,9351 с** без последующей проверки. После восстановления совпали counts всех семи таблиц, 7 выбранных сообщений и SHA-256 всей истории. Orphan messages — 0. Сессия и постоянный cursor key также присутствуют в снимке; функциональная сохранность реальных API-сессий отдельно проверена публичным restart-тестом.
После dump в источник добавлена canary-запись. Источник содержит 100 001 сообщение, восстановленная БД — исходные 100 000. Это ожидаемая граница snapshot backup: подтверждённая после снимка запись в этот backup не входит. Нулевой RPO не заявляется; нужны WAL archive/PITR. Время здесь относится к маленькому локальному синтетическому набору, не к полному production RTO.
Полные результаты: [таблица](evidence/research-summary.md), [raw JSON](evidence/research.json), [EXPLAIN](evidence/explain-plans.json), [CSV](evidence/query-measurements.csv). Dump хранится только локально в игнорируемом backups/; реальные рабочие данные не экспортировались.
## Отказы, ограничения и дальнейшие шаги
| Воздействие | Ожидание | Наблюдение | Потери / восстановление |
| --- | --- | --- | --- |
| Valkey down | Fallback в PostgreSQL, logout действует | Сценарий 0,85 с, корректные profile/history и 401 после logout | Потерян только восстанавливаемый кэш |
| Valkey flush/restart | Перезаполнение профилей; revoked token не оживает | PASS | Пользователи/сообщения/сессии не теряются |
| PostgreSQL down | 503, ready 503, live 200, без доверия анониму | Первый защищённый запрос 2,01 с | Данные на volume; прежняя сессия работает после старта |
| API + все хранилища restart | Данные и неизменённый expiry сохраняются | Публичный persistence PASS; все StartedAt изменились | Воспроизведённое восстановление около 7,924 с |
| SESSION_TTL_SECONDS=2 | 401 после expiry | PASS в отдельном API-контейнере | Истекает только сессия |
| Неизвестный участник в создании чата | Полный rollback | HTTP и SQL-проверка отсутствия остаточных строк | Нет частичного чата |
| Restore снимка | Совпадение состояния на момент dump | 100 000 сообщений и полный checksum совпали | Canary после снимка отсутствует ожидаемо |
Ограничения: один локальный PostgreSQL, нет репликации/HA/PITR; именованный volume не защищает от потери диска/хоста. Synchronous COMMIT опирается на настройки PostgreSQL и честность fsync нижележащего хранилища. Истёкшие сессии логически не дают доступ, но фоновая очистка их строк пока не реализована. Кэш не измерялся на stampede/stale read — трек 1 не заявляется. Обновление/удаление пользователей, вложения, idempotency и балансировка относятся к следующим работам.
Короткие последовательные SQL-измерения с прогретыми страницами и фиксированным порядком вариантов не дают production SLA, максимальный throughput или статистически устойчивые tail-percentiles. CPU-профилирование не проводилось; ограничения ресурсов заданы явно. Полноценный HTTP-сервер промышленного развёртывания потребовал бы дополнительных ограничений соединений и внешнего TLS.
## Ответы на вопросы защиты
- **COMMIT:** фиксирует всю транзакцию либо не фиксирует её при ошибке; возврат API происходит после завершения контекста транзакции. Durability зависит от synchronous_commit, fsync, full_page_writes, диска и сохранности volume. Ответ на неопределённый сетевой обрыв ещё не гарантирует отсутствие совершённой записи.
- **Сессии и Redis/Valkey:** сессии находятся в PostgreSQL, Valkey содержит только public User. Flush/restart теряет cache hit, но не токен/expiry. Logout всегда проверяется по БД.
- **Аутентификация и доступ:** Bearer устанавливает текущего пользователя; членство решает, может ли он читать/писать конкретный чат. Действительный токен постороннего всё равно получает 404.
- **Password KDF и checksum:** человеческий пароль низкоэнтропийный, нужен salted memory-cost KDF; случайный 256-битный токен можно искать по SHA-256. SHA-256 истории в backup-проверке обнаруживает отличие данных и не заменяет password KDF.
## Первичные источники
- [PostgreSQL transactions](https://www.postgresql.org/docs/17/tutorial-transactions.html), [EXPLAIN](https://www.postgresql.org/docs/17/using-explain.html), [SQL dump](https://www.postgresql.org/docs/17/backup-dump.html).
- [Psycopg connection pools](https://www.psycopg.org/psycopg3/docs/advanced/pool.html), [query parameters](https://www.psycopg.org/psycopg3/docs/basic/params.html).
- [Python scrypt](https://docs.python.org/3.13/library/hashlib.html#hashlib.scrypt), [Basic authentication RFC 7617](https://www.rfc-editor.org/rfc/rfc7617).
- [Valkey expiration](https://valkey.io/commands/expire/), [Dockerfile reference](https://docs.docker.com/reference/dockerfile/).