Co-authored-by: Cursor <cursoragent@cursor.com>
21 KiB
Отчёт — лабораторная 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 только чтобы гонять тесты с хоста). Секреты в репозитории нет.
python scripts/bootstrap.py
docker compose --env-file .env up -d --build
bootstrap.py один раз пишет .env и secrets/ (пароль Postgres и URL). В консоль пароль не печатает. Повторный запуск файлы не перезаписывает: volume уже инициализирован этим паролем.
Дальше дождаться GET /health/ready = 200 и:
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-скрипт):
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 штраф будет виднее; этот режим я не мерила.