# Отчёт — лабораторная 2 - Автор, группа: Самсонов Александр, БВТ2303 - Целевая оценка: 4 - Commit/PR: TODO после публикации - Использованные источники, библиотеки и помощь ИИ: PostgreSQL transactions, PostgreSQL EXPLAIN, Valkey persistence, RFC 7617, hashlib.scrypt, psycopg 3, redis-py. Помощь ИИ в реализации сервера, миграции, Compose и тестов. ## Запуск из чистого clone Нужны Docker Desktop и Python 3.9+ (для публичных тестов; приложение в контейнере — Python 3.12.6). ```powershell git clone cd lb2 Copy-Item .env.example .env docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build docker compose --env-file .env ps ``` Готовность: `GET http://localhost:8080/health/ready` возвращает `{"status":"ok"}`. Миграции применяет сам API при старте, повторный запуск не вставляет данные второй раз: версия записана в `schema_migrations`. Проверки: ```powershell python tests/smoke.py --base-url http://localhost:8080 python tests/student_level4.py --base-url http://localhost:8080 --deps docker compose --env-file .env exec -T api python3 /app/explain_history.py ``` Сохранность после рестарта API, PostgreSQL и Valkey (volumes не удаляются): ```powershell # Git Bash или WSL, у scripts/restart.sh должен быть executable bit chmod +x scripts/restart.sh python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080 ``` Короткий TTL сессии: ```powershell # в .env: SESSION_TTL_SECONDS=2 docker compose --env-file .env up -d --force-recreate api python tests/student_level4.py --base-url http://localhost:8080 --expiry # вернуть SESSION_TTL_SECONDS=3600 и снова up -d --force-recreate api ``` Остановка без удаления данных: ```powershell docker compose --env-file .env stop ``` Удаление учебных данных вместе с volumes: ```powershell docker compose --env-file .env down -v ``` Образы закреплены тегами: `python:3.12.6-slim-bookworm`, `postgres:16.6-bookworm`, `valkey/valkey:8.0.2`. Зависимости Python закреплены в `requirements.txt`. ## Архитектура и решения ``` Клиент --HTTP--> API (src/server.py) --SQL--> PostgreSQL | +--сессия--> Valkey (AOF + volume) ``` Из lab1 перенесены пользователи, чаты, членство, сообщения, keyset-пагинация, формат ошибок и `X-Request-Id`. `X-User-Id` больше не выбирает пользователя. Регистрация требует `password`. Вход — только `POST /api/v1/auth/sessions` с `Authorization: Basic`. Остальные защищённые запросы требуют `Authorization: Bearer`. Basic на бизнес-запросе даёт 401. ### Источник истины PostgreSQL хранит пользователей, чаты, участников и сообщения. Пароль хранится как scrypt (`hashlib.scrypt`, параметры `N=16384,r=8,p=1`), не как SHA-256 и не как plaintext. bcrypt не используется: он обрезает пароль на 72 байтах и не покрывает весь диапазон UTF-8 до 128 code points. Сессии хранит только Valkey. Ключ — `session:` + SHA-256 токена, значение — id пользователя, TTL равен `SESSION_TTL_SECONDS` (по умолчанию 3600). Токен — `secrets.token_urlsafe(32)`, 256 бит, клиенту отдаётся один раз. Сам токен в Redis и в логи не пишется. TTL не продлевается при рестарте: Redis восстанавливает ключ вместе с оставшимся сроком из AOF. Один TTL без диска сессию после рестарта не сохранил бы, поэтому у Valkey включены `--appendonly yes --appendfsync everysec` и volume `valkeydata`. Инвалидация: logout удаляет ключ. Истёкший TTL удаляет ключ сам. Повтор с отозванным токеном — 401. ### Транзакционные границы - Регистрация: один `INSERT`. Два параллельных запроса с одним username упираются в `UNIQUE`; второй получает 409, а не 500. - Создание чата: одна транзакция. Сначала вставляется чат, затем проверяются участники и вставляются `chat_members`. Неизвестный участник поднимает ошибку, транзакция откатывается, чат в списке не появляется. - Сообщение: один `INSERT ... WHERE EXISTS` участника. Чужой чат не создаёт строку и отвечает 404. - Сессия не входит в транзакцию PostgreSQL. Пул: `psycopg_pool`, максимум 10 соединений, таймаут выдачи 5 с, `connect_timeout` 3 с, `statement_timeout` 5 с. Все запросы параметризованы (`%s`), значения в SQL не подставляются. История читается так: ```sql SELECT ... FROM messages WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4 ``` Индекс `messages_history_idx (chat_id, created_at, id)` позволяет открыть страницу диапазоном, а не сканом всей таблицы. Это проверяет `src/explain_history.py` на 10000 сообщениях командой `EXPLAIN (ANALYZE, BUFFERS)`. ### Готовность и отказ `/health/live` проверяет только процесс. `/health/ready` проверяет PostgreSQL и Valkey: без любого из них ответ 503 `unavailable`. Запрос без токена при недоступном Valkey остаётся 401, а не успешным анонимным доступом. Запрос с токеном при недоступном Valkey или PostgreSQL — 503, без текста SQL и без токена в ответе. ### Соответствие `.env.example` | Переменная | Где используется | |---|---| | `APP_HOST`, `APP_PORT`, `APP_ENV` | bind и строка старта API | | `SESSION_TTL_SECONDS` | TTL новой сессии в Valkey и `expires_at` | | `SESSION_STORE=valkey` | сессии не пишутся в PostgreSQL | | `POSTGRES_*` | контейнер PostgreSQL и сборка `DATABASE_URL` в Compose | | `DATABASE_URL` | API, если нет файла `DATABASE_URL_FILE` | | `REDIS_URL` | API, если нет файла `CACHE_URL_FILE` | `.env` в Git не входит. Volumes `pgdata` и `valkeydata` тоже. ## Доказательства критериев | Критерий | Команда | Что смотреть | |---|---|---| | Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | строка `PASS: lab2 public API scenario` | | Рестарт с тем же токеном | `python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080` | `PASS: persistence preserved confirmed data and existing session` | | Гонка username, rollback чата, logout, неверный пароль, битый cursor | `python tests/student_level4.py --base-url http://localhost:8080` | `ALL STUDENT TESTS PASSED` | | Недоступность Valkey и PostgreSQL | `python tests/student_level4.py --base-url http://localhost:8080 --deps` | `PASS dependencies`: ready/me дают 503, запрос без токена даёт 401, после старта прежний токен снова 200 | | Expiry при коротком TTL | `SESSION_TTL_SECONDS=2`, recreate api, `python tests/student_level4.py --expiry` | `PASS expiry` | | План истории | `docker compose --env-file .env exec -T api python3 /app/explain_history.py` | в плане Index Scan по `messages_history_idx`, без Seq Scan | | Повтор миграций | второй `docker compose up` | в `schema_migrations` одна строка `001_init.sql`, пользователи не задвоены | На этой машине Docker в PATH не найден, поэтому smoke, persistence и EXPLAIN здесь не запускались. Команды выше — то, чем закрываются критерии на стенде. ## Ограничения - Рестарт выдерживают данные PostgreSQL и ещё не истёкшие сессии Valkey, пока volumes не удалены. `down -v` стирает и сообщения, и сессии. - Потеря Valkey не пускает анонима в API, но и не даёт войти, пока сессии некому хранить: это 503, не обход в PostgreSQL. Отдельной копии сессий в PostgreSQL нет. - `appendfsync everysec` может потерять последнюю секунду записи при жёстком падении процесса Valkey. Обычный `docker compose restart` делает штатный shutdown, и AOF сбрасывается. - Нагрузка больше лабораторного smoke не измерялась.