Files
mtusi2026lab2/REPORT.md
T

29 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Брезгунова Анжелика, БВТ2303.
  • Целевая оценка: 5. Трек 2 — план запроса и восстановление.
  • Рабочая ветка: solution/BVT2303-Брезгунова-на5. Commit/PR появятся при публикации работы.
  • Реализация: Go; PostgreSQL как источник истины; Redis как кэш неизменяемых профилей.
  • Использована помощь Codex для реализации, тестов и оформления. Основа HTTP API, модели и ограничения запросов перенесены из собственной первой лабы. Контракт, задание и публичные тесты второй лабы сохранены.

Запуск из чистого clone

Нужны Docker Engine с Compose v2+ и Python 3.9+. Локальный Go и make необязательны: Dockerfile выполняет go test ./..., go vet ./... и сборку. Образы закреплены: Go 1.24.7-alpine3.22, Alpine 3.22.1, PostgreSQL 17.6-alpine3.22, Redis 7.4.5-alpine3.21. Приложение имеет локальный тег mtusi-messenger:lab2.

Из каталога репозитория, в PowerShell или POSIX shell:

python scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
python scripts/wait_ready.py --base-url http://127.0.0.1:8080
python scripts/check_contract.py
python tests/smoke.py --base-url http://127.0.0.1:8080

Bootstrap генерирует случайный локальный пароль, .env и secrets/database_url, secrets/cache_url. При повторе пароль не меняется. Эти файлы игнорируются Git и исключены из build context. На Linux .env имеет права 0600, каталог secrets — 0700; отдельные URL-файлы имеют 0644 для чтения непривилегированным API после bind mount. Не копировать сюда secrets или volume первой лабы. Изменение пароля в .env не меняет пароль уже инициализированной БД.

API доступен на 127.0.0.1:8080; порт хоста меняется через HOST_PORT в .env. PostgreSQL и Redis не публикуют порты. В Windows выбран IPv4-адрес, чтобы исключить наблюдавшуюся задержку разрешения localhost. Если меняете порт, передайте соответствующий --base-url, а для собственного integration-теста задайте BASE_URL.

При наличии make те же проверки:

make up PYTHON=python
make check test PYTHON=python BASE_URL=http://127.0.0.1:8080
chmod +x scripts/restart.sh
make test-persistence PYTHON=python ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-extra research PYTHON=python

Для Windows hook запускается непосредственно публичным тестом:

python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080

Полный последовательный прогон с сохранением доказательств:

python student-tests/verify.py
python student-tests/profile_load.py

verify.py создаёт синтетические данные, перезапускает только сервисы этой лабы, временно останавливает Redis/PostgreSQL и восстанавливает их в finally. Для expiry временно пересоздаёт API с TTL=2, затем возвращает значение из .env. Исследование работает в собственных уникальных БД и удаляет только созданные этим запуском БД; учебные данные приложения не меняет. Backup остаётся в игнорируемом каталоге backups/. Исследовательский сервис restore после эксперимента остановлен; его отдельный volume сохранён.

Безопасная остановка с сохранением всех данных:

docker compose --env-file .env --profile research down

Намеренное удаление всех учебных данных этого Compose-проекта, только когда они больше не нужны:

docker compose --env-file .env --profile research down --volumes

Для полной проверки OpenAPI установите requirements-dev.txt в venv и выполните python scripts/validate_openapi.py. CI skeleton выполняет эту проверку отдельно. Собственный workflow application.yml собирает приложение и запускает smoke, persistence, дополнительные тесты и исследование; он не использует секреты аккаунта.

Архитектура и решения

Клиент -> API :8080 -> PostgreSQL :5432
                  \-> Redis :6379 (необязательный кэш профилей)
Исследование -> pg_dump -> отдельный PostgreSQL restore -> отдельный volume

Приложение работает от непривилегированного пользователя, с read-only файловой системой и без Linux capabilities. Состояние API не хранится локально. Основные volumes: postgres_data, redis_data; для эксперимента — restore_data. Redis не содержит обязательных данных и не требует persistence. Его volume не используется как доказательство сохранности сессий.

Схема, ограничения и транзакционные границы

Схема задаётся миграцией migrations/001_initial.sql:

Таблица Содержимое и ограничения Индексы
users UUID PK, уникальный username, display_name, password_hash, время БД; CHECK формата username и длины display_name PK, UNIQUE username
chats UUID PK, title с ограничением длины, время БД PK, (created_at,id)
chat_members FK на chat/user, PK (chat_id,user_id), уникальный порядок участника в чате PK, UNIQUE (chat_id,position), (user_id,chat_id)
messages UUID PK, FK на чат; составной FK (chat_id,sender_id) на членство; text 1–4000 code points, время БД PK, (chat_id,created_at,id)
sessions SHA-256 случайного токена как bytea PK длиной 32; FK user; абсолютный expires_at больше created_at PK, expires_at для очистки
schema_migrations Имя миграции, контрольная сумма SHA-256, время применения PK имени

Создание чата и всех его участников — одна SQL-транзакция. Неизвестный второй участник вызывает FK-ошибку уже после вставки чата и первого участника; rollback удаляет все изменения. Регистрация — один INSERT; UNIQUE в PostgreSQL разрешает гонку одинаковых username. Запись сообщения и создание/удаление сессии — отдельные атомарные SQL-операции. Ответ 201/204 отправляется после успешного выполнения/COMMIT. Используются штатные настройки PostgreSQL fsync, synchronous_commit, full_page_writes; рестарт контейнера проверен, отказ диска/хоста этим не моделируется.

Миграции встроены в бинарник. При старте advisory lock сериализует запуск, а миграции и запись их контрольных сумм коммитятся вместе. Повторный старт пропускает применённые миграции; изменение уже применённого файла приводит к ошибке старта. Новые изменения схемы нужно оформлять новым нумерованным файлом. Миграции не выполняют seed приложения.

Все пользовательские значения передаются параметрами $1…; SQL не собирается из полей HTTP. Пул ограничен 8 соединениями, контекст HTTP/БД — 2 секунды, подключение — 2 секунды, SQL statement timeout — 2 секунды, lock timeout — 1 секунда. HTTP имеет ограничения размера тела (1 MiB), заголовков и таймауты чтения/записи. Admission gate — 64 бизнес-запроса; одновременно работают максимум 4 password KDF. При заполнении gate возвращается 429 с Retry-After. Health остаётся доступен при заполнении gate.

Аутентификация и доступ

Регистрация принимает пароль из 12–128 Unicode code points. Argon2id v19: память 32 MiB, 3 итерации, 2 lanes, случайная соль 16 bytes, результат 32 bytes. Сравнение ключей выполняется в постоянное время. Пароли не усекутся на 72 bytes; проверен пароль длиной 128 Unicode-символов с двоеточием. Пустые и состоящие только из пробелов значения отклоняются.

POST /api/v1/auth/sessions принимает Basic без тела. Неверный пароль и неизвестный пользователь возвращают одинаковый 401 и Basic challenge; для неизвестного пользователя также выполняется dummy KDF. Сессия получает 32 случайных bytes (256 бит), закодированных base64url. Это opaque токен; в PostgreSQL сохраняется только его SHA-256. SHA-256 здесь служит индексом случайного высокоэнтропийного токена, а не password KDF.

Защищённые запросы принимают Bearer; X-User-Id игнорируется, Basic на бизнес-эндпоинтах не принимается. Авторизация всегда проверяет сессию в PostgreSQL с expires_at > clock_timestamp(). TTL задаёт SESSION_TTL_SECONDS, по умолчанию 3600; абсолютное время не изменяется из-за рестарта. Logout атомарно удаляет действительную сессию. Повторный logout и запрос после expiry — 401 с Bearer challenge. Фоновая очистка удаляет истёкшие сессии раз в минуту; действительность не зависит от запуска этой очистки.

Далее проверяется членство пользователя в чате: постороннему возвращается 404. Sender определяется по сессии, клиентское поле sender_id отклоняется. User никогда не содержит password/hash/token. Регистрация, вход и health публичны; /metrics — локальное диагностическое расширение.

Redis, expiry и инвалидация

Redis действительно кэширует ответы профиля GET /users/me по ключу profile:v1:<user_id>, TTL 300 секунд. Источник истины — users в PostgreSQL. API текущей лабы не меняет и не удаляет профиль, поэтому инвалидация при записи не нужна: кэш заполняется только из успешно сохранённого User. При добавлении редактирования понадобится явная инвалидация/версионирование. История чата не кэшируется: следующее чтение после подтверждённой записи сразу идёт в PostgreSQL.

Сессия проверяется в PostgreSQL до обращения к Redis; кэш не может обойти logout, expiry или отказ БД. При miss/ошибке/потере Redis профиль читается из PostgreSQL. GET/SET кэша ограничены 150 ms каждый, retry выключен; cache hit/miss/failure видны в /metrics. Redis ограничен 64 MiB, политика allkeys-lru. Недоступность Redis не блокирует readiness. Недоступность PostgreSQL приводит к 503 readiness и защищённых запросов; liveness остаётся 200. Приложение не принимает анонимного пользователя как доверенного.

Пагинация и порядок

История читает максимум limit+1 записей по предикату chat_id=$1 AND (created_at,id)>($2,$3), сортировке (created_at,id) и индексу (chat_id,created_at,id). OFFSET и чтение всей истории в память отсутствуют. Дополнительная запись определяет next_cursor; последний элемент страницы не повторяется. Cursor содержит ресурс, время и UUID; cursor чужого чата или списка другого пользователя отклоняется. Допускается смена limit, диапазон 1–100.

Время назначается PostgreSQL с точностью microseconds; UUID разрешает равенство времён. Между HTTP-страницами нет snapshot: конкурентная вставка с ключом раньше уже пройденного cursor может не попасть в этот обход. Обратный ход системных часов также может создать такую запись. Для неизменяемой истории обход полный и без повторов. Следующее чтение с начала видит все подтверждённые записи.

Конфигурация

APP_HOST, APP_PORT, SESSION_TTL_SECONDS, SESSION_STORE, DATABASE_URL_FILE, CACHE_URL_FILE, DB_MAX_CONNECTIONS, DB_TIMEOUT_MS, KDF_CONCURRENCY, MAX_IN_FLIGHT, MAX_BODY_BYTES читаются приложением. _FILE имеет приоритет над прямым URL; SESSION_STORE допускает только postgres. POSTGRES_PASSWORD и HOST_PORT используются Compose, APP_ENV=lab в примере — информационная метка. HTTP допустим здесь для локального стенда с синтетическими данными; Basic кодирует, но не шифрует пароль.

Доказательства критериев

Фактические результаты сохраняются в evidence/verification.json, integration.json, research.json, load.json, resources.json, build.txt. Команды внутри JSON позволяют повторить проверку. Публичные Python-команды — прямые эквиваленты соответствующих targets Makefile; локальный make на проверяемой Windows-машине отсутствует.

Критерий Команда/сценарий Доказательство
Контракт и сборка python scripts/check_contract.py; Docker build с go test и go vet verification.json; build.txt
Обязательный API, неверный пароль, Basic/Bearer, доступ, logout python tests/smoke.py --base-url http://127.0.0.1:8080 verification.json
Данные и действующие сессии после рестарта всех сервисов публичный resilience с restart.cmd/restart.sh verification.json: PASS, StartedAt всех трёх контейнеров до/после
Миграции с нуля и повторный запуск первая инициализация volume; restart API и сравнение migration/user/message counts build.txt; integration.json
Username race, атомарность чата, параметризованный SQL 4 конкурентные регистрации; чат с неизвестным вторым участником; чтение SQL-результатов integration.json; database.go
Password KDF, Unicode, безопасное хранение токена проверки префикса hash/digest в БД, Unicode login, Go-тест integration.json; build.txt
Реальная роль Redis рост cache_hits; stop Redis и FLUSHDB; тот же токен читает данные integration.json
Expiry, logout, отказ Redis/БД TTL=2; 401/503/200 по сценарию integration.json
Ограниченный пул/таймауты конфигурация приложения, bounded outage assertions main.go; compose.yaml; integration.json
Индекс на ≥10 000 сообщений EXPLAIN ANALYZE BUFFERS на 100 000 research.json
Трек 2 целиком два индекса, чтение/запись, dump/restore в другой контейнер/volume, сверка research.json

Эксперимент: план запроса и восстановление

Гипотеза: индекс (chat_id,created_at,id) ограничивает работу на keyset-страницу независимо от длины истории чата, но увеличивает объём индекса и стоимость вставки относительно (chat_id).

Стенд: Windows, Docker Desktop Linux/WSL2; Intel Core i7-12700H, 14 физических ядер / 20 логических процессоров, RAM около 16 GiB. Compose лимиты: API 1 CPU / 512 MiB, PostgreSQL 1 CPU / 512 MiB, Redis 0.5 CPU / 128 MiB. Restore PostgreSQL — отдельный контейнер 1 CPU / 512 MiB. Образы и зависимости закреплены в Dockerfile/compose/go.mod/go.sum.

Методика python student-tests/research.py: отдельная исследовательская БД, 100 000 сообщений в 10 чатах: 80 000, 15 000 и 8×625. В большом чате text имеет 200 символов, в остальных 40. Сравниваются (chat_id) и (chat_id,created_at,id). Три страницы большого чата: начало, после 40 000, после 79 000; LIMIT 51, два прогрева и пять измерений каждой страницы. В raw JSON сохранены execution times, actual rows и BUFFERS. Для каждого индекса — пять INSERT по 2000 строк под EXPLAIN ANALYZE, затем rollback. Это сравнение работы вставки с FK/triggers, без измерения COMMIT; rollback может оставить dead tuples, что явно ограничивает точность сравнения.

После измерений выбранный составной индекс сохраняется в схеме. pg_dump -Fc создаёт snapshot; pg_restore --exit-on-error восстанавливает его в пустую БД отдельного PostgreSQL-контейнера на отдельном named volume. Проверяются counts users/chats/members/messages, digest всех сообщений в устойчивом порядке и 10 полных сообщений. Исследовательские БД после успешной сверки удаляются, backup исключён из Git.

Результаты 10 октября 2026 года

Полный последовательный прогон прошёл. Smoke и persistence вернули PASS; verification.json дополнительно подтверждает изменение StartedAt API, PostgreSQL и Redis. Гонка регистрации дала ровно один 201 и три 409; составной чат после FK-ошибки отсутствовал. При отказе Redis сценарий fallback занял 0,375 с; последовательная проверка отказа PostgreSQL заняла 4,031 с (два запроса к БД с таймаутом 2 с, liveness и отказ анонимному пользователю). TTL=2 и logout дали ожидаемые 401.

Измерение, медиана пяти повторов (chat_id) (chat_id,created_at,id)
Страница в начале, ms 18,687 0,158
Страница после 40 000, ms 14,587 0,170
Страница после 79 000, ms 12,460 0,149
INSERT 2000 строк с последующим rollback, ms 125,699 116,631
Размер индекса, bytes 720 896 5 914 624
Shared hit blocks средней страницы, выбранный третий повтор 3224 7

План (chat_id) на большом чате выбрал parallel sequential scan и top-N sort. Составной индекс дал Index Scan с соответствующим Index Cond и 51 фактической строкой под Limit; полной сортировки/сканирования истории нет. Средняя страница ускорилась примерно в 85,8 раза на этом стенде. Цена по размеру индекса — около 8,2 раза. Предположение о замедлении INSERT в этом коротком опыте не подтвердилось: составной индекс оказался немного быстрее. Нельзя выдавать это за отсутствие стоимости индекса; ограничения порядка вариантов, прогрева, rollback и доминирующих FK/triggers не позволяют сделать такой вывод. Уверенно подтверждены выигрыш чтения и рост размера индекса.

Backup: 2 882 994 bytes, создание 1,500 с, восстановление 1,734 с. В исходной и восстановленной БД совпали 1 пользователь, 10 чатов, 10 membership и 100 000 сообщений; digest всех сообщений be1222f55df222fef96c1d71910ec87b, а также 10 полных выбранных сообщений совпали. Эти данные сохранены вместе с raw планами в evidence/research.json. Restore выполнен в отдельном контейнере и отдельном volume, без повторного seed.

Первый HTTP-прогон: 30,125 с, concurrency=4, 9873 успешных запроса, 0 ошибок, 327,734 successful RPS; p50=15, p95=31, p99=32 ms. Его вывод сохранён в verification.json.

Повтор на финальном образе с одновременными CPU/RAM-сэмплами: 30,093 с, 10 435 успешных запросов, 0 ошибок, 346,758 successful RPS; p50=15, p95=31, p99=32 ms. В resources.json сохранены шесть сэмплов Docker stats во время этого прогона; load.json содержит итог. HTTP-прогоны начинаются после readiness/bootstrap; отдельный временной прогрев HTTP-нагрузки не выделялся. Максимум среди этих сэмплов (это не непрерывный peak): API 72,90% CPU и 73,16 MiB RAM; PostgreSQL 74,11% и 84,70 MiB; Redis 6,00% и 6,496 MiB. CPU-процент Docker относится к одному логическому CPU. Изменение размера истории и фоновые операции/измерения входят в профиль; разница RPS между повторами не интерпретируется как отдельное доказательство оптимизации.

Ограничения

Одна API-реплика и одна основная БД: отказ PostgreSQL не скрывается, HA не заявляется. Redis — доверенный внутренний сервис локальной Compose-сети, без TLS/ACL; он не опубликован наружу. Пользователь БД в учебном стенде управляет миграциями; разделение migration/runtime ролей оставлено для последующих лабораторных. Secrets Compose — файлы локального оператора, внешний secret manager не используется.

Перезапуск с volumes проверяет сохранность контейнерного стенда, а не внезапное отключение питания или повреждение диска. Отдельные request contexts ограничивают время ожидания; 201 может быть потерян на сети после COMMIT, поэтому прозрачный retry POST в lab2 не добавлен. Идемпотентность появляется по контракту lab3.

Backup включает данные на snapshot начала dump. Сообщения, подтверждённые позже этого snapshot, в backup не входят: без WAL archiving/PITR предел потери данных равен времени с последнего backup. Измеренное время восстановления относится к restore уже подготовленного локального контейнера и не включает обнаружение аварии и provisioning.

Нагрузочный генератор closed-loop, concurrency=4, 30 секунд; latency — только успешных запросов, есть coordinated omission. Это успешные HTTP-подтверждения, а не универсальная максимальная пропускная способность или точный счётчик COMMIT. Индексный эксперимент — пять последовательных повторов на прогретом локальном buffer cache; порядок вариантов фиксирован, статистическая универсальность не заявляется.

Из факультативной первой лабы сохранены лимит тела, admission gate и метрики; in-memory лимит числа сообщений заменён устойчивым хранением без искусственного ограничения истории. Grafana/Prometheus не входят в обязательный минимум второй лабы, /metrics позволяет подключить их отдельно. Следующие шаги: несколько API-реплик и идемпотентность по lab3, разделение DB-ролей, TLS и управление secrets в соответствующих лабораторных.

Источники

  • Задание этой лабораторной, COURSE.md, contracts/README.md, contracts/openapi.json, публичные тесты.
  • Собственная реализация первой лабораторной: HTTP API, модели, метрики и admission gate.
  • Библиотеки github.com/lib/pq, github.com/redis/go-redis/v9, golang.org/x/crypto/argon2; точные версии в go.mod/go.sum. Код SQL, KDF и cache integration написан под контракт этой лабы.