Files
mtusi2026lab2/REPORT.md
T
2026-10-23 11:35:32 +03:00

129 lines
21 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 (план запроса и восстановление из backup). На 4 сессии в Redis, не Valkey.
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: свой код lab1 (FastAPI, проверка полей, cursor, формат ошибок). Дальше psycopg, argon2-cffi, redis-py, официальные образы PostgreSQL 16.10 и Redis 7.4.2. По persistence смотрела документацию Redis AOF и PostgreSQL transactions/EXPLAIN, по Basic — RFC 7617. Реализацию и текст отчёта готовила с помощью Cursor; команды, тесты и планы прогнала локально и могу объяснить.
## Запуск из чистого clone
Нужны Docker и Python 3.11+ (Python только чтобы гонять тесты с хоста). Секреты в репозитории нет.
```bat
python scripts/bootstrap.py
docker compose --env-file .env up -d --build
```
`bootstrap.py` один раз пишет `.env` и `secrets/` (пароль Postgres и URL). В консоль пароль не печатает. Повторный запуск файлы не перезаписывает: volume уже инициализирован этим паролем.
Дальше дождаться `GET /health/ready` = 200 и:
```bat
python tests/smoke.py --base-url http://127.0.0.1:8080
python student-tests/run.py
python student-tests/run_failures.py
python student-tests/run_track2.py
```
Persistence (Linux, либо WSL, потому что hook — shell-скрипт):
```sh
chmod +x scripts/restart.sh
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
```
На этой машине Win32-python не запускает shebang, поэтому официальный persistence я гоняла из WSL тем же `scripts/restart.sh`. Скрипт делает `docker compose restart` для postgres, redis и api и `up --wait` для баз. `down -v` там нет.
Остановка без удаления данных: `docker compose --env-file .env stop`.
Снести учебные данные: `docker compose --env-file .env down -v`. Пароль в `secrets/` после этого всё ещё подходит к новому пустому volume. Чтобы выписать новый пароль, удалить `secrets/` и снова запустить bootstrap.
Образы, не `latest`: `python:3.12.10-slim-bookworm` (`sha256:fd95fa221297a88e1cf49c55ec1828edd7c5a428187e67b5d1805692d11588db`), `postgres:16.10-bookworm` (`sha256:38471f330eb885e04de130b768d6db4e10469e2311879c7e5c699f6d2d8a1c74`), `redis:7.4.2-bookworm` (`sha256:fbdbaea47b9ae4ecc2082ecdb4e1cea81e32176ffb1dcf643d422ad07427e5d9`). API слушает 8080 внутри контейнера, с хоста только `127.0.0.1:8080`. Postgres и Redis наружу не проброшены. Процесс API — пользователь 10001.
## Архитектура и решения
Из lab1 остались маршруты, разбор JSON, cursor `(created_at, id)`, тело ошибки и `X-Request-Id`. In-memory словари и заголовок `X-User-Id` убраны. `STORE_MODE` тоже: порядок истории теперь задаёт индекс, а не сортировка в процессе.
Клиент ходит в один процесс API. Пользователи, чаты, участники и сообщения лежат в PostgreSQL — это источник истины. Redis хранит только сессии. Историю сообщений в Redis я не клала, поэтому отдельной инвалидации кэша истории нет: после успешного INSERT следующий GET читает Postgres.
Сессия: случайные 32 байта (`token_urlsafe`), клиенту отдаётся сырой токен. В Redis ключ `sess:` + SHA-256 токена, значение — `user_id` и `expires_at`. Срок абсолютный (`SET` с `pxat`), плюс та же метка внутри значения. Чтение сессию не продлевает. Logout делает `DEL`. Истёкший ключ или `expires_at` в прошлом — 401. Рестарт контейнера срок не сдвигает: в persistence-тесте жил старый токен, в отдельной проверке TTL=2 после паузы дал 401.
Пароль — Argon2id (`time_cost=2`, `memory_cost=19456`, `parallelism=1`). Не SHA-256 и не bcrypt: пароль до 128 code points в UTF-8, bcrypt режет 72 байта. В ответ пользователя хеш не входит. Неизвестный username прогоняется через фиктивный хеш, чтобы отказ не был мгновенным.
Basic только на `POST /api/v1/auth/sessions`. Остальное — Bearer. `X-User-Id` не читается. Чужой чат и чат без членства — 404, не 403: аутентификация (живая сессия) и доступ к чату (строка в `chat_members`) — разные проверки.
Создание чата — одна транзакция: `INSERT` в `chats`, затем участники. Чужой `user_id` ломает внешний ключ, транзакция откатывается, счётчик чатов не растёт. Регистрация: `INSERT ... ON CONFLICT (username) DO NOTHING`, уникальный индекс на `username`.
Пул psycopg: максимум 8 соединений, ожидание 3 с, `statement_timeout` 5 с, `lock_timeout` 3 с. Redis: пул 16, таймаут сокета 2 с. Запросы с параметрами `%s`, не склейкой строк. История — два текста SQL (первая страница и страница после cursor), оба `ORDER BY created_at, id` и `LIMIT`, без OFFSET. Индекс `messages_history_idx (chat_id, created_at, id)` совпадает с этим предикатом. Миграция `migrations/001_init.sql`, учёт в `schema_migrations`. Повторный старт API пишет `already applied` и строки не копирует.
Если Redis или Postgres недоступны, `/health/live` остаётся 200, `/health/ready` — 503. Запрос с Bearer получает 503 и не превращается в пользователя. Запрос без токена или только с `X-User-Id` — 401. В тексте ошибки нет имён сервисов и SQL.
Соответствие `.env`: `APP_HOST` / `APP_PORT` — listen uvicorn; `APP_ENV` в код не входит, это метка стенда; `SESSION_TTL_SECONDS` — срок сессии (в smoke 3600, для проверки истечения пересоздавала API с 2); `SESSION_STORE=redis` обязателен, другое значение процесс не принимает; `DATABASE_URL_FILE` и `CACHE_URL_FILE` — пути к файлам в `/run/secrets`, не сами пароли.
Postgres в compose запущен с `fsync=on`, `synchronous_commit=on`, `full_page_writes=on`. `COMMIT`, который уже вернулся клиенту, означает сброс WAL на этот диск. Реплики нет: `wal_level=replica` само по себе никуда WAL не отправляет. Redis: `appendonly yes`, `appendfsync everysec`, каталог `/data` на named volume, плюс RDB `save 60 1`. Для сессий важен AOF. `protected-mode no`, пароля у Redis нет: порт на хост не опубликован, граница — сеть compose. Это учебное упрощение, не схема для чужой сети.
По вопросу про хеш и checksum: Argon2id специально медленный, чтобы по украденной базе паролей нельзя было быстро перебирать. Быстрый checksum (SHA-256 файла) нужен, чтобы заметить изменение байтов, и он как раз должен быть дешёвым. Подменять одно другим нельзя: checksum пароля перебирается, а KDF не проверяет целостность вложения.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `python tests/smoke.py --base-url http://127.0.0.1:8080` | `PASS: lab2 public API scenario` | evidence/smoke.txt |
| Offline check | `python scripts/check_contract.py` | `PASS: offline skeleton structure...` | вывод в терминале |
| Postgres: пользователи, чаты, участники, сообщения, PK/FK, уникальный username | миграция при первом старте, затем трек 2 | `migration 001_init applied`; в дампе users/chats/members/messages | лог API, evidence/track2_summary.json |
| Миграция повторно не дублирует данные | `python student-tests/run.py`, внутри restart API | users 6 -> 6, версия по-прежнему `001_init` | evidence/student_checks.txt |
| Создание чата атомарно | тот же `run.py`: чужой member_id и отдельный SQL с битым FK | счётчик чатов 1 -> 1; строка `rollback-probe` = 0 | evidence/student_checks.txt |
| Basic только на сессию, дальше Bearer, X-User-Id не пускает | smoke и `run.py` | неверный пароль 401, Basic на `/users/me` 401 с Bearer challenge, один X-User-Id 401, вместе с Bearer личность не меняется | evidence/smoke.txt, evidence/student_checks.txt |
| Пароль — Argon2id, в User его нет | `run.py`, в том числе пароль с `:` и кириллицей | 201 без полей password/password_hash | evidence/student_checks.txt, src/passwords.py |
| Сессии переживают рестарт API и хранилищ | persistence из WSL, hook `scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session`; StartedAt сменился у api, postgres и redis | evidence/persistence.txt |
| Logout | smoke и `run.py` | DELETE 204, тот же токен дальше 401 | evidence/smoke.txt |
| Гонка одинакового username | 12 параллельных POST | один 201, одиннадцать 409, в таблице одна строка | evidence/student_checks.txt |
| Пул, таймауты, параметры | код стенда | pool max 8, timeout 3 с, statement_timeout 5000, Redis socket 2 с, SQL только с `%s` | src/store.py, compose.yaml |
| Redis — хранилище сессий, AOF, не один TTL | `INFO persistence` и рестарт | `aof_enabled:1`, `aof_last_write_status:ok`; после рестарта старый токен жив | evidence/student_checks.txt, evidence/persistence.txt |
| Короткий TTL, logout, неверный пароль | `run_failures.py` и `run.py` | TTL около 1.96 с, потом 401; после возврата к 3600 срок снова ~3600 с; неверный пароль 401 | evidence/failures.txt, evidence/student_checks.txt |
| Нет Redis или Postgres | `run_failures.py`: `stop redis`, затем `stop postgres` | live 200, ready 503, без токена 401, с Bearer 503, X-User-Id 401 | evidence/failures.txt |
| Индекс истории, не полный проход | EXPLAIN на чате из 70 000, весь набор 101 000 | Index Scan `messages_history_idx`, 51 строка, shared hit=4, 0.095 мс | evidence/explain_history_index.txt |
| Трек 2: второй индекс/запрос и запись | тот же прогон | индекс только по `created_at`: hit=698, filter убрал 1173, 0.679 мс; OFFSET 5000 по хорошему индексу читает 5050 строк, 1.420 мс | evidence/explain_created_at_index.txt, evidence/explain_offset.txt, evidence/track2_summary.json |
| Трек 2: backup в новое хранилище | `pg_dump -Fc`, второй контейнер и новый volume, `pg_restore` | dump 2.40 с, restore 1.89 с; users/chats/members/messages и выбранные тексты совпали | evidence/track2_summary.json |
## Эксперименты и отказы
Гипотеза: страница истории по `(chat_id, created_at, id)` с LIMIT должна взять десятки записей индекса, а не чат целиком. Индекс только по `created_at` при перемешанных временах чатов будет выкидывать чужие строки. OFFSET N даже с хорошим индексом пройдёт около N записей. Отдельный btree на вставке 20 тысяч строк может замедлить запись, но на одном INSERT это может утонуть в шуме Docker.
Стенд: Docker Desktop, 8 CPU, 8246038528 байт RAM (~7.7 GiB). Лимиты `--cpus` / `--memory` не ставила. PostgreSQL 16.10, `fsync=on`, `synchronous_commit=on`, `full_page_writes=on`. Данные: 1 чат на 70 000, 1 на 20 000, 10 по 1 000 и 100 по 10, всего 101 000. Время сообщения — `n * 1000 + номер_чата` микросекунд от 2024-06-01, чтобы чаты шли вперемешку, а не каждый своим сплошным куском. Загрузка одним SQL, 4.4 с. Потом `ANALYZE`. Размер relation `messages` — 21 MB. Курсор для «глубокой» страницы — сообщение `t2-5` большого чата, там ещё живы и маленькие чаты. Запрос тот же, что в API: `WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT 51`. Первую страницу этого чата дополнительно сверила через HTTP: порядок текстов совпал с SQL.
Хороший индекс, вторая (уже тёплая) попытка: Index Scan по `messages_history_idx`, условие сразу и по чату, и по паре `(created_at, id)`, 51 строка, `shared hit=4`, execution 0.095 мс. Сортировки нет.
Тот же запрос, индекс снят и создан `(created_at)`, всё внутри транзакции и `ROLLBACK` (боевой индекс после этого на месте, проверяла `pg_indexes`): Index Scan по `messages_created_idx` плюс Incremental Sort, filter снял 1173 строки, `shared hit=698 read=4`, execution 0.679 мс. Четыре `read` — план был холоднее, но 698 попаданий против 4 это не объясняют.
OFFSET 5000 LIMIT 50 по хорошему индексу: тот же Index Scan, но `rows=5050`, `shared hit=98`, 1.420 мс. Индекс годный, форма запроса заставляет дойти до пятитысячной строки.
Запись, отдельная таблица без FK, INSERT…SELECT на 20 000 строк, один прогрев и три замера, медиана:
| Вариант | Повторы, мс | Медиана |
| --- | --- | --- |
| только PK | 467, 331, 194 | 331 |
| PK + `(chat_id, created_at, id)` | 596, 195, 648 | 596 |
| то же + индекс по `(chat_id, body)` | 368, 302, 385 | 368 |
Разброс внутри «только PK» (194–467) сопоставим с разницей медиан. Один прогон с индексом истории был 195 мс, быстрее двух прогонов без него. Устойчивого штрафа за запись я отсюда не беру. Для этой лабораторной узкое место страницы — не вставка, а способ читать: keyset против OFFSET и состав индекса.
Backup: `pg_dump -Fc` живой базы (2.40 с, 3 023 928 байт) и `pg_restore` в новый контейнер `mtusi-lab2-restore` с новым volume и тем же образом Postgres. Сверяла не выборку «на глаз», а числа и тексты: messages 101010, users 14, chats 116, members 120, большой чат 70 000, маленький 10, тела маленького чата `t2-1`…`t2-10`, у большого маркеры `t2-1`, `t2-500`, `t2-70000`. Совпало. Лишние 10 сообщений сверх 101 000 — это smoke и свои проверки, которые уже лежали в той же базе; дамп снимала целиком, не фильтром. Restore 1.89 с. Контейнер, volume и файл дампа после сверки удалила, скрипт умеет повторить.
Потеря данных. Пока база тихая, в дамп попало всё уже зафиксированное: сверка сошлась. Снимок `pg_dump` не включает транзакцию, которая закоммитится после начала снимка, и не включает незакоммиченное. Я этот зазор отдельным параллельным INSERT не мерила. Сессий в дампе нет: токен живёт в Redis. `synchronous_commit=on` относится к WAL Postgres, не к AOF. `appendfsync everysec` на штатном `docker restart` сессию сохранил (persistence PASS). Жёсткий kill Redis может отрезать около последней секунды новых логинов; сообщения при этом не в Redis, история от этого не пропадает.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `scripts/restart.sh` | старый токен и сообщение на месте, volume цел | persistence PASS; StartedAt обновился у всех трёх контейнеров | API поднялся в том же прогоне, данные целы |
| `stop redis` | live 200, ready 503, чужой заголовок не становится пользователем | так и есть: anon/X-User-Id 401, Bearer 503 | после `start` ready снова 200, сообщения не трогала |
| `stop postgres` | то же, сессия в Redis не заменяет базу | live 200, ready 503, Bearer 503, без токена 401 | после `start` ready 200 |
| `SESSION_TTL_SECONDS=2` | токен умирает примерно через 2 с, рестарт срок не раздувает | delta 1.96 с, затем 401; возврат настройки дал срок ~3600 с | сессия истекла, пользователь в Postgres остался |
| backup → новый volume | те же количества и выбранные тексты | совпали, restore 1.89 с | для тихого снимка потери зафиксированных строк не увидела; сессии в этот backup не входят |
## Ограничения и следующие шаги
Выдерживается: рестарт одного Docker-хоста с сохранёнными volume (сообщения и ещё живая сессия), отказ Redis или Postgres без подмены пользователя, гонка username, откат создания чата, keyset-страница без прохода по всему чату. Не выдерживается: смерть этого хоста, потеря Redis AOF (сессии), запрос, закоммиченный уже после старта `pg_dump`. Один API-процесс — не вторая реплика.
Не сделано: UI, TLS, скользящий TTL, пароль на Redis, архивация WAL и PITR. `protected-mode no` у Redis допустим только пока порт не смотрит в сеть.
Подтверждено планом: составной индекс и keyset читают страницу за 4 страницы буфера; индекс по одному `created_at` на том же запросе снял фильтром 1173 строки; OFFSET 5000 прошёл 5050 строк. Не подтверждено: что индекс истории заметно тормозит вставку. На 20 тысячах строк в одном INSERT шум больше эффекта. Пока гипотеза, что на потоке одиночных POST штраф будет виднее; этот режим я не мерила.