Files
mtusi2026lab2/REPORT.md
T

127 lines
20 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
- Автор: Саламатин, БПИ-2304.
- Целевая оценка: **4**, включая все требования уровня 3. Исследовательские треки на 5 не заявляются.
- Проверено 31 октября 2026 года, Europe/Moscow. В JSON и времени контейнеров используется UTC.
- Задание: [mtusi2026/mtusi2026lab2](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2), предоставленный архив, контракт 1.2.0. README задания, содержимое `contracts/` и публичные `tests/` сохранены.
- Основа: собственная lab1 из `Lab1_Highload`, commit `0a931edce3bcd3c1130093b3dd5259f7b208cf2e`. Перенесены HTTP-маршруты, строгие модели, формат ошибок, request ID, проверка доступа и идея подписанного cursor. In-memory Store полностью заменён PostgreSQL/Redis; регистрация и идентификация изменены по контракту lab2.
- Локальный commit сборки из чистого clone зафиксирован в `evidence/clean-source.json`. Публикация fork/ветки и оформление PR выполняются отдельно.
## Запуск из чистого clone
Нужны Docker Desktop с Linux containers, Docker Compose и Python 3.13 для локальных вспомогательных скриптов. API и все его Python-зависимости собираются в контейнере; локальная установка PostgreSQL/Redis не требуется. На Linux подходит Docker Engine с Compose.
Версии: Python `3.13.15-slim-bookworm`, PostgreSQL `17.6-bookworm`, Redis `7.4.5-bookworm`; тестовый Docker CLI `28.5.1-cli`. FastAPI 0.141.1, Pydantic 2.13.5, Uvicorn 0.53.0, Psycopg 3.2.10, pool 3.2.6, redis-py 6.4.0. Прямые и транзитивные Python-зависимости закреплены в `requirements.txt`. Образы закреплены тегами версий; фактические image ID записаны в доказательствах.
Из корня полученного clone, PowerShell:
```powershell
python scripts/init_local.py
python scripts/verify.py
```
На этой машине вместо `python` доступен `D:\Labs_Highload\.tools\bin\python3.13.exe`:
```powershell
& 'D:\Labs_Highload\.tools\bin\python3.13.exe' scripts/init_local.py
& 'D:\Labs_Highload\.tools\bin\python3.13.exe' scripts/verify.py
```
`init_local.py` создаёт `.env`, случайные пароли PostgreSQL/Redis, DSN и ключ подписи cursor в `secrets/`. Значения не печатаются. Повторный запуск сохраняет секреты и нормализует окончания строк для Linux. В `.env` только имя Compose-проекта, опубликованный порт, окружение и TTL. Пароли/DSN передаются как Compose secrets, а не в образе. Не удалять секреты существующего стенда при сохранённых volumes.
`verify.py` собирает API и тестовый образ, поднимает зависимости, ждёт readiness, запускает публичные и собственные тесты, полный restart, отдельную проверку TTL=2, EXPLAIN и повтор миграций. Результаты сохраняются в `evidence/`; основной стенд остаётся запущенным. Проверка управляет только сервисами данного Compose-проекта. Существующий контейнер с именем временного TTL-теста не удаляется автоматически.
Отдельные команды:
```powershell
docker compose --env-file .env config --quiet
docker compose --env-file .env build api checks
docker compose --env-file .env up -d --wait
docker compose --env-file .env run --rm --no-deps checks make check
docker compose --env-file .env run --rm --no-deps checks make test
docker compose --env-file .env run --rm --no-deps checks make test-student
docker compose --env-file .env run --rm --no-deps checks make test-persistence ACTION_SCRIPT=scripts/restart.sh
docker compose --env-file .env run --rm --no-deps checks make explain
```
На Linux после clone: `chmod +x scripts/restart.sh`. `verify.py` также выполняет chmod перед публичным persistence-тестом. Контейнер `checks` содержит GNU Make и Docker CLI: это позволяет выполнять неизменённый Linux hook и тесты на Windows. Для управления рестартом ему подключён локальный Docker socket; сервис относится к профилю `tools`, не запускается с обычным `up` и завершается после проверки. Runtime API работает от пользователя `messenger`, без Docker CLI/socket.
API публикуется только на loopback, по умолчанию `127.0.0.1:8080`; PostgreSQL и Redis не имеют опубликованных портов. На проверявшейся Windows-машине порт 8080 сбрасывал соединения, поэтому в локальном `.env` выбран `API_PORT=18080`: `http://127.0.0.1:18080`. На этом порту curl и публичный HTTP-клиент проверяют опубликованный API. Основные проверки также идут из отдельного клиента к API по Docker-сети. Для дополнительного smoke с хоста: `python scripts/verify.py --published-base-url http://127.0.0.1:18080`. `APP_HOST=0.0.0.0` и `APP_PORT=8080` заданы внутри контейнера; `API_PORT` меняет только внешний порт. `APP_ENV` влияет на стартовый лог, `SESSION_TTL_SECONDS` — на новые сессии. Внутри контейнеров `SESSION_STORE=redis`, DSN и ключ читаются через `DATABASE_URL_FILE`, `CACHE_URL_FILE`, `CURSOR_KEY_FILE`.
Остановка с сохранением данных:
```powershell
docker compose --env-file .env stop
# Либо удалить контейнеры и сеть, сохранив volumes:
docker compose --env-file .env down
```
Только для намеренного уничтожения всех данных этого учебного стенда: `docker compose --env-file .env down --volumes`. Эта команда не используется ни в одном restart-тесте.
Отдельный job сборки и acceptance-проверок подготовлен в `.github/workflows/application.yml`. Он использует изолированный runner, создаёт локальные секреты и сохраняет только `evidence/`. На площадке workflow не запускался; локальный эквивалент выполнен из чистого clone. GitHub workflow — дополнительная возможность, локальные проверки от площадки не зависят.
## Архитектура и решения
Клиент → Uvicorn/FastAPI → PostgreSQL для пользователей, чатов, членства и сообщений; Redis для серверных сессий. Схема и транзакционные границы описаны в [docs/DATABASE.md](docs/DATABASE.md).
Миграция `001_initial.sql` создаёт PK/FK, UNIQUE username, ограничения длины и индексы. Сервис `migrate` применяет её до API. Версии и SHA-256 находятся в `schema_migrations`; advisory lock сериализует запуск. Перед checksum окончания строк нормализуются к LF, чтобы Windows checkout не менял версию SQL. Повтор миграции не меняет данные, изменённый ранее применённый SQL отклоняется.
Отдельно на существующей БД повторно применены временные LF- и CRLF-копии одного SQL: обе распознаны как Unchanged, версия, checksum и applied_at не изменились. Результат — `evidence/migration-newlines.txt`.
Все значения SQL передаются параметрами. Пул PostgreSQL ограничен 10 соединениями и очередью 20 запросов. Ожидание пула 1 s, соединения 2 s, SQL 2 s, блокировки 1 s; keepalive и TCP_USER_TIMEOUT ограничивают сетевые зависания. У Redis максимум 10 соединений, connect/read timeout 1 s, повторов команд нет. Общий бюджет обработки HTTP — 5 s. Занятый/недоступный сервис даёт 503 без SQL, DSN и stack trace в ответе.
Регистрация сохраняет scrypt-хеш с независимой 128-битной солью: N=16384, r=8, p=1, выход 32 байта. Вычисление вынесено из event loop, одновременно выполняются максимум четыре KDF. UTF-8 пароль длиной 128 code points, включая двоеточие и многобайтовые символы, проверен без усечения. Basic используется только при входе. Отсутствующий пользователь и неверный пароль возвращают одинаковый 401 и Basic challenge.
Bearer содержит 256 случайных бит. В Redis хранится SHA-256 токена как ключ и UUID/абсолютное время окончания как значение. `PXAT` и дополнительная проверка срока в API не позволяют продлевать сессию чтением/рестартом. Logout удаляет ключ до 204. Неизвестный, истёкший и отозванный токены дают 401 с Bearer challenge; X-User-Id не влияет на личность.
Redis — единственное хранилище сессий, поэтому настроены volume, AOF и `appendfsync always`. TTL управляет сроком жизни, AOF — сохранностью. Кэширования истории нет: следующее чтение идёт в PostgreSQL и видит подтверждённую запись. При отказе Redis API не подменяет сессии локальной памятью. Для readiness критичны оба хранилища; liveness проверяет только процесс.
Запись сообщения блокирует строку своего чата до COMMIT. Новая метка не меньше текущего времени и предыдущей метки + 1 microsecond. Это сохраняет порядок commit в одном чате при совпадении/откате часов. История использует подписанный cursor, привязанный к чату, и keyset-условие `(created_at, id) > (...)`. Общего snapshot между страницами нет; поздние записи могут появиться на следующих страницах. После рестарта cursor остаётся действителен благодаря сохранённому ключу подписи.
## Доказательства критериев
| Критерий | Команда / сценарий | Наблюдение | Доказательство |
| --- | --- | --- | --- |
| Структура и публичный API | `make check`, `make test` в checks | PASS, Unicode, членство, пагинация, Basic/Bearer, logout | `contract-check.txt`, `smoke.txt`, `smoke-final.txt` |
| Реальные PostgreSQL/Redis, volume и полный restart | Неизменённый `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Подтверждённое сообщение и прежняя сессия сохранились; перезапущены все 3 сервиса | `persistence.txt`, `restart.json` |
| Миграция с нуля и повторяемость | Старт migrate, затем повтор `compose run --rm --no-deps migrate` | 001 применена; повтор — Unchanged; количества строк совпали | `migrations-repeat.txt`, `verification.json`, `clean-source.json` |
| Password KDF, UTF-8, неверные credentials, logout | `make test-student` | Хеш проверен scrypt; пароль 128 code points без усечения; неверный пароль/Basic на бизнес-endpoint/отозванный токен — 401 | `student-tests.txt` |
| Redis реально хранит сессии с TTL/persistence | Интеграционный SIGKILL Redis и возврат со старым токеном | Сессия восстановилась из AOF, абсолютный expiry не изменился | `student-tests.txt`, `infra/redis.conf` |
| Гонка регистрации | 10 параллельных запросов одного username | 1 ответ 201, 9 ответов 409, 1 строка users | `student-tests.txt` |
| Rollback составной операции | Второй участник чата неизвестен; сравнение БД до/после | 400, число чатов/членств не изменилось, частичного чата нет | `student-tests.txt` |
| Сохранность конкурентных сообщений | 100 сообщений, 10 HTTP-клиентов, чтение всех страниц | 100 подтверждений, 100 уникальных UUID, все тексты на месте | `student-tests.txt` |
| Индекс истории ≥10 000 сообщений | `make explain` | Начало/середина/поздняя страница: Index Scan, LIMIT 51, без Seq Scan/OFFSET | `explain.json`, `explain.txt`, `explain-run.txt` |
| Expiry при коротком TTL | Отдельный API с TTL=2 | 200 сразу, 401 через 2.3 s; основной TTL не меняется | `expiry.json`, `expiry.txt` |
| Недоступность Redis/БД | Поочерёдный stop/start каждого хранилища | Live 200, ready и защищённый запрос 503 примерно за 1 s, анонимный X-User-Id 401; прежняя сессия работает после восстановления | `failures.json`, `student-tests.txt` |
| Сборка и повтор проверок из чистого clone | Отдельный Compose-проект и пустые volumes | Чистый commit, независимые secrets/volumes, повтор проверок | `clean-source.json`, `clean-verification.json`, `clean-build.txt` |
Имена файлов в таблице относятся к `evidence/`, если не указан иной каталог.
## Измерения и отказы
Стенд: Windows, Docker Desktop/WSL2 Linux containers, Intel Core i5-9600K, 6 физических/логических ядер, RAM 31.9 GiB. Лимиты: API 1 CPU/256 MiB, PostgreSQL 1 CPU/512 MiB, Redis 0.5 CPU/192 MiB; клиент проверок 1 CPU/256 MiB. Версии и фактические ограничения сохранены в JSON. Это функциональные проверки и локальный план SQL; максимальная пропускная способность/RPS/p95/p99 не измерялись и не заявляются.
Для плана создан отдельный чат с 10 000 синтетическими сообщениями, выполнен ANALYZE. Измерены первая страница и страницы после 5000-го/9900-го сообщения, по 50 элементов. Каждому HTTP-запросу соответствует `LIMIT 51`: лишняя строка нужна только для признака следующей страницы. Сохранены машинный JSON и текстовый EXPLAIN (ANALYZE, BUFFERS). Во всех трёх случаях используется `messages_chat_created_id_idx`, обрабатывается 51 строка. Во втором прогретом чтении время выполнения составляло около 0.03 ms и 3–4 shared buffer hits. Эти цифры относятся к SQL на прогретом локальном наборе, а не ко времени HTTP или дисковому чтению холодного стенда.
| Воздействие | Результат |
| --- | --- |
| Рестарт API + PostgreSQL + Redis | Те же данные и старый токен доступны после readiness; имена volumes сохранены |
| SIGKILL Redis | Сессия восстанавливается из AOF; абсолютный expiry не продлён |
| Stop Redis | Защищённый запрос 503 примерно за 1 s, live 200; после start работает старый токен |
| Stop PostgreSQL | Защищённый запрос 503 примерно за 1 s, live 200; пул восстанавливает соединения |
| Истечение TTL | Через 2.3 s сессия с TTL=2 отклонена с 401 |
| Неизвестный участник при создании чата | Вся SQL-транзакция откатилась |
## Ограничения
Один Docker-host, одна PostgreSQL и один Redis: рестарт выдерживается, потеря host/диска/volume — нет. Backup/restore, репликация и HA не реализованы. Redis flush уничтожает сессии. При потере SQL-соединения после отправки COMMIT клиент может получить неопределённый результат; идемпотентность сообщений относится к lab3. Общего snapshot между страницами нет. Записи одного очень активного чата сериализуются его row lock. Нет UI, TLS, лимита хранения истории и исследования уровня 5. HTTP разрешён только в локальном изолированном стенде с синтетическими паролями.
## Источники и разбор
- [Задание и контракт lab2](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2); локальные `README.md`, `contracts/README.md`, OpenAPI и публичные тесты.
- Собственная реализация lab1, указанный выше commit.
- [Psycopg connection pools](https://www.psycopg.org/psycopg3/docs/advanced/pool.html).
- [PostgreSQL EXPLAIN](https://www.postgresql.org/docs/17/using-explain.html), [транзакции](https://www.postgresql.org/docs/17/tutorial-transactions.html).
- [redis-py asyncio](https://redis.readthedocs.io/en/stable/examples/asyncio_examples.html), [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/).
- Объяснение схемы — [docs/DATABASE.md](docs/DATABASE.md); сценарий защиты и разбор решений — [docs/DEFENSE.md](docs/DEFENSE.md); порядок передачи файлов — [docs/SUBMISSION.md](docs/SUBMISSION.md).