Skeleton contracts / contracts (pull_request) Canceled after 0s
Co-authored-by: Cursor <cursoragent@cursor.com>
129 lines
21 KiB
Markdown
129 lines
21 KiB
Markdown
# Отчёт — лабораторная 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 штраф будет виднее; этот режим я не мерила.
|